@sanning/proof 0.13.0 → 0.14.0

package/vectors/README.md

@@ -26,12 +26,33 @@ 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
 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)
+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)
+**and by the Python kernel against the same bytes**, in
+`tests/test_witness_cache_vectors.py`. Every expectation is written by hand in
+`tools/gen-vectors/gen_witness_cache_table.py`, which writes this file.
+
+**The one thing a consumer must not do with it: print a cached time as
+anything but not checked.** Nobody signs the file, and anyone holding the pack
+can write it. The only time a surface may print as the public record's is one a
+gateway returned; a cached time the record contradicts is a finding, and one no
+lookup settled stays labelled not checked.
+
 ## `jcs-reader.json`
 
 The rule that decides how a kernel reads bytes that claim to be `JCS(value)`
-(RFC 8785). Four checks, none of them left to a built-in decoder's defaults:
-**strict UTF-8**, **no leading byte-order mark**, **no non-finite literal**, and
-**no unpaired surrogate in the parsed value**. The fourth is not the first one
+(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
+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).
@@ -135,6 +156,25 @@ whoever assembled the drop. Written by
 `tools/gen-vectors/gen_case_file_index_vectors.py`, whose expectations are
 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
+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
+table by [`../test/file-match.test.ts`](../test/file-match.test.ts) **and by the
+Python kernel against the same bytes**, in `tests/test_file_match.py`. `packs`
+holds real signed packs, keyed by name, with any side content beside them as
+`content_hex`; each row names the packs it reads (one for `mode: pack`, several
+for `mode: case`), the files it offers as names and bytes, and the reading it
+expects, with each `not_read` entry's rendered line left out. **A file is
+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.
+
 ## `case-split.json`
 
 How `case` turns the folders it was handed into packs: the verify page's