infra/paperspec
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8c8b51cc3f8fc39a0870d02fa7913e22710b324a
paperspec/docs/glossary.md
T
alexmandClaude 8c8b51cc3f feat: validator, bundle builder and release checks for 0.1.0 
- Add tools/validate.py: validates packages, and with --correction runs
  proposed corrections through the gate against a package without
  writing anything (spec/11 §11.4). The gate now refuses a proposal that
  fails the correction schema, rule correction.schema.
- tools/load.py validates every package before loading, and with
  --bundle --built-from builds a scienting-bundle/1 with the FTS5 search
  index and bundle_meta (spec/13 §13.5). Search rows are defined per
  unit (sentence, cell, equation outside a sentence, figure-text) with
  the parent kind as context.
- Roster keys carry a role, and a key with the role owner may revoke any
  receipt (spec/08 §8.7, spec/20); roster schema, store table and the
  fixture roster updated. The checker signs a trial revocation to prove
  the rule both ways.
- A qa: receipt raises the nodes it sampled except those in its errors
  (spec/08 §8.2); the example paper's fidelity counts become 27 F3,
  13 F2, 4 F1 and 1 F0.
- The destination chooses the keyed scheme, not the text policy:
  hmac-team between the team's machines, hkdf-pages outside the team
  (spec/05 §5.8, spec/12 §12.5).
- A TextQuoteSelector must repeat the anchor's plain quote and is absent
  for hashed or keyed anchors (spec/18 §18.3).
- Add fixtures/records/suspect.json, a scienting-suspect/1 record.
- Oracle: hashes are kept incrementally and checked after every
  correction against a full recomputation; load and write refuse unsafe
  manifest paths; Ed25519, HKDF and schema validation come from the
  cryptography and jsonschema packages; canonical JSON uses the built-in
  encoder with an exact RFC 8785 fallback.
- The tools need Python 3.14 with cryptography and jsonschema; the py310
  CI environment is dropped and the workflow runs the default only.
- Resolve every [CHECK] note in the docs, READMEs and context; add
  CONTRIBUTING.md; every tool answers --help and refuses unknown options.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-14 18:58:00 -04:00

163 lines
11 KiB
Markdown
Raw Blame History

# Glossary
A scientific paper changes after it is published: errata appear, readings get corrected, annotations pile up. manuspec is a set of file formats for scientific papers that keeps each sentence findable through those changes (repository: <https://git.scient.ing/infra/manuspec>).
This glossary defines its terms for readers from newcomer to expert, implementers included.
Each entry gives the plain meaning, then the precise one, then the chapter that defines it.
A hash is a fixed-length fingerprint of data; changing one character changes it.
SHA-256 is the hash function the formats use.
The specification is at version 0.1.0, and each format is `candidate` or `provisional` in `registry/formats.json`.
Format names begin with `scienting-`, as in `scienting-doc/1`; that prefix is the formats' namespace, a separate matter from the repository's name. "Outside term" marks a standard from another project.
Address
: A string that names one node, optionally pinned to its state by the first six digits of its `node_hash` and narrowed to a span of code points (numbered characters of text): `key#id@hash6[start:end]`. ([6.1](../spec/06-anchors.md#61-addresses))
Alias
: A legacy ID kept so that old references still lead to the node that now holds their text. ([4.3](../spec/04-identity.md#43-permanence-retirement-and-aliases))
Align key
: A hash of a node's lossy projection, used only to propose that two readings hold the same sentence; it never certifies anything. ([5.1](../spec/05-hashes.md#51-the-five-values))
Anchor
: The stored form of a pinned address, with its quotation and context, so that a reference can be found again after the text changes.
It resolves as current, changed below, moved, reattached or stale. ([6.2](../spec/06-anchors.md#62-the-anchor), [6.5](../spec/06-anchors.md#65-resolution))
Asset store
: Where a team keeps files by SHA-256: witnesses, images, crops and withheld text. ([12.6](../spec/12-package.md#126-assets))
Bundle
: One SQLite file with every table and a full-text index, which a reader or a store queries.
Format `scienting-bundle/1`, `provisional`. ([13.5](../spec/13-database.md#135-the-bundle))
Changed below
: The resolution of an anchor on a container that is unchanged in itself while something inside it changed. ([6.5](../spec/06-anchors.md#65-resolution))
Correction
: An operation on an established document, with its evidence and author; never edited, only appended. ([11](../spec/11-corrections.md))
Document
: The text established for one version of one work, from one or more witnesses, as a tree of nodes. ([2.1](../spec/02-model.md#21-four-objects), [3](../spec/03-nodes.md))
Drift
: The amount that has changed below a container since an anchor on it was made, counted from the corrections: the share of the container's leaves touched by later corrections.
It is reported as `none`, `low` or `high`, with a default threshold of a quarter. ([6.6](../spec/06-anchors.md#66-drift))
Exercise
: An annotation whose body holds a prompt, an answer key and a grading rule.
The key is anchors, a verdict, a chain, a value or planted errors, by exercise kind. ([19.1](../spec/19-exercises.md#191-exercises))
Fidelity level
: How far a leaf's text was checked against its source, from F0 converted to F3 proofread. ([8.1](../spec/08-fidelity.md#81-levels-of-fidelity))
JATS
: Outside term.
Journal Article Tag Suite, ANSI/NISO Z39.96-2024, an XML format in which publishers and archives exchange journal content ([the NISO page](https://www.niso.org/publications/z3996-2024-jats)).
In manuspec, `jats` is a witness kind: the fixture `okafor2025open` was established from a JATS file and a PDF that agree.
The formats ingest JATS and do not replace it. ([2.3](../spec/02-model.md#23-witnessesjson))
Keyed hash
: A content value computed as an HMAC (a hash mixed with a secret key) under a team key or a key derived from page fingerprints, so a short text cannot be recovered by hashing guesses. ([5.8](../spec/05-hashes.md#58-keyed-hashes))
Layer
: A named set of annotations with one purpose, audience, visibility and license. ([18.2](../spec/18-layers.md#182-the-layer))
Leaf
: A node that holds text itself: a sentence, cell, reference, author line, keyword line, equation, equation line, code or algorithm.
A leaf anchor points at one whole. ([6.4](../spec/06-anchors.md#64-four-kinds-of-anchor))
Lossy projection
: A node's text with scripts flattened, citation marks, whitespace and dashes removed, and case folded; used for proposing alignments. ([5.5](../spec/05-hashes.md#55-the-lossy-projection))
Match hash
: A hash of a node's strict projection.
Two readings agree only when their match hashes are equal and their complex-notation keys are equal.
A complex-notation key is `notation:source` for a piece of math too complex for the formats to normalize, with the source's whitespace removed ([5.3](../spec/05-hashes.md#53-the-strict-projection)). ([5.1](../spec/05-hashes.md#51-the-five-values), [5.3](../spec/05-hashes.md#53-the-strict-projection))
Node
: An addressable part of a document: a section, paragraph, sentence, figure, panel, caption, table, row, cell, equation, footnote, reference and the rest.
Each node has a permanent ID and five content values; table columns and figure-text items have IDs and are not nodes. ([3](../spec/03-nodes.md), [4.2](../spec/04-identity.md#42-minting-node-ids))
Own hash
: A hash of a node's own content without its children, used to judge anchors on containers that have content of their own.
The `node_hash` is a hash of the own hash and the children's node hashes. ([5.1](../spec/05-hashes.md#51-the-five-values), [5.2](../spec/05-hashes.md#52-own-content))
Package
: A document as a folder, or a zip of one, of canonical JSON (a plain-text data format) and JSON Lines (one JSON value per line) files, with a manifest whose hash pins them all. ([12](../spec/12-package.md))
Page fingerprint
: A hash of a page's size, its text with download stamps removed, and its images, so that differently stamped downloads share their pages. ([7.1](../spec/07-geometry.md#71-page-fingerprints))
Plain projection
: A node's text as one string, on which offsets, quotations and text hashes are defined. ([3.6](../spec/03-nodes.md#36-the-plain-projection))
Policy
: A project owner's signed decision that settles rights a record leaves unknown.
It never overrides a use the record sets to true or false. ([14.2](../spec/14-rights.md#142-effective-uses))
Project
: A team's curated set of documents, with its members, layers, data, reading paths and drafts.
Format `scienting-project/1`, `provisional`. ([20](../spec/20-projects.md))
Receipt
: One signature over a Merkle root of what a person reviewed in a sitting.
The signature sets the fidelity level of what it lists.
A Merkle root is a single hash that commits to a list of items; receipts build it as RFC 6962 (an internet standards document) describes, a tree that [RFC 9162](https://www.rfc-editor.org/rfc/rfc9162) obsoletes and defines identically. ([8.3](../spec/08-fidelity.md#83-receipts), [8.5](../spec/08-fidelity.md#85-merkle-roots))
Revision
: The index of the last correction applied to a document, or 0 when there is none; anchors and receipts record it. ([11](../spec/11-corrections.md))
Revocation
: A signed record that withdraws a receipt, or every receipt by one signer in a period. ([8.7](../spec/08-fidelity.md#87-revocations-and-the-roster))
Rights record
: A witness's license, the basis on which the team holds it, and the uses that basis allows. ([14.1](../spec/14-rights.md#141-the-rights-record))
Roster
: The list of keys that may sign, with the person who holds each, that person's role in the team, and what the key may sign. ([8.7](../spec/08-fidelity.md#87-revocations-and-the-roster))
Selector
: Outside term.
In the W3C Web Annotation Data Model, the part of an annotation's target that says where in the source resource the annotation applies.
The model defines `TextQuoteSelector` (exact text, with optional prefix and suffix) and `TextPositionSelector` (offsets, which the model calls very brittle), among others ([the W3C model](https://www.w3.org/TR/annotation-model/)).
Layers use a custom `AnchorSelector`, which carries an anchor, followed by a `TextQuoteSelector` for tools that do not know it; they use neither `TextPositionSelector` nor `FragmentSelector`. ([18.3](../spec/18-layers.md#183-the-annotation))
Spot-check
: A second reviewer's check of a sample of a receipt's nodes, drawn from a seed nobody can steer: the checker's deterministic signature over the receipt's record hash. ([8.8](../spec/08-fidelity.md#88-spot-checks))
Stamp rule
: A pattern that recognizes a publisher's download stamp in a page's text, so that fingerprints ignore it. ([7.2](../spec/07-geometry.md#72-stamp-rules))
Strict projection
: A node's text with notation folded to one canonical form and structure kept; used for certifying agreement. ([5.3](../spec/05-hashes.md#53-the-strict-projection))
Suspect
: A doubtful reading raised for a person or a review session to answer. ([5.7](../spec/05-hashes.md#57-suspects))
Targeted F3
: Proofreading the nodes a team's claims, quotations and datasets rest on, rather than every node.
The target set also includes every display equation and, under the project's digit rule (`all`, `anchored-sections` or `none`), sentences with a digit in a text or math run (an inline stretch of plain text, or of TeX or Typst math, within the sentence; [3.5](../spec/03-nodes.md#35-inline-runs)). ([8.10](../spec/08-fidelity.md#810-targeted-f3))
Text leaf
: A leaf whose text a container's projections are made of: any leaf except an equation line, or an equation inside a sentence, whose text is already part of its equation or its sentence. ([3.6](../spec/03-nodes.md#36-the-plain-projection))
Text policy
: Whether a package carries its text (`full`) or withholds it (`checks-only`). ([12.5](../spec/12-package.md#125-text-policies))
Verdict
: A judgment of whether a cited passage supports a citing sentence: supports, partly, does not, or cannot tell. ([19.2](../spec/19-exercises.md#192-verdicts))
Version
: One expression of a work: a preprint, the version of record, an erratum, the Supporting Information. ([2.1](../spec/02-model.md#21-four-objects))
Web Annotation
: Outside term.
The W3C Recommendation of 23 February 2017 for annotations with a body, a target and a motivation ([the W3C model](https://www.w3.org/TR/annotation-model/)).
It gives sentences no permanent IDs and reports no outcomes such as current or stale; for annotation in general, it and its clients are the better choice.
Layers are Web Annotations. ([18](../spec/18-layers.md))
Witness
: One file of one version of a work, identified by its SHA-256. ([2.1](../spec/02-model.md#21-four-objects), [2.3](../spec/02-model.md#23-witnessesjson))
Work
: A piece of scholarship across all its versions. ([2.1](../spec/02-model.md#21-four-objects))
Reference in new issue View Git Blame Copy Permalink