@sanning/proof 0.6.0 → 0.8.0

package/src/evidence.ts

@@ -73,6 +73,34 @@ export const ANCHOR_TRACE_BODY_TYPES = [
 // 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";
+export const STAMP_EVIDENCE_BODY_TYPE = "sanning.stamp.evidence/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 {
@@ -160,6 +188,95 @@ 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[];
+}
+
+// ---- `sanning.stamp.evidence/v1` wire types (evidence-bundle.md §5.3) -----
+//
+// Both halves of a DL-52 record, bound: the producer signs the envelope, and
+// Sanning signs and witnesses the stamp whose root commits to it. Neither
+// earlier body joins them, and a field added to §5.2 could not — a conformant
+// reader MUST ignore fields it does not know (envelope-spec.md §2), so the
+// join has to live in a body_type readers DISPATCH on. See §5.3.1.
+
+/** §5.3's inclusion: §5.1's shape with `stamp_ref` as the join key. */
+export interface StampEvidenceInclusion {
+  leaf_hash: string; // hex
+  leaf_index: number;
+  leaf_count: number;
+  audit_path: string[]; // hex[]
+  /** Resolves against `stamps[].stamp_ref` in the SAME body. */
+  stamp_ref: string;
+}
+
+export interface StampEvidenceEvent {
+  envelope: Envelope;
+  record_bytes?: string; // hex of JCS(event record); omitted == withheld
+  content?: string; // opt-in disclosed raw bytes, lowercase hex
+  inclusion: StampEvidenceInclusion;
+}
+
+export interface StampEvidenceBody {
+  /** Byte-identical to §5.2.2 — one definition, one place to change. */
+  stamps: StampEntry[];
+  events: StampEvidenceEvent[];
+}
+
 export interface EvidenceBundle {
   spec_version: string;
   body_type: string;
@@ -265,6 +382,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.
@@ -284,6 +451,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[];
 }
 
@@ -572,6 +745,18 @@ export async function verifyEvidenceBundle(
     return verifyExportBody(b, specVersionOk, assertedStatus, errors, options);
   }
 
+  // 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);
+  }
+
+  // The DL-52 hand-over body (§5.3): stamps AND the customer's events, joined.
+  if (bodyType === STAMP_EVIDENCE_BODY_TYPE) {
+    return verifyStampEvidence(b, specVersionOk, assertedStatus, errors, options);
+  }
+
   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,
@@ -943,79 +1128,10 @@ async function verifyAnchorTrace(
       }
     }
 
-    // Content (raw-log) binding — the rawLog → content_hash link the rest of
-    // the chain (content_hash → record → payload_hash → signature → leaf →
-    // root) already covers. The committed hash lives in the RECORD
-    // (record.event.content_hash, minimal disclosure); for a promoted-disclosure
-    // envelope it falls back to the envelope's own committed hashes
-    // (contentHashes — NOT verifyEnvelope's path, which reads payload/event_type
-    // and yields nothing for a sanning.events/v1 envelope). Disclosed bytes come
-    // from the signed in-body `ev.content` FIRST, then the out-of-band
-    // options.content side input. Undetermined (null) when nothing is disclosed
-    // or nothing is committed; false ONLY on a real mismatch or an in-body vs
-    // side-input disagreement — mirroring payloadBindingOk's never-fail-on-absent
-    // discipline.
-    let contentOk: boolean | null = null;
-    {
-      const committed: string[] = [];
-      let recordContentHash: string | undefined;
-      if (recordBytes !== undefined) {
-        try {
-          const record = JSON.parse(new TextDecoder().decode(recordBytes)) as {
-            event?: { content_hash?: unknown };
-          };
-          const ch = record.event?.content_hash;
-          if (typeof ch === "string" && ch) recordContentHash = ch.toLowerCase();
-        } catch {
-          // record not JSON — the payload binding already reflects that; content
-          // stays undetermined rather than throwing.
-        }
-      }
-      if (recordContentHash !== undefined) {
-        committed.push(recordContentHash);
-      } else if (ev.envelope && typeof ev.envelope === "object") {
-        // Promoted fallback. Guarded: contentHashes() dereferences env.payload,
-        // which throws on a null/non-object envelope — a verifier must never
-        // raise on adversarial input (such an event already fails via envelopeOk).
-        for (const c of contentHashes(ev.envelope)) committed.push(c.hash.toLowerCase());
-      }
-
-      // Disclosed bytes, precedence: in-body (signed) → side input. A string
-      // 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.
-        contentOk = false;
-        evErrors.push(
-          "disclosed content disagreement: in-body events[].content and the supplied content differ",
-        );
-      } else {
-        const disclosed = inBody ?? side;
-        if (disclosed === undefined || committed.length === 0) {
-          contentOk = null;
-          if (disclosed !== undefined && committed.length === 0) {
-            evErrors.push(
-              "disclosed content present but no committed content_hash to bind to " +
-                "(record withheld or record has no event.content_hash) — undetermined",
-            );
-          }
-        } else {
-          const got = await sha256Hex(disclosed);
-          contentOk = committed.includes(got);
-          if (!contentOk) {
-            evErrors.push(
-              "disclosed content does not match the committed content_hash: " +
-                `sha256(disclosed)=${got} committed=${committed.join("|")}`,
-            );
-          }
-        }
-      }
-    }
+    // Content (raw-log) binding — shared with every other event-carrying body.
+    const contentRes = await verifyDisclosedContent(ev, eventId, recordBytes, options.content);
+    const contentOk = contentRes.contentOk;
+    evErrors.push(...contentRes.errors);
 
     eventResults.push({
       eventId,
@@ -1117,6 +1233,623 @@ 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.
+ */
+// ===========================================================================
+// Disclosed-content binding, shared by every body that carries events.
+//
+// Extracted for `sanning.stamp.evidence/v1` (§5.3) rather than copied. The
+// rawLog -> content_hash link is the one step the chain
+// (content_hash -> record -> payload_hash -> signature -> leaf -> root) does
+// not otherwise cover, and a second copy of it is a second place for the
+// never-fail-on-absent discipline to drift. The rules are unchanged from the
+// anchor-trace path this came from: undetermined (null) when nothing is
+// disclosed or nothing is committed; false ONLY on a real mismatch or an
+// in-body vs side-input disagreement.
+// ===========================================================================
+async function verifyDisclosedContent(
+  ev: { envelope?: unknown; content?: unknown },
+  eventId: string,
+  recordBytes: Uint8Array | undefined,
+  sideContent: VerifyEvidenceOptions["content"],
+): Promise<{ contentOk: boolean | null; errors: string[] }> {
+  const evErrors: string[] = [];
+  let contentOk: boolean | null = null;
+
+  const committed: string[] = [];
+  let recordContentHash: string | undefined;
+  if (recordBytes !== undefined) {
+    try {
+      const record = JSON.parse(new TextDecoder().decode(recordBytes)) as {
+        event?: { content_hash?: unknown };
+      };
+      const ch = record.event?.content_hash;
+      if (typeof ch === "string" && ch) recordContentHash = ch.toLowerCase();
+    } catch {
+      // record not JSON — the payload binding already reflects that; content
+      // stays undetermined rather than throwing.
+    }
+  }
+  if (recordContentHash !== undefined) {
+    committed.push(recordContentHash);
+  } else if (ev.envelope && typeof ev.envelope === "object") {
+    // Promoted fallback. Guarded: contentHashes() dereferences env.payload,
+    // which throws on a null/non-object envelope — a verifier must never raise
+    // on adversarial input.
+    for (const c of contentHashes(ev.envelope as Envelope)) committed.push(c.hash.toLowerCase());
+  }
+
+  const selection = selectDisclosedBytes(ev as TraceEvent, eventId, sideContent);
+  const { inBody, side } = selection;
+  evErrors.push(...selection.errors);
+
+  if (inBody !== undefined && side !== undefined && !bytesEqual(inBody, side)) {
+    contentOk = false;
+    evErrors.push(
+      "disclosed content disagreement: in-body events[].content and the supplied content differ",
+    );
+  } else {
+    const disclosed = inBody ?? side;
+    if (disclosed === undefined || committed.length === 0) {
+      contentOk = null;
+      if (disclosed !== undefined && committed.length === 0) {
+        evErrors.push(
+          "disclosed content present but no committed content_hash to bind to " +
+            "(record withheld or record has no event.content_hash) — undetermined",
+        );
+      }
+    } else {
+      const got = await sha256Hex(disclosed);
+      contentOk = committed.includes(got);
+      if (!contentOk) {
+        evErrors.push(
+          "disclosed content does not match the committed content_hash: " +
+            `sha256(disclosed)=${got} committed=${committed.join("|")}`,
+        );
+      }
+    }
+  }
+  return { contentOk, errors: evErrors };
+}
+
+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,
+  };
+}
+
+// ===========================================================================
+// `sanning.stamp.evidence/v1` — the two halves, bound (evidence-bundle.md §5.3)
+//
+// The stamp half is §5.2's code unchanged (`verifyStampEntry`, which carries
+// the sub-tree partition check). The event half reuses the same primitives the
+// anchor-trace path uses — `verifyEnvelope`, `verifyInclusion`, `leafHash`,
+// `verifyDisclosedContent` — because a second copy of Merkle verification is a
+// second place for it to drift.
+//
+// What differs, and only this: the join. An event resolves `inclusion.stamp_ref`
+// to a stamps[] entry and walks its audit path to the root committed INSIDE
+// that stamp's witnessed bytes. There is no `merkle_root` field on the event to
+// read instead — repeating the root beside its own authoritative bytes would be
+// two answers to one question inside one signature (§5.1.2).
+// ===========================================================================
+async function verifyStampEvidence(
+  b: EvidenceBundle,
+  specVersionOk: boolean,
+  assertedStatus: string | null,
+  errors: string[],
+  options: VerifyEvidenceOptions,
+): Promise<EvidenceBundleResult> {
+  const body = b.body as StampEvidenceBody;
+  if (!Array.isArray(body?.stamps) || !Array.isArray(body?.events)) {
+    return malformed(`${STAMP_EVIDENCE_BODY_TYPE} body must have stamps[] and events[]`, true);
+  }
+
+  // --- The stamp half: §5.2's rules, §5.2's code ----------------------------
+  const seen = new Set<string>();
+  const stamps: StampResult[] = [];
+  for (const entry of body.stamps) stamps.push(await verifyStampEntry(entry, seen));
+
+  // The join table. ONLY a stamp whose derived ref and witnessed bytes both
+  // checked out is joinable: a root read out of bytes that failed their own
+  // verification is not a root anyone should walk a proof to, and admitting one
+  // would let a broken stamp lend its authority to an event.
+  const byRef = new Map<string, StampResult>();
+  for (const st of stamps) {
+    if (st.stampRef && st.stampRefOk && st.bodyOk) byRef.set(st.stampRef, st);
+  }
+
+  // --- The event half -------------------------------------------------------
+  const eventResults: EventResult[] = [];
+  for (const rawEv of body.events) {
+    const evErrors: string[] = [];
+    // A verifier must never RAISE on adversarial input — a caller handed a
+    // stack trace instead of a verdict cannot tell a malformed pack from a
+    // broken tool. `events[]` is attacker-shaped, so a null/non-object entry
+    // is coerced to an empty event and fails through the normal path, exactly
+    // as the Python kernel does. Found by adversarial review, not by the
+    // cross-kernel leg — whose cases did not include one, and now do.
+    if (rawEv === null || typeof rawEv !== "object" || Array.isArray(rawEv)) {
+      // NOT an event. Graded and reported as such rather than coerced to an
+      // empty one: probing verifyEnvelope with nothing asks the envelope layer
+      // a question about an object that was never an envelope, and the two
+      // kernels answer it differently (undetermined vs failed) — a real
+      // divergence, but not this body's to resolve. Reported separately.
+      eventResults.push({
+        eventId: "<unknown>",
+        envelopeOk: false,
+        payloadBindingOk: null,
+        inclusionOk: false,
+        checkpointBound: false,
+        contentOk: null,
+        ok: false,
+        errors: ["events[] entry is not an object"],
+      });
+      continue;
+    }
+    const ev = rawEv as StampEvidenceEvent;
+    const eventId = getEventId(ev.envelope);
+    let envelopeOk = false;
+    let payloadBindingOk: boolean | null = null;
+
+    let recordBytes: Uint8Array | undefined;
+    try {
+      if (typeof ev.record_bytes === "string") recordBytes = hexToBytes(ev.record_bytes);
+    } catch (e) {
+      evErrors.push(`event record_bytes is not hex: ${stringifyErr(e)}`);
+    }
+    try {
+      const res = await verifyEnvelope(
+        ev.envelope,
+        recordBytes !== undefined ? { payloadBytes: recordBytes } : {},
+      );
+      envelopeOk = res.ok; // tolerates an undetermined binding (withheld record)
+      payloadBindingOk = res.payloadHashOk;
+      if (!res.signatureOk) evErrors.push("event envelope signature failed");
+      if (res.payloadHashOk === false) evErrors.push("event record does not bind to payload_hash");
+    } catch (e) {
+      evErrors.push(`event envelope verify error: ${stringifyErr(e)}`);
+    }
+
+    // --- The join (§5.3.3 rule 1) -------------------------------------------
+    const incl = ev.inclusion as (StampEvidenceInclusion & Record<string, unknown>) | undefined;
+    let st: StampResult | undefined;
+    if (!incl || typeof incl !== "object") {
+      evErrors.push("event missing inclusion proof");
+    } else if (incl.checkpoint_ref !== undefined || incl.checkpoint_tx_id !== undefined) {
+      // One bundle speaks one vocabulary. An inclusion carrying an anchor-trace
+      // join key inside this body is a mixed bundle, and resolving it anyway is
+      // how an event silently binds to something nobody meant (§5.1.2).
+      evErrors.push(
+        `event inclusion carries an anchor-trace join key in a ${STAMP_EVIDENCE_BODY_TYPE} body`,
+      );
+    } else if (typeof incl.stamp_ref !== "string") {
+      evErrors.push("event inclusion missing stamp_ref");
+    } else {
+      st = byRef.get(incl.stamp_ref);
+      if (st === undefined) {
+        // Hard reject, never undetermined: without a resolved stamp the
+        // inclusion proof has no root to check against at all.
+        evErrors.push(
+          `event inclusion.stamp_ref ${JSON.stringify(incl.stamp_ref)} resolves to no verified stamp`,
+        );
+      }
+    }
+    const stampBound = st !== undefined;
+
+    let inclusionOk = false;
+    if (incl && stampBound && st) {
+      // Rule 3: the tree walked must be the tree the stamp committed to. A
+      // proof walked against a different leaf_count is a proof about a
+      // different tree, and RFC 9162's path shape depends on the size.
+      if (st.leafCount !== null && incl.leaf_count !== st.leafCount) {
+        evErrors.push(
+          `inclusion leaf_count ${incl.leaf_count} does not equal the stamp's committed ` +
+            `leaf_count ${st.leafCount}`,
+        );
+      } else {
+        try {
+          inclusionOk = await verifyInclusion(
+            hexToBytes(incl.leaf_hash),
+            incl.leaf_index,
+            incl.leaf_count,
+            (incl.audit_path ?? []).map((h) => hexToBytes(h)),
+            hexToBytes(st.merkleRoot ?? ""),
+          );
+          if (!inclusionOk) {
+            evErrors.push("RFC 9162 inclusion proof did not reconstruct the stamp root");
+          }
+
+          // Defense in depth, as §5.1: the claimed leaf MUST be this event's
+          // own signed envelope bytes, or a valid proof for an UNRELATED leaf
+          // could be smuggled in.
+          const expectedLeafHex = toHex(await leafHash(utf8(jcs(ev.envelope))));
+          if (expectedLeafHex !== (incl.leaf_hash ?? "").toLowerCase()) {
+            inclusionOk = false;
+            evErrors.push(
+              "inclusion leaf_hash does not match SHA-256(0x00 || JCS(event envelope))",
+            );
+          }
+        } catch (e) {
+          evErrors.push(`inclusion verify error: ${stringifyErr(e)}`);
+        }
+      }
+    }
+
+    const contentRes = await verifyDisclosedContent(ev, eventId, recordBytes, options.content);
+    const contentOk = contentRes.contentOk;
+    evErrors.push(...contentRes.errors);
+
+    eventResults.push({
+      eventId,
+      envelopeOk,
+      payloadBindingOk,
+      inclusionOk,
+      // Named for §5.1's join; here it reports whether `stamp_ref` resolved.
+      checkpointBound: stampBound,
+      contentOk,
+      ok: envelopeOk && inclusionOk && stampBound && contentOk !== false,
+      errors: evErrors,
+    });
+  }
+
+  // --- Rollup ---------------------------------------------------------------
+  // Rule 4: a declared event MUST be checked. `events[]` present and unverified
+  // is the false green this body exists to prevent, so an event that did not
+  // verify fails the bundle — it is never rolled up as verified.
+  const anyHardFailure = stamps.some((st) => !st.ok) || eventResults.some((e) => !e.ok);
+  const anyUnwitnessed = stamps.some((st) => st.anchorRef === null);
+
+  let status: EvidenceStatus;
+  if (anyHardFailure) {
+    status = "failed";
+  } else if (stamps.length === 0 && eventResults.length === 0) {
+    status = "partial";
+    errors.push(`${STAMP_EVIDENCE_BODY_TYPE} body carries no stamps and no events`);
+  } else if (anyUnwitnessed) {
+    // §5.3.3 rule 6, inherited whole from §5.2.4: for a stamp the witness IS
+    // the independent part, so the events resting on it inherit `partial`.
+    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_EVIDENCE_BODY_TYPE,
+    onChainChecked: false,
+    checkpoints: [],
+    events: eventResults,
+    assertedStatus,
+    stamps,
+    errors,
+  };
+}
+
 // ===========================================================================
 // Ingest: materializing the disclosed raw bytes (evidence-bundle.md §5.1).
 //
@@ -1306,7 +2039,13 @@ 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;