@sanning/proof 0.12.0 → 0.14.0

package/src/evidence.ts

@@ -29,11 +29,14 @@ import {
   utf8,
   verifyRsaPssSha256,
 } from "./crypto.js";
+import { isConformantHandoffRecord, isHandoffNamespace, type HeldRecord } from "./handoff.js";
 import { leafHash, verifyInclusion } from "./merkle.js";
 import {
+  DuplicateKeyError,
   MAX_CANONICAL_DEPTH,
   contentHashes,
   exceedsDepth,
+  isRfc3339UtcInstant,
   jcs,
   jcsParse,
   verifyEnvelope,
@@ -48,7 +51,8 @@ import type { Envelope } from "./types.js";
 // Only the evidence-bundle major(s) this kernel verifies. A new major is a
 // deliberate one-entry addition HERE — same fail-closed discipline as the
 // envelope verifier's ACCEPTED_SPEC_MAJORS.
-const ACCEPTED_EVIDENCE_MAJORS = ["sanning.evidence/v1"];
+/** The accepted `sanning.evidence/v1` wrapper majors; exported in both kernels (P-01, 0.13.0). */
+export const ACCEPTED_EVIDENCE_MAJORS: readonly string[] = Object.freeze(["sanning.evidence/v1"]);
 
 // The body_type this module knows how to verify structurally. An unknown
 // body_type is not a hard failure of the WRAPPER (the signature + body_hash
@@ -514,6 +518,12 @@ export interface EvidenceBundleResult {
   // Absent for every other body — additive, backward-compatible.
   stamps?: StampResult[];
   errors: string[];
+  // Informational only: never read, never gated on, never moves `status` or
+  // the CLI exit code. Carries `CO_SIGNATURES_NOTE` where the wrapper's
+  // reserved `co_signatures` field is present with at least one entry
+  // (evidence-bundle.md §2, §7.1 decision proof#148). Absent for every
+  // bundle without it, additive and backward-compatible.
+  notes?: string[];
 }
 
 // ---- Attested-evidence-export wire + result types (evidence-export.md) -------
@@ -669,6 +679,43 @@ export interface VerifyEvidenceOptions {
   fetchImpl?: typeof fetch;
 }
 
+/**
+ * A surface MUST NOT present a wrapper's `co_signatures` as evidence
+ * (evidence-bundle.md §2, decided by Phil 2026-09-24 on proof#148): nothing
+ * in either kernel verifies the field, and it sits outside the wrapper's
+ * signed scope (`bundleForSig` below), so anyone holding a pack's bytes can
+ * append it with no key at all. This is the one sentence both kernels attach
+ * as a note, never a verdict, never an exit code.
+ */
+export const CO_SIGNATURES_NOTE =
+  "unverified co-signatures are present in this pack's wrapper and are not part of the evidence";
+
+/**
+ * True iff the wrapper's reserved `co_signatures` field carries at least one
+ * entry.
+ *
+ * Absence and an empty array read the same way here: the field asserts
+ * nothing about a second signer until it holds one, and evidence-bundle.md's
+ * own carve-out language for the analogous envelope field treats "absent"
+ * and "an empty array" as one thing (envelope-spec.md §7.1). A non-array
+ * value (malformed shape, but the field is reserved, not yet specified)
+ * still counts as present: it is not the well-formed absence either rule
+ * describes.
+ */
+export function coSignaturesPresent(b: unknown): boolean {
+  if (b === null || typeof b !== "object" || Array.isArray(b)) return false;
+  const value = (b as Record<string, unknown>).co_signatures;
+  if (!("co_signatures" in (b as Record<string, unknown>)) || value === null || value === undefined) {
+    return false;
+  }
+  if (Array.isArray(value)) return value.length > 0;
+  return true;
+}
+
+function coSignaturesNote(bundle: unknown): string | undefined {
+  return coSignaturesPresent(bundle) ? CO_SIGNATURES_NOTE : undefined;
+}
+
 function isEvidenceMajorAccepted(specVersion: unknown): boolean {
   if (typeof specVersion !== "string" || specVersion === "") return false;
   return ACCEPTED_EVIDENCE_MAJORS.some((m) => {
@@ -690,6 +737,10 @@ function isEvidenceMajorAccepted(specVersion: unknown): boolean {
  * (`evidence-bundle.md` 5.5.1), so reporting `false` here let a holder who
  * broke its own body shape read as a forger.
  */
+/** evidence-bundle §2 (A31). Byte-identical to the Python kernel's. */
+export const GENERATED_AT_MALFORMED =
+  "malformed generated_at: not an RFC 3339 UTC date-time with Z naming a real date and time (evidence-bundle §2)";
+
 function malformed(error: string, specVersionOk = false, wrapperOk = false): EvidenceBundleResult {
   return {
     status: "malformed",
@@ -710,7 +761,9 @@ function malformed(error: string, specVersionOk = false, wrapperOk = false): Evi
  * the Python kernel writes too. Anything outside this set comes from the host:
  * a JSON parser, a codec, a crypto library. See `thrownDetail`.
  */
-const KERNEL_WORDING = ["hexToBytes: "];
+// `duplicate key ` is `DuplicateKeyError` in `verifier.ts`, which
+// `DuplicateKey` in the Python twin's `canonicalize.py` words identically.
+const KERNEL_WORDING = ["hexToBytes: ", "duplicate key "];
 
 /**
  * The detail a finding may append about a caught exception.
@@ -728,6 +781,27 @@ const KERNEL_WORDING = ["hexToBytes: "];
  * is the host's parse offset, which no reader can act on and which was never
  * the same in the two kernels.
  */
+/**
+ * The kernel's `duplicate key "<name>"` when a record repeats a member name,
+ * else `undefined` (proof#144; `_record_duplicate_key` in the Python twin).
+ *
+ * ONLY A DUPLICATE, and not every unreadable record. Every reader below this
+ * one that parses a record treats an unreadable one as absent, so the content
+ * binding reads undetermined and the pack said "1 record discloses no bytes"
+ * about a record whose bytes it had read. A record that repeats a name is
+ * a defect in the artifact, and a defect this kernel can see fails, the rule
+ * `event_bytes` that are not hex already follow.
+ */
+function recordDuplicateKey(eventBytes: Uint8Array | undefined): string | undefined {
+  if (eventBytes === undefined) return undefined;
+  try {
+    jcsParse(eventBytes);
+  } catch (e) {
+    if (e instanceof DuplicateKeyError) return e.message;
+  }
+  return undefined;
+}
+
 function thrownDetail(e: unknown): string {
   const text = e instanceof Error ? e.message : String(e);
   return KERNEL_WORDING.some((w) => text.startsWith(w)) ? `: ${text}` : "";
@@ -804,7 +878,17 @@ export async function verifyEvidenceBundle(
   bundle: unknown,
   options: VerifyEvidenceOptions = {},
 ): Promise<EvidenceBundleResult> {
-  return verifyBundle(bundle, options, false);
+  // The ONE place a present `co_signatures` becomes a note, so every caller
+  // (including `case.ts`, which calls this function directly per pack) gets
+  // it, however the wrapper otherwise verifies. Never touches `status` or
+  // the exit code: a bundle that would otherwise verify still verifies, note
+  // or not (proof#148).
+  const result = await verifyBundle(bundle, options, false);
+  const note = coSignaturesNote(bundle);
+  if (note !== undefined) {
+    result.notes = [...(result.notes ?? []), note];
+  }
+  return result;
 }
 
 // `exportSource`: read the bundle as an export's source (evidence-export.md
@@ -830,12 +914,16 @@ async function verifyBundle(
   const b = bundle as EvidenceBundle;
   const specVersionOk = isEvidenceMajorAccepted(b.spec_version);
   if (!specVersionOk) {
-    return malformed(`unsupported evidence spec_version: ${JSON.stringify(b.spec_version)}`, false);
+    // `?? null`: an ABSENT field is spelled `null`, as the Python twin's
+    // `_json_str` spells it. `JSON.stringify(undefined)` is `undefined`, and
+    // the two kernels printed two different sentences for one bundle until
+    // `verify --json` compared them byte for byte (0.13.0).
+    return malformed(`unsupported evidence spec_version: ${JSON.stringify(b.spec_version ?? null)}`, false);
   }
   if (typeof b.signature_alg === "string" && b.signature_alg !== "ed25519") {
     // The reference verifier implements ed25519 only (evidence-bundle §2 +
     // decision #2); other algs are a deliberate future addition.
-    return malformed(`unsupported signature_alg: ${JSON.stringify(b.signature_alg)}`, true);
+    return malformed(`unsupported signature_alg: ${JSON.stringify(b.signature_alg ?? null)}`, true);
   }
   if (typeof b.public_key !== "string" || typeof b.signature !== "string") {
     return malformed("evidence bundle is missing public_key/signature", true);
@@ -885,7 +973,7 @@ async function verifyBundle(
       const { signature: _sig, co_signatures: _co, ...bundleForSig } = b as EvidenceBundle & {
         co_signatures?: unknown;
       };
-      signatureOk = await ed25519Verify(b.signature, utf8(jcs(bundleForSig)), b.public_key);
+      signatureOk = await ed25519Verify(utf8(jcs(bundleForSig)), b.signature, b.public_key);
       if (!signatureOk) errors.push("wrapper Ed25519 signature verification failed");
     } catch (e) {
       errors.push(`wrapper signature verification error${thrownDetail(e)}`);
@@ -911,6 +999,19 @@ async function verifyBundle(
     };
   }
 
+  // --- The wrapper's own time (evidence-bundle §2, A31) ---------------------
+  // `generated_at` is copied into a recomputed verdict's `as_of` (the export
+  // reading) and printed beside every verdict, so a present value that is not
+  // the RFC 3339 form `signed_at` already pins is a wrapper this kernel cannot
+  // render, whatever its signature. It is read only once the wrapper holds: a
+  // broken wrapper is `failed` above, as it was. Absence is unchanged.
+  if (
+    Object.prototype.hasOwnProperty.call(b, "generated_at") &&
+    !isRfc3339UtcInstant((b as { generated_at?: unknown }).generated_at)
+  ) {
+    return malformed(GENERATED_AT_MALFORMED, specVersionOk, true);
+  }
+
   // --- Body dispatch ---------------------------------------------------------
   const bodyType = typeof b.body_type === "string" ? b.body_type : null;
 
@@ -1135,7 +1236,7 @@ function parseAnchorRef(
   }
   const o = raw as Record<string, unknown>;
   if (typeof o.kind !== "string" || !/^[a-z0-9][a-z0-9._-]*$/.test(o.kind)) {
-    errors.push(`anchor_ref.kind is missing or malformed: ${JSON.stringify(o.kind)}`);
+    errors.push(`anchor_ref.kind is missing or malformed: ${JSON.stringify(o.kind ?? null)}`);
     return { ref: null, malformed: true };
   }
   if (typeof o.id !== "string" || o.id === "") {
@@ -1384,6 +1485,11 @@ async function verifyAnchorTrace(
       eventBytesMalformed = true;
       evErrors.push(`event event_bytes is not hex${thrownDetail(e)}`);
     }
+    const duplicate = recordDuplicateKey(eventBytes);
+    if (duplicate !== undefined) {
+      eventBytesMalformed = true;
+      evErrors.push(`event record is not JSON: ${duplicate}`);
+    }
     try {
       const res = await verifyEnvelope(
         ev.envelope,
@@ -1711,21 +1817,61 @@ async function verifyDisclosedContent(
   const evErrors: string[] = [];
   let contentOk: boolean | null = null;
 
+  // WHICH hash in the record is decided by the record's STRUCTURE
+  // (evidence-bundle §5.1 v1.19, A20). A record `envelope-spec.md` §4.1
+  // governs (`isHandoffNamespace`) commits to its message through
+  // `event.message_hash`, SHA-256 of `JCS(message object)`, and has no
+  // `content_hash`, so until A20 its disclosure bound to nothing and an honest
+  // hand-off pack could never grade `verified`. For such a record the committed
+  // hash is `event.message_hash` and nothing else: not a `content_hash` it also
+  // carries, and not the envelope's. It binds only when the record is a
+  // CONFORMANT hand-off record under the key that signed it
+  // (`isConformantHandoffRecord`) and the value is 64 characters of lowercase
+  // hex. Anything short of that commits nothing this reader will bind to, so
+  // the reading is undetermined and never true: a record dressed as a hand-off
+  // record gains no binding from the dress, and a record outside §4.1 keeps its
+  // `content_hash` exactly as before, whatever `message_hash` field it writes.
+  // The Python twin is `evidence._evaluate_content`.
   const committed: string[] = [];
   let recordContentHash: string | undefined;
+  let governed = false;
+  let handoffHash: string | undefined;
   if (eventBytes !== undefined) {
     try {
-      const record = jcsParse(eventBytes) as {
+      const parsed = jcsParse(eventBytes);
+      const record = parsed as {
         event?: { content_hash?: unknown };
-      };
-      const ch = record.event?.content_hash;
+      } | null;
+      const ch = record?.event?.content_hash;
       if (typeof ch === "string" && ch) recordContentHash = ch.toLowerCase();
+      if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+        const envelope = ev.envelope;
+        const held: HeldRecord = {
+          publicKey:
+            envelope !== null && typeof envelope === "object" && !Array.isArray(envelope)
+              ? ((envelope as { public_key?: unknown }).public_key as string)
+              : (undefined as unknown as string),
+          record: parsed as HeldRecord["record"],
+          ref: "",
+        };
+        if (isHandoffNamespace(held)) {
+          governed = true;
+          const event = (parsed as { event?: unknown }).event;
+          const mh =
+            event !== null && typeof event === "object" && !Array.isArray(event)
+              ? (event as { message_hash?: unknown }).message_hash
+              : undefined;
+          if (isConformantHandoffRecord(held) && isLowerHex(mh, 64)) handoffHash = mh;
+        }
+      }
     } catch {
       // record not JSON — the payload binding already reflects that; content
       // stays undetermined rather than throwing.
     }
   }
-  if (recordContentHash !== undefined) {
+  if (governed) {
+    if (handoffHash !== undefined) committed.push(handoffHash);
+  } else if (recordContentHash !== undefined) {
     committed.push(recordContentHash);
   } else if (ev.envelope && typeof ev.envelope === "object") {
     // Promoted fallback. Guarded: contentHashes() dereferences env.payload,
@@ -1749,16 +1895,21 @@ async function verifyDisclosedContent(
       contentOk = null;
       if (disclosed !== undefined && committed.length === 0) {
         evErrors.push(
-          "disclosed content present but no committed content_hash to bind to " +
-            "(record withheld or record has no event.content_hash) -- undetermined",
+          governed
+            ? "disclosed content present but this hand-off record commits no " +
+                "message_hash a reader can bind to (not a conformant hand-off " +
+                "record, or message_hash is not 64 lowercase hex) -- undetermined"
+            : "disclosed content present but no committed content_hash to bind to " +
+                "(record withheld or record has no event.content_hash) -- undetermined",
         );
       }
     } else {
       const got = await sha256Hex(disclosed);
       contentOk = committed.includes(got);
       if (!contentOk) {
+        const fieldName = governed ? "message_hash" : "content_hash";
         evErrors.push(
-          "disclosed content does not match the committed content_hash: " +
+          `disclosed content does not match the committed ${fieldName}: ` +
             `sha256(disclosed)=${got} committed=${committed.join("|")}`,
         );
       }
@@ -1882,7 +2033,7 @@ async function verifyStampEntry(
     // reader's dispatch key and it said v1; honouring the other spelling is
     // how a reader half-parses a shape it does not know.
     errors.push(
-      `unsupported stamp_version ${JSON.stringify(body.stamp_version)} in a ` +
+      `unsupported stamp_version ${JSON.stringify(body.stamp_version ?? null)} in a ` +
         `${STAMP_TRACE_BODY_TYPE} body (expected ${STAMP_BODY_VERSION})`,
     );
     return { result: base, witnessedHex };
@@ -1894,6 +2045,10 @@ async function verifyStampEntry(
     if (typeof body[f] !== "string" || body[f] === "") {
       errors.push(`stamp body ${f} is missing or not a non-empty string`);
       base.bodyOk = false;
+    } else if (f !== "org_ref" && !isRfc3339UtcInstant(body[f])) {
+      // §5.2 (A31): the promise window is the form `signed_at` pins.
+      errors.push(`stamp body ${f} is not an RFC 3339 UTC date-time with Z naming a real date and time`);
+      base.bodyOk = false;
     }
   }
   base.intervalStart = typeof body.interval_start === "string" ? body.interval_start : null;
@@ -2204,6 +2359,11 @@ async function verifyStampEvidence(
       eventBytesMalformed = true;
       evErrors.push(`event event_bytes is not hex${thrownDetail(e)}`);
     }
+    const duplicate = recordDuplicateKey(eventBytes);
+    if (duplicate !== undefined) {
+      eventBytesMalformed = true;
+      evErrors.push(`event record is not JSON: ${duplicate}`);
+    }
     try {
       const res = await verifyEnvelope(
         ev.envelope,
@@ -2429,8 +2589,8 @@ async function verifyStampEvidence(
  * synthesis exists to drive `gatewayUnavailable`, which is what downgrades that
  * run to `partial`. Here §5.2.4 already downgrades an unwitnessed stamp to
  * `partial` on its own, with a better error. Copying the synthesis would add
- * nothing to the status and would silently move the CLI exit code from 0 to 3
- * for an unwitnessed stamp — changing what an auditor's script does, based on
+ * nothing to the status, which is `partial` either way, and would add an
+ * unreachable-gateway note for a network event that never happened, based on
  * nothing but whether the caller happened to pass a gateway list.
  */
 async function refetchStamps(
@@ -2840,8 +3000,11 @@ async function verifyExportBody(
   // step-5 erratum flagged in the slice report.
   let verdictAgreementOk = false;
   try {
-    const cachedProjection = jcs(projectVerdictForAgreement(body.kernel_verdict));
-    const freshProjection = jcs(projectVerdictForAgreement(verdict));
+    const cached = projectVerdictForAgreement(body.kernel_verdict);
+    const fresh = projectVerdictForAgreement(verdict);
+    toleratePreA20Content(cached, fresh, sourceEventsGoverned(inline));
+    const cachedProjection = jcs(cached);
+    const freshProjection = jcs(fresh);
     verdictAgreementOk = cachedProjection === freshProjection;
     if (!verdictAgreementOk) {
       errors.push(
@@ -2874,8 +3037,8 @@ async function verifyExportBody(
   ) {
     status = "failed";
   } else if (sourceResult.status === "partial") {
-    // Undetermined source (withheld record → exit 0; gateway-unreachable →
-    // exit 3 via the propagated "unreachable" note). Never a failure.
+    // Undetermined source (a withheld record, or an unreachable gateway):
+    // exit 3 either way since 0.13.0. Never a failure.
     status = "partial";
   } else {
     status = "verified";
@@ -3030,6 +3193,10 @@ function payloadFieldError(payload: Record<string, unknown>): string | null {
       want = "1, 2 or 3";
     }
     if (!ok) return `attestation payload field ${JSON.stringify(name)} is missing or not ${want}`;
+    if (name === "attested_at" && !isRfc3339UtcInstant(v)) {
+      // evidence-export §3.1 (v3.4): the form `signed_at` pins.
+      return 'attestation payload field "attested_at" is not an RFC 3339 UTC date-time with Z naming a real date and time';
+    }
   }
   return null;
 }
@@ -3064,7 +3231,7 @@ async function verifyAttestation(
   if (rec.signature_alg !== "rsa-pss-sha256") {
     return {
       result,
-      malformed: `unsupported attestation signature_alg: ${JSON.stringify(rec.signature_alg)}`,
+      malformed: `unsupported attestation signature_alg: ${JSON.stringify(rec.signature_alg ?? null)}`,
     };
   }
   const pub = rec.public_key as { kty?: unknown; n?: unknown; e?: unknown } | null;
@@ -3266,7 +3433,11 @@ function eventVerdictStatus(e: EventResult): string {
 // nullish normalization) — a structural difference surfaces as disagreement,
 // which is the correct tamper signal. Works on both the cached snake_case JSON
 // and the freshly built VerdictObject.
-function projectVerdictForAgreement(v: unknown): unknown {
+function projectVerdictForAgreement(v: unknown): {
+  schema_version: string | null;
+  events: { content_ok: boolean | null }[];
+  checkpoints: unknown[];
+} {
   const o = (v ?? {}) as VerdictObject;
   const events = Array.isArray(o.events) ? o.events : [];
   const checkpoints = Array.isArray(o.checkpoints) ? o.checkpoints : [];
@@ -3304,6 +3475,69 @@ function projectVerdictForAgreement(v: unknown): unknown {
   };
 }
 
+// Per event of an export's inline `sanning.anchor.trace/v3` source, in order:
+// whether `envelope-spec.md` §4.1 governs its record. Decoded the way the
+// content binding decodes it, so an event whose record is withheld, not hex or
+// not JCS is not governed here either. The Python twin is
+// `evidence._source_events_governed`.
+function sourceEventsGoverned(source: unknown): boolean[] {
+  if (source === null || typeof source !== "object" || Array.isArray(source)) return [];
+  const s = source as { body_type?: unknown; body?: unknown };
+  if (s.body_type !== ANCHOR_TRACE_BODY_TYPE) return [];
+  const body = s.body as { events?: unknown } | null | undefined;
+  const events =
+    body !== null && typeof body === "object" && !Array.isArray(body) ? body.events : undefined;
+  if (!Array.isArray(events)) return [];
+  return events.map((raw: unknown) => {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return false;
+    const ev = raw as { event_bytes?: unknown; envelope?: unknown };
+    if (typeof ev.event_bytes !== "string") return false;
+    try {
+      const parsed = jcsParse(hexToBytes(ev.event_bytes));
+      if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return false;
+      const envelope = ev.envelope;
+      const held: HeldRecord = {
+        publicKey:
+          envelope !== null && typeof envelope === "object" && !Array.isArray(envelope)
+            ? ((envelope as { public_key?: unknown }).public_key as string)
+            : (undefined as unknown as string),
+        record: parsed as HeldRecord["record"],
+        ref: "",
+      };
+      return isHandoffNamespace(held);
+    } catch {
+      return false;
+    }
+  });
+}
+
+// The one difference §5 step 5 does not read as a disagreement
+// (evidence-export.md, evidence-bundle.md v1.19, A20): a cached `content_ok` of
+// `null` against a recomputed `true`, on an event whose record §4.1 governs. A
+// kernel before A20 could not bind a hand-off record's disclosed message, so an
+// export it composed claims less than the recompute proves, and reading that
+// as tamper failed an honest export. Only that direction: a cached `true`
+// against a recomputed `false` or `null`, `null` against `false`, and any
+// difference on a record outside §4.1 still disagree. Edits `fresh` in place
+// to match `cached` on those events. The Python twin is
+// `evidence._tolerate_pre_a20_content`.
+function toleratePreA20Content(
+  cached: { events: { content_ok: boolean | null }[] },
+  fresh: { events: { content_ok: boolean | null }[] },
+  governed: boolean[],
+): void {
+  const n = Math.min(cached.events.length, fresh.events.length);
+  for (let i = 0; i < n; i++) {
+    if (
+      governed[i] === true &&
+      cached.events[i]!.content_ok === null &&
+      fresh.events[i]!.content_ok === true
+    ) {
+      fresh.events[i]!.content_ok = null;
+    }
+  }
+}
+
 function summarizeExport(
   status: EvidenceStatus,
   source: EvidenceBundleResult,

package/src/exit-codes.ts

@@ -0,0 +1,54 @@
+// 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.
+
+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;
+
+/**
+ * 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.
+ */
+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,
+});
+
+/** What every verb's help prints, identical in both commands. */
+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",
+].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.
+ */
+export function exitCodeFor(verdict: unknown): number {
+  if (typeof verdict === "string" && Object.prototype.hasOwnProperty.call(EXIT_CODES, verdict)) {
+    return EXIT_CODES[verdict]!;
+  }
+  return EXIT_MALFORMED;
+}