@sanning/proof 0.5.0 → 0.7.0

package/src/chain.ts

@@ -0,0 +1,460 @@
+// 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;
+    const seq = Number.isInteger(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;
+}
+
+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);
+    const missing: number[] = [];
+    for (let s = low; s <= high; s++) if (!present.has(s)) missing.push(s);
+    if (missing.length > 0) {
+      const after = sequenced.filter((m) => (m.seq as number) > missing[0]!).sort(byChainOrder)[0];
+      findings.push({
+        kind: "chain-gap",
+        ...base,
+        count: missing.length,
+        eventIds: after === undefined ? [] : [after.eventId],
+        firstMissingSeq: missing[0]!,
+      });
+    }
+  }
+
+  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}`;
+  groups.sort((a, b) => order(a).localeCompare(order(b)));
+
+  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(", ")})`
+      );
+  }
+}