@sanning/proof 0.11.0 → 0.12.0

package/dist/handoff.d.ts

@@ -126,6 +126,16 @@ 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.
+     */
+    accountedFor?: string | null;
 }
 export interface HandoffReading {
     ref: string;
@@ -135,7 +145,12 @@ export interface HandoffReading {
     findings: string[];
     /** Ordered, never filtered. */
     candidates: string[];
-    /** One entry per candidate, in the same order, and nothing left out of it. */
+    /**
+     * 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.
+     */
     candidateReadings: CandidateReading[];
 }
 /**

package/dist/handoff.js

@@ -1,4 +1,4 @@
-// The hand-off pairing rule of specs/envelope-spec.md §4.1 (v1.9).
+// The hand-off pairing rule of specs/envelope-spec.md §4.1 (v1.17).
 //
 // 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
@@ -40,6 +40,9 @@
 //     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
@@ -116,14 +119,23 @@
 // `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.
+// 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"];
 /**
@@ -144,7 +156,7 @@ 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 CHECK_ORDER = ["message_hash", "sequence", "self_handoff", "counterparty_named"];
 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
@@ -478,6 +490,22 @@ function gradePair(subject, counterpart) {
         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] };
 }
@@ -527,21 +555,39 @@ export function readHandoff(subject, held) {
     // 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 by = verdict === "failed" ? accountedFor(subject, candidate, held) : null;
+        return { ref: candidate.ref, verdict, failedChecks: checks, accountedFor: by };
     });
-    const worst = Math.max(...graded.map((g) => VERDICT_RANK[g.verdict]));
+    // 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.
+        return {
+            ref: subject.ref,
+            verdict: null,
+            failedChecks: [],
+            findings: ["counterpart_absent"],
+            candidates: candidates.map((c) => c.ref),
+            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);
-    // 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).
+    // 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 failed = new Set();
-    for (const g of graded)
+    for (const g of live)
         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)
+    if (live.length > 1)
         findings.push("counterpart_ambiguous");
     if (verdict === "malformed")
         findings.push("malformed_record");
@@ -554,6 +600,54 @@ export function readHandoff(subject, held) {
         candidateReadings: graded,
     };
 }
+/**
+ * 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:
+ *
+ *   1. `o` is signed by the SUBJECT's own 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.
+ */
+function accountedFor(subject, candidate, held) {
+    const own = normalizedSigningKey(subject.publicKey);
+    const theirs = normalizedSigningKey(candidate.publicKey);
+    // Condition 2: the candidate names the subject's key back.
+    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.
+        if (normalizedSigningKey(other.publicKey) !== own)
+            continue;
+        if (eventType(other) !== eventType(subject))
+            continue;
+        // Condition 2: o names the candidate's signer.
+        if (normalizedSigningKey(section(other.record, "event").counterparty_public_key) !== theirs) {
+            continue;
+        }
+        // Condition 3: another position than the subject's.
+        if (sameNumber(section(other.record, "event").sequence, subjectSequence))
+            continue;
+        // Condition 4: a verified pair.
+        if (gradePair(other, candidate).verdict === "verified")
+            return other.ref;
+    }
+    return null;
+}
 /**
  * EVERY record the reader holds gets a reading, in the order given.
  *

package/dist/index.js

@@ -77,7 +77,8 @@ export { DECLARATION_VERSION, checkDeclaration, declarationClaims, packRecords,
 // because the omission happens before any reader runs. Reading several parties'
 // packs at once is what closes it: a `handoff.sent` with no counterpart is
 // always named, and where a pack signed by the key it names is in the case, the
-// reading says that pack holds no counterpart. Whether a party that presented
+// reading says that pack holds no counterpart (unless every candidate was
+// accounted for under A20, which reads as no counterpart and names no pack). Whether a party that presented
 // no such pack recorded anything is not established (proof#143). `readCase`
 // verifies every pack itself, offline, so it is async. Matching is on keys and hashes alone and NEVER on tenancy, so a pair from two
 // organizations verifies (DL-60).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanning/proof",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "TypeScript kernel of the Sanning verification stack: RFC 8785 (JCS) canonicalization, SHA-256, and Ed25519 verification for Verifiable Event Envelopes. Full-family verifier (inline + external commitment); accepts sanning.agent/v1 and sanning.events/v2. Conformance-gated byte-for-byte against the test-vectors corpus.",
   "license": "MIT",
   "type": "module",

package/src/case.ts

@@ -185,7 +185,8 @@
  *    (F2).
  * 10. **`counterpart_absent`** (`continue`). Skips the ambiguity and pair
  *     reporting, and there is nothing to skip: 4.1 emits that finding only
- *     for an EMPTY candidate list. Which of the three counterpart kinds it
+ *     where no candidate is left to read, an EMPTY candidate list or one whose
+ *     every candidate another record accounts for (4.1 v1.17, A20). Which of the three counterpart kinds it
  *     gets reads the keys of the packs that verified, counted before exit 4,
  *     and whether any pack took exit 2 or 3.
  *
@@ -225,16 +226,16 @@
  *   with that verdict and its reasons, so the case never reads above its
  *   weakest pack. On-chain re-fetch and `gradePack` are a caller's to run.
  *
- * THE COST OF 4.1's "GRADE EVERY CANDIDATE", INHERITED HERE AND STATED RATHER
- * THAN LEFT TO BE FOUND (proof#134, ratified by Phil 2026-09-22). A reader
- * whose pile holds two or more records of the complementary type signed by one
- * counterparty key cannot reach `verified`: the other exchanges' records are
- * candidates too, they commit to other messages, and they fail. One agent
- * sending two messages to the same counterparty inside one case lands there,
- * and it surfaces as `COUNTERPART_AMBIGUOUS` beside the failure. An
- * alternating exchange (A sends, B replies) does NOT, because a reply is
- * signed by the other key and is the other type. Narrowing that here with
- * `handoffs[]` is precisely the move that would reopen proof#137's door.
+ * THE COST OF 4.1's "GRADE EVERY CANDIDATE", AND WHAT IS LEFT OF IT (4.1
+ * v1.17, amendment A20, which reopens proof#134). Up to v1.16 a pile holding
+ * two or more records of the complementary type signed by one counterparty key
+ * could not reach `verified`. 4.1 now sets such a candidate aside where a
+ * record the subject's own key signed pairs with it verified at another
+ * sequence, so two messages in one direction, and the demo's A to B, B to A,
+ * A to B, read clean. What is left surfaces as `COUNTERPART_AMBIGUOUS` beside
+ * the failure: fan-in, fan-out, and the same pair in two cases at the same
+ * sequence. Narrowing any of it here with `handoffs[]` is precisely the move
+ * that would reopen proof#137's door.
  */
 
 import {
@@ -335,7 +336,9 @@ export const CASE_QUARANTINED_PROFILES = ["sanning.mlflow/v1"] as const;
 /**
  * A conformant hand-off record with no counterpart among the records this
  * reader read, where every pack in the case verified under a key this reader
- * can read and NO pack in the case is signed by the key the record names.
+ * can read and NO pack in the case is signed by the key the record names,
+ * or where every candidate it had was accounted for by another record under
+ * A20 (the exception then carries `count`, and names no pack).
  * **An exception, never a failure** (anchor#198, criterion 3).
  *
  * That is ALL it says. It does not say the counterparty's account is absent,
@@ -425,9 +428,11 @@ export const COUNTERPART_ABSENT_FROM_COUNTERPARTY_RECORDS =
 export const COUNTERPART_ABSENT_SIGNER_UNKNOWN = "counterpart_absent_signer_unknown";
 
 /**
- * More than one candidate counterpart (4.1, and proof#134's stated cost). The
- * reading is the worst of them and the ambiguity is named: a reader permitted
- * to take one match can be handed an honest decoy beside a tampered record.
+ * More than one candidate counterpart that nothing accounts for (4.1 v1.17,
+ * A20). The reading is the worst of them and the ambiguity is named: a reader
+ * permitted to take one match can be handed an honest decoy beside a tampered
+ * record. `count` is how many of the candidates are live, which is the number
+ * the ambiguity is about.
  */
 export const COUNTERPART_AMBIGUOUS = "counterpart_ambiguous";
 
@@ -793,7 +798,11 @@ export interface CaseException {
   counterpartyKey?: string | null;
   /** Which checks a formed pair failed, in 4.1's fixed order. */
   failedChecks?: string[];
-  /** How many of a thing the exception is about, where it is about a count. */
+  /**
+   * How many of a thing the exception is about, where it is about a count. On
+   * `COUNTERPART_ABSENT` it is set only where 4.1 set every candidate aside
+   * (v1.17, A20), and it is how many were set aside.
+   */
   count?: number;
   /** The pack's own bundle verdict, for `PACK_BUNDLE_NOT_VERIFIED`. */
   status?: CaseVerdict;
@@ -1343,13 +1352,34 @@ export async function readCase(
       // that party's pack. Where some pack could not be tied to a key, "no
       // pack is signed by the named key" is not established and the reading
       // says it could not tell.
+      //
+      // EXCEPT where 4.1 set every candidate aside (v1.17, A20). There the
+      // absence is a finding about the candidates the reader DID read, each
+      // paired `verified` with another record the subject's own signer made,
+      // and not a finding about any pack. 4.1 and evidence-bundle A16 name the
+      // neutral kind for it, and the damning one would put the audited party's
+      // own unfaithful record on the counterparty's pack as a statement
+      // against it. `count` is how many candidates were set aside, which is
+      // also what tells the rendered sentence which absence this is.
+      const graded = reading.candidateReadings;
+      const setAside =
+        graded.length > 0 && graded.every((c) => c.accountedFor !== null)
+          ? graded.length
+          : 0;
       const kind =
-        named !== null && holderKeys.has(named)
-          ? COUNTERPART_ABSENT_FROM_COUNTERPARTY_RECORDS
-          : unattributed > 0
-            ? COUNTERPART_ABSENT_SIGNER_UNKNOWN
-            : COUNTERPART_ABSENT;
-      note(kind, { packRef, eventId, counterpartyKey: named });
+        setAside > 0
+          ? COUNTERPART_ABSENT
+          : named !== null && holderKeys.has(named)
+            ? COUNTERPART_ABSENT_FROM_COUNTERPARTY_RECORDS
+            : unattributed > 0
+              ? COUNTERPART_ABSENT_SIGNER_UNKNOWN
+              : COUNTERPART_ABSENT;
+      note(
+        kind,
+        setAside > 0
+          ? { packRef, eventId, counterpartyKey: named, count: setAside }
+          : { packRef, eventId, counterpartyKey: named },
+      );
       continue;
     }
 
@@ -1357,7 +1387,7 @@ export async function readCase(
       note(COUNTERPART_AMBIGUOUS, {
         packRef,
         eventId,
-        count: reading.candidates.length,
+        count: reading.candidateReadings.filter((c) => c.accountedFor === null).length,
       });
     }
     // ON `failedChecks` AND NOT ON THE VERDICT WORD. 4.1 keeps the UNION of
@@ -1406,6 +1436,17 @@ export function renderException(exception: CaseException): string {
   const where = `${exception.packRef}/${exception.eventId}`;
   switch (exception.kind) {
     case COUNTERPART_ABSENT:
+      if (exception.count) {
+        const which =
+          exception.count === 1
+            ? "its one candidate counterpart pairs"
+            : `each of its ${exception.count} candidate counterparts pairs`;
+        return (
+          `${where} has no counterpart among the records this verifier read: ` +
+          `${which} verified with another record signed by the key that ` +
+          "signed this one, at a different sequence, and is set aside"
+        );
+      }
       return (
         `${where} has no counterpart among the records this verifier read, ` +
         "and no pack in this case is signed by the key it names"
@@ -1523,7 +1564,7 @@ export function renderException(exception: CaseException): string {
     case RECORD_PROFILE_QUARANTINED:
       return (
         `${where} is signed under a profile this case reader does not read ` +
-        "while its admission is undecided (DL-63), so what it says is UNKNOWN"
+        "while its admission is undecided, so what it says is UNKNOWN"
       );
     case CASE_HOLDS_NO_PACKS:
       return "this case holds no packs";