@sanning/proof 0.19.1 → 0.20.0

package/dist/declaration.js

@@ -1,152 +1,47 @@
-// 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.
+// 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.
 import { hexToBytes, utf8 } from "./crypto.js";
 import { jcs, jcsParse } from "./verifier.js";
 import { isConformantHandoffRecord, isHandoffNamespace } from "./handoff.js";
 import { hasSideContent, inBodyContentOffered, sideContentEntry, } 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,
@@ -155,13 +50,11 @@ export const DECLARATION_VERSIONS = [
 /** The versions whose every `records[]` entry carries a signed `role`. */
 const ROLE_VERSIONS = [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"];
-/** The three states a declaration check can reach, from the §3 vocabulary. */
-export const DECLARATION_VERDICTS = ["verified", "failed", "partial"];
+export const DECLARATION_VERDICTS = ["verified", "failed", "incomplete"];
 export const DECLARATION_DEVIATION_KINDS = [
     /** The declaration is written to this version and is not readable as one. */
     "declaration_malformed",
@@ -169,160 +62,86 @@ 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",
 ];
 /**
- * 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",
 ];
-/** 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",
 ];
 /**
- * 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) {
     let parsed;
@@ -334,20 +153,11 @@ function committedRecord(raw) {
     }
     return isObject(parsed) ? parsed : 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" };
+// 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" };
 /**
- * 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, side) {
     if (!p.bytesSupplied)
@@ -361,11 +171,8 @@ function sideReading(p, side) {
 }
 const bodyOf = (bundle) => bundle?.body;
 /**
- * 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, content) {
     const events = bodyOf(bundle)?.events;
@@ -375,19 +182,13 @@ export function packRecords(bundle, content) {
         const raw = ev?.envelope?.event_id;
         const nameable = typeof raw === "string" && raw.length > 0;
         const eventId = nameable ? raw : `#${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,
@@ -402,28 +203,18 @@ export function packRecords(bundle, content) {
         };
     });
 }
-// ---- 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) => typeof v === "object" && v !== null && !Array.isArray(v);
 const isId = (v) => typeof v === "string" && v.length > 0;
 /**
- * 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, version = DECLARATION_VERSION) {
     const reasons = [];
-    // 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 = [];
     const v2 = ROLE_VERSIONS.includes(version);
     const note = (r) => reasons.push(r);
@@ -463,8 +254,7 @@ function readDeclaration(declaration, version = DECLARATION_VERSION) {
                 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"`);
@@ -504,8 +294,7 @@ function readDeclaration(declaration, version = DECLARATION_VERSION) {
             pairs.push({ sent: sent, received: received });
         }
     }
-    // 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 = [];
     if (version === DECLARATION_VERSION_V3) {
         const rawChains = declaration["chains"];
@@ -530,9 +319,8 @@ function readDeclaration(declaration, version = DECLARATION_VERSION) {
         ? { ok: false, reasons }
         : { ok: true, read: { records, pairs, roles, chains } };
 }
-// ---- The check ---------------------------------------------------------------
 const noDeclaration = () => ({
-    verdict: "partial",
+    verdict: "incomplete",
     deviations: [],
     contentFindings: [],
     notes: [],
@@ -544,9 +332,7 @@ const noDeclaration = () => ({
     chains: [],
 });
 /**
- * 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) {
     if (!isObject(declaration))
@@ -557,10 +343,8 @@ function knownVersion(declaration) {
         : 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, role, claimed) {
     if (role === "handoff")
@@ -576,16 +360,9 @@ function roleReading(p, role, claimed) {
     }
     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, keys) {
     if (!isObject(value))
@@ -594,14 +371,9 @@ function hasExactKeys(value, keys) {
     return have.length === keys.length && keys.every((k) => Object.prototype.hasOwnProperty.call(value, k));
 }
 /**
- * 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) {
     if (!isObject(obj))
@@ -644,9 +416,8 @@ function isDeclarationShape(obj) {
         chains.every((c) => hasExactKeys(c, ["chain_key"]) && typeof c["chain_key"] === "string"));
 }
 /**
- * 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, p, content) {
     const inBody = isObject(ev) ? ev["content"] : undefined;
@@ -682,9 +453,8 @@ function sameBytes(a, b) {
     return true;
 }
 /**
- * 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) {
     try {
@@ -697,13 +467,8 @@ function isDeclarationBytes(raw) {
 }
 /**
  * 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, pack, declaration, content) {
     const events = pack.length > 0 ? (bodyOf(bundle)?.events ?? []) : [];
@@ -720,9 +485,8 @@ function otherDeclarationNotes(bundle, pack, declaration, content) {
             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;
@@ -737,46 +501,23 @@ function otherDeclarationNotes(bundle, pack, declaration, content) {
 /**
  * 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, content, links) {
-    // `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["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 };
@@ -804,37 +545,21 @@ export function checkDeclaration(bundle, content, links) {
     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();
     for (const p of pack) {
         if (p.nameable && !byId.has(p.eventId))
             byId.set(p.eventId, p);
     }
     const deviations = [];
-    // 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();
     for (const p of pack) {
         if (p.nameable && seenInPack.has(p.eventId)) {
@@ -847,11 +572,8 @@ export function checkDeclaration(bundle, content, links) {
             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.
+    // 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))
@@ -860,18 +582,9 @@ export function checkDeclaration(bundle, content, links) {
     const notes = 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`.
+    // 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 = [];
     for (const r of records) {
         const p = byId.get(r.eventId);
@@ -880,10 +593,7 @@ export function checkDeclaration(bundle, content, links) {
         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) {
@@ -895,26 +605,9 @@ export function checkDeclaration(bundle, content, links) {
             }
         }
     }
-    // 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"]) {
             const id = pair[side];
@@ -936,12 +629,8 @@ export function checkDeclaration(bundle, content, links) {
             }
         }
     }
-    // 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();
         for (const pair of pairs) {
@@ -952,7 +641,7 @@ export function checkDeclaration(bundle, content, links) {
         }
         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));
@@ -962,33 +651,22 @@ export function checkDeclaration(bundle, content, links) {
                 deviations.push({ kind, eventId });
         }
     }
-    // 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);
         deviations.push(...found.deviations);
         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 = deviations.length > 0
         ? "failed"
         : contentFindings.length > 0 || unread
-            ? "partial"
+            ? "incomplete"
             : "verified";
     return {
         verdict,
@@ -1004,22 +682,17 @@ export function checkDeclaration(bundle, content, links) {
     };
 }
 /**
- * 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, links, pack) {
     const deviations = [];
@@ -1068,12 +741,8 @@ function chainClaimFindings(claimed, links, pack) {
     return { deviations, notes };
 }
 /**
- * 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) {
     const none = {
@@ -1112,68 +781,57 @@ export function declarationClaims(bundle) {
         roles: read.read.roles,
     };
 }
+/**
+ * One line a surface can print beside the pack verdict. Both kernels print the
+ * same sentence.
+ */
 export function renderDeclarationSummary(check) {
     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.
-            return (`this pack DEVIATES from its own declaration, in ${check.deviations.length} way(s), ` +
+            // Both counts: the two facts are about different records.
+            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)`;
+        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 (`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.
- */
+/** The house wording for one note. */
 export function renderNote(note) {
     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");
+            return (`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 (`the content handed in for ${note.eventId} is a declaration that is ` +
                 "not this pack's own: it says what some pack holds, and what this " +
@@ -1181,7 +839,7 @@ export function renderNote(note) {
         case "other_declaration_withheld":
             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 (`this pack declares chain ${note.chainKey} complete and in order, ` +
                 "and a link in it points at a record its producer signed and this " +
@@ -1190,34 +848,33 @@ export function renderNote(note) {
     }
 }
 /**
- * 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) {
     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");
+                "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) {
     switch (deviation.kind) {
         case "declaration_malformed":
             return ("the declaration is not readable as " +
                 `${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 ` +
                 "in its own signed body");