@sanning/proof 0.10.0 → 0.11.1

package/src/handoff.ts

@@ -0,0 +1,694 @@
+// 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.
+//   - A formed pair verifies only when each record names the other's signer
+//     (v1.16, A21), or it fails `counterparty_named`. Up to 0.11.0 grading
+//     never read whom either record names.
+//
+// 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"] as const;
+
+/**
+ * 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", "counterparty_named"] as const;
+const VERDICT_RANK: Record<string, number> = { 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: unknown): string | null {
+  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: unknown, right: unknown): boolean {
+  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: string): string {
+  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("");
+}
+
+export type HandoffVerdict = "verified" | "failed" | "malformed";
+
+export interface HandoffRecord {
+  event_type?: unknown;
+  event?: unknown;
+  context?: unknown;
+  metadata?: unknown;
+  [key: string]: unknown;
+}
+
+/**
+ * One hand-off record as a reader holds it: the committed record, plus the
+ * `public_key` of the envelope that carries it. The key comes from the ENVELOPE
+ * and never from the record, which is the whole point of the amended rule.
+ *
+ * PRECONDITION: THE ENVELOPE MUST ALREADY HAVE VERIFIED. "Unforgeable" is a
+ * property of a VERIFIED envelope and of nothing else. The key on an envelope
+ * whose signature has not been checked is an assertion like any other, and
+ * every reading in this module is then worth exactly as much as that
+ * assertion. A reader builds a `HeldRecord` only from an envelope that
+ * `verifyEnvelope` returned `ok` for, bound to the canonical bytes of this
+ * record. Nothing in this module can check that for itself, which is why it is
+ * stated here (proof#133 adversarial gate, ruling 3), and why candidacy and
+ * the self-hand-off check read `normalizedSigningKey(publicKey)` rather than
+ * the spelling the audited party chose.
+ */
+export interface HeldRecord {
+  publicKey: string;
+  record: HandoffRecord;
+  ref: string;
+}
+
+/**
+ * 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: HeldRecord): boolean {
+  if ("counterparty_public_key" in section(held.record, "event")) return true;
+  const type = eventType(held);
+  return typeof type === "string" && foldEventType(type).split(".").includes("handoff");
+}
+
+/**
+ * What one candidate graded to, kept beside the aggregate. 4.1 requires a
+ * reader to name the record and which check failed, and `malformed` outranks
+ * `failed`, so one junk record signed by the counterparty key would otherwise
+ * turn a named `message_hash` failure into a `malformed` with nothing named
+ * (proof#133 review, ruling 6).
+ */
+export interface CandidateReading {
+  ref: string;
+  verdict: HandoffVerdict;
+  failedChecks: string[];
+}
+
+export interface HandoffReading {
+  ref: string;
+  /** `null` where no pair formed: there is no verdict to give, and the finding says why. */
+  verdict: HandoffVerdict | null;
+  failedChecks: string[];
+  findings: string[];
+  /** Ordered, never filtered. */
+  candidates: string[];
+  /** One entry per candidate, in the same order, and nothing left out of it. */
+  candidateReadings: CandidateReading[];
+}
+
+function section(record: HandoffRecord, key: "event" | "context"): Record<string, unknown> {
+  const value = record[key];
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function eventType(held: HeldRecord): unknown {
+  return held.record.event_type;
+}
+
+function isSafeSequence(value: unknown): boolean {
+  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: string): number {
+  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: unknown, right: unknown): boolean {
+  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: HeldRecord): boolean {
+  if (normalizedSigningKey(held.publicKey) === null) return true;
+  const type = eventType(held);
+  if (typeof type !== "string" || !(DEFINED_EVENT_TYPES as readonly string[]).includes(type)) {
+    return true; // including any other handoff.* name, which A11 forbids
+  }
+  const raw = held.record;
+  for (const key of ["event", "context"] as const) {
+    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: unknown): string {
+  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: HeldRecord, held: readonly HeldRecord[]): HeldRecord[] {
+  // 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: HeldRecord, candidates: HeldRecord[]): HeldRecord[] {
+  const wantedCase = namedCase(section(subject.record, "context"));
+  const wantedSequence = section(subject.record, "event").sequence;
+  const rank = (c: HeldRecord): [number, number, string] => {
+    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: Record<string, unknown>): unknown {
+  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: unknown, right: unknown): boolean {
+  if (left === null && right === null) return true;
+  return typeof left === "string" && typeof right === "string" && left === right;
+}
+
+function gradePair(
+  subject: HeldRecord,
+  counterpart: HeldRecord,
+): { verdict: HandoffVerdict; checks: string[] } {
+  if (recordIsMalformed(subject) || recordIsMalformed(counterpart)) {
+    return { verdict: "malformed", checks: [] };
+  }
+  const failed = new Set<string>();
+  // 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");
+  // Each record names the OTHER's signer (v1.16, A21). Candidacy reads the key
+  // the subject names and nothing the candidate says, so up to and including
+  // 0.11.0 a sent record addressed to C paired `verified` with B's receipt of
+  // it, and a receipt naming C as its sender paired `verified` with A's send.
+  // Both halves of the naming are graded, each against the envelope key the
+  // other record was SIGNED with, compared as a key. The Python half is
+  // `_grade_pair`.
+  const [sent, received] =
+    eventType(subject) === "handoff.sent" ? [subject, counterpart] : [counterpart, subject];
+  const sentNames = normalizedSigningKey(section(sent.record, "event").counterparty_public_key);
+  const receivedNames = normalizedSigningKey(
+    section(received.record, "event").counterparty_public_key,
+  );
+  // The send names who received it.
+  if (sentNames !== normalizedSigningKey(received.publicKey)) failed.add("counterparty_named");
+  // The receipt names who sent it.
+  if (receivedNames !== normalizedSigningKey(sent.publicKey)) failed.add("counterparty_named");
+  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: HeldRecord, held: readonly HeldRecord[]): HandoffReading {
+  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: CandidateReading[] = 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,
+  ) as HandoffVerdict)!;
+
+  // 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<string>();
+  for (const g of graded) for (const check of g.failedChecks) failed.add(check);
+
+  const findings: string[] = [];
+  // 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: readonly HeldRecord[]): HandoffReading[] {
+  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: HeldRecord): boolean {
+  return isHandoffNamespace(held) && !recordIsMalformed(held);
+}