@sanning/proof 0.19.1 → 0.20.0

package/dist/declaration.d.ts

@@ -1,82 +1,46 @@
 import type { ChainLink } from "./chain.js";
 import { type HandoffRecord } from "./handoff.js";
 import { type SideContentMap } from "./side-content.js";
-/** The first declaration schema, which every earlier reader knows. */
+/** The first declaration schema. */
 export declare const DECLARATION_VERSION = "sanning.declaration/v1";
-/**
- * v1 plus a signed `records[].role` on every record (evidence-bundle.md
- * 5.4.1 v1.20, A21). A reader that knows only v1 reads a v2 declaration as one
- * it cannot read, which is the safe direction.
- */
+/** v1 plus a signed `records[].role` on every record (§5.4.1). */
 export declare const DECLARATION_VERSION_V2 = "sanning.declaration/v2";
 /**
  * v2 plus a signed `chains[]`: the `chain_key`s the holder claims are complete
- * and in order (evidence-bundle.md 5.4.1 v1.36, A45). A reader that knows only
- * v1 and v2 reads a v3 declaration as one it cannot read, which is the safe
+ * and in order (§5.4.1). An older reader cannot read it, which is the safe
  * direction.
  */
 export declare const DECLARATION_VERSION_V3 = "sanning.declaration/v3";
-/** Every declaration schema this reader knows, in the order they were added. */
+/** Every declaration schema this reader knows, oldest first. */
 export declare const DECLARATION_VERSIONS: readonly ["sanning.declaration/v1", "sanning.declaration/v2", "sanning.declaration/v3"];
 /**
- * What a v2 declaration may sign a record IS, compared exactly: `handoff`, a
- * record 4.1 governs that the pack claims as a side in `handoffs[]`, or
- * `step`, any other record.
+ * The roles a v2 declaration can sign, compared exactly: `handoff` for a
+ * record §4.1 governs that the pack claims in `handoffs[]`, `step` otherwise.
  */
 export declare const DECLARATION_ROLES: readonly ["handoff", "step"];
 export type DeclarationRole = (typeof DECLARATION_ROLES)[number];
-/** The three states a declaration check can reach, from the §3 vocabulary. */
-export declare const DECLARATION_VERDICTS: readonly ["verified", "failed", "partial"];
+export declare const DECLARATION_VERDICTS: readonly ["verified", "failed", "incomplete"];
 export type DeclarationVerdict = (typeof DECLARATION_VERDICTS)[number];
 export declare const DECLARATION_DEVIATION_KINDS: readonly ["declaration_malformed", "declared_absent", "undeclared_present", "withheld_but_disclosed", "duplicate_event_id", "pair_record_undeclared", "pair_record_not_a_handoff", "role_handoff_unclaimed", "role_step_claimed", "role_step_governed", "role_step_unreadable", "chain_second_root", "chain_fork", "chain_link_dangling", "chain_claimed_absent"];
 export type DeclarationDeviationKind = (typeof DECLARATION_DEVIATION_KINDS)[number];
 /**
- * Every way a pack and the UNSIGNED content handed in beside it fail to line
- * up, as a closed set. Neither of these is a deviation, and neither of them
- * fails (proof#147, ratified by Phil 2026-09-22).
- *
- * WHY THEY ARE NOT DEVIATIONS. 5.4 grades a pack's declaration partly against
- * content the reader was HANDED, and that content is not signed by anybody.
- * `events[].content` rides inside `body`, so the wrapper signature and
- * `body_hash` cover it and what it says about the holder is the holder's own
- * word. The side-content map is the other channel, and whoever assembles a
- * case fills it in: an accuser could put an intact pack into
- * `pack_declaration_deviates`, which contributed `failed`, WITH NO KEY AT
- * ALL, by dropping the bytes of a record the pack declared `disclosed` or by
- * adding bytes for one it declared `content_withheld`. The pack was intact,
- * its wrapper verified, and its holder had done nothing.
- *
- * This is the mirror of proof#143. There a counterparty makes itself look
- * better by choosing what it hands over; here an accuser makes a counterparty
- * look worse the same way. Both now read as what the READER established, so
- * `failed` stays for what a signature covers.
- *
- * WHAT A HOSTILE HOLDER GAINS FROM THE WEAKER WORD: nothing, because a
- * cheaper move already dominates it. Declaring a record `content_withheld` is
- * legal and grades `verified`, which is strictly better than the `incomplete`
- * these carry.
+ * Every way a pack and the unsigned content handed in beside it fail to line
+ * up. Not deviations, and never `failed`: whoever assembles a case fills the
+ * side-content map, so an accuser could otherwise fail an intact pack with no
+ * key at all. `failed` stays for what a signature covers.
  */
 export declare const DECLARATION_CONTENT_KINDS: readonly ["content_dependent_withholding", "content_dependent_disclosure"];
 export type DeclarationContentKind = (typeof DECLARATION_CONTENT_KINDS)[number];
-/**
- * One way the pack and the unsigned content beside it do not line up. Named
- * like a deviation and weighed like an absence.
- */
+/** One content finding: named like a deviation, weighed like an absence. */
 export interface DeclarationContentFinding {
     kind: DeclarationContentKind;
-    /** The record this is about. Always one: both kinds are per-record. */
+    /** The record this is about. */
     eventId?: string;
 }
-/** Everything this check reports that is NOT a deviation, as a closed set. */
+/** Everything this check reports that is not a deviation. */
 export declare const DECLARATION_NOTE_KINDS: readonly ["disclosure_did_not_travel", "pair_record_withheld", "role_step_withheld", "other_declaration_held", "other_declaration_withheld", "chain_claim_withheld"];
 export type DeclarationNoteKind = (typeof DECLARATION_NOTE_KINDS)[number];
-/**
- * One named non-deviation finding, as data.
- *
- * A note never moves the declaration verdict. It exists so the one shape rule
- * 3 deliberately does not fail is still SAID, rather than leaving a reader to
- * notice nothing was reported.
- */
+/** One named finding that is not a deviation. A note never moves the verdict. */
 export interface DeclarationNote {
     kind: DeclarationNoteKind;
     /** How many records the note is about, where it is about a count. */
@@ -90,43 +54,37 @@ export interface DeclarationNote {
     /** The claimed chain, for `chain_claim_withheld`. */
     chainKey?: string;
 }
-/** One deviation, as data. A surface renders its own prose or calls `renderDeviation`. */
+/** One deviation, as data. */
 export interface DeclarationDeviation {
     kind: DeclarationDeviationKind;
     /** The record this is about, where it is about one. */
     eventId?: string;
-    /** Which side of a claimed hand-off named it, for the two `pair-record-` deviations. */
+    /** Which side of a claimed hand-off, for the `pair_record_` deviations. */
     side?: "sent" | "received";
-    /** Which claimed hand-off, by position, for the two `pair-record-` deviations. */
+    /** Which claimed hand-off, by position, for the `pair_record_` deviations. */
     pairIndex?: number;
     /** What is wrong with the declaration itself, for `declaration_malformed`. */
     reason?: string;
-    /**
-     * The `declaration_version` the object claimed, for `declaration_malformed`,
-     * so the rendered sentence names the version the holder wrote to rather than
-     * the first one this reader learned.
-     */
+    /** The `declaration_version` the object claimed, for `declaration_malformed`. */
     version?: string;
-    /** The claimed chain, for the four rule 11 `chain_` deviations. */
+    /** The claimed chain, for the `chain_` deviations. */
     chainKey?: string;
 }
 export interface DeclarationCheck {
     verdict: DeclarationVerdict;
-    /** Every deviation, in a fixed order. Empty is only a pass when the verdict says so. */
+    /** Every deviation, in a fixed order. */
     deviations: DeclarationDeviation[];
     /**
-     * Every way the pack and the unsigned content beside it do not line up, in
-     * a fixed order. These are NOT deviations: they carry the check to
-     * `partial` and the pack to `incomplete`, never to `failed`.
+     * Mismatches with unsigned content, in a fixed order. They carry the check to
+     * `incomplete` and the pack to `incomplete`, never to `failed`.
      */
     contentFindings: DeclarationContentFinding[];
-    /** Named findings that are NOT deviations, in a fixed order. */
+    /** Named findings that are not deviations, in a fixed order. */
     notes: DeclarationNote[];
     /**
-     * Whether the body carried a `declaration` member at all, WHATEVER its
-     * shape. A string, an array or a `null` under that key is a claim the holder
-     * made and this reader cannot read, which is not the same thing as a pack
-     * that claimed nothing: `gradePack` grades the two differently.
+     * Whether the body carried a `declaration` member at all, whatever its shape.
+     * An unreadable claim is not the same as no claim: `gradePack` grades them
+     * differently.
      */
     present: boolean;
     /** `event_id`s the declaration expects, in declaration order. */
@@ -134,140 +92,70 @@ export interface DeclarationCheck {
     /** Of those, the ones declared withheld on purpose. */
     declaredWithheld: string[];
     /**
-     * The `declaration_version` this reader read the object as, one of
-     * `DECLARATION_VERSIONS`, or `null` where the body carries no declaration or
-     * one whose version this reader does not know. Set for a malformed object
-     * too: the version was read, the rest was not. Optional so a check a caller
-     * builds by hand, as rule version 5 adapters do, still type-checks.
+     * The version the object was read as, or `null` where there is no
+     * declaration or its version is unknown. Set for a malformed object too.
      */
     version?: string | null;
-    /**
-     * Every record a v2 declaration signs a role for, in declaration order.
-     * Empty for v1, and for anything this reader could not read.
-     */
+    /** Every record a v2 or v3 declaration signs a role for, in declaration order. */
     roles?: {
         eventId: string;
         role: DeclarationRole;
     }[];
-    /**
-     * Every `chain_key` a v3 declaration claims is complete and in order, in
-     * declaration order. Empty for v1 and v2, and for anything this reader could
-     * not read.
-     */
+    /** Every `chain_key` a v3 declaration claims, in declaration order. */
     chains?: string[];
 }
 /**
- * One of the pack's own records: the id, and whether the pack supplied its
- * bytes.
- *
- * An event with no readable `event_id` is given a positional name, the same
- * `#n` convention `accountDisclosure` uses, so it is still reported rather
- * than dropped. An unnameable record cannot be declared, so it can only ever
- * be surplus, which is a deviation and is named as one.
+ * One of the pack's own records. An event with no readable `event_id` gets a
+ * positional `#n` name, so it is reported as surplus rather than dropped.
  */
 export interface PackRecord {
     eventId: string;
     nameable: boolean;
-    /**
-     * Whether bytes for this record reached the reader at ALL, from either
-     * channel. This is what the disclosure account counts.
-     */
+    /** Whether bytes reached the reader from either channel. */
     disclosed: boolean;
     /**
-     * Whether the bytes came from `events[].content`, INSIDE the body the
-     * wrapper signed and `body_hash` commits to. The two channels are kept
-     * apart because only this one is the holder's own word: the side-content
-     * map is filled in by whoever assembled the case (proof#147).
+     * Whether the bytes came from `events[].content`, inside the signed body.
+     * Only this channel is the holder's own word.
      */
     disclosedInBody: boolean;
     publicKey: string;
     record: HandoffRecord | null;
     /**
-     * Whether the pack SUPPLIED `event_bytes` for this record at all.
-     * `event_bytes` is OPTIONAL (evidence-bundle.md 5.1 and 5.3), and
-     * withholding it is minimum disclosure rather than a defect, so "the pack
-     * supplied bytes this reader cannot read" and "the pack supplied none" are
-     * two different readings and never one.
+     * Whether the pack supplied `event_bytes` at all. Supplied-but-unreadable and
+     * not supplied are different readings: withholding is minimum disclosure.
      */
     bytesSupplied: boolean;
     /**
-     * Whether this record's payload binding is UNDETERMINED: no `event_bytes`
-     * string and no inline envelope `payload`, the two things the envelope
-     * verifier binds `payload_hash` against. Rule 11 excuses a dangling link
-     * only for such a record's producing key.
+     * Whether the payload binding is undetermined: no `event_bytes` and no inline
+     * `payload`. Rule 11 excuses a dangling link only for such a record's key.
      */
     bindingUndetermined: boolean;
     /**
-     * The envelope's signed `payload_hash` as written, or `""`. For a record
-     * whose binding is undetermined it is the identity a successor's pointer
-     * names: rule 11 excuses a dangling link only where the pointer equals it.
+     * The envelope's signed `payload_hash`, or `""`. Rule 11 excuses a dangling
+     * link only where the pointer equals it.
      */
     payloadHash: string;
 }
 /**
- * The pack's own records, in bundle order. Exported so the CASE layer
- * (`./case.ts`, anchor#198) reads a pack through the SAME parser that grades
- * it here, rather than through a second one beside it. A validation copied
- * next to the one that enforces it drifts, and a copy that is looser blesses
- * a value the real one then rejects.
+ * The pack's own records, in bundle order. Exported so `./case.ts` reads a
+ * pack through the same parser that grades it.
  */
 export declare function packRecords(bundle: unknown, content: SideContentMap | null | undefined): PackRecord[];
 /**
  * Check a pack against the declaration inside its body.
  *
- * `content` is the same side-content map `verifyEvidenceBundle` takes, and is
- * optional: a pack that discloses its bytes in the body needs no side input,
- * and a pack that discloses them beside itself passes the map a consumer
- * already built.
- *
- * `chains` is `readChains` over the SAME bundle. Only a v3 declaration that
- * claims a chain reads it (rule 11). It is an argument rather than computed
- * here because `readChains` is asynchronous and this check is not, and Python's
- * `check_declaration` takes it the same way so the two kernels share one
- * contract. A v3 declaration that claims a chain, checked without it, reads as
- * a reader that does not know v3 reads it: `partial`, nothing named, and the
- * pack `incomplete`. Leaving it out can never read `verified`.
+ * @param content - The side-content map `verifyEvidenceBundle` takes.
+ * @param chains - `readChains` over the same bundle, read only for a v3 chain
+ *   claim. Omitted, such a claim reads `incomplete`, never `verified`.
  *
- * The verdict is this check's own. It does not restate the bundle verdict and
- * it does not read it: a declaration can match perfectly over a pack whose
- * signatures are forged, and saying so is `gradePack`'s job, which takes both.
+ * The verdict does not read the bundle verdict: a declaration can match over
+ * forged signatures, and `gradePack` combines the two.
  */
 export declare function checkDeclaration(bundle: unknown, content?: SideContentMap | null, links?: readonly ChainLink[] | null): DeclarationCheck;
 /**
- * The house wording for one deviation.
- *
- * Offered, not imposed, exactly as `renderCause` is: what must not vary
- * between surfaces is the verdict and the set of deviations, and those come
- * from `checkDeclaration`. Both kernels return this same text for the same
- * deviation, and `cross-kernel/run_cli.sh` holds the two commands to it.
- */
-/**
- * One line a surface can print beside the pack verdict: what the pack claimed
- * to hold, and whether it does.
- *
- * Both kernels' commands print this sentence, so a reader who runs
- * `sanning-proof verify` and `npx @sanning/proof verify` over one pack reads
- * one sentence rather than two that differ by a word.
- *
- * `partial` is spelled out rather than printed as a word, because "partial" on
- * its own beside a green pack reads as a hedge. What it means is that nobody
- * said what the pack was meant to contain, and a reader deciding whether this
- * is a full hand-over needs that in words.
- */
-/**
- * What a pack's declaration CLAIMS, for a reader one layer out.
- *
- * `checkDeclaration` answers "does this pack agree with its own claim". A case
- * reader (`./case.ts`, anchor#198) needs a different thing from the same
- * object: which records the holder claimed as a hand-off side at all, so that
- * a conformant hand-off record the holder claimed NOWHERE is a named finding
- * rather than a silence. That is the door proof#137 ratified open at this
- * layer: `handoffs[]` MAY be empty, so rule 2 cannot reach a declared record
- * and rule 7 cannot reach an unclaimed one.
- *
- * It is read HERE, from the same two functions `checkDeclaration` reads,
- * rather than restated in the case layer. A second reader of one object drifts
- * from the first, and a looser copy blesses a claim the real one rejects.
+ * What a pack's declaration claims, for `./case.ts`: which records the holder
+ * claimed as a hand-off side, so a hand-off record claimed nowhere is a named
+ * finding. Read from the same functions `checkDeclaration` uses.
  */
 export interface DeclarationClaims {
     /**
@@ -276,54 +164,40 @@ export interface DeclarationClaims {
      */
     present: boolean;
     /**
-     * Whether this reader could read the claim as one of `DECLARATION_VERSIONS` AND the
-     * object satisfies 5.4.1. `false` covers an absent declaration, an unknown
-     * version and a malformed object, and a case reader must not read any of the
-     * three as "the holder claimed nothing to check".
+     * Whether the claim reads as a known version and satisfies §5.4.1. `false`
+     * never means "the holder claimed nothing to check".
      */
     readable: boolean;
     /** The case the declaration names, where it names one. */
     caseId: string | null;
-    /**
-     * Every `event_id` a `handoffs[]` entry names on either side, in declaration
-     * order, with no duplicates. Empty where the holder claimed no pair, which
-     * is legal and is exactly the shape a case reader has to name.
-     */
+    /** Every `event_id` a `handoffs[]` entry names, in order, without duplicates. */
     claimedSides: string[];
-    /**
-     * The version the claim was read as, where `readable`; else `null`. The case
-     * reader's claim check is v1's alone (5.5.1 v1.20): a v2 pack's claim check
-     * is rule 9, which the declaration check already ran.
-     */
+    /** The version the claim was read as, where `readable`; else `null`. */
     version: string | null;
-    /** Every record a READABLE v2 declaration signs a role for. Empty for v1. */
+    /** Every record a readable v2 or v3 declaration signs a role for. */
     roles: {
         eventId: string;
         role: DeclarationRole;
     }[];
 }
 /**
- * Read the claim a pack's declaration makes, without grading the pack.
- *
- * Deliberately total: a bundle this reader cannot read comes back with
- * `readable: false` rather than throwing, because a case reader grades what it
- * was handed and a reader that throws on a hostile pack cannot report that the
- * pack is hostile.
+ * Read the claim a pack's declaration makes, without grading the pack. Total:
+ * never throws, so a hostile pack is reported rather than crashing the reader.
  */
 export declare function declarationClaims(bundle: unknown): DeclarationClaims;
-export declare function renderDeclarationSummary(check: DeclarationCheck): string;
 /**
- * The house wording for one note. Offered, not imposed, as `renderDeviation`
- * is.
+ * One line a surface can print beside the pack verdict. Both kernels print the
+ * same sentence.
  */
+export declare function renderDeclarationSummary(check: DeclarationCheck): string;
+/** The house wording for one note. */
 export declare function renderNote(note: DeclarationNote): string;
 /**
- * The house wording for one content-dependent finding.
- *
- * EVERY SENTENCE HERE NAMES THE CONTENT AND NOT THE HOLDER. That is the whole
- * point of the kind: the bytes are unsigned and whoever assembled the case
- * chose them, so a sentence that reads as an accusation would put the weaker
- * word beside the stronger claim and an auditor would read the claim.
+ * The house wording for one content finding. Names the content, never the
+ * holder: the bytes are unsigned.
  */
 export declare function renderContentFinding(finding: DeclarationContentFinding): string;
+/**
+ * The house wording for one deviation. Both kernels return the same text.
+ */
 export declare function renderDeviation(deviation: DeclarationDeviation): string;