@sanning/proof 0.10.0 → 0.11.1

package/dist/declaration.d.ts

@@ -0,0 +1,284 @@
+import { type HandoffRecord } from "./handoff.js";
+import { type SideContentMap } from "./side-content.js";
+/** The declaration schema this reader knows. */
+export declare const DECLARATION_VERSION = "sanning.declaration/v1";
+/** The three states a declaration check can reach, from the §3 vocabulary. */
+export type DeclarationVerdict = "verified" | "failed" | "partial";
+export type DeclarationDeviationKind = 
+/** The declaration is written to this version and is not readable as one. */
+"declaration-malformed"
+/** A record the declaration expects is not in the pack. */
+ | "declared-absent"
+/** A record in the pack the declaration never expected. */
+ | "undeclared-present"
+/**
+ * A record declared `content_withheld` whose bytes the pack supplies INSIDE
+ * its own signed body, in `events[].content`.
+ */
+ | "withheld-but-disclosed"
+/** The pack carries one `event_id` on two or more records. */
+ | "duplicate-event-id"
+/** A claimed hand-off names a record the declaration does not declare. */
+ | "pair-record-undeclared"
+/**
+ * A claimed hand-off names a record that is not a conformant hand-off
+ * record of the side it is claimed on (envelope-spec.md 4.1).
+ */
+ | "pair-record-not-a-handoff";
+/**
+ * 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.
+ */
+export type DeclarationContentKind = 
+/**
+ * A record declared `disclosed` whose bytes reached this reader from
+ * neither channel. ALWAYS content-dependent: 5.4.1 lets those bytes travel
+ * beside the pack as `logs/<event_id>.json`, so "no bytes arrived" is a
+ * fact about what the READER was handed and never a fact about what the
+ * holder supplied. No signature covers the absence of a file nobody signed.
+ */
+"content-dependent-withholding"
+/**
+ * A record declared `content_withheld` whose bytes reached this reader ONLY
+ * from the unsigned side-content map. The pack's own body supplies none, so
+ * the holder committed to no such disclosure. The in-body half of the same
+ * rule is the `withheld-but-disclosed` DEVIATION and still fails.
+ */
+ | "content-dependent-disclosure";
+/**
+ * One way the pack and the unsigned content beside it do not line up. Named
+ * like a deviation and weighed like an absence.
+ */
+export interface DeclarationContentFinding {
+    kind: DeclarationContentKind;
+    /** The record this is about. Always one: both kinds are per-record. */
+    eventId?: string;
+}
+/** Everything this check reports that is NOT a deviation, as a closed set. */
+export type DeclarationNoteKind = 
+/**
+ * Every record declared `disclosed` supplied no bytes, so nothing was
+ * selected: the bytes did not travel with the pack.
+ */
+"disclosure-did-not-travel"
+/**
+ * A claimed hand-off side whose `event_bytes` the pack withholds. The reader
+ * cannot see what the record is either way, so it is neither a conformant
+ * hand-off record nor a non-conformant one.
+ */
+ | "pair-record-withheld";
+/**
+ * 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.
+ */
+export interface DeclarationNote {
+    kind: DeclarationNoteKind;
+    /** How many records the note is about, where it is about a count. */
+    count?: number;
+    /** The record this is about, where it is about one. */
+    eventId?: string;
+    /** Which side of a claimed hand-off named it, for `pair-record-withheld`. */
+    side?: "sent" | "received";
+    /** Which claimed hand-off, by position, for `pair-record-withheld`. */
+    pairIndex?: number;
+}
+/** One deviation, as data. A surface renders its own prose or calls `renderDeviation`. */
+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. */
+    side?: "sent" | "received";
+    /** Which claimed hand-off, by position, for the two `pair-record-` deviations. */
+    pairIndex?: number;
+    /** What is wrong with the declaration itself, for `declaration-malformed`. */
+    reason?: string;
+}
+export interface DeclarationCheck {
+    verdict: DeclarationVerdict;
+    /** Every deviation, in a fixed order. Empty is only a pass when the verdict says so. */
+    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`.
+     */
+    contentFindings: DeclarationContentFinding[];
+    /** 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.
+     */
+    present: boolean;
+    /** `event_id`s the declaration expects, in declaration order. */
+    declared: string[];
+    /** Of those, the ones declared withheld on purpose. */
+    declaredWithheld: 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.
+ */
+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.
+     */
+    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).
+     */
+    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.
+     */
+    bytesSupplied: boolean;
+}
+/**
+ * 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.
+ */
+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.
+ *
+ * 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.
+ */
+export declare function checkDeclaration(bundle: unknown, content?: SideContentMap | 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.
+ */
+export interface DeclarationClaims {
+    /**
+     * Whether the body carried a `declaration` member at all, whatever its
+     * shape. The same field `DeclarationCheck` carries, and the same meaning.
+     */
+    present: boolean;
+    /**
+     * Whether this reader could read the claim as `DECLARATION_VERSION` 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".
+     */
+    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.
+     */
+    claimedSides: string[];
+}
+/**
+ * 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.
+ */
+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.
+ */
+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.
+ */
+export declare function renderContentFinding(finding: DeclarationContentFinding): string;
+export declare function renderDeviation(deviation: DeclarationDeviation): string;