@sanning/proof 0.19.1 → 0.20.0

package/dist/grading.d.ts

@@ -1,38 +1,44 @@
 import type { DeclarationCheck, DeclarationContentKind, DeclarationDeviationKind, DeclarationVerdict } from "./declaration.js";
 import { type SideContentMap } from "./side-content.js";
-export declare const PACK_VERDICTS: readonly ["verified", "partial", "pending", "not_found", "mixed", "failed", "malformed", "incomplete"];
-export type PackVerdict = (typeof PACK_VERDICTS)[number];
+import { type Problem, type ReasonKind, type Verdict } from "./claims.js";
+export declare const PACK_VERDICTS: readonly ["verified", "failed", "incomplete"];
+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. */
@@ -50,8 +56,8 @@ export interface DisclosureAccount {
     extra: string[];
 }
 /**
- * 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;
@@ -64,21 +70,14 @@ export type CompletenessNote = {
     presented: null;
     kind: "unreadable";
 };
-export declare const PACK_GRADE_CAUSE_KINDS: readonly ["records_omitted", "records_surplus", "leaf_count_unreadable", "no_disclosure", "missing_disclosure", "unreadable_disclosure", "unaccounted_disclosure", "declaration_deviation", "declaration_content_dependent"];
+export declare const PACK_GRADE_CAUSE_KINDS: readonly ["records_omitted", "records_surplus", "leaf_count_unreadable", "no_disclosure", "missing_disclosure", "unreadable_disclosure", "unaccounted_disclosure", "declaration_deviation", "declaration_content_dependent", "agent_record_nonconforming", "agent_record_incomplete"];
 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;
@@ -96,148 +95,112 @@ 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[];
 }
 /**
- * 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 declare function accountDisclosure(bundle: unknown, content: SideContentMap): DisclosureAccount;
 /**
- * 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 declare function safeInteger(value: unknown): number | 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 declare function signedLeafCount(checkpoint: {
     event_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.
+ * 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 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.
+ * 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 declare function gradeCauses(account: DisclosureAccount, notes: readonly CompletenessNote[], declaration?: DeclarationCheck | null, withheld?: readonly string[]): PackGradeCause[];
+export declare function gradeCauses(account: DisclosureAccount, notes: readonly CompletenessNote[], declaration?: DeclarationCheck | null, withheld?: readonly string[], events?: GradeInput["events"]): PackGradeCause[];
 /**
- * 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.
- *
- *   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.
+ * 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.
+ *
+ * `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 declare function gradePack(result: GradeInput, account: DisclosureAccount, notes: readonly CompletenessNote[], declaration?: DeclarationCheck | null): 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.
+ * 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 declare function renderCause(cause: PackGradeCause, subject?: string): string;