@sanning/proof 0.6.0 → 0.8.0

package/src/index.ts

@@ -64,6 +64,9 @@ export {
   ANCHOR_TRACE_BODY_TYPE_V1,
   ANCHOR_TRACE_BODY_TYPES,
   EXPORT_BODY_TYPE,
+  STAMP_BODY_VERSION,
+  STAMP_TRACE_BODY_TYPE,
+  STAMP_EVIDENCE_BODY_TYPE,
   disclosedContent,
   recomputeExportVerdict,
   verifyEvidenceBundle,
@@ -90,6 +93,15 @@ export type {
   OnChainResult,
   PerGatewayOutcome,
   AnchorRef,
+  StampBody,
+  StampEntry,
+  StampResult,
+  StampSubtree,
+  StampSubtreeResult,
+  StampTraceBody,
+  StampEvidenceBody,
+  StampEvidenceEvent,
+  StampEvidenceInclusion,
   TraceCheckpoint,
   TraceCheckpointV1,
   TraceEvent,
@@ -136,6 +148,40 @@ export type {
   PackVerdict,
 } from "./grading.js";
 
+// Chain reading (src/chain.ts): following the pointer every sanning.events/v1
+// record carries to the record before it, over the records ONE bundle presents.
+//
+// Every anchored event has carried that pointer since the profile was ratified
+// and nothing we shipped read it, so a bundle with an event removed — and a
+// chain that restarted after a crash and now asserts two beginnings — passed
+// every check we had (proof#43). The verifier was right not to do this: it
+// verifies a single envelope and says so. Nothing above it did it either.
+//
+// Pure — data in, data out, no I/O — so the kernel's scope boundary
+// (specs/architecture.md §3) is unchanged, and the rule ships as
+// `vectors/chain-reading.json` beside the pack-grading table for the same
+// reason: a rule consumers must agree with needs a statement they can fetch.
+//
+// It returns FINDINGS, never a verdict, and it feeds no status. Chain links are
+// deletion/reorder-evidence for the events present and NOT a completeness proof
+// (`anchor/docs/profile-sanning.events-v1.md` §5) — drop the last N events of a
+// chain and nothing dangles. `CHAIN_READING_SCOPE` is that sentence, exported so
+// every surface prints the same limit rather than paraphrasing it into a claim.
+// Additive — no existing export changes.
+export {
+  ADAPTER_CHAIN_NAMESPACES,
+  CHAIN_READING_SCOPE,
+  readChains,
+  renderChainFinding,
+} from "./chain.js";
+export type {
+  ChainFinding,
+  ChainFindingKind,
+  ChainReading,
+  ChainSource,
+  ChainSummary,
+} from "./chain.js";
+
 // The `proof export` composer (specs/evidence-export.md §5, phase 2): produce a
 // signed, offline-verifiable sanning.evidence.export/v1 artifact from a source
 // anchor-trace bundle + operator attestations + an exporter Ed25519 key. The

package/src/verifier.ts

@@ -228,6 +228,20 @@ export async function verifyEnvelope(
     typeof optionsOrContentHash === "string"
       ? { expectedContentHash: optionsOrContentHash }
       : (optionsOrContentHash ?? {});
+  // REFUSE an unknown option key rather than ignore it. `expected_content_hash`
+  // — the Python kernel's spelling — previously fell through as `undefined`, so
+  // the content bind silently never ran and the caller got a clean pass with no
+  // errors at all. A check that quietly does not happen is worse than one that
+  // fails: the caller believes they verified an artifact they never checked.
+  const KNOWN_VERIFY_OPTIONS = new Set(["payloadBytes", "expectedContentHash"]);
+  const unknownOptions = Object.keys(opts).filter((k) => !KNOWN_VERIFY_OPTIONS.has(k));
+  if (unknownOptions.length > 0) {
+    throw new TypeError(
+      `verifyEnvelope: unknown option(s) ${unknownOptions.join(", ")}. ` +
+        `Did you mean ${[...KNOWN_VERIFY_OPTIONS].join(" / ")}? ` +
+        "Option keys are camelCase in the TypeScript kernel; the Python kernel uses snake_case.",
+    );
+  }
   const expectedContentHash = opts.expectedContentHash;
   const errors: string[] = [];
 
@@ -313,19 +327,47 @@ export async function verifyEnvelope(
   let contentHashOk: boolean | null = null;
   let contentRole: ContentRole | null = null;
   if (expectedContentHash !== undefined) {
-    const want = expectedContentHash.toLowerCase();
-    const match = contentHashes(env).find((c) => c.hash.toLowerCase() === want);
-    contentHashOk = match !== undefined;
-    contentRole = match ? match.role : null;
-    if (!contentHashOk) {
-      errors.push("provided content hash does not match any hash this envelope commits to");
+    const committed = contentHashes(env);
+    if (committed.length === 0) {
+      // UNDETERMINED, not failed. An external-commitment envelope
+      // (`sanning.events/v1`) has no inline payload, so it commits to no
+      // envelope-readable content hash and there is nothing here to compare
+      // against. Reporting that as a failure would render "we cannot check
+      // this" as "it did not match" — what P-10 and I-5 exist to prevent — and
+      // would fail every envelope on the DL-52 path.
+      //
+      // The caller is still told the check did not happen; silence would be
+      // worse than either verdict.
+      contentHashOk = null;
+      errors.push(
+        "this envelope commits to no readable content hash (external-commitment " +
+          "profile), so the provided content hash could not be checked — " +
+          "undetermined, not failed",
+      );
+    } else {
+      const want = expectedContentHash.toLowerCase();
+      const match = committed.find((c) => c.hash.toLowerCase() === want);
+      contentHashOk = match !== undefined;
+      contentRole = match ? match.role : null;
+      if (!contentHashOk) {
+        errors.push("provided content hash does not match any hash this envelope commits to");
+      }
     }
   }
 
   return {
     // null (binding not checkable) does not fail the verdict — Python-kernel
     // parity: ok = spec && sig && payloadHashOk is not False.
-    ok: specVersionOk && signatureOk && payloadHashOk !== false,
+    // A supplied `expectedContentHash` that matches nothing this envelope
+    // commits to is a FAILING verdict, not a side note (proof#42). This is the
+    // check an external auditor runs — "does this file match what was
+    // anchored" — and reporting it only in `contentHashOk` meant the top-level
+    // verdict, the field a caller naturally reads, said pass over a file that
+    // does not match.
+    //
+    // Absence stays undetermined: `contentHashOk` is null when no hash was
+    // supplied, and null must not fail (P-10 — absence is not failure).
+    ok: specVersionOk && signatureOk && payloadHashOk !== false && contentHashOk !== false,
     specVersionOk,
     payloadHashOk,
     signatureOk,

package/vectors/chain-reading.json

@@ -0,0 +1,293 @@
+{
+  "rule": "chain-reading",
+  "ruleVersion": 1,
+  "statement": "What following an event chain DOES and DOES NOT show. Every sanning.events/v1 record points at the record before it; reading those pointers over the records a bundle presents yields deletion- and reorder-EVIDENCE for those records, and nothing else. It is not a completeness proof and no finding here is a verdict: a chain whose last events were never exported dangles nowhere, and a record that is withheld or unreadable takes no part in a chain rather than becoming an accusation. Findings are the specific links that do not resolve inside the bundle in front of the reader: chain-link-dangling, chain-gap, chain-second-root.",
+  "home": "@sanning/proof — ts/vectors/chain-reading.json. This file is the RULE, not a test fixture of one implementation. The kernel implements it in ts/src/chain.ts and is held to it by ts/test/chain.test.ts.",
+  "consumers": "A surface that follows event chains SHOULD call the kernel's readChains rather than derive the rule again. A surface that cannot yet (an older pinned kernel, another language) vendors this file byte-for-byte, asserts its own derivation against it, and runs a drift check that compares its copy against the copy shipped in the @sanning/proof tarball at vectors/chain-reading.json — and that fails when it cannot find a copy to compare against. A vendored copy that is not byte-identical to this one is a defect, not a variant.",
+  "howToUse": "Each case is a chain as it was WRITTEN, in order. Build one event record per entry from `recordScaffold`, overriding `previous_hash`, `context` and `metadata` from the entry and setting `event.content_length` to the entry's index so no two records share bytes. Canonicalize each record (RFC 8785), hex-encode the bytes as `record_bytes`, and place it in a bundle body as `{ envelope: { event_id, public_key }, record_bytes }` — in array order, SKIPPING every entry marked `dropped`. A dropped entry is still built and still hashed, because that is what deletion is: the record existed, its successor still points at it, and the pointer now leads nowhere. Then call readChains and assert `expect`.",
+  "placeholders": {
+    "@<id>": "The LINK IDENTITY of the entry with that id — for a record chain the SHA-256 of its canonical record bytes, for an adapter chain its event_id. Resolvable for dropped entries too; that is the point of them.",
+    "GENESIS": "In previous_hash: this record claims to begin its chain.",
+    "null": "In prev_event_id: this record claims to begin its adapter chain.",
+    "publicKey": "An alias, not a real Ed25519 key. The reader treats it as an opaque grouping token — a chain is one head per (public_key, chain_key), profile section 3.2 — so only its distinctness is load-bearing."
+  },
+  "adapterNamespaces": "Verified against sanning-io/anchor @ main, 2026-09-07: `run` (LangChain callbacks, TS and Python — anchor#68 promoted this out of the old `langchain` namespace), `vercel_ai` (Vercel AI SDK middleware), `interchange` (Interchange adapter). All three carry `prev_event_id` and `seq`; their chain key is `root_run_id`, `chain_key` and `session_id` respectively. These are read ONLY where the record carries no chain of its own, and they are transitional: once every adapter sets the record's own previous_hash, a reader needs no adapter knowledge at all.",
+  "recordScaffold": {
+    "payload_version": 1,
+    "spec_version": "sanning.events/v1",
+    "event_type": "langchain.tool_start",
+    "subject": { "type": "producer", "producer_id": "vector" },
+    "event": {
+      "content_hash": "5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8",
+      "content_length": 0
+    },
+    "extras": {}
+  },
+  "cases": [
+    {
+      "id": "intact-record-chain",
+      "why": "the baseline that must stay silent — four linked records, nothing to report. Asserted with the chain summary, not with an empty findings list alone: a reader that matched no records at all would also report no findings, and would pass a bare emptiness check forever.",
+      "events": [
+        { "id": "e1", "publicKey": "kA", "previous_hash": "GENESIS", "context": { "chain_key": "agent-run-1" } },
+        { "id": "e2", "publicKey": "kA", "previous_hash": "@e1", "context": { "chain_key": "agent-run-1" } },
+        { "id": "e3", "publicKey": "kA", "previous_hash": "@e2", "context": { "chain_key": "agent-run-1" } },
+        { "id": "e4", "publicKey": "kA", "previous_hash": "@e3", "context": { "chain_key": "agent-run-1" } }
+      ],
+      "expect": {
+        "chains": [
+          { "chainKey": "agent-run-1", "source": "record", "publicKey": "kA", "events": 4 }
+        ],
+        "findings": []
+      }
+    },
+    {
+      "id": "record-chain-one-event-dropped",
+      "why": "the failure the whole reader exists for. Remove one record and every SURVIVOR still verifies perfectly — signature, payload binding, inclusion proof, all green. Only the pointer shows it: e4 points at a record nobody presents.",
+      "events": [
+        { "id": "e1", "publicKey": "kA", "previous_hash": "GENESIS", "context": { "chain_key": "agent-run-1" } },
+        { "id": "e2", "publicKey": "kA", "previous_hash": "@e1", "context": { "chain_key": "agent-run-1" } },
+        { "id": "e3", "publicKey": "kA", "previous_hash": "@e2", "context": { "chain_key": "agent-run-1" }, "dropped": true },
+        { "id": "e4", "publicKey": "kA", "previous_hash": "@e3", "context": { "chain_key": "agent-run-1" } }
+      ],
+      "expect": {
+        "chains": [
+          { "chainKey": "agent-run-1", "source": "record", "publicKey": "kA", "events": 3 }
+        ],
+        "findings": [
+          {
+            "kind": "chain-link-dangling",
+            "chainKey": "agent-run-1",
+            "source": "record",
+            "publicKey": "kA",
+            "count": 1,
+            "of": 3,
+            "eventIds": ["e4"],
+            "unresolvedPointer": "@e3"
+          }
+        ]
+      }
+    },
+    {
+      "id": "record-chain-restarted",
+      "why": "a process crashed, the SDK lost its chain head, and it began again under the same chain key. A link-walk alone calls this CLEAN — both halves walk back to a legitimate GENESIS and nothing dangles — so it is caught only by counting beginnings. anchor's own envelope-anchorer documents the case and measures it: 2 GENESIS roots under one chain_key.",
+      "events": [
+        { "id": "e1", "publicKey": "kA", "previous_hash": "GENESIS", "context": { "chain_key": "agent-run-1" } },
+        { "id": "e2", "publicKey": "kA", "previous_hash": "@e1", "context": { "chain_key": "agent-run-1" } },
+        { "id": "e3", "publicKey": "kA", "previous_hash": "GENESIS", "context": { "chain_key": "agent-run-1" } },
+        { "id": "e4", "publicKey": "kA", "previous_hash": "@e3", "context": { "chain_key": "agent-run-1" } }
+      ],
+      "expect": {
+        "chains": [
+          { "chainKey": "agent-run-1", "source": "record", "publicKey": "kA", "events": 4 }
+        ],
+        "findings": [
+          {
+            "kind": "chain-second-root",
+            "chainKey": "agent-run-1",
+            "source": "record",
+            "publicKey": "kA",
+            "count": 2,
+            "of": 4,
+            "eventIds": ["e1", "e3"]
+          }
+        ]
+      }
+    },
+    {
+      "id": "record-chain-window-is-not-a-finding",
+      "why": "an export is a WINDOW onto a chain that began before it. Its earliest record necessarily points at a predecessor nobody handed us, and reporting that would put a finding on every second export until people stopped reading them. Exactly one unresolved pointer is expected where the bundle shows no GENESIS.",
+      "events": [
+        { "id": "e1", "publicKey": "kA", "previous_hash": "GENESIS", "context": { "chain_key": "agent-run-1" }, "dropped": true },
+        { "id": "e2", "publicKey": "kA", "previous_hash": "@e1", "context": { "chain_key": "agent-run-1" }, "dropped": true },
+        { "id": "e3", "publicKey": "kA", "previous_hash": "@e2", "context": { "chain_key": "agent-run-1" } },
+        { "id": "e4", "publicKey": "kA", "previous_hash": "@e3", "context": { "chain_key": "agent-run-1" } },
+        { "id": "e5", "publicKey": "kA", "previous_hash": "@e4", "context": { "chain_key": "agent-run-1" } }
+      ],
+      "expect": {
+        "chains": [
+          { "chainKey": "agent-run-1", "source": "record", "publicKey": "kA", "events": 3 }
+        ],
+        "findings": []
+      }
+    },
+    {
+      "id": "record-chain-window-with-a-drop",
+      "why": "the window allowance is spent once and only once. Three records from mid-chain, one of them removed: the earliest unresolved pointer is the window edge, the second is a deletion, and only the second is reported.",
+      "events": [
+        { "id": "e1", "publicKey": "kA", "previous_hash": "GENESIS", "context": { "chain_key": "agent-run-1" }, "dropped": true },
+        { "id": "e2", "publicKey": "kA", "previous_hash": "@e1", "context": { "chain_key": "agent-run-1" }, "dropped": true },
+        { "id": "e3", "publicKey": "kA", "previous_hash": "@e2", "context": { "chain_key": "agent-run-1" } },
+        { "id": "e4", "publicKey": "kA", "previous_hash": "@e3", "context": { "chain_key": "agent-run-1" }, "dropped": true },
+        { "id": "e5", "publicKey": "kA", "previous_hash": "@e4", "context": { "chain_key": "agent-run-1" } }
+      ],
+      "expect": {
+        "chains": [
+          { "chainKey": "agent-run-1", "source": "record", "publicKey": "kA", "events": 2 }
+        ],
+        "findings": [
+          {
+            "kind": "chain-link-dangling",
+            "chainKey": "agent-run-1",
+            "source": "record",
+            "publicKey": "kA",
+            "count": 1,
+            "of": 2,
+            "eventIds": ["e5"],
+            "unresolvedPointer": "@e4"
+          }
+        ]
+      }
+    },
+    {
+      "id": "unchained-singletons-are-not-a-chain",
+      "why": "an anchor call with no chain is a singleton and its record says GENESIS (profile section 5). Every singleton a producer ever wrote says GENESIS, so a reader that grouped on the pointer alone would assemble one enormous fictional chain and report a second root for every pair of unrelated events. context.chain_key is present IFF the record is chained, and that is what gates grouping.",
+      "events": [
+        { "id": "e1", "publicKey": "kA", "previous_hash": "GENESIS", "context": {} },
+        { "id": "e2", "publicKey": "kA", "previous_hash": "GENESIS", "context": {} },
+        { "id": "e3", "publicKey": "kA", "previous_hash": "GENESIS", "context": {} }
+      ],
+      "expect": { "chains": [], "findings": [] }
+    },
+    {
+      "id": "same-chain-name-two-producers",
+      "why": "a chain is one head per (public_key, chain_key). Two producers that both call their chain session-1 are two chains, and merging them would manufacture a second root out of a naming coincidence.",
+      "events": [
+        { "id": "e1", "publicKey": "kA", "previous_hash": "GENESIS", "context": { "chain_key": "session-1" } },
+        { "id": "e2", "publicKey": "kB", "previous_hash": "GENESIS", "context": { "chain_key": "session-1" } }
+      ],
+      "expect": {
+        "chains": [
+          { "chainKey": "session-1", "source": "record", "publicKey": "kA", "events": 1 },
+          { "chainKey": "session-1", "source": "record", "publicKey": "kB", "events": 1 }
+        ],
+        "findings": []
+      }
+    },
+    {
+      "id": "intact-adapter-chain-run",
+      "why": "the batched LangChain path writes its linkage only in metadata; its records all say GENESIS and carry no chain_key. Three of them must read as ONE chain with nothing to report — not as three roots of a fictional one. The namespace is `run`, not `langchain`: anchor#68 moved it, and a reader still pinned on the old name would find no chain here and report nothing, which is indistinguishable from a clean bundle.",
+      "events": [
+        { "id": "e1", "publicKey": "kA", "previous_hash": "GENESIS", "context": {}, "metadata": { "run": { "run_id": "r1", "parent_run_id": null, "root_run_id": "root-1", "seq": 0, "prev_event_id": null } } },
+        { "id": "e2", "publicKey": "kA", "previous_hash": "GENESIS", "context": {}, "metadata": { "run": { "run_id": "r2", "parent_run_id": "r1", "root_run_id": "root-1", "seq": 1, "prev_event_id": "@e1" } } },
+        { "id": "e3", "publicKey": "kA", "previous_hash": "GENESIS", "context": {}, "metadata": { "run": { "run_id": "r3", "parent_run_id": "r1", "root_run_id": "root-1", "seq": 2, "prev_event_id": "@e2" } } }
+      ],
+      "expect": {
+        "chains": [
+          { "chainKey": "root-1", "source": "adapter", "namespace": "run", "publicKey": "kA", "events": 3 }
+        ],
+        "findings": []
+      }
+    },
+    {
+      "id": "adapter-chain-one-event-dropped-run",
+      "why": "a deletion on the adapter path shows twice, and both are worth saying: the pointer dangles AND the sequence has a hole. anchor's own comment is that the slot is burned BEFORE the hash, so a dropped event consumed a seq number and leaves a permanent gap.",
+      "events": [
+        { "id": "e1", "publicKey": "kA", "previous_hash": "GENESIS", "context": {}, "metadata": { "run": { "run_id": "r1", "parent_run_id": null, "root_run_id": "root-1", "seq": 0, "prev_event_id": null } } },
+        { "id": "e2", "publicKey": "kA", "previous_hash": "GENESIS", "context": {}, "metadata": { "run": { "run_id": "r2", "parent_run_id": "r1", "root_run_id": "root-1", "seq": 1, "prev_event_id": "@e1" } } },
+        { "id": "e3", "publicKey": "kA", "previous_hash": "GENESIS", "context": {}, "metadata": { "run": { "run_id": "r3", "parent_run_id": "r1", "root_run_id": "root-1", "seq": 2, "prev_event_id": "@e2" } }, "dropped": true },
+        { "id": "e4", "publicKey": "kA", "previous_hash": "GENESIS", "context": {}, "metadata": { "run": { "run_id": "r4", "parent_run_id": "r1", "root_run_id": "root-1", "seq": 3, "prev_event_id": "@e3" } } }
+      ],
+      "expect": {
+        "chains": [
+          { "chainKey": "root-1", "source": "adapter", "namespace": "run", "publicKey": "kA", "events": 3 }
+        ],
+        "findings": [
+          {
+            "kind": "chain-link-dangling",
+            "chainKey": "root-1",
+            "source": "adapter",
+            "namespace": "run",
+            "publicKey": "kA",
+            "count": 1,
+            "of": 3,
+            "eventIds": ["e4"],
+            "unresolvedPointer": "@e3"
+          },
+          {
+            "kind": "chain-gap",
+            "chainKey": "root-1",
+            "source": "adapter",
+            "namespace": "run",
+            "publicKey": "kA",
+            "count": 1,
+            "of": 3,
+            "eventIds": ["e4"],
+            "firstMissingSeq": 2
+          }
+        ]
+      }
+    },
+    {
+      "id": "adapter-window-starting-mid-sequence-vercel",
+      "why": "only INTERIOR holes are gaps. A window that starts at seq 7 is a window, and reporting its first seven absent slots as missing records would bury the one hole that means something. Pairs with the dangling window rule: the earliest record's pointer leaves the bundle and that is expected.",
+      "events": [
+        { "id": "e0", "publicKey": "kA", "previous_hash": "GENESIS", "context": {}, "metadata": { "vercel_ai": { "chain_key": "req-9", "caller_supplied_chain": true, "seq": 6, "prev_event_id": null } }, "dropped": true },
+        { "id": "e1", "publicKey": "kA", "previous_hash": "GENESIS", "context": {}, "metadata": { "vercel_ai": { "chain_key": "req-9", "caller_supplied_chain": true, "seq": 7, "prev_event_id": "@e0" } } },
+        { "id": "e2", "publicKey": "kA", "previous_hash": "GENESIS", "context": {}, "metadata": { "vercel_ai": { "chain_key": "req-9", "caller_supplied_chain": true, "seq": 8, "prev_event_id": "@e1" } } },
+        { "id": "e3", "publicKey": "kA", "previous_hash": "GENESIS", "context": {}, "metadata": { "vercel_ai": { "chain_key": "req-9", "caller_supplied_chain": true, "seq": 9, "prev_event_id": "@e2" } } }
+      ],
+      "expect": {
+        "chains": [
+          { "chainKey": "req-9", "source": "adapter", "namespace": "vercel_ai", "publicKey": "kA", "events": 3 }
+        ],
+        "findings": []
+      }
+    },
+    {
+      "id": "interchange-gap-without-a-dangling-link",
+      "why": "Interchange passes through its own reactor-owned seq, and a record the caller opted out of is never committed — so the adapter does not advance the pointer for it. The result is a hole in the sequence with an INTACT link chain, which is why the two causes are separate findings and not one. A reader that only walked pointers would see nothing here.",
+      "events": [
+        { "id": "e1", "publicKey": "kA", "previous_hash": "GENESIS", "context": {}, "metadata": { "interchange": { "session_id": "sess-3", "call_id": "c1", "seq": 0, "tool": "search", "blocked": false, "prev_event_id": null } } },
+        { "id": "e2", "publicKey": "kA", "previous_hash": "GENESIS", "context": {}, "metadata": { "interchange": { "session_id": "sess-3", "call_id": "c2", "seq": 1, "tool": "search", "blocked": false, "prev_event_id": "@e1" } } },
+        { "id": "e4", "publicKey": "kA", "previous_hash": "GENESIS", "context": {}, "metadata": { "interchange": { "session_id": "sess-3", "call_id": "c4", "seq": 3, "tool": "search", "blocked": false, "prev_event_id": "@e2" } } }
+      ],
+      "expect": {
+        "chains": [
+          { "chainKey": "sess-3", "source": "adapter", "namespace": "interchange", "publicKey": "kA", "events": 3 }
+        ],
+        "findings": [
+          {
+            "kind": "chain-gap",
+            "chainKey": "sess-3",
+            "source": "adapter",
+            "namespace": "interchange",
+            "publicKey": "kA",
+            "count": 1,
+            "of": 3,
+            "eventIds": ["e4"],
+            "firstMissingSeq": 2
+          }
+        ]
+      }
+    },
+    {
+      "id": "the-record-chain-wins-over-adapter-metadata",
+      "why": "the envelope path sets BOTH the record's own previous_hash and the adapter metadata. One record must land in one chain, and it must be the one a third party can walk from the spec alone — otherwise the same events are counted twice and every chain reads as two.",
+      "events": [
+        { "id": "e1", "publicKey": "kA", "previous_hash": "GENESIS", "context": { "chain_key": "root-1" }, "metadata": { "run": { "run_id": "r1", "parent_run_id": null, "root_run_id": "root-1", "seq": 0, "prev_event_id": null } } },
+        { "id": "e2", "publicKey": "kA", "previous_hash": "@e1", "context": { "chain_key": "root-1" }, "metadata": { "run": { "run_id": "r2", "parent_run_id": "r1", "root_run_id": "root-1", "seq": 1, "prev_event_id": "@e1" } } }
+      ],
+      "expect": {
+        "chains": [
+          { "chainKey": "root-1", "source": "record", "publicKey": "kA", "events": 2 }
+        ],
+        "findings": []
+      }
+    },
+    {
+      "id": "withheld-records-take-no-part",
+      "why": "a bundle may present an event with its record withheld (minimal disclosure). A link we cannot read is UNKNOWN, never an accusation — verifyEvidenceBundle already reports the binding as undetermined, and a second, harsher finding for the same fact would be the false-integrity failure in reverse. The chain that IS readable is still read.",
+      "events": [
+        { "id": "e1", "publicKey": "kA", "previous_hash": "GENESIS", "context": { "chain_key": "agent-run-1" } },
+        { "id": "e2", "publicKey": "kA", "previous_hash": "@e1", "context": { "chain_key": "agent-run-1" }, "withheld": true },
+        { "id": "e3", "publicKey": "kA", "previous_hash": "@e2", "context": { "chain_key": "agent-run-1" }, "withheld": true }
+      ],
+      "expect": {
+        "chains": [
+          { "chainKey": "agent-run-1", "source": "record", "publicKey": "kA", "events": 1 }
+        ],
+        "findings": []
+      }
+    }
+  ]
+}