@sanning/proof 0.10.0 → 0.11.1

package/dist/case.d.ts

@@ -0,0 +1,745 @@
+/**
+ * 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 type { SideContentMap } from "./side-content.js";
+/**
+ * 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 declare const CASE_VERDICTS: readonly ["verified", "failed", "partial", "mixed", "incomplete", "malformed"];
+export type CaseVerdict = (typeof CASE_VERDICTS)[number];
+/**
+ * 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 declare const CASE_BODY_TYPES: readonly ["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 declare const CASE_RECORD_PROFILES: readonly ["sanning.agent/v1", "sanning.events/v2"];
+/** The ratified profiles under quarantine, pending DL-63. */
+export declare const CASE_QUARANTINED_PROFILES: readonly ["sanning.mlflow/v1"];
+/**
+ * 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare const PACK_UNDECLARED = "pack_undeclared";
+/**
+ * The pack's `body_type` is not one this reader knows to carry `events[]`
+ * (`CASE_BODY_TYPES`).
+ */
+export declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare const RECORD_PROFILE_QUARANTINED = "record_profile_quarantined";
+/** The reader was handed no packs at all. */
+export declare 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 declare 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 declare const CASE_EXCEPTION_KINDS: readonly ["counterpart_absent", "counterpart_absent_from_counterparty_records", "counterpart_absent_signer_unknown", "counterpart_ambiguous", "counterpart_malformed", "pair_failed", "record_malformed", "record_unclaimed_by_its_pack", "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"];
+export type CaseExceptionKind = (typeof CASE_EXCEPTION_KINDS)[number];
+/**
+ * One pack in a case, as a reader was handed it.
+ *
+ * `ref` is the reader's own name for the pack (a file name, an archive member)
+ * and is never read from the pack itself: a value inside the pack is written by
+ * the party that assembled it, and two packs are free to claim one name.
+ *
+ * A caller passes packs as it received them. `readCase` runs
+ * `verifyEvidenceBundle` over each one itself, so `HeldRecord`'s precondition
+ * (every envelope it compares has verified) is met by this module and cannot
+ * be skipped by a caller. A pack that does not verify is
+ * `PACK_DOES_NOT_VERIFY`.
+ */
+export interface CasePack {
+    ref: string;
+    bundle: unknown;
+    content?: SideContentMap | null;
+}
+/** One named exception, as data. A surface renders its own prose or calls
+ * `renderException`. */
+export interface CaseException {
+    kind: CaseExceptionKind;
+    /** Which pack this is about, by the reader's own name for it. */
+    packRef?: string;
+    /** Which record, by its envelope `event_id`. */
+    eventId?: string;
+    /**
+     * The counterparty key the record named, for the two counterpart kinds.
+     * Normalized (`normalizedSigningKey`), so a reader compares what this module
+     * compared.
+     */
+    counterpartyKey?: string | null;
+    /** Which checks a formed pair failed, in 4.1's fixed order. */
+    failedChecks?: string[];
+    /** How many of a thing the exception is about, where it is about a count. */
+    count?: number;
+    /** The pack's own bundle verdict, for `PACK_BUNDLE_NOT_VERIFIED`. */
+    status?: CaseVerdict;
+    /**
+     * What the bundle verifier said, as it said it, for the kinds that carry a
+     * verifier's grading: `PACK_BUNDLE_NOT_VERIFIED` and the three record kinds
+     * graded on the record's own envelope and content.
+     */
+    reasons?: string[];
+}
+/**
+ * 4.1's reading of one record the case holds, with the pack it came from.
+ *
+ * EVERY record every pack supplied and this reader could read gets one of
+ * these, in pack order and then in bundle order, including the ones that are
+ * not hand-off records at all (`findings` carries `not_a_handoff_record`). 4.1
+ * (v1.9, A14) requires that and names the reason: the one thing an attacker
+ * wants is for a record to be absent from the output.
+ */
+export interface CaseRecordReading {
+    packRef: string;
+    eventId: string;
+    verdict: string | null;
+    findings: string[];
+    failedChecks: string[];
+    counterparts: string[];
+}
+export interface CaseReading {
+    verdict: CaseVerdict;
+    /**
+     * Every exception, in a fixed order: the pack-level ones for each pack in the
+     * order the reader was given the packs, then the record-level ones in pack
+     * order and bundle order.
+     *
+     * **An empty array is the only shape a reader may read as clean**, and it is
+     * reachable only together with `verdict === "verified"`.
+     */
+    exceptions: CaseException[];
+    /** One reading per record the case holds and this reader could read. */
+    records: CaseRecordReading[];
+    /**
+     * Every `[contributor, verdict]` the case verdict was computed from, in
+     * order. Carried so the verdict is auditable rather than asserted, and so two
+     * kernels compare the derivation and not only its answer.
+     */
+    contributions: [string, CaseVerdict][];
+    /** How many hand-off records the case held. Zero is its own exception. */
+    handoffRecords: number;
+    /**
+     * Whether any witness behind any pack in this case was re-fetched on chain.
+     * It is **false** in every reading this function produces, and it is here to
+     * be READ rather than inferred.
+     *
+     * Gate 4 on proof#140, finding 3. A pack is `partial` only when `anchor_ref`
+     * is ABSENT, so the honest omission is named and the unverifiable assertion
+     * is not: a holder that writes any `anchor_ref` at all reads `verified`,
+     * because this reader makes no network call. That is the standing lens
+     * inverted, and the answer is not to refuse the assertion, which no offline
+     * reader can grade. It is to say what was not checked, so nobody reads a
+     * clean case as "a witness held". Re-fetching on chain stays the caller's
+     * job, exactly as `evidence-bundle.md` 5.5's does-not-claim list says.
+     *
+     * Derived from each pack's own `EvidenceBundleResult.onChainChecked` rather
+     * than written as a constant, so it stays true of what was actually run:
+     * this reader passes no gateways, and it is the ALL of an empty list of
+     * checked packs, which is false.
+     */
+    onChainChecked: boolean;
+}
+/**
+ * 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 declare function readCase(packs: readonly CasePack[]): Promise<CaseReading>;
+export declare function renderException(exception: CaseException): string;
+/**
+ * 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 declare function renderCaseSummary(reading: CaseReading): string;