@sanning/proof 0.11.0 → 0.12.0

package/README.md

@@ -163,6 +163,28 @@ Every event also appears in `result.events`, in body order, with a status that n
 
 Bytes come back as `Uint8Array`, never a string: the spec commits to **raw bytes**, and a UTF-8 decode is lossy for any payload that is not valid UTF-8, re-encoding such a string would change the bytes and break the hash. Decode to text yourself if you know your payload is text.
 
+## Check a case: several packs, one verdict
+
+When a case spans more than one pack (two agents, two organizations, one hand-off between them), check the packs together. This is `readCase` from a terminal, with no page in the way:
+
+```bash
+npx @sanning/proof case assessor-pack/ challenger-pack/
+unzip decision-file.zip -d case/ && npx @sanning/proof case case/   # a decision file
+npx @sanning/proof case case/ --json            # the full reading, for a script
+```
+
+Each argument is a folder: one pack (`bundle.json` plus `logs/`), or a folder that holds several packs, such as an unpacked decision file. `case` does not open archives: given a `.zip`, it exits `2` and says to unzip it first and pass the folder. Packs are found by the verify page's splitting rule, so the page and this command apply the same rule to the same unpacked tree: every `bundle.json` is a pack, a file belongs to the deepest pack whose `bundle.json` or `logs/` it sits in, and every other file is listed as outside every pack and never opened. A `.zip` inside the folder is a file like any other. Several folders are read as one folder holding them, each under its own name. Each `bundle.json` is read with `verify`'s own reader (`readBundleBytes`), so the two commands classify one bundle the same way.
+
+The walk is bounded and follows no link. A symbolic link is never followed: it is listed as outside every pack and not read, even under a pack's `logs/`, and a link named on the command line exits `2`. A folder nested more than 32 levels deep, more than 50,000 files and folders in all, or a name that is not valid UTF-8 exits `2`; a bad name is refused rather than escaped, because two different names would then read as one. A `bundle.json` nested more than 512 levels deep exits `2`, from `case` and from `verify` alike. The rules are pinned for both kernels by `vectors/case-split.json`, shipped in this tarball, as directory trees.
+
+Known differences from the verify page: the page opens a dropped `.zip`; the page drops a leading byte-order mark from `bundle.json`, which `verify`'s reader refuses; the page reads whatever the browser hands it for a link, a bad name or a very deep tree; and the page loses a record named `__proto__`, which this command keeps.
+
+The first line is the case verdict, then the kernel's summary and every exception through `renderException`, then the packs, the files outside them, and the on-chain half. Exit codes: `0` verified · `1` failed · `2` malformed, usage, an input that cannot be read as a case, or an unexpected error in the command · `3` incomplete or partial · `4` mixed (more than one outcome: read the exceptions). `verify` never exits `4`.
+
+A case reading establishes that every pack verified offline, that every record every pack supplied was read in one pile under envelope-spec §4.1's hand-off rules, and that a hand-off record with no counterpart is always named. It does **not** establish that the case is complete, that a party which presented no pack under the named key recorded nothing, that two organizations are independent, or that any witness was re-fetched on chain: the output says `on-chain NOT CHECKED` unless you pass `--gateways <url,url>`. With gateways, each pack's witnesses are re-fetched pack by pack and reported beside the reading, which they never change; a witness that does not match exits `1`, and an on-chain half that could not be settled turns `0` into `3`.
+
+The Python kernel ships the same command as `sanning-proof case`, and `cross-kernel/run_case_cli.sh` requires the two to print the same bytes, the same `--json` and the same exit code over every `case/` corpus vector and every tree in `vectors/case-split.json`.
+
 ## Verify a Merkle inclusion proof
 
 Agents close daily checkpoints over per-cycle leaves (RFC 9162, §2.1 domain separation, not the Bitcoin duplicate-leaf variant). Verify a leaf's inclusion against an anchored root:

package/dist/case.d.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 type { SideContentMap } from "./side-content.js";
 /**
@@ -281,7 +282,9 @@ export declare const CASE_QUARANTINED_PROFILES: readonly ["sanning.mlflow/v1"];
 /**
  * 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,
@@ -367,9 +370,11 @@ export declare const COUNTERPART_ABSENT_FROM_COUNTERPARTY_RECORDS = "counterpart
  */
 export declare 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 declare const COUNTERPART_AMBIGUOUS = "counterpart_ambiguous";
 /**
@@ -636,7 +641,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;

package/dist/case.js

@@ -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 { checkDeclaration, declarationClaims, packRecords, } from "./declaration.js";
 import { NOT_A_HANDOFF_FINDING, normalizedSigningKey, readHandoffs, recordIsMalformed, } from "./handoff.js";
@@ -309,7 +310,9 @@ export const CASE_QUARANTINED_PROFILES = ["sanning.mlflow/v1"];
 /**
  * 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,
@@ -395,9 +398,11 @@ export const COUNTERPART_ABSENT_FROM_COUNTERPARTY_RECORDS = "counterpart_absent_
  */
 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";
 /**
@@ -1135,19 +1140,36 @@ export async function readCase(packs) {
             // 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.
-            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 });
+            //
+            // 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 = 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;
         }
         if (reading.findings.includes(COUNTERPART_AMBIGUOUS)) {
             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
@@ -1192,6 +1214,14 @@ export function renderException(exception) {
     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");
         case COUNTERPART_ABSENT_FROM_COUNTERPARTY_RECORDS:
@@ -1276,7 +1306,7 @@ export function renderException(exception) {
                 because(exception.reasons));
         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";
         case CASE_HOLDS_NO_HANDOFF_RECORDS:

package/dist/cli.d.ts

@@ -5,4 +5,102 @@ interface Cli {
     fetchImpl?: typeof fetch;
 }
 export declare function runCli(argv: string[], io: Cli): Promise<number>;
+/** The error text for an input with no pack in it, word for word the page's. */
+export declare const NO_BUNDLE = "No bundle.json found. An evidence pack contains bundle.json plus logs/.";
+/** A directory nested deeper than this below an argument refuses the input. */
+export declare const MAX_WALK_DEPTH = 32;
+/** More names than this, across every argument, refuse the input. */
+export declare const MAX_WALK_ENTRIES = 50000;
+/**
+ * `bundle.json` nested deeper than this is refused before it is parsed, by
+ * `verify` and by `case` alike (see `readBundleBytes`).
+ */
+export declare const MAX_JSON_DEPTH = 512;
+/**
+ * The input could not be read as a case. The message is the whole report,
+ * identical in both kernels, and the command exits 2 on it. `hint` is an
+ * optional second line naming a way through.
+ */
+export declare class CaseInputError extends Error {
+    readonly hint: string | null;
+    constructor(message: string, hint?: string | null);
+}
+/**
+ * `bundle.json` bytes that `readBundleBytes` will not read. `tooDeep` separates
+ * the one refusal that is not a parse error; `detail` is the parser's own words,
+ * which differ by kernel and are printed by `verify` only.
+ */
+export declare class BundleReadError extends Error {
+    readonly tooDeep: boolean;
+    readonly detail: string;
+    constructor(tooDeep: boolean, detail: string);
+}
+/**
+ * How both `verify` and `case` turn `bundle.json` bytes into JSON, in both
+ * kernels (`read_bundle_bytes` in the Python twin). UTF-8 with each ill-formed
+ * sequence read as U+FFFD, and a byte-order mark kept; then nesting deeper than
+ * MAX_JSON_DEPTH is refused before any parser walks into it; then `JSON.parse`.
+ * Throws `BundleReadError`.
+ */
+export declare function readBundleBytes(bytes: Uint8Array): unknown;
+export interface SplitPack {
+    ref: string;
+    bundlePath: string;
+    bundleBytes: Uint8Array;
+    /**
+     * `logs/<event_id>.json` bytes by event id. A `Map` and not an object: an
+     * event id is written by the audited party, and `obj["__proto__"] = bytes`
+     * replaces the prototype instead of storing the disclosure.
+     */
+    content: Map<string, Uint8Array>;
+    unaccounted: string[];
+}
+export interface SplitCase {
+    packs: SplitPack[];
+    /** Paths that belong to no pack, sorted. Never opened. */
+    outside: string[];
+    /** The part of `outside` that is not a regular file. Never followed, never opened. */
+    notRegular: string[];
+}
+/** One name the walk found that is not a directory. */
+export interface TreeEntry {
+    fsPath: string;
+    /** `true` for a regular file; `false` for a link or anything else. */
+    regular: boolean;
+}
+/**
+ * The page's `splitCase` followed by its `assemble` per pack, over the walk's
+ * tree. `read` opens a file; it is called for the files a pack owns and for
+ * nothing else.
+ */
+export declare function splitCase(tree: Map<string, TreeEntry>, read: (entry: TreeEntry, key: string) => Promise<Uint8Array>): Promise<SplitCase>;
+/** `verify`'s reader, with the refusal named by the pack's path. */
+export declare function loadBundle(pack: SplitPack): unknown;
+/**
+ * A regular file's bytes. Opened without following a link and without
+ * blocking, then checked again, so a file swapped for a link or a pipe after
+ * the walk listed it is refused rather than followed or waited on.
+ */
+export declare function readFileEntry(entry: TreeEntry, key: string): Promise<Uint8Array>;
+/**
+ * Every name under the directories named, keyed `<name>/<path inside>`. Each
+ * argument must be a directory, and not a link to one. A `.zip` is refused
+ * with the way through.
+ */
+export declare function treeFromArguments(paths: readonly string[]): Promise<Map<string, TreeEntry>>;
+export declare const CASE_EXIT_CODES: Readonly<Record<string, number>>;
+export declare const CASE_USAGE = "sanning-proof case -- one verdict over several evidence packs, offline\n\n  sanning-proof case <folder>... [--gateways <url,url>] [--json]\n\n  <folder>    a pack folder (bundle.json plus logs/), or a folder that holds\n              several packs, such as an unpacked decision file. case reads\n              folders only: given a .zip, it exits 2 and says to unzip it\n              first (for example, unzip file.zip -d case/) and pass the folder.\n              Packs are found by the verify page's splitting rule: every\n              bundle.json is a pack, a file belongs to the deepest pack whose\n              bundle.json or logs/ it sits in, and every other file is listed\n              as outside every pack and never opened. A .zip inside a folder is\n              a file like any other. A symbolic link is never followed: it is\n              listed as outside and not read, even under a pack's logs/.\n              Several folders are read as one folder holding them, each under\n              its own name. A folder nested more than 32 levels deep, more than\n              50000 files and folders in all, or a name that is not valid UTF-8\n              exits 2.\n  --gateways  comma-separated gateway URLs. Each pack's witnesses are then\n              re-fetched on chain, pack by pack, and reported beside the case\n              reading. Without it the on-chain half is NOT checked, and the\n              output says so.\n  --json      the full reading as JSON: the verdict, every exception with its\n              rendered line, every record, every contribution, the packs, the\n              files outside them, and the on-chain half.\n\nEach pack's bundle.json is read as verify reads it, so the two commands\nclassify one bundle the same way.\n\nWhat a case reading establishes: every pack is verified offline by this\nkernel; every record every pack supplied is read, in one pile, under the\nhand-off rules of envelope-spec section 4.1; a hand-off record with no\ncounterpart among the case's records is always named, and when a pack signed by\nthe key it names is in the case, the reading says that pack holds none, unless\nevery candidate it had was accounted for by another record (A20), which reads\nas no counterpart and names no pack.\n\nWhat it does not establish: that the case is complete (a party can decline to\nhand over a pack); that a party which presented no pack under the named key\nrecorded nothing; that two organizations are independent of each other; or\nthat any witness was re-fetched on chain, which the reading never does.\n\nExit codes: 0 verified \u00B7 1 failed \u00B7 2 malformed, usage, an input that cannot\nbe read as a case, or an unexpected error in this command \u00B7 3 incomplete or\npartial (undetermined, not failed) \u00B7 4 mixed (more than one outcome: read the\nexceptions). With --gateways, a witness that does not match on chain exits 1,\nand an on-chain half that could not be settled turns 0 into 3.";
+/**
+ * The case verdict's code, moved only by an on-chain half that was asked for:
+ * a witness that does not match is a failure whatever the reading said, and an
+ * on-chain half that could not be settled is never a clean 0.
+ */
+export declare function caseExitCode(verdict: string, onChainVerdict: string): number;
+/**
+ * `proof case <folder>... [--gateways <urls>] [--json]`. Every path out of the
+ * command is an exit code from the table: an exception nobody expected exits 2,
+ * never 1, because 1 would name the evidence failed over a defect in this
+ * command.
+ */
+export declare function runCase(argv: readonly string[], io: Cli): Promise<number>;
 export {};