@sanning/proof 0.19.0 → 0.20.0

package/dist/grading.js

@@ -1,93 +1,42 @@
-// 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 { renderContentFinding, renderDeviation } from "./declaration.js";
 import { hasSideContent, sideContentKeys } 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, } 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",
-];
-// ---- Output ------------------------------------------------------------------
+// The three verdicts (evidence-bundle.md section 3). A pack reads its claims.
+export const PACK_VERDICTS = VERDICTS;
 export const PACK_GRADE_CAUSE_KINDS = [
     "records_omitted",
     "records_surplus",
@@ -98,29 +47,20 @@ 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",
 ];
 /**
- * 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) {
     if (!o)
@@ -140,10 +80,8 @@ function inclusionKeyOf(incl) {
         return null;
     return (hasV2 ? incl.checkpoint_ref : incl.checkpoint_tx_id);
 }
-// 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) {
     const k = joinKeyOf(o);
     return k !== null && typeof o?.checkpoint_ref === "string" ? k.toLowerCase() : k;
@@ -160,82 +98,30 @@ const checkpointsOf = (bundle) => {
     const c = bundle?.body?.checkpoints;
     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 ─────────────────────────────────────────────────
- *
- * **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.
- *
- * 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 ───────────────────────────────────────
+ * `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.
  *
- *   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).
+ * 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
  *
- * ── 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) {
     if (!SAFE_EVENT_ID.test(eventId)) {
         return "only letters, digits, dot, underscore and dash are admitted";
@@ -255,32 +141,16 @@ function unsafeEventIdReason(eventId) {
     return null;
 }
 /**
- * Account for the disclosed bytes a pack handed us against the records its
- * bundle presents.
- *
- * `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".
+ * 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.
  *
- * 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, 
-// `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) {
     const expected = [];
     const present = [];
@@ -295,25 +165,13 @@ content) {
         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
@@ -324,31 +182,23 @@ content) {
     return { expected, present, missing, unreadable, extra };
 }
 /**
- * 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) {
-    // `+ 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) {
     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));
-        // 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 {
@@ -356,16 +206,10 @@ export function signedLeafCount(checkpoint) {
     }
 }
 /**
- * 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) {
     const events = eventsOf(bundle);
@@ -374,19 +218,13 @@ export function completenessNotes(bundle) {
         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)
@@ -396,16 +234,13 @@ export function completenessNotes(bundle) {
     }
     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, notes, declaration, withheld = []) {
-    // 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`.
+export function gradeCauses(account, notes, declaration, withheld = [], events = []) {
+    // 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 = {
@@ -415,11 +250,8 @@ export function gradeCauses(account, notes, declaration, withheld = []) {
         };
     }
     const causes = [];
-    // 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",
@@ -428,9 +260,8 @@ export function gradeCauses(account, notes, declaration, withheld = []) {
             reason: renderDeviation(deviation),
         });
     }
-    // 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",
@@ -439,6 +270,26 @@ export function gradeCauses(account, notes, declaration, withheld = []) {
             reason: renderContentFinding(finding),
         });
     }
+    // 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({
@@ -462,10 +313,7 @@ export function gradeCauses(account, notes, declaration, withheld = []) {
             causes.push({ kind: "leaf_count_unreadable", checkpointRef: note.checkpointRef });
         }
     }
-    // "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 });
     }
@@ -490,96 +338,41 @@ export function gradeCauses(account, notes, declaration, withheld = []) {
     return causes;
 }
 /**
- * The kernel headline this rule is willing to repeat, as an ALLOW-LIST.
- *
- * `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 = new Set([
-    "verified",
-    "partial",
-    "pending",
-    "not_found",
-    "mixed",
-]);
-function passThrough(status) {
-    return typeof status === "string" && PASS_THROUGH.has(status)
-        ? status
-        : "incomplete";
-}
-/**
- * The verdict a surface may print, and the counts it may print beside it.
+ * The verdict a surface may print, and the counts 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.
- *
- * 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.
+ * 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.
  *
- *   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, account, notes, declaration) {
     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((e) => typeof e.eventId === "string" &&
@@ -590,22 +383,19 @@ export function gradePack(result, account, notes, declaration) {
         .map((e) => e.eventId);
     const recordsWithheld = withheldEventIds.length;
     const recordsUndetermined = events.length - recordsVerified - recordsFailed - recordsWithheld;
-    const causes = gradeCauses(account, notes, declaration, withheldEventIds);
-    let verdict;
-    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 causes = gradeCauses(account, notes, declaration, withheldEventIds, events);
+    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 = {
         verdict,
+        ...(outcome.reason_kind === undefined ? {} : { reasonKind: outcome.reason_kind }),
+        problems,
         recordsVerified,
         recordsFailed,
         recordsUndetermined,
@@ -617,48 +407,102 @@ export function gradePack(result, account, notes, declaration) {
         grade.declaration = declaration.verdict;
     return grade;
 }
-// ---- Presentation (optional) -------------------------------------------------
 /**
- * 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.
+ * 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, events, account, causes, declaration, withheld) {
+    const out = bundleProblems(result, 0);
+    const ids = events.map((e) => e.eventId ?? null);
+    const records = (...eventIds) => {
+        const wanted = eventIds.map((e) => e ?? null);
+        const found = [];
+        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. 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, subject = "this pack") {
     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} ` +
+            return (`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`);
+            return (`${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}`;
         case "unaccounted_disclosure":
             return (`${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}`);
     }