feat: documents and session tokens

fixtures/README.md

@@ -1,17 +1,53 @@
 # Fixtures
 
-All text here is synthetic and dedicated CC0; license fields describe fictional works.
+Example data for learning the formats and for testing implementations.
+All text here is synthetic, written for these files and dedicated CC0; license fields inside the fixtures describe fictional works.
 
-| Path | Is |
+## Packages
+
+| Package | What it shows |
 | --- | --- |
-| `packages/hale2026harmonic/` | Two sections of a converted chemistry paper, read once with errors and fixed by twelve corrections: a digit, a lost superscript, a missed boundary, a false boundary, a split paragraph, a running head, two labels, a garbled row replaced, a dropped row inserted, and a header span. It has a multi-level-header table, a display equation inside a sentence, a footnote, a figure with figure text and a real image asset, references, legacy aliases, geometry on fingerprinted pages, receipts (one partly invalidated by a correction, one spot-checked clean, one revoked, one suspended), a roster, a reported dataset and derived MathML. |
-| `packages/hale2026harmonic.checks-only/` | The same document exported to another machine of the team: text withheld, values under the team key in `keys/`. |
-| `packages/okafor2025open/` | An open-access paper with a JATS witness and a PDF witness, corroborated. |
-| `packages/smithlab2027charges/` | A short Typst draft that cites sentences of `hale2026harmonic` by address. |
-| `packages/tiny2026example/` | A small document; the base of the correction vectors and the invalid packages. |
-| `records/` | A valid record of every other format: anchors (span, leaf, cell, paragraph and keyed), rights, a policy, backends, profiles, a layer with its annotations and receipt, submissions, grades, a project, a digitization with its confirmation and dataset, a view, a QA report, a snapshot and a draft's sentence IDs. |
-| `invalid/<case>/` | A package that breaks one rule, and `expect.json` naming it. |
-| `keys/` | The Ed25519 test keys that signed the fixtures, and the checks-only export's team secret. Public; never use them for anything else. |
-| `src/` | The hand-written sources of the three M1 documents ([src/README.md](src/README.md)). |
+| `packages/hale2026harmonic/` | The main example, followed step by step in [the walkthrough](../docs/walkthrough.md): a chemistry paper read once with mistakes and fixed by twelve corrections. It has a table with two levels of column headers and grouped rows, an equation inside a sentence, a footnote, a figure with text inside its panels and a real image, references, legacy aliases, boxes on fingerprinted pages, receipts in every state (counting, partly invalidated, spot-checked, revoked and suspended), the roster that signed them, a dataset taken from the table, and derived MathML. |
+| `packages/hale2026harmonic.checks-only/` | The same document prepared for another of the team's machines: text withheld, every hash an HMAC under the team key in `keys/`. |
+| `packages/okafor2025open/` | An open-access paper established from a JATS file and a PDF that agree, so every sentence is corroborated. |
+| `packages/smithlab2027charges/` | A short draft written in Typst, whose sentences cite sentences of the main example by address. |
+| `packages/tiny2026example/` | A small document, the starting point of the correction vectors and the broken packages. |
 
-Everything except `src/` is generated by `python3 tools/build.py`; do not edit it by hand.
+## Records
+
+`records/` holds a valid example of every other format: anchors (a span, a leaf, a cell, a paragraph, and one keyed for a public layer), rights records, a team policy, backend declarations, team profiles, a layer with its annotations and the receipt that confirms them, submissions and grades, a project, a digitization with its confirmation and the dataset it yields, a view, a QA report, a draft snapshot and a draft's sentence IDs.
+
+## Broken packages
+
+Each folder in `invalid/` holds a package that breaks exactly one rule, and `expect.json` names it.
+A conforming implementation refuses every one of them and should report that rule.
+
+| Case | What is wrong | Rule |
+| --- | --- | --- |
+| `alias-dangling/` | An alias whose node does not exist. | `doc.id.successor` |
+| `bad-id/` | IDs use Crockford base32, which has no i, l, o or u. | `package.schema` |
+| `checks-only-plain/` | A checks-only package that still carries text and plain hashes. | `doc.policy.withheld` |
+| `cite-not-reference/` | A cite run names a node that is not a reference. | `doc.run.cite` |
+| `empty-optional-file/` | An optional JSONL file with no records. | `package.file.empty` |
+| `hash-mismatch/` | A node_hash that does not recompute. | `doc.hash.node-hash` |
+| `heading-not-first/` | A heading must be a section's first child. | `doc.tree.child` |
+| `location-unknown-page/` | A location on a page no witness has. | `doc.location.page` |
+| `manifest-hash/` | A file changed after the manifest was written. | `package.manifest.hash` |
+| `not-canonical/` | A line that is valid JSON but not canonical JSON. | `package.file.canonical` |
+| `receipt-root/` | A receipt whose Merkle root does not recompute. | `doc.receipt.root` |
+| `receipt-signature/` | A receipt changed after it was signed. | `doc.receipt.signature` |
+| `root-mismatch/` | document.json's root is not the root node's node_hash. | `doc.hash.root` |
+| `style-sup-sub/` | A run cannot be both a subscript and a superscript. | `doc.run.style` |
+| `text-edited/` | Text changed without its hashes. | `doc.hash.text-hash` |
+| `unknown-kind/` | Kinds outside the list are refused. | `package.schema` |
+| `unlisted-file/` | A file the manifest does not list. | `package.manifest.unlisted` |
+
+## Keys
+
+`keys/` holds the Ed25519 secret keys that signed the fixtures' receipts, and the team secret of the checks-only package.
+They are published so that anyone can reproduce the signatures; never use them for anything else.
+
+## Sources
+
+`src/` holds the hand-written descriptions of the three main documents, as first read; see [src/README.md](src/README.md).
+Everything else here is generated by `python3 tools/build.py`, so change the sources or the builder, never the generated files.

fixtures/src/README.md

@@ -1,6 +1,7 @@
 # Fixture sources
 
-Each source describes a document as first read, errors included, in a shorthand that `tools/build.py` expands; the build mints IDs, applies the listed corrections, lays out synthetic geometry, signs the listed receipts and writes the package.
+Each source describes a document as a converter first read it, mistakes included, in a shorthand that `tools/build.py` expands.
+The build mints IDs, applies the listed corrections, lays out synthetic geometry, signs the listed receipts and writes the package.
 The shorthand is tooling, not a format.
 
 | Shorthand | Becomes |