@sanning/proof 0.19.1 → 0.20.0

package/src/declaration.ts

@@ -1,136 +1,35 @@
-// The declaration: what a pack SAYS it holds, checked against what it does.
+// The declaration: what a pack says it holds, checked against what it does
+// (evidence-bundle.md §5.4).
 //
-// 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.
+// Every per-record check verifies a record that is present, so a trimmed pack
+// verifies as well as a full one. The declaration is the pack's own signed
+// statement of what it was meant to contain. It rides inside `body`, so the
+// bundle signature and `body_hash` cover it.
 //
-// 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.
+//   verified   the pack holds exactly what the declaration says. A record
+//              declared `content_withheld` is checked for its signature and
+//              commitment only.
+//   failed     any deviation, and every deviation is named. A deviation never
+//              surfaces as an absence a reader is left to interpret.
+//   incomplete no declaration, or one this reader cannot read. Nothing to
+//              check against, and nothing proven wrong.
 //
-// ── the rule ────────────────────────────────────────────────────────────────
+// When no record declared `disclosed` supplied bytes, nothing was selected:
+// the bytes travelled separately. That is a note, not a deviation, and the
+// missing bytes still carry the pack to `incomplete`. Partial disclosure is a
+// selection and fails.
 //
-//   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.
+// Pure: data in, data out. "The holder supplied bytes" is defined once, in
+// `./side-content.ts`. This check does not verify that a claimed hand-off pair
+// is a real pair (the case verdict does), but it does require each claimed side
+// to be a conformant hand-off record (`./handoff.ts`).
 //
-// 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).
+// A pack cannot prove what its holder left out: a record declared in
+// `records[]` and claimed in no `handoffs[]` entry reads `verified` here. The
+// case verdict across both parties' packs closes that.
+
+// The one reader for bytes a producer signed: strict UTF-8, no leading BOM, no
+// non-finite literal. Python's twin is `jcs_loads`.
 import type { ChainLink } from "./chain.js";
 import { hexToBytes, utf8 } from "./crypto.js";
 import { jcs, jcsParse } from "./verifier.js";
@@ -142,25 +41,20 @@ import {
   type SideContentMap,
 } from "./side-content.js";
 
-/** The first declaration schema, which every earlier reader knows. */
+/** The first declaration schema. */
 export const DECLARATION_VERSION = "sanning.declaration/v1";
 
-/**
- * v1 plus a signed `records[].role` on every record (evidence-bundle.md
- * 5.4.1 v1.20, A21). A reader that knows only v1 reads a v2 declaration as one
- * it cannot read, which is the safe direction.
- */
+/** v1 plus a signed `records[].role` on every record (§5.4.1). */
 export const DECLARATION_VERSION_V2 = "sanning.declaration/v2";
 
 /**
  * v2 plus a signed `chains[]`: the `chain_key`s the holder claims are complete
- * and in order (evidence-bundle.md 5.4.1 v1.36, A45). A reader that knows only
- * v1 and v2 reads a v3 declaration as one it cannot read, which is the safe
+ * and in order (§5.4.1). An older reader cannot read it, which is the safe
  * direction.
  */
 export const DECLARATION_VERSION_V3 = "sanning.declaration/v3";
 
-/** Every declaration schema this reader knows, in the order they were added. */
+/** Every declaration schema this reader knows, oldest first. */
 export const DECLARATION_VERSIONS = [
   DECLARATION_VERSION,
   DECLARATION_VERSION_V2,
@@ -171,15 +65,13 @@ export const DECLARATION_VERSIONS = [
 const ROLE_VERSIONS: readonly string[] = [DECLARATION_VERSION_V2, DECLARATION_VERSION_V3];
 
 /**
- * What a v2 declaration may sign a record IS, compared exactly: `handoff`, a
- * record 4.1 governs that the pack claims as a side in `handoffs[]`, or
- * `step`, any other record.
+ * The roles a v2 declaration can sign, compared exactly: `handoff` for a
+ * record §4.1 governs that the pack claims in `handoffs[]`, `step` otherwise.
  */
 export const DECLARATION_ROLES = ["handoff", "step"] as const;
 export type DeclarationRole = (typeof DECLARATION_ROLES)[number];
 
-/** The three states a declaration check can reach, from the §3 vocabulary. */
-export const DECLARATION_VERDICTS = ["verified", "failed", "partial"] as const;
+export const DECLARATION_VERDICTS = ["verified", "failed", "incomplete"] as const;
 export type DeclarationVerdict = (typeof DECLARATION_VERDICTS)[number];
 
 export const DECLARATION_DEVIATION_KINDS = [
@@ -189,47 +81,27 @@ export const DECLARATION_DEVIATION_KINDS = [
   "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`.
-   */
+  /** A record declared `content_withheld` whose bytes the pack's own body supplies. */
   "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).
-   */
+  /** A claimed hand-off side that is not a conformant hand-off record of that side (§4.1). */
   "pair_record_not_a_handoff",
-  /**
-   * Rule 9 (v1.20, A21), `sanning.declaration/v2` only. A record declared
-   * `handoff` that no `handoffs[]` entry names as a side.
-   */
+  /** v2 only: a record declared `handoff` that no `handoffs[]` entry claims. */
   "role_handoff_unclaimed",
   /** A record a `handoffs[]` entry names as a side, declared `step`. */
   "role_step_claimed",
-  /**
-   * A record declared `step` that 4.1's scope test puts in scope: its `event`
-   * carries `counterparty_public_key`, or its folded `event_type` has a
-   * `handoff` segment. The holder signed that a hand-off record is not one.
-   */
+  /** A record declared `step` that §4.1's scope test puts in scope. */
   "role_step_governed",
-  /**
-   * A record declared `step` whose supplied `event_bytes` this reader cannot
-   * read under rule 7's parser rule.
-   */
+  /** A record declared `step` whose supplied `event_bytes` cannot be read. */
   "role_step_unreadable",
-  /**
-   * Rule 11 (v1.36, A45), `sanning.declaration/v3` only. The holder signed
-   * that a chain is complete and in order, and a second record under that key,
-   * under any producing key, begins it.
-   */
+  /** v3 only: a second record beginning a claimed chain, under any producing key. */
   "chain_second_root",
   /** A record of a claimed chain is the second successor of one predecessor. */
   "chain_fork",
-  /** A record of a claimed chain points at a predecessor its chain does not present in the pack. */
+  /** A claimed chain's record points at a predecessor the pack does not present. */
   "chain_link_dangling",
   /** A claimed chain of which the pack presents no record at all. */
   "chain_claimed_absent",
@@ -237,115 +109,67 @@ export const DECLARATION_DEVIATION_KINDS = [
 export type DeclarationDeviationKind = (typeof DECLARATION_DEVIATION_KINDS)[number];
 
 /**
- * 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.
+ * Every way a pack and the unsigned content handed in beside it fail to line
+ * up. Not deviations, and never `failed`: whoever assembles a case fills the
+ * side-content map, so an accuser could otherwise fail an intact pack with no
+ * key at all. `failed` stays for what a signature covers.
  */
 export const DECLARATION_CONTENT_KINDS = [
   /**
-   * 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.
+   * A record declared `disclosed` whose bytes arrived from neither channel.
+   * Always content-dependent: the bytes may travel beside the pack, so this is
+   * a fact about what the reader was handed.
    */
   "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.
+   * A record declared `content_withheld` whose bytes arrived only through the
+   * side-content map. The in-body case is the `withheld_but_disclosed`
+   * deviation.
    */
   "content_dependent_disclosure",
 ] as const;
 export type DeclarationContentKind = (typeof DECLARATION_CONTENT_KINDS)[number];
 
-/**
- * One way the pack and the unsigned content beside it do not line up. Named
- * like a deviation and weighed like an absence.
- */
+/** One content finding: named like a deviation, weighed like an absence. */
 export interface DeclarationContentFinding {
   kind: DeclarationContentKind;
-  /** The record this is about. Always one: both kinds are per-record. */
+  /** The record this is about. */
   eventId?: string;
 }
 
-/** Everything this check reports that is NOT a deviation, as a closed set. */
+/** Everything this check reports that is not a deviation. */
 export const DECLARATION_NOTE_KINDS = [
-  /**
-   * Every record declared `disclosed` supplied no bytes, so nothing was
-   * selected: the bytes did not travel with the pack.
-   */
+  /** No record declared `disclosed` supplied bytes: they 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.
+   * A claimed hand-off side whose `event_bytes` the pack withholds. Withholding
+   * is minimum disclosure, so it is neither conformant nor non-conformant.
    */
   "pair_record_withheld",
   /**
-   * A record a v2 declaration signs `step` whose `event_bytes` the pack
-   * withholds (rule 9, v1.20). Its role cannot be checked in either direction,
-   * so it is a note; the pack grade still holds the pack at `incomplete`,
-   * because its payload binding is undetermined.
+   * A record a v2 declaration signs `step` whose `event_bytes` are withheld, so
+   * its role cannot be checked. The undetermined binding keeps the pack at
+   * `incomplete`.
    */
   "role_step_withheld",
   /**
-   * Rule 10 (v1.29, A36). A record whose signed `event_type` is `declaration`
-   * and whose content HANDED IN to this reader is exactly `JCS(object)` of a
-   * declaration object of a version this reader knows, carrying exactly that
-   * version's keys, and not this pack's own. The note names the content handed
-   * in, never the record: whether those bytes bind to the record's
-   * `content_hash` is the bundle verifier's check, and an accuser can hand in
-   * declaration-shaped bytes for an honest record. What the pack holds is what
-   * the declaration in its body says, so this moves no verdict.
+   * A record signed as `event_type` `declaration` whose handed-in content is
+   * `JCS` of a known declaration other than this pack's own. Names the content,
+   * not the record: an accuser can hand in such bytes for an honest record.
+   * Moves no verdict.
    */
   "other_declaration_held",
-  /**
-   * Rule 10. A record whose signed `event_type` is `declaration` and whose
-   * content did not reach this reader from either channel, so whether it is a
-   * declaration other than this pack's own is UNKNOWN.
-   */
+  /** A record signed `declaration` whose content did not arrive, so what it declares is unknown. */
   "other_declaration_withheld",
   /**
-   * Rule 11 (v1.36, A45). A claimed chain has a dangling link, and a record
-   * signed by the same producing key has an undetermined payload binding. That
-   * record takes no part in a chain, so whether the missing link is it is
-   * UNKNOWN. Moves nothing: the undetermined binding holds the pack at
-   * `incomplete`.
+   * A claimed chain has a dangling link, and a same-key record with an
+   * undetermined payload binding could be the missing link. Moves nothing.
    */
   "chain_claim_withheld",
 ] as const;
 export type DeclarationNoteKind = (typeof DECLARATION_NOTE_KINDS)[number];
 
-/**
- * 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.
- */
+/** One named finding that is not a deviation. A note never moves the verdict. */
 export interface DeclarationNote {
   kind: DeclarationNoteKind;
   /** How many records the note is about, where it is about a count. */
@@ -360,44 +184,38 @@ export interface DeclarationNote {
   chainKey?: string;
 }
 
-/** One deviation, as data. A surface renders its own prose or calls `renderDeviation`. */
+/** One deviation, as data. */
 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. */
+  /** Which side of a claimed hand-off, for the `pair_record_` deviations. */
   side?: "sent" | "received";
-  /** Which claimed hand-off, by position, for the two `pair-record-` deviations. */
+  /** Which claimed hand-off, by position, for the `pair_record_` deviations. */
   pairIndex?: number;
   /** What is wrong with the declaration itself, for `declaration_malformed`. */
   reason?: string;
-  /**
-   * The `declaration_version` the object claimed, for `declaration_malformed`,
-   * so the rendered sentence names the version the holder wrote to rather than
-   * the first one this reader learned.
-   */
+  /** The `declaration_version` the object claimed, for `declaration_malformed`. */
   version?: string;
-  /** The claimed chain, for the four rule 11 `chain_` deviations. */
+  /** The claimed chain, for the `chain_` deviations. */
   chainKey?: string;
 }
 
 export interface DeclarationCheck {
   verdict: DeclarationVerdict;
-  /** Every deviation, in a fixed order. Empty is only a pass when the verdict says so. */
+  /** Every deviation, in a fixed order. */
   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`.
+   * Mismatches with unsigned content, in a fixed order. They carry the check to
+   * `incomplete` and the pack to `incomplete`, never to `failed`.
    */
   contentFindings: DeclarationContentFinding[];
-  /** Named findings that are NOT deviations, in a fixed order. */
+  /** 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.
+   * Whether the body carried a `declaration` member at all, whatever its shape.
+   * An unreadable claim is not the same as no claim: `gradePack` grades them
+   * differently.
    */
   present: boolean;
   /** `event_id`s the declaration expects, in declaration order. */
@@ -405,28 +223,16 @@ export interface DeclarationCheck {
   /** Of those, the ones declared withheld on purpose. */
   declaredWithheld: string[];
   /**
-   * The `declaration_version` this reader read the object as, one of
-   * `DECLARATION_VERSIONS`, or `null` where the body carries no declaration or
-   * one whose version this reader does not know. Set for a malformed object
-   * too: the version was read, the rest was not. Optional so a check a caller
-   * builds by hand, as rule version 5 adapters do, still type-checks.
+   * The version the object was read as, or `null` where there is no
+   * declaration or its version is unknown. Set for a malformed object too.
    */
   version?: string | null;
-  /**
-   * Every record a v2 declaration signs a role for, in declaration order.
-   * Empty for v1, and for anything this reader could not read.
-   */
+  /** Every record a v2 or v3 declaration signs a role for, in declaration order. */
   roles?: { eventId: string; role: DeclarationRole }[];
-  /**
-   * Every `chain_key` a v3 declaration claims is complete and in order, in
-   * declaration order. Empty for v1 and v2, and for anything this reader could
-   * not read.
-   */
+  /** Every `chain_key` a v3 declaration claims, in declaration order. */
   chains?: string[];
 }
 
-// ---- Reading the pack --------------------------------------------------------
-
 interface DeclarationBundleLike {
   body?: {
     declaration?: unknown;
@@ -439,25 +245,10 @@ interface DeclarationBundleLike {
 }
 
 /**
- * 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.
+ * The record committed inside one `events[]` entry, or `null` where this
+ * reader cannot read it. Bytes that are not `JCS(event record)` are not a
+ * conformant record; parsing goes through the shared `hexToBytes` and
+ * `jcsParse` so both kernels agree on every input.
  */
 function committedRecord(raw: unknown): HandoffRecord | null {
   let parsed: unknown;
@@ -469,33 +260,19 @@ function committedRecord(raw: unknown): HandoffRecord | 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;
+// A pack that names its receipt as the sent side has mislabelled a record.
+const SIDE_EVENT_TYPES = { sent: "agent.handoff.sent", received: "agent.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.
+ * How a claimed hand-off side reads. Three readings, not two: `event_bytes` is
+ * optional, and withholding it is minimum disclosure, not a non-conformant
+ * record.
  */
 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.
+ * How a claimed side reads. Conformant is §4.1's own rule
+ * (`isConformantHandoffRecord`) plus the record type the side names.
  */
 function sideReading(
   p: {
@@ -517,60 +294,41 @@ function sideReading(
 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.
+ * One of the pack's own records. An event with no readable `event_id` gets a
+ * positional `#n` name, so it is reported as surplus rather than dropped.
  */
 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.
-   */
+  /** Whether bytes reached the reader from either channel. */
   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).
+   * Whether the bytes came from `events[].content`, inside the signed body.
+   * Only this channel is the holder's own word.
    */
   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.
+   * Whether the pack supplied `event_bytes` at all. Supplied-but-unreadable and
+   * not supplied are different readings: withholding is minimum disclosure.
    */
   bytesSupplied: boolean;
   /**
-   * Whether this record's payload binding is UNDETERMINED: no `event_bytes`
-   * string and no inline envelope `payload`, the two things the envelope
-   * verifier binds `payload_hash` against. Rule 11 excuses a dangling link
-   * only for such a record's producing key.
+   * Whether the payload binding is undetermined: no `event_bytes` and no inline
+   * `payload`. Rule 11 excuses a dangling link only for such a record's key.
    */
   bindingUndetermined: boolean;
   /**
-   * The envelope's signed `payload_hash` as written, or `""`. For a record
-   * whose binding is undetermined it is the identity a successor's pointer
-   * names: rule 11 excuses a dangling link only where the pointer equals it.
+   * The envelope's signed `payload_hash`, or `""`. Rule 11 excuses a dangling
+   * link only where the pointer equals it.
    */
   payloadHash: string;
 }
 
 /**
- * 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.
+ * The pack's own records, in bundle order. Exported so `./case.ts` reads a
+ * pack through the same parser that grades it.
  */
 export function packRecords(
   bundle: unknown,
@@ -582,19 +340,13 @@ export function packRecords(
     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.
+    // From the envelope, never the record: an unparseable key makes the record
+    // `malformed` under §4.1.
     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.
+    // Only a non-empty string counts as supplied; anything else is the field
+    // not travelling.
     const rawBytes = ev?.event_bytes;
     return {
       eventId,
@@ -610,14 +362,9 @@ export function packRecords(
   });
 }
 
-// ---- 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.
+// RFC 3339 `date-time` with an uppercase `Z`. Format only, not ordering.
 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> =>
@@ -633,21 +380,15 @@ interface ReadDeclaration {
 }
 
 /**
- * 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.
+ * Read a declaration of a known version, or collect every malformation in it
+ * (all of them, so the holder fixes them in one pass).
  */
 function readDeclaration(
   declaration: Record<string, unknown>,
   version: string = DECLARATION_VERSION,
 ): { ok: true; read: ReadDeclaration } | { ok: false; reasons: string[] } {
   const reasons: string[] = [];
-  // Under v2 every `records[]` entry must also carry `role`, exactly `handoff`
-  // or `step` (5.4.1 v1.20, A21); under v1 the member is not read at all, so a
-  // v1 declaration carrying `role` reads exactly as the same object without it.
+  // v2 and v3 require `role` on every entry; v1 does not read the member.
   const roles: { eventId: string; role: DeclarationRole }[] = [];
   const v2 = ROLE_VERSIONS.includes(version);
   const note = (r: string) => reasons.push(r);
@@ -686,8 +427,7 @@ function readDeclaration(
         note(`records[${i}] (${eventId}) has no disclosure of "disclosed" or "content_withheld"`);
         continue;
       }
-      // Compared exactly: `Handoff`, `hand-off` and `step ` are other values,
-      // and a non-string never equals one.
+      // Exact: `Handoff`, `hand-off` and `step ` are other values.
       const role = r["role"];
       if (v2 && !(role === "handoff" || role === "step")) {
         note(`records[${i}] (${eventId}) has no role of "handoff" or "step"`);
@@ -727,8 +467,7 @@ function readDeclaration(
     }
   }
 
-  // v3 is v2 plus a required `chains[]` (5.4.1 v1.36, A45); v1 and v2 do not
-  // read the member.
+  // v3 requires `chains[]`; v1 and v2 do not read the member.
   const chains: string[] = [];
   if (version === DECLARATION_VERSION_V3) {
     const rawChains = declaration["chains"];
@@ -754,10 +493,8 @@ function readDeclaration(
     : { ok: true, read: { records, pairs, roles, chains } };
 }
 
-// ---- The check ---------------------------------------------------------------
-
 const noDeclaration = (): DeclarationCheck => ({
-  verdict: "partial",
+  verdict: "incomplete",
   deviations: [],
   contentFindings: [],
   notes: [],
@@ -770,9 +507,7 @@ const noDeclaration = (): DeclarationCheck => ({
 });
 
 /**
- * The `declaration_version` of an object this reader knows, or `null`: a
- * declaration that is not an object, an absent or `null` version and a version
- * outside `DECLARATION_VERSIONS` are each a claim this reader cannot read.
+ * The `declaration_version` of a declaration this reader knows, or `null`.
  */
 function knownVersion(declaration: unknown): string | null {
   if (!isObject(declaration)) return null;
@@ -783,10 +518,8 @@ function knownVersion(declaration: unknown): string | null {
 }
 
 /**
- * Rule 9 over one record the pack holds: the deviation or note it earns, or
- * `null` where the signed role agrees with the pack and the record. The first
- * of the four deviations that applies, in the order 5.4.2 lists them. Whether
- * 4.1 governs the record is `isHandoffNamespace`, CALLED, never restated.
+ * Rule 9 for one held record: the first deviation that applies in §5.4.2
+ * order, a note, or `null` where the signed role agrees.
  */
 function roleReading(
   p: { eventId: string; publicKey: string; record: HandoffRecord | null; bytesSupplied: boolean },
@@ -809,17 +542,10 @@ function roleReading(
   return null;
 }
 
-/**
- * The `event_type` a declaration record is signed under: a reserved
- * single-segment name, and the one `@sanning/anchor`'s `bundle` anchors a
- * declaration as.
- */
+/** The reserved `event_type` a declaration record is signed under. */
 const DECLARATION_EVENT_TYPE = "declaration";
 
-/**
- * The keys a declaration object carries, under every version this reader
- * knows: exactly these, no more and no fewer (5.4.1).
- */
+/** The exact keys of a declaration object, under every known version (§5.4.1). */
 const DECLARATION_KEYS = ["declaration_version", "case_id", "agents", "period", "records", "handoffs"];
 
 function hasExactKeys(value: unknown, keys: string[]): value is Record<string, unknown> {
@@ -829,14 +555,9 @@ function hasExactKeys(value: unknown, keys: string[]): value is Record<string, u
 }
 
 /**
- * Whether `obj` is shaped like a declaration this reader knows: one of
- * `DECLARATION_VERSIONS` compared exactly, exactly the keys that version
- * defines, and the value types this module reads.
- *
- * It is the shape test `@sanning/anchor`'s `isDeclarationShape` makes, and it
- * checks shape only, not the 5.4.1 rules `readDeclaration` grades: a stale
- * declaration is somebody else's claim, and this reader does not grade it, it
- * names it.
+ * Whether `obj` has the shape of a known declaration: a known version, exactly
+ * its keys, and the value types read here. Shape only: another holder's stale
+ * declaration is named, not graded.
  */
 function isDeclarationShape(obj: unknown): boolean {
   if (!isObject(obj)) return false;
@@ -871,9 +592,8 @@ function isDeclarationShape(obj: unknown): boolean {
 }
 
 /**
- * The content bytes disclosed for one record, or `null` where none are usable:
- * `events[].content` first, then the side-content map, chosen the way the
- * bundle verifier chooses the bytes it binds.
+ * The content bytes disclosed for one record, or `null`: `events[].content`
+ * first, then the side-content map, as the bundle verifier chooses.
  */
 function disclosedBytes(
   ev: unknown,
@@ -908,9 +628,8 @@ function sameBytes(a: Uint8Array, b: Uint8Array): boolean {
 }
 
 /**
- * Whether `raw` is exactly `JCS(object)` of a declaration-shaped object.
- * Canonical bytes, not merely parseable ones: a declaration is anchored as
- * `JCS(declaration)`, and nothing an agent writes by accident.
+ * Whether `raw` is exactly `JCS` of a declaration-shaped object. Canonical
+ * bytes only, so an agent does not write one by accident.
  */
 function isDeclarationBytes(raw: Uint8Array): boolean {
   try {
@@ -923,13 +642,8 @@ function isDeclarationBytes(raw: Uint8Array): boolean {
 
 /**
  * Rule 10: every record that is a declaration other than the pack's own, in
- * bundle order.
- *
- * The record's `event_type` is read from its signed `event_bytes`, so a record
- * whose bytes the pack withholds is not named: the reader cannot see what it
- * was signed as. Its content is read from either channel; a record whose
- * content is byte for byte `JCS` of the pack's own declaration is the pack's
- * own and is never named.
+ * bundle order. The `event_type` comes from the signed `event_bytes`, so a
+ * record with withheld bytes is not named.
  */
 function otherDeclarationNotes(
   bundle: unknown,
@@ -949,9 +663,8 @@ function otherDeclarationNotes(
     if (p.record === null || p.record.event_type !== DECLARATION_EVENT_TYPE) return;
     const raw = disclosedBytes(events[i], p, content);
     if (raw === null) {
-      // Offered and unusable is not withheld: something arrived, it is not a
-      // declaration, and the bundle verifier names what is wrong with it.
-      // Nothing arrived is the reading the reader cannot settle.
+      // Unusable content is the bundle verifier's finding; only content that
+      // never arrived is unknown here.
       if (!p.disclosed) notes.push({ kind: "other_declaration_withheld", eventId: p.eventId });
       return;
     }
@@ -964,50 +677,27 @@ function otherDeclarationNotes(
 /**
  * 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.
- *
- * `chains` is `readChains` over the SAME bundle. Only a v3 declaration that
- * claims a chain reads it (rule 11). It is an argument rather than computed
- * here because `readChains` is asynchronous and this check is not, and Python's
- * `check_declaration` takes it the same way so the two kernels share one
- * contract. A v3 declaration that claims a chain, checked without it, reads as
- * a reader that does not know v3 reads it: `partial`, nothing named, and the
- * pack `incomplete`. Leaving it out can never read `verified`.
+ * @param content - The side-content map `verifyEvidenceBundle` takes.
+ * @param chains - `readChains` over the same bundle, read only for a v3 chain
+ *   claim. Omitted, such a claim reads `incomplete`, never `verified`.
  *
- * 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.
+ * The verdict does not read the bundle verdict: a declaration can match over
+ * forged signatures, and `gradePack` combines the two.
  */
 export function checkDeclaration(
   bundle: unknown,
   content?: SideContentMap | null,
   links?: readonly ChainLink[] | 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.
+  // An absent `declaration` claimed nothing; one present but unreadable did
+  // claim something. The two must not collapse into one.
   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.
+  // An unreadable declaration is unknown, not an accusation, but each such
+  // shape is one field from a valid re-sealed pack, so none may reach a clean
+  // pack verdict.
   const version = knownVersion(declaration);
   if (version === null) {
     return { ...noDeclaration(), present: true };
@@ -1038,13 +728,8 @@ export function checkDeclaration(
   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[]`.
+  // First in bundle order wins; later records under the same id are named.
+  // A map by id would be last-write-wins and grade one of them by nothing.
   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);
@@ -1052,24 +737,13 @@ export function checkDeclaration(
 
   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.
+  // Declared and absent: the trimmed hand-over.
   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.
+  // Present and undeclared. An unnameable record is surplus by construction.
+  // A repeated id is named once as `duplicate_event_id`, not also as surplus.
   const seenInPack = new Set<string>();
   for (const p of pack) {
     if (p.nameable && seenInPack.has(p.eventId)) {
@@ -1082,11 +756,8 @@ export function checkDeclaration(
     }
   }
 
-  // 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.
+  // If no held `disclosed` record supplied bytes, nothing was selected: a note.
+  // Some supplying and some not is a selection, and every shortfall is named.
   const disclosedHeld = records
     .filter((r) => !r.withheld)
     .map((r) => byId.get(r.eventId))
@@ -1096,28 +767,16 @@ export function checkDeclaration(
     ? [{ 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`.
+  // The disclosure rules, over held records only. Each splits on the channel:
+  // in-body content is the holder's signed word and a mismatch is a deviation;
+  // side content is unsigned and yields a content finding.
   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.
+      // Always content-dependent: deleting one file beside the pack reaches it.
       contentFindings.push({ kind: "content_dependent_withholding", eventId: r.eventId });
     } else if (r.withheld && p.disclosed) {
       if (p.disclosedInBody) {
@@ -1128,26 +787,9 @@ export function checkDeclaration(
     }
   }
 
-  // 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`.
+  // Each claimed side must be declared and be a conformant hand-off record of
+  // that side. A withheld side is a note, not a deviation. The pair itself is
+  // the case verdict's to check.
   for (const [i, pair] of pairs.entries()) {
     for (const side of ["sent", "received"] as const) {
       const id = pair[side];
@@ -1167,12 +809,8 @@ export function checkDeclaration(
     }
   }
 
-  // Rule 9 (5.4.2 v1.20, A21), `sanning.declaration/v2` only: a record's
-  // signed role against the pack and against the record. Its deviations follow
-  // every deviation rules 1 to 8 report, and its note follows every other
-  // note, both in `records[]` order. It reads the signed body alone and NEVER
-  // the side-content map, so no party that signed nothing can create, move or
-  // remove one of its findings.
+  // Rule 9, v2 and v3: reads the signed body alone, never the side-content
+  // map, so no party that signed nothing can move its findings.
   if (roles.length > 0) {
     const claimed = new Set<string>();
     for (const pair of pairs) {
@@ -1181,7 +819,7 @@ export function checkDeclaration(
     }
     for (const { eventId, role } of roles) {
       const p = byId.get(eventId);
-      // Declared and absent: rule 1 named it, and one defect is one finding.
+      // Already named by rule 1.
       if (p === undefined) continue;
       const kind = roleReading(p, role, claimed.has(eventId));
       if (kind === "role_step_withheld") notes.push({ kind, eventId });
@@ -1189,12 +827,8 @@ export function checkDeclaration(
     }
   }
 
-  // Rule 11 (5.4.2 v1.36, A45), `sanning.declaration/v3` only: a chain the
-  // holder signed as complete and in order, against the chain reading of the
-  // same pack. Its deviations follow rule 9's, and its notes follow rule 9's
-  // and precede rule 10's, both in `chains[]` order.
-  // A caller that passed no links leaves the claim UNREAD: rules 1 to 10 still
-  // run, and the verdict below is never `verified`.
+  // Rule 11, v3 only. Without chain links the claim is unread, and the verdict
+  // is never `verified`.
   const unread = claimedChains.length > 0 && (links === undefined || links === null);
   if (claimedChains.length > 0 && links !== undefined && links !== null) {
     const found = chainClaimFindings(claimedChains, links, pack);
@@ -1202,23 +836,16 @@ export function checkDeclaration(
     notes.push(...found.notes);
   }
 
-  // Rule 10 (5.4.2 v1.29, A36): content handed in for a record signed
-  // `declaration` that is a declaration other than this pack's own. Notes only, in bundle order, after every other note, and
-  // never a deviation: the pack holds what its own declaration says whatever
-  // one of its records says.
+  // Rule 10: notes only, after every other note.
   notes.push(...otherDeclarationNotes(bundle, pack, declaration, content));
 
-  // 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.
+  // A deviation always wins. Otherwise a content finding is undetermined:
+  // `incomplete`.
   const verdict: DeclarationVerdict =
     deviations.length > 0
       ? "failed"
       : contentFindings.length > 0 || unread
-        ? "partial"
+        ? "incomplete"
         : "verified";
 
   return {
@@ -1236,22 +863,17 @@ export function checkDeclaration(
 }
 
 /**
- * Rule 11 over every claimed `chain_key`, in `chains[]` order. The twin of
- * Python's `_chain_claim_findings`, which states the rule in full.
+ * Rule 11 over every claimed `chain_key`, in `chains[]` order. Python's twin is
+ * `_chain_claim_findings`.
  *
- * A claim covers every record whose OWN signed linkage names the key
- * (`source === "record"`), under every producing key; an adapter's metadata
- * linkage is never read for a claim. Under a claim, in bundle order: every
- * record after the first that begins the chain is a `chain_second_root`; a
- * record whose predecessor already has an earlier successor in its chain is a
- * `chain_fork`; a record whose pointer resolves to no record of its own chain
- * (one producing key, one `chain_key`) is a `chain_link_dangling`, with no
- * window allowance; a claimed key with no such record is
- * `chain_claimed_absent`. Links are read from the record each envelope binds,
- * `event_bytes` or an inline `payload`. A dangling link is the note
- * `chain_claim_withheld` instead, once per key, only where its pointer equals
- * the signed `payload_hash` of a same-key record whose binding is
- * undetermined: exactly the missing link. Nothing else is excused.
+ * A claim covers every record whose own signed linkage names the key, under
+ * every producing key; adapter metadata linkage is never read. In bundle order:
+ * a record after the first root is `chain_second_root`; a second successor of
+ * one predecessor is `chain_fork`; a pointer to no record of its own chain is
+ * `chain_link_dangling`; a claimed key with no record is `chain_claimed_absent`.
+ * A dangling link is excused as the note `chain_claim_withheld` only where its
+ * pointer equals the `payload_hash` of a same-key record with an undetermined
+ * binding.
  */
 function chainClaimFindings(
   claimed: string[],
@@ -1300,43 +922,10 @@ function chainClaimFindings(
   return { deviations, notes };
 }
 
-// ---- 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.
+ * What a pack's declaration claims, for `./case.ts`: which records the holder
+ * claimed as a hand-off side, so a hand-off record claimed nowhere is a named
+ * finding. Read from the same functions `checkDeclaration` uses.
  */
 export interface DeclarationClaims {
   /**
@@ -1345,37 +934,23 @@ export interface DeclarationClaims {
    */
   present: boolean;
   /**
-   * Whether this reader could read the claim as one of `DECLARATION_VERSIONS` 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".
+   * Whether the claim reads as a known version and satisfies §5.4.1. `false`
+   * never means "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.
-   */
+  /** Every `event_id` a `handoffs[]` entry names, in order, without duplicates. */
   claimedSides: string[];
-  /**
-   * The version the claim was read as, where `readable`; else `null`. The case
-   * reader's claim check is v1's alone (5.5.1 v1.20): a v2 pack's claim check
-   * is rule 9, which the declaration check already ran.
-   */
+  /** The version the claim was read as, where `readable`; else `null`. */
   version: string | null;
-  /** Every record a READABLE v2 declaration signs a role for. Empty for v1. */
+  /** Every record a readable v2 or v3 declaration signs a role for. */
   roles: { eventId: string; role: DeclarationRole }[];
 }
 
 /**
- * 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.
+ * Read the claim a pack's declaration makes, without grading the pack. Total:
+ * never throws, so a hostile pack is reported rather than crashing the reader.
  */
 export function declarationClaims(bundle: unknown): DeclarationClaims {
   const none: DeclarationClaims = {
@@ -1413,55 +988,47 @@ export function declarationClaims(bundle: unknown): DeclarationClaims {
   };
 }
 
+/**
+ * One line a surface can print beside the pack verdict. Both kernels print the
+ * same sentence.
+ */
 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";
+    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.
+    // Before the content-findings branch: a deviation always wins.
     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.
+      // Both counts: the two facts are about different records.
       return (
-        `this pack DEVIATES from its own declaration, in ${check.deviations.length} way(s), ` +
+        `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)`;
+    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.
+    // Before the `incomplete` branch below: this says what the reader could not
+    // establish, that one says the claim could not be read.
     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" && (check.chains ?? []).length > 0) {
-    // Read before the branch below: the declaration WAS read, and its chain
-    // claim was not checked because the caller gave no reading.
+  if (check.verdict === "incomplete" && (check.chains ?? []).length > 0) {
+    // The declaration was read; its chain claim was not checked.
     return (
       "this pack holds what it declares, and says its chains are complete " +
       "and in order, which this verifier did not check, so whether they " +
-      "are is UNKNOWN"
+      "are is unknown"
     );
   }
-  if (check.verdict === "partial") {
+  if (check.verdict === "incomplete") {
     return (
       "this pack says what it holds in a declaration this verifier cannot read, " +
-      "so whether it is complete is UNKNOWN"
+      "so whether it is complete is unknown"
     );
   }
   return (
@@ -1470,27 +1037,24 @@ export function renderDeclarationSummary(check: DeclarationCheck): string {
   );
 }
 
-/**
- * The house wording for one note. Offered, not imposed, as `renderDeviation`
- * is.
- */
+/** The house wording for one note. */
 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"
+        `this pack declares ${note.count} ${note.count === 1 ? "record" : "records"} 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"
+        "is, is unknown"
       );
     case "role_step_withheld":
       return (
         `${note.eventId} is signed as a step and this pack withholds its ` +
-        "record bytes, so whether it is one is UNKNOWN"
+        "record bytes, so whether it is one is unknown"
       );
     case "other_declaration_held":
       return (
@@ -1502,7 +1066,7 @@ export function renderNote(note: DeclarationNote): string {
       return (
         `${note.eventId} is signed as a declaration and no content for it ` +
         "reached this verifier, so whether it is a declaration other than " +
-        "this pack's own is UNKNOWN"
+        "this pack's own is unknown"
       );
     case "chain_claim_withheld":
       return (
@@ -1515,12 +1079,8 @@ export function renderNote(note: DeclarationNote): string {
 }
 
 /**
- * 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.
+ * The house wording for one content finding. Names the content, never the
+ * holder: the bytes are unsigned.
  */
 export function renderContentFinding(finding: DeclarationContentFinding): string {
   switch (finding.kind) {
@@ -1528,17 +1088,20 @@ export function renderContentFinding(finding: DeclarationContentFinding): string
       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"
+        "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"
+        "whether the holder disclosed them is unknown"
       );
   }
 }
 
+/**
+ * The house wording for one deviation. Both kernels return the same text.
+ */
 export function renderDeviation(deviation: DeclarationDeviation): string {
   switch (deviation.kind) {
     case "declaration_malformed":
@@ -1547,9 +1110,9 @@ export function renderDeviation(deviation: DeclarationDeviation): string {
         `${deviation.version || DECLARATION_VERSION}: ${deviation.reason}`
       );
     case "declared_absent":
-      return `${deviation.eventId} is declared and is NOT in this pack`;
+      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`;
+      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 ` +