@sanning/proof 0.19.0 → 0.20.0

package/src/exit-codes.ts

@@ -1,82 +1,43 @@
-// One exit-code table for every verb (0.13.0).
-//
-// Both commands, `npx @sanning/proof` and `sanning-proof`, map a verdict word to
-// an exit code through this one table, for `verify`, `case` and `export` alike,
-// and every verb's `--help` prints `EXIT_CODES_HELP` byte for byte. The twin is
-// `src/sanning_proof/exit_codes.py`; the specification is `evidence-export.md`
-// §5.
-//
-// Until 0.13.0 `verify` exited 0 on `partial` unless a gateway was unreachable,
-// while `case` exited 3 on it, so a CI gate reading `verify`'s exit code read a
-// stamp witnessed by nobody as verified. Every word that means "could not be
-// settled" now exits 3, which is the code's name: undetermined.
+// One exit-code table for every verb (`verify`, `case`, `export`), shared by both
+// commands. Every verb's `--help` prints `EXIT_CODES_HELP` byte for byte
+// (evidence-export.md section 5).
 
 export const EXIT_VERIFIED = 0;
 export const EXIT_FAILED = 1;
-export const EXIT_MALFORMED = 2;
-export const EXIT_UNDETERMINED = 3;
-export const EXIT_MIXED = 4;
+export const EXIT_INCOMPLETE = 2;
 /**
- * Sandbox evidence (envelope-spec §2): a run that would exit 0 over a pack or
- * case holding a record signed `environment: "dev"`, or a run over records
- * that are ALL signed `dev` whose only unsettled witnesses are simulated.
- * Not a verdict word: the verdict stays what the checks established
- * (`sandboxExit`). No flag turns 5 into 0.
+ * Not a verdict: the verdict is `verified` and a record is signed `environment: "dev"`
+ * (envelope-spec section 2). A failed or incomplete sandbox run keeps 1 or 2.
  */
-export const EXIT_SANDBOX = 5;
+export const EXIT_SANDBOX = 3;
+/** A bad flag, a missing file, or an input that is not a pack or a case at all. */
+export const EXIT_COULD_NOT_RUN = 4;
 
-/**
- * The exit code of each of the eight verdict words (`evidence-bundle.md` §3).
- * `undetermined` is the name of 3, and never a word here.
- */
+/** The exit code of each verdict (`evidence-bundle.md` section 3). */
 export const EXIT_CODES: Readonly<Record<string, number>> = Object.freeze({
   verified: EXIT_VERIFIED,
   failed: EXIT_FAILED,
-  malformed: EXIT_MALFORMED,
-  partial: EXIT_UNDETERMINED,
-  pending: EXIT_UNDETERMINED,
-  incomplete: EXIT_UNDETERMINED,
-  not_found: EXIT_UNDETERMINED,
-  mixed: EXIT_MIXED,
+  incomplete: EXIT_INCOMPLETE,
 });
 
-/** What every verb's help prints, identical in both commands. */
+/** What every verb's help prints. */
 export const EXIT_CODES_HELP = [
   "Exit codes, one table for every verb:",
-  "  0  verified, or the export was written",
-  "  1  failed",
-  "  2  usage or malformed",
-  "  3  undetermined: partial, pending, incomplete or not_found",
-  "  4  mixed: more than one outcome, none failed; read the exceptions",
-  "  5  sandbox: a record is signed environment dev; would be 0, or only a simulated witness is unchecked",
+  "  0  verified: every claim in scope is proven; export: the export was written",
+  "  1  failed: a claim is disproven",
+  "  2  incomplete: nothing is disproven and a claim is not proven",
+  "  3  sandbox: verified, and a record is signed environment dev",
+  "  4  could not run: a bad flag, a missing file, or an input that is not a pack or case",
 ].join("\n");
 
 /**
- * The exit code of a verdict word. A word outside the eight is a verdict
- * nothing can render, so it exits 2, never 0.
+ * The exit code of a verdict. `verified` over a record signed `dev` is 3. A value outside
+ * the three verdicts is 4, never 0.
  */
-export function exitCodeFor(verdict: unknown): number {
-  if (typeof verdict === "string" && Object.prototype.hasOwnProperty.call(EXIT_CODES, verdict)) {
-    return EXIT_CODES[verdict]!;
+export function exitCodeFor(verdict: unknown, environmentMarker: string | null = null): number {
+  if (typeof verdict !== "string" || !Object.prototype.hasOwnProperty.call(EXIT_CODES, verdict)) {
+    return EXIT_COULD_NOT_RUN;
   }
-  return EXIT_MALFORMED;
-}
-
-/**
- * The code a verb exits with once the environment marker is read. 5 where the
- * run would otherwise exit 0 and the pack or case holds a record signed `dev`;
- * 5 where the run is undetermined only because a simulated witness could not
- * be looked up (`onlySimulatedUnsettled`, which the caller works out) and
- * EVERY record is signed `dev`, so a production or mixed pack carrying a
- * simulated witness keeps 3; the code unchanged everywhere else. A failure
- * stays 1, malformed 2 and mixed 4.
- */
-export function sandboxExit(
-  code: number,
-  environmentMarker: string | null,
-  onlySimulatedUnsettled = false,
-): number {
-  if (code === EXIT_VERIFIED && environmentMarker !== null) return EXIT_SANDBOX;
-  if (code === EXIT_UNDETERMINED && environmentMarker === "dev" && onlySimulatedUnsettled) return EXIT_SANDBOX;
-  return code;
+  if (verdict === "verified" && environmentMarker !== null) return EXIT_SANDBOX;
+  return EXIT_CODES[verdict]!;
 }

package/src/file-match.ts

@@ -1,45 +1,20 @@
 /**
- * Files handed in beside a pack, matched against what its records signed (A29).
+ * Matches files handed in beside a pack against the commitments its signed
+ * records make (evidence-bundle.md §5.7). Conformance: `vectors/file-match.json`.
  *
- * The TypeScript half of `src/sanning_proof/file_match.py`. Both kernels are
- * held to one table, `vectors/file-match.json`, so neither can pass by agreeing
- * with the other, and `cross-kernel/run_file_match.sh` holds the two readings,
- * and the two commands' `--files` output, to the same bytes.
+ * - Matching is by SHA-256 of the exact bytes only. A file's name is a label
+ *   and is never compared with an `event_id`, a part name or a path.
+ * - Unmatched is reported, never guessed.
+ * - Only what a record's own key signed counts: a verified envelope whose
+ *   `event_bytes` bind to its `payload_hash`, or a hand-off message whose bytes
+ *   bind to that record's `message_hash`. No wrapper field is read.
+ * - The verdict does not move (`FILE_MATCH_SCOPE`).
  *
- * WHAT THIS ANSWERS (evidence-bundle.md 5.7 v1.24, proof#92, decided by Phil
- * 2026-09-23 as option 2). A reader holds a pack and some files beside it and
- * asks whether the pack vouches for them. Each offered file is hashed, SHA-256
- * over its exact bytes, and the digest is looked for among the commitments the
- * pack's SIGNED records make. The reading says which offered files a record
- * commits to (naming the record, its signer and its `signed_at`), which match
- * no record, and which commitments had no file offered.
- *
- * THE RULES THAT CARRY THE WEIGHT:
- *
- *   - By hash, and by nothing else. A file's name is carried through as the
- *     caller's label and is never compared with an `event_id`, a part's name or
- *     a `logs/` path. There is no layout convention.
- *   - Unmatched is reported, never guessed.
- *   - Only what a record's own key signed: a verified envelope whose
- *     `event_bytes` bind to its `payload_hash`, or a hand-off message whose
- *     bytes bind to that record's `message_hash`. No wrapper field is read.
- *   - The verdict does not move. A match proves that a signed record in the
- *     pack committed to those exact bytes, and nothing more (`FILE_MATCH_SCOPE`).
- *
- * WHAT COUNTS AS A COMMITMENT, in record order and then part order:
- *
- *   1. `record`: a record outside envelope-spec.md 4.1 commits through
- *      `event.content_hash`, 64 hex characters in either case.
- *   2. `file_part`: a record 4.1 governs commits to its MESSAGE through
- *      `event.message_hash` (5.1, A20), never through a `content_hash` it also
- *      writes. Where the message's JCS bytes are in hand (in the body, or in
- *      the side content) and bind to it, each file part of that message (A18)
- *      commits by its `content_hash`.
- *
- * Side content is read for ONE thing, to find a hand-off message that binds to
- * a signed `message_hash`. It is never an offered file.
- *
- * Pure: a bundle, the files and the optional side content in, a reading out.
+ * A record outside envelope-spec.md §4.1 commits through `event.content_hash`.
+ * A hand-off record commits to its message through `event.message_hash`, and,
+ * where the message bytes are in hand and bind, each file part of that message
+ * commits by its `content_hash`. Side content is read only to find such a
+ * message; it is never an offered file.
  */
 
 import { hexToBytes, isHexField, sha256Hex } from "./crypto.js";
@@ -52,7 +27,7 @@ import type { SideContentMap } from "./side-content.js";
 import type { Envelope } from "./types.js";
 import { jcsParse, verifyEnvelope } from "./verifier.js";
 
-/** The one sentence every surface prints with the reading (5.7). */
+/** The scope sentence every surface prints with the reading (§5.7). */
 export const FILE_MATCH_SCOPE =
   "A match proves that a signed record in the pack committed to these exact " +
   "bytes, and nothing more.";
@@ -71,9 +46,8 @@ export const NOT_READ_REASONS = [
 export type NotReadReason = (typeof NOT_READ_REASONS)[number];
 
 /**
- * Why a file was named in the report and never hashed (5.7.5). A skipped file
- * is listed, never dropped: every file a command found is matched, unmatched or
- * skipped, so "no match" is never read as "no file was there".
+ * Why a found file was not hashed (§5.7.5). A skipped file is listed, never
+ * dropped, so "no match" is never read as "no file was there".
  */
 export const SKIPPED_REASONS = [
   "symbolic_link",
@@ -90,7 +64,6 @@ const SKIPPED_TEXT: Record<SkippedReason, string> = {
   not_regular: "not a regular file: not read",
   unreadable: "could not be read",
   too_large: "past the 1 GiB read from folders in one run: not read",
-  // Followed by the reader's own words, `renderSkipped`.
   refused: "a .zip entry the reader refused",
 };
 
@@ -105,9 +78,8 @@ const REASON_TEXT: Record<NotReadReason, string> = {
   message_withheld: "its message is not in hand, so its file parts cannot be read",
 };
 
-// The accept-set minus the quarantined `sanning.mlflow/v1` (DL-63), the set
-// both kernels read a case under.
-const RECORD_PROFILES = ["sanning.agent/v1", "sanning.events/v2"] as const;
+// The accepted profiles minus the quarantined `sanning.mlflow/v1`.
+const RECORD_PROFILES = ["sanning.events/v2"] as const;
 
 /** One commitment a signed record makes to a file's bytes. */
 export interface FileCommitment {
@@ -118,13 +90,9 @@ export interface FileCommitment {
   contentHash: string;
   signer: string;
   signedAt: string | null;
-  /**
-   * The pack, by its position in the packs `matchCaseFiles` was handed (the
-   * same position the case reading's `packIndex` names), or `null` from
-   * `matchFiles`, which reads one pack (A43).
-   */
+  /** Position in the packs `matchCaseFiles` was handed, or `null` from `matchFiles`. */
   packIndex: number | null;
-  /** The record, by its position in the events the pack presents (A43). */
+  /** Position in the events the pack presents. */
   recordIndex: number;
 }
 
@@ -143,7 +111,7 @@ export interface UnmatchedFile {
 export interface SkippedFile {
   name: string;
   reason: SkippedReason;
-  /** The reader's own words, for a `.zip` entry it refused (`refused`). */
+  /** The reader's own words, for a refused `.zip` entry. */
   detail?: string;
 }
 
@@ -151,12 +119,8 @@ export interface NotRead {
   packRef: string | null;
   eventId: string | null;
   reason: NotReadReason;
-  /** As on `FileCommitment` (A43). */
   packIndex: number | null;
-  /**
-   * As on `FileCommitment`, or `null` where the pack presents no events at all
-   * (`no_records`).
-   */
+  /** `null` where the pack presents no events (`no_records`). */
   recordIndex: number | null;
 }
 
@@ -167,18 +131,13 @@ export interface FileMatchReading {
   notOffered: FileCommitment[];
   notRead: NotRead[];
   scope: string;
-  /**
-   * Files found and not hashed. The matching functions leave it empty: it is
-   * the caller's, because only a caller that reads a folder knows a link.
-   */
+  /** Files found and not hashed. Filled by the caller, which alone reads folders. */
   skipped?: SkippedFile[];
 }
 
 /**
- * A file handed in beside a pack. `name` is a label and is never compared. The
- * file is its `bytes`, or its `sha256` (64 lowercase hex characters) where the
- * caller has already hashed it: a command streams a file of any size rather
- * than hold it.
+ * A file handed in beside a pack. `name` is a label, never compared. Give
+ * `bytes`, or `sha256` (64 lowercase hex) when the caller streamed the file.
  */
 export type OfferedFile =
   | { name: string; bytes: Uint8Array; sha256?: undefined }
@@ -203,8 +162,8 @@ function own(o: Record<string, unknown>, key: string): unknown {
   return Object.prototype.hasOwnProperty.call(o, key) ? o[key] : undefined;
 }
 
-// The envelope's key and signature in the hex charset at their lengths, the
-// reading every body verifier applies inside a bundle (proof#142).
+// The key and signature must be hex at their lengths, as every body verifier
+// requires inside a bundle.
 function envelopeSpelled(envelope: Record<string, unknown>): boolean {
   for (const [name, nibbles] of [
     ["public_key", 64],
@@ -369,8 +328,8 @@ async function readPack(
   return { commitments, notRead };
 }
 
-// A malformed file entry is the CALLER's mistake, not the evidence's, so it
-// throws rather than reading as a file that matched nothing.
+// A malformed entry is the caller's mistake, not the evidence's, so it throws
+// rather than reading as an unmatched file.
 async function offeredDigests(files: readonly OfferedFile[]): Promise<[string, string][]> {
   const out: [string, string][] = [];
   for (const entry of files) {
@@ -427,10 +386,8 @@ async function match(
 }
 
 /**
- * Match each offered file against the commitments one pack's signed records
- * make. `content` is the side content handed in beside the pack, read only to
- * find a hand-off message that binds to its record's `message_hash`; it is
- * never an offered file.
+ * Matches each offered file against one pack's signed commitments. `content`
+ * is the pack's side content, read only to bind hand-off messages.
  */
 export async function matchFiles(
   bundle: unknown,
@@ -441,7 +398,7 @@ export async function matchFiles(
   return match(commitments, notRead, files);
 }
 
-/** The same reading over every pack of a case, each commitment naming its pack's `ref`. */
+/** `matchFiles` over every pack of a case. */
 export async function matchCaseFiles(
   packs: readonly FileMatchPack[],
   files: readonly OfferedFile[],
@@ -472,7 +429,7 @@ function commitmentJson(c: FileCommitment): Record<string, unknown> {
   };
 }
 
-/** The reading as the `files` member of `--json`, identical in both kernels. */
+/** The reading as the `files` member of `--json`. */
 export function fileMatchToJson(reading: FileMatchReading): Record<string, unknown> {
   const skipped = reading.skipped ?? [];
   return {
@@ -492,8 +449,7 @@ export function fileMatchToJson(reading: FileMatchReading): Record<string, unkno
       reason: n.reason,
       rendered: renderNotRead(n),
     })),
-    // Present only when something was skipped, so a reading with no skipped
-    // file is the object it was before a folder could be offered (A40).
+    // Omitted when empty, so a reading with nothing skipped keeps its shape.
     ...(skipped.length > 0
       ? {
           skipped: skipped.map((k) => ({
@@ -535,11 +491,9 @@ function renderNotRead(n: NotRead): string {
 
 /**
  * The commitments no offered file matched and no disclosed log answers.
- *
- * `contents` is each pack's side content by `pack_ref`. A record whose own pack
- * discloses bytes that hash to its `content_hash` is accounted for by the pack,
- * and is not returned. Only the text report's count reads this; the reading, and
- * `--json`, still list every commitment no file matched.
+ * A record whose own pack discloses bytes hashing to its `content_hash` is
+ * accounted for. Only the text report's count reads this; `--json` still lists
+ * every unmatched commitment.
  */
 export async function notAccountedFor(
   reading: FileMatchReading,
@@ -559,11 +513,8 @@ export async function notAccountedFor(
 }
 
 /**
- * The text report's lines for the reading, identical in both kernels.
- *
- * By default every commitment no file matched is a line. `notAmong` is the case
- * command's report when no `--files` was given: one count line for the recorded
- * files no loose file matched, and no line for each (A41).
+ * The text report's lines for the reading. With `notAmong` (the case command
+ * with no `--files`), unmatched commitments collapse to one count line.
  */
 export function renderFileMatch(reading: FileMatchReading, notAmong?: number): string[] {
   const skipped = reading.skipped ?? [];