@sanning/proof 0.19.1 → 0.20.0

package/dist/handoff.d.ts

@@ -1,50 +1,28 @@
-export declare const CANDIDATE_NAMESPACE = "handoff.";
-export declare const DEFINED_EVENT_TYPES: readonly ["handoff.sent", "handoff.received"];
+export declare const CANDIDATE_NAMESPACE = "agent.handoff.";
+export declare const DEFINED_EVENT_TYPES: readonly ["agent.handoff.sent", "agent.handoff.received"];
 /**
- * The finding a record that is not a hand-off record at all reads with.
- *
- * A FINDING and not a verdict: the ratified verdict words are closed
- * (anchor#188) and this reading names an outcome beside one, exactly as
- * `counterpart_absent`, `counterpart_ambiguous` and `malformed_record` do. It
- * exists because 4.1 had a SILENT branch, and a rule with a silent branch is a
- * rule the party being audited steers into (proof#136). A record TRYING to be
- * a hand-off and getting it wrong reads `malformed`; a record that is not a
- * hand-off at all reads this. Both are readings. Neither is silence.
+ * 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 declare const NOT_A_HANDOFF_FINDING = "not_a_handoff_record";
 /**
- * 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 declare 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 declare function sameSigningKey(left: unknown, right: unknown): boolean;
-export type HandoffVerdict = "verified" | "failed" | "malformed";
+export type HandoffVerdict = "verified" | "failed" | "incomplete";
 export interface HandoffRecord {
     event_type?: unknown;
     event?: unknown;
@@ -53,87 +31,49 @@ export interface HandoffRecord {
     [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.
+ * 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 declare 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;
 }
@@ -146,79 +86,41 @@ 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[];
 }
 /**
- * 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 declare function recordDefect(held: HeldRecord): "malformed" | "nonconforming" | null;
+/** `recordDefect` is `malformed`. */
 export declare function recordIsMalformed(held: HeldRecord): boolean;
+/** `recordDefect` is `nonconforming`. */
+export declare function recordIsNonconforming(held: HeldRecord): boolean;
 /**
- * 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 declare function readHandoff(subject: HeldRecord, held: readonly HeldRecord[]): HandoffReading;
 /**
- * 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 declare function readHandoffs(held: readonly HeldRecord[]): HandoffReading[];
 /**
- * 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 declare function isConformantHandoffRecord(held: HeldRecord): boolean;