@sanning/proof 0.10.0 → 0.11.0

package/src/declaration.ts

@@ -0,0 +1,1005 @@
+// The declaration: what a pack SAYS it holds, checked against what it does.
+//
+// WHY THIS EXISTS.
+// A pack is a selection out of an interval. Every per-record check in this
+// kernel is a check on a record that is PRESENT: signatures, payload bindings,
+// inclusion proofs, content hashes. Drop half the records and every survivor
+// still verifies perfectly, so an auditor holding a pack cannot tell a full
+// hand-over from a trimmed one. `completenessNotes` in `./grading.ts` closes
+// one narrow case of that, where a checkpoint's own signed record commits to a
+// leaf count. Nothing closes it for a hand-over pack built out of a stamp, and
+// nothing at all says which records were withheld ON PURPOSE.
+//
+// The declaration is the pack's own signed statement of what it was meant to
+// contain: which agents, which period, which case, the records expected, which
+// of those are disclosed and which are withheld deliberately, and the hand-off
+// pairs it claims. It rides INSIDE `body`, so the bundle's signature covers it
+// and `body_hash` commits to it: the claim has an author, and re-declaring a
+// different selection later means signing a different pack.
+//
+// ── the rule ────────────────────────────────────────────────────────────────
+//
+//   verified   the pack holds exactly what the declaration says it holds. A
+//              record declared `content_withheld` is in scope for its
+//              signature and its commitment only, and its absent bytes are
+//              not a deviation, because the declaration said so in advance.
+//   failed     ANY deviation, and EVERY deviation is named. Declared and
+//              absent, present and undeclared, the pack carrying one
+//              `event_id` twice, withheld without being declared, disclosed
+//              after being declared withheld, or a claimed hand-off naming a
+//              record the declaration never declared.
+//   partial    no declaration, or one the reader cannot interpret as this
+//              version. The pack makes no claim this reader can check, so
+//              what it was meant to contain is UNKNOWN. Never `verified`,
+//              because there is nothing to check against, and never `failed`,
+//              because nothing is wrong: absence is not failure.
+//
+// A deviation is a FAILURE and is NAMED. It must never surface as an absence
+// a reader is left to interpret. That is the shape the hand-off record
+// contract caught in review (anchor#189): a check made a condition of pairing
+// turns a deviation into two records that did not pair for no stated reason,
+// and a reader reads a missing thing as an innocent one.
+//
+// ── the bytes that did not travel ────────────────────────────────────
+//
+// One case inside rule 3 is not a selection and is not graded as one. When NO
+// record declared `disclosed` supplied bytes, nothing was selected: either the
+// bytes travelled separately or the reader was handed the JSON alone. A
+// hostile holder gains nothing from that shape, because declaring those
+// records `content_withheld` grades `verified` today and is cheaper, so the
+// only party who reaches it is the honest one who forgot `--logs`. This check
+// emits a NAMED note instead of a deviation, and the pack's missing bytes
+// carry it to `incomplete` through the disclosure account that already counts
+// them.
+//
+// PARTIAL disclosure is a selection and stays a deviation: nineteen of twenty
+// declared-disclosed records supplying bytes and one not is a choice about
+// which record, and it fails.
+//
+// ── the seam ────────────────────────────────────────────────────────────────
+//
+// PURE, like `./grading.ts`: data in, data out, no I/O and no key lifecycle.
+// It reads the bundle it is handed and, optionally, the same side-content map
+// `verifyEvidenceBundle` takes, because "the holder supplied bytes for this
+// record" has exactly one definition in this kernel (`./side-content.ts`) and
+// this module calls it rather than restating it.
+//
+// ── what this check does NOT claim ──────────────────────────────────────────
+//
+// It compares the declaration to the pack. It does not read a record's
+// internals and cross-check `agents`, `period` or `case_id` against them, and
+// it does not verify that a claimed hand-off PAIR is a real pair: the hashes
+// match, the sequence holds, the two sides name each other's keys. Those are
+// the CASE verdict, across packs and across organizations, and they are
+// anchor#198. Doing half of that here would put two implementations of one
+// rule in the stack, which is the defect `./grading.ts` was brought into the
+// kernel to end.
+//
+// It does now check that each SIDE of a claimed hand-off is a conformant
+// hand-off record (proof#136, ratified by Phil 2026-09-22), and it asks
+// `./handoff.ts` rather than restating that rule. `handoffs[]` carried the
+// claim and checked nothing about it, and that is what made an unreadable
+// record useful: a receiving side respelled one code point of `event_type`
+// and one of `event.counterparty_public_key`, which put the record outside
+// envelope-spec.md 4.1 by both of its scope clauses, then declared it and
+// claimed it as the received half. The record layer said nothing and the pack
+// layer said `verified`. A record cannot be unreadable now and usable later.
+//
+// What that does NOT close (proof#137, ratified by Phil 2026-09-22). The
+// sentence deleted from the spec beside this one said the other door was
+// closed too: omit the record from `handoffs[]` and it is a
+// present-and-undeclared record. It is not. `handoffs[]` MAY be empty, so a
+// holder declares the record in `records[]` and claims it nowhere, and then
+// rule 2 cannot reach it because it is declared and rule 7 cannot reach it
+// because it is unclaimed: this check reads `verified`, exactly as it does
+// over the honest pack. The corpus pins that pack as EXPECTED
+// (`declaration/declaration-unclaimed-record-01`). A pack a party assembles
+// about itself is not self-proving about what that party LEFT OUT, because
+// the omission happens before any reader runs; the closure is the case
+// verdict across BOTH parties' packs, anchor#198.
+//
+// ── the three defects the sixth hunt landed on this check (proof#137) ───────
+//
+// Three. The fourth door the hunt found, whether a pack a party assembles
+// about itself can prove what it LEFT OUT, is a founder call and is not
+// answered here.
+//
+//   ONE PARSER, NOT TWO BUILT-INS. The two kernels read one `event_bytes`
+//   differently, three of the four ways verdict-level on identical bytes:
+//   Python's `json.loads` accepts `NaN`, `Infinity` and `-Infinity` and this
+//   kernel's `JSON.parse` rejects them, and Python's `.decode("utf-8")` keeps
+//   a leading byte-order mark where `TextDecoder` eats it. One pack read
+//   `verified` here and `failed[pair-record-not-a-handoff]` there. The rule is
+//   now stated rather than delegated: bytes that are not RFC 8785 JSON are not
+//   a conformant record, so a leading BOM and each of the three non-finite
+//   literals are rejected in BOTH kernels, spelled out in each, exactly as the
+//   hex charset already was.
+//
+//   ONE `event_id`, TWO RECORDS. Both kernels built a map by id, which is
+//   last-write-wins in both languages, so a second record under a declared id
+//   was graded by neither rule 2 nor rule 7 and was never reported as surplus.
+//   FIRST in bundle order is now the record every other rule grades, and every
+//   record after it under the same id is a `duplicate-event-id` deviation.
+//
+//   MINIMUM DISCLOSURE IS NOT A DEVIATION. A claimed side whose `event_bytes`
+//   the pack withholds was graded "not a conformant hand-off record", so an
+//   honest holder exercising the disclosure posture this product sells proved
+//   a deviation, and the cheapest escape from that was to stop claiming pairs
+//   at all. A withheld side now gets its OWN reading, distinct from both
+//   conformant and non-conformant, and is a NAMED NOTE.
+
+// The kernel's one reader for bytes a producer signed: strict UTF-8, no leading
+// byte-order mark, no non-finite literal. `jcs_loads` in
+// `src/sanning_proof/canonicalize.py` is the twin (proof#140 gate 5).
+import { hexToBytes } from "./crypto.js";
+import { jcsParse } from "./verifier.js";
+import { isConformantHandoffRecord, type HandoffRecord } from "./handoff.js";
+import { hasSideContent, inBodyContentOffered, type SideContentMap } from "./side-content.js";
+
+/** The declaration schema this reader knows. */
+export const DECLARATION_VERSION = "sanning.declaration/v1";
+
+/** The three states a declaration check can reach, from the §3 vocabulary. */
+export type DeclarationVerdict = "verified" | "failed" | "partial";
+
+export type DeclarationDeviationKind =
+  /** The declaration is written to this version and is not readable as one. */
+  | "declaration-malformed"
+  /** A record the declaration expects is not in the pack. */
+  | "declared-absent"
+  /** A record in the pack the declaration never expected. */
+  | "undeclared-present"
+  /**
+   * A record declared `content_withheld` whose bytes the pack supplies INSIDE
+   * its own signed body, in `events[].content`.
+   */
+  | "withheld-but-disclosed"
+  /** The pack carries one `event_id` on two or more records. */
+  | "duplicate-event-id"
+  /** A claimed hand-off names a record the declaration does not declare. */
+  | "pair-record-undeclared"
+  /**
+   * A claimed hand-off names a record that is not a conformant hand-off
+   * record of the side it is claimed on (envelope-spec.md 4.1).
+   */
+  | "pair-record-not-a-handoff";
+
+/**
+ * Every way a pack and the UNSIGNED content handed in beside it fail to line
+ * up, as a closed set. Neither of these is a deviation, and neither of them
+ * fails (proof#147, ratified by Phil 2026-09-22).
+ *
+ * WHY THEY ARE NOT DEVIATIONS. 5.4 grades a pack's declaration partly against
+ * content the reader was HANDED, and that content is not signed by anybody.
+ * `events[].content` rides inside `body`, so the wrapper signature and
+ * `body_hash` cover it and what it says about the holder is the holder's own
+ * word. The side-content map is the other channel, and whoever assembles a
+ * case fills it in: an accuser could put an intact pack into
+ * `pack_declaration_deviates`, which contributed `failed`, WITH NO KEY AT
+ * ALL, by dropping the bytes of a record the pack declared `disclosed` or by
+ * adding bytes for one it declared `content_withheld`. The pack was intact,
+ * its wrapper verified, and its holder had done nothing.
+ *
+ * This is the mirror of proof#143. There a counterparty makes itself look
+ * better by choosing what it hands over; here an accuser makes a counterparty
+ * look worse the same way. Both now read as what the READER established, so
+ * `failed` stays for what a signature covers.
+ *
+ * WHAT A HOSTILE HOLDER GAINS FROM THE WEAKER WORD: nothing, because a
+ * cheaper move already dominates it. Declaring a record `content_withheld` is
+ * legal and grades `verified`, which is strictly better than the `incomplete`
+ * these carry.
+ */
+export type DeclarationContentKind =
+  /**
+   * A record declared `disclosed` whose bytes reached this reader from
+   * neither channel. ALWAYS content-dependent: 5.4.1 lets those bytes travel
+   * beside the pack as `logs/<event_id>.json`, so "no bytes arrived" is a
+   * fact about what the READER was handed and never a fact about what the
+   * holder supplied. No signature covers the absence of a file nobody signed.
+   */
+  | "content-dependent-withholding"
+  /**
+   * A record declared `content_withheld` whose bytes reached this reader ONLY
+   * from the unsigned side-content map. The pack's own body supplies none, so
+   * the holder committed to no such disclosure. The in-body half of the same
+   * rule is the `withheld-but-disclosed` DEVIATION and still fails.
+   */
+  | "content-dependent-disclosure";
+
+/**
+ * One way the pack and the unsigned content beside it do not line up. Named
+ * like a deviation and weighed like an absence.
+ */
+export interface DeclarationContentFinding {
+  kind: DeclarationContentKind;
+  /** The record this is about. Always one: both kinds are per-record. */
+  eventId?: string;
+}
+
+/** Everything this check reports that is NOT a deviation, as a closed set. */
+export type DeclarationNoteKind =
+  /**
+   * Every record declared `disclosed` supplied no bytes, so nothing was
+   * selected: the bytes did not travel with the pack.
+   */
+  | "disclosure-did-not-travel"
+  /**
+   * A claimed hand-off side whose `event_bytes` the pack withholds. The reader
+   * cannot see what the record is either way, so it is neither a conformant
+   * hand-off record nor a non-conformant one.
+   */
+  | "pair-record-withheld";
+
+/**
+ * One named non-deviation finding, as data.
+ *
+ * A note never moves the declaration verdict. It exists so the one shape rule
+ * 3 deliberately does not fail is still SAID, rather than leaving a reader to
+ * notice nothing was reported.
+ */
+export interface DeclarationNote {
+  kind: DeclarationNoteKind;
+  /** How many records the note is about, where it is about a count. */
+  count?: number;
+  /** The record this is about, where it is about one. */
+  eventId?: string;
+  /** Which side of a claimed hand-off named it, for `pair-record-withheld`. */
+  side?: "sent" | "received";
+  /** Which claimed hand-off, by position, for `pair-record-withheld`. */
+  pairIndex?: number;
+}
+
+/** One deviation, as data. A surface renders its own prose or calls `renderDeviation`. */
+export interface DeclarationDeviation {
+  kind: DeclarationDeviationKind;
+  /** The record this is about, where it is about one. */
+  eventId?: string;
+  /** Which side of a claimed hand-off named it, for the two `pair-record-` deviations. */
+  side?: "sent" | "received";
+  /** Which claimed hand-off, by position, for the two `pair-record-` deviations. */
+  pairIndex?: number;
+  /** What is wrong with the declaration itself, for `declaration-malformed`. */
+  reason?: string;
+}
+
+export interface DeclarationCheck {
+  verdict: DeclarationVerdict;
+  /** Every deviation, in a fixed order. Empty is only a pass when the verdict says so. */
+  deviations: DeclarationDeviation[];
+  /**
+   * Every way the pack and the unsigned content beside it do not line up, in
+   * a fixed order. These are NOT deviations: they carry the check to
+   * `partial` and the pack to `incomplete`, never to `failed`.
+   */
+  contentFindings: DeclarationContentFinding[];
+  /** Named findings that are NOT deviations, in a fixed order. */
+  notes: DeclarationNote[];
+  /**
+   * Whether the body carried a `declaration` member at all, WHATEVER its
+   * shape. A string, an array or a `null` under that key is a claim the holder
+   * made and this reader cannot read, which is not the same thing as a pack
+   * that claimed nothing: `gradePack` grades the two differently.
+   */
+  present: boolean;
+  /** `event_id`s the declaration expects, in declaration order. */
+  declared: string[];
+  /** Of those, the ones declared withheld on purpose. */
+  declaredWithheld: string[];
+}
+
+// ---- Reading the pack --------------------------------------------------------
+
+interface DeclarationBundleLike {
+  body?: {
+    declaration?: unknown;
+    events?: {
+      envelope?: { event_id?: unknown; public_key?: unknown };
+      content?: unknown;
+      event_bytes?: unknown;
+    }[];
+  };
+}
+
+/**
+ * The record committed inside one `events[]` entry, or `null`.
+ *
+ * `null` is "this reader cannot read the record", which is not the same as
+ * "the record is fine": a claimed hand-off side whose bytes the pack supplied
+ * and this reader cannot read is a deviation, because the claim is that it IS
+ * a hand-off record and nothing here supports that. It is not the same as "the
+ * pack supplied no bytes" either: see `bytesSupplied`.
+ *
+ * ONE RULE, SPELLED OUT, BECAUSE TWO BUILT-INS ARE NOT ONE RULE. The bytes are
+ * `JCS(event record)` (RFC 8785) or they are not a conformant record. Three
+ * checks carry that: lowercase-or-uppercase hex in pairs, no leading byte-order
+ * mark, and no non-finite literal. The hex is `hexToBytes`, because it and
+ * `bytes.fromhex` disagree about embedded whitespace (proof#135); the rest is
+ * `jcsParse`, which every site in either kernel that reads signed bytes now
+ * shares (proof#140 gate 5). Both halves were a hand-rolled copy in this module
+ * until proof#146, and both are the shared reader now: the answer on every
+ * input is the same, and there is one fewer place for the rule to drift. The
+ * cross-kernel declaration leg and `declaration.test.ts` hold both kernels to
+ * the same answer on the same bytes rather than to either built-in.
+ */
+function committedRecord(raw: unknown): HandoffRecord | null {
+  let parsed: unknown;
+  try {
+    parsed = jcsParse(hexToBytes(raw as string));
+  } catch {
+    return null;
+  }
+  return isObject(parsed) ? (parsed as HandoffRecord) : null;
+}
+
+// Which record type each side of a claimed hand-off has to be. A pack that
+// names its receipt as the sent side has mislabeled a record, and the reading
+// layer grades the two types differently.
+const SIDE_EVENT_TYPES = { sent: "handoff.sent", received: "handoff.received" } as const;
+
+/**
+ * The three readings a claimed hand-off side can get. THREE, not two
+ * (proof#137, defect 3). A reader that has only "conformant" and "not
+ * conformant" has to put a record whose `event_bytes` the pack withholds into
+ * one of them, and both are wrong: `event_bytes` is OPTIONAL and withholding
+ * it is minimum disclosure, which the corpus calls a customer's right and not
+ * a defect. Grading it "not a conformant hand-off record" made an honest
+ * minimum-disclosure pack prove a deviation, and the cheapest way out of that
+ * was to stop claiming pairs at all.
+ */
+type SideReading = "conformant" | "withheld" | "not-a-handoff";
+
+/**
+ * How a claimed side reads: conformant, withheld, or not a hand-off record.
+ *
+ * The definition of conformant is 4.1's own (`isConformantHandoffRecord`),
+ * read once and never restated here, plus the record type the side names.
+ *
+ * WITHHELD IS ITS OWN READING. The pack supplied no `event_bytes`, so this
+ * reader cannot see what the record is in either direction. Saying it is not a
+ * hand-off record is a claim the reader cannot support, and it punishes the
+ * disclosure posture the product sells.
+ */
+function sideReading(
+  p: {
+    eventId: string;
+    publicKey: string;
+    record: HandoffRecord | null;
+    bytesSupplied: boolean;
+  },
+  side: "sent" | "received",
+): SideReading {
+  if (!p.bytesSupplied) return "withheld";
+  if (p.record === null) return "not-a-handoff";
+  return isConformantHandoffRecord({ publicKey: p.publicKey, record: p.record, ref: p.eventId }) &&
+    p.record.event_type === SIDE_EVENT_TYPES[side]
+    ? "conformant"
+    : "not-a-handoff";
+}
+
+const bodyOf = (bundle: unknown) => (bundle as DeclarationBundleLike | null)?.body;
+
+/**
+ * One of the pack's own records: the id, and whether the pack supplied its
+ * bytes.
+ *
+ * An event with no readable `event_id` is given a positional name, the same
+ * `#n` convention `accountDisclosure` uses, so it is still reported rather
+ * than dropped. An unnameable record cannot be declared, so it can only ever
+ * be surplus, which is a deviation and is named as one.
+ */
+export interface PackRecord {
+  eventId: string;
+  nameable: boolean;
+  /**
+   * Whether bytes for this record reached the reader at ALL, from either
+   * channel. This is what the disclosure account counts.
+   */
+  disclosed: boolean;
+  /**
+   * Whether the bytes came from `events[].content`, INSIDE the body the
+   * wrapper signed and `body_hash` commits to. The two channels are kept
+   * apart because only this one is the holder's own word: the side-content
+   * map is filled in by whoever assembled the case (proof#147).
+   */
+  disclosedInBody: boolean;
+  publicKey: string;
+  record: HandoffRecord | null;
+  /**
+   * Whether the pack SUPPLIED `event_bytes` for this record at all.
+   * `event_bytes` is OPTIONAL (evidence-bundle.md 5.1 and 5.3), and
+   * withholding it is minimum disclosure rather than a defect, so "the pack
+   * supplied bytes this reader cannot read" and "the pack supplied none" are
+   * two different readings and never one.
+   */
+  bytesSupplied: boolean;
+}
+
+/**
+ * The pack's own records, in bundle order. Exported so the CASE layer
+ * (`./case.ts`, anchor#198) reads a pack through the SAME parser that grades
+ * it here, rather than through a second one beside it. A validation copied
+ * next to the one that enforces it drifts, and a copy that is looser blesses
+ * a value the real one then rejects.
+ */
+export function packRecords(
+  bundle: unknown,
+  content: SideContentMap | null | undefined,
+): PackRecord[] {
+  const events = bodyOf(bundle)?.events;
+  if (!Array.isArray(events)) return [];
+  return events.map((ev, i) => {
+    const raw = ev?.envelope?.event_id;
+    const nameable = typeof raw === "string" && raw.length > 0;
+    const eventId = nameable ? (raw as string) : `#${i + 1}`;
+    // One definition of "the holder supplied bytes", in both of the two
+    // shapes a pack can supply them: in the body, or beside it. Both are
+    // `./side-content.ts`, never restated here.
+    const disclosedInBody = inBodyContentOffered(ev?.content);
+    const disclosed = disclosedInBody || (nameable && hasSideContent(content, eventId));
+    // The key comes from the ENVELOPE and never from inside the record, which
+    // is 4.1's whole point: a value that names no key makes the record
+    // `malformed` there, so a claimed side carrying one is a deviation here.
+    const key = ev?.envelope?.public_key;
+    // The family convention for "the holder supplied this hex field": a
+    // non-empty string. Anything else, an absent key, a `null` or a number, is
+    // the field not travelling, which is minimum disclosure and not a record
+    // this reader was handed and could not read.
+    const rawBytes = ev?.event_bytes;
+    return {
+      eventId,
+      nameable,
+      disclosed,
+      disclosedInBody,
+      publicKey: typeof key === "string" ? key : "",
+      record: committedRecord(rawBytes),
+      bytesSupplied: typeof rawBytes === "string" && rawBytes.length > 0,
+    };
+  });
+}
+
+// ---- Reading the declaration -------------------------------------------------
+
+const DISCLOSURE_STATES = new Set(["disclosed", "content_withheld"]);
+
+// RFC 3339 `date-time` with an uppercase `Z`, the family's convention for an
+// instant. Format only: this is not an ordering check and not a calendar
+// check, and it deliberately does not restate the `signed_at` rule of
+// envelope-spec §2, which grades a different field on a different layer.
+const INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/;
+
+const isObject = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
+const isId = (v: unknown): v is string => typeof v === "string" && v.length > 0;
+
+interface ReadDeclaration {
+  records: { eventId: string; withheld: boolean }[];
+  pairs: { sent: string | null; received: string | null }[];
+}
+
+/**
+ * Read a declaration written to the version this reader knows, or say what is
+ * wrong with it.
+ *
+ * Every malformation is collected, not the first: a declaration is a claim,
+ * and a reader that names one defect in a claim with four sends its holder
+ * round the loop four times.
+ */
+function readDeclaration(
+  declaration: Record<string, unknown>,
+): { ok: true; read: ReadDeclaration } | { ok: false; reasons: string[] } {
+  const reasons: string[] = [];
+  const note = (r: string) => reasons.push(r);
+
+  if (!isId(declaration["case_id"])) note("case_id is not a non-empty string");
+
+  const agents = declaration["agents"];
+  if (!Array.isArray(agents) || agents.length === 0) {
+    note("agents is not a non-empty array");
+  } else if (!agents.every(isId)) {
+    note("agents holds an entry that is not a non-empty string");
+  } else if (new Set(agents as string[]).size !== agents.length) {
+    note("agents names the same agent twice");
+  }
+
+  const period = declaration["period"];
+  if (!isObject(period)) note("period is not an object");
+  else if (typeof period["start"] !== "string" || !INSTANT.test(period["start"]))
+    note("period.start is not an RFC 3339 instant ending in Z");
+  else if (typeof period["end"] !== "string" || !INSTANT.test(period["end"]))
+    note("period.end is not an RFC 3339 instant ending in Z");
+
+  const records: { eventId: string; withheld: boolean }[] = [];
+  const raw = declaration["records"];
+  if (!Array.isArray(raw)) note("records is not an array");
+  else {
+    const seen = new Set<string>();
+    for (const [i, r] of raw.entries()) {
+      if (!isObject(r) || !isId(r["event_id"])) {
+        note(`records[${i}] carries no event_id`);
+        continue;
+      }
+      const eventId = r["event_id"] as string;
+      const disclosure = r["disclosure"];
+      if (typeof disclosure !== "string" || !DISCLOSURE_STATES.has(disclosure)) {
+        note(`records[${i}] (${eventId}) has no disclosure of "disclosed" or "content_withheld"`);
+        continue;
+      }
+      if (seen.has(eventId)) {
+        note(`records[${i}] declares ${eventId} a second time`);
+        continue;
+      }
+      seen.add(eventId);
+      records.push({ eventId, withheld: disclosure === "content_withheld" });
+    }
+  }
+
+  const pairs: { sent: string | null; received: string | null }[] = [];
+  const rawPairs = declaration["handoffs"];
+  if (!Array.isArray(rawPairs)) note("handoffs is not an array");
+  else {
+    for (const [i, p] of rawPairs.entries()) {
+      if (!isObject(p)) {
+        note(`handoffs[${i}] is not an object`);
+        continue;
+      }
+      const sent = p["sent_event_id"] ?? null;
+      const received = p["received_event_id"] ?? null;
+      const legal = (v: unknown) => v === null || isId(v);
+      if (!legal(sent) || !legal(received)) {
+        note(`handoffs[${i}] names a side that is neither null nor a non-empty string`);
+        continue;
+      }
+      if (sent === null && received === null) {
+        note(`handoffs[${i}] claims a hand-off with neither side`);
+        continue;
+      }
+      pairs.push({ sent: sent as string | null, received: received as string | null });
+    }
+  }
+
+  return reasons.length > 0 ? { ok: false, reasons } : { ok: true, read: { records, pairs } };
+}
+
+// ---- The check ---------------------------------------------------------------
+
+const noDeclaration = (): DeclarationCheck => ({
+  verdict: "partial",
+  deviations: [],
+  contentFindings: [],
+  notes: [],
+  present: false,
+  declared: [],
+  declaredWithheld: [],
+});
+
+/**
+ * Check a pack against the declaration inside its body.
+ *
+ * `content` is the same side-content map `verifyEvidenceBundle` takes, and is
+ * optional: a pack that discloses its bytes in the body needs no side input,
+ * and a pack that discloses them beside itself passes the map a consumer
+ * already built.
+ *
+ * The verdict is this check's own. It does not restate the bundle verdict and
+ * it does not read it: a declaration can match perfectly over a pack whose
+ * signatures are forged, and saying so is `gradePack`'s job, which takes both.
+ */
+export function checkDeclaration(
+  bundle: unknown,
+  content?: SideContentMap | null,
+): DeclarationCheck {
+  // `body.declaration` as WRITTEN, not as hoped. The key being absent and the
+  // key holding a string, an array or `null` are graded differently and must
+  // not collapse into one another: a body with no `declaration` key claimed
+  // nothing, which every pack built before §5.4 did, while a body whose
+  // `declaration` will not read DID claim something. Reading the second as the
+  // first is how a one-field edit to a re-sealed pack graded clean.
+  const body = bodyOf(bundle);
+  if (!isObject(body) || !("declaration" in body)) return noDeclaration();
+  const declaration = (body as Record<string, unknown>)["declaration"];
+
+  // A declaration this reader cannot interpret as `sanning.declaration/v1` is
+  // UNKNOWN and not an accusation: the same posture §4 step 1 takes for an
+  // unknown `body_type`, one layer down. `present` says a declaration was
+  // THERE, so a surface can tell "nothing was claimed" from "something was
+  // claimed in a language I do not speak", and `gradePack` carries the second
+  // to `incomplete`.
+  //
+  // Every shape that lands here is one field away from a valid declared pack
+  // the holder can re-seal with its own key: an unknown `declaration_version`,
+  // a deleted one, a null one, and a `declaration` that is a string, an array
+  // or null. Each of those hides the evidence of a trim inside a signed body,
+  // so none of them may reach a clean pack verdict.
+  if (!isObject(declaration) || declaration["declaration_version"] !== DECLARATION_VERSION) {
+    return { ...noDeclaration(), present: true };
+  }
+
+  const read = readDeclaration(declaration);
+  if (!read.ok) {
+    return {
+      verdict: "failed",
+      deviations: read.reasons.map((reason) => ({ kind: "declaration-malformed", reason })),
+      contentFindings: [],
+      notes: [],
+      present: true,
+      declared: [],
+      declaredWithheld: [],
+    };
+  }
+
+  const { records, pairs } = read.read;
+  const declared = records.map((r) => r.eventId);
+  const declaredSet = new Set(declared);
+  const pack = packRecords(bundle, content);
+  // FIRST WINS, and the second record under one id is named below. A map built
+  // by id is last-write-wins in both languages, so a pack carrying one
+  // `event_id` twice had its second record graded by rule 7 and its first by
+  // nothing, or the reverse once the order flipped, and neither record was
+  // ever reported as surplus (proof#137, defect 2). First in bundle order is
+  // the record every other rule grades, and it does not depend on how the
+  // holder ordered `events[]`.
+  const byId = new Map<string, (typeof pack)[number]>();
+  for (const p of pack) {
+    if (p.nameable && !byId.has(p.eventId)) byId.set(p.eventId, p);
+  }
+
+  const deviations: DeclarationDeviation[] = [];
+
+  // Declared and absent. The trimmed hand-over, which is the whole reason a
+  // declaration exists: nothing else in the pack can see it.
+  for (const r of records) {
+    if (!byId.has(r.eventId)) deviations.push({ kind: "declared-absent", eventId: r.eventId });
+  }
+
+  // Present and undeclared, and the pack carrying one id twice.
+  //
+  // An unnameable record is present-and-undeclared, because a record the
+  // declaration could not have named is surplus by construction.
+  //
+  // A record under an id the pack already carries is named SEPARATELY, in
+  // bundle order, and is not also reported as surplus: one defect, one
+  // finding. 5.4.1 says declaring an id twice is a malformed declaration and
+  // said nothing about the PACK carrying one twice, so a second record under a
+  // declared id was graded by no rule at all and was never reported
+  // (proof#137, defect 2). A declaration names records by id, so an id that
+  // names two records names neither.
+  const seenInPack = new Set<string>();
+  for (const p of pack) {
+    if (p.nameable && seenInPack.has(p.eventId)) {
+      deviations.push({ kind: "duplicate-event-id", eventId: p.eventId });
+      continue;
+    }
+    if (p.nameable) seenInPack.add(p.eventId);
+    if (!p.nameable || !declaredSet.has(p.eventId)) {
+      deviations.push({ kind: "undeclared-present", eventId: p.eventId });
+    }
+  }
+
+  // The bytes that did not travel. Over the records declared `disclosed` that
+  // the pack actually holds: if NONE of them supplied bytes, no record was
+  // selected over another and the honest reading is that the bytes travelled
+  // separately, so this is a note and not a deviation. One of them supplying
+  // bytes and another not IS a selection, and every shortfall is named.
+  const disclosedHeld = records
+    .filter((r) => !r.withheld)
+    .map((r) => byId.get(r.eventId))
+    .filter((p): p is NonNullable<typeof p> => p !== undefined);
+  const nothingTravelled = disclosedHeld.length > 0 && !disclosedHeld.some((p) => p.disclosed);
+  const notes: DeclarationNote[] = nothingTravelled
+    ? [{ kind: "disclosure-did-not-travel", count: disclosedHeld.length }]
+    : [];
+
+  // The two disclosure rules, in declaration order, over the records the pack
+  // actually holds: an absent record is already named above, and naming it
+  // twice would report one defect as two.
+  //
+  // EACH OF THEM SPLITS ON WHICH CHANNEL THE BYTES CAME FROM (proof#147,
+  // ratified by Phil 2026-09-22). `events[].content` is inside the signed
+  // body, so what it says is the holder's own word and a mismatch with the
+  // holder's own declaration is a proven deviation. The side-content map is
+  // unsigned and is filled in by whoever assembled the case, so a reading
+  // that rests on it says what the READER established and not what the holder
+  // did. The weaker readings are named, and they carry the check to `partial`
+  // and the pack to `incomplete`.
+  const contentFindings: DeclarationContentFinding[] = [];
+  for (const r of records) {
+    const p = byId.get(r.eventId);
+    if (p === undefined) continue;
+    if (!r.withheld && !p.disclosed) {
+      if (nothingTravelled) continue;
+      // ALWAYS content-dependent. 5.4.1 lets a record's bytes travel beside
+      // the pack, so no pack can prove it supplied them and no reader can
+      // prove it did not: an accuser holding a twenty-file drop reaches this
+      // reading by deleting one file.
+      contentFindings.push({ kind: "content-dependent-withholding", eventId: r.eventId });
+    } else if (r.withheld && p.disclosed) {
+      if (p.disclosedInBody) {
+        deviations.push({ kind: "withheld-but-disclosed", eventId: r.eventId });
+      } else {
+        contentFindings.push({ kind: "content-dependent-disclosure", eventId: r.eventId });
+      }
+    }
+  }
+
+  // A claimed hand-off that names a record the declaration does not declare,
+  // or names one that is not a conformant hand-off record of that side.
+  //
+  // The PAIR itself, that the hashes match and the sequence holds, is the case
+  // verdict (anchor#198) and is deliberately not checked here. Each SIDE is
+  // checked, and that is the belt for 4.1's own repair: a record respelled out
+  // of 4.1's scope was unreadable at the record layer and still usable here,
+  // because this array carried the claim and checked nothing about it
+  // (proof#136). A record declared and absent is already named above and is
+  // not named twice.
+  //
+  // A claimed side whose `event_bytes` the pack WITHHELD is a NAMED NOTE and
+  // not a deviation (proof#137, defect 3). `event_bytes` is OPTIONAL, and a
+  // holder that withholds it is exercising minimum disclosure, which this
+  // corpus calls a customer's right and not a defect. Grading it "not a
+  // conformant hand-off record" made an honest pack prove a deviation over a
+  // record the reader cannot see in either direction, and the cheapest escape
+  // from that was to stop claiming pairs, which is the door proof#137 is
+  // about. A withheld side is still not a clean claim: the pack's own
+  // disclosure account already carries those absent bytes to `incomplete`.
+  for (const [i, pair] of pairs.entries()) {
+    for (const side of ["sent", "received"] as const) {
+      const id = pair[side];
+      if (id === null) continue;
+      if (!declaredSet.has(id)) {
+        deviations.push({ kind: "pair-record-undeclared", eventId: id, side, pairIndex: i });
+        continue;
+      }
+      const p = byId.get(id);
+      if (p === undefined) continue;
+      const reading = sideReading(p, side);
+      if (reading === "withheld") {
+        notes.push({ kind: "pair-record-withheld", eventId: id, side, pairIndex: i });
+      } else if (reading === "not-a-handoff") {
+        deviations.push({ kind: "pair-record-not-a-handoff", eventId: id, side, pairIndex: i });
+      }
+    }
+  }
+
+  // A proven deviation wins: it is a mismatch between what the pack claimed
+  // and what its own signed body carries, and a failing check always wins.
+  // With no deviation and a content-dependent finding, the pack lines up with
+  // its claim everywhere a signature reaches and does not line up somewhere
+  // only unsigned bytes could settle, which is UNDETERMINED: `partial` is
+  // 3's word for that, and it adds none.
+  const verdict: DeclarationVerdict =
+    deviations.length > 0 ? "failed" : contentFindings.length > 0 ? "partial" : "verified";
+
+  return {
+    verdict,
+    deviations,
+    contentFindings,
+    notes,
+    present: true,
+    declared,
+    declaredWithheld: records.filter((r) => r.withheld).map((r) => r.eventId),
+  };
+}
+
+// ---- Presentation (optional) -------------------------------------------------
+
+/**
+ * The house wording for one deviation.
+ *
+ * Offered, not imposed, exactly as `renderCause` is: what must not vary
+ * between surfaces is the verdict and the set of deviations, and those come
+ * from `checkDeclaration`. Both kernels return this same text for the same
+ * deviation, and `cross-kernel/run_cli.sh` holds the two commands to it.
+ */
+/**
+ * One line a surface can print beside the pack verdict: what the pack claimed
+ * to hold, and whether it does.
+ *
+ * Both kernels' commands print this sentence, so a reader who runs
+ * `sanning-proof verify` and `npx @sanning/proof verify` over one pack reads
+ * one sentence rather than two that differ by a word.
+ *
+ * `partial` is spelled out rather than printed as a word, because "partial" on
+ * its own beside a green pack reads as a hedge. What it means is that nobody
+ * said what the pack was meant to contain, and a reader deciding whether this
+ * is a full hand-over needs that in words.
+ */
+/**
+ * What a pack's declaration CLAIMS, for a reader one layer out.
+ *
+ * `checkDeclaration` answers "does this pack agree with its own claim". A case
+ * reader (`./case.ts`, anchor#198) needs a different thing from the same
+ * object: which records the holder claimed as a hand-off side at all, so that
+ * a conformant hand-off record the holder claimed NOWHERE is a named finding
+ * rather than a silence. That is the door proof#137 ratified open at this
+ * layer: `handoffs[]` MAY be empty, so rule 2 cannot reach a declared record
+ * and rule 7 cannot reach an unclaimed one.
+ *
+ * It is read HERE, from the same two functions `checkDeclaration` reads,
+ * rather than restated in the case layer. A second reader of one object drifts
+ * from the first, and a looser copy blesses a claim the real one rejects.
+ */
+export interface DeclarationClaims {
+  /**
+   * Whether the body carried a `declaration` member at all, whatever its
+   * shape. The same field `DeclarationCheck` carries, and the same meaning.
+   */
+  present: boolean;
+  /**
+   * Whether this reader could read the claim as `DECLARATION_VERSION` AND the
+   * object satisfies 5.4.1. `false` covers an absent declaration, an unknown
+   * version and a malformed object, and a case reader must not read any of the
+   * three as "the holder claimed nothing to check".
+   */
+  readable: boolean;
+  /** The case the declaration names, where it names one. */
+  caseId: string | null;
+  /**
+   * Every `event_id` a `handoffs[]` entry names on either side, in declaration
+   * order, with no duplicates. Empty where the holder claimed no pair, which
+   * is legal and is exactly the shape a case reader has to name.
+   */
+  claimedSides: string[];
+}
+
+/**
+ * Read the claim a pack's declaration makes, without grading the pack.
+ *
+ * Deliberately total: a bundle this reader cannot read comes back with
+ * `readable: false` rather than throwing, because a case reader grades what it
+ * was handed and a reader that throws on a hostile pack cannot report that the
+ * pack is hostile.
+ */
+export function declarationClaims(bundle: unknown): DeclarationClaims {
+  const none: DeclarationClaims = {
+    present: false,
+    readable: false,
+    caseId: null,
+    claimedSides: [],
+  };
+  const body = bodyOf(bundle);
+  if (!isObject(body) || !("declaration" in body)) return none;
+  const declaration = (body as Record<string, unknown>)["declaration"];
+  if (!isObject(declaration) || declaration["declaration_version"] !== DECLARATION_VERSION) {
+    return { ...none, present: true };
+  }
+  const read = readDeclaration(declaration);
+  if (!read.ok) return { ...none, present: true };
+
+  const claimedSides: string[] = [];
+  for (const pair of read.read.pairs) {
+    for (const eventId of [pair.sent, pair.received]) {
+      if (eventId !== null && !claimedSides.includes(eventId)) claimedSides.push(eventId);
+    }
+  }
+  const caseId = declaration["case_id"];
+  return {
+    present: true,
+    readable: true,
+    caseId: typeof caseId === "string" ? caseId : null,
+    claimedSides,
+  };
+}
+
+export function renderDeclarationSummary(check: DeclarationCheck): string {
+  if (!check.present) {
+    return "this pack does not say what it holds, so whether it is complete is UNKNOWN";
+  }
+  if (check.verdict === "failed") {
+    // READ BEFORE THE CONTENT-FINDINGS BRANCH BELOW. A failing check always
+    // wins (section 5.4.3: a pack with one deviation and one content-dependent
+    // finding is `failed`, and the finding is still named), so a pack that
+    // deviates gets the deviating sentence even when it also carries findings.
+    // Ordered the other way round, a pack holding both printed "this pack
+    // agrees with its own declaration everywhere its signature reaches" with
+    // its own named deviations listed underneath, which is the reading this
+    // section exists to prevent: a deviation surfacing as something a reader
+    // is left to interpret.
+    if (check.contentFindings.length > 0) {
+      // BOTH counts, because the two facts are about different records and a
+      // reader shown one of them would look in the wrong place.
+      return (
+        `this pack DEVIATES from its own declaration, in ${check.deviations.length} way(s), ` +
+        `and in ${check.contentFindings.length} further way(s) it does not line up with ` +
+        "the unsigned content handed in beside it, which anyone could have supplied"
+      );
+    }
+    return `this pack DEVIATES from its own declaration, in ${check.deviations.length} way(s)`;
+  }
+  if (check.contentFindings.length > 0) {
+    // Read before the `partial` branch below, because both reach this verdict
+    // and they are two different sentences. This one says what the reader
+    // could not establish; the one below says the reader could not read the
+    // claim at all.
+    return (
+      "this pack agrees with its own declaration everywhere its signature reaches, " +
+      `and in ${check.contentFindings.length} way(s) it does not line up with the ` +
+      "unsigned content handed in beside it, which anyone could have supplied"
+    );
+  }
+  if (check.verdict === "partial") {
+    return (
+      "this pack says what it holds in a declaration this verifier cannot read, " +
+      "so whether it is complete is UNKNOWN"
+    );
+  }
+  return (
+    `this pack holds exactly what it declares: ${check.declared.length} record(s), ` +
+    `${check.declaredWithheld.length} withheld on purpose`
+  );
+}
+
+/**
+ * The house wording for one note. Offered, not imposed, as `renderDeviation`
+ * is.
+ */
+export function renderNote(note: DeclarationNote): string {
+  switch (note.kind) {
+    case "disclosure-did-not-travel":
+      return (
+        `this pack declares ${note.count} record(s) disclosed and supplies no bytes for ` +
+        "any of them: the bytes did not travel with the pack, so their content is UNKNOWN"
+      );
+    case "pair-record-withheld":
+      return (
+        `the claimed hand-off at position ${note.pairIndex} names ${note.eventId} on its ` +
+        `${note.side} side, whose record bytes this pack withholds, so what that record ` +
+        "IS is UNKNOWN"
+      );
+  }
+}
+
+/**
+ * The house wording for one content-dependent finding.
+ *
+ * EVERY SENTENCE HERE NAMES THE CONTENT AND NOT THE HOLDER. That is the whole
+ * point of the kind: the bytes are unsigned and whoever assembled the case
+ * chose them, so a sentence that reads as an accusation would put the weaker
+ * word beside the stronger claim and an auditor would read the claim.
+ */
+export function renderContentFinding(finding: DeclarationContentFinding): string {
+  switch (finding.kind) {
+    case "content-dependent-withholding":
+      return (
+        `${finding.eventId} is declared disclosed and no bytes for it reached this ` +
+        "verifier, from the pack or from beside it, so whether the holder supplied " +
+        "them is UNKNOWN"
+      );
+    case "content-dependent-disclosure":
+      return (
+        `${finding.eventId} is declared withheld and bytes for it were handed in ` +
+        "beside this pack, which the pack does not carry and nobody signed, so " +
+        "whether the holder disclosed them is UNKNOWN"
+      );
+  }
+}
+
+export function renderDeviation(deviation: DeclarationDeviation): string {
+  switch (deviation.kind) {
+    case "declaration-malformed":
+      return `the declaration is not readable as ${DECLARATION_VERSION}: ${deviation.reason}`;
+    case "declared-absent":
+      return `${deviation.eventId} is declared and is NOT in this pack`;
+    case "undeclared-present":
+      return `${deviation.eventId} is in this pack and is NOT declared`;
+    case "withheld-but-disclosed":
+      return (
+        `${deviation.eventId} is declared withheld and this pack carries its bytes ` +
+        "in its own signed body"
+      );
+    case "duplicate-event-id":
+      return `this pack carries ${deviation.eventId} more than once`;
+    case "pair-record-undeclared":
+      return (
+        `the claimed hand-off at position ${deviation.pairIndex} names ` +
+        `${deviation.eventId} on its ${deviation.side} side, which the declaration does not declare`
+      );
+    case "pair-record-not-a-handoff":
+      return (
+        `the claimed hand-off at position ${deviation.pairIndex} names ` +
+        `${deviation.eventId} on its ${deviation.side} side, which is not a conformant ` +
+        `${SIDE_EVENT_TYPES[deviation.side ?? "sent"]} record`
+      );
+  }
+}