paperspec/DECISIONS.md

# Decisions

In the style of Lode's `DECISIONS.md`.
Each entry says what `spec` 0.1 does where the design leaves a choice open, refines a rule so that two implementations compute the same bytes, or departs from the design's wording.
Entries marked *provisional* wait for the maintainer; everything else is adopted for 0.1.

## Refinements and departures

| ID | Decision | Why |
| --- | --- | --- |
| D1 | The repository is `varve-spec`; every identifier inside stays `scienting-*`. | The design keeps product names out of technical identifiers. |
| D2 | Offsets and quotations index the stored plain projection; `own_hash` and `node_hash` cover stored values exactly, without normalization; only the text values normalize. | When `node_hash` is equal, every offset is still exact, and a renderer slices stored text directly. |
| D3 | The kind list names `title`, `authors`, `abstract`, `keywords`, `notes`, `acknowledgments`, `appendix`, `figure-note` and `table-note` explicitly. | The design uses them as children but omits them from the list it says refuses all others. |
| D4 | After its heading, a section's blocks and subsections may interleave. | Papers put text after subsections; the design's "then nested section" would refuse them. |
| D5 | Simple notation includes `.` and `,`. | Otherwise `$-1.5$` is complex and never agrees with the text "−1.5". |
| D6 | The strict projection marks `cite`, `xref` and `fnmark` runs with U+FFF9 and U+FFFB. | Citation structure must not vanish: "10" and citation 3 is not "103". The design is silent. |
| D7 | Outside notation, a hyphen-minus or en dash before a digit becomes U+2212. | The design's "a hyphen before a digit" read for text as well as notation; "10-20" and "10–20" then agree. |
| D8 | The lossy projection deletes whitespace and dashes rather than collapsing them. | OCR merges and splits words; the key only proposes alignments, so recall matters. |
| D9 | Container projections join their text leaves with a space; [3.6](spec/03-nodes.md#36-the-plain-projection) defines the leaves. | The design says "concatenated" without a separator or a leaf set. |
| D10 | Anchors always carry `own_hash`; anchors on containers without content carry their `leaves`. | The relabel rule needs `own_hash` on every anchor, and the "half of the original leaves" rule needs the original leaves. |
| D11 | Quotations over 200 code points become `exact_hash` and `length`; `prefix` and `suffix` hold at most 32. | The open decision on the cap, adopted provisionally, without losing reattachment of long sentences. *Provisional.* |
| D12 | When a quote has several hits, `prefix` and `suffix` pick one. | As W3C text-quote selectors do; the design says only "exactly once". |
| D13 | A tenth operation, `set`, changes one structural attribute; `place_after` positions inserts and moves; `split` trims whitespace at the cut; `merge` joins runs with one space by default. | Spans, roles and header paths are dropped by readings and need a correction; `after` was needed for a hash. |
| D14 | Applied corrections record `before`, `after`, `path`, `to_path`, `touched`, `created`, `retired` and `from`. | Drift and relabel reattachment become computable from the record, without replaying history. |
| D15 | Drift's share is touched leaves over current leaves and touched leaves together, four decimals, half up; `high` is strictly above the threshold. | The design gives the idea; this gives one number. |
| D16 | A row's `header_path` is not part of any hash. | The design gives rows no content of their own; so a header-path fix does not stale cell anchors. |
| D17 | Fingerprint text deletes whitespace and control and format characters. | PDF extractors disagree about where they insert spaces. |
| D18 | SQL names avoid words reserved in SQLite, PostgreSQL or MySQL: `doc_key`, `work_key`, `idx`, `made_at`, `signer`, `before_hash`, `after_hash`, `ref_node`. | Dolt is MySQL-compatible, and `key`, `index`, `before` and `by` are reserved there. |
| D19 | The tables store every property of every record, JSON as canonical text, so that unload gives the package back byte for byte, with assets by SHA-256 in `package_files`. | The design requires a byte-identical round trip. |
| D20 | Keyed hashing: HKDF salts `scienting-team-key/1` and `scienting-page-key/1`, info `scienting-hash/1` or the export's context, `key_id` from a domain-separated SHA-256, and page hashes rather than fingerprints in exports. | The design's open decision on the scheme, made concrete. *Provisional.* |
| D21 | Receipts may attest F1 to F3, may cover `records` as well as nodes, and are re-issued under a key with `export_of`. | The same mechanism signs annotations and digitizations; plain hashes cannot leave the team. |
| D22 | Spot-check samples rank node IDs by SHA-256 of the seed and the ID; bounds are one-sided at 95%, reported to six places, rounded up. | One deterministic sample and one string for every implementation. |
| D23 | Checks-only packages also omit corrections, suspects, datasets, figure text and CSL records. | Each carries fragments of the text. |
| D24 | Fidelity is recorded on leaves only, and F3 comes only from receipts. | A receipt is the only record of a person's check. |
| D25 | A policy resolves only unknown uses; an expired basis makes every use false. | A team's decision should never silently widen an explicit `false`. |
| D26 | Backend conditions are a closed vocabulary, and an unknown answer fails a condition. | A gate that guesses is not a gate. |

## Still open

| ID | Decision | Default here | Waits for |
| --- | --- | --- | --- |
| O1 | The roster: `scienting-roster/1` is defined here; Lode already verifies a roster. | This format. | Reconciling with Lode's at M4. |
| O2 | The manifest's exact field names against `lode-cache/1`. | `{format, doc, key, files: [{path, sha256, size}]}`. | Comparing with Lode's implementation. |
| O3 | Package extension and media type. | `.sct.zip`, `application/vnd.scienting.doc+zip`. | The maintainer; fixed forever once shared. |
| O4 | Node ID form. | Opaque. | The maintainer. |
| O5 | Text normalization for `text_hash`. | NFC and whitespace. | The maintainer; existing Lode extracts keep Lode's rule. |
| O6 | Canonical math, stage 2. | Stage 1: complex runs compared by source, run by run. | H4. |
| O7 | Quotation cap. | 200 code points. | Counsel and robustness measurements. |
| O8 | Drift threshold, spot-check sample, digit rule, target set, receipt scopes, container strictness. | As the design proposes. | The validation tests of the design's 16.1. |
| O9 | Stage-to-rights defaults and the combining rule. | As the design proposes, in `registry/stages/`. | Counsel. |
| O10 | Stamp-line rules. | Four published patterns and a margin rule. | Pairs of real downloads, kept out of the repository. |
| O11 | License of the tools. | Apache-2.0. | The maintainer. |

## Known limits of 0.1

- The strict projection removes spaces inside notation but keeps them in text, so `$T = 300$` from LaTeX and "T = 300" from a PDF disagree and become a `word` suspect; M3 should measure how often.
- Page fingerprints depend on extracted text lines; the vectors test the function, and the converter and the reader must use extractors that agree on the corpus.
- The oracle verifies Ed25519 only; SSH, OpenPGP and Sigstore signatures are specified by reference.
- CI executes the SQL on SQLite only; Dolt and PostgreSQL are covered by the portability rules and the reserved-word check, not by execution.
- There is no zipped package among the fixtures yet.
- Vectors were computed with Unicode 15.0; normalization is stable across versions, but Script and General Category assignments for newly encoded characters are not.