@sanning/proof 0.4.1 → 0.6.0

package/src/evidence.ts

@@ -32,6 +32,11 @@ import {
   jcs,
   verifyEnvelope,
 } from "./verifier.js";
+import {
+  inBodyContentOffered,
+  sideContentEntry,
+  type SideEntry,
+} from "./side-content.js";
 import type { Envelope } from "./types.js";
 
 // Only the evidence-bundle major(s) this kernel verifies. A new major is a
@@ -43,7 +48,23 @@ const ACCEPTED_EVIDENCE_MAJORS = ["sanning.evidence/v1"];
 // body_type is not a hard failure of the WRAPPER (the signature + body_hash
 // still verify), but its body cannot be re-derived, so the per-body verdict is
 // "undetermined" rather than "verified".
-export const ANCHOR_TRACE_BODY_TYPE = "sanning.anchor.trace/v1";
+export 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 const ANCHOR_TRACE_BODY_TYPE_V1 = "sanning.anchor.trace/v1";
+
+/** Every anchor-trace body this kernel verifies. Order is newest-first. */
+export const ANCHOR_TRACE_BODY_TYPES = [
+  ANCHOR_TRACE_BODY_TYPE,
+  ANCHOR_TRACE_BODY_TYPE_V1,
+] as const;
 
 // The issuer-composed attested-evidence-export body (specs/evidence-export.md
 // §2). The wrapper is unchanged (`sanning.evidence/v1`, Ed25519-signed); this body
@@ -70,20 +91,58 @@ export interface EvidenceVerdict {
   [k: string]: unknown;
 }
 
-// `sanning.anchor.trace/v1` body (§5.1). Uint8Array fields ride as lowercase hex.
+/**
+ * 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>;
+}
+
+// `sanning.anchor.trace/v2` body (§5.1). Uint8Array fields ride as lowercase hex.
 export interface TraceCheckpoint {
-  tx_id: string;
+  /**
+   * 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; // hex of JCS(checkpoint record)
   merkle_root: string; // hex
 }
 
+/** The frozen `sanning.anchor.trace/v1` checkpoint (§5.1.3). Read, never written. */
+export interface TraceCheckpointV1 {
+  tx_id: string;
+  envelope: Envelope;
+  record_bytes: string;
+  merkle_root: string;
+}
+
 export interface TraceInclusion {
   leaf_hash: string; // hex
   leaf_index: number;
   leaf_count: number;
   audit_path: string[]; // hex[]
-  checkpoint_tx_id: string;
+  /** Resolves against `checkpoints[].checkpoint_ref`. v1 spells this `checkpoint_tx_id`. */
+  checkpoint_ref: string;
 }
 
 export interface TraceEvent {
@@ -127,7 +186,7 @@ export type EvidenceStatus =
   | "malformed"; // structurally unparseable / unknown major / body_hash mismatch
 
 // Per-gateway on-chain outcome for one checkpoint tx (evidence-export.md §4.2).
-// The on-chain re-fetch resolves each checkpoint_tx_id against EACH configured
+// The on-chain re-fetch resolves each checkpoint's anchor_ref.id against EACH configured
 // gateway and records that gateway's individual outcome:
 //   confirm     — the gateway returned the tx and its bytes match the record.
 //   mismatch    — the gateway returned the tx but its bytes disagree — a finding.
@@ -151,7 +210,25 @@ export interface OnChainResult {
 }
 
 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;
   // The checkpoint envelope verified (signature + payload binding to its record).
   envelopeOk: boolean;
   // The committed record's merkle_root equals the checkpoint's claimed merkle_root.
@@ -176,7 +253,7 @@ export interface EventResult {
   payloadBindingOk: boolean | null;
   // RFC 9162 inclusion of this event's leaf in its checkpoint's root.
   inclusionOk: boolean;
-  // The inclusion's checkpoint_tx_id resolved to a checkpoint in the bundle.
+  // The inclusion's checkpoint_ref resolved to a checkpoint in the bundle.
   checkpointBound: boolean;
   // Raw-log (content) binding: SHA-256 of the disclosed bytes equals the
   // committed event.content_hash (in record_bytes) — or, for a promoted
@@ -215,7 +292,12 @@ export interface EvidenceBundleResult {
 // One embedded operator attestation record (§2.2 / §3). RSA-PSS-SHA-256 over
 // JCS(payload); the operator key is the operator's Arweave RSA wallet.
 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; // "rsa-pss-sha256"
   public_key: { kty: "RSA"; n: string; e: string };
@@ -281,7 +363,7 @@ export interface VerdictAttestation {
 }
 
 export interface VerdictCheckpoint {
-  checkpoint_tx_id: string;
+  checkpoint_ref: string;
   merkle_root_ok: boolean;
   on_chain: VerdictOnChain | null;
   attestations: VerdictAttestation[];
@@ -300,7 +382,7 @@ export interface VerdictObject {
 }
 
 export interface AttestationResult {
-  checkpointTxId: string;
+  checkpointRef: string;
   operator: string;
   gateway: string | null;
   // The RSA-PSS-SHA-256 signature over JCS(payload) verified (§5 step 6a).
@@ -310,7 +392,7 @@ export interface AttestationResult {
   // payload.data_hash == the resolved source checkpoint's committed content hash
   // (SHA-256(JCS(checkpoint.envelope))) (§5 step 6c).
   dataHashBound: boolean;
-  // checkpoint_tx_id resolved to a present source checkpoint.
+  // checkpoint_ref resolved to a present source checkpoint.
   checkpointResolved: boolean;
   level: number | null;
   // subject_ref (§3.2) tri-state: null absent/undetermined, true/false only
@@ -340,7 +422,7 @@ export interface ExportResult {
 }
 
 export interface VerifyEvidenceOptions {
-  // Gateways to re-fetch each checkpoint_tx_id from (first responsive wins).
+  // Gateways to re-fetch each anchor_ref.id from (first responsive wins).
   // When supplied, the on-chain bytes MUST byte-match the bundle's checkpoint
   // envelope, proving the proof is anchored, not just locally asserted.
   gateways?: string[];
@@ -349,7 +431,15 @@ export interface VerifyEvidenceOptions {
   // Uint8Array is used as-is; a string is parsed as lowercase hex. In-body
   // `events[].content` (signed) takes precedence over this side input; if both
   // are present for an event and disagree, the event fails (§5.1).
-  content?: Record<string, Uint8Array | string>;
+  //
+  // A `Map` is the SAFE shape and the one to prefer — it is what
+  // `disclosedContent` hands back, so our output feeds straight back in, and a
+  // Map keys on the string itself: no prototype to inherit from and no
+  // `__proto__` write that silently lands somewhere else. The plain `Record` is
+  // still accepted (it was the original signature and remains supported), and
+  // the lookup guards it — see `lookupSideContent`. Widening is additive: every
+  // existing caller passing a Record keeps working unchanged.
+  content?: Record<string, Uint8Array | string> | ReadonlyMap<string, Uint8Array | string>;
   // Injectable fetch (Node >=18 global `fetch` by default) — test seam.
   fetchImpl?: typeof fetch;
 }
@@ -482,13 +572,13 @@ export async function verifyEvidenceBundle(
     return verifyExportBody(b, specVersionOk, assertedStatus, errors, options);
   }
 
-  if (bodyType !== ANCHOR_TRACE_BODY_TYPE) {
+  if (bodyType !== ANCHOR_TRACE_BODY_TYPE && bodyType !== ANCHOR_TRACE_BODY_TYPE_V1) {
     // The wrapper is authentic but we don't know this body's structure. Per
     // wrap-don't-merge, that is "partial" (cryptographically sound wrapper,
     // body verdict undetermined) — not a failure.
     errors.push(
       `body_type ${JSON.stringify(bodyType)} is not verifiable by this kernel ` +
-        `(only ${ANCHOR_TRACE_BODY_TYPE}); wrapper verified, body undetermined`,
+        `(only ${ANCHOR_TRACE_BODY_TYPES.join(", ")}); wrapper verified, body undetermined`,
     );
     return {
       status: "partial",
@@ -507,6 +597,158 @@ export async function verifyEvidenceBundle(
   return verifyAnchorTrace(b, bodyType, specVersionOk, assertedStatus, errors, options);
 }
 
+/**
+ * Index a source bundle's checkpoints by the key its attestations will use.
+ *
+ * The attestation join key follows the SOURCE bundle's own vocabulary — a
+ * v2 source is keyed by `checkpoint_ref`, a frozen v1 source by `tx_id`. The
+ * alternative (always deriving a v2-style key) would silently un-resolve every
+ * attestation ever written against a v1 export: `data_hash_bound` would go
+ * false, the export would stop reaching `verified`, and nothing would say why.
+ */
+async function indexSourceCheckpoints(
+  bundle: EvidenceBundle,
+): Promise<Map<string, AnyTraceCheckpoint>> {
+  const out = new Map<string, AnyTraceCheckpoint>();
+  const sb = bundle.body as AnchorTraceBody | undefined;
+  const isV1 = bundle.body_type === ANCHOR_TRACE_BODY_TYPE_V1;
+  if (!sb || typeof sb !== "object" || !Array.isArray(sb.checkpoints)) return out;
+  for (const cp of sb.checkpoints as AnyTraceCheckpoint[]) {
+    if (!cp || typeof cp !== "object") continue;
+    let recordBytes: Uint8Array | undefined;
+    try {
+      if (typeof cp.record_bytes === "string") recordBytes = hexToBytes(cp.record_bytes);
+    } catch {
+      recordBytes = undefined;
+    }
+    const keyed = await resolveCheckpointKey(cp, recordBytes, isV1);
+    if (keyed.key !== null && !out.has(keyed.key)) out.set(keyed.key, cp);
+  }
+  return out;
+}
+
+/** Either shape of checkpoint, before the form is resolved. */
+type AnyTraceCheckpoint = Partial<TraceCheckpoint> & Partial<TraceCheckpointV1>;
+
+/**
+ * Resolve a checkpoint's join key and its witness reference, for whichever
+ * body form we are reading.
+ *
+ * ── The rule that matters, and why it is a reject rather than a preference ──
+ *
+ * A checkpoint carrying BOTH vocabularies is two answers to one question
+ * inside one signature. A reader that silently prefers one gives a different
+ * answer from a reader that prefers the other, over the same signed bytes —
+ * and both look like they verified. So a v2 body carrying `tx_id`, or a v1
+ * body carrying `anchor_ref`/`checkpoint_ref`, is rejected rather than
+ * resolved. This is cheap to enforce here and impossible to enforce later.
+ *
+ * ── Why v2's key is recomputed ──
+ *
+ * In v1 the key was an asserted label matched against another asserted label;
+ * nothing tied either to the bytes, so relabelling a checkpoint and every
+ * event pointing at it left a bundle that still verified. In v2 the key IS the
+ * bytes, so the same relabel fails here. v1's behaviour is preserved exactly
+ * as it was — deliberately, because those bundles are already signed and
+ * re-interpreting them is not backwards compatibility.
+ */
+async function resolveCheckpointKey(
+  cp: AnyTraceCheckpoint,
+  recordBytes: Uint8Array | undefined,
+  isV1: boolean,
+): Promise<{ key: string | null; anchorRef: AnchorRef | null; errors: string[] }> {
+  const errors: string[] = [];
+
+  if (isV1) {
+    if (cp.checkpoint_ref !== undefined || cp.anchor_ref !== undefined) {
+      errors.push(
+        "sanning.anchor.trace/v1 checkpoint carries v2 fields (checkpoint_ref/anchor_ref) — " +
+          "one bundle speaks one vocabulary",
+      );
+      return { key: null, anchorRef: null, errors };
+    }
+    if (typeof cp.tx_id !== "string" || cp.tx_id === "") {
+      errors.push("checkpoint missing tx_id");
+      return { key: null, anchorRef: null, errors };
+    }
+    // v1's tx_id IS an Arweave transaction — its own spec said so. Surfacing it
+    // through the same shape as v2 gives ONE reader-side vocabulary without
+    // touching a byte of the signed bundle.
+    return { key: cp.tx_id, anchorRef: { kind: "arweave", id: cp.tx_id }, errors };
+  }
+
+  if (cp.tx_id !== undefined) {
+    errors.push(
+      "sanning.anchor.trace/v2 checkpoint carries legacy tx_id — one bundle speaks one vocabulary",
+    );
+    return { key: null, anchorRef: null, errors };
+  }
+  if (typeof cp.checkpoint_ref !== "string" || cp.checkpoint_ref === "") {
+    errors.push("checkpoint missing checkpoint_ref");
+    return { key: null, anchorRef: null, errors };
+  }
+  if (recordBytes === undefined) {
+    // Without the bytes the key cannot be recomputed, so it cannot be trusted.
+    errors.push("checkpoint_ref cannot be verified — record_bytes missing or not hex");
+    return { key: null, anchorRef: null, errors };
+  }
+  const derived = await sha256Hex(recordBytes);
+  if (derived !== cp.checkpoint_ref.toLowerCase()) {
+    errors.push(
+      `checkpoint_ref does not match SHA-256(record_bytes): claimed=${cp.checkpoint_ref} derived=${derived}`,
+    );
+    return { key: null, anchorRef: null, errors };
+  }
+
+  const anchorRef = parseAnchorRef(cp.anchor_ref, errors);
+  return { key: derived, anchorRef, errors };
+}
+
+/**
+ * Validate an optional `anchor_ref` (§5.1.1).
+ *
+ * ── An unrecognised `kind` is NOT a failure, and that is the point ──
+ *
+ * The offline verdict — signatures, payload binding, Merkle inclusion — is
+ * computed with no witness access at all. A reader that cannot resolve a
+ * witness has therefore learned NOTHING about whether the evidence was
+ * altered, and must not say otherwise. The shipped issuer did the opposite:
+ * an unrecognised signature type returned `false` rather than `null`, mapped
+ * to `tampered`, and was cached as permanent — a false accusation, produced
+ * by a coverage gap, for a company whose product is telling people whether
+ * records were altered.
+ *
+ * So this validates the SHAPE and never the vocabulary. A malformed
+ * `anchor_ref` is a defect in the bundle; an unknown `kind` is a defect in
+ * the reader, and only the first is the bundle's fault.
+ */
+function parseAnchorRef(raw: unknown, errors: string[]): AnchorRef | null {
+  if (raw === undefined || raw === null) return null; // placed, not yet witnessed
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    errors.push("anchor_ref must be an object");
+    return null;
+  }
+  const o = raw as Record<string, unknown>;
+  if (typeof o.kind !== "string" || !/^[a-z0-9][a-z0-9._-]*$/.test(o.kind)) {
+    errors.push(`anchor_ref.kind is missing or malformed: ${JSON.stringify(o.kind)}`);
+    return null;
+  }
+  if (typeof o.id !== "string" || o.id === "") {
+    errors.push("anchor_ref.id is missing or empty");
+    return null;
+  }
+  const ref = o.ref;
+  if (ref !== undefined && (typeof ref !== "object" || ref === null || Array.isArray(ref))) {
+    errors.push("anchor_ref.ref must be an object when present");
+    return null;
+  }
+  return {
+    kind: o.kind,
+    id: o.id,
+    ...(ref === undefined ? {} : { ref: ref as Record<string, unknown> }),
+  };
+}
+
 async function verifyAnchorTrace(
   b: EvidenceBundle,
   bodyType: string,
@@ -516,40 +758,55 @@ async function verifyAnchorTrace(
   options: VerifyEvidenceOptions,
 ): Promise<EvidenceBundleResult> {
   const body = b.body as AnchorTraceBody;
+  const isV1 = bodyType === ANCHOR_TRACE_BODY_TYPE_V1;
   if (!Array.isArray(body.checkpoints) || !Array.isArray(body.events)) {
-    return malformed("sanning.anchor.trace/v1 body must have checkpoints[] and events[]", true);
+    return malformed(`${bodyType} body must have checkpoints[] and events[]`, true);
   }
 
   const gateways = options.gateways ?? [];
   const onChainChecked = gateways.length > 0;
 
   // --- Step 3: per-checkpoint -------------------------------------------------
-  const byTxId = new Map<string, TraceCheckpoint>();
+  //
+  // ── Why the join key is resolved BEFORE anything else ──
+  //
+  // `byKey` is what binds an event to the root its inclusion proof is checked
+  // against. Get it wrong and an event proves inclusion in a tree it was never
+  // in — the one failure in this file that produces a WRONG VERIFIED, not a
+  // failed verify. Everything below is downstream of it.
+  const byKey = new Map<string, AnyTraceCheckpoint>();
+  const anchorByKey = new Map<string, AnchorRef | null>();
   const checkpointResults: CheckpointResult[] = [];
-  for (const cp of body.checkpoints) {
+  for (const cp of body.checkpoints as AnyTraceCheckpoint[]) {
     const cpErrors: string[] = [];
     let envelopeOk = false;
     let merkleRootOk = false;
 
-    if (typeof cp.tx_id !== "string") {
-      cpErrors.push("checkpoint missing tx_id");
-    } else if (byTxId.has(cp.tx_id)) {
-      cpErrors.push(`duplicate checkpoint tx_id ${cp.tx_id}`);
-    } else {
-      byTxId.set(cp.tx_id, cp);
-    }
-
-    // Verify the checkpoint envelope against its committed record (external
-    // commitment — the record is the payload these external envelopes bind to).
+    // Decode record_bytes first: in v2 the join key is DERIVED from it, so it
+    // is an input to identity, not just to the payload binding below.
     let recordBytes: Uint8Array | undefined;
     try {
       if (typeof cp.record_bytes === "string") recordBytes = hexToBytes(cp.record_bytes);
     } catch (e) {
       cpErrors.push(`checkpoint record_bytes is not hex: ${stringifyErr(e)}`);
     }
+
+    const keyed = await resolveCheckpointKey(cp, recordBytes, isV1);
+    cpErrors.push(...keyed.errors);
+    if (keyed.key !== null) {
+      if (byKey.has(keyed.key)) {
+        cpErrors.push(`duplicate checkpoint ${isV1 ? "tx_id" : "checkpoint_ref"} ${keyed.key}`);
+      } else {
+        byKey.set(keyed.key, cp);
+        anchorByKey.set(keyed.key, keyed.anchorRef);
+      }
+    }
+
+    // Verify the checkpoint envelope against its committed record (external
+    // commitment — the record is the payload these external envelopes bind to).
     try {
       const res = await verifyEnvelope(
-        cp.envelope,
+        cp.envelope as Envelope,
         recordBytes !== undefined ? { payloadBytes: recordBytes } : {},
       );
       // A checkpoint must fully bind: signature + the committed record matching
@@ -583,12 +840,19 @@ async function verifyAnchorTrace(
     }
 
     checkpointResults.push({
-      txId: typeof cp.tx_id === "string" ? cp.tx_id : "",
+      checkpointRef: keyed.key ?? "",
+      anchorRef: keyed.anchorRef,
       envelopeOk,
       merkleRootOk,
       onChainOk: null, // filled in step 5 if a gateway re-fetch was requested
       onChain: null, // per-gateway (§4.2), filled in step 5
-      ok: envelopeOk && merkleRootOk,
+      // `keyed.errors` is load-bearing here, not decorative. A structurally
+      // invalid anchor_ref rides INSIDE the signature, so it is a defect we
+      // can see rather than a coverage gap we cannot — and this kernel's
+      // standing rule is that malformed is a failure while absent is
+      // undetermined (the same rule disclosed `content` follows). Without
+      // this term the vector `trace-v2-malformed-anchor-ref` verified GREEN.
+      ok: envelopeOk && merkleRootOk && keyed.errors.length === 0,
       errors: cpErrors,
     });
   }
@@ -622,16 +886,34 @@ async function verifyAnchorTrace(
 
     // Bind the event to exactly one checkpoint in the bundle, then verify
     // RFC 9162 inclusion against THAT checkpoint's merkle_root.
-    const incl = ev.inclusion;
-    const cp = incl && typeof incl.checkpoint_tx_id === "string" ? byTxId.get(incl.checkpoint_tx_id) : undefined;
-    const checkpointBound = cp !== undefined;
+    const incl = ev.inclusion as (TraceInclusion & { checkpoint_tx_id?: unknown }) | undefined;
+    // The join key is spelled differently in the two forms and MUST NOT be read
+    // from the other one: an inclusion carrying v1's spelling inside a v2 body
+    // is a mixed bundle, and resolving it anyway is how an event silently binds
+    // to a checkpoint nobody meant.
+    const keyField = isV1 ? "checkpoint_tx_id" : "checkpoint_ref";
+    const wrongField = isV1 ? "checkpoint_ref" : "checkpoint_tx_id";
+    const inclAsRecord = incl as unknown as Record<string, unknown> | undefined;
+    const rawKey = inclAsRecord ? inclAsRecord[keyField] : undefined;
+    const strayKey = inclAsRecord ? inclAsRecord[wrongField] : undefined;
+    let cp: AnyTraceCheckpoint | undefined;
     if (!incl || typeof incl !== "object") {
       evErrors.push("event missing inclusion proof");
-    } else if (!checkpointBound) {
+    } else if (strayKey !== undefined) {
       evErrors.push(
-        `event inclusion.checkpoint_tx_id ${JSON.stringify(incl.checkpoint_tx_id)} resolves to no checkpoint`,
+        `event inclusion carries ${wrongField} in a ${bodyType} body — one bundle speaks one vocabulary`,
       );
+    } else if (typeof rawKey !== "string") {
+      evErrors.push(`event inclusion missing ${keyField}`);
+    } else {
+      cp = byKey.get(rawKey);
+      if (cp === undefined) {
+        evErrors.push(
+          `event inclusion.${keyField} ${JSON.stringify(rawKey)} resolves to no checkpoint`,
+        );
+      }
     }
+    const checkpointBound = cp !== undefined;
 
     let inclusionOk = false;
     if (incl && checkpointBound && cp) {
@@ -641,7 +923,7 @@ async function verifyAnchorTrace(
           incl.leaf_index,
           incl.leaf_count,
           (incl.audit_path ?? []).map((h) => hexToBytes(h)),
-          hexToBytes(cp.merkle_root),
+          hexToBytes(cp.merkle_root ?? ""),
         );
         if (!inclusionOk) evErrors.push("RFC 9162 inclusion proof did not reconstruct the checkpoint root");
 
@@ -699,26 +981,12 @@ async function verifyAnchorTrace(
       }
 
       // Disclosed bytes, precedence: in-body (signed) → side input. A string
-      // side input is hex; a Uint8Array is used as-is.
-      let inBody: Uint8Array | undefined;
-      if (typeof ev.content === "string") {
-        try {
-          inBody = hexToBytes(ev.content);
-        } catch (e) {
-          evErrors.push(`event content is not hex: ${stringifyErr(e)}`);
-        }
-      }
-      let side: Uint8Array | undefined;
-      const sideRaw = options.content?.[eventId];
-      if (sideRaw instanceof Uint8Array) {
-        side = sideRaw;
-      } else if (typeof sideRaw === "string") {
-        try {
-          side = hexToBytes(sideRaw);
-        } catch (e) {
-          evErrors.push(`supplied content for ${eventId} is not hex: ${stringifyErr(e)}`);
-        }
-      }
+      // side input is hex; a Uint8Array is used as-is. Resolved by the SHARED
+      // selector so `disclosedContent` hands a consumer the very bytes bound
+      // here — one decode, not two that can drift apart.
+      const selection = selectDisclosedBytes(ev, eventId, options.content);
+      const { inBody, side } = selection;
+      evErrors.push(...selection.errors);
 
       if (inBody !== undefined && side !== undefined && !bytesEqual(inBody, side)) {
         // Two disclosures that disagree: a genuine conflict, not undetermined.
@@ -775,9 +1043,26 @@ async function verifyAnchorTrace(
       errors.push("on-chain re-fetch requested but no fetch implementation is available");
     } else {
       for (const cpr of checkpointResults) {
-        const cp = byTxId.get(cpr.txId);
+        const cp = byKey.get(cpr.checkpointRef);
         if (!cp) continue;
-        const outcome = await refetchCheckpoint(cp, gateways, fetchImpl);
+        // A checkpoint with no anchor_ref has NOTHING to re-fetch. Under DL-52
+        // that is the normal state inside a stamp interval — placed, readable,
+        // not yet witnessed — so it reports as unreachable (which downgrades
+        // the run to partial) and NEVER as a mismatch. Treating "we never
+        // anchored it yet" as "the chain disagrees" would be the same false
+        // accusation this whole change is removing.
+        if (cpr.anchorRef === null) {
+          gatewayUnavailable = true;
+          cpr.onChain = {
+            perGateway: gateways.map((gw) => ({ gateway: gw, outcome: "unreachable" as const })),
+            rollup: "unreachable",
+            onChainOk: null,
+          };
+          cpr.onChainOk = null;
+          cpr.errors.push("checkpoint has no anchor_ref — not yet witnessed, nothing to re-fetch");
+          continue;
+        }
+        const outcome = await refetchCheckpoint(cp, cpr.anchorRef, gateways, fetchImpl);
         cpr.onChain = outcome.onChain;
         cpr.onChainOk = outcome.onChain.onChainOk;
         if (outcome.unavailable) gatewayUnavailable = true;
@@ -832,6 +1117,214 @@ async function verifyAnchorTrace(
   };
 }
 
+// ===========================================================================
+// Ingest: materializing the disclosed raw bytes (evidence-bundle.md §5.1).
+//
+// The receiving half of a handoff. `events[].content` rides as lowercase hex
+// (JSON cannot carry arbitrary bytes), and until now every consumer that wanted
+// the actual log bytes back had to know that and decode them itself —
+// re-implementing an encoding convention the kernel already applies internally.
+// A consumer that copied `content` VERBATIM into a file shipped packs that
+// failed verification on genuine, untampered evidence, because the hash of the
+// hex text is not the hash of the bytes it encodes.
+//
+// `disclosedContent` closes that gap with one rule: bytes come back only when
+// they are BOUND. It verifies the bundle first and hands back a decoded
+// Uint8Array only for events whose whole chain held AND whose disclosed bytes
+// hash to the committed `content_hash`. Everything else comes back as a status
+// with a reason and NO bytes — in particular a minimal-disclosure event reports
+// `not_disclosed` rather than empty bytes, because a caller that cannot tell
+// those apart writes an empty log file and believes it succeeded.
+// ===========================================================================
+
+// Per-event outcome of an ingest attempt. Only `verified` carries bytes.
+export type DisclosureStatus =
+  | "verified" // bytes decoded AND bound to the committed content_hash
+  | "not_disclosed" // nothing disclosed for this event — minimal disclosure, nothing to write
+  | "undetermined" // bytes disclosed but nothing to bind them to (record withheld / no commitment)
+  | "failed"; // the event's chain did not verify, or the disclosure did not bind/decode
+
+export interface DisclosedEventContent {
+  eventId: string;
+  status: DisclosureStatus;
+  // The decoded raw bytes. Non-null ONLY when status === "verified" — an
+  // unbound or unverified disclosure is withheld, never handed back.
+  bytes: Uint8Array | null;
+  // Why, whenever bytes are absent for a reason other than plain non-disclosure.
+  errors: string[];
+}
+
+export interface DisclosedContentResult {
+  // The bundle-level rollup, verbatim from verifyEvidenceBundle.
+  status: EvidenceStatus;
+  // The full verification result, so a caller verifies ONCE: render the verdict
+  // from this and materialize from `content` in the same pass.
+  verification: EvidenceBundleResult;
+  // One entry per event in the bundle body, in body order.
+  events: DisclosedEventContent[];
+  // event_id → verified raw bytes: the materialization map. Contains ONLY
+  // entries whose status is "verified", so `for (const [id, bytes] of
+  // result.content)` is always safe to write straight to disk.
+  content: Map<string, Uint8Array>;
+  // Bundle-level reasons no content could be materialized at all.
+  errors: string[];
+}
+
+// How many `sanning.evidence.export/v1` wrappers deep the source bundle may be
+// nested before this path gives up. verifyEvidenceBundle's canonicalization
+// depth bound already rejects a pathological bundle, but the unwrap must be
+// independently bounded rather than trusting that it ran first.
+const MAX_EXPORT_UNWRAP = 4;
+
+/**
+ * Materialize the disclosed raw bytes of a received bundle (evidence-bundle §5.1).
+ *
+ * Verify-then-return: the bundle is verified with {@link verifyEvidenceBundle}
+ * (same options — gateways, out-of-band `content`, `fetchImpl`), and an event's
+ * bytes are returned ONLY when that verification bound them to the committed
+ * `content_hash`. There is no path through this function that yields bytes
+ * whose SHA-256 is not the commitment.
+ *
+ * Returns `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 produce different bytes and a different hash. Callers who
+ * know their payload is text decode it themselves and own that assumption.
+ */
+export async function disclosedContent(
+  bundle: unknown,
+  options: VerifyEvidenceOptions = {},
+): Promise<DisclosedContentResult> {
+  const verification = await verifyEvidenceBundle(bundle, options);
+  const events: DisclosedEventContent[] = [];
+  const content = new Map<string, Uint8Array>();
+  const errors: string[] = [];
+  const empty = (): DisclosedContentResult => ({
+    status: verification.status,
+    verification,
+    events: [],
+    content: new Map(),
+    errors: [...errors, ...verification.errors],
+  });
+
+  const traceEvents = resolveTraceEvents(bundle);
+  if (traceEvents === undefined) {
+    errors.push(
+      `no ${ANCHOR_TRACE_BODY_TYPES.join(" / ")} body to materialize content from ` +
+        `(body_type ${JSON.stringify(verification.bodyType)})`,
+    );
+    return empty();
+  }
+
+  // Fail closed on any drift between the body we are decoding and the results
+  // we are trusting. Both must be the same events in the same order, or the
+  // "these bytes are the bytes that verified" guarantee is void — which is the
+  // only guarantee this function makes. A broken wrapper lands here too:
+  // verifyEvidenceBundle returns zero event results, so nothing is emitted.
+  if (traceEvents.length !== verification.events.length) {
+    errors.push(
+      "the bundle did not verify far enough to materialize content: " +
+        `${verification.events.length} verified event result(s) for ${traceEvents.length} body event(s)`,
+    );
+    return empty();
+  }
+  for (let i = 0; i < traceEvents.length; i++) {
+    const te = traceEvents[i];
+    const envelope = te !== null && typeof te === "object" ? te.envelope : undefined;
+    if (getEventId(envelope) !== verification.events[i]!.eventId) {
+      errors.push(
+        `event alignment drift at index ${i}: the body event and its verification result ` +
+          "are not the same event; refusing to hand back any content",
+      );
+      return empty();
+    }
+  }
+
+  for (let i = 0; i < traceEvents.length; i++) {
+    const ev = traceEvents[i] as TraceEvent;
+    const res = verification.events[i]!;
+    const selection = selectDisclosedBytes(ev, res.eventId, options.content);
+    const bytes = selection.inBody ?? selection.side;
+    const evErrors: string[] = [];
+    let status: DisclosureStatus;
+
+    if (!res.ok || res.contentOk === false) {
+      // The event itself is not trustworthy (bad signature, broken inclusion,
+      // unbound checkpoint) or its disclosure contradicts the commitment.
+      status = "failed";
+      evErrors.push(
+        res.contentOk === false
+          ? "disclosed content does not bind to the committed content_hash — withheld"
+          : "the event's own proof chain did not verify — nothing here is safe to materialize",
+      );
+      evErrors.push(...res.errors);
+    } else if (!selection.offered) {
+      // Minimal disclosure: the committed hash is there, the bytes are not.
+      // Distinct from empty bytes, and never an error.
+      status = "not_disclosed";
+    } else if (bytes === undefined) {
+      status = "failed";
+      evErrors.push(
+        "content was disclosed for this event but is not a decodable lowercase-hex string",
+      );
+      evErrors.push(...selection.errors);
+    } else if (res.contentOk !== true) {
+      // Disclosed and decodable, but there is no commitment to check it against
+      // (withheld record, or a record committing no content_hash). Unbound
+      // bytes are exactly what a consumer must not silently write out.
+      status = "undetermined";
+      evErrors.push(
+        "disclosed bytes are not bound to any committed content_hash — withheld rather than returned",
+      );
+      evErrors.push(...res.errors);
+    } else {
+      status = "verified";
+    }
+
+    const verified = status === "verified" && bytes !== undefined;
+    if (verified) {
+      if (content.has(res.eventId)) {
+        errors.push(
+          `duplicate event_id ${JSON.stringify(res.eventId)}: the content map keeps the first ` +
+            "occurrence — read events[] for every event",
+        );
+      } else {
+        content.set(res.eventId, bytes);
+      }
+    }
+    events.push({
+      eventId: res.eventId,
+      status,
+      bytes: verified ? bytes : null,
+      errors: evErrors,
+    });
+  }
+
+  return { status: verification.status, verification, events, content, errors };
+}
+
+// The anchor-trace events a bundle carries, unwrapping any evidence-export
+// wrapper(s) to the inline source bundle — mirroring how verifyEvidenceBundle
+// recurses into `source_bundle`, so the events line up with its results.
+// `undefined` when there is no anchor-trace body to materialize from.
+function resolveTraceEvents(bundle: unknown): TraceEvent[] | undefined {
+  let cur: unknown = bundle;
+  for (let depth = 0; depth < MAX_EXPORT_UNWRAP; depth++) {
+    if (cur === null || typeof cur !== "object" || Array.isArray(cur)) return undefined;
+    const b = cur as EvidenceBundle;
+    const bodyType = typeof b.body_type === "string" ? b.body_type : null;
+    if (bodyType === ANCHOR_TRACE_BODY_TYPE || bodyType === ANCHOR_TRACE_BODY_TYPE_V1) {
+      const body = b.body as AnchorTraceBody | null | undefined;
+      if (body === null || typeof body !== "object" || !Array.isArray(body.events)) return undefined;
+      return body.events;
+    }
+    if (bodyType !== EXPORT_BODY_TYPE) return undefined;
+    const body = b.body as ExportBody | null | undefined;
+    if (body === null || typeof body !== "object") return undefined;
+    cur = body.source_bundle;
+  }
+  return undefined;
+}
+
 // ===========================================================================
 // Attested-evidence-export verification (evidence-export.md §5, steps 3–9).
 // Reached from verifyEvidenceBundle AFTER the wrapper (Ed25519 issuer signature
@@ -924,14 +1417,8 @@ async function verifyExportBody(
   // content_ok, and the optional per-gateway on-chain re-fetch, §4.2 / step 7).
   const sourceResult = await verifyEvidenceBundle(inline, options);
 
-  // Map source checkpoints by tx_id for attestation data_hash binding (§5 6c).
-  const sourceCheckpoints = new Map<string, TraceCheckpoint>();
-  const sb = inline.body as AnchorTraceBody | undefined;
-  if (sb && typeof sb === "object" && Array.isArray(sb.checkpoints)) {
-    for (const cp of sb.checkpoints) {
-      if (cp && typeof cp.tx_id === "string") sourceCheckpoints.set(cp.tx_id, cp);
-    }
-  }
+  // Attestation data_hash binding (§5 6c).
+  const sourceCheckpoints = await indexSourceCheckpoints(inline);
 
   // --- Step 6: embedded attestation records ---------------------------------
   const attestations: AttestationResult[] = [];
@@ -1063,15 +1550,9 @@ export async function recomputeExportVerdict(
 ): Promise<ComposeVerdictResult> {
   const sourceResult = await verifyEvidenceBundle(sourceBundle, options);
 
-  // Map source checkpoints by tx_id for attestation data_hash binding (§5 6c) —
-  // identical to verifyExportBody's map construction.
-  const sourceCheckpoints = new Map<string, TraceCheckpoint>();
-  const sb = sourceBundle.body as AnchorTraceBody | undefined;
-  if (sb && typeof sb === "object" && Array.isArray(sb.checkpoints)) {
-    for (const cp of sb.checkpoints) {
-      if (cp && typeof cp.tx_id === "string") sourceCheckpoints.set(cp.tx_id, cp);
-    }
-  }
+  // Attestation data_hash binding (§5 6c) — the SAME index construction as
+  // verifyExportBody, deliberately shared rather than restated.
+  const sourceCheckpoints = await indexSourceCheckpoints(sourceBundle);
 
   const attestations: AttestationResult[] = [];
   for (const rec of attestationRecords) {
@@ -1115,12 +1596,12 @@ export async function recomputeExportVerdict(
 // undetermined-tolerant and never gates.
 async function verifyAttestation(
   rec: AttestationRecord,
-  sourceCheckpoints: Map<string, TraceCheckpoint>,
+  sourceCheckpoints: Map<string, AnyTraceCheckpoint>,
 ): Promise<{ result: AttestationResult; malformed?: string }> {
   const errs: string[] = [];
   const result: AttestationResult = {
-    checkpointTxId:
-      rec && typeof rec.checkpoint_tx_id === "string" ? rec.checkpoint_tx_id : "",
+    checkpointRef:
+      rec && typeof rec.checkpoint_ref === "string" ? rec.checkpoint_ref : "",
     operator: "",
     gateway: null,
     signatureOk: false,
@@ -1198,11 +1679,11 @@ async function verifyAttestation(
   // uploaded JCS(envelope) bytes (the same bytes the on-chain re-fetch compares
   // against, §4.2), so the checkpoint's committed content hash is
   // SHA-256(JCS(checkpoint.envelope)).
-  const cp = sourceCheckpoints.get(result.checkpointTxId);
+  const cp = sourceCheckpoints.get(result.checkpointRef);
   result.checkpointResolved = cp !== undefined;
   if (!cp) {
     errs.push(
-      `attestation checkpoint_tx_id ${JSON.stringify(result.checkpointTxId)} resolves to no source checkpoint`,
+      `attestation checkpoint_ref ${JSON.stringify(result.checkpointRef)} resolves to no source checkpoint`,
     );
   } else {
     try {
@@ -1261,7 +1742,7 @@ function buildVerdictObject(
 ): VerdictObject {
   const attByCheckpoint = new Map<string, VerdictAttestation[]>();
   for (const a of attestations) {
-    const list = attByCheckpoint.get(a.checkpointTxId) ?? [];
+    const list = attByCheckpoint.get(a.checkpointRef) ?? [];
     list.push({
       operator: a.operator,
       ...(a.gateway ? { gateway: a.gateway } : {}),
@@ -1271,7 +1752,7 @@ function buildVerdictObject(
       ...(a.level !== null ? { level: a.level } : {}),
       subject_ref_ok: a.subjectRefOk,
     });
-    attByCheckpoint.set(a.checkpointTxId, list);
+    attByCheckpoint.set(a.checkpointRef, list);
   }
 
   const events: VerdictEvent[] = source.events.map((e) => ({
@@ -1284,10 +1765,10 @@ function buildVerdictObject(
   }));
 
   const checkpoints: VerdictCheckpoint[] = source.checkpoints.map((c) => ({
-    checkpoint_tx_id: c.txId,
+    checkpoint_ref: c.checkpointRef,
     merkle_root_ok: c.merkleRootOk,
     on_chain: c.onChain ? toVerdictOnChain(c.onChain) : null,
-    attestations: attByCheckpoint.get(c.txId) ?? [],
+    attestations: attByCheckpoint.get(c.checkpointRef) ?? [],
   }));
 
   let verified = 0;
@@ -1356,7 +1837,7 @@ function projectVerdictForAgreement(v: unknown): unknown {
       const cp = (c ?? {}) as VerdictCheckpoint;
       const atts = Array.isArray(cp.attestations) ? cp.attestations : [];
       return {
-        checkpoint_tx_id: cp.checkpoint_tx_id ?? null,
+        checkpoint_ref: cp.checkpoint_ref ?? null,
         merkle_root_ok: cp.merkle_root_ok ?? null,
         // on_chain DELIBERATELY OMITTED — environment/time-dependent (see step 5).
         attestations: atts.map((a) => {
@@ -1394,7 +1875,8 @@ function summarizeExport(
 // gateways is preserved; the derived collapsed `onChainOk` reproduces the old
 // single-boolean exactly for a single gateway.
 async function refetchCheckpoint(
-  cp: TraceCheckpoint,
+  cp: AnyTraceCheckpoint,
+  anchorRef: AnchorRef,
   gateways: string[],
   fetchImpl: typeof fetch,
 ): Promise<{ onChain: OnChainResult; unavailable: boolean; error?: string }> {
@@ -1409,15 +1891,18 @@ async function refetchCheckpoint(
 
   const perGateway: PerGatewayOutcome[] = [];
   for (const gw of gateways) {
-    perGateway.push({ gateway: gw, outcome: await probeGateway(cp, gw, expectedHex, fetchImpl) });
+    perGateway.push({
+      gateway: gw,
+      outcome: await probeGateway(anchorRef, gw, expectedHex, fetchImpl),
+    });
   }
 
   const onChain = rollupOnChain(perGateway);
   let error: string | undefined;
   if (onChain.rollup === "mismatch") {
-    error = `on-chain bytes at ${cp.tx_id} do not match the bundle's checkpoint envelope`;
+    error = `on-chain bytes at ${anchorRef.id} do not match the bundle's checkpoint envelope`;
   } else if (onChain.rollup === "unreachable") {
-    error = `checkpoint ${cp.tx_id} unreachable on all gateways`;
+    error = `checkpoint ${anchorRef.id} unreachable on all gateways`;
   }
   return { onChain, unavailable: onChain.rollup === "unreachable", error };
 }
@@ -1425,12 +1910,12 @@ async function refetchCheckpoint(
 // One gateway's outcome for one checkpoint tx: confirm (bytes match), mismatch
 // (bytes disagree), or unreachable (no response / !ok / network error).
 async function probeGateway(
-  cp: TraceCheckpoint,
+  anchorRef: AnchorRef,
   gateway: string,
   expectedHex: string | undefined,
   fetchImpl: typeof fetch,
 ): Promise<OnChainOutcome> {
-  const url = `${gateway.replace(/\/+$/, "")}/${cp.tx_id}`;
+  const url = `${gateway.replace(/\/+$/, "")}/${anchorRef.id}`;
   let resp: Awaited<ReturnType<typeof fetch>>;
   try {
     resp = await fetchImpl(url);
@@ -1478,6 +1963,76 @@ function getEventId(env: unknown): string {
   return "<unknown>";
 }
 
+// The disclosed bytes offered for ONE trace event (evidence-bundle §5.1),
+// decoded once. Shared by the verifier's content check and the `disclosedContent`
+// ingest API: the bytes a consumer receives are then, by construction, the bytes
+// the verifier hashed against the commitment rather than a second decode of the
+// same field that could drift from it.
+interface DisclosedSelection {
+  // In-body `events[].content` (the signed disclosure), when it decoded.
+  inBody?: Uint8Array;
+  // Out-of-band `options.content[eventId]`, when it decoded.
+  side?: Uint8Array;
+  // A disclosure was OFFERED for this event — in-body or side input — whether or
+  // not it decoded. This is what separates "minimal disclosure, nothing to
+  // materialize" from "disclosed, but unusable"; conflating those is how a
+  // consumer writes an empty log file and believes it succeeded.
+  offered: boolean;
+  // Decode failures, in the verifier's existing wording.
+  errors: string[];
+}
+
+// The side-input presence rule lives in `side-content.ts`, stated ONCE.
+//
+// It used to live here as a private `lookupSideContent`, and `grading.ts`
+// carried a second, laxer answer to the same question (`hasEntry`: own +
+// enumerable, nothing more). On one and the same content map the grader said
+// PRESENT while this verifier said nothing was offered, and `gradePack` then
+// returned `incomplete` with ZERO causes. Read `side-content.ts` for the rule
+// and for what each clause of it cost.
+
+function selectDisclosedBytes(
+  ev: TraceEvent,
+  eventId: string,
+  sideContent: VerifyEvidenceOptions["content"],
+): DisclosedSelection {
+  const errors: string[] = [];
+  let inBody: Uint8Array | undefined;
+  if (typeof ev.content === "string") {
+    try {
+      inBody = hexToBytes(ev.content);
+    } catch (e) {
+      errors.push(`event content is not hex: ${stringifyErr(e)}`);
+    }
+  }
+  let side: Uint8Array | undefined;
+  const sideEntry: SideEntry = sideContentEntry(sideContent, eventId);
+  if (sideEntry.value instanceof Uint8Array) {
+    side = sideEntry.value;
+  } else if (typeof sideEntry.value === "string") {
+    try {
+      side = hexToBytes(sideEntry.value);
+    } catch (e) {
+      errors.push(`supplied content for ${eventId} is not hex: ${stringifyErr(e)}`);
+    }
+  }
+  // `offered` comes from the SAME test that produced the value, never from
+  // `value !== undefined` — that is the conflation this whole guard exists to
+  // remove, and it was removed from ONE of the two operands. The left one
+  // carried it unchanged: an in-body `"content": null` is `!== undefined`, so
+  // the event was marked offered while no bytes were selected, and the kernel
+  // split against itself — `verifyEvidenceBundle` VERIFIED, `disclosedContent`
+  // FAILED, on one bundle. `null` is how an optional field's absence
+  // serializes; `inBodyContentOffered` states that once, beside the side-input
+  // rule it mirrors.
+  return {
+    inBody,
+    side,
+    offered: inBodyContentOffered(ev.content) || sideEntry.offered,
+    errors,
+  };
+}
+
 function toHex(bytes: Uint8Array): string {
   let out = "";
   for (const x of bytes) out += x.toString(16).padStart(2, "0");