@sanning/proof 0.19.1 → 0.20.0

package/src/verifier.ts

@@ -1,71 +1,33 @@
-// Independent client-side implementation of the envelope verification
-// algorithm (specs/envelope-spec.md). This is deliberately a second
-// implementation of the same algorithm the Go kernel runs — a second,
-// conformance-tested verifier is what demonstrates the product's claim:
-// verification needs no Sanning code in the trust path.
-//
-// Conformance is enforced by test/conformance.test.ts, which runs every
-// corpus test vector through this code and asserts byte-for-byte agreement.
+// Client-side envelope verification (specs/envelope-spec.md), an independent
+// implementation so that verification needs no Sanning code in the trust path.
+// test/conformance.test.ts holds it to every corpus vector.
 
 import canonicalize from "canonicalize";
 
 import { SIGNATURE_FAILED, ed25519Refusal, isHexField, sha256Hex, utf8 } from "./crypto.js";
-import type { ContentRole, Envelope, VerificationResult, VerifyOptions } from "./types.js";
-
-// Fail-closed accepted-profile registry (envelope-spec §2): exactly the
-// accepted profile majors, nothing else. Minors within an accepted
-// major ("sanning.agent/v1.<minor>") are additive and tolerated — matching the Go
-// reference kernel's semantics (pkg/proof isSupportedSpec) so the kernels do
-// not diverge on minors. Accepting a new profile is a deliberate one-entry
-// addition HERE and only here. sanning.events/v2 (external commitment + Minimal
-// disclosure; envelope-spec §4) is verified through the SAME primitives — the
-// signed scope is still envelope-minus-signature-minus-co_signatures, with no
-// profile-specific dialect (no underscore strip, that is mlflow-only).
-//
-// Exported for parity with the sibling kernels' registries — Python
-// `ACCEPTED_SPEC_MAJORS`, Go `SupportedSpecMajor` — so the accept-set is
-// assertable rather than inferable: test/accept-set.test.ts holds it to the
-// ratified §4/§5 set transcribed in cross-kernel/accept-set.json, and the
-// cross-kernel gate probes one signed envelope per identifier. This entry list
-// is NOT the ratified accept-set today: sanning.mlflow/v1 is in the ratified
-// set and absent here, an escalated divergence (cross-kernel/README.md
-// § Known divergences) whose resolution is a founder decision, not an edit.
-//
-// FROZEN, and that is load-bearing, not hygiene: `specVersionSupported` (and
-// therefore `verifyEnvelope`) reads THIS array, so an exported mutable one
-// would let any code sharing the module instance widen the accept-set of a
-// running verifier — `ACCEPTED_SPEC_MAJORS.push("x/v1")` and the kernel starts
-// admitting `x/v1`. `Object.freeze` makes that throw (the package is ESM, so
-// always strict mode) and the `readonly string[]` type rejects it at compile
-// time. The elements are strings, so a shallow freeze is a deep one. Pinned by
-// test/accept-set.test.ts "the exported registry cannot be widened at runtime".
+import type { ContentRole, Envelope, EnvelopeFault, VerificationResult, VerifyOptions } from "./types.js";
+import { ENVELOPE_FAULTS } from "./types.js";
+
+// Fail-closed accepted-profile registry (envelope-spec section 2): exactly these
+// majors. Numeric minors within an accepted major are additive and tolerated.
+// Accepting a profile is a one-entry addition here and only here.
+// test/accept-set.test.ts holds it to cross-kernel/accept-set.json;
+// sanning.mlflow/v1 is a known divergence (cross-kernel/README.md).
 //
-// `sanning.events/v2` replaced `sanning.events/v1` in the producer-to-agent cut
-// (envelope-spec A10, governance.md §8 W-3). The old major is rejected like any
-// other unknown one: DL-73 keeps no reader for it.
-export const ACCEPTED_SPEC_MAJORS: readonly string[] = Object.freeze([
-  "sanning.agent/v1",
-  "sanning.events/v2",
-]);
-
-// Maximum JSON container-nesting depth a verifier will canonicalize. Inputs
-// nested deeper are rejected as malformed BEFORE canonicalization runs. This is
-// a NORMATIVE cross-kernel invariant (envelope-spec §2 shared-invariant 7): the
-// bound must be the same fixed constant in every kernel. Without it, a
-// deeply-nested body one kernel canonicalizes on its large native stack while
-// another hits its recursion limit (CPython defaults to ~1000 frames) yields a
-// split verdict — the same bytes reported `verified`/`failed` by one kernel and
-// crash/`malformed` by another, on a depth the producer of the bytes fully
-// controls. 128 is >10x any legitimate evidence structure (which nests <15) and
-// safely under the tightest kernel recursion limit, with headroom for the JCS
-// library's own frames-per-level. Mirrors the Python kernel's MAX_CANONICAL_DEPTH.
+// Frozen because `verifyEnvelope` reads this array: a mutable export would let
+// any code sharing the module widen a running verifier's accept-set.
+export const ACCEPTED_SPEC_MAJORS: readonly string[] = Object.freeze(["sanning.events/v2"]);
+
+// Maximum JSON nesting depth a verifier canonicalizes; deeper input is
+// malformed before canonicalization runs (envelope-spec §2 shared invariant 7).
+// Every kernel must use the same bound, or a producer-chosen depth splits the
+// verdict between a kernel that recurses and one that hits its stack limit.
+// Matches Python's MAX_CANONICAL_DEPTH.
 export const MAX_CANONICAL_DEPTH = 128;
 
-// Returned by `boundedInput` in place of a value that nests past the bound.
 // A symbol, so no input can forge it.
 const OVER_DEEP = Symbol("canonicalization input nests past the bound");
 
-// The serializer's own test (`object.toJSON instanceof Function`), on an object.
 function hasToJSON(node: unknown): boolean {
   return (
     node !== null &&
@@ -74,11 +36,8 @@ function hasToJSON(node: unknown): boolean {
   );
 }
 
-// Follow `node.toJSON()` until the value has none, which is what the serializer
-// does (`serialize(object.toJSON())`: in place, at the same depth). Bounded,
-// because the serializer burns a stack frame per hop: a `toJSON` that keeps
-// returning another `toJSON` object is over-deep, not something to follow
-// forever.
+// Follow `node.toJSON()` as the serializer does, bounded: a chain of `toJSON`
+// objects is over-deep, not something to follow forever.
 function resolveToJSON(node: unknown, max: number): unknown {
   let resolved = node;
   for (let hops = 0; hasToJSON(resolved); hops++) {
@@ -88,42 +47,17 @@ function resolveToJSON(node: unknown, max: number): unknown {
   return resolved;
 }
 
-// Bound nesting AND resolve `toJSON`, in one pass, returning the value the rest
-// of `jcs` must use: a structure with every `toJSON` already resolved, so
-// `canonicalize` never calls one itself. `OVER_DEEP` if any container nests
-// deeper than `max` levels. The root container is depth 1; each nested
-// array/object is one deeper; scalars have no children and never increase depth.
-//
-// Deliberately NOT recursive: this runs on already-parsed, possibly-hostile
-// input, so it must never itself overflow the call stack — it walks an explicit
-// heap stack instead.
-//
-// It returns a resolved COPY rather than checking the caller's value in place,
-// and that is the load-bearing part. `canonicalize` serializes `object.toJSON()`
-// IN PLACE OF the object and recurses into the result, so a guard that only
-// LOOKS at what `toJSON` returns and then lets the serializer ask again calls it
-// twice, and the two answers need not match: an unstable `toJSON` hands the
-// guard a shallow value and the serializer a deep one, which is the overflow the
-// bound exists to prevent, reached through the bound (proof#71 review). Copying
-// what was measured is what makes check and use the same value. It also settles
-// a getter, which is read once here and never re-read.
-//
-// Every object copy has a NULL prototype, and that is load-bearing too. RFC
-// 8785 has no reserved member names, and `JSON.parse` keeps `__proto__` as an
-// ordinary own key. On a plain `{}`, `copy["__proto__"] = x` runs the setter
-// inherited from `Object.prototype`: it replaces the copy's prototype and
-// creates no key, so the member and everything under it vanished from the
-// canonical bytes. Content there was covered by no hash and no signature, and
-// this kernel disagreed with the Python and Go kernels on the same bytes
-// (0.9.0; the same bug class as proof#31 and proof#34). With no prototype
-// there is no setter, so every key, `__proto__` included, lands as an own data
-// property. `canonicalize` reads the copy with `Object.keys` and `object[key]`
-// and tests `toJSON instanceof Function`, none of which a prototype affects
-// for JSON data, so no other input's output changes.
+// Null prototype, so a `__proto__` key from `JSON.parse` lands as an own data
+// property instead of running the inherited setter and vanishing from the
+// canonical bytes (and from the hash and signature).
 function emptyObject(): Record<string, unknown> {
   return Object.create(null) as Record<string, unknown>;
 }
 
+// Bound nesting and resolve `toJSON` in one pass, returning a resolved copy
+// (or `OVER_DEEP`) for `jcs` to serialize. Iterative, because the input is
+// hostile. A copy, so the check and the serialization see the same value: an
+// unstable `toJSON` or getter cannot answer differently the second time.
 function boundedInput(value: unknown, max: number): unknown {
   const root = resolveToJSON(value, max);
   if (root === OVER_DEEP || root === null || typeof root !== "object") return root;
@@ -131,8 +65,6 @@ function boundedInput(value: unknown, max: number): unknown {
   const stack: Array<[object, Record<string, unknown> | unknown[], number]> = [[root, copy, 1]];
   while (stack.length > 0) {
     const [src, dst, depth] = stack.pop()!;
-    // `Object.entries` is what `canonicalize` walks for an object, and for an
-    // array it yields the same index keys its `reduce` visits.
     for (const [key, rawChild] of Object.entries(src)) {
       const child = resolveToJSON(rawChild, max);
       if (child === OVER_DEEP) return OVER_DEEP;
@@ -140,7 +72,7 @@ function boundedInput(value: unknown, max: number): unknown {
         (dst as Record<string, unknown>)[key] = child;
         continue;
       }
-      if (depth + 1 > max) return OVER_DEEP; // a container nested past the bound
+      if (depth + 1 > max) return OVER_DEEP;
       const childCopy: Record<string, unknown> | unknown[] = Array.isArray(child) ? [] : emptyObject();
       (dst as Record<string, unknown>)[key] = childCopy;
       stack.push([child, childCopy, depth + 1]);
@@ -149,45 +81,25 @@ function boundedInput(value: unknown, max: number): unknown {
   return copy;
 }
 
-// Test whether `value` nests JSON containers deeper than `max` levels. Same walk
-// `jcs` runs, so the predicate and the serialization agree by construction.
-// Callers holding a value with a `toJSON` pay for it once per call: this runs it,
-// and so does the `jcs` that usually follows. Within `jcs` itself it runs once.
+// Whether `value` nests JSON containers deeper than `max`. Same walk as `jcs`,
+// so the predicate and the serialization agree.
 export function exceedsDepth(value: unknown, max: number): boolean {
   return boundedInput(value, max) === OVER_DEEP;
 }
 
 /**
- * The bytes an envelope's inline `payload` commits to: `JCS(payload)`. The ONE
- * place this is spelled: `verifyEnvelope` binds `payload_hash` against these
- * bytes, and the chain links rule 11 reads (`readChainLinks`) read an inline
- * record through them, so the binding rule and the linkage rule cannot
- * disagree about which bytes a record is. Throws where the payload cannot be
- * canonicalized. The twin is Python's `inline_payload_bytes`.
+ * The bytes an envelope's inline `payload` commits to: `JCS(payload)`. The one
+ * place this is defined, so payload binding and chain linkage agree on a
+ * record's bytes. Throws where the payload cannot be canonicalized.
  */
 export function inlinePayloadBytes(envelope: { payload: unknown }): Uint8Array {
   return utf8(jcs(envelope.payload));
 }
 
-// RFC 8785 (JCS) canonicalization. The `canonicalize` package is the reference
-// JS implementation; correctness is pinned by the conformance vectors.
-//
-// Nesting is bounded FIRST (MAX_CANONICAL_DEPTH): the depth guard throws before
-// `rejectLoneSurrogates` (recursive) or `canonicalize` (recursive) ever see the
-// input, so neither can overflow, and a too-deep input is a caller/input error
-// that the callers bucket as malformed (same contract as a malformed key).
-//
-// Both of them then see `boundedInput`'s output, never the caller's value. That
-// is what makes the two checks below true of what actually gets serialized: the
-// bound holds against an unstable `toJSON`, and a lone surrogate behind a
-// `toJSON` is seen rather than emitted (proof#71 and its review).
-//
-// Lone (unpaired) UTF-16 surrogates are REJECTED, never passed through: RFC
-// 8785 requires well-formed UTF-8 output, JS strings can carry lone
-// surrogates that `canonicalize` would emit as-is, and the sibling kernels
-// cannot represent them (Python raises on encode; Go's JSON decoder replaces
-// them). Reject-only is the one behavior all three kernels can share —
-// pinned here and by the corpus lone-surrogate negative.
+// RFC 8785 (JCS) canonicalization. Nesting is bounded first, so neither
+// recursive step can overflow; a too-deep input throws and callers treat it as
+// malformed. Lone UTF-16 surrogates are rejected, never emitted: RFC 8785
+// requires well-formed UTF-8, and no other kernel can represent them.
 export function jcs(value: unknown): string {
   const input = boundedInput(value, MAX_CANONICAL_DEPTH);
   if (input === OVER_DEEP) {
@@ -203,58 +115,23 @@ export function jcs(value: unknown): string {
   return canonical;
 }
 
-// The byte-order mark, as a CHARACTER. RFC 8785 output never begins with
-// U+FEFF, so bytes that do are not conformant whatever a JSON reader makes of
-// them.
+// RFC 8785 output never begins with U+FEFF.
 const JCS_BOM = "";
 
-/**
- * Read bytes that claim to be `jcs(value)` (RFC 8785), strictly. The Python
- * twin is `jcs_loads` in `src/sanning_proof/canonicalize.py`, and every site in
- * either kernel that reads bytes a producer signed goes through one of the two.
- *
- * ONE RULE, SPELLED OUT, BECAUSE TWO BUILT-INS ARE NOT ONE RULE. Five checks
- * carry it, none of them left to a decoder's defaults: strict UTF-8, no leading
- * byte-order mark, no non-finite literal (this kernel's `JSON.parse` rejects
- * `NaN`, `Infinity` and `-Infinity` natively, and Python names them in a
- * `parse_constant` hook), no object that repeats a member name
- * (`DuplicateKeyError`, proof#144), and no unpaired surrogate in the parsed
- * value.
- *
- * THE FOURTH CHECK IS NOT THE FIRST ONE TWICE. The strict decode refuses a
- * surrogate written as raw bytes; it cannot see one written as the ASCII
- * escape `\ud800`, which `JSON.parse` turns into a lone code unit AFTER the
- * decode has passed. `"c\ud800x"` is pure ASCII on the wire, so this reader
- * accepted it while its own text above said it does not, and one poisoned
- * record then deleted the Python kernel's whole chain reading (the gate on
- * proof#154). Both spellings are the same malformed record, and both are
- * refused here.
- *
- * `new TextDecoder()` alone is none of that. It replaces every invalid sequence
- * with U+FFFD and strips a BOM. Python's `json.loads(<bytes>)` is not it
- * either, in the opposite direction: CPython sniffs the encoding and decodes
- * with `errors="surrogatepass"`, so it strips a UTF-8 BOM, accepts a UTF-16 or
- * UTF-32 body, and passes a lone surrogate and a CESU-8 pair through. Both
- * defaults have shipped a split verdict on one pack: a raw `0x80` inside a
- * stamp body read `verified` here and `failed` there (gate 4), and then a
- * `BOM + JCS(record)` checkpoint read `verified` there and `mixed` here (gate
- * 5), both on proof#140. JCS is defined over UTF-8 and I-JSON (RFC 7493)
- * forbids a lone surrogate, so each of those inputs is MALFORMED rather than
- * another spelling of the same record.
- *
- * Throws for anything that is not conformant; every call site treats a throw as
- * "this reader cannot read these bytes" and names the check that failed.
- */
-/**
- * Bytes as strict UTF-8, a leading byte-order mark KEPT as a character.
- * `utf8_strict` in the Python twin's `canonicalize.py` is the same rule, and
- * `jcsParse` below performs the identical decode. Throws on bytes that are not
- * UTF-8.
- */
+/** Bytes as strict UTF-8, a leading byte-order mark kept as a character. Throws on invalid UTF-8. */
 export function utf8Strict(bytes: Uint8Array): string {
   return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
 }
 
+/**
+ * Read bytes that claim to be `jcs(value)`, strictly: valid UTF-8, no leading
+ * BOM, no non-finite literal, no repeated member name, and no unpaired
+ * surrogate (including one written as a `\ud800` escape). Every site that reads
+ * bytes a producer signed goes through this or its Python twin `jcs_loads`, so
+ * the kernels cannot split on decoder defaults.
+ *
+ * @throws When the bytes are not conformant.
+ */
 export function jcsParse(bytes: Uint8Array): unknown {
   const text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
   if (text.startsWith(JCS_BOM)) throw new Error("jcsParse: leading byte-order mark");
@@ -264,97 +141,8 @@ export function jcsParse(bytes: Uint8Array): unknown {
 }
 
 /**
- * Whether the bytes nest arrays and objects deeper than `max`, read from the
- * bytes before any parser sees them: the greatest number of `[` and `{` open
- * at once outside strings. A `"` opens a string and the next `"` no `\`
- * escapes closes it; a `]` or `}` outside a string closes one open level, if
- * one is open. Defined for every byte string, JSON or not. The Python twin is
- * `exceeds_text_depth` in `canonicalize.py`.
- *
- * On the bytes because a parser's own limit is its host's: CPython 3.10
- * stops near 1,000 levels, `JSON.parse` and CPython 3.13 read far deeper, Go's
- * decoder stops at 10,000 (enclave-attestation section 2.1).
- */
-export function exceedsTextDepth(bytes: Uint8Array, max: number): boolean {
-  let brackets = 0;
-  for (let i = 0; i < bytes.length; i++) {
-    const b = bytes[i]!;
-    if (b === 0x5b || b === 0x7b) brackets++;
-  }
-  if (brackets <= max) return false; // it cannot open more levels than it has brackets
-  let depth = 0;
-  let inString = false;
-  let escaped = false;
-  for (let i = 0; i < bytes.length; i++) {
-    const b = bytes[i]!;
-    if (inString) {
-      if (escaped) escaped = false;
-      else if (b === 0x5c) escaped = true;
-      else if (b === 0x22) inString = false;
-    } else if (b === 0x22) {
-      inString = true;
-    } else if (b === 0x5b || b === 0x7b) {
-      if (++depth > max) return true;
-    } else if ((b === 0x5d || b === 0x7d) && depth > 0) {
-      depth--;
-    }
-  }
-  return false;
-}
-
-/**
- * Whether a parsed value holds a number no IEEE 754 double holds, at any
- * depth. `JSON.parse` reads `1e400`, and an integer of 400 digits, as
- * `Infinity`. Iterative: the value is a producer's. The Python twin is
- * `has_non_finite_number`.
- */
-export function hasNonFiniteNumber(value: unknown): boolean {
-  const stack: unknown[] = [value];
-  while (stack.length > 0) {
-    const node = stack.pop();
-    if (typeof node === "number") {
-      if (!Number.isFinite(node)) return true;
-    } else if (Array.isArray(node)) {
-      for (const child of node) stack.push(child);
-    } else if (typeof node === "object" && node !== null) {
-      for (const child of Object.values(node)) stack.push(child);
-    }
-  }
-  return false;
-}
-
-/**
- * The deepest a JSON text an enclave reader parses may nest, and the depth
- * every kernel canonicalizes to (`MAX_CANONICAL_DEPTH`).
- */
-export const MAX_READ_DEPTH = MAX_CANONICAL_DEPTH;
-
-/**
- * `jcsParse`, within the reader limits of enclave-attestation section 2.1:
- * the bytes nest at most `MAX_READ_DEPTH` levels, checked on the bytes first,
- * and every number in the value is a finite double. Throws past either limit,
- * and wherever `jcsParse` throws. The Python twin is `jcs_loads_within_limits`.
- */
-export function jcsParseWithinLimits(bytes: Uint8Array): unknown {
-  if (exceedsTextDepth(bytes, MAX_READ_DEPTH)) {
-    throw new Error(`jcsParseWithinLimits: nests deeper than ${MAX_READ_DEPTH} levels`);
-  }
-  const value = jcsParse(bytes);
-  if (hasNonFiniteNumber(value)) throw new Error("jcsParseWithinLimits: holds a number no double holds");
-  return value;
-}
-
-/**
- * A JSON object that names one member twice (I-JSON, RFC 7493 section 2.3).
- * The Python twin is `DuplicateKey` in `canonicalize.py`, and the message is
- * the same kernel wording in both: `duplicate key ` and the name as
- * `renderKey` spells it.
- *
- * JCS (RFC 8785) is defined over I-JSON, and I-JSON forbids duplicate member
- * names, so bytes that repeat a name are MALFORMED rather than another spelling
- * of the last value. `JSON.parse` and Python's `json.loads` both keep the last
- * value and say nothing, which let a bundle carrying `"spec_version":"junk"`
- * before its real `spec_version` read `verified` in both kernels (proof#144).
+ * A JSON object that names one member twice. I-JSON (RFC 7493 §2.3) forbids it,
+ * so the bytes are malformed rather than a spelling of the last value.
  */
 export class DuplicateKeyError extends Error {
   readonly key: string;
@@ -364,17 +152,13 @@ export class DuplicateKeyError extends Error {
   }
 }
 
-// The longest rendered name a message carries, in characters, before it is
-// cut. The rendering is pure ASCII, so the cut lands on the same character in
-// both kernels.
+// Rendering is pure ASCII, so the cut lands on the same character in every kernel.
 const RENDERED_KEY_MAX = 64;
 
 /**
- * A member name as a quoted, pure-ASCII string, identically in both kernels
- * (`render_key` in the Python twin). Printable ASCII other than `"` and `\` is
- * kept; `"` and `\` are backslash-escaped; every other UTF-16 code unit is
- * `\uXXXX` in lower-case hex. A rendering longer than 64 characters is cut
- * there and `...` follows the closing quote.
+ * A member name as a quoted, pure-ASCII string, identical in both kernels.
+ * Printable ASCII is kept (`"` and `\` escaped), every other code unit is
+ * `\uXXXX`, and anything past 64 characters is cut with `...`.
  */
 export function renderKey(key: string): string {
   let body = "";
@@ -390,13 +174,10 @@ export function renderKey(key: string): string {
 }
 
 /**
- * `JSON.parse(text)`, refusing an object that repeats a member name. The Python
- * twin is `loads_refusing_duplicates` in `canonicalize.py`.
+ * `JSON.parse(text)`, refusing an object that repeats a member name. Parses
+ * first, so non-JSON fails as JSON, then rescans for repeats.
  *
- * `JSON.parse` cannot see a repeat, because it keeps the last value, so the
- * text is scanned once more AFTER it parsed. The parse runs first, so text
- * that is not JSON at all fails as JSON and never as a duplicate, as it does in
- * the Python twin. Throws `DuplicateKeyError`.
+ * @throws DuplicateKeyError
  */
 export function parseRefusingDuplicates(text: string): unknown {
   const value: unknown = JSON.parse(text);
@@ -406,23 +187,13 @@ export function parseRefusingDuplicates(text: string): unknown {
 }
 
 /**
- * The repeated member name to report for text `JSON.parse` has already
- * accepted, or `undefined` when no object repeats one.
- *
- * WHICH ONE, because both kernels must name the same one. Objects are checked
- * as they CLOSE, innermost first, which is the order Python's
- * `object_pairs_hook` sees them in; inside one object the name reported is the
- * first whose repeat comes earliest. Names compare after unescaping, so `"a"`
- * and `"\u0061"` are one name, as they are to both parsers.
- *
- * ITERATIVE, with an explicit stack, for the reason `rejectUnpairedSurrogates`
- * is: this walks bytes a producer wrote. It relies on the text being valid
- * JSON, which is why it runs only after `JSON.parse` succeeded: outside a
- * string, only `{`, `[`, `}`, `]`, `,` and `"` change what comes next.
+ * The repeated member name to report, or `undefined`. Objects are checked as
+ * they close, innermost first, matching Python's `object_pairs_hook`, so both
+ * kernels name the same key. Iterative, because the text is producer-written;
+ * runs only on text `JSON.parse` accepted.
  */
 export function firstDuplicateKey(text: string): string | undefined {
-  // `names` is null for an array. `expectName` is true where the next string
-  // is a member name rather than a value.
+  // `names` is null for an array; `expectName` marks the next string as a key.
   const stack: Array<{ names: Set<string> | null; expectName: boolean; dup?: string }> = [];
   const n = text.length;
   let i = 0;
@@ -464,15 +235,8 @@ export function firstDuplicateKey(text: string): string | undefined {
 }
 
 /**
- * Refuse a parsed value carrying an unpaired surrogate, in a key or a value, at
- * any depth. The Python twin is `_reject_unpaired_surrogates`, and the two name
- * the failure with the same words.
- *
- * Deliberately ITERATIVE. `rejectLoneSurrogates` below walks a value this
- * kernel is about to serialize, which `boundedInput` has already depth-bounded.
- * This one walks whatever `JSON.parse` returned for a producer's bytes, with no
- * bound in front of it, so a recursive walk would turn a deeply-nested record
- * into a `RangeError` out of the reader itself.
+ * Refuse a parsed value carrying an unpaired surrogate, in a key or value, at
+ * any depth. Iterative: the parsed value has no depth bound in front of it.
  */
 function rejectUnpairedSurrogates(value: unknown): void {
   const stack: unknown[] = [value];
@@ -491,9 +255,7 @@ function rejectUnpairedSurrogates(value: unknown): void {
   }
 }
 
-// Walk every string in the value (keys and values). The check must run on
-// the INPUT: `canonicalize` escapes a lone surrogate as `\udXXX` text in its
-// output, so the malformed code unit is invisible after serialization.
+// Must run on the input: `canonicalize` escapes a lone surrogate, hiding it.
 function rejectLoneSurrogates(value: unknown): void {
   if (typeof value === "string") {
     if (hasLoneSurrogate(value)) {
@@ -521,7 +283,7 @@ function hasLoneSurrogate(s: string): boolean {
     if (c >= 0xd800 && c <= 0xdbff) {
       const next = i + 1 < s.length ? s.charCodeAt(i + 1) : 0;
       if (next >= 0xdc00 && next <= 0xdfff) {
-        i++; // valid pair
+        i++;
         continue;
       }
       return true; // high surrogate without a low
@@ -531,13 +293,9 @@ function hasLoneSurrogate(s: string): boolean {
   return false;
 }
 
-// Grammar-strict accept check (envelope-spec §2): `<major>` exactly, or
-// `<major>.<minor>` where minor is `[0-9]+`. A non-numeric minor suffix is
-// malformed, not a tolerated future version — matching the Python kernel's
-// 0.1.1 semantics (the TS/Go fail-open lenience was closed deliberately).
-//
-// `accepted` NARROWS the registry and never widens it, as the Python twin's
-// `spec_version_supported(spec_version, accepted)` does (P-10, 0.13.0).
+// Grammar-strict accept check (envelope-spec section 2): `<major>` or
+// `<major>.<digits>`. Any other suffix is malformed. `accepted` narrows the
+// registry and never widens it.
 export function specVersionSupported(
   specVersion: string,
   accepted?: readonly string[],
@@ -553,20 +311,9 @@ export function specVersionSupported(
   });
 }
 
-// `signed_at` format (envelope-spec §2: "RFC 3339 UTC, `Z`"), proof#95. The
-// accepted form is RFC 3339 `date-time` narrowed three ways, identically in
-// every kernel:
-//   - the zone is an uppercase `Z`: never a numeric offset (not even
-//     `+00:00`), never a lowercase `z` or `t`;
-//   - the date is a real proleptic Gregorian date from 0001-01-01 to
-//     9999-12-31, so February 29 only in a leap year;
-//   - second 60 is refused. RFC 3339 allows it at a real leap second, but
-//     which instants those were needs a table, and JavaScript's `Date`,
-//     Python's `datetime` and Go's `time` cannot hold one, so a verified `:60`
-//     would fail the first consumer that parses it.
-// Fractional seconds of any length are allowed. Digits are ASCII `[0-9]`
-// (Python's `\d` matches any Unicode digit, so the Python kernel spells it the
-// same way).
+// `signed_at` (envelope-spec section 2): RFC 3339 `date-time`, identically in every
+// kernel: uppercase `Z` only, a real date from 0001-01-01 to 9999-12-31, and no
+// second 60 (no common runtime can hold a leap second). ASCII digits only.
 const RFC3339_UTC = /^([0-9]{4})-([0-9]{2})-([0-9]{2})T([0-9]{2}):([0-9]{2}):([0-9]{2})(?:\.[0-9]+)?Z$/;
 const DAYS_IN_MONTH = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
 
@@ -581,28 +328,12 @@ export function isRfc3339UtcInstant(value: unknown): boolean {
   return day <= days && hour <= 23 && minute <= 59 && second <= 59;
 }
 
-// The skeleton fields whose FORMAT §2 fixes and no other check reaches: a
-// correctly signed envelope with `signed_at: "2026-02-30T00:00:00Z"` or
-// `environment: "prod\u0000uction"` passes the signature and the payload
-// binding, so without this it verified in full. Each is checked only when
-// present: §2 flags an absent `signed_at` as non-conformant rather than
-// rejecting it, and `environment` is optional in the skeleton.
-//
-// `public_key` AND `signature` ARE CHECKED HERE TOO (proof#146, under
-// proof#135 option B). The strict `hexToBytes` inside `ed25519Verify` is what
-// makes the three kernels agree on the VERDICT; naming the spelling is what
-// makes them agree on the REASON. On its own a respelled key reads `Ed25519
-// signature verification failed`, which sends an auditor looking for a forged
-// signature that is not there. proof#135 was opened against this function's
-// Python twin, for covering `signed_at` and `environment` and not `public_key`.
-//
-// ONLY A STRING IS CHECKED, the same rule `envelopeHexError` follows one layer
-// up: an absent or non-string `public_key` is already a failed signature in all
-// three kernels (Go names it "missing signature or public_key"), and naming it
-// here as a spelling would state one fact twice and in the wrong words. CASE IS
-// NOT CHECKED: proof#135 pinned the charset and left the case open.
-//
-// Own properties only, because those are the members `jcs` signs over.
+// The skeleton fields whose format §2 fixes and no other check reaches; each is
+// checked only when present. A well-signed envelope with an impossible
+// `signed_at` would otherwise verify in full. `public_key` and `signature` are
+// checked here so a respelled key is named as a spelling, not reported as a
+// forged signature; only strings are checked, and case is not. Own properties
+// only, because those are what `jcs` signs.
 function skeletonFieldErrors(env: Envelope): string[] {
   const fields = env as unknown as Record<string, unknown>;
   const own = (k: string): unknown => (Object.prototype.hasOwnProperty.call(fields, k) ? fields[k] : undefined);
@@ -613,72 +344,60 @@ function skeletonFieldErrors(env: Envelope): string[] {
   ] as const) {
     const value = own(name);
     if (typeof value === "string" && !isHexField(value, nibbles)) {
-      out.push(`malformed ${name}: not ${nibbles} hex characters (envelope-spec §2)`);
+      out.push(`malformed ${name}: not ${nibbles} hex characters (envelope-spec section 2)`);
     }
   }
   const signedAt = own("signed_at");
   if (signedAt !== undefined && !isRfc3339UtcInstant(signedAt)) {
-    out.push("malformed signed_at: not an RFC 3339 UTC date-time with Z naming a real date and time (envelope-spec §2)");
+    out.push("malformed signed_at: not an RFC 3339 UTC date-time with Z naming a real date and time (envelope-spec section 2)");
   }
   const environment = own("environment");
   if (environment !== undefined && environment !== "dev" && environment !== "production") {
-    out.push('malformed environment: not "dev" or "production" (envelope-spec §2)');
+    out.push('malformed environment: not "dev" or "production" (envelope-spec section 2)');
   }
   out.push(...identityFieldErrors(own));
   return out;
 }
 
-// The four fields envelope-spec §2 types and A23 pins (proof#97, proof#155).
-// Every pattern is anchored at both ends with no `m` flag, so `$` never matches
-// before a trailing newline, and uses ASCII classes only.
+// The four identity fields envelope-spec §2 types. Every pattern is anchored at
+// both ends, no `m` flag, ASCII classes only.
 //
-// `event_id`: "UUID v4, lowercase", the pattern both SDKs already refuse to
-// sign anything else under (`UUID_V4_RE` in `@sanning/anchor`, `_UUID_V4_RE` in
-// `sanning-anchor`); the Go agent's `uuid.NewString` emits the same.
+// `event_id`: UUID v4, lowercase, as both SDKs sign.
 const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
-// `payload_hash`: sha256-hex, which invariant 2 defines as lowercase hex with no
-// `0x`. Lower case is pinned here, unlike `public_key`, because every kernel
-// compares the value against a digest it recomputes in lower case: an
-// upper-case `payload_hash` already failed wherever there was material.
+// `payload_hash`: lowercase sha256 hex. Unlike `public_key`, case is pinned:
+// every kernel compares it against a lowercase recomputed digest.
 const SHA256_HEX = /^[0-9a-f]{64}$/;
-// `payload_ref`: §2 says "string (URI)" and names no grammar, so this pins what
-// both SDKs emit: an ASCII scheme, a colon, then RFC 3986 unreserved, reserved
-// and percent-encoded characters, at most 2048 of them in all (`REF_RE` and
-// `MAX_REF_LEN` in `@sanning/anchor`'s `ref.ts`).
+// `payload_ref`: §2 names no grammar, so this pins what the SDKs emit: an ASCII
+// scheme, a colon, RFC 3986 characters, at most 2048 in all.
 const URI_REF = /^[A-Za-z][A-Za-z0-9+.-]*:[A-Za-z0-9\-._~:/?#[\]@!$&'()*+,;=%]*$/;
 const MAX_URI_REF = 2048;
 // `subject`: "string fields <=128 chars matching `^[A-Za-z0-9_.:-]+$`".
 const SUBJECT_FIELD = /^[A-Za-z0-9_.:-]{1,128}$/;
 
-// `event_id`, `payload_hash`, `payload_ref` and `subject` (A23). Each is checked
-// only when present, and present includes a JSON null, as for `signed_at`.
-// `payload_hash` is the exception: only a STRING is checked here, because a
-// missing or non-string one is already `missing payload_hash` below, and naming
-// it twice would state one fact in two sets of words. `subject` fixes only its
-// STRING members: §2 types no other, so a member of another type is left as it
-// was. Own members only, as everywhere in this file. The messages are
-// byte-identical to the Python and Go kernels'.
+// Each checked only when present (including JSON null). `payload_hash` only as
+// a string: a missing one is reported below. `subject` checks only its string
+// members. Messages are byte-identical across kernels.
 function identityFieldErrors(own: (k: string) => unknown): string[] {
   const out: string[] = [];
   const eventId = own("event_id");
   if (eventId !== undefined && !(typeof eventId === "string" && UUID_V4.test(eventId))) {
-    out.push("malformed event_id: not a lowercase UUID v4 (envelope-spec §2)");
+    out.push("malformed event_id: not a lowercase UUID v4 (envelope-spec section 2)");
   }
   const payloadHash = own("payload_hash");
   if (typeof payloadHash === "string" && !SHA256_HEX.test(payloadHash)) {
-    out.push("malformed payload_hash: not 64 lowercase hex characters (envelope-spec §2)");
+    out.push("malformed payload_hash: not 64 lowercase hex characters (envelope-spec section 2)");
   }
   const payloadRef = own("payload_ref");
   if (
     payloadRef !== undefined &&
     !(typeof payloadRef === "string" && payloadRef.length <= MAX_URI_REF && URI_REF.test(payloadRef))
   ) {
-    out.push("malformed payload_ref: not a URI of at most 2048 RFC 3986 characters (envelope-spec §2)");
+    out.push("malformed payload_ref: not a URI of at most 2048 RFC 3986 characters (envelope-spec section 2)");
   }
   const subject = own("subject");
   if (subject !== undefined && !isWellFormedSubject(subject)) {
     out.push(
-      "malformed subject: not an object whose string fields are 1 to 128 characters of [A-Za-z0-9_.:-] (envelope-spec §2)",
+      "malformed subject: not an object whose string fields are 1 to 128 characters of [A-Za-z0-9_.:-] (envelope-spec section 2)",
     );
   }
   return out;
@@ -693,16 +412,14 @@ function isWellFormedSubject(subject: unknown): boolean {
   return true;
 }
 
-// The content hash(es) an envelope commits to, by event type — the values a
-// reverse lookup can match the user's in-browser file hash against.
-//   asset_registered -> payload.hash            (the registered, known-good bytes)
-//   asset_missing    -> payload.baseline.hash   (last known-good bytes that vanished)
-//   tamper_detected  -> payload.observed.hash   (the tampered bytes that were flagged)
-//                    -> payload.baseline.hash   (the known-good bytes it diverged from)
-// Other event types commit to no asset content hash.
+// The content hashes an envelope commits to, by event type: what a reverse
+// lookup matches a user's file hash against.
+//   asset_registered -> payload.hash            (the registered bytes)
+//   asset_missing    -> payload.baseline.hash   (last known-good bytes)
+//   tamper_detected  -> payload.observed.hash   (the flagged bytes)
+//                    -> payload.baseline.hash   (the known-good bytes)
 export function contentHashes(env: Envelope): { role: ContentRole; hash: string }[] {
-  // Minimal-disclosure / external-commitment envelopes have no inline payload
-  // (and no event_type) — they commit to no envelope-readable content hash.
+  // External-commitment envelopes have no inline payload, so no hash here.
   const p = (env.payload ?? {}) as {
     hash?: unknown;
     baseline?: { hash?: unknown };
@@ -733,46 +450,29 @@ export function contentHashes(env: Envelope): { role: ContentRole; hash: string
   return out;
 }
 
-// Verify an envelope — both binding modes (envelope-spec §3), one rule,
-// mirroring the Python reference kernel exactly:
+// Verify an envelope in either binding mode (envelope-spec §3):
 //
-//   - envelope carries `payload`        → inline check: recompute
-//     SHA-256(JCS(payload)) and compare to payload_hash
-//   - caller supplies `payloadBytes`    → external check:
-//     SHA-256(payloadBytes) must equal payload_hash
-//   - both available                    → both must pass
-//   - neither                           → payloadHashOk = null and the
-//     verdict does NOT fail: "signature-valid, semantics-undetermined"
-//     (§3.1/§6.2). The signature alone still proves who signed what bytes.
+//   - inline `payload`        -> SHA-256(JCS(payload)) must equal payload_hash
+//   - supplied `payloadBytes` -> SHA-256(payloadBytes) must equal payload_hash
+//   - both                    -> both must pass
+//   - neither                 -> payloadHashOk = null, and the verdict does not
+//     fail: the signature still proves who signed what (§3.1, §6 item 2).
 //
-// payload_hash itself MUST be present (a string) in every mode — its
-// absence is rejected per envelope-spec §2, independent of whether there is
-// material to compare it against.
-//
-// Binding-mode detection is structural, not registry-driven: mode confusion
-// is closed by the signed scope itself (an inline payload is INSIDE the
-// signature, so stripping it to fake "external" — or injecting one to fake
-// "inline" — breaks the signature).
-//
-// The second argument is a VerifyOptions object ({ payloadBytes,
-// expectedContentHash, acceptedSpecMajors }). Until 0.13.0 it could also be a
-// bare `expectedContentHash` string; that overload is gone (P-10), so the two
-// kernels take one options shape: write `{ expectedContentHash: hash }`.
+// `payload_hash` must be present in every mode. Mode detection is structural:
+// an inline payload is inside the signed scope, so adding or stripping one
+// breaks the signature.
 export async function verifyEnvelope(
   env: Envelope,
   options?: VerifyOptions,
 ): Promise<VerificationResult> {
   if (typeof options === "string") {
     throw new TypeError(
-      "verifyEnvelope: pass { expectedContentHash } rather than a bare string (0.13.0)",
+      "verifyEnvelope: pass { expectedContentHash } rather than a bare string",
     );
   }
   const opts: VerifyOptions = options ?? {};
-  // REFUSE an unknown option key rather than ignore it. `expected_content_hash`
-  // — the Python kernel's spelling — previously fell through as `undefined`, so
-  // the content bind silently never ran and the caller got a clean pass with no
-  // errors at all. A check that quietly does not happen is worse than one that
-  // fails: the caller believes they verified an artifact they never checked.
+  // Refuse an unknown option rather than ignore it: a misspelled option would
+  // otherwise skip its check and report a clean pass.
   const KNOWN_VERIFY_OPTIONS = new Set(["payloadBytes", "expectedContentHash", "acceptedSpecMajors"]);
   const unknownOptions = Object.keys(opts).filter((k) => !KNOWN_VERIFY_OPTIONS.has(k));
   if (unknownOptions.length > 0) {
@@ -782,36 +482,24 @@ export async function verifyEnvelope(
         "Option keys are camelCase in the TypeScript kernel; the Python kernel uses snake_case.",
     );
   }
-  // ── A verifier never raises on an input (proof#85 item 3) ──
-  //
-  // The option check above is the one exception and stays OUTSIDE this try: an
-  // unknown option key is the CALLER's mistake, not the envelope's, and turning
-  // a typo into a verdict is how a check silently never runs.
-  //
-  // Below, every field read is a read of attacker-shaped data. `env` is typed
-  // as an `Envelope`, but nothing enforces that at runtime, and an object whose
-  // property reads throw (a `get`-trap `Proxy`, a getter that raises, an
-  // exotic object from another realm) passed the null/non-object guard and then
-  // escaped as a raised exception. An auditor cannot tell a raised exception
-  // apart from a broken tool, which is the one thing this kernel exists not to
-  // hand them. CLAUDE.md states the rule flatly: malformed envelopes return a
-  // failed `VerificationResult`, they do not throw. This closes the class, not
-  // the one `Proxy` case: #77 hardened the anchor-trace path for the same
-  // reason, and a per-input patch would have to be written again for the next
-  // exotic object.
+  // A verifier never throws on an input: a raised exception is
+  // indistinguishable from a broken tool. Every field read below is of
+  // attacker-shaped data (a throwing getter or `Proxy` included). The option
+  // check above stays outside, because a bad option is the caller's mistake.
   try {
     return await verifyEnvelopeChecked(env, opts);
   } catch {
     return {
       ok: false,
       specVersionOk: false,
-      // `null`, never `false`: nothing was read, so nothing was determined.
-      // The same rule the not-a-JSON-object branch below follows.
+      // `null`: nothing was read, so nothing was determined.
       payloadHashOk: null,
       signatureOk: false,
       contentHashOk: opts.expectedContentHash === undefined ? null : false,
       contentRole: null,
       errors: ["envelope could not be read"],
+      fault: "not_an_envelope",
+      faults: ["not_an_envelope"],
     };
   }
 }
@@ -823,40 +511,26 @@ async function verifyEnvelopeChecked(
   const expectedContentHash = opts.expectedContentHash;
   const errors: string[] = [];
 
-  // Guard a malformed input (null / non-object / array) up front — every field
-  // access below assumes an object. A hostile gateway or a hand-edited report
-  // can supply anything; treat it as "not verified," never a thrown exception.
+  // Malformed input is "not verified", never a thrown exception.
   if (env === null || typeof env !== "object" || Array.isArray(env)) {
     return {
       ok: false,
       specVersionOk: false,
-      // `null`, not `false` (proof#62). This field carries "we cannot tell"
-      // against "it is wrong", and that distinction is what the whole
-      // minimum-disclosure posture rests on: a withheld record is `null` BY
-      // DESIGN and must never read as a failure (`evidence-bundle.md` §3.1,
-      // §6.2). There is no envelope here, so there is nothing to bind and
-      // nothing was determined. `false` asserted a binding had been checked
-      // and had failed, which is a claim this branch cannot support.
-      //
-      // The Python kernel already answered `None`, so the two disagreed on
-      // the dimension `verify-page` renders: an auditor on one CLI saw a
-      // dimension that could not be determined, and on the other one that
-      // failed, for the same bytes. `ok` is `false` either way, so no rollup
-      // verdict changes; what changes is what we tell the reader.
-      //
-      // `contentHashOk` on the next line already follows this rule.
+      // `null`, not `false`: with no envelope nothing was determined, and a
+      // withheld binding must never read as a failure (envelope-spec.md §3.1).
       payloadHashOk: null,
       signatureOk: false,
       contentHashOk: expectedContentHash === undefined ? null : false,
       contentRole: null,
       errors: ["envelope is not a JSON object"],
+      fault: "not_an_envelope",
+      faults: ["not_an_envelope"],
     };
   }
 
   const specVersionOk = specVersionSupported(env.spec_version, opts.acceptedSpecMajors);
   if (!specVersionOk) {
-    // Absent or null reads "missing", as in the Python kernel. Everything else
-    // is quoted the way both kernels quote a value in a finding.
+    // Absent or null reads "missing"; anything else is quoted.
     errors.push(
       env.spec_version === undefined || env.spec_version === null
         ? "missing spec_version"
@@ -864,46 +538,31 @@ async function verifyEnvelopeChecked(
     );
   }
 
-  // Skeleton field format (envelope-spec §2, proof#95): a present `signed_at`
-  // or `environment` that is not what §2 says fails the verdict. There is no
-  // result field for it, so the verdict shape is unchanged for every envelope
-  // the spec allows; the reason is in `errors`.
+  // A present `signed_at` or `environment` in the wrong format fails the verdict, as does
+  // a missing `payload_hash`.
   const fieldErrors = skeletonFieldErrors(env);
+  if (typeof env.payload_hash !== "string") {
+    fieldErrors.push("missing payload_hash (envelope-spec section 2: required in every profile)");
+  }
   errors.push(...fieldErrors);
   const fieldsOk = fieldErrors.length === 0;
 
-  // Check 1 — Payload binding (both modes; see header).
-  //
-  // payload_hash MUST be present and a string in every mode — envelope-spec
-  // §2: "a verifier cannot proceed without spec_version / public_key /
-  // signature / payload_hash and MUST reject their absence." All three
-  // kernels enforce this (the Python reference's prior compare-only-if-present
-  // lenience was the bug; §2 is binding).
-  //
-  // When present, it is COMPARED only against material that exists — an
-  // inline payload, supplied committed bytes, or both. With neither, the
-  // binding is undetermined (null): "signature-valid, semantics-undetermined"
-  // (§3.1/§6.2). null does not fail the verdict; absence does.
+  // Check 1: payload binding. `payload_hash` is compared only against material that
+  // exists; with none it is undetermined (`null`), which does not fail. A hash that is not
+  // 64 hex characters binds nothing either; one in upper case is compared in lower case, so
+  // a hash in the wrong form reads as a form error, never as bytes that changed.
   //
-  // THE ENVELOPE'S OWN `payload_hash` IS NOT ECHOED INTO THESE REASONS, and
-  // that is a change (proof#154 F4). It is producer-controlled text of any
-  // length, and it went into an auditor-facing error list verbatim: a producer
-  // could put a newline and a forged `payload_hash: OK  envelope verified`
-  // line, or an ANSI escape that paints `VERIFIED` green, into what the
-  // verifier prints. No other field in this file echoes its value, the Python
-  // twin names the same failure without one, and the value is in the envelope
-  // the auditor already holds. Neither is the recomputed digest: the reason is
-  // the Python kernel's sentence, word for word (proof#150).
-  let payloadHashOk: boolean | null;
-  if (typeof env.payload_hash !== "string") {
-    payloadHashOk = false;
-    errors.push("missing payload_hash (envelope-spec §2: required in every profile)");
-  } else {
+  // The envelope's own `payload_hash` is never echoed into these reasons: it is
+  // producer-controlled text, and a newline or ANSI escape could forge lines in
+  // what the verifier prints.
+  let payloadHashOk: boolean | null = null;
+  if (typeof env.payload_hash === "string" && HEX64.test(env.payload_hash)) {
+    const storedHash = env.payload_hash.toLowerCase();
     const checks: boolean[] = [];
     if ("payload" in env && env.payload !== undefined) {
       try {
         const recomputed = await sha256Hex(inlinePayloadBytes(env as { payload: unknown }));
-        checks.push(recomputed === env.payload_hash);
+        checks.push(recomputed === storedHash);
       } catch {
         checks.push(false);
         errors.push("payload is not JCS-canonicalizable");
@@ -911,26 +570,19 @@ async function verifyEnvelopeChecked(
     }
     if (opts.payloadBytes !== undefined) {
       const external = await sha256Hex(opts.payloadBytes);
-      checks.push(external === env.payload_hash);
+      checks.push(external === storedHash);
     }
     payloadHashOk = checks.length > 0 ? checks.every(Boolean) : null;
-    // One sentence for a mismatch against the inline payload, the supplied
-    // bytes or both, and none when the payload could not be canonicalized: the
-    // Python kernel's rule, word for word (proof#150).
+    // One sentence for any mismatch; none when canonicalization failed.
     if (payloadHashOk === false && !errors.some((e) => e.startsWith("payload is not"))) {
       errors.push("payload_hash does not match the committed bytes");
     }
   }
 
-  // Check 2 — Signature Confirmed: Ed25519 over the signed scope, which is
-  // JCS(envelope minus `signature` minus `co_signatures`) per envelope-spec §2.
-  // The co_signatures carve-out (§7.1) lets a countersignature be added without
-  // invalidating the primary signature; the field is reserved/default-absent.
-  // The corpus has no co-signed vectors, so this strip is pinned by an explicit
-  // unit test rather than by conformance.
-  // The refusal names the clause of the Ed25519 rule a signature breaks
-  // (envelope-spec §7, A44), so a forged shape reads differently from a
-  // corrupted byte; an equation that does not hold reads the bare sentence.
+  // Check 2: Ed25519 over JCS(envelope minus `signature` and `co_signatures`)
+  // (§2). The `co_signatures` carve-out (§7.1) lets a countersignature be added
+  // later; a unit test pins it. The refusal names the clause of the Ed25519 rule
+  // that broke (§7).
   let signatureOk = false;
   try {
     const { signature: _signature, co_signatures: _coSignatures, ...envelopeForSig } = env;
@@ -938,33 +590,24 @@ async function verifyEnvelopeChecked(
     signatureOk = refusal === null;
     if (refusal !== null) errors.push(refusal);
   } catch {
-    // The sentence the Python kernel writes for the same failure. What was
-    // thrown is the host's wording (`jcs: input nesting exceeds ...`), and a
-    // public result carries the kernel's own words only (proof#150).
+    // The kernel's own sentence, never the host's thrown text.
     errors.push(SIGNATURE_FAILED);
   }
 
-  // Check 3 (optional) — Content Bind: the user's bytes match a hash this
-  // envelope commits to. The tag got us here; only this proves the bytes match.
+  // Check 3 (optional): content bind. Only this proves the user's bytes match.
   let contentHashOk: boolean | null = null;
   let contentRole: ContentRole | null = null;
   if (expectedContentHash !== undefined) {
     const committed = contentHashes(env);
     if (committed.length === 0) {
-      // UNDETERMINED, not failed. An external-commitment envelope
-      // (`sanning.events/v2`) has no inline payload, so it commits to no
-      // envelope-readable content hash and there is nothing here to compare
-      // against. Reporting that as a failure would render "we cannot check
-      // this" as "it did not match" — what P-10 and I-5 exist to prevent — and
-      // would fail every envelope on the DL-52 path.
-      //
-      // The caller is still told the check did not happen; silence would be
-      // worse than either verdict.
+      // Undetermined, not failed: an external-commitment envelope commits to
+      // no readable content hash, and "cannot check" must not read as "did not
+      // match". The caller is still told the check did not run.
       contentHashOk = null;
       errors.push(
         "this envelope commits to no readable content hash (external-commitment " +
-          "profile), so the provided content hash could not be checked — " +
-          "undetermined, not failed",
+          "profile), so the provided content hash could not be checked; " +
+          "not checked, not failed",
       );
     } else {
       const want = expectedContentHash.toLowerCase();
@@ -977,18 +620,14 @@ async function verifyEnvelopeChecked(
     }
   }
 
+  const faults: EnvelopeFault[] =
+    specVersionOk && fieldsOk && signatureOk && payloadHashOk !== false
+      ? []
+      : envelopeFaults(env, { signatureOk, payloadHashOk, specVersionOk, fieldsOk });
   return {
-    // null (binding not checkable) does not fail the verdict — Python-kernel
-    // parity: ok = spec && sig && payloadHashOk is not False.
-    // A supplied `expectedContentHash` that matches nothing this envelope
-    // commits to is a FAILING verdict, not a side note (proof#42). This is the
-    // check an external auditor runs — "does this file match what was
-    // anchored" — and reporting it only in `contentHashOk` meant the top-level
-    // verdict, the field a caller naturally reads, said pass over a file that
-    // does not match.
-    //
-    // Absence stays undetermined: `contentHashOk` is null when no hash was
-    // supplied, and null must not fail (P-10 — absence is not failure).
+    // `null` does not fail. A supplied `expectedContentHash` that matches
+    // nothing does: it is the check an auditor runs, and `ok` is what a caller
+    // reads.
     ok: specVersionOk && fieldsOk && signatureOk && payloadHashOk !== false && contentHashOk !== false,
     specVersionOk,
     payloadHashOk,
@@ -996,6 +635,43 @@ async function verifyEnvelopeChecked(
     contentHashOk,
     contentRole,
     errors,
+    fault: faults[0] ?? null,
+    faults,
   };
 }
 
+const ENVELOPE_MEMBERS = ["spec_version", "public_key", "signature", "payload_hash"];
+const HEX64 = /^[0-9a-fA-F]{64}$/;
+
+type FaultChecks = { signatureOk: boolean; payloadHashOk: boolean | null; specVersionOk: boolean; fieldsOk: boolean };
+
+/**
+ * Every one of `ENVELOPE_FAULTS` that applies, in that order. Each is judged without the
+ * others: a key that cannot be read checks no signature, and still the bytes are checked
+ * against `payload_hash`. A field's form is judged only under a signature that holds over a
+ * version this verifier knows.
+ */
+export function envelopeFaults(env: unknown, checks: FaultChecks): EnvelopeFault[] {
+  if (
+    env === null ||
+    typeof env !== "object" ||
+    Array.isArray(env) ||
+    !ENVELOPE_MEMBERS.some((m) => Object.prototype.hasOwnProperty.call(env, m))
+  ) {
+    return ["not_an_envelope"];
+  }
+  const found = new Set<EnvelopeFault>();
+  const key = (env as { public_key?: unknown }).public_key;
+  if (typeof key !== "string" || !HEX64.test(key)) found.add("key_unreadable");
+  else if (!checks.signatureOk) found.add("signature_failed");
+  if (checks.payloadHashOk === false) found.add("payload_unbound");
+  if (!checks.specVersionOk) found.add("spec_version_unknown");
+  else if (checks.signatureOk && !checks.fieldsOk) found.add("nonconforming");
+  return ENVELOPE_FAULTS.filter((f) => found.has(f));
+}
+
+/** The worst of `envelopeFaults`, or `null`. */
+export function envelopeFault(env: unknown, checks: FaultChecks): EnvelopeFault | null {
+  return envelopeFaults(env, checks)[0] ?? null;
+}
+