@sanning/proof 0.19.1 → 0.20.0

package/vectors/README.md

@@ -1,7 +1,7 @@
-# `vectors/` — conformance tables that ship to consumers
+# `vectors/`: conformance tables that ship to consumers
 
-Unlike [`../../test-vectors/`](../../test-vectors/) — the tagged, vendored corpus
-for the kernel primitives — everything here is **inside the published package**
+Unlike [`../../test-vectors/`](../../test-vectors/), the tagged, vendored corpus
+for the kernel primitives, everything here is **inside the published package**
 (`files: ["vectors", …]`) and reaches downstream surfaces through npm.
 
 That distinction is the whole point. A rule that consumers must agree with needs
@@ -11,26 +11,26 @@ correctly.
 ## `stamp-on-chain.json`
 
 The rule that decides what re-fetching a **stamp's witness** from a gateway does
-and does not settle — the optional, online half of `sanning.stamp.trace/v1` and
+and does not settle: the optional, online half of `sanning.stamp.trace/v1` and
 `sanning.stamp.evidence/v2` (`evidence-bundle.md` §5.2.4 / §5.3.4). Implemented
 by [`../src/evidence.ts`](../src/evidence.ts) and asserted against this table by
-[`../test/stamp-on-chain-vectors.test.ts`](../test/stamp-on-chain-vectors.test.ts)
-— **and by the Python kernel against the same bytes**, in
+[`../test/stamp-on-chain-vectors.test.ts`](../test/stamp-on-chain-vectors.test.ts),
+**and by the Python kernel against the same bytes**, in
 `tests/test_stamp_on_chain_vectors.py`, so neither kernel can pass by agreeing
 with the other.
 
 **The one thing a consumer must not do with it: collapse the four states into a
 boolean.** `not checked` · `confirm` · `mismatch` · `unreachable`. A reader that
 cannot tell the first from the last will report that no gateway could be reached
-on a run that contacted none — a false accusation manufactured by a missing
-state, and the defect this table was written after. Vendoring rules are the same
+on a run that contacted none: a false accusation manufactured by a missing
+state. Vendoring rules are the same
 three steps as below, against `vectors/stamp-on-chain.json`.
 
 ## `witness-cache.json`
 
 The rule that decides what a reader does with the witnessed-time cache, the
 unsigned `witness-cache.json` beside a pack's `bundle.json` (`evidence-bundle.md`
-§5.5.6 and §5.6.6, v1.25, A30). Implemented by [`../src/witness-cache.ts`](../src/witness-cache.ts)
+§5.5.6 and §5.6.6). Implemented by [`../src/witness-cache.ts`](../src/witness-cache.ts)
 and the `case` command in [`../src/cli.ts`](../src/cli.ts), and asserted against
 this table by
 [`../test/witness-cache-vectors.test.ts`](../test/witness-cache-vectors.test.ts)
@@ -49,13 +49,12 @@ lookup settled stays labelled not checked.
 The rule that decides how a kernel reads bytes that claim to be `JCS(value)`
 (RFC 8785). Five checks, none of them left to a built-in decoder's defaults:
 **strict UTF-8**, **no leading byte-order mark**, **no non-finite literal**,
-**no object that names one member twice** (I-JSON, RFC 7493; rule version 3,
-proof#144), and **no unpaired surrogate in the parsed value**. A duplicate is
+**no object that names one member twice** (I-JSON, RFC 7493), and **no unpaired surrogate in the parsed value**. A duplicate is
 refused with the same message in both kernels, `duplicate key "<name>"`, and a
 case that carries `error` pins that exact string. The fourth is not the first one
 twice: a surrogate written as the ASCII escape `\ud800` survives every
 byte-level check, because the bytes are ASCII, and the parser produces the
-malformed code unit afterwards (proof#154).
+malformed code unit afterwards.
 Implemented by [`../src/verifier.ts`](../src/verifier.ts) as `jcsParse` and by
 `src/sanning_proof/canonicalize.py` as `jcs_loads`, and asserted against this
 table by [`../test/host-wording.test.ts`](../test/host-wording.test.ts) **and by
@@ -68,7 +67,7 @@ BOM. Python's `json.loads(<bytes>)` is not `bytes.decode("utf-8")` then
 `json.loads`: CPython sniffs the encoding and decodes with
 `errors="surrogatepass"`, so it strips a BOM too, accepts a UTF-16 or UTF-32
 body, and passes a lone surrogate and a CESU-8 pair through. Both defaults have
-shipped a split verdict on one pack that verifies (proof#140, gates 4 and 5).
+shipped a split verdict on one pack that verifies.
 
 **The accepted cases matter as much as the rejected ones.** An honest body
 carrying astral characters, a noncharacter, a U+FEFF *inside a string value* or
@@ -84,8 +83,8 @@ been tested.
 
 ## `pack-grading.json`
 
-The rule that decides whether a **pack** — a signed bundle plus whatever
-disclosed bytes travelled beside it — is `verified`, `failed` or `incomplete`.
+The rule that decides whether a **pack**, a signed bundle plus whatever
+disclosed bytes travelled beside it, is `verified`, `failed` or `incomplete`.
 Implemented by [`../src/grading.ts`](../src/grading.ts) and asserted against this
 table by [`../test/grading.test.ts`](../test/grading.test.ts).
 
@@ -110,30 +109,30 @@ One implementation, no table to keep in step, no drift to guard against.
 An older pinned kernel, another language, a surface that adapts a result from
 somewhere else. Then, and only then:
 
-1. **Vendor this file byte-for-byte.** Not "equivalent" — identical. A vendored
+1. **Vendor this file byte-for-byte.** Not "equivalent": identical. A vendored
    copy that is not byte-identical to this one is a defect, not a variant.
 2. **Assert your derivation against it** in your own suite, so an implementation
    that drifts from the rule goes red in your repo.
 3. **Run a drift check in CI** that compares your copy against the copy in
    `node_modules/@sanning/proof/vectors/pack-grading.json` and fails on any
-   difference — *and fails when it cannot find a copy to compare against.* A
+   difference, *and fails when it cannot find a copy to compare against.* A
    drift check that skips when its source is missing is not a check.
 
 Step 3 is the one people skip, and it is the one that matters. Steps 1 and 2
 catch an implementation drifting from its own table. Only step 3 catches the
-table itself being edited on one side — which is the failure that actually
-happened, and the reason this file moved here.
+table itself being edited on one side, and that is why this file ships in the
+package.
 
 ### Shape
 
 | Key | Meaning |
 |---|---|
 | `ruleVersion` | Bumped when a case's expectation changes **or a case is added**. An implementation asserts the version it was written against, so a table it does not understand fails loudly rather than passing vacuously. Currently **6**: `evidence-bundle.md` §5.4.5, where a record withheld by a readable declaration is counted apart and holds the pack at nothing. |
-| `kernelEventClasses` | The six per-event outcome classes a verification result can carry, named so a case can be written as counts rather than as a hand-built bundle. The two added at rule version 6, `withheldBound` and `withheldUnbound`, carry an `eventId` and a `payloadBindingOk`; `howToUse` says how an adapter builds them. |
+| `kernelEventClasses` | The six per-event outcome classes a verification result can carry, named so a case can be written as counts rather than as a hand-built bundle. Two of them, `withheldBound` and `withheldUnbound`, carry an `eventId` and a `payloadBindingOk`; `howToUse` says how an adapter builds them. |
 | `cases[].kernel` | The verification result to grade, as class counts. |
 | `cases[].logs` | The disclosure account: how many records the bundle presents, and how many disclosed usable bytes. |
-| `cases[].omissions` | Completeness notes — a checkpoint's signed `leaf_count` against the records the pack presents for it. |
-| `cases[].expect` | The verdict, the three counts, how many causes the grade must carry, and, from rule version 6, `recordsWithheld` where a case pins it. |
+| `cases[].omissions` | Completeness notes: a checkpoint's signed `leaf_count` against the records the pack presents for it. |
+| `cases[].expect` | The verdict, the three counts, how many causes the grade must carry, and `recordsWithheld` where a case pins it. |
 
 Nothing in a case names a transport. A directory read and a browser drop produce
 the same account and must produce the same verdict; a table that encoded one
@@ -142,7 +141,7 @@ surface's mechanism would let the other one drift while staying green.
 ## `case-file-index.json`
 
 How a reader compares a case file's index, `contents.json`, with the folder it
-sits at the root of (`evidence-bundle.md` §5.6.3, v1.20 A25). One pure function
+sits at the root of (`evidence-bundle.md` §5.6.3). One pure function
 in both kernels, `readCaseFileIndex` in [`../src/case-file.ts`](../src/case-file.ts)
 and `read_case_file_index` in `src/sanning_proof/case_file.py`, asserted against
 this table by [`../test/case-file-index.test.ts`](../test/case-file-index.test.ts)
@@ -159,7 +158,7 @@ literals.
 ## `file-match.json`
 
 How a reader matches files handed in beside a pack against the commitments its
-signed records make (`evidence-bundle.md` §5.7, v1.24 A29, proof#92). One pure
+signed records make (`evidence-bundle.md` §5.7). One pure
 reading in both kernels, `matchFiles` and `matchCaseFiles` in
 [`../src/file-match.ts`](../src/file-match.ts) and `match_files` and
 `match_case_files` in `src/sanning_proof/file_match.py`, asserted against this
@@ -173,8 +172,8 @@ matched by its SHA-256 and by nothing else**, and **no match moves a verdict**:
 a surface that matched by name, or took a hash from a field no record's key
 signed, would vouch for a file the pack never committed to. Written by
 `tools/gen-vectors/gen_file_match_vectors.py`, whose expectations are written
-by hand from what it built. Rule version 2 (A43, proof#204) adds `pack_index`
-and `record_index` to every commitment and every `not_read` entry: the pack's
+by hand from what it built. Every commitment and every `not_read` entry
+carries `pack_index` and `record_index`: the pack's
 position among the row's packs in `mode: case` (`null` in `mode: pack`) and
 the record's position among the events the pack presents, both read off the
 packs the row names.
@@ -182,8 +181,7 @@ packs the row names.
 ## `case-split.json`
 
 How `case` turns the folders it was handed into packs: the verify page's
-splitting rule (`sanning-io/verify-page` `src/lib/case.ts` `splitCase`,
-`src/lib/pack.ts` `assemble`) over a walk whose rules are the command's own,
+splitting rule (`splitCase`) over a walk whose rules are the command's own,
 restated in [`../src/cli.ts`](../src/cli.ts) and `src/sanning_proof/cli.py`
 because the page's code lives in the page. Two tables and the limits:
 
@@ -192,7 +190,7 @@ because the page's code lives in the page. Two tables and the limits:
   the packs, the outside paths and the paths that are not regular files, or
   the refusal. The rows include the decision file unpacked, a symbolic link
   under `logs/`, each side of the depth and entry limits, names that are not
-  UTF-8, and (v1.20, A25) a case file unpacked and as a `.zip` argument, with
+  UTF-8, and a case file unpacked and as a `.zip` argument, with
   the entries a reader lists and never reads and the archives it refuses.
 - `parses`: how `bundle.json` bytes become JSON through the reader `verify`
   and `case` share, including each side of the nesting limit.
@@ -205,8 +203,7 @@ run through both commands by `cross-kernel/run_case_cli.sh`.
 
 Every expectation is a literal written in
 `tools/gen-vectors/gen_case_split_vectors.py`, not the output of either
-kernel. The splitting rows were graded against the page's own code when the
-table was first written. The walk rows (links, depth, entry count, names, a
+kernel. The splitting rows match the page's own splitting. The walk rows (links, depth, entry count, names, a
 `.zip` argument) and the reader rows are the command's own rules, and the page
 does not share them: it opens a dropped `.zip`, drops a leading byte-order
 mark, and reads whatever the browser hands it for a link, a bad name or a deep
@@ -248,6 +245,27 @@ TypeScript verdict line and the Python `Gateways` line exactly.
 Two more members: `stoppedEarly` holds packs whose verification stops before
 any witness is read, each of which must print and write the same with
 `--gateways`, reachable or not, as offline (the Python `Gateways` line names
-the gateways passed); `agentProof` holds an agent proof signed `dev`, which the
-TypeScript `verify` prints as `SANDBOX` with exit 5 and the Python one, which
-implements no agent-proof verifier, refuses with exit 2.
+the gateways passed); `retiredAgentProof` holds a `sanning.agent.proof/v1` proof signed `dev`, which
+both `verify` commands read malformed, exit 2, and never as sandbox evidence: no
+kernel reads that retired format.
+
+## `agent-record.json`
+
+How a kernel reads one `agent.*` record on its own: steps 1 to 6 of
+`agent-events.md` §10, in the `sanning-io/specs` release pinned in
+[`../../vendor/specs/`](../../vendor/specs/). Implemented by `readAgentRecord`
+in [`../src/agent-record.ts`](../src/agent-record.ts), against the schemas
+bundled in [`../src/agent-schemas.generated.ts`](../src/agent-schemas.generated.ts),
+and asserted against this table by
+[`../test/agent-record.test.ts`](../test/agent-record.test.ts). The pinned
+release's own cases are asserted by
+[`../test/agent-conformance.test.ts`](../test/agent-conformance.test.ts). Every
+expectation is written by hand in
+`tools/gen-vectors/gen_agent_record_table.py`, which writes this file. The
+Python kernel does not read `agent.*` records yet, so only the TypeScript
+kernel asserts this table today.
+
+**The one thing a consumer must not do with it: read `partial` as a pass.** A
+record whose `extras.event_schema` names a version the kernel does not know,
+`sanning.agent/1.1` or `sanning.agent/2`, reads `partial`: the kernel holds no
+schema to check it against. It is never `verified` and never `malformed`.