infra/paperspec
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3831b52a2bbb7186c60162b81ef7ce19a2a87bf3
paperspec/docs/glossary.md
T
alexmandClaude 3831b52a2b feat: ML-DSA-65, did:key, named hash algorithm, model provenance, log tiles and witnesses 
- hashing.algorithm names the hash function in every document; a consumer refuses one it does not implement (doc.hash.algorithm)
- ML-DSA-65 (FIPS 204) is an implemented signature scheme: pure-Python reference in tools/oracle/mldsa.py checked against NIST ACVP vectors, a receipt signed by the new roster key dana, and signature vectors for key generation and a deterministic signature
- roster keys may carry a did:key, which the validator checks against the public key (doc.roster.did), and a witness purpose for parties that cosign log checkpoints
- model provenance: a correction's author and an annotation's generator name the model with provider, version and the hashes of its weights, prompt and parameters, and where it ran
- the transparency log gains the tlog-tiles static layout (fixtures/records/log/), a project settings.log with origin, witnesses and threshold, and an acceptance rule; the fixture checkpoint is cosigned by a witness
- store.sql: roster_keys accepts cose and ml-dsa-65 and gains a did column
- spec chapters 01, 08, 11, 18, 20 and 23, the rationale, glossary, fixture, vector and tool guides updated; stress harness covers ML-DSA

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-15 04:39:12 -04:00

207 lines
14 KiB
Markdown
Raw Blame History

# Glossary
A scientific paper changes after it is published: errata appear, readings get corrected, annotations pile up. paperspec is a set of file formats for scientific papers that keeps each sentence findable through those changes (repository: <https://git.scient.ing/infra/paperspec>).
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))
Checklist
: A record of checking an export, such as accessible HTML, against a named standard, criterion by criterion; it is covered by the receipt of the person who checked.
Format `scienting-checklist/1`, `provisional`. ([8.11](../spec/08-fidelity.md#811-checklists))
Checkpoint
: A signed note that states a transparency log's size and root hash, which a verifier checks against the last checkpoint it saw.
Independent parties, the log's witnesses, cosign it, and a project says how many must.
Format `scienting-checkpoint/1`, `provisional`. ([23.2](../spec/23-log.md#232-checkpoints))
Correction
: An operation on an established document, with its evidence and author; never edited, only appended. ([11](../spec/11-corrections.md))
Description
: An annotation that describes a figure, panel or table for readers who cannot see it, as a short text equivalent (`alt`) or a full description (`long`); an accessible export uses confirmed descriptions only. ([18.4](../spec/18-layers.md#184-bodies))
DID
: Outside term.
A decentralized identifier (W3C).
A roster key may carry its `did:key`, which the public key alone determines, so a signer has one name inside and outside the store. ([8.7](../spec/08-fidelity.md#87-revocations-and-the-roster))
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))
Document key
: The work key, with a dotted suffix for any version other than the version of record: `.si` for Supporting Information, `.v2` for a second preprint. ([2.4](../spec/02-model.md#24-work-and-document-keys))
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))
History root
: The root of the Merkle tree over a document's corrections, kept in `document.json`, so a consistency proof can show that a later revision extends an earlier one. ([11.5](../spec/11-corrections.md#115-the-history-root))
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 paperspec, `jats` is a witness kind: the fixture `okafor2025solvent-acth` 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))
ML-DSA-65
: Outside term.
The lattice-based signature scheme of FIPS 204, believed to resist quantum computers.
A receipt may be signed with it today, beside Ed25519. ([8.4](../spec/08-fidelity.md#84-record-hashes-and-signatures))
Model
: The record of a machine-learning model that proposed a correction or wrote an annotation: its name, provider and version, and the hashes of its weights, instructions and parameters. ([11.2](../spec/11-corrections.md#112-every-correction-records))
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))
Proof
: An RFC 9162 inclusion proof that one item was covered by a receipt, or a consistency proof that one history extends another, each a short list of hashes.
Format `scienting-proof/1`. ([8.5](../spec/08-fidelity.md#85-merkle-roots))
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 the leaves of every anchored container, every equation and, under the project's digit rule (`all`, `anchored-sections` or `none`), sentences and cells with a digit in a text or math run (an inline stretch of plain text, or of TeX or Typst math, within the node; [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))
Tile
: One file of a transparency log served statically: 256 hashes of one level of the tree, or 256 entries, so a client fetches only the subtrees it needs. ([23.4](../spec/23-log.md#234-serving-a-log))
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))
VRF
: A verifiable random function (RFC 9381): a keyed function with exactly one valid proof for each key and input, so that a spot-check seed can be checked but not chosen. ([8.8](../spec/08-fidelity.md#88-spot-checks))
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))
Work key
: A work's permanent name: a Scholar-style citation key, a hyphen, and the first characters of a hash of the work's identity, such as `vaswani2017attention-a241`; minted once and never recomputed. ([2.4](../spec/02-model.md#24-work-and-document-keys))
Reference in new issue View Git Blame Copy Permalink