@sanning/proof 0.9.2 → 0.11.0

package/dist/handoff.js

@@ -0,0 +1,598 @@
+// The hand-off pairing rule of specs/envelope-spec.md §4.1 (v1.9).
+//
+// Two agents exchange a message and each side records what it held. This module
+// is the TypeScript half of the reference reading of those two records: which
+// records are candidates to be the counterpart of a given one, how a candidate
+// set of more than one is ordered, and what a formed pair grades to. The
+// Python half is src/sanning_proof/handoff.py, and the two have to answer
+// identically on identical bytes.
+//
+// WHY IT IS WRITTEN THIS WAY (proof#132, ratified by Phil 2026-09-21)
+//
+// §4.1 as ratified at v1.7 formed a pair from three conjuncts, all three chosen
+// by the party being audited and none of them graded: `context.case_id`, the
+// mutual naming of each other's key in `event.counterparty_public_key`, and the
+// two record types. A receiving side that had tampered with a message could
+// change ONE of them, form no pair at all, and have its deviation surface as
+// two absences, which §4.1 obliges a reader to treat as innocent.
+//
+// The amended rule turns on the one thing no party can choose for another:
+//
+//   - Candidates come from who SIGNED. The candidates for a `handoff.sent` are
+//     the `handoff.received` records signed by the key it named, read from each
+//     envelope's own `public_key`, which is the binding of §2 and cannot be
+//     forged. Apart from which of the two types it is, nothing a candidate
+//     asserts about itself takes it out of that set.
+//   - Narrowing orders and annotates, and never reduces what is graded.
+//     `context.case_id` and `event.sequence` put the candidate a reader is most
+//     likely to want first in the report and remove none of them from grading.
+//     A narrowing that could drop a candidate was itself a laundering path:
+//     publish the tampered receipt with one of those two fields changed beside
+//     a clean decoy that carries them, and the step that "leaves at least one
+//     candidate" leaves the decoy and drops the tamper.
+//   - More than one candidate is a named finding, never a free choice: a reader
+//     permitted to take one match can be handed an honest decoy beside a
+//     tampered record. The per-candidate readings travel with the report, so
+//     naming the record and the check that failed survives a junk record that
+//     outranks it.
+//   - A record missing a REQUIRED field of its own type is `malformed`, so a
+//     pair that commits to nothing never reaches the check that would have
+//     compared absent to absent and found them equal.
+//   - A pair whose two envelope signing keys are equal does not verify.
+//   - Every hand-off record a reader holds is read, not only the ones that pair.
+//
+// THE THREE ATTACKS THE ADVERSARIAL GATE LANDED (proof#133, rulings 1 to 3),
+// and they are one root cause: candidacy and the self-hand-off check compared
+// the envelope `public_key` as a STRING, and nothing constrains its spelling,
+// so the party being audited chose it.
+//
+//   - A key is compared as a KEY (`normalizedSigningKey`). The record side of a
+//     key is pinned to 64-char lowercase hex and the envelope side is pinned
+//     nowhere, so a receiving side that spelled its own envelope key in upper
+//     case decided whether its own record was a candidate at all: one character
+//     class on one field put a tampered receipt beside a clean decoy back at
+//     `verified` with no ambiguity named, and read a self-hand-off signed by
+//     one key as a transfer between two parties. The normalization sits on the
+//     `HeldRecord` boundary so a reader cannot skip it. Whether the ENVELOPE
+//     layer starts rejecting a non-lowercase `public_key` is a
+//     wire-compatibility question and a founder call (proof#135); nothing here
+//     changes what an envelope accepts.
+//   - The reserved namespace bites on any spelling a reader would take for a
+//     hand-off record (`isHandoffNamespace`). An exact `handoff.` prefix let
+//     `HANDOFF.RECEIVED`, `sanning.handoff.received`, `handoff-received` and a
+//     non-string `event_type` disappear from the reading entirely, not even as
+//     malformed, which composed with a decoy reads `verified` over proven
+//     tampering from one edit.
+//
+// THE TWO THE FOURTH HUNT LANDED ON THAT REPAIR (proof#133, rulings 1 and 2),
+// and they are one root cause too: each test above was an allow-list over a
+// value the audited party writes. Candidacy turned on the spelling of a key and
+// scope turned on the spelling of a name, so narrowing the allow-list only
+// moved the boundary and the next spelling walked around it.
+//
+//   - Scope turns on the STRUCTURE (`isHandoffNamespace`). A record carrying
+//     `event.counterparty_public_key`, the field §4.1 defines and no other
+//     section does, is read whatever its `event_type` says, which closes the
+//     `ff` ligature, full-width letters, a Cyrillic `a`, `hand-off`,
+//     `handoffs`, a zero-width space, a BOM and a non-breaking space in one
+//     rule rather than by chasing Unicode. The folded name stays as an
+//     additional way in for a record that omits the field.
+//   - A key that does not parse makes the record `malformed`, never absent
+//     (`recordIsMalformed`). The rule it replaces let such a record drop out
+//     of candidacy in silence, and the other side then read
+//     `counterpart_absent`, which §4.1 obliges a reader to call innocent.
+//     Nine whitespace spellings of a real key produce a VERIFIED envelope in
+//     exactly that state in the Python kernel, so the first attack came back
+//     whole THROUGH the repair. Nothing here changes what an envelope accepts,
+//     and the rule holds either way proof#135 goes.
+//
+// WHAT THE FIFTH HUNT LANDED ON THAT REPAIR, AND WHY THIS ONE IS DIFFERENT
+// (proof#136, ratified by Phil 2026-09-22). Scope was two clauses and both
+// operands are written by the party being audited: an exact test for the key
+// name `counterparty_public_key`, and an ASCII fold of `event_type`. One code
+// point on each (`counterparty_public_k\u0435y` with a Cyrillic `\u0435`,
+// `hando\ufb00.received` with a ligature) put the record in scope by NEITHER
+// route, so it had no reading at all and the pile read `verified`.
+//
+//   - Scope stops existing. `readHandoffs` returns a reading for EVERY record
+//     it is given, in the order given, and a record that is not a conformant
+//     hand-off reads with `NOT_A_HANDOFF_FINDING` rather than producing
+//     silence. Any rule with a silent branch is a rule the audited party
+//     steers into: five repairs narrowed which values reached the branch and
+//     five hunts found a value outside it, so the branch is removed rather
+//     than narrowed a sixth time.
+//   - The declaration names the hand-offs (`isConformantHandoffRecord`, read
+//     by `./declaration.ts`). The gain was that a record could be unreadable
+//     NOW and usable LATER; a claimed side that is not a conformant hand-off
+//     record now fails at the pack layer.
+//   - Missing and explicit null name one thing (`namedCase`). Python's missing
+//     value is `None` and this kernel's is `undefined`, so a candidate
+//     carrying `"case_id": null` was "same case" in one kernel and not in the
+//     other: same verdict, different candidate ORDER, on a value the audited
+//     party writes.
+//
+// No verdict word is coined: `verified`, `failed` and `malformed` are already in
+// use, and `counterpart_absent`, `counterpart_ambiguous` and
+// `not_a_handoff_record` are findings reported beside a verdict rather than
+// verdicts.
+//
+// THE COST OF GRADING EVERY CANDIDATE, stated rather than left to be found. A
+// reader whose pile holds two or more records of the complementary type signed
+// by the counterparty key can no longer reach `verified`: every one of them is
+// graded and the worst of them is the reading. Two agents that exchange more
+// than one message land there. That is the price of never letting a value the
+// audited party writes decide what reaches a check, and the belt is the pack
+// layer: the declaration (evidence-bundle.md 5.4) says which records a pack
+// claims are a pair.
+export const CANDIDATE_NAMESPACE = "handoff.";
+export const DEFINED_EVENT_TYPES = ["handoff.sent", "handoff.received"];
+/**
+ * The finding a record that is not a hand-off record at all reads with.
+ *
+ * A FINDING and not a verdict: the ratified verdict words are closed
+ * (anchor#188) and this reading names an outcome beside one, exactly as
+ * `counterpart_absent`, `counterpart_ambiguous` and `malformed_record` do. It
+ * exists because 4.1 had a SILENT branch, and a rule with a silent branch is a
+ * rule the party being audited steers into (proof#136). A record TRYING to be
+ * a hand-off and getting it wrong reads `malformed`; a record that is not a
+ * hand-off at all reads this. Both are readings. Neither is silence.
+ */
+export const NOT_A_HANDOFF_FINDING = "not_a_handoff_record";
+const OUTCOMES = ["accepted", "rejected", "failed"];
+const ID_PATTERN = /^[A-Za-z0-9_.:-]+$/;
+const HEX64 = /^[0-9a-fA-F]{64}$/;
+const LOWER_HEX64 = /^[0-9a-f]{64}$/;
+// The order a reader names the checks a formed pair failed, fixed so two
+// kernels report one list rather than two orderings of it.
+const CHECK_ORDER = ["message_hash", "sequence", "self_handoff"];
+const VERDICT_RANK = { verified: 0, failed: 1, malformed: 2 };
+// ASCII whitespace, listed rather than delegated: `String.trim()` and Python's
+// `str.strip()` do not strip the same set (`U+FEFF` is whitespace to one and
+// not to the other), and a fold the two kernels disagree about is a divergence
+// on identical bytes (proof#133 review, ruling 3).
+const ASCII_WHITESPACE = new Set([" ", "\t", "\n", "\r", "\v", "\f"]);
+/**
+ * An envelope `public_key` as a KEY rather than as a string: the 32 key bytes
+ * written as lowercase hex, or `null` where the value is not 64 characters of
+ * hex and so names no key this reading can compare.
+ *
+ * Case is the whole point: §2 states lowercase as a PRODUCER convention, the
+ * envelope layer accepts either case in every kernel, and the party being
+ * audited is the producer (proof#133 adversarial gate, ruling 1). Nothing
+ * wider is folded: whitespace inside the value is not stripped, because
+ * Python's `bytes.fromhex` skips ASCII whitespace and this kernel's charset
+ * check does not, a live divergence at the ENVELOPE layer and a separate
+ * founder call (proof#135). A reading rule that silently repaired it would
+ * hide it.
+ */
+export function normalizedSigningKey(value) {
+    if (typeof value !== "string" || !HEX64.test(value))
+        return null;
+    return [...value]
+        .map((c) => (c >= "A" && c <= "Z" ? String.fromCharCode(c.charCodeAt(0) + 32) : c))
+        .join("");
+}
+/**
+ * Whether two envelope keys are the SAME KEY. Two values that name a key are
+ * equal when their key bytes are equal.
+ *
+ * Where either side names no key, the question cannot be answered from key
+ * bytes and the answer is the conservative one: the two are reported as one
+ * key, so the pair reads `failed[self_handoff]` rather than clean. Exact
+ * string equality was the answer here and it was the wrong way round: one key
+ * that signed both ends, spelled `abcd...` on one envelope and `abcd ...` on
+ * the other, is one party, and string equality called it two and read the
+ * self-hand-off `verified` (proof#133 fourth hunt, finding 1). A record whose
+ * own envelope key this reading cannot read is `malformed` under
+ * `recordIsMalformed` and a formed pair reaches `malformed` before it reaches
+ * this line, so the two rules are belt and braces rather than one rule stated
+ * twice.
+ */
+export function sameSigningKey(left, right) {
+    const leftKey = normalizedSigningKey(left);
+    const rightKey = normalizedSigningKey(right);
+    if (leftKey === null || rightKey === null)
+        return true;
+    return leftKey === rightKey;
+}
+/**
+ * The spelling of an `event_type`, folded for the namespace test only: ASCII
+ * whitespace off each end, ASCII upper case down to lower case, and `-` and
+ * `_` read as the `.` separator. Every step is spelled out rather than
+ * delegated to `toLowerCase()` or `trim()`, which do not agree with Python on
+ * non-ASCII input.
+ */
+function foldEventType(value) {
+    const characters = [...value];
+    let start = 0;
+    let end = characters.length;
+    while (start < end && ASCII_WHITESPACE.has(characters[start]))
+        start += 1;
+    while (end > start && ASCII_WHITESPACE.has(characters[end - 1]))
+        end -= 1;
+    return characters
+        .slice(start, end)
+        .map((c) => {
+        if (c === "-" || c === "_")
+            return ".";
+        return c >= "A" && c <= "Z" ? String.fromCharCode(c.charCodeAt(0) + 32) : c;
+    })
+        .join("");
+}
+/**
+ * Whether a reader reads this record as a hand-off record at all.
+ *
+ * §4.1 says a reader reads EVERY hand-off record it holds, and an exact
+ * `handoff.` prefix did not deliver that: `HANDOFF.RECEIVED`,
+ * `sanning.handoff.received`, `handoff-received` and a non-string `event_type`
+ * all vanished from the reading entirely, not even as malformed, so a receipt
+ * typed one character outside the prefix was never read and, beside a clean decoy,
+ * published `verified` over proven tampering (proof#133 adversarial gate,
+ * ruling 2).
+ *
+ * The rule is checkable rather than a judgement, and it is exactly two
+ * clauses. The FIRST is the one the adversary cannot evade: the record's
+ * `event` carries `counterparty_public_key`, the field §4.1 defines and no
+ * other section does, WHATEVER its `event_type` says. The second keeps a
+ * record that omits the field in scope: an `event_type` that is a string whose
+ * folded form has `handoff` as one of its `.`-separated segments, which leaves
+ * `asset_missing` and the other families alone.
+ *
+ * The order is the fix, not decoration. Every earlier version of this test was
+ * an ALLOW-LIST OVER A NAME THE AUDITED PARTY WRITES, so each repair narrowed
+ * the class and the next spelling walked around it: an exact `handoff.` prefix
+ * fell to `HANDOFF.RECEIVED`, and the ASCII fold that replaced it fell to the
+ * `ff` ligature, full-width letters, a Cyrillic `a`, `hand-off`, `handoffs`, a
+ * zero-width space, a BOM and a non-breaking space, each of which left a
+ * tampered receipt with no reading at all beside a clean decoy (proof#133
+ * fourth hunt, finding 2). The structural field closes all of them in one rule
+ * rather than by chasing Unicode, because the attack needs the field: a
+ * receipt that drops `counterparty_public_key` says nothing about who it came
+ * from.
+ *
+ * Anything in scope that is not exactly `handoff.sent` or `handoff.received`
+ * is `malformed`, so a spelling is never a way out.
+ *
+ * THIS IS NO LONGER A GATE ON BEING READ (proof#136). Both clauses are written
+ * by the party being audited, and one code point on each put a record in scope
+ * by neither, which produced silence. `readHandoffs` reads every record it
+ * holds, and this test now decides only WHICH reading a record gets: in scope
+ * and wrong reads `malformed`, out of scope reads `NOT_A_HANDOFF_FINDING`. A
+ * respelling buys a different line rather than no line.
+ */
+export function isHandoffNamespace(held) {
+    if ("counterparty_public_key" in section(held.record, "event"))
+        return true;
+    const type = eventType(held);
+    return typeof type === "string" && foldEventType(type).split(".").includes("handoff");
+}
+function section(record, key) {
+    const value = record[key];
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function eventType(held) {
+    return held.record.event_type;
+}
+function isSafeSequence(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 1;
+}
+// Code POINTS, not UTF-16 units. `"\u{1F600}".length` is 2 in JavaScript and
+// `len()` of the same character is 1 in Python, so a length bound counted in
+// units makes the two kernels disagree about identical bytes (proof#133
+// review, ruling 3).
+function codePoints(value) {
+    return [...value].length;
+}
+// `===` rather than `==`, and the Python half now matches: `True == 1` holds in
+// Python and `true === 1` does not in JavaScript, which let a record carrying
+// `"sequence": true` stay in one kernel's reading and drop out of the other's.
+function sameNumber(left, right) {
+    return left === right;
+}
+/**
+ * A record missing a REQUIRED field of its own type, or carrying one that is
+ * not the type §4.1 states, is malformed and fails. Stated as a rule because
+ * §4.1 had none: a pair where both sides omitted `message_hash` compared absent
+ * to absent, found them equal, and graded intact (proof#132).
+ *
+ * A record whose ENVELOPE key this reading cannot read is malformed too, and
+ * that one is a repair rather than an omission. The rule used to be "a value
+ * that is not 64 characters of hex names no key and matches nothing", so such a
+ * record dropped out of candidacy in silence and the subject read
+ * `counterpart_absent`, which §4.1 obliges a reader to call innocent. Nine
+ * whitespace spellings of a real key produce a VERIFIED envelope in exactly
+ * that state in the Python kernel, because `bytes.fromhex` skips ASCII
+ * whitespace, which reopened the whole of the first attack through the repair
+ * rather than around it (proof#133 fourth hunt, finding 1). A record a reader
+ * HOLDS, whose own key it cannot read, is a defect in the record and not an
+ * absence of one. This holds whatever the envelope layer decides about its hex
+ * charset (proof#135).
+ */
+export function recordIsMalformed(held) {
+    if (normalizedSigningKey(held.publicKey) === null)
+        return true;
+    const type = eventType(held);
+    if (typeof type !== "string" || !DEFINED_EVENT_TYPES.includes(type)) {
+        return true; // including any other handoff.* name, which A11 forbids
+    }
+    const raw = held.record;
+    for (const key of ["event", "context"]) {
+        const value = raw[key];
+        if (value === null || typeof value !== "object" || Array.isArray(value))
+            return true;
+    }
+    const event = section(raw, "event");
+    const context = section(raw, "context");
+    if (typeof event.message_hash !== "string" || !HEX64.test(event.message_hash))
+        return true;
+    const contentType = event.content_type;
+    if (typeof contentType !== "string" ||
+        codePoints(contentType) === 0 ||
+        codePoints(contentType) > 128) {
+        return true;
+    }
+    if (typeof event.counterparty_public_key !== "string" ||
+        !LOWER_HEX64.test(event.counterparty_public_key)) {
+        return true;
+    }
+    if (!isSafeSequence(event.sequence))
+        return true;
+    if (type === "handoff.received") {
+        if (typeof event.outcome !== "string" || !OUTCOMES.includes(event.outcome))
+            return true;
+    }
+    else if ("outcome" in event) {
+        return true; // outcome is a handoff.received field only
+    }
+    // The OPTIONAL fields are optional: absence is never malformed, and a present
+    // one still has to be what §4.1 says it is.
+    //
+    // `message_bytes_hash` is NOT checked here. Its own row in 4.1 says a reader
+    // MUST NOT match, pair or grade on it, and calling a record malformed for it
+    // is grading on it (proof#133 review, ruling 5).
+    if ("case_id" in context) {
+        const value = context.case_id;
+        if (typeof value !== "string" || codePoints(value) > 128 || !ID_PATTERN.test(value))
+            return true;
+    }
+    if ("protocol" in context) {
+        const value = context.protocol;
+        if (typeof value !== "string" || codePoints(value) === 0 || codePoints(value) > 64)
+            return true;
+    }
+    if ("in_reply_to" in context) {
+        const value = context.in_reply_to;
+        if (typeof value !== "string" || !HEX64.test(value))
+            return true;
+    }
+    return false;
+}
+function complement(type) {
+    return type === "handoff.sent" ? "handoff.received" : "handoff.sent";
+}
+/**
+ * Who signed, and nothing a candidate says about itself.
+ *
+ * The complementary record type is the one conjunct that stays hard, and the
+ * reason is the honest two-way case rather than a preference: an honest reply is
+ * a `handoff.sent` signed by the other agent, naming this one, under the same
+ * case identifier and at the same sequence number, which is byte-for-byte the
+ * shape of a receiving side that mislabels its receipt. Admitting same-type
+ * candidates would grade an honest reply as a failed hand-off. §4.1 names that
+ * residual path, and the declaration (evidence-bundle.md §5.4) is its belt.
+ */
+function candidatesFor(subject, held) {
+    // KEYS, never spellings of a key. Comparing the raw strings handed the
+    // audited party the set itself: an envelope key spelled in upper case names
+    // the same key, the record side is pinned to lowercase hex and the envelope
+    // side is pinned nowhere, so one character class took the tampered receipt
+    // out of the set and left the clean decoy in it (proof#133 adversarial
+    // gate, ruling 1).
+    const wanted = normalizedSigningKey(section(subject.record, "event").counterparty_public_key);
+    if (wanted === null)
+        return []; // the subject names no key
+    const wantedType = complement(eventType(subject));
+    return held.filter((candidate) => candidate !== subject &&
+        normalizedSigningKey(candidate.publicKey) === wanted &&
+        eventType(candidate) === wantedType);
+}
+/**
+ * Order a candidate set. It REMOVES NOTHING.
+ *
+ * `context.case_id` and then `event.sequence` put the candidate a reader is most
+ * likely to want at the front of the report, and both are written by the party
+ * being audited, so neither decides what gets graded. A version of this function
+ * that filtered, "applying a step only where it leaves at least one candidate",
+ * was itself a laundering path: the receiving side publishes the tampered
+ * receipt with its `case_id` or its `sequence` changed and a clean decoy that
+ * carries the subject's values, the surviving decoy keeps the step alive, the
+ * tamper drops out of the set, and the reading is `verified` with no ambiguity
+ * named (proof#133 review, ruling 1).
+ *
+ * The sort is total and deterministic, so the two kernels report one order.
+ */
+function order(subject, candidates) {
+    const wantedCase = namedCase(section(subject.record, "context"));
+    const wantedSequence = section(subject.record, "event").sequence;
+    const rank = (c) => {
+        const context = section(c.record, "context");
+        const sameCase = isSameCase(namedCase(context), wantedCase);
+        const sameSequence = sameNumber(section(c.record, "event").sequence, wantedSequence);
+        return [sameCase ? 0 : 1, sameSequence ? 0 : 1, c.ref];
+    };
+    return [...candidates].sort((a, b) => {
+        const [ac, aq, ar] = rank(a);
+        const [bc, bq, br] = rank(b);
+        if (ac !== bc)
+            return ac - bc;
+        if (aq !== bq)
+            return aq - bq;
+        return ar < br ? -1 : ar > br ? 1 : 0;
+    });
+}
+/**
+ * Which case a record names, for the ordering step only.
+ *
+ * An ABSENT `context.case_id` and one written as `null` name the same thing,
+ * which is no case. Python's missing value is `None` and this kernel's is
+ * `undefined`, so a candidate carrying `"case_id": null` was "same case" in
+ * one kernel and not in the other when the subject lawfully omits the OPTIONAL
+ * key: same verdict, DIFFERENT candidate order, and the cross-kernel gate's
+ * own contract is that the reading it compares carries the candidates in
+ * order. The party being audited writes that `null` (proof#133 fifth hunt,
+ * closed by proof#136).
+ */
+function namedCase(context) {
+    const value = context.case_id;
+    return value === undefined ? null : value;
+}
+/**
+ * Whether two records name the same case, for the ordering step only. Two
+ * records that name NO case are in the same position, and a case identifier is
+ * a string (4.1), so anything else names no case a reader can compare. Stated
+ * in one rule in both kernels so `None` and `undefined` cannot mean two
+ * things.
+ */
+function isSameCase(left, right) {
+    if (left === null && right === null)
+        return true;
+    return typeof left === "string" && typeof right === "string" && left === right;
+}
+function gradePair(subject, counterpart) {
+    if (recordIsMalformed(subject) || recordIsMalformed(counterpart)) {
+        return { verdict: "malformed", checks: [] };
+    }
+    const failed = new Set();
+    // The same KEY, whatever the two envelopes spelled it as: one key signing
+    // both ends spelled upper case on one side and lower on the other read as a
+    // transfer between two parties (proof#133 adversarial gate, ruling 1).
+    if (sameSigningKey(subject.publicKey, counterpart.publicKey))
+        failed.add("self_handoff");
+    const subjectEvent = section(subject.record, "event");
+    const counterpartEvent = section(counterpart.record, "event");
+    const subjectHash = String(subjectEvent.message_hash ?? "").toLowerCase();
+    const counterpartHash = String(counterpartEvent.message_hash ?? "").toLowerCase();
+    if (subjectHash !== counterpartHash)
+        failed.add("message_hash");
+    if (!sameNumber(subjectEvent.sequence, counterpartEvent.sequence))
+        failed.add("sequence");
+    const checks = CHECK_ORDER.filter((name) => failed.has(name));
+    return { verdict: checks.length > 0 ? "failed" : "verified", checks: [...checks] };
+}
+/**
+ * Read ONE record against everything the reader holds.
+ *
+ * Every record gets a reading, and the two findings are how the distinction a
+ * reader needs survives (proof#136): a record that is not a hand-off record at
+ * all reads `NOT_A_HANDOFF_FINDING` with no verdict, and a record 4.1 DOES
+ * govern and that is wrong reads `malformed`. The scope test lives HERE and
+ * not in `readHandoffs`, so the two entry points cannot answer differently
+ * about one record.
+ */
+export function readHandoff(subject, held) {
+    if (!isHandoffNamespace(subject)) {
+        return {
+            ref: subject.ref,
+            verdict: null,
+            failedChecks: [],
+            findings: [NOT_A_HANDOFF_FINDING],
+            candidates: [],
+            candidateReadings: [],
+        };
+    }
+    if (recordIsMalformed(subject)) {
+        return {
+            ref: subject.ref,
+            verdict: "malformed",
+            failedChecks: [],
+            findings: ["malformed_record"],
+            candidates: [],
+            candidateReadings: [],
+        };
+    }
+    const candidates = order(subject, candidatesFor(subject, held));
+    if (candidates.length === 0) {
+        return {
+            ref: subject.ref,
+            verdict: null,
+            failedChecks: [],
+            findings: ["counterpart_absent"],
+            candidates: [],
+            candidateReadings: [],
+        };
+    }
+    // EVERY candidate is graded. Ordering above chose where each one is reported
+    // and took none of them out of this list.
+    const graded = candidates.map((candidate) => {
+        const { verdict, checks } = gradePair(subject, candidate);
+        return { ref: candidate.ref, verdict, failedChecks: checks };
+    });
+    const worst = Math.max(...graded.map((g) => VERDICT_RANK[g.verdict]));
+    const verdict = Object.keys(VERDICT_RANK).find((name) => VERDICT_RANK[name] === worst);
+    // Over every candidate, not only the ones at the winning verdict: `malformed`
+    // outranks `failed`, so a single junk record would otherwise strip the named
+    // `message_hash` failure out of the report (proof#133 review, ruling 6).
+    const failed = new Set();
+    for (const g of graded)
+        for (const check of g.failedChecks)
+            failed.add(check);
+    const findings = [];
+    // Never a free choice: a reader permitted to take one match can be handed an
+    // honest decoy beside a tampered record.
+    if (candidates.length > 1)
+        findings.push("counterpart_ambiguous");
+    if (verdict === "malformed")
+        findings.push("malformed_record");
+    return {
+        ref: subject.ref,
+        verdict,
+        failedChecks: CHECK_ORDER.filter((name) => failed.has(name)),
+        findings,
+        candidates: candidates.map((c) => c.ref),
+        candidateReadings: graded,
+    };
+}
+/**
+ * EVERY record the reader holds gets a reading, in the order given.
+ *
+ * This function does not filter, and the branch that used to decide whether a
+ * record was read at all is gone (proof#136, ratified by Phil 2026-09-22).
+ * Scope was two clauses, an exact test for the key name
+ * `counterparty_public_key` and an ASCII fold of `event_type`, and both
+ * operands are written by the party being audited: one code point on each put
+ * a record in scope by NEITHER route, so it had no reading at all and the pile
+ * read clean. Five repairs narrowed which values reached that silent branch
+ * and five hunts found a value outside it, so the branch is removed rather
+ * than narrowed again.
+ *
+ * The distinction a reader needs survives as two findings rather than as a
+ * reading and a silence: a record TRYING to be a hand-off and getting it wrong
+ * reads `malformed` with `malformed_record`, and a record that is not a
+ * hand-off record at all reads `NOT_A_HANDOFF_FINDING` with no verdict.
+ * `isHandoffNamespace` decides which of the two, in `readHandoff`, and no
+ * longer whether a record is read.
+ *
+ * THE COST, stated rather than left to be found: a reader given a mixed pile
+ * produces a line per record, including for records that have nothing to do
+ * with hand-offs. 4.1 says so too.
+ */
+export function readHandoffs(held) {
+    return held.map((record) => readHandoff(record, held));
+}
+/**
+ * Whether this record is a conformant hand-off record of 4.1: it is read as a
+ * hand-off record at all (`isHandoffNamespace`) and it is not `malformed`
+ * (`recordIsMalformed`), which between them mean it is exactly a
+ * `handoff.sent` or a `handoff.received` carrying every REQUIRED field of its
+ * own type, under an envelope key this reading can read.
+ *
+ * `./declaration.ts` reads this for evidence-bundle.md 5.4: a claimed
+ * `sent_event_id` or `received_event_id` naming a record that is not one of
+ * these is a DEVIATION, so a record cannot be unreadable at the record layer
+ * and usable at the pack layer at the same time (proof#136).
+ */
+export function isConformantHandoffRecord(held) {
+    return isHandoffNamespace(held) && !recordIsMalformed(held);
+}

package/dist/index.d.ts

@@ -2,13 +2,21 @@ export { ACCEPTED_SPEC_MAJORS, contentHashes, jcs, specVersionSupported, verifyE
 export { bytesToHex, deriveOperatorAddress, ed25519Verify, hexToBytes, sha256Bytes, sha256Hex, utf8, verifyRsaPssSha256, } from "./crypto.js";
 export { EMPTY_TREE_ROOT_HEX, auditPath, leafHash, merkleRoot, nodeHash, verifyInclusion, } from "./merkle.js";
 export type { ContentRole, Envelope, Subject, VerificationResult, VerifyOptions } from "./types.js";
-export { ANCHOR_TRACE_BODY_TYPE, ANCHOR_TRACE_BODY_TYPE_V1, ANCHOR_TRACE_BODY_TYPES, EXPORT_BODY_TYPE, STAMP_BODY_VERSION, STAMP_TRACE_BODY_TYPE, STAMP_EVIDENCE_BODY_TYPE, disclosedContent, recomputeExportVerdict, verifyEvidenceBundle, } from "./evidence.js";
-export type { AnchorTraceBody, AttestationPayload, AttestationRecord, AttestationResult, CheckpointResult, ComposeVerdictResult, DisclosedContentResult, DisclosedEventContent, DisclosureStatus, EvidenceBundle, EvidenceBundleResult, EvidenceIssuer, EvidenceStatus, EvidenceVerdict, EventResult, ExportBody, ExportResult, OnChainOutcome, OnChainResult, PerGatewayOutcome, AnchorRef, StampBody, StampEntry, StampResult, StampSubtree, StampSubtreeResult, StampTraceBody, StampEvidenceBody, StampEvidenceEvent, StampEvidenceInclusion, TraceCheckpoint, TraceCheckpointV1, TraceEvent, TraceInclusion, VerdictAttestation, VerdictCheckpoint, VerdictEvent, VerdictObject, VerdictOnChain, VerdictOnChainGateway, VerifyEvidenceOptions, } from "./evidence.js";
+export { ANCHOR_TRACE_BODY_TYPE, EXPORT_BODY_TYPE, STAMP_BODY_VERSION, STAMP_TRACE_BODY_TYPE, STAMP_EVIDENCE_BODY_TYPE, disclosedContent, recomputeExportVerdict, verifyEvidenceBundle, } from "./evidence.js";
+export type { AnchorTraceBody, AttestationPayload, AttestationRecord, AttestationResult, CheckpointResult, ComposeVerdictResult, DisclosedContentResult, DisclosedEventContent, DisclosureStatus, EvidenceBundle, EvidenceBundleResult, EvidenceIssuer, EvidenceStatus, EvidenceVerdict, EventResult, ExportBody, ExportResult, OnChainOutcome, OnChainResult, PerGatewayOutcome, AnchorRef, StampBody, StampEntry, StampResult, StampSubtree, StampSubtreeResult, StampTraceBody, StampEvidenceBody, StampEvidenceEvent, StampEvidenceInclusion, TraceCheckpoint, TraceEvent, TraceInclusion, VerdictAttestation, VerdictCheckpoint, VerdictEvent, VerdictObject, VerdictOnChain, VerdictOnChainGateway, VerifyEvidenceOptions, } from "./evidence.js";
 export { accountDisclosure, completenessNotes, gradeCauses, gradePack, renderCause, signedLeafCount, } from "./grading.js";
 export type { CompletenessNote, DisclosureAccount, GradeInput, PackGrade, PackGradeCause, PackGradeCauseKind, PackVerdict, } from "./grading.js";
+export { DECLARATION_VERSION, checkDeclaration, declarationClaims, packRecords, renderContentFinding, renderDeclarationSummary, renderDeviation, renderNote, } from "./declaration.js";
+export type { DeclarationCheck, DeclarationClaims, DeclarationContentFinding, DeclarationContentKind, DeclarationDeviation, DeclarationDeviationKind, DeclarationNote, DeclarationNoteKind, DeclarationVerdict, PackRecord, } from "./declaration.js";
+export { CASE_BODY_TYPES, CASE_EXCEPTION_KINDS, CASE_QUARANTINED_PROFILES, CASE_RECORD_PROFILES, CASE_VERDICTS, readCase, renderCaseSummary, renderException, } from "./case.js";
+export type { CaseException, CaseExceptionKind, CasePack, CaseReading, CaseRecordReading, CaseVerdict, } from "./case.js";
 export { ADAPTER_CHAIN_NAMESPACES, CHAIN_READING_SCOPE, readChains, renderChainFinding, } from "./chain.js";
 export type { ChainFinding, ChainFindingKind, ChainReading, ChainSource, ChainSummary, } from "./chain.js";
 export { attestationSignatureToHex, composeExport } from "./compose.js";
 export type { ComposeExportOptions, ComposeExportResult, ExporterKey } from "./compose.js";
 export { AGENT_PROOF_SPEC_PREFIX, isAgentProofSpec, verifyAgentProofBundle } from "./agent-proof.js";
 export type { AgentProofBundle, AgentProofResult, VerifyAgentProofOptions, } from "./agent-proof.js";
+export { CANDIDATE_NAMESPACE, DEFINED_EVENT_TYPES, NOT_A_HANDOFF_FINDING, isConformantHandoffRecord, readHandoff, readHandoffs, recordIsMalformed, } from "./handoff.js";
+export type { CandidateReading, HandoffReading, HandoffRecord, HandoffVerdict, HeldRecord, } from "./handoff.js";
+export { BYTES_FOR_UNKNOWN_PART, CONFLICTING_PART_BYTES, INLINE_BYTES_KEYS, MESSAGE_RESULT_ORDER, PARTS_NOT_AN_ARRAY, PART_ENCODING_MISMATCH, PART_INLINE_BYTES, PART_INLINE_MISMATCHED, PART_MALFORMED_DESCRIPTOR, PART_MATCHED, PART_MISMATCHED, PART_NOT_A_FILE, PART_SUPPLIED_TWICE, PART_UNCHECKED, REFUSAL_ORDER, commitHeldMessage, isFilePart, uncheckedHeldParts, } from "./message-parts.js";
+export type { HeldMessage, Note, PartReading, Refusal, SuppliedPart } from "./message-parts.js";