@sanning/proof 0.5.0 → 0.7.0

package/dist/cli.js

@@ -13,10 +13,12 @@
 //   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 { CHAIN_READING_SCOPE, readChains, renderChainFinding } from "./chain.js";
 import { composeExport } from "./compose.js";
 import { utf8 } from "./crypto.js";
 import { verifyEvidenceBundle } from "./evidence.js";
@@ -68,7 +70,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 +80,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 +100,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 +148,17 @@ export async function runCli(argv, io) {
         ...(content ? { content } : {}),
         ...(io.fetchImpl ? { fetchImpl: io.fetchImpl } : {}),
     });
-    return reportEvidence(result, bundlePath, gateways, io);
+    // Read the chains from the SAME parsed bundle the verifier saw. Findings are
+    // evidence about the records in front of us, not a verdict: they are printed
+    // and they never move `exit`, because a chain is not a completeness proof and
+    // an exit code is exactly the kind of thing people read as one.
+    const chains = await readChains(parsed);
+    const exit = reportEvidence(result, bundlePath, gateways, io, chains);
+    // 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 +374,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 +564,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,14 +572,25 @@ 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");
 }
-function reportEvidence(result, path, gateways, io) {
+function reportEvidence(result, path, gateways, io, chains) {
     if (result.status === "malformed") {
         io.err(paint("MALFORMED", R) + `  ${path}`);
         for (const e of result.errors)
@@ -424,7 +605,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));
         }
@@ -445,6 +626,7 @@ function reportEvidence(result, path, gateways, io) {
                 io.out(paint(`        - ${e}`, R));
         }
     }
+    reportChains(chains, io);
     if (result.export) {
         reportExport(result.export, io);
     }
@@ -459,6 +641,39 @@ function reportEvidence(result, path, gateways, io) {
     }
     return mapStatusToExit(result.status, result.errors);
 }
+/**
+ * The chain block: what following each record's pointer to the record before it
+ * showed, over the records THIS bundle presents.
+ *
+ * Three deliberate choices, all of them about not overclaiming.
+ *
+ * 1. It prints the chains it READ, not just the findings. "3 chains, nothing to
+ *    report" and silence are different statements, and a reader that quietly
+ *    matched no records at all would produce the second one while covering
+ *    nothing.
+ * 2. It prints the scope sentence whenever it read a chain, findings or not.
+ *    "Delete an event and the next pointer dangles" is true; "so the bundle is
+ *    complete" does not follow, and two customer-facing documents had already
+ *    made that leap. The limit travels with the result or it gets dropped.
+ * 3. It does not touch the exit code. Findings are evidence; the exit code is
+ *    the verdict surface, and the pinned 0/1/2/3 contract stays exactly what it
+ *    was. A dangling link is something for a person to look at, not a machine
+ *    decision this check is entitled to make.
+ */
+function reportChains(reading, io) {
+    if (reading.chains.length === 0)
+        return;
+    io.out("");
+    io.out(paint("  Event chains", DIM));
+    for (const c of reading.chains) {
+        const where = c.namespace === undefined ? "record" : `${c.namespace} metadata`;
+        io.out(paint(`    ${c.chainKey}  ${count(c.events, "record", "records")} present  (linked in ${where})`, DIM));
+    }
+    for (const f of reading.findings) {
+        io.out(paint(`    ! ${renderChainFinding(f, "this bundle")}`, Y));
+    }
+    io.out(paint(`    ${CHAIN_READING_SCOPE}`, DIM));
+}
 // Render the export-specific block (evidence-export.md §5): source-bundle
 // linkage, cached-vs-recomputed verdict agreement, and each embedded operator
 // attestation (RSA-PSS sig · operator-address binding · data_hash binding).

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,6 +1,42 @@
 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";
+/**
+ * The Sanning-signed interval stamp body (evidence-bundle.md §5.2, DL-58).
+ *
+ * Its own `body_type` rather than a widened anchor-trace body, and the reason
+ * is the whole decision: an anchor-trace checkpoint carries a PRODUCER-signed
+ * `sanning.events/v1` envelope, and a stamp has no producer signature at all —
+ * Sanning places it, under DL-52, for a customer who holds no chain identity.
+ * The two rejected options were making `envelope` optional and synthesising an
+ * envelope that Sanning signs; the second would have made a Sanning
+ * attestation indistinguishable ON THE WIRE from a producer's, which is
+ * unrecoverable once witnessed.
+ */
+export declare const STAMP_TRACE_BODY_TYPE = "sanning.stamp.trace/v1";
+/**
+ * The version string INSIDE a witnessed stamp body — a different string from
+ * the `body_type` above, and the two are easy to confuse.
+ *
+ * `sanning.stamp.trace/v1` discriminates the BUNDLE BODY: it is the reader's
+ * dispatch key. `sanning.stamp/v1` is the control plane's own version of the
+ * bytes it hands a witness (`control-plane/src/stamp-tree.ts`,
+ * `STAMP_BODY_VERSION`). A `sanning.stamp.trace/v1` body pins the inner
+ * version to exactly this value: two answers to one question inside one
+ * signature is the §5.1.2 mixed-vocabulary reject, one layer down.
+ */
+export declare const STAMP_BODY_VERSION = "sanning.stamp/v1";
 export interface EvidenceIssuer {
     kind: string;
     tenant_id?: string;
@@ -15,7 +51,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 +97,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;
@@ -38,6 +110,58 @@ export interface AnchorTraceBody {
     checkpoints: TraceCheckpoint[];
     events: TraceEvent[];
 }
+/**
+ * One sub-tree of a stamp, as the WITNESSED bytes carry it.
+ *
+ * Keyed in the body by a blinded reference (an HMAC under a per-org secret we
+ * never publish), so a reader learns that the org runs N agents and their
+ * relative volumes and learns no name. The RANGE is deliberately in the clear:
+ * it is what makes a later per-agent slice claim checkable by a third party
+ * without Sanning, and hiding it would put us back in the trust path.
+ */
+export interface StampSubtree {
+    first_leaf: number;
+    leaf_count: number;
+    /** Hex RFC-9162 root over this sub-tree's leaves alone. */
+    root: string;
+}
+/**
+ * The stamp body as the control plane witnesses it
+ * (`control-plane/src/stamp-tree.ts`, `StampBody`).
+ *
+ * Never read from the bundle directly — it is parsed out of `stamp_bytes`,
+ * which is the only authority. Present as a type so the parse has a shape.
+ */
+export interface StampBody {
+    stamp_version: string;
+    /** The org, BLINDED. Not an org id, and not reversible without the secret. */
+    org_ref: string;
+    interval_start: string;
+    interval_end: string;
+    merkle_root: string;
+    leaf_count: number;
+    subtrees: Record<string, StampSubtree>;
+}
+/** One entry of a `sanning.stamp.trace/v1` body's `stamps[]` (§5.2). */
+export interface StampEntry {
+    /**
+     * The stamp's identity within this bundle, DERIVED: hex SHA-256 of the
+     * DECODED `stamp_bytes`, not of the hex text. A verifier MUST recompute it.
+     */
+    stamp_ref: string;
+    /** Lowercase hex of the exact JCS bytes that were handed to the witness. */
+    stamp_bytes: string;
+    /**
+     * Where the stamp was witnessed, IF IT HAS BEEN (§5.1.1). Absent is honest:
+     * a sealed-but-unconfirmed stamp is witnessed by nobody, and an emitter that
+     * filled this in from a submission receipt would be claiming a chain
+     * position that does not exist yet.
+     */
+    anchor_ref?: AnchorRef;
+}
+export interface StampTraceBody {
+    stamps: StampEntry[];
+}
 export interface EvidenceBundle {
     spec_version: string;
     body_type: string;
@@ -66,7 +190,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;
@@ -84,6 +226,54 @@ export interface EventResult {
     ok: boolean;
     errors: string[];
 }
+/** One sub-tree's recomputed result (§5.2). */
+export interface StampSubtreeResult {
+    /** The blinded key the body spells it under. Meaningless without the org's secret. */
+    ref: string;
+    firstLeaf: number;
+    leafCount: number;
+    root: string;
+}
+/** One `stamps[]` entry's result (§5.2). */
+export interface StampResult {
+    /** The stamp's derived identity, as the bundle spells it. "" when unusable. */
+    stampRef: string;
+    /** The asserted `stamp_ref` equals SHA-256 of the decoded `stamp_bytes`. */
+    stampRefOk: boolean;
+    /**
+     * The witnessed bytes decoded, parsed, and re-canonicalized to themselves.
+     *
+     * The last clause is not pedantry. The plane stores these bytes as TEXT and
+     * replays them verbatim precisely because a round-trip through a normalizing
+     * serializer is not guaranteed to reproduce what was signed; a body that is
+     * not JCS-canonical is one that every re-deriving reader hashes differently.
+     */
+    bodyOk: boolean;
+    stampVersion: string | null;
+    intervalStart: string | null;
+    intervalEnd: string | null;
+    merkleRoot: string | null;
+    leafCount: number | null;
+    /**
+     * Every sub-tree range accounts for exactly one leaf of the stamp: the
+     * ranges sorted by `first_leaf` tile `[0, leaf_count)` with no gap and no
+     * overlap, and their counts sum to `leaf_count`.
+     */
+    subtreesOk: boolean;
+    subtrees: StampSubtreeResult[];
+    /**
+     * Where it was witnessed, or `null` for a stamp nothing has witnessed yet.
+     *
+     * `null` is NOT a failure and never an accusation — it is the honest state
+     * of every stamp for the first minutes of its life and the permanent state
+     * of every stamp when no witness is configured. It does hold the bundle at
+     * `partial`: a stamp is Sanning's own assertion until something independent
+     * carries it.
+     */
+    anchorRef: AnchorRef | null;
+    ok: boolean;
+    errors: string[];
+}
 export interface EvidenceBundleResult {
     status: EvidenceStatus;
     specVersionOk: boolean;
@@ -95,10 +285,16 @@ export interface EvidenceBundleResult {
     events: EventResult[];
     assertedStatus: string | null;
     export?: ExportResult;
+    stamps?: StampResult[];
     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 +354,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 +375,7 @@ export interface VerdictObject {
     [k: string]: unknown;
 }
 export interface AttestationResult {
-    checkpointTxId: string;
+    checkpointRef: string;
     operator: string;
     gateway: string | null;
     signatureOk: boolean;
@@ -201,7 +397,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>;
@@ -234,6 +430,7 @@ export interface DisclosedContentResult {
  * know their payload is text decode it themselves and own that assumption.
  */
 export declare function disclosedContent(bundle: unknown, options?: VerifyEvidenceOptions): Promise<DisclosedContentResult>;
+export declare function resolveTraceEvents(bundle: unknown): TraceEvent[] | undefined;
 export interface ComposeVerdictResult {
     verdict: VerdictObject;
     sourceStatus: EvidenceStatus;