@sanning/proof 0.10.0 → 0.11.1

package/src/chain.ts

@@ -55,6 +55,7 @@
 // and can go.
 
 import { hexToBytes, sha256Hex } from "./crypto.js";
+import { jcsParse } from "./verifier.js";
 import { resolveTraceEvents } from "./evidence.js";
 
 /**
@@ -203,7 +204,25 @@ function decodeRecord(hex: unknown): { record: EventRecord; bytes: Uint8Array }
   if (typeof hex !== "string" || hex.length === 0) return null;
   try {
     const bytes = hexToBytes(hex);
-    const record = JSON.parse(new TextDecoder().decode(bytes)) as EventRecord;
+    // 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) as EventRecord;
     if (record === null || typeof record !== "object") return null;
     return { record, bytes };
   } catch {

package/src/cli.ts

@@ -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";
@@ -23,17 +43,26 @@ import { fileURLToPath } from "node:url";
 import { isAgentProofSpec, verifyAgentProofBundle } from "./agent-proof.js";
 import type { AgentProofResult } from "./agent-proof.js";
 import { CHAIN_READING_SCOPE, readChains, renderChainFinding } from "./chain.js";
+
+// What this command holds after asking for a chain reading: the reading, or a
+// named statement that one could not be produced. Three states, not two.
+type ChainOutcome = ChainReading | { unreadable: string };
 import type { ChainReading } from "./chain.js";
 import { composeExport } from "./compose.js";
 import type { ComposeExportOptions } from "./compose.js";
-import { utf8 } from "./crypto.js";
+import { isHexField, utf8 } from "./crypto.js";
 import { verifyEvidenceBundle } from "./evidence.js";
 import type { AttestationRecord, EvidenceBundle, EvidenceBundleResult, ExportResult } from "./evidence.js";
+import { checkDeclaration, renderDeclarationSummary, renderNote } from "./declaration.js";
+import { completenessNotes, gradePack, renderCause } from "./grading.js";
+import type { DisclosureAccount, PackGrade } 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;
 
 interface Cli {
   out: (s: string) => void;
@@ -174,8 +203,21 @@ export async function runCli(argv: string[], io: Cli): Promise<number> {
   // 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: ChainOutcome;
+  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") reportLogsCoverage(logs, result, io);
@@ -627,12 +669,28 @@ function sample(names: string[], max = 3): string {
 }
 
 // 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: string): Uint8Array | string {
-  if (v.length > 0 && v.length % 2 === 0 && /^[0-9a-f]+$/.test(v)) return v; // hex passthrough
+  if (v.length > 0 && v.length % 2 === 0 && isHexField(v, v.length)) return v; // hex passthrough
   return utf8(v); // raw utf8 bytes
 }
 
@@ -666,7 +724,49 @@ function printUsage(io: Cli): void {
   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: EvidenceBundleResult,
+  logs: LoadedLogs | undefined,
+): DisclosureAccount {
+  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(
@@ -674,7 +774,9 @@ function reportEvidence(
   path: string,
   gateways: string[],
   io: Cli,
-  chains: ChainReading,
+  chains: ChainOutcome,
+  parsed: unknown,
+  logs: LoadedLogs | undefined,
 ): number {
   if (result.status === "malformed") {
     io.err(paint("MALFORMED", R) + `  ${path}`);
@@ -765,17 +867,55 @@ function reportEvidence(
     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);
 }
 
 /**
@@ -797,7 +937,19 @@ function reportEvidence(
  *    was. A dangling link is something for a person to look at, not a machine
  *    decision this check is entitled to make.
  */
-function reportChains(reading: ChainReading, io: Cli): void {
+function reportChains(reading: ChainOutcome, io: Cli): void {
+  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("");
@@ -859,14 +1011,17 @@ function reportAgentProof(
     `  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: string,
+  headline: string,
+  bundleStatus: string,
   asserted: string | null,
   gateways: string[],
   onChainChecked: boolean,
@@ -876,30 +1031,59 @@ function printRollup(
     ? `verified offline + on-chain against ${gateways.length} gateway(s)`
     : "verified offline (no gateway re-fetch requested)";
   let head: string;
-  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) {
+  // 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(
-        `  (producer asserted "${asserted}"; recomputed verdict is "${status}" — recomputed wins)`,
+        `  (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: PackGrade, result: EvidenceBundleResult): number {
+  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: string, errors: string[]): number {
   if (status === "failed") return EXIT_FAILED;
   if (status === "malformed") return EXIT_MALFORMED;
@@ -910,7 +1094,7 @@ function mapStatusToExit(status: string, errors: string[]): number {
     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/src/crypto.ts

@@ -25,6 +25,14 @@ export function bytesToHex(bytes: Uint8Array): string {
 }
 
 export function hexToBytes(hex: string): Uint8Array {
+  // 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
   // malformed hex through. A strict charset check closes that.
@@ -36,6 +44,26 @@ export function hexToBytes(hex: string): Uint8Array {
   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: unknown, nibbles: number, lower = false): value is string {
+  if (typeof value !== "string" || value.length !== nibbles) return false;
+  return (lower ? /^[0-9a-f]*$/ : /^[0-9a-fA-F]*$/).test(value);
+}
+
 export function utf8(s: string): Uint8Array {
   return new TextEncoder().encode(s);
 }