@sanning/proof 0.19.1 → 0.20.0

package/src/handoff.ts

@@ -1,155 +1,33 @@
-// The hand-off pairing rule of specs/envelope-spec.md §4.1 (v1.17).
+// The hand-off pairing rule of specs/envelope-spec.md §4.1: which records are
+// candidates to be the counterpart of a given one, how candidates are ordered,
+// and what a formed pair grades to. The Python half is
+// src/sanning_proof/handoff.py; both must answer identically on identical bytes.
 //
-// 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.
+// Every field a record carries is written by the party being audited, so:
 //
-// 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, AND THE ACCOUNTED-FOR RULE THAT PAYS
-// MOST OF IT (envelope-spec.md 4.1 v1.17, amendment A20). Grading every
-// candidate means the records of a party's OTHER exchanges are candidates too,
-// and they fail. Up to v1.16 that put `verified` out of reach for any two agents
-// that exchanged more than one message in one direction, and the declaration
-// named as the belt cannot be one: evidence-bundle.md 5.5 forbids the reading
-// to consult `handoffs[]` to pair anything. So a candidate that grades `failed`
-// is SET ASIDE from the subject's verdict, failed checks and ambiguity when,
-// and only when, the reader holds another record `o` that accounts for it
-// (`accountedFor` below): `o` is signed by the subject's own key and is the
-// subject's type; `o` names the candidate's signer and the candidate names the
-// subject's key back; `o`'s sequence differs from the subject's; and the
-// candidate grades `verified` against `o`. The candidate stays in `candidates`
-// and `candidateReadings`, with `accountedFor` set. Setting one aside needs a
-// verified pair with a record the OTHER side signed, so a tampered record
-// stays live. Fan-in, fan-out, and one pair in two cases at one sequence still
-// read `failed`: the Python half's module docstring says why.
-
-export const CANDIDATE_NAMESPACE = "handoff.";
-export const DEFINED_EVENT_TYPES = ["handoff.sent", "handoff.received"] as const;
+//   - Candidates come from who signed: the `agent.handoff.received` records signed by
+//     the key an `agent.handoff.sent` names, read from each envelope's own `public_key`.
+//     Keys are compared as keys (`normalizedSigningKey`), never as strings.
+//   - Ordering (`case_id`, then `sequence`) never removes a candidate. A filter
+//     would let a clean decoy shadow a tampered receipt.
+//   - More than one live candidate is the finding `counterpart_ambiguous`.
+//   - A record whose envelope key does not parse is `malformed`, never absent:
+//     absence reads as innocent. An `agent.handoff.*` record missing a required
+//     field, or one the agent reader reads `nonconforming`, is `nonconforming`.
+//   - A pair signed by one key on both ends fails `self_handoff`, and each
+//     record must name the other's signer or it fails `counterparty_named`.
+//   - Every record gets a reading. There is no silent branch for a spelling to
+//     steer into: a record that is not a hand-off reads `NOT_A_HANDOFF_FINDING`.
+//   - A failed candidate is set aside (`accountedFor`) only when the reader
+//     holds a verified pair proving it belongs to another exchange.
+
+export const CANDIDATE_NAMESPACE = "agent.handoff.";
+export const DEFINED_EVENT_TYPES = ["agent.handoff.sent", "agent.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.
+ * The finding for a record that is not a hand-off record at all. A finding
+ * beside a verdict, not a verdict: a record that tries to be a hand-off and
+ * gets it wrong reads `malformed` or `nonconforming` instead. Neither is silence.
  */
 export const NOT_A_HANDOFF_FINDING = "not_a_handoff_record";
 const OUTCOMES = ["accepted", "rejected", "failed"];
@@ -157,30 +35,37 @@ 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.
+// 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 };
+// The verdict a defect gives a record (evidence-bundle.md section 3): a record that cannot be
+// read as a hand-off is `incomplete` (its claim is not proven, unreadable), and one that
+// breaks its vocabulary is `failed` with nothing proven altered.
+const DEFECT_VERDICT = { malformed: "incomplete", nonconforming: "failed" } as const;
+
+/**
+ * Which candidate a subject reads as, worst last. A proven check failure outranks a
+ * record that breaks its vocabulary (`failed` with no check named), and a record that
+ * cannot be read outranks both, so one junk candidate is named as itself
+ * (`counterpart_malformed`) and never as a failed pair.
+ */
+function rank(verdict: HandoffVerdict, failedChecks: readonly string[]): number {
+  if (verdict === "incomplete") return 3;
+  if (verdict === "failed") return failedChecks.length > 0 ? 2 : 1;
+  return 0;
+}
 
-// 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).
+// Listed rather than delegated: `String.trim()` and Python's `str.strip()`
+// disagree on `U+FEFF`, and the kernels must fold identically.
 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.
+ * An envelope `public_key` as a key: the 32 key bytes as lowercase hex, or
+ * `null` where the value is not 64 hex characters.
  *
- * 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.
+ * Case is folded because the envelope layer accepts either case and the
+ * audited party is the producer. Whitespace is not stripped: Python's
+ * `bytes.fromhex` skips it and this kernel does not, and repairing that here
+ * would hide the divergence.
  */
 export function normalizedSigningKey(value: unknown): string | null {
   if (typeof value !== "string" || !HEX64.test(value)) return null;
@@ -190,20 +75,9 @@ export function normalizedSigningKey(value: unknown): string | null {
 }
 
 /**
- * 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.
+ * Whether two envelope keys are the same key. Where either side names no key,
+ * the answer is the conservative one (same key), so the pair reads
+ * `failed[self_handoff]` rather than clean.
  */
 export function sameSigningKey(left: unknown, right: unknown): boolean {
   const leftKey = normalizedSigningKey(left);
@@ -213,11 +87,9 @@ export function sameSigningKey(left: unknown, right: unknown): boolean {
 }
 
 /**
- * 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.
+ * An `event_type` folded for the namespace test only: ASCII whitespace
+ * trimmed, ASCII lower-cased, `-` and `_` read as `.`. Spelled out because
+ * `toLowerCase()` and `trim()` disagree with Python on non-ASCII input.
  */
 function foldEventType(value: string): string {
   const characters = [...value];
@@ -234,7 +106,7 @@ function foldEventType(value: string): string {
     .join("");
 }
 
-export type HandoffVerdict = "verified" | "failed" | "malformed";
+export type HandoffVerdict = "verified" | "failed" | "incomplete";
 
 export interface HandoffRecord {
   event_type?: unknown;
@@ -245,67 +117,36 @@ export interface HandoffRecord {
 }
 
 /**
- * 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.
+ * 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, never from the record.
  *
- * 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.
+ * Precondition: build a `HeldRecord` only from an envelope `verifyEnvelope`
+ * returned `ok` for. An unverified key is an assertion like any other, and this
+ * module cannot check it.
  */
 export interface HeldRecord {
   publicKey: string;
   record: HandoffRecord;
   ref: string;
+  /**
+   * The agent reader read this record `failed` (agent-events.md section
+   * 10). Set only by a reader that read the record with the pile it is held in
+   * (the case reading); the section 4.1 reading then takes the record as
+   * nonconforming, so its counterpart reads its candidate as nonconforming.
+   */
+  agentNonconforming?: boolean;
 }
 
 /**
- * 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.
+ * Whether a record is in the hand-off namespace: its `event` carries
+ * `counterparty_public_key` (the field §4.1 defines), whatever its `event_type`
+ * says, or its folded `event_type` has `handoff` as a `.`-separated segment.
  *
- * 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.
+ * The structural clause comes first because a name is written by the audited
+ * party and Unicode respellings walk around any allow-list. This decides only
+ * which reading a record gets: in scope and wrong reads `malformed`, out of
+ * scope reads `NOT_A_HANDOFF_FINDING`.
  */
 export function isHandoffNamespace(held: HeldRecord): boolean {
   if ("counterparty_public_key" in section(held.record, "event")) return true;
@@ -314,24 +155,17 @@ export function isHandoffNamespace(held: HeldRecord): boolean {
 }
 
 /**
- * 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).
+ * What one candidate graded to, kept beside the aggregate, so a junk record
+ * that outranks it (`malformed` over `failed`) cannot hide a named failure.
  */
 export interface CandidateReading {
   ref: string;
   verdict: HandoffVerdict;
   failedChecks: string[];
   /**
-   * The ref of the record that ACCOUNTS FOR this candidate, or `null` (4.1
-   * v1.17, A20). Set only on a candidate that graded `failed` and that the
-   * reader holds a verified pair for elsewhere; such a candidate is still
-   * reported here and takes no part in the subject's verdict, failed checks or
-   * ambiguity. Every reading this kernel returns carries it. It is optional in
-   * the type only so that code which builds a `CandidateReading` itself keeps
-   * compiling: the field is an addition.
+   * The ref of the record that accounts for this failed candidate, or `null`.
+   * An accounted-for candidate takes no part in the subject's verdict, failed
+   * checks or ambiguity. Optional only so caller-built readings compile.
    */
   accountedFor?: string | null;
 }
@@ -345,10 +179,8 @@ export interface HandoffReading {
   /** Ordered, never filtered. */
   candidates: string[];
   /**
-   * One entry per candidate, in the same order, and nothing left out of it. A
-   * candidate another record accounts for is here with `accountedFor` set, and
-   * where every candidate is accounted for the reading is `counterpart_absent`
-   * with the candidates still listed.
+   * One entry per candidate, in the same order. Where every candidate is
+   * accounted for, the reading is `counterpart_absent` with them still listed.
    */
   candidateReadings: CandidateReading[];
 }
@@ -368,46 +200,50 @@ 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).
+// Code points, not UTF-16 units, so a length bound matches Python's `len()`.
 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.
+// Strict: Python's half also rejects `True == 1`, so `"sequence": true` cannot
+// read differently in the two kernels.
 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).
+ * What is wrong with a record section 4.1 governs, read on its own, or `null`.
  *
- * 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).
+ * `malformed` where it cannot be read as a hand-off record: its envelope key
+ * does not parse (an unreadable key would drop it out of candidacy and the
+ * other side would read an innocent `counterpart_absent`), or its type is a
+ * respelling of the two names. `nonconforming` where it is one of the two types
+ * and a required field is missing or mistyped (two records that both omit
+ * `message_hash` would otherwise compare equal), or the agent reader read it
+ * `failed` (`agentNonconforming`).
  */
-export function recordIsMalformed(held: HeldRecord): boolean {
-  if (normalizedSigningKey(held.publicKey) === null) return true;
+export function recordDefect(held: HeldRecord): "malformed" | "nonconforming" | null {
+  if (normalizedSigningKey(held.publicKey) === null) return "malformed";
   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
+    return "malformed"; // including any other handoff.* name
   }
+  if (held.agentNonconforming === true || breaksItsType(held, type)) return "nonconforming";
+  return null;
+}
+
+/** `recordDefect` is `malformed`. */
+export function recordIsMalformed(held: HeldRecord): boolean {
+  return recordDefect(held) === "malformed";
+}
+
+/** `recordDefect` is `nonconforming`. */
+export function recordIsNonconforming(held: HeldRecord): boolean {
+  return recordDefect(held) === "nonconforming";
+}
+
+/** A record of one of the two types missing a field section 4.1 requires, or carrying one it does not allow. */
+function breaksItsType(held: HeldRecord, type: string): boolean {
   const raw = held.record;
   for (const key of ["event", "context"] as const) {
     const value = raw[key];
@@ -433,18 +269,15 @@ export function recordIsMalformed(held: HeldRecord): boolean {
   }
   if (!isSafeSequence(event.sequence)) return true;
 
-  if (type === "handoff.received") {
+  if (type === "agent.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
+    return true; // outcome is an agent.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).
+  // Optional fields: absence is never a defect, but a present one must have
+  // its §4.1 type. `message_bytes_hash` is not checked: §4.1 says a reader must
+  // not grade on it.
   if ("case_id" in context) {
     const value = context.case_id;
     if (typeof value !== "string" || codePoints(value) > 128 || !ID_PATTERN.test(value))
@@ -463,27 +296,16 @@ export function recordIsMalformed(held: HeldRecord): boolean {
 }
 
 function complement(type: unknown): string {
-  return type === "handoff.sent" ? "handoff.received" : "handoff.sent";
+  return type === "agent.handoff.sent" ? "agent.handoff.received" : "agent.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.
+ * The candidates for a subject, chosen by who signed. The complementary type is
+ * required because an honest reply has exactly the shape of a mislabelled
+ * receipt; the declaration (evidence-bundle.md §5.4) covers that residual path.
  */
 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).
+  // Keys, never spellings of a key: the envelope side's case is unconstrained.
   const wanted = normalizedSigningKey(section(subject.record, "event").counterparty_public_key);
   if (wanted === null) return []; // the subject names no key
   const wantedType = complement(eventType(subject));
@@ -496,19 +318,9 @@ function candidatesFor(subject: HeldRecord, held: readonly HeldRecord[]): HeldRe
 }
 
 /**
- * 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.
+ * Order a candidate set by `case_id`, then `sequence`. Removes nothing: both
+ * fields are written by the audited party. The sort is total so the two kernels
+ * report one order.
  */
 function order(subject: HeldRecord, candidates: HeldRecord[]): HeldRecord[] {
   const wantedCase = namedCase(section(subject.record, "context"));
@@ -529,16 +341,8 @@ function order(subject: HeldRecord, candidates: HeldRecord[]): HeldRecord[] {
 }
 
 /**
- * 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).
+ * Which case a record names, for ordering only. Absent and `null` both mean no
+ * case, so Python's `None` and this kernel's `undefined` order identically.
  */
 function namedCase(context: Record<string, unknown>): unknown {
   const value = context.case_id;
@@ -546,11 +350,8 @@ function namedCase(context: Record<string, unknown>): unknown {
 }
 
 /**
- * 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.
+ * Whether two records name the same case, for ordering only. Two records naming
+ * no case match; a non-string names no case.
  */
 function isSameCase(left: unknown, right: unknown): boolean {
   if (left === null && right === null) return true;
@@ -561,13 +362,10 @@ function gradePair(
   subject: HeldRecord,
   counterpart: HeldRecord,
 ): { verdict: HandoffVerdict; checks: string[] } {
-  if (recordIsMalformed(subject) || recordIsMalformed(counterpart)) {
-    return { verdict: "malformed", checks: [] };
-  }
+  const defects = [recordDefect(subject), recordDefect(counterpart)];
+  if (defects.includes("malformed")) return { verdict: DEFECT_VERDICT.malformed, checks: [] };
+  if (defects.includes("nonconforming")) return { verdict: DEFECT_VERDICT.nonconforming, 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");
@@ -575,36 +373,24 @@ function gradePair(
   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`.
+  // Each record must name the other's signer, compared as a key against the
+  // envelope key the other was signed with. Candidacy alone reads only what the
+  // subject names.
   const [sent, received] =
-    eventType(subject) === "handoff.sent" ? [subject, counterpart] : [counterpart, subject];
+    eventType(subject) === "agent.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.
+ * Read one record against everything the reader holds. The scope test lives
+ * here, not in `readHandoffs`, so the two entry points cannot disagree.
  */
 export function readHandoff(subject: HeldRecord, held: readonly HeldRecord[]): HandoffReading {
   if (!isHandoffNamespace(subject)) {
@@ -617,12 +403,13 @@ export function readHandoff(subject: HeldRecord, held: readonly HeldRecord[]): H
       candidateReadings: [],
     };
   }
-  if (recordIsMalformed(subject)) {
+  const defect = recordDefect(subject);
+  if (defect !== null) {
     return {
       ref: subject.ref,
-      verdict: "malformed",
+      verdict: DEFECT_VERDICT[defect],
       failedChecks: [],
-      findings: ["malformed_record"],
+      findings: [`${defect}_record`],
       candidates: [],
       candidateReadings: [],
     };
@@ -640,21 +427,18 @@ export function readHandoff(subject: HeldRecord, held: readonly HeldRecord[]): H
     };
   }
 
-  // EVERY candidate is graded. Ordering above chose where each one is reported
-  // and took none of them out of this list.
+  // Every candidate is graded; ordering only chose where each is reported.
   const graded: CandidateReading[] = candidates.map((candidate) => {
     const { verdict, checks } = gradePair(subject, candidate);
-    const by = verdict === "failed" ? accountedFor(subject, candidate, held) : null;
+    // Only a pair that failed a check can be another exchange's record.
+    const by =
+      verdict === "failed" && checks.length > 0 ? accountedFor(subject, candidate, held) : null;
     return { ref: candidate.ref, verdict, failedChecks: checks, accountedFor: by };
   });
 
-  // The verdict, the failed checks and the ambiguity are taken over the
-  // candidates nothing accounts for. The others stay in the report.
   const live = graded.filter((g) => g.accountedFor === null);
   if (live.length === 0) {
-    // Every candidate is another exchange's record, each proven so by a
-    // verified pair with a record the subject's own key signed: an absence,
-    // reported with the candidates it looked at.
+    // Every candidate belongs to another exchange: an absence.
     return {
       ref: subject.ref,
       verdict: null,
@@ -664,23 +448,18 @@ export function readHandoff(subject: HeldRecord, held: readonly HeldRecord[]): H
       candidateReadings: graded,
     };
   }
-  const worst = Math.max(...live.map((g) => VERDICT_RANK[g.verdict]));
-  const verdict = (Object.keys(VERDICT_RANK).find(
-    (name) => VERDICT_RANK[name] === worst,
-  ) as HandoffVerdict)!;
-
-  // Over every live 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 worst = Math.max(...live.map((g) => rank(g.verdict, g.failedChecks)));
+  const verdict: HandoffVerdict = (["verified", "failed", "failed", "incomplete"] as const)[worst]!;
+
+  // Over every live candidate: `malformed` outranks `failed`, and one junk
+  // record must not strip a named failure from the report.
   const failed = new Set<string>();
   for (const g of live) 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 (live.length > 1) findings.push("counterpart_ambiguous");
-  if (verdict === "malformed") findings.push("malformed_record");
+  if (worst === 3) findings.push("malformed_record");
+  else if (worst === 1) findings.push("nonconforming_record");
 
   return {
     ref: subject.ref,
@@ -693,23 +472,18 @@ export function readHandoff(subject: HeldRecord, held: readonly HeldRecord[]): H
 }
 
 /**
- * The ref of the record that accounts for a FAILED candidate, or `null` (4.1
- * v1.17, A20). The candidate is another exchange's record, and not a deviation
- * on this one, only where the reader holds a record `o`, other than the
- * subject, for which all four hold:
+ * The ref of the record that accounts for a failed candidate, or `null`. That
+ * is a record `o`, other than the subject, where:
  *
- *   1. `o` is signed by the SUBJECT's own key, and is the subject's type;
+ *   1. `o` is signed by the subject's key and is the subject's type;
  *   2. `o` names the candidate's signer, and the candidate names the subject's
  *      key back;
  *   3. `o`'s `sequence` differs from the subject's;
  *   4. the candidate grades `verified` against `o`.
  *
- * Condition 1 is what the audited party cannot supply: a verified pair needs
- * the OTHER side's signature over the digest and the number. Condition 3 is
- * the position guard (proof#129): a second record at the subject's own number
- * is a second claim about the subject's message. The first `o` in the order
- * the records are held is reported, so two kernels name one record. The
- * Python half, `_accounted_for`, carries the full reasoning.
+ * Condition 1 is what the audited party cannot supply: a verified pair needs the
+ * other side's signature. Condition 3 stops a second claim about the subject's
+ * own message. The first `o` in held order wins, so both kernels name one record.
  */
 function accountedFor(
   subject: HeldRecord,
@@ -718,68 +492,42 @@ function accountedFor(
 ): string | null {
   const own = normalizedSigningKey(subject.publicKey);
   const theirs = normalizedSigningKey(candidate.publicKey);
-  // Condition 2: the candidate names the subject's key back.
+  // Condition 2, the candidate's half.
   if (normalizedSigningKey(section(candidate.record, "event").counterparty_public_key) !== own) {
     return null;
   }
   const subjectSequence = section(subject.record, "event").sequence;
   for (const other of held) {
     if (other === subject) continue;
-    // Condition 1: signed by the subject's own key, of the subject's own type.
+    // Condition 1.
     if (normalizedSigningKey(other.publicKey) !== own) continue;
     if (eventType(other) !== eventType(subject)) continue;
-    // Condition 2: o names the candidate's signer.
+    // Condition 2, o's half.
     if (normalizedSigningKey(section(other.record, "event").counterparty_public_key) !== theirs) {
       continue;
     }
-    // Condition 3: another position than the subject's.
+    // Condition 3.
     if (sameNumber(section(other.record, "event").sequence, subjectSequence)) continue;
-    // Condition 4: a verified pair.
+    // Condition 4.
     if (gradePair(other, candidate).verdict === "verified") return other.ref;
   }
   return null;
 }
 
 /**
- * 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.
+ * Read every held record, in the order given. Nothing is filtered: a record
+ * outside the hand-off namespace reads `NOT_A_HANDOFF_FINDING`, so a mixed pile
+ * produces a line per record.
  */
 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).
+ * Whether a record is a conformant hand-off: in the namespace, with no
+ * defect. `./declaration.ts` uses it for evidence-bundle.md section 5.4, so a record
+ * cannot be unreadable here and usable at the pack layer.
  */
 export function isConformantHandoffRecord(held: HeldRecord): boolean {
-  return isHandoffNamespace(held) && !recordIsMalformed(held);
+  return isHandoffNamespace(held) && recordDefect(held) === null;
 }