@sanning/proof 0.10.0 → 0.11.0

package/dist/case.js

@@ -0,0 +1,1318 @@
+/**
+ * One verdict for a CASE, across packs and across organizations (anchor#198).
+ *
+ * The TypeScript half of `src/sanning_proof/case.py`. Both kernels are held to
+ * the same corpus set, `test-vectors/case/`, so neither can pass by agreeing
+ * with the other.
+ *
+ * WHY THIS LAYER EXISTS, AND WHAT IT IS THE CLOSURE FOR
+ * =====================================================
+ *
+ * `envelope-spec.md` 4.1 reads records. `evidence-bundle.md` 5.4 reads one pack
+ * against its own declaration. Neither can answer the question an audit team
+ * actually asks, and 4.1 (v1.10, A15) and 5.4.2 rule 7 (v1.10) now say so in
+ * these words:
+ *
+ *     **A pack a party assembles about itself is not self-proving about what
+ *     that party LEFT OUT.**
+ *
+ * `handoffs[]` MAY be empty (5.4.1), so a holder declares a record in
+ * `records[]` and claims it nowhere: rule 2 cannot reach it because it is
+ * declared, rule 7 cannot reach it because it is unclaimed, and the pack reads
+ * `verified` with no deviation, which is the same reading the honest pack gets.
+ * The corpus pins that pack as EXPECTED
+ * (`test-vectors/declaration/declaration-unclaimed-record-01`) rather than
+ * leaving it to be rediscovered. Six repairs treated a property of one-sided
+ * evidence as a defect in a rule (proof#137, ratified by Phil 2026-09-22), and
+ * the omission happens BEFORE any reader runs, so no rule at either of those
+ * layers reaches it.
+ *
+ * **This module is the closure, and the reason it can be is that it reads
+ * several parties' packs at once.** A `handoff.sent` with no counterpart among
+ * the records of the case is always NAMED, and when a pack signed by the key
+ * that record names is in the case, the reading says that pack holds no
+ * counterpart. No party can make a missing counterpart read clean.
+ *
+ * What it does NOT establish is that a party which presented no pack signed by
+ * the named key recorded nothing. Nothing binds a pack's wrapper key to the
+ * keys its records are signed with, so a counterparty that hands over its
+ * account under any other key, or inside an export an issuer signed, or not at
+ * all, gets the reading that says only that no pack in the case is signed by
+ * the named key. Proving that a party did NOT record something needs that
+ * party's account or a completeness mechanism over its records, and which of
+ * those this reading waits for is proof#143.
+ *
+ * WHAT THAT MEANS FOR HOW THE JOIN IS BUILT
+ * =========================================
+ *
+ * **The case reader does not consult `handoffs[]` to pair anything.** That is
+ * not an oversight, it is the whole mechanism. The declaration is written by
+ * the party being audited, so a join keyed on it inherits exactly the hole it
+ * is meant to close: claim the clean pair, keep the tampered receipt
+ * unclaimed, and a declaration-keyed reader never grades the receipt at all.
+ * This reader pairs records with records, through `readHandoff`, over the
+ * union of every record every pack in the case supplied. `handoffs[]` is read
+ * for ONE thing and one only: to name a record its own holder DECLARED and
+ * claimed nowhere (`RECORD_UNCLAIMED`), which is the pinned vector above
+ * becoming visible. That claim check runs over every record a pack declares,
+ * and not only over the ones 4.1 governs, because "is this a conformant
+ * hand-off record" is an answer the audited party writes.
+ *
+ * **Matching is on hashes and identifiers alone and NEVER on tenancy**
+ * (anchor#198, and DL-60: producer identity gates what the plane accepts and
+ * never whether evidence verifies). The union pile is not partitioned by pack,
+ * by issuer, by `tenant_id` or by organization anywhere in this module, so a
+ * pair assembled by two organizations reads exactly as a pair assembled by
+ * one. There is no code path here that reads a tenant.
+ *
+ * THE DEFECT CLASS THIS MODULE IS WRITTEN AGAINST
+ * ===============================================
+ *
+ * Seventeen findings on this program share one generator: **a deviation
+ * designed as a comparison between two present things, where the deviation
+ * itself removes one of them, so the code takes the "nothing to compare"
+ * branch written for the honest case.** A rule shaped that way reads the
+ * absence of a signal as "fine" rather than as "I could not tell", and a real
+ * deviation grades clean.
+ *
+ * Acceptance criterion 3 of anchor#198 is made of exactly that shape: *a
+ * one-sided hand-off is an exception, not a failure*. So the four rules below
+ * are structural and are the thing to preserve in any change here.
+ *
+ * 1. **Every exception is NAMED and appears in the output, and every exception
+ *    contributes a verdict.** There is no path through this module that
+ *    removes a record, a pack or a claim from the reading. An empty
+ *    `exceptions` is the ONLY shape a reader may read as clean, and `readCase`
+ *    is invariant: `verified` is reachable only when that array is empty.
+ * 2. **Nothing a party writes decides whether grading happens.** No graded
+ *    value is part of any key that selects a code path. The pile is everything
+ *    every pack supplied; there is no filter.
+ * 3. **Every field that selects a code path and is chosen by the party being
+ *    audited has an accept-set, and an unknown value goes to a named exception
+ *    rather than to silence.** `body_type` is `CASE_BODY_TYPES`;
+ *    `declaration_version` is `checkDeclaration`'s; `event_type` and
+ *    `event.counterparty_public_key` are 4.1's, through `readHandoffs`. A pack
+ *    that supplies zero records is `PACK_HOLDS_NO_RECORDS` and a case with no
+ *    hand-off record in it at all is `CASE_HOLDS_NO_HANDOFF_RECORDS`, because
+ *    "nothing to grade" is never "nothing is wrong".
+ * 4. **The 4.1 predicates are CALLED, never restated.** `readHandoffs`,
+ *    `normalizedSigningKey` and `packRecords` are the one implementation of
+ *    each rule. A validation copied beside the one that enforces it drifts,
+ *    and a copy that is looser blesses a value the real one then rejects.
+ *
+ * EVERY EARLY EXIT IN THIS MODULE, AND WHAT IT SKIPS
+ * ==================================================
+ *
+ * Three defects on this layer were one shape: an exit between a record
+ * entering the pile and a check running over it, with the audited party
+ * choosing whether the exit was taken. So the exits are enumerated here rather
+ * than left to be rediscovered a fourth time. `src/sanning_proof/case.py` has
+ * the same exits in the same order, and the pull request that added this list
+ * carries the same table.
+ *
+ * 1. **No packs** (`return`). Skips everything. Reached by the reader, who
+ *    chose what to hand in. Named: `CASE_HOLDS_NO_PACKS`.
+ * 2. **A wrapper key this reader cannot read** (`continue`). Skips the bundle
+ *    verification, the declaration check and every record in the pack. The
+ *    holder writes the key, so it steers here freely, and the pack is NAMED
+ *    (`PACK_KEY_UNREADABLE`). Both bundle verifiers now refuse every such
+ *    spelling in the same words (proof#142), so this exit and exit 3 agree on
+ *    which packs they take; it stays first because it names WHY. While any
+ *    pack takes this exit, a one-sided record whose named key signed no pack
+ *    reads `COUNTERPART_ABSENT_SIGNER_UNKNOWN` and never the innocent
+ *    `COUNTERPART_ABSENT`.
+ * 3. **The wrapper does not hold** (`continue`): `signatureOk` and
+ *    `bodyHashOk` are not both true. Skips the declaration check and every
+ *    record in the pack, and the key it claims is never counted as a pack
+ *    signer. **This is the forger's case and the only exit that turns on
+ *    provenance**: those two fields are the whole of what ties a pack to a
+ *    key. Reached by whoever built the pack, and by anyone who alters its
+ *    unsigned `signature` field, which is indistinguishable from a forgery.
+ *    Named: `PACK_DOES_NOT_VERIFY`, and it moves one-sided records to
+ *    `COUNTERPART_ABSENT_SIGNER_UNKNOWN` exactly as exit 2 does.
+ *
+ *    A pack whose wrapper HOLDS is never sent here, whatever is wrong inside
+ *    it (gate 3 on proof#140): its key is counted, its own bundle verdict is
+ *    `PACK_BUNDLE_NOT_VERIFIED` when that verdict is not `verified`, and each
+ *    record is graded on its own envelope below.
+ * 3b. **The bundle verdict is `malformed`** (`continue`, after exit 3 and after
+ *    `PACK_BUNDLE_NOT_VERIFIED`). The body is one the verifier could not read,
+ *    so it graded no record. The key is already counted.
+ * 4. **`body_type` outside `CASE_BODY_TYPES`** (`continue`). Skips the
+ *    declaration check and every record in the pack. The holder writes
+ *    `body_type`, so the holder steers here freely, which is why it is named
+ *    every time (`PACK_BODY_TYPE_UNKNOWN`) and why the pack's wrapper key is
+ *    counted ABOVE it: a counterparty cannot leave the damning counterpart
+ *    line by choosing a body (F3). `sanning.evidence.export/v2` lands here and
+ *    is not unwrapped.
+ * 5. **No records** (`continue`). Skips the declaration check, over nothing.
+ *    The holder steers here by handing over an empty `events[]`. Named:
+ *    `PACK_HOLDS_NO_RECORDS`; the wrapper key is already counted.
+ * 5b. **A record under a quarantined profile** and 5c. **a record whose own
+ *    envelope does not verify** (`continue`). Each skips 4.1 for that record,
+ *    its candidacy for any other record, and the claim check, because 4.1
+ *    compares only envelopes that verified (`HeldRecord`). Named:
+ *    `RECORD_PROFILE_QUARANTINED` (`incomplete`, pending DL-63) and
+ *    `RECORD_ENVELOPE_DOES_NOT_VERIFY` (`failed`). Neither removes a named
+ *    failure from another record: the other records of the pack are still
+ *    graded, and pairs still form over every record that verified.
+ * 6. **`event_bytes` withheld** and 7. **`event_bytes` unreadable**
+ *    (`continue`). Each skips 4.1 for that record, its candidacy for any other
+ *    record, and the claim check. The holder steers into both by what it
+ *    discloses. Each is named in the claim check's place
+ *    (`RECORD_BYTES_WITHHELD` `incomplete`, `RECORD_BYTES_UNREADABLE`
+ *    `malformed`), so neither buys a cleaner reading than an unclaimed record
+ *    would get, and neither decides which counterpart kind another record
+ *    gets, since that reads wrapper keys.
+ *
+ *    Not exits: a record whose envelope verifies and whose content does not
+ *    match its commitment is `RECORD_CONTENT_MISMATCH`, and one that fails
+ *    another check inside its pack is `RECORD_DOES_NOT_VERIFY_IN_ITS_PACK`.
+ *    Both are named and both STAY in the pile, so neither unsigned content
+ *    handed in beside a pack nor a broken inclusion proof removes a record
+ *    from pairing.
+ * 8. **`not_a_handoff_record`** (`continue`). Skips the hand-off count and the
+ *    counterpart, ambiguity and pair reporting, which 4.1 does not give a
+ *    record outside its scope. The holder steers here by respelling a field.
+ *    It no longer skips the claim check, which runs ABOVE it because it asks
+ *    what the pack SAID and not what the record is (F1).
+ * 9. **THIS record is malformed** (`continue`). Skips the counterpart,
+ *    ambiguity and pair reporting, and 4.1 computed none of them for a
+ *    malformed subject, so nothing is lost. A party steers here only by
+ *    breaking a record it signed, and the record is named `RECORD_MALFORMED`.
+ *    A well formed record whose CANDIDATE is malformed does not take this
+ *    exit: it is `COUNTERPART_MALFORMED` and the reporting below still runs
+ *    (F2).
+ * 10. **`counterpart_absent`** (`continue`). Skips the ambiguity and pair
+ *     reporting, and there is nothing to skip: 4.1 emits that finding only
+ *     for an EMPTY candidate list. Which of the three counterpart kinds it
+ *     gets reads the keys of the packs that verified, counted before exit 4,
+ *     and whether any pack took exit 2 or 3.
+ *
+ * Not an exit, and listed because it is one more place this shape could
+ * hide: the claim check runs only where the pack's declaration is READABLE. An
+ * absent or unreadable one is named once for the pack (`PACK_UNDECLARED`,
+ * `PACK_DECLARATION_UNREADABLE`) rather than once per record.
+ *
+ * THE VERDICT VOCABULARY IS CLOSED
+ * ================================
+ *
+ * `verified`, `failed`, `partial`, `mixed`, `incomplete` and `malformed`,
+ * every one of them already in use (`evidence-bundle.md` 3 and
+ * `PACK_VERDICTS`). **No new word is coined anywhere in this module**, and
+ * `CASE_VERDICTS` is asserted against `PACK_VERDICTS` by the test suite so a
+ * future addition here cannot invent one quietly. Everything this module has
+ * to say that is not one of those six is an EXCEPTION KIND reported beside the
+ * verdict, exactly as `counterpart_absent` and `not_a_handoff_record` are
+ * findings beside a verdict in 4.1.
+ *
+ * A case with more than one outcome is `mixed` (anchor#198, criterion 4).
+ *
+ * WHAT THIS READER DOES NOT CLAIM
+ * ===============================
+ *
+ * * **Not that the case is complete.** Joining is voluntary. A counterparty
+ *   that never handed over a pack leaves `COUNTERPART_ABSENT`, which is an
+ *   exception and never a failure. It says that no pack in the case is signed
+ *   by the named key, and nothing about what that party recorded.
+ * * **Not that a party which presented no pack under the named key recorded
+ *   nothing.** See the top of this comment, and proof#143.
+ * * **Not that two organizations are independent.** One team holding both keys
+ *   proves which agent said what, not that two parties agreed (4.1, 5.4.4).
+ * * **Not that a `verified` case has no other problem.** It reads hand-offs.
+ *   It runs `verifyEvidenceBundle` over every pack itself, offline and with no
+ *   gateways, and a pack whose own bundle verdict is not `verified` is named
+ *   with that verdict and its reasons, so the case never reads above its
+ *   weakest pack. On-chain re-fetch and `gradePack` are a caller's to run.
+ *
+ * THE COST OF 4.1's "GRADE EVERY CANDIDATE", INHERITED HERE AND STATED RATHER
+ * THAN LEFT TO BE FOUND (proof#134, ratified by Phil 2026-09-22). A reader
+ * whose pile holds two or more records of the complementary type signed by one
+ * counterparty key cannot reach `verified`: the other exchanges' records are
+ * candidates too, they commit to other messages, and they fail. One agent
+ * sending two messages to the same counterparty inside one case lands there,
+ * and it surfaces as `COUNTERPART_AMBIGUOUS` beside the failure. An
+ * alternating exchange (A sends, B replies) does NOT, because a reply is
+ * signed by the other key and is the other type. Narrowing that here with
+ * `handoffs[]` is precisely the move that would reopen proof#137's door.
+ */
+import { checkDeclaration, declarationClaims, packRecords, } from "./declaration.js";
+import { NOT_A_HANDOFF_FINDING, normalizedSigningKey, readHandoffs, recordIsMalformed, } from "./handoff.js";
+import { verifyEvidenceBundle } from "./evidence.js";
+// ---- The vocabulary ---------------------------------------------------------
+/**
+ * The verdicts a case can reach. Every one is already in use in
+ * `evidence-bundle.md` 3 or `PACK_VERDICTS`, and anchor#198 says in terms that
+ * no new verdict word is introduced anywhere.
+ */
+export const CASE_VERDICTS = [
+    "verified",
+    "failed",
+    "partial",
+    "mixed",
+    "incomplete",
+    "malformed",
+];
+/**
+ * anchor#198 says in terms that no new verdict word is introduced anywhere, and
+ * this line is what ENFORCES it rather than asserting it in prose.
+ *
+ * `tsc` refuses to compile if any member of `CASE_VERDICTS` is not already a
+ * `PackVerdict`, so a seventh word added here fails the BUILD rather than
+ * reaching a test that might not cover it. The Python half asserts the same
+ * containment at run time against `grading.PACK_VERDICTS`, which is that
+ * language's equivalent gate.
+ */
+const _caseVerdictsAreSharedVocabulary = [...CASE_VERDICTS];
+void _caseVerdictsAreSharedVocabulary;
+/**
+ * The two pack bodies that carry `events[]` and may carry a `declaration`
+ * (`evidence-bundle.md` 5.4.1). This is an ACCEPT-SET and not a hint.
+ *
+ * `body_type` selects a code path and is written by the party assembling the
+ * pack. Without this set, a pack whose records live under a key this reader
+ * does not know yields zero records, contributes nothing, and lets the rest of
+ * the case read clean over it: the exact defect class this module is written
+ * against. An unknown value is `PACK_BODY_TYPE_UNKNOWN`.
+ *
+ * **`sanning.evidence.export/v2` is NOT in this set and is NOT unwrapped.** It
+ * verifies as a bundle and carries a whole `sanning.anchor.trace/v3` pack under
+ * `body.source_bundle`, so its records do not reach the pile and the export is
+ * named `PACK_BODY_TYPE_UNKNOWN`, `incomplete`. Reading inside it changes which
+ * packs this reader grades, so it is a decision of its own. A reader who needs
+ * the records hands in the source bundle as a pack. The export's wrapper key is
+ * still read, so wrapping a pack in one does not change which counterpart kind
+ * another record gets.
+ */
+export const CASE_BODY_TYPES = [
+    "sanning.anchor.trace/v3",
+    "sanning.stamp.evidence/v2",
+];
+/**
+ * The envelope profiles the case reader reads records under: the ratified
+ * accept-set (`envelope-spec.md` 5) minus every profile under quarantine in
+ * `cross-kernel/accept-set.json`. A test in each kernel derives both arrays
+ * from that file, and a test here pins this one equal to this kernel's own
+ * `ACCEPTED_SPEC_MAJORS`, which is what `verifyEvidenceBundle` reads under:
+ * the Python kernel narrows its verifier to this set for the case reader, and
+ * this kernel's verifier already reads exactly it. If this kernel ever admits
+ * a quarantined profile, that test fails, and the case reader has to narrow
+ * its verifier the way the Python one does before it can pass.
+ */
+export const CASE_RECORD_PROFILES = ["sanning.agent/v1", "sanning.events/v2"];
+/** The ratified profiles under quarantine, pending DL-63. */
+export const CASE_QUARANTINED_PROFILES = ["sanning.mlflow/v1"];
+// ---- The exceptions ---------------------------------------------------------
+//
+// Each of these is a NAME for something a reader would otherwise have to infer
+// from an absence. None of them is a verdict word.
+/**
+ * A conformant hand-off record with no counterpart among the records this
+ * reader read, where every pack in the case verified under a key this reader
+ * can read and NO pack in the case is signed by the key the record names.
+ * **An exception, never a failure** (anchor#198, criterion 3).
+ *
+ * That is ALL it says. It does not say the counterparty's account is absent,
+ * and it does not say nothing was tampered with: a counterparty that signs its
+ * own pack under a second key, or hands over an export an issuer signed,
+ * reaches this reading too, and nothing offline binds a pack's key to the keys
+ * of the records inside it (proof#143). The rendered text states the fact and
+ * stops.
+ *
+ * It says nothing about RECORDS signed by that key either. A party may hold records
+ * its counterparty signed, and those are still graded as candidates, but they
+ * are not the counterparty's account of itself, so they do not move this
+ * record to `COUNTERPART_ABSENT_FROM_COUNTERPARTY_RECORDS`.
+ */
+export const COUNTERPART_ABSENT = "counterpart_absent";
+/**
+ * THE CLOSURE anchor#198 exists for.
+ *
+ * A conformant hand-off record with no counterpart, where a pack that VERIFIES
+ * and is SIGNED by the key this record names is in the case, and not one
+ * record this reader could read is this record's counterpart. It states that a
+ * pack signed by the named key is present and holds no counterpart this reader
+ * could read, and nothing more. 4.1 (v1.10, A15) and 5.4.2 rule 7 (v1.10) both point here, and
+ * `declaration/declaration-unclaimed-record-01` is the pack that reaches this
+ * line.
+ *
+ * **"Its own account" is read from the key that signed the PACK, and never
+ * from the keys that signed records.** A pack's wrapper key signs `body_hash`
+ * and `body` carries the declaration (`evidence-bundle.md` 5.4, "Who signs
+ * it"), so a wrapper signed by B is provenance the accusing party cannot forge
+ * without B's private key. Records signed by B that A merely HOLDS are not B's
+ * account of itself: keyed on record keys, one pack from A plus one unrelated
+ * record B signed at some other time reached this line when B had handed over
+ * nothing at all.
+ *
+ * What it does NOT prove, stated so no surface claims it: that B handed the
+ * pack over for THIS case. A pack B signed for some other purpose and a third
+ * party replayed reads the same, because the only values that could say
+ * otherwise (the declaration's `case_id` and `period`) are written by B and
+ * would let B leave this line by writing them differently. The cost the other
+ * way: a pack B assembles under any key other than the one its records name, a
+ * per-organization hand-over key (anchor#196) included, reads
+ * `COUNTERPART_ABSENT`, because nothing in the case binds that key to B. That
+ * reading is still true: no pack signed by the named key is here. So a
+ * counterparty can AVOID this line by choosing the key it signs under; what it
+ * cannot do is make the missing counterpart read clean.
+ *
+ * It is deliberately NOT also conditioned on a record signed by B being in the
+ * pile. B's pack can hold none this reader reads (a body it does not unwrap,
+ * bytes B withheld, an empty `events[]`), and each of those is a choice B makes
+ * and is named on its own. A second conjunct on them hands B the innocent line
+ * for making one.
+ *
+ * It is a DISTINCT kind from `COUNTERPART_ABSENT` and not a louder spelling of
+ * it. Collapsing the two would be the defect class again: "the counterparty
+ * never joined" and "the counterparty joined and its own account does not
+ * contain this hand-off" are the honest reading and the damning one, and one
+ * name for both lets the second read as the first.
+ *
+ * It is still an EXCEPTION and not a failure, which criterion 3 requires and
+ * which is also the honest call: the counterparty's pack is a selection over
+ * its own interval, and a hand-off outside that interval is legitimately not
+ * in it. What this names is that the question can now be ASKED of the other
+ * party's own evidence, which is what no single pack could ever support.
+ */
+export const COUNTERPART_ABSENT_FROM_COUNTERPARTY_RECORDS = "counterpart_absent_from_counterparty_records";
+/**
+ * A conformant hand-off record with no counterpart, no VERIFIED pack in the
+ * case signed by the key it names, and at least one pack in the case that this
+ * reader could not tie to a key: its wrapper key is unreadable
+ * (`PACK_KEY_UNREADABLE`) or it does not verify (`PACK_DOES_NOT_VERIFY`).
+ * Whether a pack signed by the named key is in the case is UNKNOWN, so neither
+ * of the other two kinds is true.
+ *
+ * The gate on the previous version of this reader showed why it exists. A
+ * counterparty that signed its own pack under `" " + key` got
+ * `PACK_KEY_UNREADABLE` for the pack and the innocent `COUNTERPART_ABSENT` for
+ * the record, and the output contradicted itself: whose pack it was is
+ * UNKNOWN, and then no pack is signed by the named key. The second sentence
+ * was not established.
+ *
+ * `incomplete`, like the other two one-sided kinds: "I could not tell".
+ */
+export const COUNTERPART_ABSENT_SIGNER_UNKNOWN = "counterpart_absent_signer_unknown";
+/**
+ * More than one candidate counterpart (4.1, and proof#134's stated cost). The
+ * reading is the worst of them and the ambiguity is named: a reader permitted
+ * to take one match can be handed an honest decoy beside a tampered record.
+ */
+export const COUNTERPART_AMBIGUOUS = "counterpart_ambiguous";
+/**
+ * A formed pair that failed a check. Carries which checks, from 4.1's own
+ * fixed order, so a reader is told the record AND the check.
+ */
+export const PAIR_FAILED = "pair_failed";
+/**
+ * THIS record is wrong: 4.1 governs it and `recordIsMalformed` says so of the
+ * record itself. A statement about the record this exception names, and about
+ * no other.
+ */
+export const RECORD_MALFORMED = "record_malformed";
+/**
+ * A CANDIDATE counterpart of this record is malformed, and this record is not.
+ *
+ * 4.1 grades every candidate and reports the worst of them, and `malformed`
+ * outranks `failed`, so one junk record signed by the counterparty's key makes
+ * the reading of a perfectly well formed record `malformed` too. Filed under
+ * `RECORD_MALFORMED`, that read as "this record is not a well formed hand-off
+ * record" about the HONEST record, and the branch it took skipped the
+ * counterpart, ambiguity and `failedChecks` reporting entirely: one junk record
+ * both blamed the wrong party and stripped a named `message_hash` failure out
+ * of the case. That is proof#133 ruling 6, which 4.1 closed by keeping the
+ * UNION of `failedChecks`, reappearing one layer out because this layer
+ * discarded that union.
+ *
+ * A record's own conformance and its candidate's are different facts and do
+ * not share a kind. This one is `incomplete` and not `malformed`: the proven
+ * defect belongs to the candidate, which carries its own `RECORD_MALFORMED`
+ * line, and what is true of THIS record is that its pairing could not be
+ * determined. Contributing `malformed` here would attribute the candidate's
+ * defect to the record a party being accused did not write.
+ */
+export const COUNTERPART_MALFORMED = "counterpart_malformed";
+/**
+ * A record that its own pack DECLARES and its own pack's READABLE declaration
+ * claims in no `handoffs[]` entry. This is proof#137's door, named at the layer
+ * that can see it: the holder declared the record and claimed it nowhere, so
+ * neither 5.4.2 rule 2 nor rule 7 reaches it and the pack reads `verified`.
+ *
+ * **It turns on what the PACK said about the record, and never on whether 4.1
+ * governs it.** Gating it on "is this a conformant hand-off record" put it
+ * behind a value the audited party writes: the same second receipt, respelled
+ * with an `ff` ligature in `event_type` and a Cyrillic `е` in
+ * `counterparty_public_key`, left 4.1's scope, took the `not_a_handoff_record`
+ * branch, and bought a case reading of `verified` with zero exceptions where
+ * the conformant spelling read `mixed` with four. proof#136 ratified that a
+ * respelling buys a DIFFERENT LINE rather than no line; at this layer it
+ * bought no line at all, and a strictly better outcome than honesty.
+ *
+ * It is not an accusation. `handoffs[]` MAY be empty and an unclaimed record
+ * may be entirely innocent. What it is, is the end of the silence: the reader
+ * cannot tell whether an unclaimed record is part of the hand-over the holder
+ * meant to give or one it is keeping out of its own account, and that is "I
+ * could not tell", which is why it carries `incomplete` and not `verified`.
+ *
+ * THE COST, stated rather than left to be found: a pack that declares records
+ * which are not hand-off sides at all, an ordinary log line among them, is
+ * named once per such record, so a case holding one cannot read `verified`.
+ * That is the price of a rule with no branch the holder selects, and the only
+ * narrower rule available keys on a value the holder writes. A surface that
+ * wants the two apart reads `CaseRecordReading.findings`, where
+ * `not_a_handoff_record` still says which is which.
+ */
+export const RECORD_UNCLAIMED = "record_unclaimed_by_its_pack";
+/**
+ * The pack supplied no `event_bytes` for a record, so this reader cannot see
+ * what the record IS in either direction.
+ *
+ * `event_bytes` is OPTIONAL (5.1, 5.3) and withholding it is minimum
+ * disclosure, which the corpus calls a customer's right and not a defect
+ * (proof#137, defect 3), so this is not a deviation and does not fail. It is
+ * still SAID, because a withheld record is exactly where a missing counterpart
+ * would hide, and a reader that dropped it silently would read a trimmed pack
+ * as an honest one.
+ */
+export const RECORD_BYTES_WITHHELD = "record_bytes_withheld";
+/**
+ * The pack SUPPLIED `event_bytes` this reader cannot read as
+ * `JCS(event record)` (5.4.2 rule 7's parser rule, one implementation in
+ * `packRecords`). Bytes the holder handed over that do not decode are a defect
+ * in what was handed over, not an absence, so this one is `malformed`.
+ */
+export const RECORD_BYTES_UNREADABLE = "record_bytes_unreadable";
+/**
+ * The pack deviates from its own declaration (5.4.2). A proven mismatch, so it
+ * fails: a case cannot be clean over a pack that is proven to be trimmed.
+ */
+export const PACK_DECLARATION_DEVIATES = "pack_declaration_deviates";
+/**
+ * The pack and the UNSIGNED content handed in beside it do not line up (5.4.2
+ * rules 3 and 4, proof#147, ratified by Phil 2026-09-22). A record the pack
+ * declares `disclosed` for which no bytes reached this reader, or one it
+ * declares `content_withheld` for which bytes reached this reader from the
+ * side-content map alone.
+ *
+ * `incomplete` and never `failed`, which is the whole point of the kind. 5.4
+ * grades a pack's declaration partly against content the READER was handed,
+ * and whoever assembles a case fills that map in. Under
+ * `PACK_DECLARATION_DEVIATES` an accuser could put an intact pack into a
+ * `failed` case WITH NO KEY AT ALL: supply bytes for a record its holder
+ * declared withheld, or drop the bytes of one it declared disclosed. The pack
+ * was intact, its wrapper verified, and its holder had done nothing. This is
+ * the mirror of proof#143, where a counterparty makes ITSELF look better by
+ * choosing what it hands over.
+ *
+ * It is emitted BESIDE `PACK_DECLARATION_DEVIATES` where a pack does both,
+ * because the two say different things about different records.
+ */
+export const PACK_DECLARATION_CONTENT_DEPENDENT = "pack_declaration_content_dependent";
+/**
+ * The pack carries a `declaration` this reader cannot read (5.4.3): an unknown
+ * `declaration_version`, an absent or `null` one, a non-object, or one that
+ * does not satisfy 5.4.1. `declaration_version` is chosen by the same party
+ * that assembles the pack and has no accept-set of its own, so this is UNKNOWN
+ * and never clean.
+ */
+export const PACK_DECLARATION_UNREADABLE = "pack_declaration_unreadable";
+/**
+ * The pack carries no `declaration` member at all, so it never said what it
+ * holds. `partial` is 5.4.3's own word for a claim nobody made: never
+ * `verified`, because there is nothing to check the pack against, and never
+ * `failed`, because nothing is wrong.
+ */
+export const PACK_UNDECLARED = "pack_undeclared";
+/**
+ * The pack's `body_type` is not one this reader knows to carry `events[]`
+ * (`CASE_BODY_TYPES`).
+ */
+export const PACK_BODY_TYPE_UNKNOWN = "pack_body_type_unknown";
+/**
+ * The pack carries a body this reader knows and no records in it. A pack that
+ * contributes nothing is named rather than passed over.
+ */
+export const PACK_HOLDS_NO_RECORDS = "pack_holds_no_records";
+/**
+ * The key the pack's wrapper names is not one this reader can read as a key
+ * (`normalizedSigningKey` returns nothing for it), so who signed the pack is
+ * UNKNOWN. The pack is not verified and none of its records are read, and
+ * every one-sided record whose named key signed no verified pack reads
+ * `COUNTERPART_ABSENT_SIGNER_UNKNOWN`.
+ *
+ * Found by constructing it, while enumerating this module's exits: the wrapper
+ * key is the ONE input that separates the two counterpart kinds, and a key this
+ * reader could not read used to drop out of that set in silence. The Python
+ * `verify_evidence_bundle` accepts a wrapper `public_key` with ASCII
+ * whitespace inside it or around it (`bytes.fromhex` skips it; this kernel's
+ * verifier rejects it), so a counterparty that signed its own pack under
+ * `" " + key` handed a Python reader a pack that verified, contributed no key,
+ * and moved the subject from `COUNTERPART_ABSENT_FROM_COUNTERPARTY_RECORDS` to
+ * the innocent `COUNTERPART_ABSENT`. The same repair 4.1 made for a RECORD
+ * whose envelope key it cannot read (proof#133, fourth hunt): a key a reader
+ * holds and cannot read is named, never treated as absent. It is `incomplete`
+ * rather than `malformed` because whether the spelling verifies is the envelope
+ * layer's call (proof#135), and this reader only knows it cannot read it.
+ */
+export const PACK_KEY_UNREADABLE = "pack_key_unreadable";
+/**
+ * The pack does not verify as a bundle: `verifyEvidenceBundle`, run here
+ * offline over the pack and its side content, returned `failed` or
+ * `malformed`. None of its records are read, because a record from it would
+ * reach 4.1 without the verified envelope `HeldRecord` requires, and the key
+ * its wrapper claims is never counted as a pack signer: an unverified wrapper
+ * claiming the counterparty's key is exactly what an accusing party would
+ * forge.
+ *
+ * `partial` is not this exception. `partial` means the wrapper signature and
+ * `body_hash` held and part of the body could not be determined, which is what
+ * an unknown body or withheld bytes produce, and those are named on their own.
+ *
+ * `failed`: a pack in the case is proven broken.
+ */
+export const PACK_DOES_NOT_VERIFY = "pack_does_not_verify";
+/**
+ * The pack's wrapper HOLDS and its own bundle verdict, from
+ * `verifyEvidenceBundle` run here offline over the pack and the content handed
+ * in beside it, is not `verified`. The exception carries that verdict
+ * (`status`) and the verifier's reasons (`reasons`: its bundle errors, then its
+ * stamp errors, then its checkpoint errors, each as the verifier wrote it), and
+ * it CONTRIBUTES that verdict, so the case verdict never reads above its
+ * weakest pack. Gate 3 on proof#140: two unwitnessed (`partial`) packs read as
+ * a `verified` case with no exception. It does not say who is at fault:
+ * content handed in beside a pack is not signed by its holder.
+ */
+export const PACK_BUNDLE_NOT_VERIFIED = "pack_bundle_not_verified";
+/**
+ * A record in a pack whose wrapper holds, whose OWN envelope does not verify
+ * (`EventResult.envelopeOk` is false). Not read by 4.1, and NAMED with the
+ * verifier's reasons. `failed`: a pack its holder signed carries a record that
+ * is proven not to verify. As a reason to drop the whole pack it let the
+ * counterparty add one junk event to its own pack, re-seal it, and strip a
+ * proven `message_hash` failure out of the case (gate 3 on proof#140).
+ */
+export const RECORD_ENVELOPE_DOES_NOT_VERIFY = "record_envelope_does_not_verify";
+/**
+ * A record whose envelope verifies and which fails another check the bundle
+ * verifier grades it on inside its pack (its inclusion proof, its join to a
+ * checkpoint or stamp, a retired field name). NAMED with the verifier's
+ * reasons, `failed`, and the record STAYS in the pile: a holder that could
+ * remove its own tampered receipt from pairing by breaking that receipt's
+ * inclusion proof would be choosing its own reading.
+ */
+export const RECORD_DOES_NOT_VERIFY_IN_ITS_PACK = "record_does_not_verify_in_its_pack";
+/**
+ * A record whose envelope verifies and whose disclosed content does not hash to
+ * the `content_hash` it commits to (`EventResult.contentOk` is false). `failed`,
+ * and the record STAYS in the pile: content beside a pack is unsigned and often
+ * supplied by whoever assembled the case, and gate 3 on proof#140 showed that
+ * party erasing an honest verified pair by swapping it.
+ */
+export const RECORD_CONTENT_MISMATCH = "record_content_mismatch";
+/**
+ * A record signed under a ratified profile that is under quarantine
+ * (`CASE_QUARANTINED_PROFILES`, pending DL-63). Not read, in any kernel.
+ * `incomplete`: whether it verifies is what the kernels disagree about.
+ */
+export const RECORD_PROFILE_QUARANTINED = "record_profile_quarantined";
+/** The reader was handed no packs at all. */
+export const CASE_HOLDS_NO_PACKS = "case_holds_no_packs";
+/**
+ * Every pack was read and not one hand-off record came out of any of them.
+ * There is no hand-off to have a verdict about, and saying `verified` over that
+ * would be the defect class in its purest form.
+ */
+export const CASE_HOLDS_NO_HANDOFF_RECORDS = "case_holds_no_handoff_records";
+/**
+ * Every exception this reader can report, as a closed set. A surface may render
+ * them and a test may assert over them; nothing outside this array is emitted.
+ */
+export const CASE_EXCEPTION_KINDS = [
+    COUNTERPART_ABSENT,
+    COUNTERPART_ABSENT_FROM_COUNTERPARTY_RECORDS,
+    COUNTERPART_ABSENT_SIGNER_UNKNOWN,
+    COUNTERPART_AMBIGUOUS,
+    COUNTERPART_MALFORMED,
+    PAIR_FAILED,
+    RECORD_MALFORMED,
+    RECORD_UNCLAIMED,
+    RECORD_BYTES_WITHHELD,
+    RECORD_BYTES_UNREADABLE,
+    PACK_DECLARATION_DEVIATES,
+    PACK_DECLARATION_CONTENT_DEPENDENT,
+    PACK_DECLARATION_UNREADABLE,
+    PACK_UNDECLARED,
+    PACK_BODY_TYPE_UNKNOWN,
+    PACK_HOLDS_NO_RECORDS,
+    PACK_KEY_UNREADABLE,
+    PACK_DOES_NOT_VERIFY,
+    PACK_BUNDLE_NOT_VERIFIED,
+    RECORD_ENVELOPE_DOES_NOT_VERIFY,
+    RECORD_DOES_NOT_VERIFY_IN_ITS_PACK,
+    RECORD_CONTENT_MISMATCH,
+    RECORD_PROFILE_QUARANTINED,
+    CASE_HOLDS_NO_PACKS,
+    CASE_HOLDS_NO_HANDOFF_RECORDS,
+];
+/**
+ * What each exception kind contributes to the case verdict. It is a TABLE and
+ * not a chain of branches, so "which exceptions move the verdict" is one thing
+ * a reader can read, and so that adding a kind without deciding what it means
+ * is a missing entry rather than a quiet `verified`.
+ *
+ * Read the `incomplete` rows as "I could not tell", which is the distinction
+ * this whole module turns on. None of them is `verified`: an exception never
+ * contributes a clean verdict, which is what makes the invariant in `verdictOf`
+ * hold.
+ *
+ * `PACK_BUNDLE_NOT_VERIFIED` is the one row that is not a constant: it
+ * contributes the pack's own bundle verdict, which is `partial`, `failed` or
+ * `malformed` and never `verified` (the exception is emitted only when it is
+ * not). `null` marks that row, and `readCase` fills it from `status`.
+ */
+const EXCEPTION_VERDICT = {
+    [COUNTERPART_ABSENT]: "incomplete",
+    [COUNTERPART_ABSENT_FROM_COUNTERPARTY_RECORDS]: "incomplete",
+    [COUNTERPART_ABSENT_SIGNER_UNKNOWN]: "incomplete",
+    [COUNTERPART_AMBIGUOUS]: "incomplete",
+    [COUNTERPART_MALFORMED]: "incomplete",
+    [PAIR_FAILED]: "failed",
+    [RECORD_MALFORMED]: "malformed",
+    [RECORD_UNCLAIMED]: "incomplete",
+    [RECORD_BYTES_WITHHELD]: "incomplete",
+    [RECORD_BYTES_UNREADABLE]: "malformed",
+    [PACK_DECLARATION_DEVIATES]: "failed",
+    [PACK_DECLARATION_CONTENT_DEPENDENT]: "incomplete",
+    [PACK_DECLARATION_UNREADABLE]: "incomplete",
+    [PACK_UNDECLARED]: "partial",
+    [PACK_BODY_TYPE_UNKNOWN]: "incomplete",
+    [PACK_HOLDS_NO_RECORDS]: "incomplete",
+    [PACK_KEY_UNREADABLE]: "incomplete",
+    [PACK_DOES_NOT_VERIFY]: "failed",
+    [PACK_BUNDLE_NOT_VERIFIED]: null,
+    [RECORD_ENVELOPE_DOES_NOT_VERIFY]: "failed",
+    [RECORD_DOES_NOT_VERIFY_IN_ITS_PACK]: "failed",
+    [RECORD_CONTENT_MISMATCH]: "failed",
+    [RECORD_PROFILE_QUARANTINED]: "incomplete",
+    [CASE_HOLDS_NO_PACKS]: "partial",
+    [CASE_HOLDS_NO_HANDOFF_RECORDS]: "partial",
+};
+// ---- The reading ------------------------------------------------------------
+const bodyTypeOf = (bundle) => typeof bundle === "object" && bundle !== null
+    ? bundle["body_type"]
+    : undefined;
+/**
+ * The key that SIGNED the pack wrapper, which is the key that signed the pack's
+ * declaration.
+ *
+ * The wrapper signature covers `body_hash` and `body` carries the
+ * `declaration` (`evidence-bundle.md` 5.1, 5.4.1), so this key is the party
+ * whose signed account of itself this pack is. Read from the ENVELOPE of the
+ * pack and never from `issuer`: `issuer` is a label and DL-60 keeps it out of
+ * every reading, while `public_key` is the value the signature binds.
+ *
+ * It means something only for a pack whose wrapper HOLDS, which is why
+ * `readCase` counts it only after its own `verifyEvidenceBundle` call over the
+ * pack returned `signatureOk` and `bodyHashOk`.
+ */
+const holderKeyOf = (bundle) => typeof bundle === "object" && bundle !== null
+    ? bundle["public_key"]
+    : undefined;
+/**
+ * Provenance, and nothing else: the wrapper signature over `body_hash` verified
+ * and `body_hash` is the hash of the body (evidence-bundle.md 5.5.1 step 1).
+ * Nothing inside the body is part of this answer.
+ */
+const wrapperHolds = (result) => result.signatureOk && result.bodyHashOk;
+/**
+ * Why the pack reads what it reads, as the verifier said it: its bundle errors,
+ * then each stamp's, then each checkpoint's, then each event's behind the
+ * event's own id.
+ *
+ * The event errors are here as well as on the records' own exceptions on
+ * purpose. A pack whose only defect is one record reads `failed` with no
+ * bundle-level error at all, and an exception that named the verdict and no
+ * reason would send a reader looking for a defect in the pack as a whole.
+ */
+const bundleReasons = (result) => [
+    ...result.errors,
+    ...(result.stamps ?? []).flatMap((stamp) => stamp.errors),
+    ...result.checkpoints.flatMap((cp) => cp.errors),
+    ...result.events.flatMap((ev) => ev.errors.map((e) => `${ev.eventId}: ${e}`)),
+];
+/**
+ * The `spec_version` of the envelope of `body.events[index]`, as written.
+ * `packRecords` and the bundle verifier both walk `body.events` in order, so
+ * `index` is the same record in both.
+ */
+function recordSpecVersion(bundle, index) {
+    const at = (v, k) => typeof v === "object" && v !== null ? v[k] : undefined;
+    const events = at(at(bundle, "body"), "events");
+    return Array.isArray(events) ? at(at(events[index], "envelope"), "spec_version") : undefined;
+}
+/**
+ * `specVersion` is a quarantined profile, on the same token boundary the
+ * envelope layer's own accept-check uses (`specVersionSupported`).
+ */
+function underQuarantine(specVersion) {
+    if (typeof specVersion !== "string")
+        return false;
+    return CASE_QUARANTINED_PROFILES.some((m) => {
+        if (specVersion === m)
+            return true;
+        if (!specVersion.startsWith(`${m}.`))
+            return false;
+        const minor = specVersion.slice(m.length + 1);
+        return minor.length > 0 && /^[0-9]+$/.test(minor);
+    });
+}
+/**
+ * The case verdict, from the contributions alone.
+ *
+ * One outcome is that outcome; more than one is `mixed` (anchor#198,
+ * criterion 4). `mixed` is in the 3 vocabulary and coins no word.
+ *
+ * THE INVARIANT, stated so a mutation test has something to kill: `verified` is
+ * reachable ONLY when `exceptions` is empty. Every exception kind carries a
+ * non-`verified` contribution (`EXCEPTION_VERDICT`), so this falls out of the
+ * table rather than being enforced by a second rule that could drift from it.
+ * The assertion is here anyway, because that is the property every one of the
+ * seventeen findings on this program violated.
+ */
+function verdictOf(exceptions, contributions) {
+    // Unreachable through `readCase`, which names a case with no contributions
+    // rather than returning one. Defended anyway: an empty aggregate reading as
+    // `verified` is the defect class itself.
+    if (contributions.length === 0)
+        return "partial";
+    const outcomes = new Set(contributions.map(([, v]) => v));
+    const verdict = outcomes.size === 1 ? [...outcomes][0] : "mixed";
+    if (verdict === "verified" && exceptions.length > 0) {
+        throw new Error(`verified over a non-empty exception list: ${exceptions.map((e) => e.kind).join(", ")}`);
+    }
+    return verdict;
+}
+/**
+ * Read a whole case: several packs in, one verdict and its exceptions out.
+ *
+ * The order of the work, and why it is this order:
+ *
+ * 1. **Each pack is read into records**, through `packRecords`, which is the
+ *    one implementation of "what does this pack hold". A pack whose `body_type`
+ *    this reader does not know, or which holds no records, is NAMED here and
+ *    its records are not silently zero.
+ * 2. **Each pack is graded against its own declaration**, through
+ *    `checkDeclaration`, which is the one implementation of 5.4. A pack proven
+ *    to deviate from its own claim fails the case.
+ * 3. **Every record every pack supplied goes into ONE pile**, with no partition
+ *    by pack, by issuer or by organization, and the pile is read by
+ *    `readHandoffs`, which is the one implementation of 4.1. This is where
+ *    matching happens, and it is on keys and hashes alone.
+ * 4. **Each reading becomes an exception or a clean contribution**, and the two
+ *    counterpart kinds are separated by asking whether a pack SIGNED by the
+ *    counterparty's key is in the case, a key read from every pack's wrapper
+ *    before any exit can skip it.
+ *
+ * A record whose bytes the pack did not supply never reaches the pile, because
+ * there is nothing to put in it. That is exactly the shape this module has to
+ * refuse to pass over in silence, so it is named at step 1 and carries
+ * `incomplete`: the reader genuinely cannot tell whether the record it cannot
+ * see is the counterpart that is missing.
+ */
+export async function readCase(packs) {
+    const exceptions = [];
+    const contributions = [];
+    const note = (kind, fields = {}) => {
+        exceptions.push({ kind, ...fields });
+        // `null` is PACK_BUNDLE_NOT_VERIFIED: the pack's own verdict, never verified.
+        const contribution = EXCEPTION_VERDICT[kind] ?? fields.status;
+        contributions.push([fields.eventId ?? fields.packRef ?? "case", contribution]);
+    };
+    if (packs.length === 0) {
+        note(CASE_HOLDS_NO_PACKS);
+        return {
+            verdict: verdictOf(exceptions, contributions),
+            exceptions,
+            records: [],
+            contributions,
+            handoffRecords: 0,
+            onChainChecked: false,
+        };
+    }
+    // Step 1 and 2, pack by pack, in the order the reader was given them.
+    // Whether every pack's witness was re-fetched on chain, ALL over the packs
+    // this reader verified. It passes no gateways, so this stays false and the
+    // reading says so (see `CaseReading.onChainChecked`).
+    const witnessChecked = [];
+    const held = [];
+    // The pack and the `event_id` behind each pile member, kept beside the pile
+    // rather than parsed back out of a reference string. A reference is for a
+    // human to read; a join rebuilt by splitting one is a join on a value a
+    // holder can put a separator in.
+    const provenance = [];
+    // Keyed by the pack's POSITION and never by its `ref`. `ref` is the reader's
+    // own name for a pack, and nothing stops two packs in one archive carrying
+    // the same one: keyed by ref, the second pack's claims silently replaced the
+    // first's and records from one pack were graded against another pack's
+    // declaration. Found by a constructed archive rather than by reading, which
+    // is the only way this class of defect is ever found.
+    const claimsByPack = new Map();
+    // Every key that SIGNED A PACK in this case: the wrapper key, which is the
+    // key that signs the pack's declaration. This is the ONE input that separates
+    // the two counterpart kinds (see `COUNTERPART_ABSENT_FROM_COUNTERPARTY_RECORDS`),
+    // and it replaces a set of every key that signed a RECORD anywhere in the
+    // case.
+    //
+    // The record-key set was wrong twice over, and both times in the direction
+    // that matters. It let the ACCUSER manufacture the damning line: one pack,
+    // plus one unrelated record the counterparty signed at some other time, read
+    // "the counterparty's OWN records ARE here" when the counterparty had handed
+    // over nothing (F4). And it let the COUNTERPARTY choose the innocent line: it
+    // was filled inside the record loop, which the `body_type` and no-records
+    // exits `continue` past, so a counterparty that wrapped its own pack in a body
+    // this reader does not read took its keys out of the set (F3), the third
+    // instance of a route already closed once for withheld `event_bytes`.
+    //
+    // A wrapper key closes both. The accuser cannot forge one without the
+    // counterparty's private key, and it is read HERE, first, before any exit
+    // below, from the pack envelope and never from the body, so no body type, no
+    // disclosure choice and no record content decides whether it is read.
+    const holderKeys = new Set();
+    // How many packs this reader could not tie to a key: an unreadable wrapper
+    // key, or a wrapper that does not hold. While it is not zero, "no pack in this
+    // case is signed by the named key" is not established, so the innocent
+    // one-sided kind is not available (COUNTERPART_ABSENT_SIGNER_UNKNOWN).
+    let unattributed = 0;
+    for (let position = 0; position < packs.length; position += 1) {
+        const pack = packs[position];
+        const holder = normalizedSigningKey(holderKeyOf(pack.bundle));
+        if (holder === null) {
+            // Named, never skipped: a pack whose key this reader cannot read is a
+            // pack whose signer is UNKNOWN, and not a pack nobody signed. Checked
+            // BEFORE verification, because the two bundle verifiers disagree on some
+            // of these spellings (proof#135) and the reading must not.
+            note(PACK_KEY_UNREADABLE, { packRef: pack.ref });
+            unattributed += 1;
+            continue;
+        }
+        // The precondition `HeldRecord` states, met HERE rather than trusted to a
+        // caller: every key this module compares is an envelope `public_key`, and
+        // "unforgeable" is a property of a VERIFIED envelope. Offline, no
+        // gateways: this reader makes no network call. This kernel's verifier
+        // reads envelopes under exactly CASE_RECORD_PROFILES (pinned by a test).
+        const verified = await verifyEvidenceBundle(pack.bundle, {
+            content: (pack.content ?? undefined),
+        });
+        witnessChecked.push(verified.onChainChecked);
+        // WHOSE PACK IS IT. The wrapper, and only the wrapper.
+        if (!wrapperHolds(verified)) {
+            note(PACK_DOES_NOT_VERIFY, { packRef: pack.ref });
+            unattributed += 1;
+            continue;
+        }
+        holderKeys.add(holder);
+        // WHAT IS WRONG INSIDE IT, from here on. First the pack's own assurance,
+        // which propagates: the case never reads above its weakest pack.
+        if (verified.status !== "verified") {
+            note(PACK_BUNDLE_NOT_VERIFIED, {
+                packRef: pack.ref,
+                status: verified.status,
+                reasons: bundleReasons(verified),
+            });
+        }
+        // The body is one the verifier could not read, so it graded no record, and
+        // nothing below has a grading to read. Named above.
+        if (verified.status === "malformed")
+            continue;
+        const bodyType = bodyTypeOf(pack.bundle);
+        if (!CASE_BODY_TYPES.includes(bodyType)) {
+            // `sanning.evidence.export/v2` lands here, and it is NOT unwrapped: its
+            // records sit under `body.source_bundle`, and reading them is a change to
+            // which packs this reader grades, so it is a decision of its own and not
+            // a repair (evidence-bundle.md 5.5.1 step 1 says so too). What this exit
+            // costs is that pack's RECORDS, and it is named every time. It no longer
+            // costs the pack's KEY: that was read above.
+            note(PACK_BODY_TYPE_UNKNOWN, { packRef: pack.ref });
+            continue;
+        }
+        const records = packRecords(pack.bundle, pack.content);
+        // The per-record gradings below are joined to `records` BY INDEX, so a
+        // verifier that graded a different number of records than the pack holds
+        // leaves this loop with no grading to read. That is not hypothetical: a
+        // pack whose `body_hash` does not cover its body reads `failed` with
+        // `events` EMPTY while `packRecords` reads every record in it, and only
+        // `wrapperHolds` above stands between that pack and this loop. A reader
+        // must never crash on a pack a party can build, so the gap is NAMED rather
+        // than indexed into, and the pack's records are dropped exactly as a
+        // `malformed` pack's are (gate 4 on proof#140, finding 3: under the
+        // mutation that dropped `bodyHashOk` from the wrapper test, this kernel
+        // threw `Cannot read properties of undefined (reading 'envelopeOk')` here
+        // and nothing in the ladder said so).
+        if (verified.events.length !== records.length) {
+            note(PACK_BUNDLE_NOT_VERIFIED, {
+                packRef: pack.ref,
+                status: verified.status,
+                reasons: [
+                    `this verifier graded ${verified.events.length} of the ` +
+                        `${records.length} record(s) the pack holds, so none of them is read`,
+                ],
+            });
+            continue;
+        }
+        if (records.length === 0) {
+            note(PACK_HOLDS_NO_RECORDS, { packRef: pack.ref });
+            continue;
+        }
+        const check = checkDeclaration(pack.bundle, pack.content);
+        claimsByPack.set(position, declarationClaims(pack.bundle));
+        if (check.contentFindings.length > 0) {
+            // BESIDE the deviation exception and never instead of it: a pack can do
+            // both, over different records, and the two say different things. This
+            // one is `incomplete` because whoever assembled the case chose the bytes
+            // it turns on (proof#147).
+            note(PACK_DECLARATION_CONTENT_DEPENDENT, {
+                packRef: pack.ref,
+                count: check.contentFindings.length,
+            });
+        }
+        if (check.verdict === "failed") {
+            note(PACK_DECLARATION_DEVIATES, {
+                packRef: pack.ref,
+                count: check.deviations.length,
+            });
+        }
+        else if (check.contentFindings.length > 0) {
+            // Already named above. `partial` here is not "the reader cannot read the
+            // claim": the claim was read, and part of it rests on bytes nobody
+            // signed.
+        }
+        else if (check.verdict === "verified") {
+            // A pack that agrees with its own claim contributes NOTHING, rather than
+            // a `verified` of its own. The case verdict is over the hand-off
+            // readings, and criterion 4's "mixed" is about mixed HAND-OFF outcomes: a
+            // pack-level clean contribution would put `verified` into the set on
+            // every case, so one broken pair beside two honest declarations would
+            // read `mixed` and the failure would be the quieter half of a two-word
+            // answer. A pack-level PROBLEM still contributes, through its exception.
+        }
+        else if (check.present) {
+            // `partial` with a declaration present is 5.4.3's "a claim this reader
+            // cannot read", which `gradePack` already carries to `incomplete`. The
+            // same posture here, for the same reason: the field has no accept-set and
+            // the holder writes it.
+            note(PACK_DECLARATION_UNREADABLE, { packRef: pack.ref });
+        }
+        else {
+            note(PACK_UNDECLARED, { packRef: pack.ref });
+        }
+        // Each record on its OWN envelope. `packRecords` and the verifier both walk
+        // `body.events` in order and emit one entry per element, so the index is
+        // the join, exactly as `held`, `provenance` and `readings` below.
+        for (let index = 0; index < records.length; index += 1) {
+            const record = records[index];
+            const graded = verified.events[index];
+            if (underQuarantine(recordSpecVersion(pack.bundle, index))) {
+                note(RECORD_PROFILE_QUARANTINED, { packRef: pack.ref, eventId: record.eventId });
+                continue;
+            }
+            if (!graded.envelopeOk) {
+                note(RECORD_ENVELOPE_DOES_NOT_VERIFY, {
+                    packRef: pack.ref,
+                    eventId: record.eventId,
+                    reasons: [...graded.errors],
+                });
+                continue;
+            }
+            if (!record.bytesSupplied) {
+                note(RECORD_BYTES_WITHHELD, {
+                    packRef: pack.ref,
+                    eventId: record.eventId,
+                });
+                continue;
+            }
+            if (record.record === null) {
+                note(RECORD_BYTES_UNREADABLE, {
+                    packRef: pack.ref,
+                    eventId: record.eventId,
+                });
+                continue;
+            }
+            // Named, and the record stays in the pile (see the kinds).
+            if (graded.contentOk === false) {
+                note(RECORD_CONTENT_MISMATCH, {
+                    packRef: pack.ref,
+                    eventId: record.eventId,
+                    reasons: [...graded.errors],
+                });
+            }
+            if (!(graded.inclusionOk && graded.checkpointBound) ||
+                (!graded.ok && graded.contentOk !== false)) {
+                note(RECORD_DOES_NOT_VERIFY_IN_ITS_PACK, {
+                    packRef: pack.ref,
+                    eventId: record.eventId,
+                    reasons: [...graded.errors],
+                });
+            }
+            held.push({
+                publicKey: record.publicKey,
+                record: record.record,
+                ref: `${pack.ref}/${record.eventId}`,
+            });
+            provenance.push({ position, packRef: pack.ref, eventId: record.eventId });
+        }
+    }
+    // Step 3. ONE pile, no partition. This is the line anchor#198 turns on and
+    // the line DL-60 constrains: there is nothing here that reads a tenant, an
+    // issuer or an organization, so a pair across two organizations' packs is
+    // read exactly as a pair inside one.
+    const readings = readHandoffs(held);
+    // Step 4.
+    const records = [];
+    let handoffRecords = 0;
+    for (let index = 0; index < readings.length; index += 1) {
+        const reading = readings[index];
+        const { position, packRef, eventId } = provenance[index];
+        records.push({
+            packRef,
+            eventId,
+            verdict: reading.verdict,
+            findings: [...reading.findings],
+            failedChecks: [...reading.failedChecks],
+            counterparts: [...reading.candidates],
+        });
+        // proof#137's door, named. Read from the ONE reader of the declaration
+        // (`declarationClaims`), never from a second parse here. Only a READABLE
+        // declaration can make a record unclaimed: where the claim itself is absent
+        // or unreadable, that pack already carries its own exception and naming
+        // every record in it again would report one defect many times.
+        //
+        // ABOVE the two `continue`s below, deliberately. This check asks what the
+        // PACK said about the record, which is independent of whether 4.1 governs
+        // the record and of whether the record is well formed. Behind the
+        // `not_a_handoff_record` exit it was a check the audited party switched off
+        // by respelling two fields, and behind the `malformed` exit it was one a
+        // party switched off by breaking its own record.
+        const claims = claimsByPack.get(position);
+        if (claims !== undefined &&
+            claims.readable &&
+            !claims.claimedSides.includes(eventId)) {
+            note(RECORD_UNCLAIMED, { packRef, eventId });
+        }
+        if (reading.findings.includes(NOT_A_HANDOFF_FINDING)) {
+            // 4.1 (v1.9, A14): information, not absence. A record 4.1 does not govern
+            // is not a hand-off exception, and it is still in `records` and still
+            // subject to the claim check above.
+            continue;
+        }
+        handoffRecords += 1;
+        if (reading.verdict === "malformed") {
+            // Whose defect is it? `recordIsMalformed` is 4.1's own predicate, CALLED
+            // and not restated, and it answers about THIS record. A `malformed`
+            // aggregate over a record that is itself well formed is a malformed
+            // CANDIDATE, so it is a different kind, it does not `continue`, and the
+            // counterpart, ambiguity and `failedChecks` reporting below all keep
+            // running over it.
+            if (recordIsMalformed(held[index])) {
+                note(RECORD_MALFORMED, { packRef, eventId });
+                continue;
+            }
+            note(COUNTERPART_MALFORMED, { packRef, eventId });
+        }
+        if (reading.findings.includes(COUNTERPART_ABSENT)) {
+            // `held`, `provenance` and `readings` are three views of one list in one
+            // order, built together and never filtered, so the index is the join.
+            // Deliberately not a lookup by reference string: a reference is for a
+            // person to read, and a join rebuilt by splitting one is a join on a
+            // value a holder can put a separator inside.
+            const subject = held[index];
+            const event = subject.record["event"];
+            const named = normalizedSigningKey(typeof event === "object" && event !== null
+                ? event["counterparty_public_key"]
+                : undefined);
+            // A VERIFIED pack SIGNED by the named key is in the case, and nothing
+            // else. Records signed by that key which some other party holds are not
+            // that party's pack. Where some pack could not be tied to a key, "no
+            // pack is signed by the named key" is not established and the reading
+            // says it could not tell.
+            const kind = named !== null && holderKeys.has(named)
+                ? COUNTERPART_ABSENT_FROM_COUNTERPARTY_RECORDS
+                : unattributed > 0
+                    ? COUNTERPART_ABSENT_SIGNER_UNKNOWN
+                    : COUNTERPART_ABSENT;
+            note(kind, { packRef, eventId, counterpartyKey: named });
+            continue;
+        }
+        if (reading.findings.includes(COUNTERPART_AMBIGUOUS)) {
+            note(COUNTERPART_AMBIGUOUS, {
+                packRef,
+                eventId,
+                count: reading.candidates.length,
+            });
+        }
+        // ON `failedChecks` AND NOT ON THE VERDICT WORD. 4.1 keeps the UNION of
+        // every candidate's failed checks precisely so a junk record cannot strip a
+        // named failure out of the report (proof#133 ruling 6), and reading the
+        // verdict instead threw that union away: `malformed` outranks `failed`, so
+        // one junk candidate took the branch below and a proven `message_hash`
+        // failure disappeared from the case. A named failed check is a named failed
+        // check whatever the aggregate word is.
+        if (reading.failedChecks.length > 0) {
+            note(PAIR_FAILED, {
+                packRef,
+                eventId,
+                failedChecks: [...reading.failedChecks],
+            });
+        }
+        else if (reading.verdict === "verified") {
+            contributions.push([`${packRef}/${eventId}`, "verified"]);
+        }
+    }
+    if (handoffRecords === 0)
+        note(CASE_HOLDS_NO_HANDOFF_RECORDS);
+    return {
+        verdict: verdictOf(exceptions, contributions),
+        exceptions,
+        records,
+        contributions,
+        handoffRecords,
+        onChainChecked: witnessChecked.length > 0 && witnessChecked.every((c) => c),
+    };
+}
+// ---- Presentation (optional) ------------------------------------------------
+/**
+ * The house wording for one exception.
+ *
+ * Offered, not imposed, exactly as `renderDeviation` is: what must not vary
+ * between surfaces is the verdict and the set of exceptions, and those come
+ * from `readCase`. Both kernels return this same text for the same exception.
+ */
+const because = (reasons) => reasons !== undefined && reasons.length > 0 ? `: ${reasons.join("; ")}` : "";
+export function renderException(exception) {
+    const where = `${exception.packRef}/${exception.eventId}`;
+    switch (exception.kind) {
+        case COUNTERPART_ABSENT:
+            return (`${where} has no counterpart among the records this verifier read, ` +
+                "and no pack in this case is signed by the key it names");
+        case COUNTERPART_ABSENT_FROM_COUNTERPARTY_RECORDS:
+            return (`${where} has no counterpart among the records this verifier read, ` +
+                "and a pack signed by the key it names IS in this case and holds " +
+                "no counterpart this verifier could read");
+        case COUNTERPART_ABSENT_SIGNER_UNKNOWN:
+            return (`${where} has no counterpart among the records this verifier read, ` +
+                "and a pack in this case could not be tied to a signing key, so " +
+                "whether a pack signed by the key it names is in this case is " +
+                "UNKNOWN");
+        case COUNTERPART_AMBIGUOUS:
+            return (`${where} has ${exception.count} candidate counterparts, so the ` +
+                "reading is the worst of them and no one match was chosen");
+        case PAIR_FAILED:
+            return `${where} FAILED on ${(exception.failedChecks ?? []).join(", ")}`;
+        case RECORD_MALFORMED:
+            return `${where} is not a well formed hand-off record`;
+        case COUNTERPART_MALFORMED:
+            return (`${where} is well formed and a candidate counterpart of it is not, ` +
+                "so what this record pairs with is UNKNOWN");
+        case RECORD_UNCLAIMED:
+            return (`${where} is a record its own pack declares and claims in no ` +
+                "hand-off pair, so whether the holder meant to hand it over is " +
+                "UNKNOWN");
+        case RECORD_BYTES_WITHHELD:
+            return `${where} travels with no record bytes, so what that record IS is UNKNOWN`;
+        case RECORD_BYTES_UNREADABLE:
+            return `${where} travels with record bytes this verifier cannot read`;
+        case PACK_DECLARATION_DEVIATES:
+            // "read together with" and not "deviates", flat: 5.4 grades the pack
+            // against the content the reader was handed, and content beside a pack is
+            // unsigned. Whoever assembles a case can swap it, so the sentence names
+            // what was compared rather than only the pack.
+            return (`${exception.packRef}, read together with any content handed in ` +
+                `beside it, DEVIATES from its own declaration, in ` +
+                `${exception.count} way(s)`);
+        case PACK_DECLARATION_CONTENT_DEPENDENT:
+            // Says what this verifier could not establish, and names the content
+            // rather than the pack's holder: the bytes are unsigned and whoever
+            // assembled the case chose them.
+            return (`${exception.packRef} agrees with its own declaration everywhere its ` +
+                `signature reaches, and in ${exception.count} way(s) it does not line ` +
+                "up with the unsigned content handed in beside it, which anyone could " +
+                "have supplied, so whether it holds what it declares is UNKNOWN");
+        case PACK_DECLARATION_UNREADABLE:
+            return (`${exception.packRef} says what it holds in a declaration this ` +
+                "verifier cannot read, so whether it is complete is UNKNOWN");
+        case PACK_UNDECLARED:
+            return (`${exception.packRef} does not say what it holds, so whether it is ` +
+                "complete is UNKNOWN");
+        case PACK_BODY_TYPE_UNKNOWN:
+            return (`${exception.packRef} is a pack body this verifier does not read, so ` +
+                "what it holds is UNKNOWN");
+        case PACK_HOLDS_NO_RECORDS:
+            return `${exception.packRef} holds no records this verifier can read`;
+        case PACK_KEY_UNREADABLE:
+            return (`${exception.packRef} names a signing key this verifier cannot ` +
+                "read, so who signed it is UNKNOWN and none of its records are read");
+        case PACK_DOES_NOT_VERIFY:
+            return (`${exception.packRef} carries a wrapper signature over its body that ` +
+                "does not verify, so none of its records are read and the key it " +
+                "names is not counted as its signer");
+        case PACK_BUNDLE_NOT_VERIFIED: {
+            let head = `${exception.packRef} reads ${(exception.status ?? "").toUpperCase()} as ` +
+                "a bundle, together with any content handed in beside it";
+            if (exception.status === "malformed")
+                head += ", so none of its records are read";
+            return head + because(exception.reasons);
+        }
+        case RECORD_ENVELOPE_DOES_NOT_VERIFY:
+            return (`${where} is in a pack whose wrapper verifies, and its own envelope ` +
+                "does not verify, so it is not read as a hand-off record" +
+                because(exception.reasons));
+        case RECORD_DOES_NOT_VERIFY_IN_ITS_PACK:
+            return (`${where} has an envelope that verifies and fails another check ` +
+                "inside its pack, and it is still read as a hand-off record" +
+                because(exception.reasons));
+        case RECORD_CONTENT_MISMATCH:
+            return (`${where} is read with content that does not match what it commits ` +
+                "to, and it is still read as a hand-off record" +
+                because(exception.reasons));
+        case RECORD_PROFILE_QUARANTINED:
+            return (`${where} is signed under a profile this case reader does not read ` +
+                "while its admission is undecided (DL-63), so what it says is UNKNOWN");
+        case CASE_HOLDS_NO_PACKS:
+            return "this case holds no packs";
+        case CASE_HOLDS_NO_HANDOFF_RECORDS:
+            return ("no record this verifier read in this case is a hand-off record, " +
+                "so no hand-off was verified");
+        default:
+            return exception.kind;
+    }
+}
+/**
+ * One line a surface can print for a whole case.
+ *
+ * Both kernels print this sentence, so a reader who runs the Python command and
+ * the TypeScript one over one case archive reads one sentence rather than two
+ * that differ by a word.
+ */
+export function renderCaseSummary(reading) {
+    const n = reading.handoffRecords;
+    // What was NOT checked, in the same sentence as what was, and in the
+    // `verified` one above all (gate 4 on proof#140, finding 3). It is a
+    // statement of SCOPE and not a doubt: every pack here was verified offline,
+    // and no `anchor_ref` any of them names was fetched from a chain, because
+    // this reader makes no network call. Left unsaid, a clean case reads as
+    // though a witness had been checked, which nobody established. It is not an
+    // exception, and it must never become one: an empty exception list is the
+    // only shape a reader may read as clean, so a standing exception here would
+    // put `verified` out of reach for good.
+    const scope = reading.onChainChecked
+        ? ""
+        : "; no anchor_ref in it was re-fetched on chain, which this reader never does";
+    if (reading.verdict === "verified") {
+        return (`this case verifies across ${reading.records.length} record(s): ` +
+            `${n} hand-off record(s), every one matched, no exceptions` +
+            scope);
+    }
+    return (`this case reads ${reading.verdict.toUpperCase()} over ${n} hand-off ` +
+        `record(s), with ${reading.exceptions.length} exception(s)` +
+        scope);
+}