@sanning/proof 0.12.0 → 0.14.0

package/dist/evidence.js

@@ -21,13 +21,15 @@ import { deriveOperatorAddress, ed25519Verify, hexToBytes,
 // body: two copies of one rule is how two kernels drift apart one edit at a
 // time, which is the whole defect class this fix is about.
 isHexField, sha256Hex, utf8, verifyRsaPssSha256, } from "./crypto.js";
+import { isConformantHandoffRecord, isHandoffNamespace } from "./handoff.js";
 import { leafHash, verifyInclusion } from "./merkle.js";
-import { MAX_CANONICAL_DEPTH, contentHashes, exceedsDepth, jcs, jcsParse, verifyEnvelope, } from "./verifier.js";
+import { DuplicateKeyError, MAX_CANONICAL_DEPTH, contentHashes, exceedsDepth, isRfc3339UtcInstant, jcs, jcsParse, verifyEnvelope, } from "./verifier.js";
 import { inBodyContentOffered, sideContentEntry, } from "./side-content.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 = 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
 // still verify), but its body cannot be re-derived, so the per-body verdict is
@@ -106,6 +108,41 @@ export const STAMP_EVIDENCE_BODY_TYPE = "sanning.stamp.evidence/v2";
  * signature is the §5.1.2 mixed-vocabulary reject, one layer down.
  */
 export const STAMP_BODY_VERSION = "sanning.stamp/v1";
+/**
+ * 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) {
+    if (b === null || typeof b !== "object" || Array.isArray(b))
+        return false;
+    const value = b.co_signatures;
+    if (!("co_signatures" in b) || value === null || value === undefined) {
+        return false;
+    }
+    if (Array.isArray(value))
+        return value.length > 0;
+    return true;
+}
+function coSignaturesNote(bundle) {
+    return coSignaturesPresent(bundle) ? CO_SIGNATURES_NOTE : undefined;
+}
 function isEvidenceMajorAccepted(specVersion) {
     if (typeof specVersion !== "string" || specVersion === "")
         return false;
@@ -129,6 +166,8 @@ function isEvidenceMajorAccepted(specVersion) {
  * (`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, specVersionOk = false, wrapperOk = false) {
     return {
         status: "malformed",
@@ -148,7 +187,9 @@ function malformed(error, specVersionOk = false, wrapperOk = false) {
  * 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.
  *
@@ -165,6 +206,29 @@ 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) {
+    if (eventBytes === undefined)
+        return undefined;
+    try {
+        jcsParse(eventBytes);
+    }
+    catch (e) {
+        if (e instanceof DuplicateKeyError)
+            return e.message;
+    }
+    return undefined;
+}
 function thrownDetail(e) {
     const text = e instanceof Error ? e.message : String(e);
     return KERNEL_WORDING.some((w) => text.startsWith(w)) ? `: ${text}` : "";
@@ -235,7 +299,17 @@ function jsonStr(value) {
 // (`assertedStatus`) but NEVER trusted — the displayed status is the one this
 // function recomputes (evidence-bundle §1 principle 3 / §4 step 4).
 export async function verifyEvidenceBundle(bundle, options = {}) {
-    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
 // §2.4), where the only recognised body is `sanning.anchor.trace/v3`.
@@ -254,12 +328,16 @@ async function verifyBundle(bundle, options, exportSource) {
     const b = bundle;
     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);
@@ -308,7 +386,7 @@ async function verifyBundle(bundle, options, exportSource) {
     if (keyFormOk && signatureFormOk) {
         try {
             const { signature: _sig, co_signatures: _co, ...bundleForSig } = b;
-            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");
         }
@@ -333,6 +411,16 @@ async function verifyBundle(bundle, options, exportSource) {
             errors,
         };
     }
+    // --- 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.generated_at)) {
+        return malformed(GENERATED_AT_MALFORMED, specVersionOk, true);
+    }
     // --- Body dispatch ---------------------------------------------------------
     const bodyType = typeof b.body_type === "string" ? b.body_type : null;
     // Read as an export's source (evidence-export.md §2.4), the only body this
@@ -524,7 +612,7 @@ function parseAnchorRef(raw, errors) {
     }
     const o = raw;
     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 === "") {
@@ -761,6 +849,11 @@ async function verifyAnchorTrace(b, specVersionOk, assertedStatus, errors, optio
             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, eventBytes !== undefined ? { payloadBytes: eventBytes } : {});
             const hexError = envelopeHexError("event", ev.envelope);
@@ -1076,21 +1169,62 @@ function isNonNegInt(n) {
 async function verifyDisclosedContent(ev, eventId, eventBytes, sideContent) {
     const evErrors = [];
     let contentOk = 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 = [];
     let recordContentHash;
+    let governed = false;
+    let handoffHash;
     if (eventBytes !== undefined) {
         try {
-            const record = jcsParse(eventBytes);
-            const ch = record.event?.content_hash;
+            const parsed = jcsParse(eventBytes);
+            const record = parsed;
+            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 = {
+                    publicKey: envelope !== null && typeof envelope === "object" && !Array.isArray(envelope)
+                        ? envelope.public_key
+                        : undefined,
+                    record: parsed,
+                    ref: "",
+                };
+                if (isHandoffNamespace(held)) {
+                    governed = true;
+                    const event = parsed.event;
+                    const mh = event !== null && typeof event === "object" && !Array.isArray(event)
+                        ? event.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") {
@@ -1112,15 +1246,20 @@ async function verifyDisclosedContent(ev, eventId, eventBytes, sideContent) {
         if (disclosed === undefined || committed.length === 0) {
             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");
+                evErrors.push(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) {
-                evErrors.push("disclosed content does not match the committed content_hash: " +
+                const fieldName = governed ? "message_hash" : "content_hash";
+                evErrors.push(`disclosed content does not match the committed ${fieldName}: ` +
                     `sha256(disclosed)=${got} committed=${committed.join("|")}`);
             }
         }
@@ -1217,7 +1356,7 @@ async function verifyStampEntry(raw, seen) {
         // two answers to one question inside one signature. The body_type is the
         // 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 ` +
+        errors.push(`unsupported stamp_version ${JSON.stringify(body.stamp_version ?? null)} in a ` +
             `${STAMP_TRACE_BODY_TYPE} body (expected ${STAMP_BODY_VERSION})`);
         return { result: base, witnessedHex };
     }
@@ -1228,6 +1367,11 @@ async function verifyStampEntry(raw, seen) {
             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;
     base.intervalEnd = typeof body.interval_end === "string" ? body.interval_end : null;
@@ -1501,6 +1645,11 @@ async function verifyStampEvidence(b, specVersionOk, assertedStatus, errors, opt
             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, eventBytes !== undefined ? { payloadBytes: eventBytes } : {});
             const hexError = envelopeHexError("event", ev.envelope);
@@ -1702,8 +1851,8 @@ async function verifyStampEvidence(b, specVersionOk, assertedStatus, errors, opt
  * 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(stamps, witnessed, options, errors) {
@@ -2016,8 +2165,11 @@ async function verifyExportBody(b, specVersionOk, assertedStatus, errors, option
     // 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("recomputed verdict disagrees with the cached kernel_verdict " +
@@ -2046,8 +2198,8 @@ async function verifyExportBody(b, specVersionOk, assertedStatus, errors, option
         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 {
@@ -2165,6 +2317,10 @@ function payloadFieldError(payload) {
         }
         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;
 }
@@ -2193,7 +2349,7 @@ async function verifyAttestation(rec, sourceCheckpoints) {
     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;
@@ -2421,6 +2577,66 @@ function projectVerdictForAgreement(v) {
         }),
     };
 }
+// 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) {
+    if (source === null || typeof source !== "object" || Array.isArray(source))
+        return [];
+    const s = source;
+    if (s.body_type !== ANCHOR_TRACE_BODY_TYPE)
+        return [];
+    const body = s.body;
+    const events = body !== null && typeof body === "object" && !Array.isArray(body) ? body.events : undefined;
+    if (!Array.isArray(events))
+        return [];
+    return events.map((raw) => {
+        if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+            return false;
+        const ev = raw;
+        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 = {
+                publicKey: envelope !== null && typeof envelope === "object" && !Array.isArray(envelope)
+                    ? envelope.public_key
+                    : undefined,
+                record: parsed,
+                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, fresh, governed) {
+    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, source, attestations) {
     const attOk = attestations.filter((a) => a.ok).length;
     return (`Export ${status}: source bundle ${source.status} ` +

package/dist/exit-codes.d.ts

@@ -0,0 +1,17 @@
+export declare const EXIT_VERIFIED = 0;
+export declare const EXIT_FAILED = 1;
+export declare const EXIT_MALFORMED = 2;
+export declare const EXIT_UNDETERMINED = 3;
+export declare 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 declare const EXIT_CODES: Readonly<Record<string, number>>;
+/** What every verb's help prints, identical in both commands. */
+export declare const EXIT_CODES_HELP: string;
+/**
+ * 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 declare function exitCodeFor(verdict: unknown): number;

package/dist/exit-codes.js

@@ -0,0 +1,50 @@
+// 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 = 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) {
+    if (typeof verdict === "string" && Object.prototype.hasOwnProperty.call(EXIT_CODES, verdict)) {
+        return EXIT_CODES[verdict];
+    }
+    return EXIT_MALFORMED;
+}

package/dist/file-match.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Files handed in beside a pack, matched against what its records signed (A29).
+ *
+ * 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.
+ *
+ * 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.
+ */
+import type { SideContentMap } from "./side-content.js";
+/** The one sentence every surface prints with the reading (5.7). */
+export declare const FILE_MATCH_SCOPE: string;
+/** Why a record's commitments could not be read, in the order they are tested. */
+export declare const NOT_READ_REASONS: readonly ["no_records", "record_unreadable", "record_not_verified", "record_withheld", "no_content_hash", "handoff_record_malformed", "message_withheld"];
+export type NotReadReason = (typeof NOT_READ_REASONS)[number];
+/** One commitment a signed record makes to a file's bytes. */
+export interface FileCommitment {
+    packRef: string | null;
+    eventId: string | null;
+    kind: "record" | "file_part";
+    partIndex: number | null;
+    contentHash: string;
+    signer: string;
+    signedAt: string | null;
+}
+export interface MatchedFile {
+    name: string;
+    sha256: string;
+    records: FileCommitment[];
+}
+export interface UnmatchedFile {
+    name: string;
+    sha256: string;
+}
+export interface NotRead {
+    packRef: string | null;
+    eventId: string | null;
+    reason: NotReadReason;
+}
+export interface FileMatchReading {
+    offered: number;
+    matched: MatchedFile[];
+    unmatched: UnmatchedFile[];
+    notOffered: FileCommitment[];
+    notRead: NotRead[];
+    scope: string;
+}
+/** A file handed in beside a pack. `name` is a label and is never compared. */
+export interface OfferedFile {
+    name: string;
+    bytes: Uint8Array;
+}
+/** One pack of a case, for `matchCaseFiles`. */
+export interface FileMatchPack {
+    ref: string;
+    bundle: unknown;
+    content?: SideContentMap | null;
+}
+/**
+ * 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.
+ */
+export declare function matchFiles(bundle: unknown, files: readonly OfferedFile[], content?: SideContentMap | null): Promise<FileMatchReading>;
+/** The same reading over every pack of a case, each commitment naming its pack's `ref`. */
+export declare function matchCaseFiles(packs: readonly FileMatchPack[], files: readonly OfferedFile[]): Promise<FileMatchReading>;
+/** The reading as the `files` member of `--json`, identical in both kernels. */
+export declare function fileMatchToJson(reading: FileMatchReading): Record<string, unknown>;
+/** The text report's lines for the reading, identical in both kernels. */
+export declare function renderFileMatch(reading: FileMatchReading): string[];