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

2.9 KiB

Raw Blame History

Contributing

This page is for anyone who wants to fix the specification, change a format or add an example. Propose a change as a pull request on the repository at https://git.scient.ing/infra/manuspec.

What a change needs

A change starts in the chapter of the specification that defines the rule, because the chapters are normative. The schemas, SQL, registries, vectors and fixtures then follow the chapter (spec/00 §0.5).

Change the chapter. Say what is new in the chapter's own terms, and link the sections it touches.
Change the schemas, SQL and registries that the rule shapes. A new refusal gets a rule ID in registry/rules.json.
Compute, never type, the expected values. Change the oracle in tools/oracle/ to apply the rule, and add the case that shows it to tools/build.py: a vector, a fixture or a broken package in fixtures/invalid/. Then run pixi run build, which rewrites fixtures/ and vectors/.
Run the checks. pixi run check must end with All checks pass. Without pixi, run python3 tools/check.py, with Python 3.14 and two packages, jsonschema and cryptography installed.
Record the change in CHANGELOG.md.

Versions

A change that makes a valid file invalid, or that changes a computed value, is a breaking change and needs a new major version of the format, with a migration. Adding an optional property, a node kind, a run kind or an enumeration value is a minor change (spec/00 §0.3). A rebuild that changes any file under vectors/ or any hash in fixtures/ is a computed value changing, so say in the pull request why it must.

New node kinds and run kinds

Propose a kind with the vector or fixture that shows it. A node kind needs its row in chapter 3, the node schema, and its entry in the CHILDREN table of tools/oracle/model.py. A run kind needs its row in section 3.5 and the node schema, and its text in the plain projection (3.6) and in the strict and lossy projections (5.3, 5.5).

Writing

The checker enforces two rules on every Markdown file: one sentence per line, and US spelling. pixi run lint runs markdownlint with the repository's settings. Define each term where it first appears, because the guides and READMEs are written for newcomers as well as implementers.

All fixture text is synthetic, written for the fixtures. The keys in fixtures/keys/ are public test keys and must never sign anything else.

Licenses

Each path keeps the license that LICENSE.md gives it: prose CC-BY-4.0, the normative data CC0-1.0, and tools/ Apache-2.0.

2.9 KiB Raw Blame History