@sanning/proof 0.5.0 → 0.7.0

package/dist/grading.d.ts

@@ -0,0 +1,160 @@
+export type PackVerdict = "verified" | "partial" | "pending" | "not_found" | "mixed" | "failed" | "malformed" | "incomplete";
+/**
+ * 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.
+ */
+export interface GradeInput {
+    status: string | null | undefined;
+    events: {
+        ok: boolean;
+        contentOk: boolean | 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.
+ */
+export interface DisclosureAccount {
+    /** `event_id`s the bundle presents, in bundle order. */
+    expected: string[];
+    /** `event_id`s whose bytes were supplied. */
+    present: string[];
+    /** expected, but no bytes were supplied. */
+    missing: string[];
+    /** supplied, but not usable as evidence for the record it names. */
+    unreadable: {
+        eventId: string;
+        reason: string;
+    }[];
+    /** supplied bytes no record in the bundle accounts for. */
+    extra: string[];
+}
+/**
+ * A completeness note: 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";
+};
+export type PackGradeCauseKind = "records-omitted" | "records-surplus" | "leaf-count-unreadable" | "no-disclosure" | "missing-disclosure" | "unreadable-disclosure" | "unaccounted-disclosure";
+/**
+ * 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.
+ */
+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. */
+    signed?: number;
+    /** The count the pack actually presents for that checkpoint. */
+    presented?: number;
+    /** How many records the cause is about (missing, unaccounted, expected). */
+    count?: number;
+    /** How many records the bundle presents in total, where that frames `count`. */
+    of?: number;
+    /** The first affected `event_id`, so a reader has somewhere to look. */
+    firstEventId?: string;
+    /** Why one supplied disclosure could not be used. */
+    reason?: string;
+}
+export interface PackGrade {
+    verdict: PackVerdict;
+    /** Records whose OWN bytes bound to their OWN commitment. Nothing else. */
+    recordsVerified: number;
+    recordsFailed: number;
+    recordsUndetermined: number;
+    causes: PackGradeCause[];
+}
+/**
+ * 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".
+ *
+ * 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.
+ */
+export declare function accountDisclosure(bundle: unknown, content: Readonly<Record<string, Uint8Array>> | ReadonlyMap<string, Uint8Array>): DisclosureAccount;
+/** The `leaf_count` a checkpoint's SIGNED record commits to, or null if unreadable. */
+export declare function signedLeafCount(checkpoint: {
+    record_bytes?: unknown;
+} | null | undefined): number | null;
+/**
+ * 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.
+ */
+export declare function completenessNotes(bundle: unknown): CompletenessNote[];
+/**
+ * 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.
+ */
+export declare function gradeCauses(account: DisclosureAccount, notes: readonly CompletenessNote[]): PackGradeCause[];
+/**
+ * The verdict a surface may print, and the counts it may print beside it.
+ *
+ * The invariant, stated so a mutation test can kill it: `verified` is reachable
+ * ONLY when every record's supplied bytes bound to its own commitment and
+ * nothing is missing, unreadable, surplus or omitted.
+ *
+ * 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.
+ */
+export declare function gradePack(result: GradeInput, account: DisclosureAccount, notes: readonly CompletenessNote[]): PackGrade;
+/**
+ * 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.
+ */
+export declare function renderCause(cause: PackGradeCause, subject?: string): string;

package/dist/grading.js

@@ -0,0 +1,469 @@
+// 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.
+//
+// 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.
+//
+// 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
+//               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
+//
+// `incomplete` is the surface's word for undetermined, and it is deliberately
+// NOT `verdict.status` from `evidence-bundle.md` §3. That enum grades a signed
+// bundle; this one grades a PACK — a strictly larger object, the bundle plus
+// whatever bytes travelled beside it. A pack can be incomplete while the bundle
+// it carries is impeccable, which is exactly the case that used to render green
+// over zero hashed bytes. Widening §3 to carry `incomplete` would be a spec
+// change; keeping the two enums distinct is not.
+//
+// `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.
+//
+// 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.
+//
+// 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.
+import { hexToBytes } from "./crypto.js";
+import { hasSideContent, sideContentKeys } from "./side-content.js";
+/**
+ * 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.
+ */
+function joinKeyOf(o) {
+    if (!o)
+        return null;
+    const hasV2 = typeof o.checkpoint_ref === "string";
+    const hasV1 = typeof o.tx_id === "string";
+    if (hasV2 === hasV1)
+        return null; // neither, or both (a mixed entry)
+    return (hasV2 ? o.checkpoint_ref : o.tx_id);
+}
+function inclusionKeyOf(incl) {
+    if (!incl)
+        return null;
+    const hasV2 = typeof incl.checkpoint_ref === "string";
+    const hasV1 = typeof incl.checkpoint_tx_id === "string";
+    if (hasV2 === hasV1)
+        return null;
+    return (hasV2 ? incl.checkpoint_ref : incl.checkpoint_tx_id);
+}
+const eventsOf = (bundle) => {
+    const e = bundle?.body?.events;
+    return Array.isArray(e) ? e : [];
+};
+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.
+/**
+ * `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 ───────────────────────────────────────
+ *
+ *   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.
+ */
+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. */
+function unsafeEventIdReason(eventId) {
+    if (!SAFE_EVENT_ID.test(eventId)) {
+        return "only letters, digits, dot, underscore and dash are admitted";
+    }
+    if (eventId === "." || eventId === "..") {
+        return "a relative path entry, not a name";
+    }
+    if (eventId.endsWith(".")) {
+        return "a trailing dot is stripped on Windows, so two ids collide on one file";
+    }
+    if (WINDOWS_DEVICE_NAME.test(eventId)) {
+        return "a reserved Windows device name, which swallows a write with no file on disk";
+    }
+    if (eventId.length > MAX_EVENT_ID_LENGTH) {
+        return `longer than ${MAX_EVENT_ID_LENGTH} characters, which overruns a path component`;
+    }
+    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".
+ *
+ * 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.
+ */
+export function accountDisclosure(bundle, content) {
+    const expected = [];
+    const present = [];
+    const missing = [];
+    const unreadable = [];
+    for (const [i, ev] of eventsOf(bundle).entries()) {
+        const eventId = ev?.envelope?.event_id;
+        if (typeof eventId !== "string" || eventId.length === 0) {
+            unreadable.push({ eventId: `#${i + 1}`, reason: "the bundle event carries no event_id" });
+            continue;
+        }
+        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.
+            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.
+        if (!hasSideContent(content, eventId))
+            missing.push(eventId);
+        else
+            present.push(eventId);
+    }
+    const accounted = new Set(expected);
+    const extra = sideContentKeys(content).filter((id) => !accounted.has(id));
+    return { expected, present, missing, unreadable, extra };
+}
+/** The `leaf_count` a checkpoint's SIGNED record commits to, or null if unreadable. */
+export function signedLeafCount(checkpoint) {
+    const hex = checkpoint?.record_bytes;
+    if (typeof hex !== "string" || hex.length === 0)
+        return null;
+    try {
+        const record = JSON.parse(new TextDecoder().decode(hexToBytes(hex)));
+        const n = record?.event?.leaf_count;
+        return Number.isInteger(n) ? n : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 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.
+ */
+export function completenessNotes(bundle) {
+    const events = eventsOf(bundle);
+    const notes = [];
+    for (const cp of checkpointsOf(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.
+        if (signed === null || key === null) {
+            notes.push({ checkpointRef, signed: null, presented: null, kind: "unreadable" });
+            continue;
+        }
+        const presented = events.filter((e) => inclusionKeyOf(e?.inclusion) === key).length;
+        if (presented < signed)
+            notes.push({ checkpointRef, signed, presented, kind: "omitted" });
+        else if (presented > signed)
+            notes.push({ checkpointRef, signed, presented, kind: "surplus" });
+    }
+    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.
+ */
+export function gradeCauses(account, notes) {
+    const causes = [];
+    for (const note of notes) {
+        if (note.kind === "omitted") {
+            causes.push({
+                kind: "records-omitted",
+                checkpointRef: note.checkpointRef,
+                signed: note.signed,
+                presented: note.presented,
+                count: note.signed - note.presented,
+            });
+        }
+        else if (note.kind === "surplus") {
+            causes.push({
+                kind: "records-surplus",
+                checkpointRef: note.checkpointRef,
+                signed: note.signed,
+                presented: note.presented,
+                count: note.presented - note.signed,
+            });
+        }
+        else {
+            causes.push({ kind: "leaf-count-unreadable", checkpointRef: note.checkpointRef });
+        }
+    }
+    // "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.
+    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) {
+        causes.push({
+            kind: "missing-disclosure",
+            count: account.missing.length,
+            of: account.expected.length,
+            ...(account.missing[0] === undefined ? {} : { firstEventId: account.missing[0] }),
+        });
+    }
+    for (const u of account.unreadable) {
+        causes.push({ kind: "unreadable-disclosure", firstEventId: u.eventId, reason: u.reason });
+    }
+    if (account.extra.length > 0) {
+        causes.push({
+            kind: "unaccounted-disclosure",
+            count: account.extra.length,
+            ...(account.extra[0] === undefined ? {} : { firstEventId: account.extra[0] }),
+        });
+    }
+    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 six states of the §3 vocabulary 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 invariant, stated so a mutation test can kill it: `verified` is reachable
+ * ONLY when every record's supplied bytes bound to its own commitment and
+ * nothing is missing, unreadable, surplus or omitted.
+ *
+ * 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.
+ */
+export function gradePack(result, account, notes) {
+    const events = Array.isArray(result?.events) ? result.events : [];
+    const recordsVerified = events.filter((e) => e.ok && e.contentOk === true).length;
+    const recordsFailed = events.filter((e) => e.ok === false || e.contentOk === false).length;
+    const recordsUndetermined = events.length - recordsVerified - recordsFailed;
+    const causes = gradeCauses(account, notes);
+    let verdict;
+    if (result?.status === "malformed")
+        verdict = "malformed";
+    else if (result?.status === "failed" || recordsFailed > 0)
+        verdict = "failed";
+    else if (recordsUndetermined > 0 || causes.length > 0)
+        verdict = "incomplete";
+    else
+        verdict = passThrough(result?.status);
+    return { verdict, recordsVerified, recordsFailed, recordsUndetermined, causes };
+}
+// ---- 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.
+ */
+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`);
+        case "records-surplus":
+            return (`checkpoint ${cause.checkpointRef} commits to ${cause.signed} record(s); ${subject} presents ` +
+                `${cause.presented} — more records than the signed tree accounts for`);
+        case "leaf-count-unreadable":
+            return `checkpoint ${cause.checkpointRef} has no readable signed leaf_count — completeness is UNKNOWN`;
+        case "no-disclosure":
+            return (`no record 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`);
+        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})`);
+    }
+}

package/dist/index.d.ts

@@ -2,8 +2,12 @@ export { ACCEPTED_SPEC_MAJORS, contentHashes, jcs, specVersionSupported, verifyE
 export { bytesToHex, deriveOperatorAddress, ed25519Verify, hexToBytes, sha256Bytes, sha256Hex, utf8, verifyRsaPssSha256, } from "./crypto.js";
 export { EMPTY_TREE_ROOT_HEX, auditPath, leafHash, merkleRoot, nodeHash, verifyInclusion, } from "./merkle.js";
 export type { ContentRole, Envelope, Subject, VerificationResult, VerifyOptions } from "./types.js";
-export { ANCHOR_TRACE_BODY_TYPE, EXPORT_BODY_TYPE, disclosedContent, recomputeExportVerdict, verifyEvidenceBundle, } from "./evidence.js";
-export type { AnchorTraceBody, AttestationPayload, AttestationRecord, AttestationResult, CheckpointResult, ComposeVerdictResult, DisclosedContentResult, DisclosedEventContent, DisclosureStatus, EvidenceBundle, EvidenceBundleResult, EvidenceIssuer, EvidenceStatus, EvidenceVerdict, EventResult, ExportBody, ExportResult, OnChainOutcome, OnChainResult, PerGatewayOutcome, TraceCheckpoint, TraceEvent, TraceInclusion, VerdictAttestation, VerdictCheckpoint, VerdictEvent, VerdictObject, VerdictOnChain, VerdictOnChainGateway, VerifyEvidenceOptions, } from "./evidence.js";
+export { ANCHOR_TRACE_BODY_TYPE, ANCHOR_TRACE_BODY_TYPE_V1, ANCHOR_TRACE_BODY_TYPES, EXPORT_BODY_TYPE, STAMP_BODY_VERSION, STAMP_TRACE_BODY_TYPE, disclosedContent, recomputeExportVerdict, verifyEvidenceBundle, } from "./evidence.js";
+export type { AnchorTraceBody, AttestationPayload, AttestationRecord, AttestationResult, CheckpointResult, ComposeVerdictResult, DisclosedContentResult, DisclosedEventContent, DisclosureStatus, EvidenceBundle, EvidenceBundleResult, EvidenceIssuer, EvidenceStatus, EvidenceVerdict, EventResult, ExportBody, ExportResult, OnChainOutcome, OnChainResult, PerGatewayOutcome, AnchorRef, StampBody, StampEntry, StampResult, StampSubtree, StampSubtreeResult, StampTraceBody, TraceCheckpoint, TraceCheckpointV1, TraceEvent, TraceInclusion, VerdictAttestation, VerdictCheckpoint, VerdictEvent, VerdictObject, VerdictOnChain, VerdictOnChainGateway, VerifyEvidenceOptions, } from "./evidence.js";
+export { accountDisclosure, completenessNotes, gradeCauses, gradePack, renderCause, signedLeafCount, } from "./grading.js";
+export type { CompletenessNote, DisclosureAccount, GradeInput, PackGrade, PackGradeCause, PackGradeCauseKind, PackVerdict, } from "./grading.js";
+export { ADAPTER_CHAIN_NAMESPACES, CHAIN_READING_SCOPE, readChains, renderChainFinding, } from "./chain.js";
+export type { ChainFinding, ChainFindingKind, ChainReading, ChainSource, ChainSummary, } from "./chain.js";
 export { attestationSignatureToHex, composeExport } from "./compose.js";
 export type { ComposeExportOptions, ComposeExportResult, ExporterKey } from "./compose.js";
 export { AGENT_PROOF_SPEC_PREFIX, isAgentProofSpec, verifyAgentProofBundle } from "./agent-proof.js";