@sanning/proof 0.10.0 → 0.11.1

package/dist/declaration.js

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