@sanning/proof 0.12.0 → 0.13.0

package/src/evidence.ts

@@ -29,6 +29,7 @@ import {
   utf8,
   verifyRsaPssSha256,
 } from "./crypto.js";
+import { isConformantHandoffRecord, isHandoffNamespace, type HeldRecord } from "./handoff.js";
 import { leafHash, verifyInclusion } from "./merkle.js";
 import {
   MAX_CANONICAL_DEPTH,
@@ -48,7 +49,8 @@ import type { Envelope } from "./types.js";
 // Only the evidence-bundle major(s) this kernel verifies. A new major is a
 // deliberate one-entry addition HERE — same fail-closed discipline as the
 // envelope verifier's ACCEPTED_SPEC_MAJORS.
-const ACCEPTED_EVIDENCE_MAJORS = ["sanning.evidence/v1"];
+/** The accepted `sanning.evidence/v1` wrapper majors; exported in both kernels (P-01, 0.13.0). */
+export const ACCEPTED_EVIDENCE_MAJORS: readonly string[] = Object.freeze(["sanning.evidence/v1"]);
 
 // The body_type this module knows how to verify structurally. An unknown
 // body_type is not a hard failure of the WRAPPER (the signature + body_hash
@@ -830,12 +832,16 @@ async function verifyBundle(
   const b = bundle as EvidenceBundle;
   const specVersionOk = isEvidenceMajorAccepted(b.spec_version);
   if (!specVersionOk) {
-    return malformed(`unsupported evidence spec_version: ${JSON.stringify(b.spec_version)}`, false);
+    // `?? null`: an ABSENT field is spelled `null`, as the Python twin's
+    // `_json_str` spells it. `JSON.stringify(undefined)` is `undefined`, and
+    // the two kernels printed two different sentences for one bundle until
+    // `verify --json` compared them byte for byte (0.13.0).
+    return malformed(`unsupported evidence spec_version: ${JSON.stringify(b.spec_version ?? null)}`, false);
   }
   if (typeof b.signature_alg === "string" && b.signature_alg !== "ed25519") {
     // The reference verifier implements ed25519 only (evidence-bundle §2 +
     // decision #2); other algs are a deliberate future addition.
-    return malformed(`unsupported signature_alg: ${JSON.stringify(b.signature_alg)}`, true);
+    return malformed(`unsupported signature_alg: ${JSON.stringify(b.signature_alg ?? null)}`, true);
   }
   if (typeof b.public_key !== "string" || typeof b.signature !== "string") {
     return malformed("evidence bundle is missing public_key/signature", true);
@@ -885,7 +891,7 @@ async function verifyBundle(
       const { signature: _sig, co_signatures: _co, ...bundleForSig } = b as EvidenceBundle & {
         co_signatures?: unknown;
       };
-      signatureOk = await ed25519Verify(b.signature, utf8(jcs(bundleForSig)), b.public_key);
+      signatureOk = await ed25519Verify(utf8(jcs(bundleForSig)), b.signature, b.public_key);
       if (!signatureOk) errors.push("wrapper Ed25519 signature verification failed");
     } catch (e) {
       errors.push(`wrapper signature verification error${thrownDetail(e)}`);
@@ -1135,7 +1141,7 @@ function parseAnchorRef(
   }
   const o = raw as Record<string, unknown>;
   if (typeof o.kind !== "string" || !/^[a-z0-9][a-z0-9._-]*$/.test(o.kind)) {
-    errors.push(`anchor_ref.kind is missing or malformed: ${JSON.stringify(o.kind)}`);
+    errors.push(`anchor_ref.kind is missing or malformed: ${JSON.stringify(o.kind ?? null)}`);
     return { ref: null, malformed: true };
   }
   if (typeof o.id !== "string" || o.id === "") {
@@ -1711,21 +1717,61 @@ async function verifyDisclosedContent(
   const evErrors: string[] = [];
   let contentOk: boolean | null = null;
 
+  // WHICH hash in the record is decided by the record's STRUCTURE
+  // (evidence-bundle §5.1 v1.19, A20). A record `envelope-spec.md` §4.1
+  // governs (`isHandoffNamespace`) commits to its message through
+  // `event.message_hash`, SHA-256 of `JCS(message object)`, and has no
+  // `content_hash`, so until A20 its disclosure bound to nothing and an honest
+  // hand-off pack could never grade `verified`. For such a record the committed
+  // hash is `event.message_hash` and nothing else: not a `content_hash` it also
+  // carries, and not the envelope's. It binds only when the record is a
+  // CONFORMANT hand-off record under the key that signed it
+  // (`isConformantHandoffRecord`) and the value is 64 characters of lowercase
+  // hex. Anything short of that commits nothing this reader will bind to, so
+  // the reading is undetermined and never true: a record dressed as a hand-off
+  // record gains no binding from the dress, and a record outside §4.1 keeps its
+  // `content_hash` exactly as before, whatever `message_hash` field it writes.
+  // The Python twin is `evidence._evaluate_content`.
   const committed: string[] = [];
   let recordContentHash: string | undefined;
+  let governed = false;
+  let handoffHash: string | undefined;
   if (eventBytes !== undefined) {
     try {
-      const record = jcsParse(eventBytes) as {
+      const parsed = jcsParse(eventBytes);
+      const record = parsed as {
         event?: { content_hash?: unknown };
-      };
-      const ch = record.event?.content_hash;
+      } | null;
+      const ch = record?.event?.content_hash;
       if (typeof ch === "string" && ch) recordContentHash = ch.toLowerCase();
+      if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+        const envelope = ev.envelope;
+        const held: HeldRecord = {
+          publicKey:
+            envelope !== null && typeof envelope === "object" && !Array.isArray(envelope)
+              ? ((envelope as { public_key?: unknown }).public_key as string)
+              : (undefined as unknown as string),
+          record: parsed as HeldRecord["record"],
+          ref: "",
+        };
+        if (isHandoffNamespace(held)) {
+          governed = true;
+          const event = (parsed as { event?: unknown }).event;
+          const mh =
+            event !== null && typeof event === "object" && !Array.isArray(event)
+              ? (event as { message_hash?: unknown }).message_hash
+              : undefined;
+          if (isConformantHandoffRecord(held) && isLowerHex(mh, 64)) handoffHash = mh;
+        }
+      }
     } catch {
       // record not JSON — the payload binding already reflects that; content
       // stays undetermined rather than throwing.
     }
   }
-  if (recordContentHash !== undefined) {
+  if (governed) {
+    if (handoffHash !== undefined) committed.push(handoffHash);
+  } else if (recordContentHash !== undefined) {
     committed.push(recordContentHash);
   } else if (ev.envelope && typeof ev.envelope === "object") {
     // Promoted fallback. Guarded: contentHashes() dereferences env.payload,
@@ -1749,16 +1795,21 @@ async function verifyDisclosedContent(
       contentOk = null;
       if (disclosed !== undefined && committed.length === 0) {
         evErrors.push(
-          "disclosed content present but no committed content_hash to bind to " +
-            "(record withheld or record has no event.content_hash) -- undetermined",
+          governed
+            ? "disclosed content present but this hand-off record commits no " +
+                "message_hash a reader can bind to (not a conformant hand-off " +
+                "record, or message_hash is not 64 lowercase hex) -- undetermined"
+            : "disclosed content present but no committed content_hash to bind to " +
+                "(record withheld or record has no event.content_hash) -- undetermined",
         );
       }
     } else {
       const got = await sha256Hex(disclosed);
       contentOk = committed.includes(got);
       if (!contentOk) {
+        const fieldName = governed ? "message_hash" : "content_hash";
         evErrors.push(
-          "disclosed content does not match the committed content_hash: " +
+          `disclosed content does not match the committed ${fieldName}: ` +
             `sha256(disclosed)=${got} committed=${committed.join("|")}`,
         );
       }
@@ -1882,7 +1933,7 @@ async function verifyStampEntry(
     // reader's dispatch key and it said v1; honouring the other spelling is
     // how a reader half-parses a shape it does not know.
     errors.push(
-      `unsupported stamp_version ${JSON.stringify(body.stamp_version)} in a ` +
+      `unsupported stamp_version ${JSON.stringify(body.stamp_version ?? null)} in a ` +
         `${STAMP_TRACE_BODY_TYPE} body (expected ${STAMP_BODY_VERSION})`,
     );
     return { result: base, witnessedHex };
@@ -2429,8 +2480,8 @@ async function verifyStampEvidence(
  * synthesis exists to drive `gatewayUnavailable`, which is what downgrades that
  * run to `partial`. Here §5.2.4 already downgrades an unwitnessed stamp to
  * `partial` on its own, with a better error. Copying the synthesis would add
- * nothing to the status and would silently move the CLI exit code from 0 to 3
- * for an unwitnessed stamp — changing what an auditor's script does, based on
+ * nothing to the status, which is `partial` either way, and would add an
+ * unreachable-gateway note for a network event that never happened, based on
  * nothing but whether the caller happened to pass a gateway list.
  */
 async function refetchStamps(
@@ -2840,8 +2891,11 @@ async function verifyExportBody(
   // step-5 erratum flagged in the slice report.
   let verdictAgreementOk = false;
   try {
-    const cachedProjection = jcs(projectVerdictForAgreement(body.kernel_verdict));
-    const freshProjection = jcs(projectVerdictForAgreement(verdict));
+    const cached = projectVerdictForAgreement(body.kernel_verdict);
+    const fresh = projectVerdictForAgreement(verdict);
+    toleratePreA20Content(cached, fresh, sourceEventsGoverned(inline));
+    const cachedProjection = jcs(cached);
+    const freshProjection = jcs(fresh);
     verdictAgreementOk = cachedProjection === freshProjection;
     if (!verdictAgreementOk) {
       errors.push(
@@ -2874,8 +2928,8 @@ async function verifyExportBody(
   ) {
     status = "failed";
   } else if (sourceResult.status === "partial") {
-    // Undetermined source (withheld record → exit 0; gateway-unreachable →
-    // exit 3 via the propagated "unreachable" note). Never a failure.
+    // Undetermined source (a withheld record, or an unreachable gateway):
+    // exit 3 either way since 0.13.0. Never a failure.
     status = "partial";
   } else {
     status = "verified";
@@ -3064,7 +3118,7 @@ async function verifyAttestation(
   if (rec.signature_alg !== "rsa-pss-sha256") {
     return {
       result,
-      malformed: `unsupported attestation signature_alg: ${JSON.stringify(rec.signature_alg)}`,
+      malformed: `unsupported attestation signature_alg: ${JSON.stringify(rec.signature_alg ?? null)}`,
     };
   }
   const pub = rec.public_key as { kty?: unknown; n?: unknown; e?: unknown } | null;
@@ -3266,7 +3320,11 @@ function eventVerdictStatus(e: EventResult): string {
 // nullish normalization) — a structural difference surfaces as disagreement,
 // which is the correct tamper signal. Works on both the cached snake_case JSON
 // and the freshly built VerdictObject.
-function projectVerdictForAgreement(v: unknown): unknown {
+function projectVerdictForAgreement(v: unknown): {
+  schema_version: string | null;
+  events: { content_ok: boolean | null }[];
+  checkpoints: unknown[];
+} {
   const o = (v ?? {}) as VerdictObject;
   const events = Array.isArray(o.events) ? o.events : [];
   const checkpoints = Array.isArray(o.checkpoints) ? o.checkpoints : [];
@@ -3304,6 +3362,69 @@ function projectVerdictForAgreement(v: unknown): unknown {
   };
 }
 
+// Per event of an export's inline `sanning.anchor.trace/v3` source, in order:
+// whether `envelope-spec.md` §4.1 governs its record. Decoded the way the
+// content binding decodes it, so an event whose record is withheld, not hex or
+// not JCS is not governed here either. The Python twin is
+// `evidence._source_events_governed`.
+function sourceEventsGoverned(source: unknown): boolean[] {
+  if (source === null || typeof source !== "object" || Array.isArray(source)) return [];
+  const s = source as { body_type?: unknown; body?: unknown };
+  if (s.body_type !== ANCHOR_TRACE_BODY_TYPE) return [];
+  const body = s.body as { events?: unknown } | null | undefined;
+  const events =
+    body !== null && typeof body === "object" && !Array.isArray(body) ? body.events : undefined;
+  if (!Array.isArray(events)) return [];
+  return events.map((raw: unknown) => {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return false;
+    const ev = raw as { event_bytes?: unknown; envelope?: unknown };
+    if (typeof ev.event_bytes !== "string") return false;
+    try {
+      const parsed = jcsParse(hexToBytes(ev.event_bytes));
+      if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return false;
+      const envelope = ev.envelope;
+      const held: HeldRecord = {
+        publicKey:
+          envelope !== null && typeof envelope === "object" && !Array.isArray(envelope)
+            ? ((envelope as { public_key?: unknown }).public_key as string)
+            : (undefined as unknown as string),
+        record: parsed as HeldRecord["record"],
+        ref: "",
+      };
+      return isHandoffNamespace(held);
+    } catch {
+      return false;
+    }
+  });
+}
+
+// The one difference §5 step 5 does not read as a disagreement
+// (evidence-export.md, evidence-bundle.md v1.19, A20): a cached `content_ok` of
+// `null` against a recomputed `true`, on an event whose record §4.1 governs. A
+// kernel before A20 could not bind a hand-off record's disclosed message, so an
+// export it composed claims less than the recompute proves, and reading that
+// as tamper failed an honest export. Only that direction: a cached `true`
+// against a recomputed `false` or `null`, `null` against `false`, and any
+// difference on a record outside §4.1 still disagree. Edits `fresh` in place
+// to match `cached` on those events. The Python twin is
+// `evidence._tolerate_pre_a20_content`.
+function toleratePreA20Content(
+  cached: { events: { content_ok: boolean | null }[] },
+  fresh: { events: { content_ok: boolean | null }[] },
+  governed: boolean[],
+): void {
+  const n = Math.min(cached.events.length, fresh.events.length);
+  for (let i = 0; i < n; i++) {
+    if (
+      governed[i] === true &&
+      cached.events[i]!.content_ok === null &&
+      fresh.events[i]!.content_ok === true
+    ) {
+      fresh.events[i]!.content_ok = null;
+    }
+  }
+}
+
 function summarizeExport(
   status: EvidenceStatus,
   source: EvidenceBundleResult,

package/src/exit-codes.ts

@@ -0,0 +1,54 @@
+// One exit-code table for every verb (0.13.0).
+//
+// Both commands, `npx @sanning/proof` and `sanning-proof`, map a verdict word to
+// an exit code through this one table, for `verify`, `case` and `export` alike,
+// and every verb's `--help` prints `EXIT_CODES_HELP` byte for byte. The twin is
+// `src/sanning_proof/exit_codes.py`; the specification is `evidence-export.md`
+// §5.
+//
+// Until 0.13.0 `verify` exited 0 on `partial` unless a gateway was unreachable,
+// while `case` exited 3 on it, so a CI gate reading `verify`'s exit code read a
+// stamp witnessed by nobody as verified. Every word that means "could not be
+// settled" now exits 3, which is the code's name: undetermined.
+
+export const EXIT_VERIFIED = 0;
+export const EXIT_FAILED = 1;
+export const EXIT_MALFORMED = 2;
+export const EXIT_UNDETERMINED = 3;
+export const EXIT_MIXED = 4;
+
+/**
+ * The exit code of each of the eight verdict words (`evidence-bundle.md` §3).
+ * `undetermined` is the name of 3, and never a word here.
+ */
+export const EXIT_CODES: Readonly<Record<string, number>> = Object.freeze({
+  verified: EXIT_VERIFIED,
+  failed: EXIT_FAILED,
+  malformed: EXIT_MALFORMED,
+  partial: EXIT_UNDETERMINED,
+  pending: EXIT_UNDETERMINED,
+  incomplete: EXIT_UNDETERMINED,
+  not_found: EXIT_UNDETERMINED,
+  mixed: EXIT_MIXED,
+});
+
+/** What every verb's help prints, identical in both commands. */
+export const EXIT_CODES_HELP = [
+  "Exit codes, one table for every verb:",
+  "  0  verified, or the export was written",
+  "  1  failed",
+  "  2  usage or malformed",
+  "  3  undetermined: partial, pending, incomplete or not_found",
+  "  4  mixed: more than one outcome, none failed; read the exceptions",
+].join("\n");
+
+/**
+ * The exit code of a verdict word. A word outside the eight is a verdict
+ * nothing can render, so it exits 2, never 0.
+ */
+export function exitCodeFor(verdict: unknown): number {
+  if (typeof verdict === "string" && Object.prototype.hasOwnProperty.call(EXIT_CODES, verdict)) {
+    return EXIT_CODES[verdict]!;
+  }
+  return EXIT_MALFORMED;
+}

package/src/grading.ts

@@ -41,13 +41,13 @@
 //               presents a different number of records than a checkpoint
 //               signed for — UNKNOWN
 //
-// `incomplete` is the surface's word for undetermined, and it is deliberately
-// NOT `verdict.status` from `evidence-bundle.md` §3. That enum grades a signed
-// bundle; this one grades a PACK — a strictly larger object, the bundle plus
-// whatever bytes travelled beside it. A pack can be incomplete while the bundle
-// it carries is impeccable, which is exactly the case that used to render green
-// over zero hashed bytes. Widening §3 to carry `incomplete` would be a spec
-// change; keeping the two enums distinct is not.
+// `incomplete` is one of the eight words of `evidence-bundle.md` §3 (v1.17,
+// A18), and it is a PACK verdict, never a bundle status. The bundle status
+// grades a signed bundle; this grades a PACK — a strictly larger object, the
+// bundle plus whatever bytes travelled beside it. A pack can be incomplete
+// while the bundle it carries is impeccable, which is exactly the case that
+// used to render green over zero hashed bytes. One vocabulary, two layers,
+// each issuing the subset it can reach.
 //
 // `recordsVerified` counts CONTENT-BOUND records only. The kernel's own
 // `event.ok` tolerates undisclosed content by design — a bundle may legitimately
@@ -86,15 +86,17 @@ import { jcsParse } from "./verifier.js";
 // A superset of `EvidenceStatus`: the four the kernel can return, plus the
 // pack-level `incomplete`, plus `pending` from the shared §3 vocabulary so a
 // kernel headline this module does not downgrade can pass through unchanged.
-export type PackVerdict =
-  | "verified"
-  | "partial"
-  | "pending"
-  | "not_found"
-  | "mixed"
-  | "failed"
-  | "malformed"
-  | "incomplete";
+export const PACK_VERDICTS = [
+  "verified",
+  "partial",
+  "pending",
+  "not_found",
+  "mixed",
+  "failed",
+  "malformed",
+  "incomplete",
+] as const;
+export type PackVerdict = (typeof PACK_VERDICTS)[number];
 
 // ---- Inputs ------------------------------------------------------------------
 
@@ -109,7 +111,17 @@ export type PackVerdict =
  */
 export interface GradeInput {
   status: string | null | undefined;
-  events: { ok: boolean; contentOk: boolean | null }[];
+  /**
+   * `eventId` and `payloadBindingOk` are read by rule version 6 alone (A22):
+   * an input that does not carry both is never withheld by its declaration,
+   * so an adapter written for rule version 5 keeps the stricter reading.
+   */
+  events: {
+    ok: boolean;
+    contentOk: boolean | null;
+    eventId?: string;
+    payloadBindingOk?: boolean | null;
+  }[];
 }
 
 /**
@@ -144,21 +156,23 @@ export type CompletenessNote =
 
 // ---- Output ------------------------------------------------------------------
 
-export type PackGradeCauseKind =
-  | "records-omitted"
-  | "records-surplus"
-  | "leaf-count-unreadable"
-  | "no-disclosure"
-  | "missing-disclosure"
-  | "unreadable-disclosure"
-  | "unaccounted-disclosure"
-  | "declaration-deviation"
+export const PACK_GRADE_CAUSE_KINDS = [
+  "records_omitted",
+  "records_surplus",
+  "leaf_count_unreadable",
+  "no_disclosure",
+  "missing_disclosure",
+  "unreadable_disclosure",
+  "unaccounted_disclosure",
+  "declaration_deviation",
   /**
    * The pack and the UNSIGNED content handed in beside it do not line up
    * (proof#147). A cause, so the pack cannot read clean over it and a reader
    * is told which record; NOT a deviation, so it never reaches `failed`.
    */
-  | "declaration-content-dependent";
+  "declaration_content_dependent",
+] as const;
+export type PackGradeCauseKind = (typeof PACK_GRADE_CAUSE_KINDS)[number];
 
 /**
  * One reason a pack is not `verified`, as data.
@@ -186,8 +200,8 @@ export interface PackGradeCause {
   reason?: string;
   /**
    * Which deviation from the pack's own declaration, for
-   * `declaration-deviation`, or which content-dependent finding, for
-   * `declaration-content-dependent`.
+   * `declaration_deviation`, or which content-dependent finding, for
+   * `declaration_content_dependent`.
    */
   deviation?: DeclarationDeviationKind | DeclarationContentKind;
 }
@@ -205,6 +219,17 @@ export interface PackGrade {
    * check was passed, which is the pre-§5.4 call.
    */
   declaration?: DeclarationVerdict;
+  /**
+   * Records WITHHELD BY THEIR DECLARATION (rule version 6, evidence-bundle
+   * 5.4.5 v1.20, A22): a readable declaration lists them in
+   * `declaredWithheld`, their `ok` is true, their `contentOk` is `null` and
+   * their `payloadBindingOk` is true. Never counted in `recordsVerified`: no
+   * byte of their content was hashed, and a surface MUST NOT print them as
+   * verified records.
+   */
+  recordsWithheld: number;
+  /** Their `event_id`s, in bundle order. */
+  withheldEventIds: string[];
 }
 
 // ---- Reading a bundle --------------------------------------------------------
@@ -522,7 +547,20 @@ export function gradeCauses(
   account: DisclosureAccount,
   notes: readonly CompletenessNote[],
   declaration?: DeclarationCheck | null,
+  withheld: readonly string[] = [],
 ): PackGradeCause[] {
+  // The `event_id`s WITHHELD BY THEIR DECLARATION (rule version 6) are taken
+  // out of `expected` and `missing` before the disclosure causes are computed,
+  // so a pack whose every record its declaration withholds earns neither
+  // `no_disclosure` nor `missing_disclosure`.
+  if (withheld.length > 0) {
+    const gone = new Set(withheld);
+    account = {
+      ...account,
+      expected: account.expected.filter((e) => !gone.has(e)),
+      missing: account.missing.filter((e) => !gone.has(e)),
+    };
+  }
   const causes: PackGradeCause[] = [];
 
   // What the pack CLAIMED to hold comes first, because it frames everything
@@ -532,7 +570,7 @@ export function gradeCauses(
   // four ways can never be reported as one vague shortfall.
   for (const deviation of declaration?.deviations ?? []) {
     causes.push({
-      kind: "declaration-deviation",
+      kind: "declaration_deviation",
       deviation: deviation.kind,
       ...(deviation.eventId === undefined ? {} : { firstEventId: deviation.eventId }),
       reason: renderDeviation(deviation),
@@ -544,7 +582,7 @@ export function gradeCauses(
   // deviation, so it never reaches `failed`.
   for (const finding of declaration?.contentFindings ?? []) {
     causes.push({
-      kind: "declaration-content-dependent",
+      kind: "declaration_content_dependent",
       deviation: finding.kind,
       ...(finding.eventId === undefined ? {} : { firstEventId: finding.eventId }),
       reason: renderContentFinding(finding),
@@ -554,7 +592,7 @@ export function gradeCauses(
   for (const note of notes) {
     if (note.kind === "omitted") {
       causes.push({
-        kind: "records-omitted",
+        kind: "records_omitted",
         checkpointRef: note.checkpointRef,
         signed: note.signed,
         presented: note.presented,
@@ -562,14 +600,14 @@ export function gradeCauses(
       });
     } else if (note.kind === "surplus") {
       causes.push({
-        kind: "records-surplus",
+        kind: "records_surplus",
         checkpointRef: note.checkpointRef,
         signed: note.signed,
         presented: note.presented,
         count: note.presented - note.signed,
       });
     } else {
-      causes.push({ kind: "leaf-count-unreadable", checkpointRef: note.checkpointRef });
+      causes.push({ kind: "leaf_count_unreadable", checkpointRef: note.checkpointRef });
     }
   }
 
@@ -578,10 +616,10 @@ export function gradeCauses(
   // reader deserves to be told the pack disclosed nothing rather than counting
   // N absences.
   if (account.expected.length > 0 && account.present.length === 0 && account.unreadable.length === 0) {
-    causes.push({ kind: "no-disclosure", count: account.expected.length, of: account.expected.length });
+    causes.push({ kind: "no_disclosure", count: account.expected.length, of: account.expected.length });
   } else if (account.missing.length > 0) {
     causes.push({
-      kind: "missing-disclosure",
+      kind: "missing_disclosure",
       count: account.missing.length,
       of: account.expected.length,
       ...(account.missing[0] === undefined ? {} : { firstEventId: account.missing[0] }),
@@ -589,12 +627,12 @@ export function gradeCauses(
   }
 
   for (const u of account.unreadable) {
-    causes.push({ kind: "unreadable-disclosure", firstEventId: u.eventId, reason: u.reason });
+    causes.push({ kind: "unreadable_disclosure", firstEventId: u.eventId, reason: u.reason });
   }
 
   if (account.extra.length > 0) {
     causes.push({
-      kind: "unaccounted-disclosure",
+      kind: "unaccounted_disclosure",
       count: account.extra.length,
       ...(account.extra[0] === undefined ? {} : { firstEventId: account.extra[0] }),
     });
@@ -614,7 +652,8 @@ export function gradeCauses(
  * the type and renders the verdict verbatim would then print the one word
  * `evidence-bundle.md` §6 forbids, over a pack this rule never graded.
  *
- * So: the six states of the §3 vocabulary pass through, and ANYTHING ELSE is
+ * So: the five words of the §3 vocabulary that a bundle status can pass up to
+ * a pack pass through, and ANYTHING ELSE is
  * `incomplete`. A verdict we cannot interpret is a check we could not run, and
  * the answer to that is UNKNOWN — never a pass, and never an accusation.
  * (`failed` and `malformed` are handled before this is reached.)
@@ -637,8 +676,9 @@ function passThrough(status: string | null | undefined): PackVerdict {
  * The verdict a surface may print, and the counts it may print beside it.
  *
  * The invariant, stated so a mutation test can kill it: `verified` is reachable
- * ONLY when every record's supplied bytes bound to its own commitment and
- * nothing is missing, unreadable, surplus or omitted.
+ * ONLY when every record's supplied bytes bound to its own commitment, or
+ * (rule version 6) the record is withheld by its declaration, and nothing is
+ * missing, unreadable, surplus or omitted.
  *
  * Precedence: malformed > failed > incomplete > the kernel's own headline.
  * A hard verdict wins — "the bytes are absent" is never reported as failure
@@ -696,8 +736,23 @@ export function gradePack(
   const events = Array.isArray(result?.events) ? result.events : [];
   const recordsVerified = events.filter((e) => e.ok && e.contentOk === true).length;
   const recordsFailed = events.filter((e) => e.ok === false || e.contentOk === false).length;
-  const recordsUndetermined = events.length - recordsVerified - recordsFailed;
-  const causes = gradeCauses(account, notes, declaration);
+  // WITHHELD BY ITS DECLARATION (rule version 6, 5.4.5 v1.20, A22, D5). All
+  // four conditions, each on its own. `declaredWithheld` is empty for an
+  // absent, unreadable or malformed declaration.
+  const declaredWithheld = new Set(declaration?.declaredWithheld ?? []);
+  const withheldEventIds = events
+    .filter(
+      (e) =>
+        typeof e.eventId === "string" &&
+        declaredWithheld.has(e.eventId) &&
+        e.ok === true &&
+        e.contentOk === null &&
+        e.payloadBindingOk === true,
+    )
+    .map((e) => e.eventId as string);
+  const recordsWithheld = withheldEventIds.length;
+  const recordsUndetermined = events.length - recordsVerified - recordsFailed - recordsWithheld;
+  const causes = gradeCauses(account, notes, declaration, withheldEventIds);
 
   let verdict: PackVerdict;
   if (result?.status === "malformed") verdict = "malformed";
@@ -714,6 +769,8 @@ export function gradePack(
     recordsFailed,
     recordsUndetermined,
     causes,
+    recordsWithheld,
+    withheldEventIds,
   };
   if (declaration != null) grade.declaration = declaration.verdict;
   return grade;
@@ -733,31 +790,31 @@ export function gradePack(
  */
 export function renderCause(cause: PackGradeCause, subject = "this pack"): string {
   switch (cause.kind) {
-    case "records-omitted":
+    case "records_omitted":
       return (
         `checkpoint ${cause.checkpointRef} commits to ${cause.signed} record(s); ${subject} presents ` +
         `${cause.presented} — ${cause.count} record(s) OMITTED`
       );
-    case "records-surplus":
+    case "records_surplus":
       return (
         `checkpoint ${cause.checkpointRef} commits to ${cause.signed} record(s); ${subject} presents ` +
         `${cause.presented} — more records than the signed tree accounts for`
       );
-    case "leaf-count-unreadable":
+    case "leaf_count_unreadable":
       return `checkpoint ${cause.checkpointRef} has no readable signed leaf_count — completeness is UNKNOWN`;
-    case "no-disclosure":
+    case "no_disclosure":
       return (
         `no event bytes were disclosed — content binding is UNKNOWN for all ${cause.count} ` +
         `record(s), not verified`
       );
-    case "missing-disclosure":
+    case "missing_disclosure":
       return (
         `${cause.count} of ${cause.of} record(s) disclose no bytes (first: ${cause.firstEventId}) — ` +
         `content binding is UNKNOWN, not verified`
       );
-    case "unreadable-disclosure":
+    case "unreadable_disclosure":
       return `the disclosure for ${cause.firstEventId} is unreadable: ${cause.reason}`;
-    case "unaccounted-disclosure":
+    case "unaccounted_disclosure":
       return (
         `${cause.count} disclosed file(s) are not accounted for by any record in this bundle ` +
         `(first: ${cause.firstEventId})`
@@ -766,9 +823,9 @@ export function renderCause(cause: PackGradeCause, subject = "this pack"): strin
     // here on `reason`. Re-deriving the sentence from the cause fields would
     // put the declaration's wording in two places, and one of the two would be
     // edited alone.
-    case "declaration-deviation":
+    case "declaration_deviation":
       return `this pack deviates from its own declaration: ${cause.reason}`;
-    case "declaration-content-dependent":
+    case "declaration_content_dependent":
       // Named as what the reader could not establish, never as what the
       // holder did: the bytes it turns on are unsigned and whoever assembled
       // the case chose them (proof#147).