@sanning/proof 0.16.0 → 0.18.0

package/README.md

@@ -165,17 +165,62 @@ Every event also appears in `result.events`, in body order, with a status that n
 
 Bytes come back as `Uint8Array`, never a string: the spec commits to **raw bytes**, and a UTF-8 decode is lossy for any payload that is not valid UTF-8, re-encoding such a string would change the bytes and break the hash. Decode to text yourself if you know your payload is text.
 
+## Check the files that came with a pack
+
+A pack proves what its records signed. To ask whether it vouches for the files
+you were handed beside it, such as a screenshot, a report or an export, name
+them after `--files`. Each file is hashed with SHA-256 and looked up among what
+the pack's signed records commit to. A folder stands for every regular file
+inside it, so one argument covers a whole download on any operating system,
+the Windows command prompt and PowerShell included (they do not expand a
+wildcard such as `evidence/*`, and this command does not either):
+
+```bash
+npx @sanning/proof verify pack/bundle.json --logs pack/logs --files evidence/
+```
+
+The report lists the files the pack vouches for, the files that match no record
+and the commitments no file was offered for. A match is by hash alone: file and
+folder names are never compared, and the verdict and the exit code never move.
+
+- A folder is read recursively, and hidden files count. Its files are listed as
+  `<folder>/<path inside>` in UTF-16 code unit order of that path, so both
+  kernels print one list in one order. Files and folders can be mixed in one
+  command.
+- A symbolic link inside a folder is never followed. It is listed as skipped,
+  with the reason, as is anything that is not a regular file (a pipe, a socket)
+  and a file or folder the command cannot read. Nothing is dropped without
+  being named, and a skipped file is not a verdict about it.
+- Two files with one hash are both listed, each under its own name. An empty
+  file is an ordinary file with the empty digest. A file is read in
+  pieces and hashed, so it is never held in memory. A file you name yourself is
+  read at any size; the files found inside folders share 1 GiB per run, the cap
+  the `.zip` reader uses, and one that would push past it is listed as skipped
+  (`too_large`) and not read, so a sparse file of a terabyte cannot hold the
+  command. `case` bounds its other reads of files on disk as well; the section on `case` lists them.
+- A folder nested more than 32 levels deep, one holding more than 50,000 files
+  and folders, or one with a name that is not valid UTF-8, exits 2, as `case`
+  does. A path that is not a readable file or folder exits 2.
+
 ## Read several packs together: a case reading
 
 When a case spans more than one pack (two agents, two organizations, one hand-off between them), check the packs together. This is `readCase` from a terminal, with no page in the way:
 
 ```bash
+npx @sanning/proof case audit-file.zip             # a whole download, one command
 npx @sanning/proof case assessor-pack/ challenger-pack/
-unzip packs.zip -d case/ && npx @sanning/proof case case/   # a zip of several packs
-npx @sanning/proof case case/ --json            # the full reading, for a script
+npx @sanning/proof case case/ --json               # the full reading, for a script
+```
+
+Each argument is a folder, or a case file named as a `.zip`. A folder is one pack (`bundle.json` plus `logs/`), or a folder that holds several packs, such as an unzipped folder of packs. A `.zip` is read as the folder `unzip <name>.zip -d <name>` would make, so the archive and its unpacked folder give one reading, with no unzip step and on any operating system. A `.zip` inside a folder is a file like any other: it is hashed, never unzipped. Packs are found by the verify page's splitting rule, so the page and this command apply the same rule to the same unpacked tree: every `bundle.json` is a pack, a file belongs to the deepest pack whose `bundle.json` or `logs/` it sits in, and every other file is listed as outside every pack and is never read as part of a pack. Several folders are read as one folder holding them, each under its own name. Each `bundle.json` is read with `verify`'s own reader (`readBundleBytes`), so the two commands classify one bundle the same way.
+
+**The files outside every pack are checked too, with no flag.** A download usually holds more than packs: a screenshot, a report, an export. `case` hashes each file that sits outside every pack, with SHA-256 over its exact bytes, and looks the digest up among what every pack's signed records commit to, the same check `verify --files` makes. The report lists each as vouched for, naming the record and its pack, or as matching no record:
+
+```bash
+npx @sanning/proof case audit-file.zip
 ```
 
-Each argument is a folder: one pack (`bundle.json` plus `logs/`), or a folder that holds several packs, such as an unzipped folder of packs. `case` does not open archives: given a `.zip`, it exits `2` and says to unzip it first and pass the folder. Packs are found by the verify page's splitting rule, so the page and this command apply the same rule to the same unpacked tree: every `bundle.json` is a pack, a file belongs to the deepest pack whose `bundle.json` or `logs/` it sits in, and every other file is listed as outside every pack and never opened. A `.zip` inside the folder is a file like any other. Several folders are read as one folder holding them, each under its own name. Each `bundle.json` is read with `verify`'s own reader (`readBundleBytes`), so the two commands classify one bundle the same way.
+This is information beside the case reading and never inside it: the verdict, the exit code and the summary are the same whether a file matches or not, and a changed file reads as no match, nothing more. A match is by hash alone, so no name or folder is compared. Files after `--files` are offered as well. Each file that cannot be hashed, such as a link, a pipe, a zip entry the reader refused (with the reader's own words) or a file that cannot be read, is listed as skipped with the reason, so every file outside a pack is matched, unmatched or skipped. Two files with one hash are both listed; an empty file is an ordinary file; a file is read in pieces. The files share 1 GiB in all, the cap the `.zip` reader uses: one that would push past it is listed as skipped (`too_large`) and not read, so a sparse file of a terabyte in a download cannot hold `case` at that step. Every other read `case` makes of a file on disk is bounded too, so a sparse file of a terabyte can neither stall `case` nor exhaust its memory. The index comparison hashes every file under `packs/` and `report/` in pieces, within its own 1 GiB, the files the index lists first, and a listed file it has no room left for is reported as `case_index_file_too_large`, never as a match and never as absent. A pack's own files (`bundle.json`, `logs/`), `contents.json` and `witness-cache.json` are read whole within one 1 GiB total across the run: a pack's own file with no room left exits 2 at once, naming the file (the words say the run's total is used up, not that the file is itself over 1 GiB), a `contents.json` with no room left reads as an unreadable index (`case_index_unreadable`), and a `witness-cache.json` with no room left reads as no cache, with a `note` line saying so. A `.zip` larger than 1.25 GiB on disk exits 2 before it is read. A file outside every pack, `contents.json` and `witness-cache.json` included, therefore never keeps `case` from its verdict, and one a pack owns, or an archive that large, is refused promptly instead. Without `--files` the report lists each file read and then one line, `N recorded commitment(s) matched no loose file and no log in their own pack`, with no line for each record; `--files` and `--json` list every commitment no file matched, those the count leaves out included. The section is printed when a file sits outside every pack or `--files` is given, so a case with neither prints what it printed before, and the `files` member of `--json` follows the same rule.
 
 The walk is bounded and follows no link. A symbolic link is never followed: it is listed as outside every pack and not read, even under a pack's `logs/`, and a link named on the command line exits `2`. A folder nested more than 32 levels deep, more than 50,000 files and folders in all, or a name that is not valid UTF-8 exits `2`; a bad name is refused rather than escaped, because two different names would then read as one. A `bundle.json` nested more than 512 levels deep exits `2`, from `case` and from `verify` alike. The rules are pinned for both kernels by `vectors/case-split.json`, shipped in this tarball, as directory trees.
 
@@ -238,7 +283,7 @@ The primary signature covers `JCS(envelope minus signature minus co_signatures)`
 
 ## Why you can trust it (without trusting us)
 
-Three **independent implementations** of this kernel exist: this package, the Python [`sanning-proof`](https://pypi.org/project/sanning-proof/) (PyPI), and and the MIT-licensed Go reference. The TypeScript and Python kernels are conformance-gated **byte-for-byte** in CI against one shared corpus, pinned per file by SHA-256 at cut tag `test-vectors-v4.4`, and a cross-kernel agreement gate re-runs the corpus plus adversarial negatives through both, asserting identical verdicts on identical bytes. The Go reference runs as a third leg of that same gate, built at the commit its vendoring pins.
+Three **independent implementations** of this kernel exist: this package, the Python [`sanning-proof`](https://pypi.org/project/sanning-proof/) (PyPI), and the MIT-licensed Go reference. The TypeScript and Python kernels are conformance-gated **byte-for-byte** in CI against one shared corpus, pinned per file by SHA-256 at the newest cut tag, named in `test-vectors/CORPUS-v4.md`, and a cross-kernel agreement gate re-runs the corpus plus adversarial negatives through both, asserting identical verdicts on identical bytes. The Go reference runs as a third leg of that same gate, built at the commit its vendoring pins.
 
 That mutual gate is the point: anyone can verify these provenance records with **no Sanning code in the trust path**, write your own verifier against the specs that ship inside the [`sanning-proof`](https://pypi.org/project/sanning-proof/) sdist, and the corpus will tell you if it is conformant.
 

package/dist/agent-proof.js

@@ -14,12 +14,12 @@
 //   4. Confirm the reconstructed root == checkpoint_envelope.payload.merkle_root.
 //   5. (optional) Re-fetch checkpoint_tx_id from a gateway and byte-compare.
 import { hexToBytes, utf8 } from "./crypto.js";
+import { safeInteger } from "./grading.js";
 import { leafHash, verifyInclusion } from "./merkle.js";
 import { MAX_CANONICAL_DEPTH, exceedsDepth, jcs, jcsParse, verifyEnvelope } from "./verifier.js";
 export const AGENT_PROOF_SPEC_VERSION = "sanning.agent.proof/v1";
-function stringifyErr(e) {
-    return e instanceof Error ? e.message : String(e);
-}
+/** The sentence `agent_proof.py` writes when the proof's own fields are not usable. */
+const MALFORMED_PROOF = "merkle_root / audit_path / leaf_index malformed";
 function toHex(bytes) {
     let out = "";
     for (const x of bytes)
@@ -44,26 +44,28 @@ export async function verifyAgentProof(bundle, options = {}) {
         errors: [error],
     });
     if (bundle === null || typeof bundle !== "object" || Array.isArray(bundle)) {
-        return fail("agent proof bundle is not a JSON object");
+        return fail("bundle is not a JSON object");
     }
     // Bound nesting before any canonicalization (checkpoint envelope + Merkle
     // leaves are canonicalized recursively) — a fixed shared limit keeps this a
     // `malformed` verdict in every kernel. See MAX_CANONICAL_DEPTH.
     if (exceedsDepth(bundle, MAX_CANONICAL_DEPTH)) {
-        return fail(`agent proof bundle nesting exceeds the ${MAX_CANONICAL_DEPTH}-level canonicalization depth bound`);
+        return fail(`bundle nesting exceeds the ${MAX_CANONICAL_DEPTH}-level canonicalization depth bound`);
     }
     const b = bundle;
     if (!isAgentProofSpec(b.spec_version)) {
-        return fail(`unsupported agent-proof spec_version: ${JSON.stringify(b.spec_version)}`);
+        // An absent one reads `null`, as in `agent_proof.py` (`dict.get` gives
+        // None); `JSON.stringify(undefined)` would write the word `undefined`.
+        return fail(`unsupported bundle spec_version: ${JSON.stringify(b.spec_version ?? null)}`);
     }
     if (b.checkpoint_envelope === null || typeof b.checkpoint_envelope !== "object") {
-        return fail("agent proof bundle missing checkpoint_envelope");
+        return fail("bundle missing checkpoint_envelope");
     }
     if (b.leaf === null || typeof b.leaf !== "object") {
-        return fail("agent proof bundle missing leaf");
+        return fail("bundle missing leaf");
     }
     if (!Array.isArray(b.audit_path)) {
-        return fail("agent proof bundle missing audit_path[]");
+        return fail(MALFORMED_PROOF);
     }
     const errors = [];
     // Step 1: verify the checkpoint envelope (inline payload — no payloadBytes).
@@ -85,27 +87,50 @@ export async function verifyAgentProof(bundle, options = {}) {
         const payload = (b.checkpoint_envelope.payload ?? {});
         if (typeof payload.merkle_root === "string")
             merkleRoot = payload.merkle_root;
-        if (typeof payload.leaf_count === "number")
-            leafCount = payload.leaf_count;
+        // `leaf_count` and `leaf_index` are read BY VALUE, the rule every
+        // inclusion reader in both kernels follows (evidence-bundle A38): `3.0` is
+        // 3, and a fraction, a value past 2**53 - 1, a string or a boolean is not
+        // an integer. `agent_proof.py` reads them through `_safe_integer`.
+        leafCount = safeInteger(payload.leaf_count) ?? undefined;
         if (merkleRoot === undefined)
             errors.push("checkpoint payload missing merkle_root");
         if (leafCount === undefined)
-            errors.push("checkpoint payload missing leaf_count");
+            errors.push("checkpoint payload leaf_count is not an integer");
     }
-    catch (e) {
-        errors.push(`checkpoint verify error: ${stringifyErr(e)}`);
+    catch {
+        // The sentence `agent_proof.py` writes for the same failure. The thrown
+        // text is the host's, and a public result carries the kernel's words only
+        // (proof#150).
+        errors.push("checkpoint envelope verification failed");
     }
     // Steps 2-4: leaf hash, audit-path walk, root match.
     let inclusionOk = false;
     if (merkleRoot !== undefined && leafCount !== undefined) {
+        let lh;
         try {
-            const lh = await leafHash(utf8(jcs(b.leaf)));
-            inclusionOk = await verifyInclusion(lh, b.leaf_index, leafCount, b.audit_path.map((h) => hexToBytes(h)), hexToBytes(merkleRoot));
-            if (!inclusionOk)
-                errors.push("RFC 9162 inclusion proof did not reconstruct merkle_root");
+            lh = await leafHash(utf8(jcs(b.leaf)));
+        }
+        catch {
+            errors.push("leaf is not JCS-canonicalizable");
+        }
+        const leafIndex = safeInteger(b.leaf_index);
+        if (lh !== undefined && leafIndex === null) {
+            // `agent_proof.py` refuses a leaf_index that is not an integer with this
+            // sentence. Without the check a string, `null` or `1.5` reaches the walk
+            // and reads as a failed inclusion proof instead (proof#150).
+            errors.push(MALFORMED_PROOF);
         }
-        catch (e) {
-            errors.push(`inclusion verify error: ${stringifyErr(e)}`);
+        else if (lh !== undefined) {
+            try {
+                inclusionOk = await verifyInclusion(lh, leafIndex, leafCount, b.audit_path.map((h) => hexToBytes(h)), hexToBytes(merkleRoot));
+                if (!inclusionOk)
+                    errors.push("audit_path does not reconstruct merkle_root");
+            }
+            catch {
+                // `agent_proof.py`'s sentence for the same failure; the thrown text is
+                // the host's (proof#150).
+                errors.push(MALFORMED_PROOF);
+            }
         }
     }
     // Step 5: optional on-chain re-fetch.
@@ -144,7 +169,9 @@ export async function verifyAgentProof(bundle, options = {}) {
         inclusionOk,
         onChainOk,
         onChainChecked,
-        leafIndex: typeof b.leaf_index === "number" ? b.leaf_index : -1,
+        // Read by value, as the walk above read it: a `2.5` or `1e+21` index is
+        // reported as no index, never printed beside a verdict that refused it.
+        leafIndex: safeInteger(b.leaf_index) ?? -1,
         leafCount: leafCount ?? null,
         checkpointTxId: typeof b.checkpoint_tx_id === "string" ? b.checkpoint_tx_id : null,
         errors,
@@ -155,8 +182,8 @@ async function refetch(envelope, txId, gateways, fetchImpl) {
     try {
         expectedHex = toHex(utf8(jcs(envelope)));
     }
-    catch (e) {
-        return { ok: false, unavailable: false, error: `cannot canonicalize checkpoint envelope: ${stringifyErr(e)}` };
+    catch {
+        return { ok: false, unavailable: false, error: "checkpoint envelope is not JCS-canonicalizable" };
     }
     let anyReachable = false;
     for (const gw of gateways) {

package/dist/case-file.d.ts

@@ -42,7 +42,7 @@ export declare const MAX_INDEX_DEPTH = 512;
  * Every finding this comparison can report, in the order it reports them
  * (5.6.3). None of them is a verdict word and none contributes to one.
  */
-export declare const CASE_FILE_FINDING_KINDS: readonly ["case_index_unreadable", "case_index_pack_missing", "case_index_pack_unlisted", "case_index_file_missing", "case_index_file_unlisted", "case_index_file_differs", "case_index_names_absent"];
+export declare const CASE_FILE_FINDING_KINDS: readonly ["case_index_unreadable", "case_index_pack_missing", "case_index_pack_unlisted", "case_index_file_missing", "case_index_file_unlisted", "case_index_file_differs", "case_index_file_too_large", "case_index_names_absent"];
 export type CaseFileFindingKind = (typeof CASE_FILE_FINDING_KINDS)[number];
 /**
  * Whether `ref` is a legal pack folder name in a case file. For a producer; a
@@ -98,17 +98,36 @@ export interface CaseFileIndexReading {
  * The CLI's `bundle.json` reader uses it too.
  */
 export declare function jsonDepthExceeds(text: string | Uint8Array, limit: number): boolean;
+/**
+ * The reading of an index the caller could not hold at all (it is over the
+ * run's whole-read total, or it cannot be read): one `case_index_unreadable`
+ * finding with the caller's `reason`, and no comparison. The index is never an
+ * input to the verdict, so a file that cannot be read keeps nothing from it.
+ */
+export declare function unreadableCaseFileIndex(reason: string): CaseFileIndexReading;
+/**
+ * Every path the index lists (each pack's files and `report`), or `null` where
+ * the index is unreadable. A caller that charges a budget for hashing charges
+ * these files first, so a file the index does not list, which needs no digest,
+ * cannot turn a real mismatch into `too_large`.
+ */
+export declare function caseFileListedPaths(index: Uint8Array): ReadonlySet<string> | null;
 /**
  * Compare a case file's index with the folder it sits at the root of.
  *
  * `index` is the bytes of `contents.json`, or `null` where the folder holds
  * none. `files` is every regular file in the folder, as `{ path, sha256 }`
- * with `path` from the folder's root, `/`-separated; only the files under
+ * with `path` from the folder's root, `/`-separated, or `{ path, too_large: true }`
+ * for a file the caller did not hash because it is over its cap (reported as
+ * `case_index_file_too_large` where the index lists it, never as a match or as
+ * absent); only the files under
  * `packs/` and `report/` are compared, so a caller may list the rest or not. A
  * folder with no index is a folder of packs, with no finding.
  *
  * Findings come in the order of `CASE_FILE_FINDING_KINDS`, and within a kind in
- * the order of their `ref` or `path` by UTF-8 bytes; `case_index_names_absent`
+ * the order of their `ref` or `path` by UTF-8 bytes (the order a caller charges
+ * its hashing budget in is another, UTF-16 code units: evidence-bundle 5.6.3);
+ * `case_index_names_absent`
  * is in the index's own order, one per `absent[]` entry. An unreadable index is
  * one finding and no other comparison runs.
  *
@@ -116,7 +135,8 @@ export declare function jsonDepthExceeds(text: string | Uint8Array, limit: numbe
  */
 export declare function readCaseFileIndex(index: Uint8Array | null, files: readonly {
     path: string;
-    sha256: string;
+    sha256?: string;
+    too_large?: boolean;
 }[]): CaseFileIndexReading;
 /**
  * The house wording for one finding: what the index says against what the

package/dist/case-file.js

@@ -50,6 +50,7 @@ export const CASE_FILE_FINDING_KINDS = [
     "case_index_file_missing",
     "case_index_file_unlisted",
     "case_index_file_differs",
+    "case_index_file_too_large",
     "case_index_names_absent",
 ];
 // `<ref>`: 1 to 128 characters from A-Z, a-z, 0-9, `.`, `_` and `-`, and not
@@ -218,17 +219,59 @@ function readIndex(raw) {
     const report = fileList(own(value, "report"), "report");
     return { caseId, packs: listedPacks, absent: listedAbsent, report };
 }
+/**
+ * The reading of an index the caller could not hold at all (it is over the
+ * run's whole-read total, or it cannot be read): one `case_index_unreadable`
+ * finding with the caller's `reason`, and no comparison. The index is never an
+ * input to the verdict, so a file that cannot be read keeps nothing from it.
+ */
+export function unreadableCaseFileIndex(reason) {
+    return {
+        index: "unreadable",
+        caseId: null,
+        findings: [{ kind: "case_index_unreadable", reason }],
+    };
+}
+/**
+ * Every path the index lists (each pack's files and `report`), or `null` where
+ * the index is unreadable. A caller that charges a budget for hashing charges
+ * these files first, so a file the index does not list, which needs no digest,
+ * cannot turn a real mismatch into `too_large`.
+ */
+export function caseFileListedPaths(index) {
+    let read;
+    try {
+        read = readIndex(index);
+    }
+    catch (e) {
+        if (!(e instanceof Unreadable))
+            throw e;
+        return null;
+    }
+    const paths = new Set();
+    for (const [, packFiles] of read.packs)
+        for (const [path] of packFiles)
+            paths.add(path);
+    for (const [path] of read.report)
+        paths.add(path);
+    return paths;
+}
 /**
  * Compare a case file's index with the folder it sits at the root of.
  *
  * `index` is the bytes of `contents.json`, or `null` where the folder holds
  * none. `files` is every regular file in the folder, as `{ path, sha256 }`
- * with `path` from the folder's root, `/`-separated; only the files under
+ * with `path` from the folder's root, `/`-separated, or `{ path, too_large: true }`
+ * for a file the caller did not hash because it is over its cap (reported as
+ * `case_index_file_too_large` where the index lists it, never as a match or as
+ * absent); only the files under
  * `packs/` and `report/` are compared, so a caller may list the rest or not. A
  * folder with no index is a folder of packs, with no finding.
  *
  * Findings come in the order of `CASE_FILE_FINDING_KINDS`, and within a kind in
- * the order of their `ref` or `path` by UTF-8 bytes; `case_index_names_absent`
+ * the order of their `ref` or `path` by UTF-8 bytes (the order a caller charges
+ * its hashing budget in is another, UTF-16 code units: evidence-bundle 5.6.3);
+ * `case_index_names_absent`
  * is in the index's own order, one per `absent[]` entry. An unreadable index is
  * one finding and no other comparison runs.
  *
@@ -251,13 +294,20 @@ export function readCaseFileIndex(index, files) {
             findings: [{ kind: "case_index_unreadable", reason: e.reason }],
         };
     }
+    // `null` is a file that is here and was too large to hash (a file entry of
+    // `{ path, too_large: true }`): neither a match nor absent, reported as
+    // neither.
     const here = new Map();
     for (const entry of files) {
         const path = isObject(entry) ? own(entry, "path") : undefined;
         const digest = isObject(entry) ? own(entry, "sha256") : undefined;
-        if (typeof path === "string" && typeof digest === "string" && !here.has(path)) {
+        const tooLarge = isObject(entry) && own(entry, "too_large") === true;
+        if (typeof path !== "string" || here.has(path))
+            continue;
+        if (typeof digest === "string")
             here.set(path, digest);
-        }
+        else if (tooLarge)
+            here.set(path, null);
     }
     const listedRefs = new Set(read.packs.map(([ref]) => ref));
     // The first listing of a path wins, in index order: packs in order, each
@@ -305,7 +355,7 @@ export function readCaseFileIndex(index, files) {
     }
     for (const path of listedPaths) {
         const actual = here.get(path);
-        if (actual !== undefined && actual !== listed.get(path)) {
+        if (actual !== undefined && actual !== null && actual !== listed.get(path)) {
             findings.push({
                 kind: "case_index_file_differs",
                 path,
@@ -314,6 +364,10 @@ export function readCaseFileIndex(index, files) {
             });
         }
     }
+    for (const path of listedPaths) {
+        if (here.get(path) === null)
+            findings.push({ kind: "case_index_file_too_large", path });
+    }
     for (const [reason, key] of read.absent) {
         findings.push(key === null
             ? { kind: "case_index_names_absent", reason }
@@ -341,6 +395,9 @@ export function renderCaseFileFinding(finding) {
         case "case_index_file_differs":
             return (`the index lists ${finding.path} with SHA-256 ${finding.listedSha256}; ` +
                 `the file here hashes to ${finding.sha256}`);
+        case "case_index_file_too_large":
+            return (`the index lists ${finding.path}; hashing the file here would take case ` +
+                "past the 1 GiB it hashes in one run, so it was not compared");
         case "case_index_names_absent":
             if (finding.publicKey !== undefined) {
                 return ("the assembler says a pack signed by key " +

package/dist/case.d.ts

@@ -660,6 +660,41 @@ export type CaseNoteKind = (typeof CASE_NOTE_KINDS)[number];
  */
 export declare const CASE_EXCEPTION_KINDS: readonly ["counterpart_absent", "counterpart_absent_from_counterparty_records", "counterpart_absent_signer_unknown", "counterpart_ambiguous", "counterpart_malformed", "pair_failed", "record_malformed", "record_unclaimed_by_its_pack", "record_bytes_withheld", "record_bytes_unreadable", "pack_declaration_deviates", "pack_declaration_content_dependent", "pack_declaration_unreadable", "pack_undeclared", "pack_body_type_unknown", "pack_holds_no_records", "pack_key_unreadable", "pack_does_not_verify", "pack_grade_not_verified", "pack_bundle_content_dependent", "record_envelope_does_not_verify", "record_does_not_verify_in_its_pack", "record_content_mismatch", "record_content_dependent", "record_profile_quarantined", "case_holds_no_packs"];
 export type CaseExceptionKind = (typeof CASE_EXCEPTION_KINDS)[number];
+/**
+ * The status every record in every pack carries (evidence-bundle 5.5.4
+ * v1.35, A43, proof#204), as a closed set. A record is listed for each element
+ * of its pack's `body.events` as `packRecords` reads them, or, for a
+ * `sanning.evidence.export/v2` pack, of the events of the inline source
+ * bundle it wraps (`resolveTraceEvents`), and gets exactly one:
+ *
+ * - `read_clean`: the record went into the pile, no exception carries its
+ *   `packIndex` and `recordIndex`, and its pack's declaration check
+ *   names it by nothing (`declarationFindings` is empty). It says nothing
+ *   about its PACK: the pack's own grade and exceptions are on the pack, and a
+ *   surface MUST show that grade beside the status.
+ * - `read_flagged`: the record went into the pile, and at least one
+ *   exception carries its `packIndex` and `recordIndex`, or its pack's
+ *   declaration check names its `eventId` by a deviation or a content
+ *   finding (`declarationFindings` is not empty; under an `eventId` the
+ *   pack carries twice, every record with that id). An exception about the
+ *   pack alone flags no record.
+ * - `not_read`: the record never went into the pile. `reason` is the kind
+ *   of the exception that says why, on the record
+ *   (`record_profile_quarantined`, `record_envelope_does_not_verify`,
+ *   `record_bytes_withheld`, `record_bytes_unreadable`) or on its pack
+ *   (`pack_key_unreadable`, `pack_does_not_verify`,
+ *   `pack_body_type_unknown`, `pack_grade_not_verified` where the body
+ *   could not be read or the verifier graded a different number of records).
+ *   An export's wrapped records carry the reason of the exception their pack
+ *   actually got: `pack_body_type_unknown` where its wrapper holds, and
+ *   otherwise `pack_key_unreadable`, `pack_does_not_verify` or
+ *   `pack_grade_not_verified`.
+ *
+ * Before A43 the reading listed only the records it read, so a surface had to
+ * work out which records were missing, and why, by a rule of its own.
+ */
+export declare const CASE_RECORD_STATUSES: readonly ["read_clean", "read_flagged", "not_read"];
+export type CaseRecordStatus = (typeof CASE_RECORD_STATUSES)[number];
 /**
  * One pack in a case, as a reader was handed it.
  *
@@ -682,10 +717,25 @@ export interface CasePack {
  * `renderException`. */
 export interface CaseException {
     kind: CaseExceptionKind;
-    /** Which pack this is about, by the reader's own name for it. */
+    /**
+     * Which pack this is about, by the reader's own name for it. Two packs can
+     * carry one `ref`, so it is a label and never the join: `packIndex` is.
+     */
     packRef?: string;
+    /**
+     * Which pack this is about, by its position in `CaseReading.packs` (0
+     * first), present wherever `packRef` is (A43). Unique in the reading.
+     */
+    packIndex?: number;
     /** Which record, by its envelope `event_id`. */
     eventId?: string;
+    /**
+     * Which record, by its position in its pack's `body.events` (0 first),
+     * present wherever `eventId` is (A43). One pack can carry one `event_id`
+     * twice, so `packIndex` and `recordIndex` together are the join to
+     * `CaseReading.records`.
+     */
+    recordIndex?: number;
     /**
      * The counterparty key the record named, for the two counterpart kinds.
      * Normalized (`normalizedSigningKey`), so a reader compares what this module
@@ -717,20 +767,54 @@ export interface CaseException {
     reasons?: string[];
 }
 /**
- * 4.1's reading of one record the case holds, with the pack it came from.
+ * One record of one pack, with its status and, where it was read, 4.1's
+ * reading of it.
  *
- * EVERY record every pack supplied and this reader could read gets one of
- * these, in pack order and then in bundle order, including the ones that are
- * not hand-off records at all (`findings` carries `not_a_handoff_record`). 4.1
- * (v1.9, A14) requires that and names the reason: the one thing an attacker
- * wants is for a record to be absent from the output.
+ * EVERY record of every pack gets one of these (A43), in pack order and then
+ * in bundle order: the ones this reader read, including the ones that are not
+ * hand-off records at all (`findings` carries `not_a_handoff_record`), and the
+ * ones it did not, with `status` `not_read` and the `reason`. 4.1 (v1.9, A14)
+ * names why: the one thing an attacker wants is for a record to be absent from
+ * the output. An export's wrapped records are listed, `not_read`. A pack whose
+ * body carries no `events` array, and wraps none, lists none, and its own
+ * exception says why.
  */
 export interface CaseRecordReading {
     packRef: string;
+    /** The pack, by its position in `CaseReading.packs` (A43). */
+    packIndex: number;
     eventId: string;
+    /**
+     * The record, by its position in the list of records its pack lists (A43):
+     * `body.events`, or for a `sanning.evidence.export/v2` pack the events of the
+     * source bundle it wraps.
+     */
+    recordIndex: number;
+    /** One of `CASE_RECORD_STATUSES` (A43). */
+    status: CaseRecordStatus;
+    /**
+     * For `not_read`, the kind of the exception that says why; `null` for a
+     * record that was read.
+     */
+    reason: CaseExceptionKind | null;
+    /**
+     * The kinds its pack's declaration check names this record by, deviations
+     * (`DECLARATION_DEVIATION_KINDS`) then content findings
+     * (`DECLARATION_CONTENT_KINDS`), each in the check's own order. Matched on
+     * `eventId`, so under an `event_id` the pack carries twice every record with
+     * that id carries it. A record that went into the pile with any is
+     * `read_flagged` (A43).
+     */
+    declarationFindings: string[];
+    /** 4.1's verdict, or `null` where 4.1 gave none or the record was not read. */
     verdict: string | null;
     findings: string[];
     failedChecks: string[];
+    /**
+     * 4.1's candidate counterparts, each as `<pack ref>/<event_id>`. A LABEL for
+     * a person to read and never the join: two packs can carry one ref, and one
+     * pack one `event_id` twice (A43).
+     */
     counterparts: string[];
     /**
      * The role the pack's v2 declaration signs for this record, `handoff` or
@@ -747,6 +831,8 @@ export interface CaseNote {
     kind: CaseNoteKind;
     /** Which pack, by the reader's own name for it. */
     packRef: string;
+    /** Which pack, by its position in `CaseReading.packs` (A43). */
+    packIndex: number;
     /**
      * For `CONTENT_WITHHELD_BY_DECLARATION`, how many of the pack's records its
      * declaration withholds.
@@ -759,6 +845,13 @@ export interface CaseNote {
  * its wrapper, and never by an organization (D10).
  */
 export interface CasePackReading {
+    /**
+     * The pack's position in the order the reader was given the packs, 0 first
+     * (A43): the one name for a pack that is unique in the reading. Every
+     * exception, note and record names its pack by it as `packIndex`.
+     */
+    index: number;
+    /** The reader's own name for the pack. Two packs can carry the same one. */
     ref: string;
     /** The wrapper key, normalized, or `null` where this reader could not read it. */
     signingKey: string | null;
@@ -790,7 +883,10 @@ export interface CaseReading {
      * reachable only together with `verdict === "verified"`.
      */
     exceptions: CaseException[];
-    /** One reading per record the case holds and this reader could read. */
+    /**
+     * One entry per record of every pack, read or not, in pack order and then
+     * bundle order, each with its status (A43).
+     */
     records: CaseRecordReading[];
     /**
      * Every `[contributor, verdict]` the case verdict was computed from, in