@sanning/proof 0.5.0 → 0.6.0

package/README.md

@@ -92,23 +92,48 @@ A bundle a producer built with disclosure carries the bytes **in the signed body
 npx @sanning/proof verify trace-bundle.json          # in-body content verified inline
 ```
 
-If the logs travel **alongside** a minimal bundle instead, pass them with `--logs` — a JSON object mapping `event_id` → bytes, where an even-length lowercase-hex string is read as hex and anything else as UTF-8 text:
+If the logs travel **alongside** a minimal bundle instead, pass them with `--logs`. It takes either shape below, and which one you passed is decided by `stat`, never by the extension.
+
+**A materialized pack — a DIRECTORY.** `materializeBundle` (in [`@sanning/anchor`](https://github.com/sanning-io/anchor)) writes `bundle.json` + `logs/<event_id>.json`, and each file's **raw bytes are the disclosure**. Point `--logs` at that directory and the pack verifies with nothing of ours in the path:
+
+```bash
+npx @sanning/proof verify pack/bundle.json --logs pack/logs
+```
+
+Nothing is decoded, re-parsed or re-serialised on the way in: the bytes on disk are the bytes hashed against the committed `content_hash` — the same bytes a verify page hashes from the same files. That is the whole point of the directory form. The alternative — reading the directory and hex-encoding it into a map yourself — is a step that has been got wrong twice in shipped code, once by writing the hex *text* into the log files, so `SHA-256(file)` was the hash of the encoding rather than of the bytes and genuine, untampered evidence failed.
+
+**A side input — a JSON FILE** mapping `event_id` → bytes, where an even-length lowercase-hex value is read as hex and anything else as UTF-8 text:
 
 ```bash
 npx @sanning/proof verify trace-bundle.json --logs logs.json
 ```
 
+Emit hex, not text, into that map: a UTF-8 decode is lossy for a non-text payload, and a log line that happens to *look* like hex would be decoded into something the producer never wrote. `logsSideInput` in `@sanning/anchor` builds the map correctly.
+
+The directory form's edge cases, **none of which is a verification failure** — an absent disclosure is not evidence of tampering:
+
+| Situation | What happens |
+|---|---|
+| A record with no file | That event's content is **undetermined** (`~`) and reported as undisclosed. Exit code unchanged. |
+| An empty directory | Valid. Discloses nothing, says so, exit code unchanged. |
+| A file whose name is no event id | Read, binds to nothing, and is **named** in a note — a typo'd filename is otherwise indistinguishable from minimal disclosure. |
+| A subdirectory | Skipped, never recursed: the layout is flat. Noted. |
+| Anything not named `<event_id>.json`, or not a regular file | Skipped, noted. |
+| A file we selected but cannot read | **Exit 2.** We were pointed at it, so a permissions or broken-link problem must not read as minimal disclosure. |
+
 Either way each event gains a `contentOk`: **`true`** match · **`false`** mismatch (the event *and* the rollup fail, exit `1`) · **`null`** undetermined — nothing disclosed, or no committed `content_hash` (a withheld record); never a failure, mirroring the payload-binding rule. The CLI prints a `logs ✓/✗/~` mark per event and a `logs: N/M disclosed verified` line.
 
-Programmatically the same side input is `content`, keyed by `event_id` — a `Uint8Array` is used as-is, a `string` is hex:
+Programmatically the same side input is `content`, keyed by `event_id` — a `Uint8Array` is used as-is, a `string` is hex. **Prefer a `Map`:**
 
 ```ts
 const result = await verifyEvidenceBundle(bundle, {
-  content: { [eventId]: rawLogBytes }, // Uint8Array, or a hex string
+  content: new Map([[eventId, rawLogBytes]]), // Uint8Array, or a hex string
 });
 result.events[0].contentOk; // true | false | null
 ```
 
+A plain object still works and is fully guarded on the way in. But **an `event_id` is producer-chosen**, and on a plain object the names that live on `Object.prototype` are not free: `content["__proto__"] = bytes` does not store anything — it replaces the object's prototype, and the bytes you meant to disclose are lost before the verifier ever sees them. If you are building the map from names you did not choose — a directory listing, a JSON key, an id off the wire — use a `Map` (or `Object.create(null)`). It is also what `disclosedContent` hands back, so its output feeds straight back in.
+
 In-body `events[].content` (signed) takes precedence over the side input; if both are present for an event and disagree, the event fails.
 
 ### …and get those raw logs back out (ingest)
@@ -161,6 +186,7 @@ const ok = await verifyInclusion(
 | `verifyEnvelope(env, optionsOrContentHash?)` | The three load-bearing checks (spec-version registry, payload-hash recompute, Ed25519 over the signed scope) + optional content bind. Pass `{ payloadBytes }` for external-commitment envelopes. Returns `VerificationResult`. |
 | `verifyEvidenceBundle(bundle, { gateways?, fetchImpl? })` | Verify a signed `sanning.evidence/v1` / `sanning.anchor.trace/v1` bundle: wrapper signature + `body_hash` + every checkpoint + every event's inclusion, offline (optional on-chain re-fetch). Returns `EvidenceBundleResult`. Powers the `npx @sanning/proof verify` CLI. |
 | `disclosedContent(bundle, { gateways?, content?, fetchImpl? })` | **Ingest:** verify a bundle, then hand back the DECODED raw bytes (`Uint8Array`) of every event whose disclosure bound to its committed `content_hash` — so materializing a received pack never means re-implementing the hex convention. Returns `DisclosedContentResult` (`content` map + per-event `verified` / `not_disclosed` / `undetermined` / `failed`, plus the full `verification`). |
+| `gradePack(result, account, notes)` + `accountDisclosure(bundle, content)` / `completenessNotes(bundle)` / `renderCause(cause)` | **Pack grading:** what a SURFACE may claim about a pack — the bundle plus whatever disclosed bytes travelled with it. Three states, never two: `verified` only when every record's own bytes bound to its own commitment and nothing is missing, unreadable, surplus or omitted; `failed` on a proven mismatch; `incomplete` when a check could not be run. Absent evidence is UNKNOWN, never an accusation. Pure — no I/O; transport stays yours. Conformance table: [`vectors/pack-grading.json`](https://github.com/sanning-io/proof/blob/main/ts/vectors/pack-grading.json), shipped in the tarball. |
 | `verifyAgentProofBundle(bundle, { gateways?, fetchImpl? })` / `isAgentProofSpec(v)` | Verify the agent producer's `sanning.agent.proof/v1` inclusion bundle. |
 | `contentHashes(env)` | The content hash(es) an envelope commits to, by event type — the reverse-provenance join keys. |
 | `specVersionSupported(v)` | Fail-closed accept-check: `sanning.agent/v1` and additive minors (`sanning.agent/v1.<n>`). Unknown majors/profiles are rejected. |
@@ -177,12 +203,13 @@ 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 the MIT-licensed Go reference, vendored into this repo under [`cross-kernel/vendor-agent/`](https://github.com/sanning-io/proof/tree/main/cross-kernel/vendor-agent) so anyone can build and run it. The TypeScript and Python kernels are conformance-gated **byte-for-byte** in CI against the shared [`test-vectors` corpus](https://github.com/sanning-io/proof/tree/main/test-vectors) (per-file SHA-256 pins; current cut tag `test-vectors-v2.0`), and the [cross-kernel agreement gate](https://github.com/sanning-io/proof/tree/main/cross-kernel) 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, vendored into this repo under [`cross-kernel/vendor-agent/`](https://github.com/sanning-io/proof/tree/main/cross-kernel/vendor-agent) so anyone can build and run it. The TypeScript and Python kernels are conformance-gated **byte-for-byte** in CI against the shared [`test-vectors` corpus](https://github.com/sanning-io/proof/tree/main/test-vectors) (per-file SHA-256 pins; current cut tag `test-vectors-v3.0`), and the [cross-kernel agreement gate](https://github.com/sanning-io/proof/tree/main/cross-kernel) 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 [public specs](https://github.com/sanning-io/proof/tree/main/specs) and the corpus will tell you if it's conformant.
 
 ## What this package deliberately does NOT do
 
+- **No I/O, ever.** Including in `gradePack`: it takes an account of what was disclosed, it does not go and read a directory. How a pack reached you is yours.
 - **Single-envelope scope.** Chain walking (`previous_hash`), checkpoint reconciliation, and gateway/transport logic are consumer-layer concerns composed above the kernel.
 - **Provenance is history, not endorsement.** A verified envelope proves *these bytes have this signed, anchored history* — never "safe," "approved," or "currently in production."
 - **Key identity is out-of-band.** The kernel proves the signature matches `env.public_key`; binding that key to a real-world identity is yours to establish.

package/dist/cli.js

@@ -13,8 +13,9 @@
 //   3  gateway-unavailable when an on-chain re-fetch was requested
 // `payloadHashOk === null` (a withheld record) is semantics-undetermined and
 // surfaces as a per-event note — it does NOT fail the run.
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile, readdir, stat, writeFile } from "node:fs/promises";
 import { realpathSync } from "node:fs";
+import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { isAgentProofSpec, verifyAgentProofBundle } from "./agent-proof.js";
 import { composeExport } from "./compose.js";
@@ -68,7 +69,7 @@ export async function runCli(argv, io) {
         printUsage(io);
         return EXIT_MALFORMED;
     }
-    // Pull the optional `--logs <file>` flag out of the args; the rest are
+    // Pull the optional `--logs <path>` flag out of the args; the rest are
     // positional (<bundle> [gateways]). --logs feeds disclosed raw-log bytes for
     // content verification (the evidence-bundle path only).
     let logsPath;
@@ -78,7 +79,7 @@ export async function runCli(argv, io) {
         if (a === "--logs") {
             const next = rest[i + 1];
             if (next === undefined) {
-                io.err("verify: --logs requires a file path");
+                io.err("verify: --logs requires a path (a logs directory, or a JSON map file)");
                 printUsage(io);
                 return EXIT_MALFORMED;
             }
@@ -98,34 +99,15 @@ export async function runCli(argv, io) {
         .split(",")
         .map((g) => g.trim())
         .filter((g) => g.length > 0);
-    let content;
+    let logs;
     if (logsPath !== undefined) {
-        let logsRaw;
-        try {
-            logsRaw = await readFile(logsPath, "utf8");
-        }
-        catch (e) {
-            io.err(`cannot read --logs ${logsPath}: ${e instanceof Error ? e.message : String(e)}`);
-            return EXIT_MALFORMED;
-        }
-        let logsParsed;
-        try {
-            logsParsed = JSON.parse(logsRaw);
-        }
-        catch (e) {
-            io.err(`--logs ${logsPath} is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
-            return EXIT_MALFORMED;
-        }
-        if (logsParsed === null || typeof logsParsed !== "object" || Array.isArray(logsParsed)) {
-            io.err(`--logs ${logsPath} must be a JSON object mapping event_id → disclosed bytes`);
+        logs = await loadLogs(logsPath, io);
+        if (logs === undefined)
             return EXIT_MALFORMED;
-        }
-        content = {};
-        for (const [k, v] of Object.entries(logsParsed)) {
-            if (typeof v === "string")
-                content[k] = decodeLogValue(v);
-        }
+        for (const n of logs.notes)
+            io.err(`note: ${n}`);
     }
+    const content = logs?.content;
     let raw;
     try {
         raw = await readFile(bundlePath, "utf8");
@@ -165,7 +147,12 @@ export async function runCli(argv, io) {
         ...(content ? { content } : {}),
         ...(io.fetchImpl ? { fetchImpl: io.fetchImpl } : {}),
     });
-    return reportEvidence(result, bundlePath, gateways, io);
+    const exit = reportEvidence(result, bundlePath, gateways, io);
+    // Coverage is reported only once the bundle parsed far enough to have events
+    // to compare against; over a MALFORMED bundle there is nothing to say.
+    if (logs && result.status !== "malformed")
+        reportLogsCoverage(logs, result, io);
+    return exit;
 }
 // `proof bundle <source-bundle.json> --attestations <f> --key <f> [-o <out>]`
 // (`proof export` still reaches this, undocumented — see the dispatch above.)
@@ -381,10 +368,187 @@ async function readExporterKey(path, io) {
     }
     return seed.toLowerCase();
 }
-// The --logs side-input lane decides each disclosed value's encoding: a clean,
+// The suffix the directory form reads, matched exactly — lowercase, which is
+// what `materializeBundle` writes. Anything else is skipped and NAMED rather
+// than guessed at, so a `.JSON` or extensionless file shows up as a note
+// instead of a mysteriously undisclosed event.
+const LOG_SUFFIX = ".json";
+// Which shape was passed is decided by `stat`, never by the extension: a pack's
+// log directory can be called anything, and `logs.json` is a legal directory
+// name. `stat` follows symlinks, so a symlinked logs directory works.
+async function loadLogs(logsPath, io) {
+    let isDirectory;
+    try {
+        isDirectory = (await stat(logsPath)).isDirectory();
+    }
+    catch (e) {
+        io.err(`cannot read --logs ${logsPath}: ${errMsg(e)}`);
+        return undefined;
+    }
+    return isDirectory ? loadLogsDirectory(logsPath, io) : loadLogsMap(logsPath, io);
+}
+// The JSON-map form, unchanged: `{ event_id: <hex | utf8 text> }`.
+async function loadLogsMap(logsPath, io) {
+    let logsRaw;
+    try {
+        logsRaw = await readFile(logsPath, "utf8");
+    }
+    catch (e) {
+        io.err(`cannot read --logs ${logsPath}: ${errMsg(e)}`);
+        return undefined;
+    }
+    let logsParsed;
+    try {
+        logsParsed = JSON.parse(logsRaw);
+    }
+    catch (e) {
+        io.err(`--logs ${logsPath} is not valid JSON: ${errMsg(e)}`);
+        return undefined;
+    }
+    if (logsParsed === null || typeof logsParsed !== "object" || Array.isArray(logsParsed)) {
+        io.err(`--logs ${logsPath} must be a JSON object mapping event_id → disclosed bytes, ` +
+            `or a directory of <event_id>${LOG_SUFFIX} files`);
+        return undefined;
+    }
+    const content = new Map();
+    const suppliedIds = [];
+    for (const [k, v] of Object.entries(logsParsed)) {
+        if (typeof v !== "string")
+            continue;
+        content.set(k, decodeLogValue(v));
+        suppliedIds.push(k);
+    }
+    return { content, suppliedIds, notes: [] };
+}
+// The directory form. Flat, one file per event, `<event_id>.json`.
+//
+// The decisions this pins, none of which is a verification failure — an absent
+// or unusable disclosure is UNDISCLOSED, and absence is not evidence of
+// tampering (evidence-bundle.md §5.1):
+//
+//   - a file whose name is not a known event id  → loaded, binds to nothing,
+//     named in a post-verify note (silence is how a typo'd filename becomes a
+//     mysteriously undisclosed event)
+//   - an event with no corresponding file        → undetermined (`~`), noted
+//   - an empty directory                         → valid; discloses nothing,
+//     noted, exit code unchanged
+//   - a subdirectory                             → skipped, never recursed,
+//     noted (this is the "you pointed at the pack root, not its logs/" case)
+//   - anything not named `<event_id>.json`, and anything that is not a regular
+//     file                                       → skipped, noted
+//
+// The one hard stop is a file we SELECTED but cannot read: we were pointed at
+// it, so a permissions error must not read as minimal disclosure. That exits 2.
+async function loadLogsDirectory(dirPath, io) {
+    let names;
+    try {
+        names = await readdir(dirPath);
+    }
+    catch (e) {
+        io.err(`cannot read --logs directory ${dirPath}: ${errMsg(e)}`);
+        return undefined;
+    }
+    const content = new Map();
+    const suppliedIds = [];
+    const skippedDirs = [];
+    const skippedNames = [];
+    for (const name of [...names].sort()) {
+        const p = join(dirPath, name);
+        let isDirectory;
+        let isFile;
+        try {
+            // `stat`, not the dirent kind: a symlinked log file is a log file, and a
+            // symlink to a directory is a directory.
+            const s = await stat(p);
+            isDirectory = s.isDirectory();
+            isFile = s.isFile();
+        }
+        catch (e) {
+            io.err(`cannot read --logs entry ${p}: ${errMsg(e)}`);
+            return undefined;
+        }
+        if (isDirectory) {
+            skippedDirs.push(name);
+            continue;
+        }
+        // Not a regular file (device, fifo, socket), or not named
+        // `<event_id>.json` — including a file named exactly `.json`, whose event
+        // id would be the empty string.
+        if (!isFile || !name.endsWith(LOG_SUFFIX) || name.length === LOG_SUFFIX.length) {
+            skippedNames.push(name);
+            continue;
+        }
+        const eventId = name.slice(0, -LOG_SUFFIX.length);
+        try {
+            // No encoding argument: bytes, exactly as they sit on disk. Copied out of
+            // Buffer's shared pool so the array handed to the verifier owns its own
+            // memory rather than a window onto a reused block.
+            content.set(eventId, new Uint8Array(await readFile(p)));
+        }
+        catch (e) {
+            io.err(`cannot read --logs file ${p}: ${errMsg(e)}`);
+            return undefined;
+        }
+        suppliedIds.push(eventId);
+    }
+    const notes = [];
+    if (skippedDirs.length > 0) {
+        notes.push(`--logs ${dirPath}: skipped ${count(skippedDirs.length, "subdirectory", "subdirectories")} ` +
+            `(${sample(skippedDirs)}) — the directory form reads <event_id>${LOG_SUFFIX} files ` +
+            `and does not recurse`);
+    }
+    if (skippedNames.length > 0) {
+        notes.push(`--logs ${dirPath}: skipped ${count(skippedNames.length, "entry", "entries")} ` +
+            `not named <event_id>${LOG_SUFFIX} (${sample(skippedNames)})`);
+    }
+    if (suppliedIds.length === 0) {
+        notes.push(`--logs ${dirPath} disclosed nothing (no <event_id>${LOG_SUFFIX} files) — every event ` +
+            `stays undisclosed, which is undetermined, not failed`);
+    }
+    return { content, suppliedIds, notes };
+}
+// What the side input covered, reported once the bundle's own event ids are
+// known. Both directions are ADVISORY — neither moves the verdict or the exit
+// code — and both exist because the silent version of each has already cost
+// somebody an afternoon:
+//
+//   - an entry matching no event binds to nothing. A typo'd id, or a directory
+//     scoped to a different bundle, otherwise looks identical to minimal
+//     disclosure.
+//   - an event whose content stayed undetermined disclosed no usable bytes.
+//     That is UNDISCLOSED, never a failure (evidence-bundle.md §5.1): absence
+//     of a disclosure is not evidence of tampering.
+function reportLogsCoverage(logs, result, io) {
+    const eventIds = new Set(result.events.map((e) => e.eventId));
+    const unmatched = logs.suppliedIds.filter((id) => !eventIds.has(id));
+    if (unmatched.length > 0) {
+        io.err(`note: --logs supplied ${count(unmatched.length, "entry", "entries")} matching no event ` +
+            `in the bundle, ignored: ${sample(unmatched)}`);
+    }
+    const undetermined = result.events.filter((e) => e.contentOk === null);
+    if (undetermined.length > 0) {
+        io.err(`note: ${undetermined.length} of ${result.events.length} event(s) have undetermined ` +
+            `content — no bytes disclosed, or no committed content_hash to bind them to. ` +
+            `Undisclosed, not failed: ${sample(undetermined.map((e) => e.eventId))}`);
+    }
+}
+function errMsg(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+function count(n, one, many) {
+    return `${n} ${n === 1 ? one : many}`;
+}
+// First few names, quoted, with a tail count — enough to recognise the mistake
+// without pasting a whole directory into the terminal.
+function sample(names, max = 3) {
+    const shown = names.slice(0, max).map((n) => JSON.stringify(n)).join(", ");
+    return names.length > max ? `${shown}, +${names.length - max} more` : shown;
+}
+// The --logs MAP lane decides each disclosed value's encoding: a clean,
 // even-length, lowercase-hex string is hex bytes; anything else is utf8 text.
 // (The verifier itself only distinguishes "string ⇒ hex" from "Uint8Array ⇒
-// raw bytes" — the human-facing encoding choice is made here.)
+// raw bytes" — the human-facing encoding choice is made here. The DIRECTORY
+// lane never reaches this: its bytes are already bytes.)
 function decodeLogValue(v) {
     if (v.length > 0 && v.length % 2 === 0 && /^[0-9a-f]+$/.test(v))
         return v; // hex passthrough
@@ -394,7 +558,7 @@ function printUsage(io) {
     io.out("Usage: npx @sanning/proof <command> [args]");
     io.out("");
     io.out("Commands:");
-    io.out("  verify <bundle.json> [gateways] [--logs <logs.json>]   Verify a bundle");
+    io.out("  verify <bundle.json> [gateways] [--logs <path>]        Verify a bundle");
     io.out("  bundle <source.json> --attestations <f> --key <f> [-o] Create an attested bundle");
     io.out("");
     io.out("Verify a sanning.evidence/v1 (sanning.anchor.trace/v1) bundle, an");
@@ -402,10 +566,21 @@ function printUsage(io) {
     io.out("inclusion bundle, fully offline. Supply a comma-separated gateway list");
     io.out("to also re-fetch each checkpoint on-chain.");
     io.out("");
-    io.out("--logs <logs.json>  Bind disclosed raw logs to each event's committed");
-    io.out("                    content_hash. JSON object mapping event_id → bytes");
-    io.out("                    (even-length lowercase hex ⇒ hex, else utf8 text).");
-    io.out("                    In-body events[].content is verified automatically.");
+    io.out("--logs <path>       Bind disclosed raw logs to each event's committed");
+    io.out("                    content_hash. Either shape works, and which one you");
+    io.out("                    passed is decided by stat(), not by the extension:");
+    io.out("");
+    io.out("                      a DIRECTORY of <event_id>.json files — the file's");
+    io.out("                      raw bytes ARE the content, nothing is decoded.");
+    io.out("                      This is a materialized pack's logs/ directory:");
+    io.out("                        proof verify <pack>/bundle.json --logs <pack>/logs");
+    io.out("");
+    io.out("                      a JSON FILE mapping event_id → bytes (an");
+    io.out("                      even-length lowercase-hex value ⇒ hex, else utf8).");
+    io.out("");
+    io.out("                    In-body events[].content is verified automatically");
+    io.out("                    and takes precedence. An event with no disclosed");
+    io.out("                    bytes is undetermined (~), never a failure.");
     io.out("");
     io.out("Exit codes: 0 verified · 1 failed · 2 malformed · 3 gateway-unavailable");
 }
@@ -424,7 +599,7 @@ function reportEvidence(result, path, gateways, io) {
         io.out(paint("  Checkpoints", DIM));
         for (const cp of result.checkpoints) {
             const onChain = cp.onChainOk === null ? "" : `  on-chain ${mark(cp.onChainOk)}`;
-            io.out(`    ${mark(cp.ok)} ${shortTx(cp.txId)}  envelope ${mark(cp.envelopeOk)}  root ${mark(cp.merkleRootOk)}${onChain}`);
+            io.out(`    ${mark(cp.ok)} ${shortTx(cp.checkpointRef)}  envelope ${mark(cp.envelopeOk)}  root ${mark(cp.merkleRootOk)}${onChain}`);
             for (const e of cp.errors)
                 io.out(paint(`        - ${e}`, R));
         }

package/dist/compose.js

@@ -41,7 +41,7 @@ export function attestationSignatureToHex(signature) {
 }
 // Normalize one attestation record for embedding: deep-clone (never mutate the
 // caller's input) and transcode its signature to lowercase hex. Everything else
-// — payload, public_key, signature_alg, checkpoint_tx_id — rides verbatim so the
+// — payload, public_key, signature_alg, checkpoint_ref — rides verbatim so the
 // operator's RSA-PSS signature over JCS(payload) remains valid.
 function normalizeAttestation(rec) {
     const cloned = JSON.parse(JSON.stringify(rec));

package/dist/evidence.d.ts

@@ -1,5 +1,16 @@
 import type { Envelope } from "./types.js";
-export declare const ANCHOR_TRACE_BODY_TYPE = "sanning.anchor.trace/v1";
+export declare const ANCHOR_TRACE_BODY_TYPE = "sanning.anchor.trace/v2";
+/**
+ * The frozen pre-`anchor_ref` body (evidence-bundle.md §5.1.3).
+ *
+ * Accepted PERMANENTLY, not for a deprecation window. Every bundle emitted
+ * before 2026-09-03 carries this shape, and those bundles are evidence — a
+ * reader that stopped accepting them would destroy the record it exists to
+ * defend (DL-30). Nothing new emits it.
+ */
+export declare const ANCHOR_TRACE_BODY_TYPE_V1 = "sanning.anchor.trace/v1";
+/** Every anchor-trace body this kernel verifies. Order is newest-first. */
+export declare const ANCHOR_TRACE_BODY_TYPES: readonly ["sanning.anchor.trace/v2", "sanning.anchor.trace/v1"];
 export declare const EXPORT_BODY_TYPE = "sanning.evidence.export/v1";
 export interface EvidenceIssuer {
     kind: string;
@@ -15,7 +26,42 @@ export interface EvidenceVerdict {
     as_of?: string;
     [k: string]: unknown;
 }
+/**
+ * Where a commitment was witnessed (evidence-bundle.md §5.1.1).
+ *
+ * The same three-part shape the control plane indexes (`kind` / one promoted
+ * `id` / a typed remainder), so the signed body, the index row and the SDK
+ * artifact stop being three vocabularies for one fact.
+ *
+ * NOT ONE FIELD HERE NAMES A CHAIN. Arweave's chunk proof, data_path, offsets
+ * and packing live in `ref`, opaque to every reader above this seam. A field
+ * that would need renaming for a second witness belongs in `ref` by definition.
+ */
+export interface AnchorRef {
+    kind: string;
+    id: string;
+    ref?: Record<string, unknown>;
+}
 export interface TraceCheckpoint {
+    /**
+     * The checkpoint's identity and the join key, DERIVED: hex SHA-256 of the
+     * decoded `record_bytes`. Recomputed by the verifier — in v1 this was an
+     * asserted label matched against another asserted label, so a producer could
+     * relabel a checkpoint and the bundle still verified.
+     */
+    checkpoint_ref: string;
+    /**
+     * Where it was witnessed, IF IT HAS BEEN. Optional, and absent is honest:
+     * under DL-52 a checkpoint is routinely placed before it is witnessed, and a
+     * required field that must be filled dishonestly is a defect in the format.
+     */
+    anchor_ref?: AnchorRef;
+    envelope: Envelope;
+    record_bytes: string;
+    merkle_root: string;
+}
+/** The frozen `sanning.anchor.trace/v1` checkpoint (§5.1.3). Read, never written. */
+export interface TraceCheckpointV1 {
     tx_id: string;
     envelope: Envelope;
     record_bytes: string;
@@ -26,7 +72,8 @@ export interface TraceInclusion {
     leaf_index: number;
     leaf_count: number;
     audit_path: string[];
-    checkpoint_tx_id: string;
+    /** Resolves against `checkpoints[].checkpoint_ref`. v1 spells this `checkpoint_tx_id`. */
+    checkpoint_ref: string;
 }
 export interface TraceEvent {
     envelope: Envelope;
@@ -66,7 +113,25 @@ export interface OnChainResult {
     perGateway: PerGatewayOutcome[];
 }
 export interface CheckpointResult {
-    txId: string;
+    /**
+     * The checkpoint's join key AS THE BUNDLE SPELLS IT — the derived
+     * `checkpoint_ref` for a v2 body, the legacy `tx_id` for a frozen v1 body.
+     * Never re-derived across forms: a v1 bundle's key is its `tx_id`, because
+     * that is what its own events resolve against and what an attestation
+     * written against it carries.
+     */
+    checkpointRef: string;
+    /**
+     * Where this checkpoint was witnessed, normalised to one shape.
+     *
+     * `null` when a v2 checkpoint carries no `anchor_ref` — placed but not yet
+     * witnessed, which is a normal state and NOT a deficiency. For a frozen v1
+     * checkpoint this is synthesised as `{ kind: "arweave", id: tx_id }`, which
+     * is exactly what v1's spec said the field was ("the Arweave TX the
+     * checkpoint envelope was anchored as"). The synthesis is reader-side only
+     * and never re-enters a signed artifact or a verdict.
+     */
+    anchorRef: AnchorRef | null;
     envelopeOk: boolean;
     merkleRootOk: boolean;
     onChainOk: boolean | null;
@@ -98,7 +163,12 @@ export interface EvidenceBundleResult {
     errors: string[];
 }
 export interface AttestationRecord {
-    checkpoint_tx_id: string;
+    /**
+     * The source checkpoint this attestation binds to, spelled in the SOURCE
+     * bundle's vocabulary: `checkpoint_ref` for a v2 source, the legacy `tx_id`
+     * for a frozen v1 one. Not re-derived across forms.
+     */
+    checkpoint_ref: string;
     payload: AttestationPayload;
     signature_alg: string;
     public_key: {
@@ -158,7 +228,7 @@ export interface VerdictAttestation {
     subject_ref_ok: boolean | null;
 }
 export interface VerdictCheckpoint {
-    checkpoint_tx_id: string;
+    checkpoint_ref: string;
     merkle_root_ok: boolean;
     on_chain: VerdictOnChain | null;
     attestations: VerdictAttestation[];
@@ -179,7 +249,7 @@ export interface VerdictObject {
     [k: string]: unknown;
 }
 export interface AttestationResult {
-    checkpointTxId: string;
+    checkpointRef: string;
     operator: string;
     gateway: string | null;
     signatureOk: boolean;
@@ -201,7 +271,7 @@ export interface ExportResult {
 }
 export interface VerifyEvidenceOptions {
     gateways?: string[];
-    content?: Record<string, Uint8Array | string>;
+    content?: Record<string, Uint8Array | string> | ReadonlyMap<string, Uint8Array | string>;
     fetchImpl?: typeof fetch;
 }
 export declare function verifyEvidenceBundle(bundle: unknown, options?: VerifyEvidenceOptions): Promise<EvidenceBundleResult>;