@sanning/proof 0.6.0 → 0.8.0

package/dist/index.d.ts

@@ -2,10 +2,12 @@ export { ACCEPTED_SPEC_MAJORS, contentHashes, jcs, specVersionSupported, verifyE
 export { bytesToHex, deriveOperatorAddress, ed25519Verify, hexToBytes, sha256Bytes, sha256Hex, utf8, verifyRsaPssSha256, } from "./crypto.js";
 export { EMPTY_TREE_ROOT_HEX, auditPath, leafHash, merkleRoot, nodeHash, verifyInclusion, } from "./merkle.js";
 export type { ContentRole, Envelope, Subject, VerificationResult, VerifyOptions } from "./types.js";
-export { ANCHOR_TRACE_BODY_TYPE, ANCHOR_TRACE_BODY_TYPE_V1, ANCHOR_TRACE_BODY_TYPES, EXPORT_BODY_TYPE, disclosedContent, recomputeExportVerdict, verifyEvidenceBundle, } from "./evidence.js";
-export type { AnchorTraceBody, AttestationPayload, AttestationRecord, AttestationResult, CheckpointResult, ComposeVerdictResult, DisclosedContentResult, DisclosedEventContent, DisclosureStatus, EvidenceBundle, EvidenceBundleResult, EvidenceIssuer, EvidenceStatus, EvidenceVerdict, EventResult, ExportBody, ExportResult, OnChainOutcome, OnChainResult, PerGatewayOutcome, AnchorRef, TraceCheckpoint, TraceCheckpointV1, TraceEvent, TraceInclusion, VerdictAttestation, VerdictCheckpoint, VerdictEvent, VerdictObject, VerdictOnChain, VerdictOnChainGateway, VerifyEvidenceOptions, } from "./evidence.js";
+export { ANCHOR_TRACE_BODY_TYPE, 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, } from "./evidence.js";
+export type { AnchorTraceBody, AttestationPayload, AttestationRecord, AttestationResult, CheckpointResult, ComposeVerdictResult, DisclosedContentResult, DisclosedEventContent, DisclosureStatus, EvidenceBundle, EvidenceBundleResult, EvidenceIssuer, EvidenceStatus, EvidenceVerdict, EventResult, ExportBody, ExportResult, OnChainOutcome, OnChainResult, PerGatewayOutcome, AnchorRef, StampBody, StampEntry, StampResult, StampSubtree, StampSubtreeResult, StampTraceBody, StampEvidenceBody, StampEvidenceEvent, StampEvidenceInclusion, TraceCheckpoint, TraceCheckpointV1, TraceEvent, TraceInclusion, VerdictAttestation, VerdictCheckpoint, VerdictEvent, VerdictObject, VerdictOnChain, VerdictOnChainGateway, VerifyEvidenceOptions, } from "./evidence.js";
 export { accountDisclosure, completenessNotes, gradeCauses, gradePack, renderCause, signedLeafCount, } from "./grading.js";
 export type { CompletenessNote, DisclosureAccount, GradeInput, PackGrade, PackGradeCause, PackGradeCauseKind, PackVerdict, } from "./grading.js";
+export { ADAPTER_CHAIN_NAMESPACES, CHAIN_READING_SCOPE, readChains, renderChainFinding, } from "./chain.js";
+export type { ChainFinding, ChainFindingKind, ChainReading, ChainSource, ChainSummary, } from "./chain.js";
 export { attestationSignatureToHex, composeExport } from "./compose.js";
 export type { ComposeExportOptions, ComposeExportResult, ExporterKey } from "./compose.js";
 export { AGENT_PROOF_SPEC_PREFIX, isAgentProofSpec, verifyAgentProofBundle } from "./agent-proof.js";

package/dist/index.js

@@ -34,7 +34,7 @@ export { EMPTY_TREE_ROOT_HEX, auditPath, leafHash, merkleRoot, nodeHash, verifyI
 // files that failed verification on genuine evidence. This hands back DECODED
 // bytes, and only for events whose verification bound them to the committed
 // content_hash. Additive; verifyEvidenceBundle's behavior is unchanged.
-export { ANCHOR_TRACE_BODY_TYPE, ANCHOR_TRACE_BODY_TYPE_V1, ANCHOR_TRACE_BODY_TYPES, EXPORT_BODY_TYPE, disclosedContent, recomputeExportVerdict, verifyEvidenceBundle, } from "./evidence.js";
+export { ANCHOR_TRACE_BODY_TYPE, 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, } from "./evidence.js";
 // Pack grading (src/grading.ts): what a verification SURFACE may claim about a
 // pack — the signed bundle PLUS whatever disclosed bytes travelled beside it.
 //
@@ -51,6 +51,27 @@ export { ANCHOR_TRACE_BODY_TYPE, ANCHOR_TRACE_BODY_TYPE_V1, ANCHOR_TRACE_BODY_TY
 // derivation to it, and diff its copy against ours. Additive — no existing
 // export changes.
 export { accountDisclosure, completenessNotes, gradeCauses, gradePack, renderCause, signedLeafCount, } 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";
 // 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/dist/verifier.js

@@ -215,6 +215,18 @@ export async function verifyEnvelope(env, optionsOrContentHash) {
     const opts = 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 = [];
     // Guard a malformed input (null / non-object / array) up front — every field
@@ -296,18 +308,45 @@ export async function verifyEnvelope(env, optionsOrContentHash) {
     let contentHashOk = null;
     let contentRole = 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanning/proof",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "TypeScript kernel of the Sanning verification stack: RFC 8785 (JCS) canonicalization, SHA-256, and Ed25519 verification for Verifiable Event Envelopes. Full-family verifier (inline + external commitment); accepts sanning.agent/v1, sanning.mlflow/v1, sanning.events/v1. Conformance-gated byte-for-byte against the test-vectors corpus.",
   "license": "MIT",
   "type": "module",

package/src/chain.ts

@@ -0,0 +1,500 @@
+// Chain reading — following the pointer every anchored event carries to the
+// event before it, and reporting what does not line up.
+//
+// WHY THIS LIVES IN THE KERNEL, BESIDE PACK GRADING.
+// `sanning.events/v1` records carry `previous_hash`, and until now nothing we
+// shipped read it. The envelope verifier hashes each event's `record_bytes`
+// and stops — `evidence.ts` says following the link is "consumer-layer logic
+// above it", and it was right that a SINGLE-envelope verifier should not do
+// it. But the consumer layer never did it either, so a bundle with an event
+// removed, and a chain that restarted after a crash and now asserts two
+// beginnings, both passed every shipped check (proof#43).
+//
+// Reading the link is not envelope verification and it is not pack grading: it
+// is a third, pure rule over the records a bundle presents. Same seam as
+// grading — data in, data out, no `fs`, no `fetch` — so the kernel's scope
+// boundary (`specs/architecture.md` §3) is unchanged.
+//
+// ---- WHAT THIS IS NOT ------------------------------------------------------
+//
+// It is not a completeness statement and it must never be read as one. The
+// profile says so in its own words (`anchor/docs/profile-sanning.events-v1.md`
+// §5): chain semantics are "deletion/reorder-evidence for the events present
+// ... not a completeness proof." Drop the last N events of a chain and nothing
+// here dangles; the record that would have pointed at them was never written.
+// Completeness is the checkpoint `leaf_count` mechanism, which lives in
+// `grading.ts` and answers a different question.
+//
+// So nothing in this module returns a verdict, a status, an `ok`, or the word
+// "complete". It returns FINDINGS — each one a specific link that does not
+// resolve within the bundle in front of us — and a count of the chains it read,
+// so a surface can tell "nothing to report" apart from "read nothing".
+//
+// ---- HOW A CHAIN IS IDENTIFIED ---------------------------------------------
+//
+// A chain is one head per `(public_key, chain_key)` — profile §3.2, and the
+// reason `public_key` is part of every group key below. Two producers using the
+// chain name "session-1" are two chains; merging them would manufacture a
+// second root out of a naming coincidence.
+//
+// The linkage is written two ways today, and this reads both:
+//
+//   1. THE RECORD'S OWN CHAIN (`previous_hash` + `context.chain_key`). The
+//      profile's mechanism, and the one a third party can walk from the spec
+//      alone. Links resolve in PAYLOAD-HASH space.
+//   2. THE ADAPTER'S METADATA (`metadata.<namespace>.prev_event_id` + `seq`).
+//      The batched paths write the linkage only here; their records say
+//      GENESIS. Links resolve in EVENT-ID space. Read as a FALLBACK, only when
+//      the record carries no chain of its own.
+//
+// (2) is a transitional accommodation, not the design. `metadata` is
+// caller-owned and the profile says a verifier MUST NOT read it for
+// verification — which is exactly why nothing here feeds a verdict. The fix is
+// for every adapter to set the record's own `previous_hash` (filed separately
+// against `anchor`); when it lands, the namespace table below stops mattering
+// and can go.
+
+import { hexToBytes, sha256Hex } from "./crypto.js";
+import { resolveTraceEvents } from "./evidence.js";
+
+/**
+ * The one sentence a surface should print beside these findings, so the reader
+ * is never left to infer that "no findings" means "nothing is missing".
+ *
+ * Lifted from the profile (§5) rather than reworded, because a paraphrase of a
+ * scope limit is how a scope limit turns into a claim.
+ */
+export const CHAIN_READING_SCOPE =
+  "Chain links are deletion/reorder-evidence for the events present; they are not a completeness proof.";
+
+/** Where the linkage was read from. */
+export type ChainSource = "record" | "adapter";
+
+/**
+ * The adapter metadata namespaces that carry a chain when the record does not.
+ *
+ * VERIFIED AGAINST `sanning-io/anchor` @ main, 2026-09-07. `run` is NOT a typo
+ * for `langchain`: anchor#68 promoted the LangChain linkage out of a
+ * framework-named namespace into a shared one, so the same fact has one path in
+ * every SDK. A table pinned on the old name would find no chains, report
+ * nothing, and look exactly like a clean bundle — the rename trap, in the
+ * direction that fails silently.
+ *
+ * Exported so a test can assert the table itself, and so a consumer can see
+ * what this reader knows about rather than guessing.
+ */
+export const ADAPTER_CHAIN_NAMESPACES: readonly { namespace: string; keyField: string }[] = [
+  // @sanning/anchor LangChain callbacks, TS + Python (anchor#68). One chain per
+  // root run, so the root run id is the chain.
+  { namespace: "run", keyField: "root_run_id" },
+  // @sanning/anchor Vercel AI SDK middleware. A flat sequence per correlation key.
+  { namespace: "vercel_ai", keyField: "chain_key" },
+  // @sanning/anchor Interchange adapter. One chain per session; `seq` is
+  // Interchange's own reactor-owned sequence, passed through.
+  { namespace: "interchange", keyField: "session_id" },
+];
+
+export type ChainFindingKind =
+  /** A record points at a predecessor no record in this bundle presents. */
+  | "chain-link-dangling"
+  /** A `seq` slot between two records this bundle presents has no record. */
+  | "chain-gap"
+  /** More than one record claims to begin the chain. */
+  | "chain-second-root";
+
+/**
+ * One link that does not resolve, as data.
+ *
+ * Structured for the same reason `PackGradeCause` is: prose is the part that
+ * drifts hardest between surfaces and matters least. `renderChainFinding`
+ * produces the house wording; a surface with its own voice reads the fields.
+ */
+export interface ChainFinding {
+  kind: ChainFindingKind;
+  /** The chain this is about, as the records spell it. */
+  chainKey: string;
+  /** Whether the linkage came from the record core or an adapter namespace. */
+  source: ChainSource;
+  /** The adapter metadata namespace, when `source` is `"adapter"`. */
+  namespace?: string;
+  /** The producing key, since a chain is one head per (public_key, chain_key). */
+  publicKey: string;
+  /** How many links, slots or roots the finding is about. */
+  count: number;
+  /** How many records this bundle presents for the chain, framing `count`. */
+  of: number;
+  /** The affected `event_id`s, so a reader has somewhere to look. */
+  eventIds: string[];
+  /** The pointer that resolved to no record here (`chain-link-dangling`). */
+  unresolvedPointer?: string;
+  /** The first sequence slot with no record here (`chain-gap`). */
+  firstMissingSeq?: number;
+}
+
+/**
+ * One chain this bundle presents records for.
+ *
+ * `events` is HOW MANY RECORDS ARE HERE — never how many the chain has. The
+ * summary exists so a surface can say "read 3 chains, nothing to report"
+ * instead of "nothing to report", which is also what a reader that silently
+ * matched no records would say.
+ */
+export interface ChainSummary {
+  chainKey: string;
+  source: ChainSource;
+  namespace?: string;
+  publicKey: string;
+  events: number;
+}
+
+export interface ChainReading {
+  chains: ChainSummary[];
+  findings: ChainFinding[];
+}
+
+// ---- Reading the records -----------------------------------------------------
+
+interface EventRecord {
+  previous_hash?: unknown;
+  context?: { chain_key?: unknown };
+  metadata?: Record<string, unknown>;
+}
+
+/** One record's place in one chain, normalised across the two linkage forms. */
+interface Member {
+  eventId: string;
+  /** What the NEXT record's pointer must equal: payload hash, or event id. */
+  selfId: string;
+  /** The pointer this record carries, or `null` when it claims to begin the chain. */
+  prev: string | null;
+  seq: number | null;
+  /** Position in `body.events`, the tiebreak when there is no `seq`. */
+  order: number;
+}
+
+interface Group {
+  chainKey: string;
+  source: ChainSource;
+  namespace?: string;
+  publicKey: string;
+  members: Member[];
+}
+
+/**
+ * The events this bundle is about, unwrapping any evidence-export wrapper to
+ * the inline source bundle. DEFERRED to `evidence.ts`, which is the same
+ * descent `verifyEvidenceBundle` and `disclosedContent` already use — a second
+ * answer to "which events" inside one kernel is a second implementation of one
+ * rule, and it is how a reader ends up walking a different set of events than
+ * the verifier reported on.
+ */
+const eventsOf = (bundle: unknown) => resolveTraceEvents(bundle) ?? [];
+
+/**
+ * Decode one event record from its committed bytes.
+ *
+ * Same discipline as `signedLeafCount`: hex, UTF-8, JSON, and an undecodable
+ * record is `null` rather than a throw or a guess. A withheld or unreadable
+ * record simply takes no part in a chain — `verifyEvidenceBundle` already
+ * reports its binding as undetermined, and inventing a second accusation here
+ * would say the same thing twice in a harsher voice.
+ */
+function decodeRecord(hex: unknown): { record: EventRecord; bytes: Uint8Array } | null {
+  if (typeof hex !== "string" || hex.length === 0) return null;
+  try {
+    const bytes = hexToBytes(hex);
+    const record = JSON.parse(new TextDecoder().decode(bytes)) as EventRecord;
+    if (record === null || typeof record !== "object") return null;
+    return { record, bytes };
+  } catch {
+    return null;
+  }
+}
+
+const str = (v: unknown): string | null => (typeof v === "string" && v.length > 0 ? v : null);
+
+/**
+ * The adapter linkage, if this record carries one this reader knows about.
+ *
+ * Order is the table's order and the first match wins; a record carrying two
+ * adapter namespaces is not a shape any SDK emits.
+ */
+function adapterLinkage(
+  record: EventRecord,
+): { namespace: string; chainKey: string; prev: string | null; seq: number | null } | null {
+  const metadata = record.metadata;
+  if (metadata === null || typeof metadata !== "object") return null;
+  for (const { namespace, keyField } of ADAPTER_CHAIN_NAMESPACES) {
+    const ns = (metadata as Record<string, unknown>)[namespace];
+    if (ns === null || typeof ns !== "object") continue;
+    const fields = ns as Record<string, unknown>;
+    const chainKey = str(fields[keyField]);
+    if (chainKey === null) continue;
+    // `prev_event_id` is explicitly null at the head of an adapter chain — the
+    // adapters write the null rather than omitting the key, because absent and
+    // null mean different things to a reader. Absent is treated the same way
+    // here: nothing to resolve is a beginning.
+    const prev = str(fields.prev_event_id);
+    const seqRaw = fields.seq;
+    // SAFE integer, not merely integral. Beyond 2^53 a JSON number does not
+    // survive `JSON.parse` intact — `9007199254740993` arrives as
+    // `...992` — while Python's parser keeps it exactly, so the two kernels
+    // read DIFFERENT sequence numbers off identical bytes and report gaps of
+    // different widths. Measured at 2^53+1: a `chain-gap` count of
+    // 9007199254740990 here against 9007199254740992 there (proof#49). A value
+    // this kernel cannot represent is one it cannot read, which is the same
+    // answer it gives every other unreadable field: no sequence, take no part.
+    const seq = Number.isSafeInteger(seqRaw) ? (seqRaw as number) : null;
+    return { namespace, chainKey, prev, seq };
+  }
+  return null;
+}
+
+/**
+ * Group the bundle's records into chains.
+ *
+ * Self-ids are DERIVED, never read off the envelope. A record chain's pointer
+ * is the previous record's `payload_hash`, and `payload_hash` is an asserted
+ * label sitting next to the bytes it claims to be about; matching one asserted
+ * label against another is how a relabelled checkpoint once verified cleanly
+ * (`evidence.ts`, `checkpoint_ref`). Hashing the bytes we already hold costs
+ * nothing and means a relabelled record DANGLES instead of quietly resolving.
+ * That is why this function is async.
+ */
+async function groupChains(bundle: unknown): Promise<Group[]> {
+  const groups = new Map<string, Group>();
+  const events = eventsOf(bundle);
+
+  for (let order = 0; order < events.length; order++) {
+    const entry = events[order];
+    const eventId = str(entry?.envelope?.event_id);
+    const publicKey = str(entry?.envelope?.public_key);
+    // Without a producing key there is no chain identity (§3.2), and without an
+    // event id an adapter pointer has nothing to resolve against.
+    if (eventId === null || publicKey === null) continue;
+
+    const decoded = decodeRecord(entry?.record_bytes);
+    if (decoded === null) continue;
+    const { record, bytes } = decoded;
+
+    // 1. The record's own chain. `context.chain_key` is present IFF the record
+    //    is chained (profile §5) — which is what keeps every unchained
+    //    singleton, all of them carrying `previous_hash: "GENESIS"`, out of one
+    //    enormous fictional chain that would report a second root per pair.
+    const recordChainKey = str(record.context?.chain_key);
+    let member: Member;
+    let key: string;
+    let group: Omit<Group, "members">;
+
+    if (recordChainKey !== null) {
+      const previous = str(record.previous_hash);
+      member = {
+        eventId,
+        selfId: await sha256Hex(bytes),
+        prev: previous === null || previous === "GENESIS" ? null : previous,
+        seq: null,
+        order,
+      };
+      group = { chainKey: recordChainKey, source: "record", publicKey };
+      key = `record ${publicKey} ${recordChainKey}`;
+    } else {
+      // 2. Fallback only. A record that carries its own chain is never read
+      //    through its adapter metadata: one record must not land in two
+      //    chains, and the profile's own field is the one a third party can
+      //    walk without knowing which SDK wrote it.
+      const linkage = adapterLinkage(record);
+      if (linkage === null) continue;
+      member = { eventId, selfId: eventId, prev: linkage.prev, seq: linkage.seq, order };
+      group = {
+        chainKey: linkage.chainKey,
+        source: "adapter",
+        namespace: linkage.namespace,
+        publicKey,
+      };
+      key = `adapter ${linkage.namespace} ${publicKey} ${linkage.chainKey}`;
+    }
+
+    const existing = groups.get(key);
+    if (existing === undefined) groups.set(key, { ...group, members: [member] });
+    else existing.members.push(member);
+  }
+
+  return [...groups.values()];
+}
+
+// ---- The rule ----------------------------------------------------------------
+
+/** By `seq` where both have one, else by position in the bundle. */
+function byChainOrder(a: Member, b: Member): number {
+  if (a.seq !== null && b.seq !== null && a.seq !== b.seq) return a.seq - b.seq;
+  return a.order - b.order;
+}
+
+/**
+ * The smallest slot between the lowest and highest occupied ones that no record
+ * occupies, found by walking the SORTED occupants rather than the range they
+ * span. See the call site: the range's width is chosen by whoever wrote the
+ * bundle.
+ */
+function firstMissingSlot(present: Set<number>): number | null {
+  const ordered = [...present].sort((a, b) => a - b);
+  for (let i = 0; i < ordered.length - 1; i++) {
+    if (ordered[i + 1]! > ordered[i]! + 1) return ordered[i]! + 1;
+  }
+  return null;
+}
+
+function findingsFor(group: Group): ChainFinding[] {
+  const { members, chainKey, source, publicKey } = group;
+  const of = members.length;
+  const base = {
+    chainKey,
+    source,
+    publicKey,
+    of,
+    ...(group.namespace === undefined ? {} : { namespace: group.namespace }),
+  };
+  const findings: ChainFinding[] = [];
+
+  const selfIds = new Set(members.map((m) => m.selfId));
+  const roots = members.filter((m) => m.prev === null).sort(byChainOrder);
+  const dangling = members
+    .filter((m): m is Member & { prev: string } => m.prev !== null && !selfIds.has(m.prev))
+    .sort(byChainOrder);
+
+  // A SECOND BEGINNING. One chain has one head per (public_key, chain_key), so
+  // two records claiming GENESIS under one key is a fork — the case a link-walk
+  // alone reports as CLEAN, because both halves walk back to a legitimate
+  // beginning and neither dangles. It is what a crash looks like when the SDK
+  // lost its chain head and started over under the same name.
+  if (roots.length > 1) {
+    findings.push({
+      kind: "chain-second-root",
+      ...base,
+      count: roots.length,
+      eventIds: roots.map((m) => m.eventId),
+    });
+  }
+
+  // A POINTER THAT LEAVES THIS BUNDLE. Exactly one such pointer is expected and
+  // is NOT a finding: a bundle is a window onto a chain that may have begun
+  // before this export, so the window's earliest record necessarily points at a
+  // predecessor nobody handed us. The allowance is spent only when the chain
+  // shows no GENESIS root — a chain that already has its beginning here has no
+  // window edge left to explain the next one.
+  const unexplained = roots.length === 0 ? dangling.slice(1) : dangling;
+  if (unexplained.length > 0) {
+    const first = unexplained[0]!;
+    findings.push({
+      kind: "chain-link-dangling",
+      ...base,
+      count: unexplained.length,
+      eventIds: unexplained.map((m) => m.eventId),
+      unresolvedPointer: first.prev,
+    });
+  }
+
+  // A HOLE IN THE SEQUENCE, where an adapter numbers its events. Only INTERIOR
+  // holes count: a window that starts at seq 7 is a window, not a deletion, and
+  // reporting its first six absent slots would bury the one that matters. A
+  // repeated seq is a real defect but a different one, and the present-set below
+  // is deliberately duplicate-safe rather than count-based so it cannot be
+  // mistaken for a gap.
+  const sequenced = members.filter((m) => m.seq !== null);
+  if (sequenced.length === of && of > 0) {
+    const present = new Set(sequenced.map((m) => m.seq as number));
+    const low = Math.min(...present);
+    const high = Math.max(...present);
+    // Counted, never walked. `seq` is attacker-chosen, so a bundle presenting
+    // two records at seq 0 and seq 1e15 made the old `for (let s = low; s <=
+    // high; s++)` spin for days — a verifier that HANGS on adversarial input is
+    // worse than one that raises, and this reader promises neither (proof#49).
+    // The present set is a subset of [low, high], so the absent slots are the
+    // width minus the occupants, and the first of them is found by walking the
+    // occupants in order.
+    const missingCount = high - low + 1 - present.size;
+    const firstMissing = missingCount > 0 ? firstMissingSlot(present) : null;
+    if (firstMissing !== null) {
+      const after = sequenced.filter((m) => (m.seq as number) > firstMissing).sort(byChainOrder)[0];
+      findings.push({
+        kind: "chain-gap",
+        ...base,
+        count: missingCount,
+        eventIds: after === undefined ? [] : [after.eventId],
+        firstMissingSeq: firstMissing,
+      });
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Follow every chain the bundle's records describe, and report the links that
+ * do not resolve within it.
+ *
+ * Reports NOTHING for an intact chain, and nothing for a chain whose records
+ * are withheld — a link we could not read is unknown, never an accusation.
+ * `chains` is what makes that distinguishable from having read nothing at all.
+ */
+export async function readChains(bundle: unknown): Promise<ChainReading> {
+  const groups = await groupChains(bundle);
+  const order = (g: Group) => `${g.source} ${g.namespace ?? ""} ${g.chainKey}`;
+  // Ordered by UTF-16 code unit, NOT `localeCompare`. A chain key is caller
+  // text, and `localeCompare` with no locale argument answers from the host's
+  // ICU collation: measured here, it puts "chain-2" AFTER "chain_1" where every
+  // code-wise comparison puts it before, and it can differ between two
+  // TypeScript installs, let alone between kernels. The Python reader sorts the
+  // same key encoded as `utf-16-be`, which is exactly this comparison — so the
+  // two kernels emit findings in one order (proof#49).
+  groups.sort((a, b) => {
+    const x = order(a);
+    const y = order(b);
+    return x < y ? -1 : x > y ? 1 : 0;
+  });
+
+  return {
+    chains: groups.map((g) => ({
+      chainKey: g.chainKey,
+      source: g.source,
+      ...(g.namespace === undefined ? {} : { namespace: g.namespace }),
+      publicKey: g.publicKey,
+      events: g.members.length,
+    })),
+    findings: groups.flatMap(findingsFor),
+  };
+}
+
+/**
+ * The house wording for one finding.
+ *
+ * Deliberately free of verdict vocabulary. Every sentence says what does not
+ * resolve IN THIS BUNDLE, because that is the whole of what was checked; none
+ * of them says failed, invalid, tampered or complete. A surface with its own
+ * voice should read the fields instead — but it must not upgrade the claim.
+ */
+export function renderChainFinding(finding: ChainFinding, subject = "this bundle"): string {
+  const where =
+    finding.source === "adapter"
+      ? `chain ${finding.chainKey} (${finding.namespace} metadata)`
+      : `chain ${finding.chainKey}`;
+  switch (finding.kind) {
+    case "chain-link-dangling":
+      return (
+        `${where}: ${finding.count} of ${finding.of} record(s) point at a predecessor ` +
+        `${subject} does not present (first: ${finding.eventIds[0]}, pointer ` +
+        `${finding.unresolvedPointer})`
+      );
+    case "chain-gap":
+      return (
+        `${where}: ${finding.count} sequence slot(s) between the records ${subject} presents ` +
+        `carry no record (first missing seq ${finding.firstMissingSeq}` +
+        `${finding.eventIds[0] === undefined ? "" : `, next present: ${finding.eventIds[0]}`})`
+      );
+    case "chain-second-root":
+      return (
+        `${where}: ${finding.count} records begin the chain where one chain has one beginning ` +
+        `(${finding.eventIds.join(", ")})`
+      );
+  }
+}