@sanning/proof 0.10.0 → 0.11.1

package/src/message-parts.ts

@@ -0,0 +1,998 @@
+/**
+ * A file part's BYTES, and what a receiver holding them commits to.
+ *
+ * `envelope-spec.md` section 4.1 (v1.13, amendment A18, proof#145, ratified by
+ * Phil 2026-09-22). The Python half is `src/sanning_proof/message_parts.py` and
+ * the two are held together by `cross-kernel/run_parts.sh`.
+ *
+ * THE DEFECT THIS CLOSES. Section 4.1 said "Binary and file parts are committed
+ * by their own content hash inside that canonical object" and stopped, which
+ * decided half of "an altered part fails". Measured against both SDKs
+ * (anchor#219, attack 1, in both languages): a transport that keeps a part's
+ * DESCRIPTOR and swaps its BYTES produces `accepted`. No exception, no finding,
+ * and nothing in either record: the descriptor's hash and the bytes' hash sit
+ * side by side and no rule ever compared them, so both sides commit to the same
+ * message object and the pair reads `verified`. Swapping the bytes AND the
+ * descriptor was caught all along. This is the sixth instance of one class in
+ * this section, "a deviation produces nothing and a reader is obliged to call
+ * it clean", and the repair is the same shape as A13's and A14's: remove the
+ * silent branch rather than narrow it.
+ *
+ * THE RULE, which is the smallest additive one that closes it:
+ *
+ *   * a file part is `kind: "file"` plus `content_hash` (64 hex characters,
+ *     either case, the SHA-256 of the part's exact bytes) and `content_length`
+ *     (a safe integer), and the bytes are NOT in the message;
+ *   * a receiver handed a part's bytes MUST hash them, and where the digest is
+ *     not the descriptor's, or the byte count is not the descriptor's, it
+ *     commits to the message AS IT ACTUALLY HELD IT: that part's
+ *     `content_hash` and `content_length` replaced by the held bytes' own,
+ *     nothing else touched. Its `handoff.received` then commits to a different
+ *     message object from the sender's, so the formed pair FAILS on
+ *     `message_hash`, a failure section 4.1 already names, and the receiving
+ *     side writes `outcome: "rejected"`. That is the ONE reading that moves,
+ *     and it moves only for a receiver that holds the bytes;
+ *   * every other deviation is named and none is silent. Three of them are
+ *     REFUSALS of one supply, so a receiver's own decoding defect never becomes
+ *     permanent evidence against an honest sender;
+ *   * an inline part is ACCEPTED, and it is committed by the MESSAGE ITSELF
+ *     (proof#157, ratified by Phil 2026-09-22). `message_hash` is SHA-256 over
+ *     the canonical bytes of the message object, so a part carrying its content
+ *     inside the message is already committed: alter that content and the
+ *     message object changes, the hash changes, and the pair fails. None of the
+ *     swapped-bytes attack applies, because that attack works only where a
+ *     descriptor's hash and bytes travelling BESIDE the message are two
+ *     separate things with nothing comparing them. Inline is not the risky
+ *     shape, it is the safest one. Where an inline part ALSO carries a
+ *     `content_hash` or a `content_length`, the receiver checks BOTH against
+ *     the inline content and names a disagreement: one commitment governs, and
+ *     a second one present and disagreeing is itself a finding.
+ *
+ * WHY THE HELD MESSAGE RATHER THAN A FINDING ON THE RECEIVING SIDE. A finding
+ * only the receiving side's own reader sees is the shape of every laundering
+ * path this section has closed: the party being audited publishes the pack, so
+ * a deviation that lives outside the committed record is a deviation that party
+ * chooses whether anyone reads. `message_hash` is the one value both sides
+ * publish and a reader already grades.
+ *
+ * WHAT DOES NOT MOVE. A receiver that never holds a part's bytes checks
+ * nothing, substitutes nothing and reads exactly as it did before this
+ * amendment: every file part is `PART_UNCHECKED`, and section 4.1 forbids
+ * treating an unchecked part as a checked one. No envelope field moves, no
+ * `spec_version` moves, no verdict word and no record-layer finding is coined.
+ *
+ * A REFUSAL IS SCOPED TO ITS PART, AND THE RECORD IS STILL WRITTEN (proof#156
+ * gate). The first cut of this module refused GLOBALLY: one refusal anywhere
+ * set `heldMessage` to null and dropped every substitution. That made the
+ * attack A18 exists to close launderable (a genuine swap on part 0 plus any
+ * refusal-triggering supply on part 1 wrote nothing at all), let a SENDER deny
+ * the receiver a record with an upper-case `content_hash` or a `"bytes": null`
+ * on an otherwise conformant descriptor, and contradicted section 4.1's own
+ * paragraph saying an uncheckable part is NAMED in the receiver's reading. So
+ * a problem with one part names that part, leaves the rest of the reading
+ * intact, and `heldMessage` is never null. A message-level problem is reserved
+ * for a message-level condition, and even then it produces a named result:
+ * `PARTS_NOT_AN_ARRAY`, and the entry-scoped `BYTES_FOR_UNKNOWN_PART`.
+ *
+ * WHAT THE CALLER STILL OWES, AND THE ONE FUNCTION THAT STATES IT.
+ * `substituted` decides whether a hand-off is `rejected`; it does NOT decide
+ * whether one is clean. A part that was refused reads `PART_UNCHECKED`,
+ * section 4.1 forbids a reader treating an unchecked part as a checked one,
+ * and a surface reporting a hand-off states how many parts were checked. A
+ * caller that wrote `accepted` on "nothing was substituted" alone would be
+ * calling a part it never established clean, which is the class this whole
+ * section keeps repairing.
+ *
+ * The sharp version, measured (proof#156 second gate, F5): deliver a tampered
+ * copy of a part ALONE and it is `part_mismatched`, substituted, and the pair
+ * fails on `message_hash`. Deliver the tampered copy AND the true one and it
+ * is `conflicting_part_bytes`, `part_unchecked`, nothing substituted, a
+ * `heldMessage` byte-identical to the sender's, and the pair VERIFIES. Adding
+ * data suppresses detection, and the refusal that names it lives only in
+ * `refusals`, which is a finding only the receiving side's own reader sees:
+ * the exact shape the paragraph above refuses to create.
+ * `PART_ENCODING_MISMATCH` has the same property.
+ *
+ * Until that round the obligation was PROSE IN THIS COMMENT with no mechanism,
+ * which is a rule a caller has to read to obey. `uncheckedHeldParts` is the
+ * mechanism's additive half: it names the parts the receiver HELD bytes for
+ * and did not check, so a caller writes `accepted` only where `substituted` is
+ * empty AND that list is empty, instead of re-deriving it from the refusals.
+ * It cannot make the mistake IMPOSSIBLE, because this module reads and does
+ * not write the record. What the record layer does with the list was
+ * proof#162, and Phil ratified it on 2026-09-22: `outcome: "accepted"` keeps
+ * meaning what it means today, and the count of held-but-unchecked parts
+ * rides in an ADDITIVE `context` key, REQUIRED when it is not zero. Its force
+ * is against SDKs through conformance vectors rather than against records
+ * through readers, since only the receiver knows what bytes it held, so THIS
+ * LIST IS WHAT EVERY SDK BUILT ON THE RULE WILL COUNT. A part missing from it
+ * is a part no record will ever mention (anchor#191 is the first caller).
+ *
+ * WHAT THIS MODULE DOES NOT DO. It does not canonicalize and it does not hash
+ * the message. It returns the message a receiver commits to, and the caller
+ * hashes that with the rule section 4.1 already states, so this module has no
+ * failure mode of its own for a message too deep or not serializable and there
+ * is no branch here where one kernel throws and the other returns.
+ */
+import { sha256Hex } from "./crypto.js";
+
+/**
+ * The result of a part whose supplied bytes hash to its `content_hash` AND
+ * count to its `content_length`.
+ */
+export const PART_MATCHED = "part_matched";
+
+/**
+ * The result of a part whose supplied bytes miss either of those, with no
+ * respelling of them that explains the digest. The held-message substitution
+ * applies to this part, and it replaces BOTH values with the held bytes' own.
+ */
+export const PART_MISMATCHED = "part_mismatched";
+
+/**
+ * A file part whose bytes were not supplied, or whose supply was REFUSED. It is
+ * not checked and it is not clean: section 4.1 forbids a reader treating it as
+ * checked.
+ */
+export const PART_UNCHECKED = "part_unchecked";
+
+/**
+ * A `kind: "file"` part carrying its content inside the message, and ACCEPTED
+ * (proof#157, ratified by Phil 2026-09-22). It is committed by the MESSAGE
+ * ITSELF: `message_hash` is SHA-256 over the canonical bytes of the message
+ * object, so altering that content changes the message, changes the hash, and
+ * fails the pair. Nothing is hashed against it here and nothing is substituted,
+ * because there is nothing travelling beside the message for the message to
+ * disagree with. That is why the swapped-bytes attack cannot reach this shape.
+ */
+export const PART_INLINE_BYTES = "part_inline_bytes";
+
+/**
+ * An inline part whose `content_hash`, `content_length` or both DISAGREE with
+ * its inline content: no single reading of that content satisfies every claim
+ * the part writes beside it. The message's own commitment still governs and
+ * nothing is substituted; this names the SECOND claim that disagrees with it,
+ * which is a finding in its own right (proof#157).
+ *
+ * ONE name for both claims, exactly as `PART_MISMATCHED` is one name for both
+ * on a descriptor part. It was `part_inline_hash_mismatch` for one round of
+ * this unmerged PR, when only the hash was compared; a name that says "hash"
+ * about a result that also covers a length asserts more than its body does, so
+ * the name was re-cut with the rule (proof#156 second gate, F4).
+ *
+ * The check is deliberately permissive ACROSS readings: the raw UTF-8 of the
+ * value, its base64 decoding and its hex decoding are all tried, so this fires
+ * only where no reading agrees at all. It is not permissive BETWEEN claims: one
+ * reading has to satisfy all of them, because a hash that agrees under the
+ * base64 decoding beside a length that agrees under the raw text describes no
+ * blob that exists.
+ */
+export const PART_INLINE_MISMATCHED = "part_inline_mismatched";
+
+/**
+ * `kind: "file"` without a conformant `content_hash` and `content_length`. A
+ * sender's defect rather than a receiver's, so it is named rather than refused:
+ * the receiver did nothing wrong by holding it.
+ */
+export const PART_MALFORMED_DESCRIPTOR = "part_malformed_descriptor";
+
+/**
+ * Any other part. It is committed as ordinary JSON content and this rule checks
+ * nothing about it.
+ */
+export const PART_NOT_A_FILE = "part_not_a_file";
+
+/**
+ * REFUSAL of ONE supplied entry. Bytes were supplied for no part of the
+ * message, or for a part this rule cannot check. The caller and the message
+ * disagree about what was sent, and hashing bytes against a part that is not
+ * there establishes nothing. Where the entry names a part that EXISTS but is
+ * not checkable, the refusal carries that part's index and the part keeps the
+ * result it classified to; where it names no part at all, the refusal carries
+ * the entry position and no part. Neither stops the record being written.
+ */
+export const BYTES_FOR_UNKNOWN_PART = "bytes_for_unknown_part";
+
+/**
+ * REFUSAL. Two DIFFERENT byte strings were supplied for one part. A receiver
+ * holding two answers has not established which one it held.
+ */
+export const CONFLICTING_PART_BYTES = "conflicting_part_bytes";
+
+/**
+ * REFUSAL of ONE supplied entry. The supplied bytes miss the descriptor, but a
+ * base64 or hex RESPELLING of them in EITHER direction hashes to it: either the
+ * bytes DECODE to the part (the receiver's stack never decoded what it was
+ * handed) or they ENCODE to it (the receiver's stack decoded bytes the sender
+ * committed in their encoded spelling, which is what a single-line DER
+ * attachment, a PEM body and a JWT all are). That is a coding defect in the
+ * receiver, not a tamper by the sender: a proto3 JSON transcoder re-encodes
+ * base64 URL-safe and unpadded while behaving honestly, and under the silence
+ * this amendment removes it produced a permanent tamper record against a sender
+ * who did nothing. Recording evidence out of a receiver's own bug is the one
+ * outcome worse than recording nothing, so BOTH directions are guarded
+ * (proof#156 gate): guarding only the decoding direction left the other half of
+ * one honest stack's behavior reading as a tamper.
+ */
+export const PART_ENCODING_MISMATCH = "part_encoding_mismatch";
+
+/**
+ * A MESSAGE-LEVEL result. The message carries a `parts` key whose value is
+ * present and is not an array, which is how proto3 JSON encodes a map and so is
+ * reachable from the same transport family the motivating example comes from.
+ * Section 4.1 asks for one result per part; a message shaped like this has
+ * part-shaped content and no parts, and before proof#156's gate it produced
+ * zero readings and an accepted record. It is named rather than refused: the
+ * receiver did nothing wrong by holding it, and nothing in it is checked. A
+ * `parts` written as `null` is an ABSENT `parts` and is not this, on A14's
+ * ruling that an absent value and one written as `null` name one thing.
+ */
+export const PARTS_NOT_AN_ARRAY = "parts_not_an_array";
+
+/**
+ * NOTE, not a refusal. One part supplied more than once with IDENTICAL bytes is
+ * one supply stated twice, and the part is checked normally. Different bytes for
+ * one part are `CONFLICTING_PART_BYTES`.
+ */
+export const PART_SUPPLIED_TWICE = "part_supplied_twice";
+
+/**
+ * The order refusals are reported in, fixed so two kernels report one list
+ * rather than two orderings of it.
+ */
+export const REFUSAL_ORDER = [
+  BYTES_FOR_UNKNOWN_PART,
+  CONFLICTING_PART_BYTES,
+  PART_ENCODING_MISMATCH,
+] as const;
+
+/**
+ * The order message-level results are reported in, for the same reason as
+ * `REFUSAL_ORDER`.
+ */
+export const MESSAGE_RESULT_ORDER = [PARTS_NOT_AN_ARRAY] as const;
+
+/**
+ * The results that put a HELD part into `uncheckedHeldParts`, written out so a
+ * third kernel reads the rule rather than inferring it from one kernel's
+ * filter (proof#156 third gate, C1).
+ *
+ * The line is whether the MESSAGE ITSELF commits the part's content. It does
+ * not for these two: `PART_UNCHECKED` is a supply the rule refused to grade,
+ * and `PART_MALFORMED_DESCRIPTOR` is a part whose content lives BESIDE the
+ * message under a claim no receiver can use, so in both the receiver holds
+ * bytes that nothing in the committed record covers.
+ *
+ * The other three results a supply can be refused against are excluded, and
+ * excluded for a reason rather than by omission. `PART_INLINE_BYTES`,
+ * `PART_INLINE_MISMATCHED` and `PART_NOT_A_FILE` all carry their content
+ * INSIDE the message, which `message_hash` already commits on both sides:
+ * bytes supplied beside one of those grade nothing and hide nothing, because
+ * a reader of either pack reads the content itself. Counting them would make
+ * the caller's obligation fire on parts no attack can reach.
+ */
+const HELD_UNCHECKED_RESULTS: readonly string[] = [
+  PART_UNCHECKED,
+  PART_MALFORMED_DESCRIPTOR,
+];
+
+/**
+ * The keys that make a part carry its content INLINE, in the order they are
+ * read. Named rather than inferred: `bytes` is A2A's spelling of an inline file
+ * part, and `data` and `content` are the two other spellings in the wild. The
+ * FIRST of them present with a value that is not `null` is the inline content,
+ * so a part spelling it twice reads one way in both kernels.
+ *
+ * A key present with `null` is an ABSENT inline value, on A14's ruling that an
+ * absent value and one written as `null` name one thing. That matters: an A2A
+ * `FilePart` with `uri` set carries `"bytes": null`, and so does proto3 JSON,
+ * and reading those as inline made a conformant DESCRIPTOR part uncheckable
+ * (proof#156 gate). They fall through to the descriptor rule, which is what
+ * they are.
+ */
+// A conformant DESCRIPTOR part that also carries a `content` or `data` key
+// meaning something else (a filename, a metadata blob) is reclassified by this
+// list and never checked against supplied bytes. That is inside section 4.1's
+// stated rule, and whether these parts ought to fall into it is proof#163.
+export const INLINE_BYTES_KEYS = ["bytes", "content", "data"] as const;
+
+const HEX64 = /^[0-9a-fA-F]{64}$/;
+const HEX_CHARSET = /^[0-9a-fA-F]+$/;
+const LOWER_HEX = "0123456789abcdef";
+const UPPER_HEX = "0123456789ABCDEF";
+
+/**
+ * The largest integer a double carries exactly, the same bound section 4.1 puts
+ * on `event.sequence`: a `content_length` outside it is a value the two kernels
+ * would read as two numbers.
+ */
+export const MAX_SAFE_INTEGER = Number.MAX_SAFE_INTEGER;
+
+const BASE64_STANDARD = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const BASE64_URLSAFE = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+
+/**
+ * One byte string a receiver holds, and the part it holds it for.
+ *
+ * `part` is an INDEX into the message's `parts` array. It is an index rather
+ * than a content hash on purpose: keying the supply by the value the check is
+ * about to grade would mean a receiver could only supply bytes it had already
+ * agreed with, which is the whole defect stated backwards.
+ */
+export interface SuppliedPart {
+  part: unknown;
+  data: Uint8Array;
+}
+
+/** What the receiver reports for one part of the message, one per part. */
+export interface PartReading {
+  index: number;
+  result: string;
+}
+
+/**
+ * A caller error. Nothing is written, nothing is signed, no record made.
+ *
+ * `part` is the part index where the refusal is about a part of the message,
+ * and `entry` is the POSITION of the offending supplied entry in the sequence
+ * the caller passed. The position is recorded rather than the value the caller
+ * named, so a caller that names a part with a float or a string cannot make two
+ * kernels serialize one reading two ways.
+ */
+export interface Refusal {
+  name: string;
+  part: number | null;
+  entry: number | null;
+}
+
+/**
+ * Something worth reporting that refuses nothing and checks nothing out. Same
+ * shape as a `Refusal` and carried in its own list, so no caller can read a
+ * note as a refusal by looking only at a name.
+ */
+export type Note = Refusal;
+
+/**
+ * The message a receiver commits to, and everything it found on the way.
+ *
+ * `heldMessage` is ALWAYS the message the receiver commits to and is never
+ * null: a refusal is scoped to the supply it is about and never denies the
+ * receiver a record (proof#156 gate). The caller commits `event.message_hash`
+ * as SHA-256 over its JCS (RFC 8785) canonical bytes, which is the rule section
+ * 4.1 already states and the reason this module does not hash anything itself.
+ *
+ * `messageResults` carries the message-level named results, in
+ * `MESSAGE_RESULT_ORDER`. It is empty for every message whose shape the rule
+ * reads.
+ *
+ * `substituted` carries the indexes of the parts whose descriptor the receiver
+ * replaced with the held bytes' own hash and length. It is empty for an honest
+ * hand-off, and where it is not empty the receiving side writes
+ * `outcome: "rejected"`.
+ */
+export interface HeldMessage {
+  parts: PartReading[];
+  messageResults: string[];
+  refusals: Refusal[];
+  notes: Note[];
+  heldMessage: unknown | null;
+  substituted: number[];
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function hasOwn(value: Record<string, unknown>, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}
+
+/**
+ * 64 hex characters, in EITHER case. Phil ratified proof#135 as "pin the hex
+ * charset only": a case-only difference names the same value, and refusing
+ * upper case here would contradict a ratified decision and punish a producer
+ * who did nothing wrong. Every comparison against a digest lowercases both
+ * sides, which is what the other kernels already do.
+ */
+function isHex64(value: unknown): boolean {
+  return typeof value === "string" && HEX64.test(value);
+}
+
+/**
+ * A byte count: an integer at least zero and inside the safe range. `true` is
+ * not a number. Zero is a legal length: the empty part is a real part, and a
+ * rule that read zero as "no length" would leave it unchecked in silence.
+ */
+function isSafeLength(value: unknown): boolean {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+
+function isSafeIndex(value: unknown): boolean {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+
+/**
+ * Distinguishes "no inline content" from an inline content of `null`, which
+ * A14's ruling says is the same thing but which a plain `null` could not be
+ * told apart from a legitimate value.
+ */
+const ABSENT = Symbol("absent");
+
+/**
+ * The part's inline content, or `ABSENT` where it carries none: the FIRST of
+ * `INLINE_BYTES_KEYS` present with a value that is not `null`, so a part
+ * spelling it twice reads one way in both kernels.
+ */
+function inlineValue(part: Record<string, unknown>): unknown | typeof ABSENT {
+  for (const key of INLINE_BYTES_KEYS) {
+    if (hasOwn(part, key) && part[key] !== null && part[key] !== undefined) {
+      return part[key];
+    }
+  }
+  return ABSENT;
+}
+
+/**
+ * Every byte string a reader can form from an inline value: the raw UTF-8 of
+ * the string, its base64 decoding and its hex decoding. Deliberately
+ * permissive: this exists only to decide whether a `content_hash` sitting
+ * BESIDE inline content agrees with it, and the message's own commitment
+ * governs either way, so the finding fires only where no reading agrees at all.
+ * A value that is not a string carries no readings, so a `content_hash` beside
+ * one has nothing to agree with.
+ */
+function inlineReadings(value: unknown): Uint8Array[] {
+  if (typeof value !== "string") return [];
+  const encoded = new TextEncoder().encode(value);
+  const raw = new Uint8Array(encoded.length);
+  raw.set(encoded);
+  const out: Uint8Array[] = [raw];
+  for (const decoded of [base64Decode(raw), hexDecode(raw)]) {
+    if (decoded !== null) out.push(decoded);
+  }
+  return out;
+}
+
+/**
+ * The SHAPE a part reads with before any supplied bytes are considered, or
+ * `null` where the part is one this rule checks against them.
+ *
+ * Shape only, and synchronous on purpose: the inline hash agreement needs
+ * SHA-256, which is async here and not in Python, so refining
+ * `PART_INLINE_BYTES` to `PART_INLINE_MISMATCHED` happens in the reading
+ * loop instead. Keeping it out of here is what lets `isFilePart` mean the same
+ * thing, and have the same signature, in both kernels.
+ */
+function classify(part: unknown): string | null {
+  if (!isPlainObject(part)) return PART_NOT_A_FILE;
+  if (part.kind !== "file") return PART_NOT_A_FILE;
+  // ACCEPTED, and committed by the message itself (proof#157).
+  if (inlineValue(part) !== ABSENT) return PART_INLINE_BYTES;
+  if (!isHex64(part.content_hash)) return PART_MALFORMED_DESCRIPTOR;
+  if (!isSafeLength(part.content_length)) return PART_MALFORMED_DESCRIPTOR;
+  return null;
+}
+
+/**
+ * Whether the claims written BESIDE an inline part's content agree with it.
+ *
+ * Two claims can sit beside inline content, `content_hash` and
+ * `content_length`, and BOTH are read (proof#156 second gate, F4). The length
+ * was skipped for one round of this unmerged PR, on the argument that a reader
+ * holding the message can see a contradiction between the content and the
+ * claim from the message alone. That argument is true and it is also true of
+ * `content_hash`, which is compared: accepting it deletes the neighboring
+ * check. So the rule is the one section 4.1 already applies to a descriptor
+ * part, where a hash that misses and a count that misses reach one result: two
+ * claims about one blob, and reading one of them lets the other be false in
+ * silence.
+ *
+ * A claim that is ABSENT, or is not the shape the table names, is not a claim:
+ * it is not compared and it cannot disagree. A part writing neither agrees by
+ * default, because the message's own commitment governs and this only ever
+ * names a SECOND claim that contradicts it.
+ *
+ * ONE reading has to satisfy EVERY claim present, rather than each claim
+ * finding its own. Grading them separately would let a `content_hash` that
+ * agrees under the base64 decoding sit beside a `content_length` that agrees
+ * under the raw text, a pair no blob in the world satisfies, and call it clean.
+ */
+async function inlineClaimsAgree(part: Record<string, unknown>): Promise<boolean> {
+  const wanted = isHex64(part.content_hash)
+    ? (part.content_hash as string).toLowerCase()
+    : null;
+  const length = isSafeLength(part.content_length)
+    ? (part.content_length as number)
+    : null;
+  if (wanted === null && length === null) return true;
+  for (const reading of inlineReadings(inlineValue(part))) {
+    if (wanted !== null && (await sha256Hex(reading)) !== wanted) continue;
+    if (length !== null && reading.length !== length) continue;
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Whether this part is one this rule CHECKS against bytes travelling BESIDE the
+ * message: a conformant descriptor part. Exactly the three conditions section
+ * 4.1 states, in the order that keeps inline content out. An INLINE part is
+ * accepted and committed by the message itself (proof#157), so there is nothing
+ * here for supplied bytes to be checked against and this answers `false`.
+ */
+export function isFilePart(part: unknown): boolean {
+  return classify(part) === null;
+}
+
+/**
+ * The parts of a message, or none at all.
+ *
+ * A message that carries no `parts` array carries no file parts, and that is
+ * not a deviation: it is the common case, a JSON-only message. Every supplied
+ * byte string then has no part to belong to and is refused, which is the
+ * reading section 4.1 asks for and not an exception.
+ */
+function messageParts(message: unknown): unknown[] {
+  if (!isPlainObject(message)) return [];
+  const parts = message.parts;
+  return Array.isArray(parts) ? [...parts] : [];
+}
+
+/**
+ * The message-level named results, before any part is read.
+ *
+ * One condition reaches this today: a `parts` that is present, is not null and
+ * is not an array. It gets a name rather than the silence it had (proof#156
+ * gate), because a message with part-shaped content and no parts is exactly the
+ * shape section 4.1's "one result per part" leaves nothing to say about.
+ */
+function messageResults(message: unknown): string[] {
+  if (!isPlainObject(message)) return [];
+  if (!hasOwn(message, "parts")) return [];
+  const parts = message.parts;
+  if (parts === null || parts === undefined || Array.isArray(parts)) return [];
+  return [PARTS_NOT_AN_ARRAY];
+}
+
+function sameBytes(left: Uint8Array, right: Uint8Array): boolean {
+  if (left.length !== right.length) return false;
+  for (let i = 0; i < left.length; i++) {
+    if (left[i] !== right[i]) return false;
+  }
+  return true;
+}
+
+function asAscii(data: Uint8Array): string {
+  let out = "";
+  for (const byte of data) out += String.fromCharCode(byte);
+  return out;
+}
+
+/**
+ * Strict ASCII hex. Written out rather than delegated, because Python's
+ * `bytes.fromhex` skips ASCII whitespace and a charset test does not: a decoder
+ * the two kernels disagree about would put a record on one side of
+ * `part_encoding_mismatch` in one language and the other side of it in the
+ * other.
+ *
+ * EVERY GUARD HERE AND IN `base64Decode` IS PINNED BY A CORPUS VECTOR CARRYING
+ * A HAND-WRITTEN EXPECTATION (proof#156 second gate, F3), named in the comment
+ * beside it. Until that round, six of the seven produced no signal when
+ * deleted: the whole ladder and the whole leg stayed green, so a third kernel
+ * that delegated to `atob` or `base64.b64decode` reproduced the entire corpus
+ * byte for byte, was conformant under `architecture.md` K3, and still put a
+ * record on the other side of `part_encoding_mismatch`. An agreement case
+ * cannot close that: the leg grades two kernels against each other, so a guard
+ * deleted from both is invisible to it. Only a hand-written `expected` block
+ * states which side of the boundary an input falls on.
+ */
+function hexDecode(data: Uint8Array): Uint8Array | null {
+  // An odd number of characters is not hex. Deleting this line lets `"ab0"`
+  // read as `0xab 0x00`, so a receiver handed a truncated hex string writes
+  // `part_encoding_mismatch` where it owes `part_mismatched` and a
+  // substitution: `parts-decoder-hex-odd-length-01`.
+  if (data.length === 0 || data.length % 2 !== 0) return null;
+  const text = asAscii(data);
+  if (!HEX_CHARSET.test(text)) return null;
+  const out = new Uint8Array(data.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = Number.parseInt(text.slice(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}
+
+/**
+ * Strict base64, standard OR URL-safe, padded or not, canonical only.
+ *
+ * Written out for the same reason as `hexDecode`: Python's `base64.b64decode`
+ * and JavaScript's `atob` disagree about padding, about the URL-safe alphabet
+ * and about non-zero trailing bits, and each of those disagreements decides
+ * whether a receiver refuses its own decoding defect or records a tamper
+ * against an honest sender. The two alphabets are not mixed: a string carrying
+ * one character from each is neither spelling and decodes to nothing.
+ *
+ * TWO GUARDS THAT STOOD HERE WERE DELETED IN THE PROOF#156 SECOND GATE'S
+ * ROUND, because they could not change a decode for any input and so read as
+ * protection that was not there:
+ *
+ *   * `pad > 0 && text.length % 4 !== 0` is the SAME PREDICATE as the
+ *     `(body.length + pad) % 4` test below it. The strip loop above makes
+ *     `text` exactly `body + "=".repeat(pad)`, so the two lengths are equal by
+ *     construction and the two conditions are one condition written twice.
+ *     Each masked the other, which is why deleting either alone changed
+ *     nothing;
+ *   * `body.includes("=")` is subsumed by the alphabet test three lines below
+ *     it: `=` is in neither alphabet, so a body carrying one is refused there.
+ *
+ * Checked exhaustively over every byte string of length 0 to 2 across all 256
+ * byte values, exhaustively over lengths 3 to 6 on the 16-character alphabet
+ * that reaches these branches, and over 500,000 random byte strings: zero
+ * decodes move.
+ * The remaining guards each carry the vector that pins them.
+ */
+function base64Decode(data: Uint8Array): Uint8Array | null {
+  if (data.length === 0) return null;
+  const text = asAscii(data);
+  let body = text;
+  let pad = 0;
+  while (body.endsWith("=")) {
+    body = body.slice(0, -1);
+    pad += 1;
+  }
+  // At most two padding characters. Deleting this line lets `"===="` and any
+  // aligned body followed by four `=` decode as though the padding were not
+  // there: `parts-decoder-base64-four-pad-chars-01`.
+  if (pad > 2) return null;
+
+  const standard = [...body].every((c) => BASE64_STANDARD.includes(c));
+  const urlsafe = [...body].every((c) => BASE64_URLSAFE.includes(c));
+  // One alphabet or the other, never a merge of the two. `"-/AA"` is neither
+  // spelling, and deleting this line does not merge the alphabets: it picks
+  // the URL-safe one and asks it for `/`, where `indexOf` answers -1 and
+  // garbles the arithmetic into `f7 f0 00`. TWO vectors pin that, one per
+  // shape of third kernel: `parts-decoder-base64-mixed-alphabet-01` commits
+  // the bytes a kernel that MERGES the alphabets reads, and
+  // `parts-decoder-base64-mixed-alphabet-02` commits the bytes this kernel's
+  // own -1 produces, which is the one that goes red HERE (proof#156 third
+  // gate, C2: deleting this line left all 2224 TypeScript tests green).
+  if (!standard && !urlsafe) return null;
+  const alphabet = standard ? BASE64_STANDARD : BASE64_URLSAFE;
+  // A lone trailing character carries six bits and no encoder emits one.
+  // Deleting this lets `"A"` read as the EMPTY blob, so any of the four
+  // characters whose low bits are zero could claim to be it:
+  // `parts-decoder-base64-single-character-01`.
+  if (body.length % 4 === 1) return null;
+  // Padding that does not align the string. Deleting this lets a 36-character
+  // body followed by one `=` decode as though the `=` were not there:
+  // `parts-decoder-base64-padding-misaligned-01`.
+  if (pad > 0 && (body.length + pad) % 4 !== 0) return null;
+
+  let bits = 0;
+  let width = 0;
+  const out: number[] = [];
+  for (const char of body) {
+    bits = bits * 64 + alphabet.indexOf(char);
+    width += 6;
+    if (width >= 8) {
+      width -= 8;
+      out.push(Math.floor(bits / 2 ** width) & 0xff);
+      bits = bits % 2 ** width;
+    }
+  }
+  // Canonical only: the unused low bits of the last character are zero in every
+  // encoder's output, and accepting them non-zero would let two spellings of one
+  // blob decode to one value. Both `atob` and `base64.b64decode` accept them,
+  // which is the sharpest reason this decoder is written out: deleting this
+  // line lets `"QR=="` read as `"A"`, so a receiver handed one of the sixteen
+  // non-canonical spellings of a one-byte part writes `part_encoding_mismatch`
+  // where it owes `part_mismatched` and a substitution:
+  // `parts-decoder-non-canonical-tail-01`.
+  if (width > 0 && bits !== 0) return null;
+  return new Uint8Array(out);
+}
+
+/**
+ * The inverse of `base64Decode`, written out for the same reason: `btoa` and
+ * Python's `base64` module differ in what they accept and in how they pad, and
+ * this value is compared against a digest a sender committed, so the two
+ * kernels have to emit the same characters.
+ */
+function base64Encode(data: Uint8Array, alphabet: string, pad: boolean): Uint8Array {
+  let out = "";
+  for (let start = 0; start < data.length; start += 3) {
+    const chunk = data.subarray(start, start + 3);
+    const bits =
+      (chunk[0]! << 16) | ((chunk[1] ?? 0) << 8) | (chunk[2] ?? 0);
+    const chars = [18, 12, 6, 0].map((shift) => alphabet[(bits >> shift) & 0x3f]!);
+    const keep = chunk.length + 1;
+    out += chars.slice(0, keep).join("");
+    if (pad && keep < 4) out += "=".repeat(4 - keep);
+  }
+  return asciiBytes(out);
+}
+
+function hexEncode(data: Uint8Array, alphabet: string): Uint8Array {
+  let out = "";
+  for (const byte of data) out += alphabet[byte >> 4]! + alphabet[byte & 0x0f]!;
+  return asciiBytes(out);
+}
+
+function asciiBytes(text: string): Uint8Array {
+  const out = new Uint8Array(text.length);
+  for (let i = 0; i < text.length; i++) out[i] = text.charCodeAt(i) & 0xff;
+  return out;
+}
+
+/**
+ * Every spelling of `data` an honest stack might have been handed.
+ *
+ * The ENCODING direction of the encoding guard. A receiver whose stack decoded
+ * what it was given holds the decoded bytes while the sender committed the
+ * encoded text, which is what a single-line DER attachment, a PEM body and a
+ * JWT each are: the part's bytes ARE the base64 text. Guarding only the
+ * decoding direction told that receiver it held a tamper and fired the
+ * substitution, which is the one outcome this module calls worse than recording
+ * nothing.
+ *
+ * The list is fixed and short, the same six spellings the decoder accepts, so
+ * the two kernels try the same candidates in the same order and the cost is
+ * linear in the length of the supply.
+ *
+ * A `data.length === 0` guard stood here and was deleted in the proof#156
+ * second gate's round, for the same reason as the two in `base64Decode`: it
+ * could not change an answer. This is reached only from `respellingExplains`,
+ * and only after `sha256(data)` has already been compared to `contentHash` and
+ * missed. Every spelling of the empty byte string is the empty byte string, so
+ * the one candidate it would have produced is the digest that just failed. An
+ * optimization written as a guard reads as protection that is not there.
+ */
+function respellings(data: Uint8Array): Uint8Array[] {
+  return [
+    base64Encode(data, BASE64_STANDARD, true),
+    base64Encode(data, BASE64_STANDARD, false),
+    base64Encode(data, BASE64_URLSAFE, true),
+    base64Encode(data, BASE64_URLSAFE, false),
+    hexEncode(data, LOWER_HEX),
+    hexEncode(data, UPPER_HEX),
+  ];
+}
+
+/**
+ * Whether a base64 or hex respelling of `data`, in EITHER direction, hashes to
+ * `contentHash`. `contentHash` arrives lowercased: the charset is pinned and
+ * the case is not (proof#135), so every comparison in this module is made on
+ * one spelling.
+ */
+async function respellingExplains(data: Uint8Array, contentHash: string): Promise<boolean> {
+  for (const decoded of [base64Decode(data), hexDecode(data)]) {
+    if (decoded !== null && (await sha256Hex(decoded)) === contentHash) return true;
+  }
+  for (const encoded of respellings(data)) {
+    if ((await sha256Hex(encoded)) === contentHash) return true;
+  }
+  return false;
+}
+
+/**
+ * What a receiver commits to, given the message and the bytes it holds.
+ *
+ * `supplied` is the bytes the receiver actually holds, each named by the index
+ * of the part it belongs to. An empty list is the common case, a receiver that
+ * holds no part's bytes, and it reads exactly as section 4.1 read before this
+ * amendment: every file part is `PART_UNCHECKED` and the message a receiver
+ * commits to is the message it was given.
+ *
+ * Where a part's bytes hash to something other than its `content_hash`, or
+ * where their count is not its `content_length`, the returned `heldMessage`
+ * carries that part's `content_hash` and `content_length` replaced by the held
+ * bytes' own. The receiver commits `event.message_hash` over THAT, so its
+ * record and the sender's disagree and the pair fails on `message_hash`.
+ *
+ * A refusal is scoped to the supplied entry it is about: the part it names is
+ * not checked and not substituted, every other part reads as it would have, and
+ * `heldMessage` is returned either way. Nothing a caller or a sender can do
+ * denies the receiver a record.
+ */
+export async function commitHeldMessage(
+  message: unknown,
+  supplied: readonly SuppliedPart[] = [],
+): Promise<HeldMessage> {
+  const parts = messageParts(message);
+  const classifications = parts.map(classify);
+  // The inline hash agreement, refined out of the shape pass because it hashes.
+  for (let i = 0; i < parts.length; i++) {
+    if (classifications[i] !== PART_INLINE_BYTES) continue;
+    if (!(await inlineClaimsAgree(parts[i] as Record<string, unknown>))) {
+      classifications[i] = PART_INLINE_MISMATCHED;
+    }
+  }
+
+  const refusals: Refusal[] = [];
+  const notes: Note[] = [];
+  const byPart = new Map<number, { entry: number; data: Uint8Array }[]>();
+
+  supplied.forEach((item, entry) => {
+    const index = item.part;
+    if (!isSafeIndex(index) || (index as number) >= parts.length) {
+      // No part of this message: the only genuinely message-level refusal, and
+      // it still names itself rather than going quiet.
+      refusals.push({ name: BYTES_FOR_UNKNOWN_PART, part: null, entry });
+      return;
+    }
+    if (classifications[index as number] !== null) {
+      // A part that EXISTS and cannot be checked. Scoped to that part, so a
+      // sender cannot buy silence by emitting one uncheckable part beside the
+      // part it altered.
+      refusals.push({ name: BYTES_FOR_UNKNOWN_PART, part: index as number, entry });
+      return;
+    }
+    const key = index as number;
+    const existing = byPart.get(key);
+    if (existing === undefined) byPart.set(key, [{ entry, data: item.data }]);
+    else existing.push({ entry, data: item.data });
+  });
+
+  const readings: PartReading[] = [];
+  const substituted: number[] = [];
+  const replacements = new Map<number, { contentHash: string; contentLength: number }>();
+
+  for (let index = 0; index < parts.length; index++) {
+    const pre = classifications[index];
+    if (pre !== null) {
+      readings.push({ index, result: pre });
+      continue;
+    }
+    const entries = byPart.get(index) ?? [];
+    if (entries.length === 0) {
+      readings.push({ index, result: PART_UNCHECKED });
+      continue;
+    }
+
+    const first = entries[0]!;
+    const conflicting = entries.slice(1).find((e) => !sameBytes(e.data, first.data));
+    if (conflicting !== undefined) {
+      refusals.push({ name: CONFLICTING_PART_BYTES, part: index, entry: conflicting.entry });
+      readings.push({ index, result: PART_UNCHECKED });
+      continue;
+    }
+    if (entries.length > 1) {
+      notes.push({ name: PART_SUPPLIED_TWICE, part: index, entry: entries[1]!.entry });
+    }
+
+    const part = parts[index] as Record<string, unknown>;
+    const contentHash = (part.content_hash as string).toLowerCase();
+    const contentLength = part.content_length as number;
+    const digest = await sha256Hex(first.data);
+    if (digest === contentHash) {
+      // The LENGTH is compared too, and a disagreement substitutes exactly as a
+      // hash disagreement does (proof#156 gate). Before that, a part whose
+      // stated length the receiver could see was false read `part_matched`, so
+      // the receiver certified the part and committed the false length with it.
+      if (first.data.length === contentLength) {
+        readings.push({ index, result: PART_MATCHED });
+        continue;
+      }
+      readings.push({ index, result: PART_MISMATCHED });
+      substituted.push(index);
+      replacements.set(index, { contentHash: digest, contentLength: first.data.length });
+      continue;
+    }
+    if (await respellingExplains(first.data, contentHash)) {
+      refusals.push({ name: PART_ENCODING_MISMATCH, part: index, entry: first.entry });
+      readings.push({ index, result: PART_UNCHECKED });
+      continue;
+    }
+
+    readings.push({ index, result: PART_MISMATCHED });
+    substituted.push(index);
+    replacements.set(index, { contentHash: digest, contentLength: first.data.length });
+  }
+
+  const rank = (r: Refusal): [number, number, number] => [
+    (REFUSAL_ORDER as readonly string[]).indexOf(r.name),
+    r.part === null ? -1 : r.part,
+    r.entry === null ? -1 : r.entry,
+  ];
+  refusals.sort((a, b) => {
+    const [an, ap, ae] = rank(a);
+    const [bn, bp, be] = rank(b);
+    return an - bn || ap - bp || ae - be;
+  });
+  notes.sort((a, b) => {
+    if (a.name !== b.name) return a.name < b.name ? -1 : 1;
+    return (a.part === null ? -1 : a.part) - (b.part === null ? -1 : b.part);
+  });
+
+  let held: unknown = message;
+  if (replacements.size > 0) {
+    // Rebuilt rather than mutated in place: the message a caller handed in is
+    // the caller's, and a reading that edits its input is a reading that
+    // changes what the caller commits to on the honest path too.
+    const heldParts = parts.map((part, index) => {
+      const replacement = replacements.get(index);
+      if (replacement === undefined) return part;
+      return {
+        ...(part as Record<string, unknown>),
+        content_hash: replacement.contentHash,
+        content_length: replacement.contentLength,
+      };
+    });
+    held = { ...(message as Record<string, unknown>), parts: heldParts };
+  }
+
+  const order = MESSAGE_RESULT_ORDER as readonly string[];
+  return {
+    parts: readings,
+    messageResults: messageResults(message).sort(
+      (a, b) => order.indexOf(a) - order.indexOf(b),
+    ),
+    refusals,
+    notes,
+    heldMessage: held,
+    substituted,
+  };
+}
+
+/**
+ * The parts the receiver HELD bytes for and did NOT check.
+ *
+ * The gap between "nothing was substituted" and "every part is clean", named
+ * so a caller does not have to re-derive it from the refusal list (proof#156
+ * second gate, F5). A part is in here where a refusal NAMES it and its reading
+ * is one of `HELD_UNCHECKED_RESULTS`: the receiver had bytes for that part,
+ * the rule declined to grade them, and NOTHING about that reaches the
+ * committed record.
+ *
+ * THE RULE, in one sentence, because a filter is not a rule. A part is in here
+ * where the receiver held bytes for it AND the message itself does not commit
+ * its content. `PART_UNCHECKED` is a refused supply;
+ * `PART_MALFORMED_DESCRIPTOR` is a part whose content travels BESIDE the
+ * message under a claim no receiver can use, so the receiver's bytes are
+ * exactly as ungraded and the record says as little. The first cut of this
+ * function omitted the second, which the third gate measured: a `kind: "file"`
+ * part with a non-conformant `content_hash` or `content_length`, bytes held,
+ * read `[]` here, so a caller following the rule this module prescribes wrote
+ * `accepted` over a part it held bytes for and never checked. That is the
+ * class the mechanism exists to close, and Phil named it in proof#162's
+ * ratification as the gap that decision inherits unless it is closed here.
+ *
+ * Three results are excluded ON PURPOSE. An inline part (`PART_INLINE_BYTES`,
+ * `PART_INLINE_MISMATCHED`) and a non-file part (`PART_NOT_A_FILE`) carry
+ * their content INSIDE the message, and `message_hash` commits it on both
+ * sides: bytes supplied beside one of those grade nothing and hide nothing,
+ * because a reader of either pack reads the content itself. Naming them would
+ * fire the caller's obligation on parts the swapped-bytes attack cannot reach
+ * at all.
+ *
+ * Why it is worth a function rather than a note. Delivering a tampered copy of
+ * a part alone is `part_mismatched`, is substituted, and fails the pair on
+ * `message_hash`. Delivering the tampered copy AND the true one is
+ * `conflicting_part_bytes`, is never substituted, and the pair VERIFIES, so
+ * adding data suppresses detection and the only trace is a refusal the
+ * receiving side publishes at its own discretion.
+ *
+ * NOT the same as "this part reads `PART_UNCHECKED`". A receiver that holds no
+ * bytes at all reads every file part that way, and that is the COMMON CASE,
+ * unchanged by A18 and not a reason to withhold `accepted`. Only a part whose
+ * bytes the receiver actually held and could not grade is in here.
+ *
+ * What this does NOT do: it cannot stop a caller writing `accepted` anyway.
+ * This module reads and does not write the record. proof#162 ratified what the
+ * record layer does instead (Phil, 2026-09-22): `accepted` keeps its meaning
+ * and the COUNT of these parts rides in an additive `context` key, REQUIRED
+ * when it is not zero, enforced against SDKs through conformance vectors. So a
+ * part missing from this list is a part no record built on that rule will ever
+ * mention.
+ */
+export function uncheckedHeldParts(reading: HeldMessage): number[] {
+  const unchecked = new Set(
+    reading.parts
+      .filter((p) => HELD_UNCHECKED_RESULTS.includes(p.result))
+      .map((p) => p.index),
+  );
+  const named = new Set<number>();
+  for (const refusal of reading.refusals) {
+    if (refusal.part !== null && unchecked.has(refusal.part)) named.add(refusal.part);
+  }
+  return [...named].sort((a, b) => a - b);
+}