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 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.