@sanning/proof 0.5.0 → 0.7.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
@@ -52,6 +73,33 @@ export const ANCHOR_TRACE_BODY_TYPE = "sanning.anchor.trace/v1";
 // verifyExportBody (§5).
 export 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 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 const STAMP_BODY_VERSION = "sanning.stamp/v1";
+
 // ---- Wire types (evidence-bundle.md §2 + §5.1) ------------------------------
 
 export interface EvidenceIssuer {
@@ -70,20 +118,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 {
@@ -101,6 +187,64 @@ export interface AnchorTraceBody {
   events: TraceEvent[];
 }
 
+// ---- `sanning.stamp.trace/v1` wire types (evidence-bundle.md §5.2) ---------
+
+/**
+ * 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;
@@ -127,7 +271,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 +295,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 +338,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
@@ -188,6 +350,56 @@ export interface EventResult {
   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;
   // The wrapper: accepted major, body_hash recompute, Ed25519 wrapper signature.
@@ -207,6 +419,12 @@ export interface EvidenceBundleResult {
   // above are the recomputed SOURCE-bundle results in that case. Absent for a
   // plain anchor-trace bundle — additive, backward-compatible.
   export?: ExportResult;
+  // Present ONLY for a `sanning.stamp.trace/v1` body (evidence-bundle.md §5.2):
+  // the per-stamp recomputed results. `checkpoints`/`events` stay empty for
+  // such a bundle — a stamp body carries neither, and reporting an empty list
+  // as "nothing was wrong" is the exact confusion `partial` exists to prevent.
+  // Absent for every other body — additive, backward-compatible.
+  stamps?: StampResult[];
   errors: string[];
 }
 
@@ -215,7 +433,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 +504,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 +523,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 +533,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 +563,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 +572,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 +713,20 @@ export async function verifyEvidenceBundle(
     return verifyExportBody(b, specVersionOk, assertedStatus, errors, options);
   }
 
-  if (bodyType !== ANCHOR_TRACE_BODY_TYPE) {
+  // The Sanning-signed interval stamp body (evidence-bundle.md §5.2). The
+  // wrapper is authentic — and for this body that IS "Sanning signed it", since
+  // a stamp carries no second signature of its own inside the bundle.
+  if (bodyType === STAMP_TRACE_BODY_TYPE) {
+    return verifyStampTrace(b, specVersionOk, assertedStatus, errors);
+  }
+
+  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 +745,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 +906,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 +988,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 +1034,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 +1071,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");
 
@@ -761,9 +1191,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;
@@ -818,6 +1265,332 @@ async function verifyAnchorTrace(
   };
 }
 
+// ===========================================================================
+// `sanning.stamp.trace/v1` — the Sanning-signed interval stamp (§5.2, DL-58)
+//
+// ── What this can prove, and what it deliberately does not claim ──
+//
+// A stamp is not a producer artifact. Under DL-52 the customer signs an
+// envelope and POSTs it; the commitment is witnessed later, on an interval, by
+// a stamp the customer never sees and holds no key for. So there is no
+// producer signature inside this body to check, and — this is the part worth
+// being precise about — there is no SECOND Sanning signature either. The
+// control plane stores the stamp's canonical bytes and hands them to a witness
+// as a signed chain data item; the signature lives on the chain, not in the
+// `stamps` table and not in this body.
+//
+// What "Sanning signed this" means for a stamp bundle is therefore exactly the
+// WRAPPER signature, verified generically before this function is reached. And
+// what makes the stamp evidence rather than an assertion is the witness, which
+// is on a chain and not checkable offline. Hence the rollup below: a stamp we
+// can read but nobody has witnessed holds the bundle at `partial`.
+//
+// So the checkable surface here is the stamp's INTERNAL consistency against
+// the one authority in the bundle — the witnessed bytes:
+//
+//   1. `stamp_ref` is SHA-256 of the DECODED bytes (derived, not asserted).
+//   2. Those bytes parse and re-canonicalize to themselves under JCS.
+//   3. Their `stamp_version` is the one this body_type pins.
+//   4. Every sub-tree range accounts for exactly one leaf of the stamp.
+//
+// (4) is the one that carries customer weight. R-8's whole per-agent story is
+// "prove this agent was under evidence over window W", answered by a
+// contiguous `first_leaf`/`leaf_count` slice of the org tree. Ranges that do
+// not tile `[0, leaf_count)` describe a partition that does not exist, so a
+// slice claim resting on them is unfounded — and unlike a bad signature,
+// nothing else in the stack would ever notice.
+// ===========================================================================
+
+/** Lowercase hex, even length, non-empty. The family's serialization rule. */
+function isLowerHex(s: unknown, nibbles?: number): s is string {
+  if (typeof s !== "string" || s.length === 0 || s.length % 2 !== 0) return false;
+  if (nibbles !== undefined && s.length !== nibbles) return false;
+  return /^[0-9a-f]+$/.test(s);
+}
+
+function isNonNegInt(n: unknown): n is number {
+  return typeof n === "number" && Number.isInteger(n) && n >= 0;
+}
+
+/**
+ * Parse and check one stamp's witnessed bytes.
+ *
+ * Errors accumulate rather than short-circuit wherever a later check is still
+ * meaningful, so a bundle with two independent defects reports two — a
+ * verifier that stops at the first one turns a second fix into a second
+ * round-trip.
+ */
+async function verifyStampEntry(
+  raw: unknown,
+  seen: Set<string>,
+): Promise<StampResult> {
+  const errors: string[] = [];
+  const base: StampResult = {
+    stampRef: "",
+    stampRefOk: false,
+    bodyOk: false,
+    stampVersion: null,
+    intervalStart: null,
+    intervalEnd: null,
+    merkleRoot: null,
+    leafCount: null,
+    subtreesOk: false,
+    subtrees: [],
+    anchorRef: null,
+    ok: false,
+    errors,
+  };
+
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    errors.push("stamp entry is not an object");
+    return base;
+  }
+  const e = raw as Partial<StampEntry> & Record<string, unknown>;
+
+  // --- the witnessed bytes, which are the only authority in this body -------
+  if (!isLowerHex(e.stamp_bytes)) {
+    errors.push("stamp_bytes is missing or not lowercase hex");
+    return base;
+  }
+  let bytes: Uint8Array;
+  try {
+    bytes = hexToBytes(e.stamp_bytes);
+  } catch (err) {
+    errors.push(`stamp_bytes is not hex: ${stringifyErr(err)}`);
+    return base;
+  }
+
+  // --- the derived identity -------------------------------------------------
+  const derived = await sha256Hex(bytes);
+  if (typeof e.stamp_ref !== "string" || e.stamp_ref === "") {
+    errors.push("stamp entry missing stamp_ref");
+  } else if (e.stamp_ref.toLowerCase() !== derived) {
+    // The bytes were edited and the label was not — or the label was edited
+    // and the bytes were not. Either way the bundle names a stamp it is not
+    // carrying, and quoting that name to a witness would resolve to something
+    // else entirely.
+    errors.push(
+      `stamp_ref does not match SHA-256(stamp_bytes): claimed=${e.stamp_ref} derived=${derived}`,
+    );
+  } else {
+    base.stampRefOk = true;
+    base.stampRef = derived;
+    if (seen.has(derived)) {
+      errors.push(`duplicate stamp_ref ${derived}`);
+      base.stampRefOk = false;
+    } else {
+      seen.add(derived);
+    }
+  }
+
+  // --- the body itself ------------------------------------------------------
+  let body: StampBody;
+  try {
+    const parsed: unknown = JSON.parse(new TextDecoder().decode(bytes));
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      errors.push("stamp body is not a JSON object");
+      return base;
+    }
+    body = parsed as StampBody;
+    // Re-canonicalize and compare. The plane replays these bytes verbatim on
+    // every submit attempt for exactly this reason: a non-canonical body makes
+    // a retry a DIFFERENT submission, and makes every independent re-derivation
+    // of the stamp disagree with the one that was witnessed.
+    if (jcs(body as unknown as Record<string, unknown>) !== new TextDecoder().decode(bytes)) {
+      errors.push("stamp_bytes are not JCS-canonical (RFC 8785)");
+      return base;
+    }
+  } catch (err) {
+    errors.push(`stamp body is not JSON: ${stringifyErr(err)}`);
+    return base;
+  }
+
+  if (body.stamp_version !== STAMP_BODY_VERSION) {
+    // A `sanning.stamp.trace/v1` body whose inner version is something else is
+    // two answers to one question inside one signature. The body_type is the
+    // reader's dispatch key and it said v1; honouring the other spelling is
+    // how a reader half-parses a shape it does not know.
+    errors.push(
+      `unsupported stamp_version ${JSON.stringify(body.stamp_version)} in a ` +
+        `${STAMP_TRACE_BODY_TYPE} body (expected ${STAMP_BODY_VERSION})`,
+    );
+    return base;
+  }
+  base.stampVersion = body.stamp_version;
+  base.bodyOk = true;
+
+  for (const f of ["org_ref", "interval_start", "interval_end"] as const) {
+    if (typeof body[f] !== "string" || body[f] === "") {
+      errors.push(`stamp body ${f} is missing or not a non-empty string`);
+      base.bodyOk = false;
+    }
+  }
+  base.intervalStart = typeof body.interval_start === "string" ? body.interval_start : null;
+  base.intervalEnd = typeof body.interval_end === "string" ? body.interval_end : null;
+
+  if (!isLowerHex(body.merkle_root, 64)) {
+    errors.push("stamp body merkle_root is not 64 lowercase hex characters");
+    base.bodyOk = false;
+  } else {
+    base.merkleRoot = body.merkle_root;
+  }
+  if (!isNonNegInt(body.leaf_count)) {
+    errors.push("stamp body leaf_count is not a non-negative integer");
+    base.bodyOk = false;
+  } else {
+    base.leafCount = body.leaf_count;
+  }
+
+  // --- the sub-tree ranges --------------------------------------------------
+  base.subtreesOk = checkSubtrees(body, base, errors);
+
+  base.anchorRef = parseAnchorRef(e.anchor_ref, errors);
+
+  base.ok =
+    base.stampRefOk && base.bodyOk && base.subtreesOk && errors.length === 0;
+  return base;
+}
+
+/**
+ * The range arithmetic (§5.2), and the reason it is a hard check.
+ *
+ * `buildStampTree` orders a stamp's leaves agent-major, which is the only
+ * reason `first_leaf` + `leaf_count` can describe an agent's slice at all: the
+ * ranges partition `[0, leaf_count)` exactly, by construction. A body whose
+ * ranges do not is either not a stamp this stack built or one built wrong, and
+ * in both cases the per-agent claim the ranges exist to support is unfounded.
+ *
+ * The sum is checked BEFORE the tiling and reports its own message, so a body
+ * that is merely short does not get filed under a gap it does not have.
+ */
+function checkSubtrees(body: StampBody, out: StampResult, errors: string[]): boolean {
+  const raw = body.subtrees;
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    errors.push("stamp body subtrees is not an object");
+    return false;
+  }
+
+  let shapeOk = true;
+  const subtrees: StampSubtreeResult[] = [];
+  for (const [ref, v] of Object.entries(raw)) {
+    if (v === null || typeof v !== "object" || Array.isArray(v)) {
+      errors.push(`sub-tree ${ref} is not an object`);
+      shapeOk = false;
+      continue;
+    }
+    const s = v as Partial<StampSubtree>;
+    if (!isNonNegInt(s.first_leaf)) {
+      errors.push(`sub-tree ${ref} first_leaf is not a non-negative integer`);
+      shapeOk = false;
+    }
+    // A zero-leaf sub-tree is not a slice of anything, and admitting one lets
+    // an arbitrary number of empty ranges sit inside a tiling that still adds
+    // up.
+    if (!isNonNegInt(s.leaf_count) || s.leaf_count === 0) {
+      errors.push(`sub-tree ${ref} leaf_count is not a positive integer`);
+      shapeOk = false;
+    }
+    if (!isLowerHex(s.root, 64)) {
+      errors.push(`sub-tree ${ref} root is not 64 lowercase hex characters`);
+      shapeOk = false;
+    }
+    if (!shapeOk) continue;
+    subtrees.push({
+      ref,
+      firstLeaf: s.first_leaf as number,
+      leafCount: s.leaf_count as number,
+      root: s.root as string,
+    });
+  }
+  subtrees.sort((a, b) => a.firstLeaf - b.firstLeaf);
+  out.subtrees = subtrees;
+  if (!shapeOk) return false;
+
+  const total = body.leaf_count;
+  if (!isNonNegInt(total)) return false; // already reported by the caller
+
+  const sum = subtrees.reduce((n, s) => n + s.leafCount, 0);
+  if (sum !== total) {
+    errors.push(
+      `sub-tree leaf_count sum ${sum} does not equal the stamp's leaf_count ${total}`,
+    );
+    return false;
+  }
+
+  let next = 0;
+  for (const s of subtrees) {
+    if (s.firstLeaf !== next) {
+      errors.push(
+        `sub-tree ranges do not tile [0, ${total}): expected a range at leaf ` +
+          `${next}, found one at ${s.firstLeaf}`,
+      );
+      return false;
+    }
+    next += s.leafCount;
+  }
+  return true;
+}
+
+async function verifyStampTrace(
+  b: EvidenceBundle,
+  specVersionOk: boolean,
+  assertedStatus: string | null,
+  errors: string[],
+): Promise<EvidenceBundleResult> {
+  const body = b.body as StampTraceBody;
+  if (!Array.isArray(body?.stamps)) {
+    return malformed(`${STAMP_TRACE_BODY_TYPE} body must have stamps[]`, true);
+  }
+
+  const seen = new Set<string>();
+  const stamps: StampResult[] = [];
+  for (const entry of body.stamps) {
+    stamps.push(await verifyStampEntry(entry, seen));
+  }
+
+  // --- Rollup ----------------------------------------------------------------
+  const anyHardFailure = stamps.some((s) => !s.ok);
+  const anyUnwitnessed = stamps.some((s) => s.anchorRef === null);
+
+  let status: EvidenceStatus;
+  if (anyHardFailure) {
+    status = "failed";
+  } else if (stamps.length === 0) {
+    // A bundle asserting nothing. Not a failure — nothing here is wrong — but
+    // it must never read `verified`, which a caller would take as a witness it
+    // does not have.
+    status = "partial";
+    errors.push(`${STAMP_TRACE_BODY_TYPE} body carries no stamps`);
+  } else if (anyUnwitnessed) {
+    // The honest half of P-10, one layer up. A stamp with no `anchor_ref` is
+    // sealed and unwitnessed: `retained-by-sanning`, which is a statement about
+    // our coverage and never an accusation about their evidence. It is also not
+    // `verified`, because for a stamp the witness is the entire independent
+    // part — unlike an anchor-trace checkpoint, which still carries a producer
+    // signature and an inclusion proof that stand on their own offline.
+    status = "partial";
+    errors.push(
+      "one or more stamps carries no anchor_ref — sealed by Sanning, witnessed by nobody",
+    );
+  } else {
+    status = "verified";
+  }
+
+  return {
+    status,
+    specVersionOk,
+    bodyHashOk: true,
+    signatureOk: true,
+    bodyType: STAMP_TRACE_BODY_TYPE,
+    onChainChecked: false,
+    checkpoints: [],
+    events: [],
+    assertedStatus,
+    stamps,
+    errors,
+  };
+}
+
 // ===========================================================================
 // Ingest: materializing the disclosed raw bytes (evidence-bundle.md §5.1).
 //
@@ -910,7 +1683,7 @@ export async function disclosedContent(
   const traceEvents = resolveTraceEvents(bundle);
   if (traceEvents === undefined) {
     errors.push(
-      `no ${ANCHOR_TRACE_BODY_TYPE} body to materialize content from ` +
+      `no ${ANCHOR_TRACE_BODY_TYPES.join(" / ")} body to materialize content from ` +
         `(body_type ${JSON.stringify(verification.bodyType)})`,
     );
     return empty();
@@ -1007,13 +1780,19 @@ export async function disclosedContent(
 // 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 {
+//
+// Exported for `chain.ts`, which needs the same descent and must not derive it
+// again: two answers to "which events is this bundle actually about" inside one
+// kernel is two implementations of one rule, and the one that drifted would be
+// the one nobody was looking at. Deliberately NOT re-exported from `index.ts` —
+// same posture as `side-content.ts`, internal and shared.
+export 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) {
+    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;
@@ -1118,14 +1897,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[] = [];
@@ -1257,15 +2030,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) {
@@ -1309,12 +2076,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,
@@ -1392,11 +2159,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 {
@@ -1455,7 +2222,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 } : {}),
@@ -1465,7 +2232,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) => ({
@@ -1478,10 +2245,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;
@@ -1550,7 +2317,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) => {
@@ -1588,7 +2355,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 }> {
@@ -1603,15 +2371,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 };
 }
@@ -1619,12 +2390,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);
@@ -1691,6 +2462,15 @@ interface DisclosedSelection {
   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,
@@ -1706,17 +2486,31 @@ function selectDisclosedBytes(
     }
   }
   let side: Uint8Array | undefined;
-  const sideRaw = sideContent?.[eventId];
-  if (sideRaw instanceof Uint8Array) {
-    side = sideRaw;
-  } else if (typeof sideRaw === "string") {
+  const sideEntry: SideEntry = sideContentEntry(sideContent, eventId);
+  if (sideEntry.value instanceof Uint8Array) {
+    side = sideEntry.value;
+  } else if (typeof sideEntry.value === "string") {
     try {
-      side = hexToBytes(sideRaw);
+      side = hexToBytes(sideEntry.value);
     } catch (e) {
       errors.push(`supplied content for ${eventId} is not hex: ${stringifyErr(e)}`);
     }
   }
-  return { inBody, side, offered: ev.content !== undefined || sideRaw !== undefined, errors };
+  // `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 {