@sanning/proof 0.10.0 → 0.11.0

package/dist/chain.js

@@ -54,6 +54,7 @@
 // against `anchor`); when it lands, the namespace table below stops mattering
 // and can go.
 import { hexToBytes, sha256Hex } from "./crypto.js";
+import { jcsParse } from "./verifier.js";
 import { resolveTraceEvents } from "./evidence.js";
 /**
  * The one sentence a surface should print beside these findings, so the reader
@@ -109,7 +110,25 @@ function decodeRecord(hex) {
         return null;
     try {
         const bytes = hexToBytes(hex);
-        const record = JSON.parse(new TextDecoder().decode(bytes));
+        // PINNED STRICT via `jcsParse`, and the twin at
+        // `src/sanning_proof/chain.py` is `jcs_loads` (proof#149). This was the
+        // LAST lenient decode pair in either kernel, and it was lenient on BOTH
+        // sides in different directions, so it agreed nowhere while looking like
+        // it agreed everywhere:
+        //
+        //   * A bare `new TextDecoder()` here eats a leading byte-order mark and
+        //     substitutes U+FFFD for every invalid sequence, so `BOM + JCS(r)`, a
+        //     raw `0x80`, a CESU-8 surrogate pair and a truncated UTF-8 sequence
+        //     each joined a chain HERE and joined none there.
+        //   * Python's `json.loads` accepted `NaN`, `Infinity` and `-Infinity`,
+        //     which RFC 8785 cannot emit and this kernel's `JSON.parse` rejects,
+        //     so a record carrying one joined a chain THERE and none here.
+        //
+        // Five split readings on one pair, in two directions, and no test in
+        // either kernel could see them: each kernel agreed with itself. That is
+        // why agreement between two lenient readers is not evidence of anything,
+        // and why the comparison has to run on the same bytes.
+        const record = jcsParse(bytes);
         if (record === null || typeof record !== "object")
             return null;
         return { record, bytes };

package/dist/cli.js

@@ -11,9 +11,29 @@
 //   0  verified
 //   1  a real verification failure (bad signature / tamper / broken inclusion)
 //   2  malformed bundle (unparseable, unknown spec major, body_hash mismatch)
-//   3  gateway-unavailable when an on-chain re-fetch was requested
+//   3  UNDETERMINED: a gateway was unreachable when an on-chain re-fetch was
+//      requested, or the PACK is `incomplete` (see below)
+//
+// ── The headline is the PACK verdict, not the bundle status (proof#110) ──
+//
+// This command used to print `result.status` as its headline and map it to an
+// exit code directly. That is the verdict on the signed BUNDLE, and it is not
+// the verdict the rest of the product prints. `gradePack` in `./grading.ts` is
+// the kernel's one rule for what a verification SURFACE may claim about a pack,
+// the browser verify page calls it, and this command referenced it zero times.
+// So the same file read `Incomplete` on the page and `VERIFIED`, exit 0, at the
+// terminal: two answers to one question, from one kernel, which is the exact
+// defect `grading.ts` was brought into the kernel to end.
+//
+// The two enums stay distinct, deliberately (`grading.ts` says so in its own
+// comments, and `evidence-bundle.md` §3 does not carry `incomplete`): the
+// BUNDLE status is still reported, unchanged, on its own line. What changed is
+// which of the two is the headline and which one the exit code follows.
+//
 // `payloadHashOk === null` (a withheld record) is semantics-undetermined and
-// surfaces as a per-event note — it does NOT fail the run.
+// surfaces as a per-event note, and it does NOT fail the run. It does hold the
+// PACK at `incomplete`, because a record nobody hashed is a record nobody
+// checked, and exit 3 is how this command says "undetermined".
 import { readFile, readdir, stat, writeFile } from "node:fs/promises";
 import { realpathSync } from "node:fs";
 import { join } from "node:path";
@@ -21,12 +41,16 @@ import { fileURLToPath } from "node:url";
 import { isAgentProofSpec, verifyAgentProofBundle } from "./agent-proof.js";
 import { CHAIN_READING_SCOPE, readChains, renderChainFinding } from "./chain.js";
 import { composeExport } from "./compose.js";
-import { utf8 } from "./crypto.js";
+import { isHexField, utf8 } from "./crypto.js";
 import { verifyEvidenceBundle } from "./evidence.js";
+import { checkDeclaration, renderDeclarationSummary, renderNote } from "./declaration.js";
+import { completenessNotes, gradePack, renderCause } from "./grading.js";
 const EXIT_VERIFIED = 0;
 const EXIT_FAILED = 1;
 const EXIT_MALFORMED = 2;
-const EXIT_GATEWAY_UNAVAILABLE = 3;
+// One code, two undetermined outcomes: a gateway we could not reach, and a pack
+// whose records nobody hashed. Neither is an accusation, and neither is a pass.
+const EXIT_UNDETERMINED = 3;
 const G = "\x1b[32m";
 const R = "\x1b[31m";
 const Y = "\x1b[33m";
@@ -153,8 +177,22 @@ export async function runCli(argv, io) {
     // evidence about the records in front of us, not a verdict: they are printed
     // and they never move `exit`, because a chain is not a completeness proof and
     // an exit code is exactly the kind of thing people read as one.
-    const chains = await readChains(parsed);
-    const exit = reportEvidence(result, bundlePath, gateways, io, chains);
+    //
+    // A READING THAT COULD NOT BE PRODUCED SAYS SO. This was an unguarded call:
+    // a throw out of `readChains` would have escaped the command entirely and
+    // exited 1, which is the code for "failed" and would have named the
+    // customer's evidence tampered over a fault in this reader. The Python twin
+    // had the opposite half of the same defect and swallowed the throw into "no
+    // event chain was found to follow in this bundle" (the gate on proof#154).
+    // Neither kernel is entitled to either answer, so both now print the third.
+    let chains;
+    try {
+        chains = await readChains(parsed);
+    }
+    catch (e) {
+        chains = { unreadable: errMsg(e) };
+    }
+    const exit = reportEvidence(result, bundlePath, gateways, io, chains, parsed, logs);
     // Coverage is reported only once the bundle parsed far enough to have events
     // to compare against; over a MALFORMED bundle there is nothing to say.
     if (logs && result.status !== "malformed")
@@ -552,12 +590,28 @@ function sample(names, max = 3) {
     return names.length > max ? `${shown}, +${names.length - max} more` : shown;
 }
 // The --logs MAP lane decides each disclosed value's encoding: a clean,
-// even-length, lowercase-hex string is hex bytes; anything else is utf8 text.
-// (The verifier itself only distinguishes "string ⇒ hex" from "Uint8Array ⇒
-// raw bytes" — the human-facing encoding choice is made here. The DIRECTORY
-// lane never reaches this: its bytes are already bytes.)
+// even-length hex string is hex bytes; anything else is utf8 text. (The
+// verifier itself only distinguishes "string ⇒ hex" from "Uint8Array ⇒ raw
+// bytes", so the human-facing encoding choice is made here. The DIRECTORY lane
+// never reaches this: its bytes are already bytes.)
+//
+// EITHER CASE, through the one charset rule (proof#146). This test was
+// `/^[0-9a-f]+$/`, lower case only, and it was the last copy of the hex rule
+// in either kernel that answered differently from the others: the Python CLI
+// passes every string to the kernel, and the kernel decodes it with the
+// case-open `hexToBytes` on BOTH sides. So a disclosure map written in
+// upper-case hex was read as 4 bytes of evidence there and as 8 bytes of TEXT
+// here, and this command told the auditor their genuine, correctly disclosed
+// evidence had FAILED: `proof verify --logs map.json` exited 3 in Python and
+// 1 here, on one pack and one map. Telling an auditor their evidence is forged
+// is the worst direction to be wrong in, which is the argument the Python
+// twin's own docstring already makes about this exact lane.
+//
+// Pinned by `cross-kernel/run_cli.sh`'s `logs/hex-map-upper`, beside the
+// lowercase lane that existed before and only ever exercised the one spelling
+// the two commands happened to agree on.
 function decodeLogValue(v) {
-    if (v.length > 0 && v.length % 2 === 0 && /^[0-9a-f]+$/.test(v))
+    if (v.length > 0 && v.length % 2 === 0 && isHexField(v, v.length))
         return v; // hex passthrough
     return utf8(v); // raw utf8 bytes
 }
@@ -591,9 +645,47 @@ function printUsage(io) {
     io.out("                    and takes precedence. An event with no disclosed");
     io.out("                    bytes is undetermined (~), never a failure.");
     io.out("");
-    io.out("Exit codes: 0 verified · 1 failed · 2 malformed · 3 gateway-unavailable");
+    io.out("The headline is the PACK verdict, the same one the verify page prints:");
+    io.out("a record nobody hashed leaves the pack INCOMPLETE even when the signed");
+    io.out("bundle itself is verified. Both verdicts are printed when they differ.");
+    io.out("");
+    io.out("Exit codes: 0 verified · 1 failed · 2 malformed · 3 undetermined");
+    io.out("            (an unreachable gateway, or an incomplete pack)");
+}
+/**
+ * The disclosure account this command can honestly make, from what the VERIFIER
+ * determined rather than from what the loader happened to read.
+ *
+ * `accountDisclosure` is offered by `grading.ts` as a convenience and is
+ * explicitly "NOT THE ONLY WAY TO BUILD AN ACCOUNT". It reads the side map
+ * only, and this command has a second disclosure lane the side map cannot see:
+ * `events[].content`, carried INSIDE the bundle and bound by the verifier
+ * without any `--logs` at all. Accounting off the side map would file every
+ * in-body disclosure as `missing` and print a shortfall the pack does not have,
+ * which is the shape of manufactured accusation `grading.ts` keeps warning
+ * about.
+ *
+ * So `present` is "the verifier reached a determination for this record's
+ * content" and `missing` is "it could not", which is the same tri-state that
+ * decides the verdict, so the causes printed can never contradict the headline.
+ * `extra` still comes from the side input, because bytes that bound to nothing
+ * are a fact about the pack that only the loader knows.
+ */
+function cliDisclosureAccount(result, logs) {
+    const expected = result.events.map((e) => e.eventId);
+    const known = new Set(expected);
+    return {
+        expected,
+        present: result.events.filter((e) => e.contentOk !== null).map((e) => e.eventId),
+        missing: result.events.filter((e) => e.contentOk === null).map((e) => e.eventId),
+        // The loader hard-stops (exit 2) on a file it selected and could not read,
+        // and NAMES everything it skipped as a note, so nothing reaches here as an
+        // unusable disclosure bound to a named record.
+        unreadable: [],
+        extra: (logs?.suppliedIds ?? []).filter((id) => !known.has(id)),
+    };
 }
-function reportEvidence(result, path, gateways, io, chains) {
+function reportEvidence(result, path, gateways, io, chains, parsed, logs) {
     if (result.status === "malformed") {
         io.err(paint("MALFORMED", R) + `  ${path}`);
         for (const e of result.errors)
@@ -669,16 +761,40 @@ function reportEvidence(result, path, gateways, io, chains) {
     if (result.export) {
         reportExport(result.export, io);
     }
+    // What the pack SAYS it holds, against what it does (evidence-bundle.md
+    // §5.4). A pack that deviates from its own declaration FAILS here and exits
+    // 1, which is the point: every other check in this command is a check on a
+    // record that is present, so a trimmed hand-over passes all of them.
+    //
+    // A pack with NO declaration exits exactly as it did before §5.4. The check
+    // answers `partial` and the line below says so in words, and pack grading
+    // keeps its own verdict: every pack built before §5.4 carries no
+    // declaration, and re-grading them all as undetermined would be a change to
+    // the pinned 0/1/2/3 contract rather than a new check. A pack that DOES
+    // carry a declaration this reader cannot read is a different case and exits
+    // 3: the holder chose that field, so UNKNOWN is the honest answer.
+    const declaration = checkDeclaration(parsed, logs?.content);
+    const grade = gradePack(result, cliDisclosureAccount(result, logs), completenessNotes(parsed), declaration);
     io.out("");
-    printRollup(result.status, result.assertedStatus, gateways, result.onChainChecked, io);
+    printRollup(grade.verdict, result.status, result.assertedStatus, gateways, result.onChainChecked, io);
+    io.out(paint(`  declaration: ${renderDeclarationSummary(declaration)}`, declaration.verdict === "failed" ? R : declaration.verdict === "verified" ? DIM : Y));
+    for (const n of declaration.notes)
+        io.out(paint(`  note: ${renderNote(n)}`, Y));
     for (const e of result.errors)
         io.out(paint(`  note: ${e}`, DIM));
-    const disclosed = result.events.filter((e) => e.contentOk !== null);
-    if (disclosed.length > 0) {
-        const verified = disclosed.filter((e) => e.contentOk === true).length;
-        io.out(paint(`  logs: ${verified}/${disclosed.length} disclosed verified`, DIM));
+    // Every reason the pack is not verified, in the kernel's own words. An
+    // `incomplete` with no cause is a surface saying "unknown" and unable to say
+    // why, which `grading.ts` calls out by name as a defect of its own.
+    for (const c of grade.causes)
+        io.out(paint(`  - ${renderCause(c, "the pack")}`, Y));
+    // The fraction describes the PACK, not the disclosure. It used to divide by
+    // the number of records that happened to disclose bytes, so a pack that
+    // disclosed two of three records printed `logs: 2/2`, a full score for a
+    // partial hand-over, and the one line a reader skims for exactly this.
+    if (result.events.length > 0) {
+        io.out(paint(`  logs: ${grade.recordsVerified}/${result.events.length} record(s) content-verified`, DIM));
     }
-    return mapStatusToExit(result.status, result.errors);
+    return mapGradeToExit(grade, result);
 }
 /**
  * The chain block: what following each record's pointer to the record before it
@@ -700,6 +816,13 @@ function reportEvidence(result, path, gateways, io, chains) {
  *    decision this check is entitled to make.
  */
 function reportChains(reading, io) {
+    if ("unreadable" in reading) {
+        io.out("");
+        io.out(paint(`  Event chains  this kernel could not read the event chains in this bundle ` +
+            `(${reading.unreadable}), so the chain evidence is UNKNOWN here. That is not ` +
+            `the same as there being none to read.`, Y));
+        return;
+    }
     if (reading.chains.length === 0)
         return;
     io.out("");
@@ -744,34 +867,65 @@ function reportAgentProof(result, path, gateways, io) {
     const onChain = result.onChainOk === null ? "" : `  on-chain ${mark(result.onChainOk)}`;
     io.out(`  leaf          index ${result.leafIndex} / ${result.leafCount ?? "?"}  inclusion ${mark(result.inclusionOk)}${onChain}`);
     io.out("");
-    printRollup(result.status, null, gateways, result.onChainChecked, io);
+    // An agent inclusion proof carries no records and no disclosed bytes, so
+    // there is no pack to grade: the bundle status IS the headline here.
+    printRollup(result.status, result.status, null, gateways, result.onChainChecked, io);
     for (const e of result.errors)
         io.out(paint(`  note: ${e}`, DIM));
     return mapStatusToExit(result.status, result.errors);
 }
-function printRollup(status, asserted, gateways, onChainChecked, io) {
+function printRollup(headline, bundleStatus, asserted, gateways, onChainChecked, io) {
     const scope = onChainChecked
         ? `verified offline + on-chain against ${gateways.length} gateway(s)`
         : "verified offline (no gateway re-fetch requested)";
     let head;
-    switch (status) {
+    switch (headline) {
         case "verified":
             head = paint("VERIFIED", G);
             break;
+        // Undetermined, in both of its words. Neither is an accusation, so neither
+        // is printed in the color this command uses for one.
         case "partial":
-            head = paint("PARTIAL", Y);
+        case "pending":
+        case "incomplete":
+            head = paint(headline.toUpperCase(), Y);
             break;
         case "failed":
             head = paint("FAILED", R);
             break;
         default:
-            head = paint(status.toUpperCase(), R);
+            head = paint(headline.toUpperCase(), R);
     }
     io.out(`${head}  ${paint(scope, DIM)}`);
-    if (asserted && asserted !== status) {
-        io.out(paint(`  (producer asserted "${asserted}"; recomputed verdict is "${status}" — recomputed wins)`, DIM));
+    // Both verdicts, whenever they differ, because they answer different
+    // questions: §3 grades the signed bundle, the pack verdict grades the bundle
+    // plus whatever bytes travelled beside it. A pack can be incomplete while the
+    // bundle it carries is impeccable, and a reader told only the headline would
+    // read a sound bundle as a broken one.
+    if (headline !== bundleStatus) {
+        io.out(paint(`  (the signed bundle is "${bundleStatus}"; the pack around it is "${headline}")`, DIM));
+    }
+    if (asserted && asserted !== bundleStatus) {
+        io.out(paint(`  (the asserting party said "${asserted}"; the recomputed verdict is "${bundleStatus}", ` +
+            `and the recomputed verdict wins)`, DIM));
     }
 }
+/**
+ * The exit code follows the PACK verdict, then falls back to the bundle status.
+ *
+ * `incomplete` is 3 rather than 0: it is undetermined, which is what 3 already
+ * meant for an unreachable gateway, and it is emphatically not 1: the bytes
+ * being absent is never reported as tamper (`evidence-bundle.md` §5.1).
+ */
+function mapGradeToExit(grade, result) {
+    if (grade.verdict === "malformed")
+        return EXIT_MALFORMED;
+    if (grade.verdict === "failed")
+        return EXIT_FAILED;
+    if (grade.verdict === "incomplete")
+        return EXIT_UNDETERMINED;
+    return mapStatusToExit(result.status, result.errors);
+}
 function mapStatusToExit(status, errors) {
     if (status === "failed")
         return EXIT_FAILED;
@@ -782,7 +936,7 @@ function mapStatusToExit(status, errors) {
     // §5 step 3) — maps to exit 3 (undetermined, network-dependent).
     if (status === "partial" &&
         errors.some((e) => /unreachable|could not be re-fetched|unavailable offline/.test(e))) {
-        return EXIT_GATEWAY_UNAVAILABLE;
+        return EXIT_UNDETERMINED;
     }
     // "verified" → 0. "partial" from a withheld record (semantics-undetermined,
     // not a failure) also exits 0 — the bundle is cryptographically sound.

package/dist/crypto.d.ts

@@ -1,5 +1,6 @@
 export declare function bytesToHex(bytes: Uint8Array): string;
 export declare function hexToBytes(hex: string): Uint8Array;
+export declare function isHexField(value: unknown, nibbles: number, lower?: boolean): value is string;
 export declare function utf8(s: string): Uint8Array;
 export declare function sha256Bytes(bytes: Uint8Array): Promise<Uint8Array>;
 export declare function sha256Hex(bytes: Uint8Array): Promise<string>;

package/dist/crypto.js

@@ -20,6 +20,15 @@ export function bytesToHex(bytes) {
     return out;
 }
 export function hexToBytes(hex) {
+    // The type says `string` and a bundle is not typed: every caller here reads
+    // a field a party wrote, so `undefined` and `null` arrive at runtime. Until
+    // gate 4 on proof#140 this line threw the HOST's `Cannot read properties of
+    // undefined (reading 'length')` where the Python kernel raises
+    // `hexToBytes: not a string`, and a finding that wraps it (`inclusion verify
+    // error: ...`) then read two ways. This kernel's own words, in the other
+    // kernel's wording, so a finding may quote them.
+    if (typeof hex !== "string")
+        throw new Error("hexToBytes: not a string");
     if (hex.length % 2 !== 0)
         throw new Error("hexToBytes: odd-length string");
     // Full validation: parseInt() partially parses ("1g" -> 1), which would let
@@ -32,6 +41,26 @@ export function hexToBytes(hex) {
     }
     return out;
 }
+// The one hex-field test, beside the one hex reader above. The Python twin is
+// `is_hex_field` in `src/sanning_proof/hex.py`, and every site in either kernel
+// that asks whether a producer's hex is the shape a spec fixes goes through one
+// of the two.
+//
+// The test runs BEFORE any decoder sees the value, so the failure a reader is
+// handed names the field's FORM rather than whatever the decoder happened to
+// say about it: `hexToBytes: non-hex characters` on a respelled key sends an
+// auditor looking for a broken tool, and `Ed25519 signature verification
+// failed` sends them looking for a forgery. Neither is what happened.
+//
+// CASE IS A PARAMETER AND NOT THE DEFAULT. proof#135 (option B, Phil
+// 2026-09-22) pinned the hex charset and left the case open, so `lower` is
+// passed only where a value is compared against a RECOMPUTED lowercase digest
+// and no other spelling of it could ever be that digest.
+export function isHexField(value, nibbles, lower = false) {
+    if (typeof value !== "string" || value.length !== nibbles)
+        return false;
+    return (lower ? /^[0-9a-f]*$/ : /^[0-9a-fA-F]*$/).test(value);
+}
 export function utf8(s) {
     return new TextEncoder().encode(s);
 }