@sanning/proof 0.19.1 → 0.20.0

package/src/grading.ts

@@ -1,72 +1,36 @@
-// Pack grading — what a verification SURFACE may claim about a pack it was
-// handed, as distinct from what the wrapper verdict says about a bundle.
+// Pack grading: what a verification surface may claim about a pack (a bundle
+// plus the bytes handed in beside it), as distinct from the bundle verdict.
 //
-// WHY THIS LIVES IN THE KERNEL.
-// This rule was, until now, derived twice: once in a CLI trust close and once
-// in a browser verify page, in two repos and two languages, held together by a
-// conformance table copied byte-for-byte into both. The table caught an
-// implementation drifting from the rule. Nothing caught the table itself being
-// edited on one side — and the two surfaces had already diverged once, one
-// binding disclosed bytes per record and the other believed to bind by set
-// membership. Two implementations of one verification rule is the defect; a
-// shared table is a mitigation of it.
+// Pure: no `fs`, no `fetch`. A directory read and a browser drop both arrive
+// as a content map and must produce the same grade. Causes are structured so a
+// surface can render its own prose or call `renderCause`.
 //
-// Grading is kernel semantics that leaked into consumers. The rule it encodes
-// is already normative in `specs/evidence-bundle.md`: absent disclosure — and
-// an absent committed `content_hash` — is **undetermined, not failed** (§5.1),
-// a genuine mismatch fails the event and the rollup (§5.1), and no status ever
-// means "safe" (§6). What the surfaces added was a sharper word for the
-// undetermined case and an account of what the pack failed to disclose. Both
-// belong next to the verifier that produced the result.
-//
-// ── the seam ────────────────────────────────────────────────────────────────
-//
-// Everything here is PURE: data in, data out. No `fs`, no `fetch`, no key
-// lifecycle — the kernel's standing boundary (`specs/architecture.md` §3) is
-// unchanged. How disclosed bytes were transported is a consumer concern; a
-// directory read and a browser drop both arrive here as a content map and MUST
-// produce the same verdict. `causes` come back STRUCTURED, so a surface can
-// render its own prose (or call `renderCause` and get the house wording)
-// without the kernel taking on presentation.
-//
-// ── the rule ────────────────────────────────────────────────────────────────
-//
-// Three outcomes where the old code had two:
-//
-//   verified    every record's own bytes hashed to its OWN committed
+// Outcomes (evidence-bundle.md sections 3 and 5.1), read off six claims (`claims.ts`):
+//   verified    every record's own bytes hashed to its own committed
 //               content_hash, and nothing is missing, unreadable, surplus or
 //               omitted
-//   failed      some record's bytes DISAGREE with what was committed — tamper
-//   incomplete  some record's bytes are absent or unreadable, or the pack
-//               presents a different number of records than a checkpoint
-//               signed for — UNKNOWN
+//   failed      a claim is disproven: some record's bytes disagree with its
+//               commitment, or (reason kind nonconforming) an agent record is
+//               signed and intact and does not follow its vocabulary
+//   incomplete  nothing is disproven and a claim is not proven: some record's
+//               bytes are absent or unreadable, the pack presents a different
+//               record count than a checkpoint signed, or an agent record
+//               reads partial
 //
-// `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.
+// `incomplete` is a pack verdict, never a bundle status: a pack can be
+// incomplete while its bundle is sound.
 //
-// `recordsVerified` counts CONTENT-BOUND records only. The kernel's own
-// `event.ok` tolerates undisclosed content by design — a bundle may legitimately
-// withhold a record (minimal disclosure, §5.1) — which is right for the kernel
-// and wrong for a surface whose headline is that the logs were checked.
-// Counting `ok` events is how "26 records verified" got printed over zero
-// hashed bytes.
+// `recordsVerified` counts content-bound records only. The kernel's `event.ok`
+// tolerates withheld content (minimal disclosure, §5.1), so counting `ok`
+// events would report records verified over zero hashed bytes.
 //
-// Binding is PER RECORD, never per set. The bytes disclosed for `event_id` are
-// hashed against the commitment inside THAT event's signed record; the verifier
-// does this and this module never re-implements it. A set-membership check
-// ("is this digest anywhere in the bundle?") passes a swap of two records'
-// bytes, and that is the shape of the divergence this module exists to end.
+// Binding is per record, never per set: a set-membership check passes a swap
+// of two records' bytes. The verifier does the binding; this module never
+// re-implements it.
 //
-// The conformance statement of all of the above is `../vectors/pack-grading.json`,
-// which ships in the published tarball so a consumer can diff its own vendored
-// copy against it. If an implementation disagrees with the table, the
-// implementation is wrong.
+// Conformance: `../vectors/pack-grading.json`, shipped in the package.
 
+import { INCOMPLETE_REASONS } from "./agent-record.js";
 import { hexToBytes } from "./crypto.js";
 import type {
   DeclarationCheck,
@@ -76,62 +40,57 @@ import type {
 } from "./declaration.js";
 import { renderContentFinding, renderDeviation } from "./declaration.js";
 import { hasSideContent, sideContentKeys, type SideContentMap } from "./side-content.js";
-// The kernel's one reader for bytes a producer signed: strict UTF-8, no leading
-// byte-order mark, no non-finite literal. `jcs_loads` in
-// `src/sanning_proof/canonicalize.py` is the twin (proof#140 gate 5).
+import {
+  VERDICTS,
+  bundleProblems,
+  claimsOf,
+  problem,
+  verdictOf,
+  type Problem,
+  type ProblemItem,
+  type ReasonKind,
+  type Verdict,
+} from "./claims.js";
 import { jcsParse } from "./verifier.js";
 
-// ---- The verdict a surface may print ----------------------------------------
-
-// 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 const PACK_VERDICTS = [
-  "verified",
-  "partial",
-  "pending",
-  "not_found",
-  "mixed",
-  "failed",
-  "malformed",
-  "incomplete",
-] as const;
-export type PackVerdict = (typeof PACK_VERDICTS)[number];
-
-// ---- Inputs ------------------------------------------------------------------
+// The three verdicts (evidence-bundle.md section 3). A pack reads its claims.
+export const PACK_VERDICTS = VERDICTS;
+export type PackVerdict = Verdict;
 
 /**
- * The minimum this module reads out of a verification result.
- *
- * `EvidenceBundleResult` satisfies it structurally, so a consumer normally
- * passes the kernel's own result straight through. It is stated as a minimum
- * rather than an import so a surface running an OLDER pinned kernel — or one
- * grading a result it adapted from another verifier — can still be held to
- * this rule.
+ * The minimum this module reads from a verification result.
+ * `EvidenceBundleResult` satisfies it, and an adapted result from another
+ * verifier can satisfy it too.
  */
 export interface GradeInput {
   status: string | null | undefined;
+  /** The bundle could not be read as one (`EvidenceBundleResult.unreadable`). */
+  unreadable?: boolean;
   /**
-   * `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.
+   * `eventId` and `payloadBindingOk` are read only for declared withholding
+   * (evidence-bundle §5.4.5). An input without both is never withheld, so it
+   * gets the stricter reading.
    */
   events: {
     ok: boolean;
     contentOk: boolean | null;
     eventId?: string;
     payloadBindingOk?: boolean | null;
+    /** The record's agent reading, where it is one (rule version 9). Its findings move nothing. */
+    agent?: {
+      verdict: string | null;
+      reason?: string;
+      at?: string;
+      reasons?: readonly { reason: string; at: string }[];
+      absent?: readonly string[];
+    } | null;
   }[];
 }
 
 /**
- * The account of which records disclosed bytes, and what could not be used.
- *
- * An empty account is NOT a clean bill of health: callers gate on this, never
- * on the absence of mismatches. The old readers wrapped the disclosure read in
- * `try {} catch {}` and fell back to an empty map, so deleting every log turned
- * every content check undetermined, left every event `ok`, and printed a
- * verified verdict over zero hashed bytes.
+ * Which records disclosed bytes, and what could not be used. An empty account
+ * is not a clean result: callers gate on this, never on the absence of
+ * mismatches.
  */
 export interface DisclosureAccount {
   /** `event_id`s the bundle presents, in bundle order. */
@@ -147,15 +106,13 @@ export interface DisclosureAccount {
 }
 
 /**
- * A completeness note: the pack presents a different number of records for a
- * checkpoint than that checkpoint's SIGNED record commits to.
+ * The pack presents a different number of records for a checkpoint than that
+ * checkpoint's signed record commits to.
  */
 export type CompletenessNote =
   | { checkpointRef: string; signed: number; presented: number; kind: "omitted" | "surplus" }
   | { checkpointRef: string; signed: null; presented: null; kind: "unreadable" };
 
-// ---- Output ------------------------------------------------------------------
-
 export const PACK_GRADE_CAUSE_KINDS = [
   "records_omitted",
   "records_surplus",
@@ -166,27 +123,23 @@ export const PACK_GRADE_CAUSE_KINDS = [
   "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`.
+   * The pack and the unsigned content beside it do not line up. A cause, so the
+   * pack cannot read clean; not a deviation, so it never reaches `failed`.
    */
   "declaration_content_dependent",
+  /** A reason of an agent record that reads `failed` (agent-events.md section 10): the pack is `failed`, reason kind `nonconforming`. */
+  "agent_record_nonconforming",
+  /** A reason of an agent record that reads `incomplete`: the pack is `incomplete`. */
+  "agent_record_incomplete",
 ] as const;
 export type PackGradeCauseKind = (typeof PACK_GRADE_CAUSE_KINDS)[number];
 
-/**
- * One reason a pack is not `verified`, as data.
- *
- * Structured because the two surfaces that used to derive this rule also
- * derived its prose, and prose is the part that drifts hardest and matters
- * least. `renderCause` produces the house wording; a surface with its own
- * voice reads the fields.
- */
+/** One reason a pack is not `verified`, as data. `renderCause` gives the house wording. */
 export interface PackGradeCause {
   kind: PackGradeCauseKind;
   /** The checkpoint this is about, for the completeness kinds. */
   checkpointRef?: string;
-  /** The count a checkpoint's signed record commits to. */
+  /** The count the checkpoint's signed record commits to. */
   signed?: number;
   /** The count the pack actually presents for that checkpoint. */
   presented?: number;
@@ -204,36 +157,49 @@ export interface PackGradeCause {
    * `declaration_content_dependent`.
    */
   deviation?: DeclarationDeviationKind | DeclarationContentKind;
+  /**
+   * The JSON Pointer the agent reading's reason is about, for
+   * `agent_record_nonconforming` and `agent_record_incomplete`; `reason` is its reason
+   * code (agent-events.md section 10.1).
+   */
+  at?: string;
+  /**
+   * For `agent_record_incomplete` with `listed_record_absent`, the `event_id` the
+   * closing record lists and the pack does not hold.
+   */
+  listedEventId?: string;
 }
 
 export interface PackGrade {
   verdict: PackVerdict;
+  /** `changed` or `nonconforming` where `verdict` is `failed`. */
+  reasonKind?: ReasonKind;
+  /**
+   * Every problem behind the verdict, each mapped to one claim and one state
+   * (`claims.ts`): the bundle's own, then the causes', then the declaration's.
+   * Empty exactly where `verdict` is `verified`.
+   */
+  problems: Problem[];
   /** Records whose OWN bytes bound to their OWN commitment. Nothing else. */
   recordsVerified: number;
   recordsFailed: number;
   recordsUndetermined: number;
   causes: PackGradeCause[];
   /**
-   * The declaration check's own verdict, carried so a consumer that reads only
-   * this value can tell a declared pack from an undeclared one. Absent when no
-   * check was passed, which is the pre-§5.4 call.
+   * The declaration check's verdict, so a consumer can tell a declared pack
+   * from an undeclared one. Absent when no check was passed.
    */
   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.
+   * Records withheld by their declaration (evidence-bundle §5.4.5). Never
+   * counted in `recordsVerified`: none of their content was hashed, and a
+   * surface must not print them as verified.
    */
   recordsWithheld: number;
   /** Their `event_id`s, in bundle order. */
   withheldEventIds: string[];
 }
 
-// ---- Reading a bundle --------------------------------------------------------
-
 interface BundleLike {
   body?: {
     events?: {
@@ -245,22 +211,10 @@ interface BundleLike {
 }
 
 /**
- * The checkpoint's join key, in whichever vocabulary the bundle speaks.
- *
- * ── Why this is read from the entry and not from the body_type ──
- *
- * Grading runs over a PACK, which a consumer may hand us in pieces, so the
- * wrapper is not always in scope here. Reading the key off the entry keeps
- * grading honest for both forms with no wrapper lookup. It is deliberately
- * NOT a fallback chain that would accept either spelling on the same entry:
- * an entry carrying both is a mixed bundle, and `verifyEvidenceBundle`
- * rejects it — grading must not quietly grade what the verifier refuses.
- *
- * Returning `null` (rather than a "(no tx_id)" placeholder that compares
- * equal to itself) matters: before this was dual-form, a v2 pack read every
- * checkpoint key as absent, every `presented` count as zero, and reported
- * EVERY checkpoint as "omitted" — a completeness accusation manufactured by
- * a field rename. A key we cannot read is unreadable, never zero.
+ * The checkpoint's join key, `checkpoint_ref` or the retired `tx_id`. Read from
+ * the entry because the wrapper may not be in scope. An entry carrying both is
+ * a mixed bundle the verifier rejects, so it reads as `null`. `null` means
+ * unreadable, never zero, so a key we cannot read is never counted as omitted.
  */
 function joinKeyOf(o: { checkpoint_ref?: unknown; tx_id?: unknown } | null | undefined): string | null {
   if (!o) return null;
@@ -280,10 +234,8 @@ function inclusionKeyOf(
   return (hasV2 ? incl.checkpoint_ref : incl.checkpoint_tx_id) as string;
 }
 
-// The key a checkpoint and an inclusion are MATCHED on. A `checkpoint_ref` is
-// folded to lower case, because the verifier lowercases it before comparing.
-// A retired `tx_id` / `checkpoint_tx_id` is compared exactly as written, as the
-// retired reader did, even when it happens to look like hex.
+// The key a checkpoint and an inclusion are matched on. `checkpoint_ref` is
+// lowercased, as the verifier does; a retired key is compared exactly.
 function checkpointMatchKey(o: { checkpoint_ref?: unknown; tx_id?: unknown } | null | undefined): string | null {
   const k = joinKeyOf(o);
   return k !== null && typeof o?.checkpoint_ref === "string" ? k.toLowerCase() : k;
@@ -306,84 +258,32 @@ const checkpointsOf = (bundle: unknown) => {
   return Array.isArray(c) ? c : [];
 };
 
-// Presence in a caller-built content map — DEFERRED to `side-content.ts`, which
-// is the same rule the VERIFIER applies, because two answers to "is there an
-// entry" inside one kernel is two implementations of one verification rule, and
-// ending that is why this module was brought into the kernel at all.
-//
-// This module used to answer it laxly: own + enumerable, nothing more. The
-// verifier additionally requires a DATA property (an accessor can throw, and a
-// verifier must never raise on adversarial input) holding something other than
-// null/undefined (`{ [id]: undefined }` and `new Map([[id, undefined]])` are
-// how "no entry" is spelled in the two shapes). So on one map this module said
-// PRESENT and the verifier said nothing was offered — and `gradePack` returned
-// `incomplete` with ZERO causes, the very outcome the comment in
-// `accountDisclosure` below says was removed. Now there is one definition and
-// two call sites.
+// Presence in a content map is decided by `side-content.ts`, the same rule the
+// verifier applies, so the grade and the verdict never disagree on an entry.
 
 /**
- * `event_id`s name files on every transport this rule has met. An id that
- * cannot safely name one cannot be bound to disclosed bytes, so it is refused
- * rather than joined into a path.
- *
- * ── WHAT THIS IS AND IS NOT ─────────────────────────────────────────────────
+ * `event_id`s name files on every transport. An id that cannot safely name one
+ * cannot be bound to disclosed bytes, so it reads as unreadable. This is an
+ * honesty guard, not a traversal fix (nothing here joins an id into a path);
+ * refusing an id can only move a verdict toward unknown, never toward verified.
  *
- * **Not a traversal fix, and it must not be described as one.** Nothing in
- * this kernel or in the `proof` CLI joins an `event_id` into a path: the CLI's
- * only join is `join(dirPath, name)` where `name` came from `readdir`, so the
- * id is DERIVED from a real directory entry rather than used to reach one.
- * Claiming otherwise would misrepresent a hardening as a vulnerability fix.
+ * Refused:
+ *   charset       anything outside letters, digits, dot, underscore and dash
+ *   `.` and `..`  path entries, not names
+ *   trailing dot  Windows strips it, so `a.` and `a` collide and one record's
+ *                 bytes would overwrite another's, a mismatch no tamper caused
+ *   device names  `CON`, `PRN`, `AUX`, `NUL`, `COM0-9`, `LPT0-9`, with or
+ *                 without an extension: Windows swallows the write
+ *   length        over 200, leaving room in a 255-byte path component
  *
- * It is an **honesty guard**, and it points one way only. The documented pack
- * layout is `logs/<event_id>.json`, so a downstream consumer WILL join these,
- * and an id that cannot name a file on the holder's filesystem is an id whose
- * bytes will never arrive. Saying so — `unreadable`, and therefore
- * `incomplete` — is the truth about that record. Refusing an id can only move
- * a verdict toward UNKNOWN, never toward verified, which is what makes
- * tightening this safe: the failure mode of a rule that is too strict is a
- * conservative verdict, and the failure mode of one that is too lax is a
- * record silently graded on bytes that were never there.
- *
- * ── WHAT IS REFUSED, AND WHY EACH ONE ───────────────────────────────────────
- *
- *   charset        — anything outside letters, digits, dot, underscore, dash.
- *                    No separator of any platform survives it.
- *   `.` and `..`   — not names but path entries. Under the documented `.json`
- *                    convention they are harmless (`logs/..json` is a file);
- *                    under a consumer that writes `logs/<event_id>` or uses
- *                    the id as a directory, `..` IS the parent. The kernel
- *                    does not know the convention, so it refuses the two ids
- *                    that are hazardous under any of them.
- *   trailing dot   — Windows strips it, so `a.` and `a` are one file. Two
- *                    distinct records collapsing onto one path means one
- *                    record's bytes overwrite another's, and the verifier then
- *                    reports a MISMATCH — an accusation manufactured by a
- *                    filesystem rather than by a tamper.
- *   device names   — `CON`, `PRN`, `AUX`, `NUL`, `COM0-9`, `LPT0-9`, with or
- *                    without an extension. On Windows `CON.json` is still the
- *                    console device: the write appears to succeed and nothing
- *                    is on disk.
- *   length         — a POSIX path component is 255 bytes. The charset is
- *                    ASCII, so characters are bytes; 200 leaves the documented
- *                    `.json` and room for a prefix a consumer adds, and sits
- *                    far above any real id (a UUID is 36).
- *
- * ── WHAT IS DELIBERATELY *NOT* REFUSED ──────────────────────────────────────
- *
- * **Case collisions.** `A` and `a` are distinct ids that are one file on
- * macOS and Windows. They stay legal, because banning uppercase would refuse
- * ordinary ids for a hazard the kernel cannot see: this module takes a content
- * MAP, which is case-sensitive and has already resolved the question. The
- * collision happens in the transport, and `accountDisclosure` is explicitly a
- * convenience rather than the only way to build an account — a consumer
- * reading a DIRECTORY builds its own and is the one that can detect it.
- * Pinned as a decision, not left to be rediscovered.
+ * Case collisions (`A` and `a`) stay legal: the content map is case-sensitive,
+ * and only a consumer reading a directory can see the collision.
  */
 const SAFE_EVENT_ID = /^[A-Za-z0-9._-]+$/;
 const MAX_EVENT_ID_LENGTH = 200;
 const WINDOWS_DEVICE_NAME = /^(con|prn|aux|nul|com[0-9]|lpt[0-9])(\.|$)/i;
 
-/** Why this id cannot name a file, or null if it can. Prose, for a surface. */
+/** Why this id cannot name a file, or null if it can. */
 function unsafeEventIdReason(eventId: string): string | null {
   if (!SAFE_EVENT_ID.test(eventId)) {
     return "only letters, digits, dot, underscore and dash are admitted";
@@ -404,33 +304,17 @@ function unsafeEventIdReason(eventId: string): string | null {
 }
 
 /**
- * Account for the disclosed bytes a pack handed us against the records its
- * bundle presents.
+ * Accounts for the disclosed bytes in `content` against the records the bundle
+ * presents. `content` is the map `verifyEvidenceBundle` takes; prefer a `Map`,
+ * since on a plain object an `event_id` of `__proto__` never lands. A zero-byte
+ * entry is present, not missing, so a truncated log cannot read as unknown.
  *
- * `content` is the same map `verifyEvidenceBundle` takes — a plain object or a
- * `Map` — so a caller builds it once and uses it for both. Prefer the `Map`:
- * an `event_id` is producer-chosen, and on a plain object `__proto__` is not a
- * key but a prototype setter, so bytes written under that id never land. A
- * ZERO-BYTE entry is present, not missing: bytes were supplied, the check ran,
- * and the mismatch the verifier reports stands. A truncated log must not be
- * able to launder itself into "unknown".
- *
- * A CONVENIENCE, NOT THE ONLY WAY TO BUILD AN ACCOUNT — and the difference
- * matters for one field. `extra` here can only ever name keys the content map
- * carries, so a transport whose surplus is not representable as a map entry
- * cannot report it through this function: a pack directory holding
- * `logs/notes.txt`, or a second file for a record already accounted for, is
- * invisible to a map built by iterating the bundle's own events. A consumer
- * reading a DIRECTORY should build `DisclosureAccount` itself from the real
- * listing and pass that to `gradePack` — the rule takes an account, never a
- * bundle, precisely so the transport can say things the map cannot.
+ * `extra` can only name map keys. A consumer reading a directory must build
+ * `DisclosureAccount` from the real listing to report surplus files.
  */
 export function accountDisclosure(
   bundle: unknown,
-  // `SideContentMap`, which is what `hasSideContent` and `sideContentKeys`
-  // below already take: an entry holding a string that is not hex IS an entry,
-  // and typing it out of this signature made the one map a caller builds
-  // unusable here (proof#147). A widening, so no caller moves.
+  // Any side-content entry counts, including a string that is not hex.
   content: SideContentMap,
 ): DisclosureAccount {
   const expected: string[] = [];
@@ -447,25 +331,13 @@ export function accountDisclosure(
     expected.push(eventId);
     const unsafe = unsafeEventIdReason(eventId);
     if (unsafe !== null) {
-      // The prefix is stable so a surface can group these; the suffix says
-      // which rule refused it, because "not a safe file name" alone leaves a
-      // holder with no idea what to change.
+      // A stable prefix to group on, and a suffix naming the rule that refused it.
       unreadable.push({ eventId, reason: `event_id is not a safe file name: ${unsafe}` });
       continue;
     }
-    // An OWN entry, NOT `content[eventId] === undefined`. Every key on
-    // Object.prototype — `constructor`, `toString`, `valueOf`, `__proto__` —
-    // passes SAFE_EVENT_ID (see the regex above: it admits letters, digits,
-    // dot, underscore and dash, so every one of them is a legal id here) and
-    // resolves to an inherited value, so an indexed lookup reported a record as
-    // PRESENT when nothing at all was disclosed for it. That is the module's
-    // own founding defect (absent evidence read as good evidence) reappearing
-    // one layer down: the verdict stayed `incomplete` because the verifier
-    // still had no bytes to bind, but with ZERO causes — a surface saying
-    // "incomplete" and unable to say why. `__proto__` is worse still: assigning
-    // it on a plain object either silently drops the write or replaces the
-    // object's prototype outright, so bytes a holder genuinely supplied never
-    // reach the map, and the indexed read then claimed they had.
+    // An own entry, not an indexed read: `constructor`, `__proto__` and other
+    // Object.prototype keys pass SAFE_EVENT_ID and would read as present when
+    // nothing was disclosed.
     if (!hasSideContent(content, eventId)) missing.push(eventId);
     else present.push(eventId);
   }
@@ -477,33 +349,25 @@ export function accountDisclosure(
 }
 
 /**
- * A JSON number read by its value: an integer within 2**53 - 1, or null.
- * `Number.isSafeInteger`, mirrored by `_js_safe_integer` in
- * `src/sanning_proof/chain.py`, so `2.0` is 2 in both kernels and
- * `9007199254740993`, which this parser rounds, is unreadable in both.
+ * A JSON number read by its value: an integer within 2**53 - 1, or null. So
+ * `2.0` is 2, and `9007199254740993`, which the parser rounds, is unreadable.
  */
 export function safeInteger(value: unknown): number | null {
-  // `+ 0` folds -0 into 0, which Python's `int(-0.0)` already is.
+  // `+ 0` folds -0 into 0.
   return typeof value === "number" && Number.isSafeInteger(value) ? value + 0 : null;
 }
 
-/** The `leaf_count` a checkpoint's SIGNED record commits to, or null if unreadable. */
+/** The `leaf_count` a checkpoint's signed record commits to, or null if unreadable. */
 export function signedLeafCount(checkpoint: { event_bytes?: unknown } | null | undefined): number | null {
   const hex = checkpoint?.event_bytes;
   if (typeof hex !== "string" || hex.length === 0) return null;
   try {
-    // `jcsParse`, matching `signed_leaf_count` in `src/sanning_proof/grading.py`.
-    // The pair used to agree by pointing two LENIENT decoders at one input, and
-    // that held for invalid UTF-8 and nowhere else: `TextDecoder` EATS a
-    // leading byte-order mark where Python's `errors="replace"` keeps it, so
-    // `BOM + JCS(checkpoint)` yielded a signed leaf count here and unreadable
-    // there, and that count decides a completeness note (proof#140 gate 5).
+    // The strict signed-bytes reader: a leading byte-order mark is refused, not
+    // eaten, since this count decides a verdict.
     const record = jcsParse(hexToBytes(hex)) as {
       event?: { leaf_count?: unknown };
     };
-    // Read BY VALUE, the model JCS signs: a record spelling `3.0`, `3e0` or
-    // `30e-1` commits to 3, and since A38 (proof#197) this count decides a
-    // verdict, not only a note. Past 2**53 - 1 it is unreadable, as in Python.
+    // Read by value, the model JCS signs: `3.0`, `3e0` and `30e-1` all commit to 3.
     return safeInteger(record?.event?.leaf_count);
   } catch {
     return null;
@@ -511,16 +375,10 @@ export function signedLeafCount(checkpoint: { event_bytes?: unknown } | null | u
 }
 
 /**
- * Omission — the failure a per-record check structurally cannot see.
- *
- * Drop records from a pack and every SURVIVOR still verifies perfectly:
- * signatures, inclusion proofs, content hashes, all green. The number that
- * exposes it is already in the pack and already signed — each checkpoint's
- * record commits to the `leaf_count` of the tree it anchored. This compares
- * that against how many records the pack presents for that checkpoint.
- *
- * A checkpoint whose signed count cannot be read is `unreadable`: a
- * completeness check we could not run is UNKNOWN, never a pass.
+ * Omission, which a per-record check cannot see: drop records and every
+ * survivor still verifies. Compares each checkpoint's signed `leaf_count` with
+ * the records the pack presents for it. An unreadable count is `unreadable`:
+ * a check we could not run is unknown, never a pass.
  */
 export function completenessNotes(bundle: unknown): CompletenessNote[] {
   const events = eventsOf(bundle);
@@ -529,19 +387,13 @@ export function completenessNotes(bundle: unknown): CompletenessNote[] {
     const key = joinKeyOf(cp);
     const checkpointRef = key ?? "(no checkpoint_ref)";
     const signed = signedLeafCount(cp);
-    // No readable key means we cannot count what was presented against it, so
-    // completeness is UNKNOWN — the same answer as an unreadable leaf_count,
-    // and never a shortfall.
+    // No readable key: completeness is unknown, never a shortfall.
     if (signed === null || key === null) {
       notes.push({ checkpointRef, signed: null, presented: null, kind: "unreadable" });
       continue;
     }
-    // Compared case-folded. The verifier recomputes `checkpoint_ref` and
-    // accepts it in any case (evidence-bundle.md §5.1 names lowercase hex as
-    // the form, and the kernel lowercases before comparing), so a pack whose
-    // checkpoint spells its ref in upper case still verifies. Grading it
-    // case-sensitively reported every record as omitted: a completeness
-    // accusation manufactured by letter case. The ref shown is the pack's own.
+    // Case-folded, because the verifier accepts `checkpoint_ref` in any case;
+    // otherwise an uppercase ref would report every record as omitted.
     const want = checkpointMatchKey(cp);
     const presented = events.filter((e) => inclusionMatchKey(e?.inclusion) === want).length;
     if (presented < signed) notes.push({ checkpointRef, signed, presented, kind: "omitted" });
@@ -550,22 +402,19 @@ export function completenessNotes(bundle: unknown): CompletenessNote[] {
   return notes;
 }
 
-// ---- The rule ----------------------------------------------------------------
-
 /**
- * Every reason this pack is not `verified`, in the order a reader should hear
- * them: what is missing from the whole, then what is missing from the parts.
+ * Every reason this pack is not `verified`, in reading order: what the pack
+ * claimed, then what is missing from the whole, then from the parts.
  */
 export function gradeCauses(
   account: DisclosureAccount,
   notes: readonly CompletenessNote[],
   declaration?: DeclarationCheck | null,
   withheld: readonly string[] = [],
+  events: GradeInput["events"] = [],
 ): 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`.
+  // Records withheld by their declaration are not expected, so a pack that
+  // withholds every record earns no disclosure cause.
   if (withheld.length > 0) {
     const gone = new Set(withheld);
     account = {
@@ -576,11 +425,8 @@ export function gradeCauses(
   }
   const causes: PackGradeCause[] = [];
 
-  // What the pack CLAIMED to hold comes first, because it frames everything
-  // below it: a reader told "four records are missing from what this pack says
-  // it contains" reads the per-record findings differently. Every deviation
-  // gets its own cause (one defect, one line), so a pack that deviates in
-  // four ways can never be reported as one vague shortfall.
+  // Declaration deviations first, since they frame the rest. One cause per
+  // deviation, so several are never reported as one vague shortfall.
   for (const deviation of declaration?.deviations ?? []) {
     causes.push({
       kind: "declaration_deviation",
@@ -590,9 +436,8 @@ export function gradeCauses(
     });
   }
 
-  // Then what the pack and the UNSIGNED content beside it do not agree on
-  // (proof#147). A cause, so the pack cannot read clean over it; NOT a
-  // deviation, so it never reaches `failed`.
+  // A mismatch with unsigned side content: a cause, so the pack cannot read
+  // clean, but not a deviation, so it never reaches `failed`.
   for (const finding of declaration?.contentFindings ?? []) {
     causes.push({
       kind: "declaration_content_dependent",
@@ -602,6 +447,26 @@ export function gradeCauses(
     });
   }
 
+  // Then every reason of each agent record that does not read verified (agent-events.md
+  // section 10). A reason that reads incomplete is `agent_record_incomplete`; every other
+  // reason is `agent_record_nonconforming`. A finding is never a cause: it is reported
+  // beside the record and moves nothing.
+  for (const e of events) {
+    const verdict = e.agent?.verdict;
+    if (verdict !== "failed" && verdict !== "incomplete") continue;
+    const absent = [...(e.agent?.absent ?? [])];
+    for (const r of e.agent?.reasons ?? []) {
+      const listed = r.reason === "listed_record_absent" ? absent.shift() : undefined;
+      causes.push({
+        kind: INCOMPLETE_REASONS.has(r.reason) ? "agent_record_incomplete" : "agent_record_nonconforming",
+        ...(e.eventId === undefined ? {} : { firstEventId: e.eventId }),
+        reason: r.reason,
+        at: r.at,
+        ...(listed === undefined ? {} : { listedEventId: listed }),
+      });
+    }
+  }
+
   for (const note of notes) {
     if (note.kind === "omitted") {
       causes.push({
@@ -624,10 +489,7 @@ export function gradeCauses(
     }
   }
 
-  // "Nothing at all was disclosed" is reported once, as itself. It is the
-  // regression that rendered a green banner over zero hashed bytes, and a
-  // reader deserves to be told the pack disclosed nothing rather than counting
-  // N absences.
+  // A pack that disclosed nothing is told as that, once, rather than as 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 });
   } else if (account.missing.length > 0) {
@@ -655,90 +517,34 @@ export function gradeCauses(
 }
 
 /**
- * The kernel headline this rule is willing to repeat, as an ALLOW-LIST.
+ * The verdict a surface may print, and the counts beside it.
  *
- * `GradeInput.status` is deliberately `string` so a surface can grade a result
- * from a verifier this kernel did not write. The cost of that was a hole: the
- * status used to be cast straight to `PackVerdict`, so `gradePack` would hand
- * back whatever it was given — `"mixed"` and `"not_found"` (legal, if
- * unexpected), but equally `"banana"`, `""` and `"SAFE"`. A surface that trusts
- * 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 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.)
- */
-const PASS_THROUGH: ReadonlySet<string> = new Set([
-  "verified",
-  "partial",
-  "pending",
-  "not_found",
-  "mixed",
-]);
-
-function passThrough(status: string | null | undefined): PackVerdict {
-  return typeof status === "string" && PASS_THROUGH.has(status)
-    ? (status as PackVerdict)
-    : "incomplete";
-}
-
-/**
- * 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, or
- * (rule version 6) the record is withheld by its declaration, and nothing is
+ * Invariant: `verified` only when every record's bytes bound to its own
+ * commitment or 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
- * (§5.1: undetermined, not failed), and a proven mismatch is never softened
- * into absence. The last branch passes the kernel's headline through unchanged:
- * this rule DOWNGRADES a verdict, it never invents one.
- *
- * ── the declaration (optional fourth argument) ──────────────────────────────
- *
- * `declaration` is what `checkDeclaration` in `./declaration.ts` made of the
- * pack's own signed statement of what it holds (`evidence-bundle.md` §5.4). A
- * deviation from it is a PROVEN mismatch between what the pack claimed and
- * what it carries, so it FAILS the pack and each deviation becomes its own
- * cause. It must never soften into absence: that is how a trimmed hand-over
- * reads as an innocent gap.
+ * Every problem (the bundle's, each cause, the declaration's) maps to one claim
+ * and one state (`claims.ts`) and the verdict is read off the claims (rule
+ * version 9): `failed` where a claim is disproven, else `incomplete` where one
+ * is not proven, else `verified`. Absent bytes are never a disproof (section
+ * 5.1), and a proven mismatch is never softened into absence. An agent record's
+ * findings move nothing.
  *
- * A check that came back `partial` splits in THREE (proof#147), and the first
- * of the three is not about the declaration's readability at all. The other
- * two split on whether the body carried a `declaration` member.
- *
- *   content-dependent      the pack and the UNSIGNED content beside it do not
- *                          line up (proof#147). Each finding is its own cause
- *                          and the pack is `incomplete`. It must never reach
- *                          `failed`: whoever assembles a case fills in the
- *                          side-content map, so an accuser holding an intact
- *                          pack could otherwise put its holder into `failed`
- *                          with no key at all, by dropping one file or adding
- *                          one. `failed` is left to what a signature covers.
- *   no declaration at all   nothing moves. Every pack built before §5.4 is
- *                           this case, and re-grading them would move pinned
- *                           exit codes for artifacts already in customers'
- *                           hands.
- *   present and unreadable  the pack is `incomplete`. `declaration_version` is
- *                           chosen by the same party that assembles the pack
- *                           and has no accept-set, so a holder who trims a
- *                           record and then writes one unreadable field can
- *                           re-seal the pack with its own key and hand a
- *                           reader a clean verdict over evidence of the trim
- *                           sitting inside the signed body. UNKNOWN is the
- *                           only honest answer to a claim the reader cannot
- *                           read, and it adds no cause: `PackGrade.declaration`
- *                           says why.
- *
- * `verified` adds nothing and moves nothing.
- *
- * Omitting the argument entirely is the pre-§5.4 behavior, unchanged, and
- * `PackGrade.declaration` is then absent.
+ * `declaration` is `checkDeclaration`'s result for the pack's signed statement
+ * of what it holds (§5.4):
+ *   deviation              a proven mismatch: the pack fails, one cause each
+ *   content-dependent      the pack and its unsigned side content disagree:
+ *                          `incomplete`, never `failed`, since whoever builds
+ *                          the side-content map could otherwise fail an intact
+ *                          pack without a key
+ *   no declaration         nothing moves
+ *   present and unreadable `incomplete`, with no cause and one problem,
+ *                          `pack_declaration_unreadable` (or
+ *                          `declaration_not_checked` for a chain claim this
+ *                          call was given no reading for): the pack's holder
+ *                          picks `declaration_version`, so an unreadable one
+ *                          could otherwise hide a trimmed record
+ * Omitting the argument leaves `PackGrade.declaration` absent.
  */
 export function gradePack(
   result: GradeInput,
@@ -749,9 +555,8 @@ 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;
-  // 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.
+  // Withheld by its declaration (§5.4.5) only when all four conditions hold.
+  // `declaredWithheld` is empty for an absent, unreadable or malformed declaration.
   const declaredWithheld = new Set(declaration?.declaredWithheld ?? []);
   const withheldEventIds = events
     .filter(
@@ -765,19 +570,21 @@ export function gradePack(
     .map((e) => e.eventId as string);
   const recordsWithheld = withheldEventIds.length;
   const recordsUndetermined = events.length - recordsVerified - recordsFailed - recordsWithheld;
-  const causes = gradeCauses(account, notes, declaration, withheldEventIds);
+  const causes = gradeCauses(account, notes, declaration, withheldEventIds, events);
 
-  let verdict: PackVerdict;
-  if (result?.status === "malformed") verdict = "malformed";
-  else if (result?.status === "failed" || recordsFailed > 0) verdict = "failed";
-  else if (declaration?.verdict === "failed") verdict = "failed";
-  else if (recordsUndetermined > 0 || causes.length > 0) verdict = "incomplete";
-  else if (declaration?.present === true && declaration.verdict === "partial")
-    verdict = "incomplete";
-  else verdict = passThrough(result?.status);
+  const problems = packProblems(result, events, account, causes, declaration, withheldEventIds);
+  if (recordsUndetermined > 0 && !problems.some((p) => p.claim === "unchanged")) {
+    // Fail closed: a record whose bytes were not bound and that no cause names still
+    // holds the pack below verified.
+    problems.push(problem("records_not_bound", [[0, null]]));
+  }
+  const outcome = verdictOf(claimsOf(problems));
+  const verdict = outcome.status;
 
   const grade: PackGrade = {
     verdict,
+    ...(outcome.reason_kind === undefined ? {} : { reasonKind: outcome.reason_kind }),
+    problems,
     recordsVerified,
     recordsFailed,
     recordsUndetermined,
@@ -789,41 +596,100 @@ export function gradePack(
   return grade;
 }
 
-// ---- Presentation (optional) -------------------------------------------------
+/**
+ * Every problem of one pack, read on its own (pack position 0): the bundle's, then each
+ * cause's, then the declaration's.
+ */
+function packProblems(
+  result: GradeInput,
+  events: GradeInput["events"],
+  account: DisclosureAccount,
+  causes: readonly PackGradeCause[],
+  declaration: DeclarationCheck | null | undefined,
+  withheld: readonly string[],
+): Problem[] {
+  const out = bundleProblems(result, 0);
+  const ids = events.map((e) => e.eventId ?? null);
+  const records = (...eventIds: (string | null | undefined)[]): ProblemItem[] => {
+    const wanted = eventIds.map((e) => e ?? null);
+    const found: ProblemItem[] = [];
+    ids.forEach((e, i) => {
+      if (wanted.includes(e)) found.push([0, i]);
+    });
+    return found.length > 0 ? found : [[0, null]];
+  };
+  const gone = new Set(withheld);
+  for (const c of causes) {
+    if (c.kind === "agent_record_nonconforming" || c.kind === "agent_record_incomplete") {
+      // A record the closing record lists and the pack does not hold is the item, named by
+      // its own event_id, so the line counts the records that are not held.
+      out.push(
+        problem(c.kind, c.listedEventId !== undefined ? [[0, null, c.listedEventId]] : records(c.firstEventId), {
+          rule: c.reason ?? null,
+        }),
+      );
+    } else if (c.kind === "records_omitted") {
+      out.push(problem(c.kind, [[0, null]], { count: c.count, of: c.signed, presented: c.presented }));
+    } else if (c.kind === "no_disclosure") {
+      out.push(problem(c.kind, records(...account.expected), { count: c.count }));
+    } else if (c.kind === "missing_disclosure") {
+      const missing = account.missing.filter((e) => !gone.has(e));
+      out.push(problem(c.kind, records(...missing), { count: c.count, of: c.of }));
+    } else if (c.kind === "unreadable_disclosure" || c.kind === "declaration_content_dependent") {
+      out.push(problem(c.kind, records(c.firstEventId)));
+    } else if (c.kind === "unaccounted_disclosure") {
+      out.push(problem(c.kind, [[0, null]], { count: c.count }));
+    } else if (c.kind === "declaration_deviation" && c.deviation === "declaration_malformed") {
+      // A declaration in a version this reader knows, signed with the pack, that does not
+      // parse: the producer broke its own format, and nothing was proven altered.
+      out.push(problem("declaration_nonconforming", [[0, null]]));
+    } else {
+      out.push(problem(c.kind, [[0, null]]));
+    }
+  }
+  if (declaration != null && declaration.present) {
+    if (declaration.verdict === "failed" && declaration.deviations.length === 0) {
+      out.push(problem("pack_declaration_deviates", [[0, null]]));
+    } else if (declaration.verdict === "incomplete" && declaration.contentFindings.length === 0) {
+      out.push(
+        problem(
+          declaration.version == null ? "pack_declaration_unreadable" : "declaration_not_checked",
+          [[0, null]],
+        ),
+      );
+    }
+  }
+  return out;
+}
 
 /**
- * The house wording for one cause.
- *
- * Offered, not imposed: a surface with its own voice reads the fields on
- * `PackGradeCause` instead. What must not vary between surfaces is the verdict
- * and the counts, and those come from `gradePack`.
- *
- * The `subject` names what the pack is from the reader's position — "this pack"
- * on a page someone dropped a file onto, "the pack" in a CLI report.
+ * The house wording for one cause. Optional: a surface may read the fields
+ * instead; the verdict and counts are what must not vary. `subject` is "this
+ * pack" on a page and "the pack" in a CLI report.
  */
 export function renderCause(cause: PackGradeCause, subject = "this pack"): string {
   switch (cause.kind) {
     case "records_omitted":
       return (
         `checkpoint ${cause.checkpointRef} commits to ${cause.signed} record(s); ${subject} presents ` +
-        `${cause.presented} — ${cause.count} record(s) OMITTED`
+        `${cause.presented}: ${cause.count} record(s) omitted`
       );
     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`
+        `${cause.presented}; more records than the signed tree accounts for`
       );
     case "leaf_count_unreadable":
-      return `checkpoint ${cause.checkpointRef} has no readable signed leaf_count — completeness is UNKNOWN`;
+      return `checkpoint ${cause.checkpointRef} has no readable signed leaf_count; completeness is unknown`;
     case "no_disclosure":
       return (
-        `no event bytes were disclosed — content binding is UNKNOWN for all ${cause.count} ` +
+        `no event bytes were disclosed; content binding is unknown for all ${cause.count} ` +
         `record(s), not verified`
       );
     case "missing_disclosure":
       return (
-        `${cause.count} of ${cause.of} record(s) disclose no bytes (first: ${cause.firstEventId}) — ` +
-        `content binding is UNKNOWN, not verified`
+        `${cause.count} of ${cause.of} record(s) disclose no bytes (first: ${cause.firstEventId}); ` +
+        `content binding is unknown, not verified`
       );
     case "unreadable_disclosure":
       return `the disclosure for ${cause.firstEventId} is unreadable: ${cause.reason}`;
@@ -832,16 +698,16 @@ export function renderCause(cause: PackGradeCause, subject = "this pack"): strin
         `${cause.count} disclosed file(s) are not accounted for by any record in this bundle ` +
         `(first: ${cause.firstEventId})`
       );
-    // Rendered once, by `renderDeviation` in `./declaration.ts`, and carried
-    // 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.
+    // Worded once, by `renderDeviation`, and carried on `reason`.
+    case "agent_record_nonconforming":
+      return `the agent record ${cause.firstEventId} does not conform to its vocabulary: ${cause.reason} at ${cause.at}`;
+    case "agent_record_incomplete":
+      return `the agent record ${cause.firstEventId} could not be fully read: ${cause.reason} at ${cause.at}`;
     case "declaration_deviation":
       return `this pack deviates from its own declaration: ${cause.reason}`;
     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).
+      // Worded as what the reader could not establish, never as what the
+      // holder did: the side content is unsigned.
       return (
         `${subject} and the unsigned content handed in beside it do not line up: ` +
         `${cause.reason}`