0 Fork 0

Files

T

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

4.1 KiB

Raw Blame History

22. Conformance

22.1 The suite

Path	Holds	A conforming implementation
`vectors/*.jsonl`	Inputs and expected outputs, one case per line.	Computes every expected output from its input.
`fixtures/packages/`	Valid packages: a converted chemistry paper with corrections, receipts, a multi-level-header table and a dataset; its checks-only export; an open-access paper with two witnesses; a Typst draft; a tiny document.	Accepts each, and recomputes every value it contains.
`fixtures/records/`	A valid record of every other format that is a JSON file of its own; the stage requirements and stamp rules are in `registry/`, and a bundle is built by `tools/load.py --bundle`.	Accepts each.
`fixtures/invalid/`	Invalid packages, each with `expect.json` naming the rule it breaks.	Refuses each, and SHOULD name that rule.
`fixtures/keys/`	The test keys that signed the fixtures and the team secret of the checks-only export.	Never uses them for anything else.

All fixture text is synthetic and dedicated to the public domain; license fields inside fixtures describe the fictional works. Each part's CI runs this suite against its own implementation, so the parts cannot drift apart silently.

22.2 Validating a package

A validator checks, in order, and reports each failure as path:line: rule: message:

The manifest: present, valid, sorted, every listed file present with its hash and size, nothing unlisted, paths safe, required files present.
Every file in canonical form, and every record against its schema.
The tree (3), runs and references between nodes.
The policy and hashing scheme (12.5).
The five values of every node, the root and meta_hash, when the text is present and the key, if any, is known.
The ID table, the corrections, the witnesses, pages, locations and references, and every file's order.
Receipts: IDs, roots, documents, node order, signatures against the package's roster, spot-check keys, seeds and samples, and the fidelity distribution.

22.3 Schemas

Schemas use draft 2020-12, restricted to the keywords $schema, $id, $ref, $defs, $comment, title, description, examples, default, deprecated, type, enum, const, properties, required, additionalProperties, patternProperties, propertyNames, minProperties, maxProperties, dependentRequired, items, prefixItems, minItems, maxItems, uniqueItems, contains, minLength, maxLength, pattern, format, minimum, maximum, exclusiveMinimum, exclusiveMaximum, oneOf, anyOf, allOf, not, if, then and else. Patterns avoid \d, \w, \s, \b and lookbehind, whose meaning differs between regular-expression dialects. A schema checks shape; the chapters' rules, such as the five values, are checked by validators.

22.4 Rules

registry/rules.json lists every rule ID with its meaning. Rule IDs are stable: a rule's meaning never changes, and a retired rule's ID is never reused.

Prefix	Covers
`package.`	The manifest, paths, files and schemas.
`doc.tree.`, `doc.node.`, `doc.run.`, `doc.table.`	The tree, node content and runs.
`doc.hash.`	The five values, the root and the metadata hash.
`doc.id.`, `doc.order.`	The ID table and file order.
`doc.policy.`	Text policies and keyed hashing.
`doc.correction.`, `correction.`	A package's corrections, and the gate.
`doc.receipt.`, `doc.qa.`, `doc.fidelity.`	Receipts, spot-checks and levels.
`doc.witness.`, `doc.page.`, `doc.location.`, `doc.reference.`	Witnesses and geometry.
`grade.`	Grading.

22.5 Stability

Within a major version of a format, a valid file stays valid, and every value the chapters define is computed the same way. Rule IDs, enumeration values and format identifiers are never reused with another meaning. A candidate format changes only with a recorded reason and a new or changed vector; a provisional one may change more freely, and says so in registry/formats.json.

4.1 KiB Raw Blame History