@sanning/proof 0.12.0 → 0.14.0

package/dist/case.d.ts

@@ -166,7 +166,9 @@
  *    gets, since that reads wrapper keys.
  *
  *    Not exits: a record whose envelope verifies and whose content does not
- *    match its commitment is `RECORD_CONTENT_MISMATCH`, and one that fails
+ *    match its commitment is `RECORD_CONTENT_MISMATCH` where that content is
+ *    inside the signed body and `RECORD_CONTENT_DEPENDENT` where it was handed
+ *    in beside the pack (proof#159), and one that fails
  *    another check inside its pack is `RECORD_DOES_NOT_VERIFY_IN_ITS_PACK`.
  *    Both are named and both STAY in the pile, so neither unsigned content
  *    handed in beside a pack nor a broken inclusion proof removes a record
@@ -207,7 +209,9 @@
  * verdict, exactly as `counterpart_absent` and `not_a_handoff_record` are
  * findings beside a verdict in 4.1.
  *
- * A case with more than one outcome is `mixed` (anchor#198, criterion 4).
+ * A case with any `failed` contribution is `failed`: a proven failure keeps
+ * the headline (5.5.4 v1.16, A17, proof#158). Otherwise a case with more than
+ * one outcome is `mixed` (anchor#198, criterion 4).
  *
  * WHAT THIS READER DOES NOT CLAIM
  * ===============================
@@ -237,6 +241,8 @@
  * sequence. Narrowing any of it here with `handoffs[]` is precisely the move
  * that would reopen proof#137's door.
  */
+import { type DeclarationRole } from "./declaration.js";
+import { type PackGradeCauseKind, type PackVerdict } from "./grading.js";
 import type { SideContentMap } from "./side-content.js";
 /**
  * The verdicts a case can reach. Every one is already in use in
@@ -550,17 +556,26 @@ export declare const PACK_KEY_UNREADABLE = "pack_key_unreadable";
  */
 export declare const PACK_DOES_NOT_VERIFY = "pack_does_not_verify";
 /**
- * The pack's wrapper HOLDS and its own bundle verdict, from
- * `verifyEvidenceBundle` run here offline over the pack and the content handed
- * in beside it, is not `verified`. The exception carries that verdict
- * (`status`) and the verifier's reasons (`reasons`: its bundle errors, then its
- * stamp errors, then its checkpoint errors, each as the verifier wrote it), and
- * it CONTRIBUTES that verdict, so the case verdict never reads above its
- * weakest pack. Gate 3 on proof#140: two unwitnessed (`partial`) packs read as
- * a `verified` case with no exception. It does not say who is at fault:
- * content handed in beside a pack is not signed by its holder.
- */
-export declare const PACK_BUNDLE_NOT_VERIFIED = "pack_bundle_not_verified";
+ * The pack's wrapper HOLDS and its CASE GRADE is not `verified`
+ * (evidence-bundle 5.5.1 step 1 v1.20, A23; it replaces
+ * `pack_bundle_not_verified`, which carried the bundle status alone). The case
+ * grade is the pack grade of 5.4.5, taken twice: the SIGNED grade over the run
+ * with the side map empty, and the FULL grade over the run with it. The signed
+ * grade decides where it is `failed` or `malformed`; a failure only the full
+ * grade reaches is `incomplete`, because it rests on bytes nobody signed;
+ * otherwise the full grade. A body the verifier could not read is `malformed`,
+ * a body that is not one of the two event-carrying bodies takes the signed
+ * run's status, and a verifier that graded a different number of records than
+ * the pack holds takes the signed status, or `malformed` where that status is
+ * `verified`.
+ *
+ * The exception carries `status`, the case grade; `causes`, the 5.4.5 cause
+ * kinds of the grade that decided it (none in the first three branches); and
+ * `reasons`, the verifier's reasons from the run with the side map empty. It
+ * CONTRIBUTES the grade, and `incomplete` for `pending`, `not_found` or
+ * `mixed`, so the case verdict never reads above its weakest pack.
+ */
+export declare const PACK_GRADE_NOT_VERIFIED = "pack_grade_not_verified";
 /**
  * A record in a pack whose wrapper holds, whose OWN envelope does not verify
  * (`EventResult.envelopeOk` is false). Not read by 4.1, and NAMED with the
@@ -581,12 +596,39 @@ export declare const RECORD_ENVELOPE_DOES_NOT_VERIFY = "record_envelope_does_not
 export declare const RECORD_DOES_NOT_VERIFY_IN_ITS_PACK = "record_does_not_verify_in_its_pack";
 /**
  * A record whose envelope verifies and whose disclosed content does not hash to
- * the `content_hash` it commits to (`EventResult.contentOk` is false). `failed`,
- * and the record STAYS in the pile: content beside a pack is unsigned and often
+ * the hash it commits to, its `content_hash` or a hand-off record's
+ * `message_hash` (evidence-bundle v1.19, A20) (`EventResult.contentOk` is false), with the
+ * side map EMPTY: the content is inside the signed body. The same mismatch from
+ * content handed in beside the pack is `RECORD_CONTENT_DEPENDENT` (proof#159).
+ * `failed`, and the record STAYS in the pile: content beside a pack is unsigned and often
  * supplied by whoever assembled the case, and gate 3 on proof#140 showed that
  * party erasing an honest verified pair by swapping it.
  */
 export declare const RECORD_CONTENT_MISMATCH = "record_content_mismatch";
+/**
+ * The two readings proof#147 did not reach, given its shape (proof#159, ruled
+ * by Phil 2026-09-22, evidence-bundle.md 5.5.4 v1.16, A17). A pack whose
+ * bundle verdict is `failed` ONLY when read with the unsigned content handed
+ * in beside it, and `failed` no longer when read with that map empty, is
+ * `PACK_BUNDLE_CONTENT_DEPENDENT`; a record whose content mismatch comes from
+ * that map alone is `RECORD_CONTENT_DEPENDENT`. Both are `incomplete`: the
+ * reader established that the bytes it was handed are not the bytes the record
+ * commits to, and nothing about the party that signed the record, because
+ * whoever assembled the case chose those bytes with no key. Up to v1.15 both
+ * readings carried `failed`, and one flipped nibble of accuser-supplied content
+ * put a `failed` against an intact pack; under A17's headline rule that would
+ * have become the case's headline.
+ *
+ * The test that separates the two is the one proof#159 states for the inverse:
+ * every deviation a signature covers still reads `failed` with the side map
+ * EMPTY. So the pack is verified twice, with the map and without it, and what
+ * fails without it is `PACK_GRADE_NOT_VERIFIED`, `RECORD_CONTENT_MISMATCH`
+ * (content inside the signed body) or `RECORD_DOES_NOT_VERIFY_IN_ITS_PACK`,
+ * each still `failed`. Emptying the map is the most a party that signed
+ * nothing can do to starve the check, and it cannot remove any of those.
+ */
+export declare const PACK_BUNDLE_CONTENT_DEPENDENT = "pack_bundle_content_dependent";
+export declare const RECORD_CONTENT_DEPENDENT = "record_content_dependent";
 /**
  * A record signed under a ratified profile that is under quarantine
  * (`CASE_QUARANTINED_PROFILES`, pending DL-63). Not read, in any kernel.
@@ -596,16 +638,27 @@ export declare const RECORD_PROFILE_QUARANTINED = "record_profile_quarantined";
 /** The reader was handed no packs at all. */
 export declare const CASE_HOLDS_NO_PACKS = "case_holds_no_packs";
 /**
- * Every pack was read and not one hand-off record came out of any of them.
- * There is no hand-off to have a verdict about, and saying `verified` over that
- * would be the defect class in its purest form.
+ * The three NOTEs (5.5.3 v1.20, extended proof#148): findings on the reading
+ * with no contribution, printed in the scope sentence so a clean verdict
+ * never hides any of them. `pack_undeclared` is a note only where the
+ * reading holds no hand-off record; where it holds one, it is the exception
+ * of that name.
+ */
+export declare const CONTENT_WITHHELD_BY_DECLARATION = "content_withheld_by_declaration";
+/**
+ * A pack's wrapper carries a present `co_signatures` (evidence-bundle.md §2,
+ * decided by Phil 2026-09-24 on proof#148). The field verifies nothing and
+ * sits outside the wrapper's signed scope, so the case reading names it
+ * rather than presenting it as evidence, and it contributes no verdict.
  */
-export declare const CASE_HOLDS_NO_HANDOFF_RECORDS = "case_holds_no_handoff_records";
+export declare const CO_SIGNATURES_PRESENT = "co_signatures_present";
+export declare const CASE_NOTE_KINDS: readonly ["pack_undeclared", "content_withheld_by_declaration", "co_signatures_present"];
+export type CaseNoteKind = (typeof CASE_NOTE_KINDS)[number];
 /**
  * Every exception this reader can report, as a closed set. A surface may render
  * them and a test may assert over them; nothing outside this array is emitted.
  */
-export declare const CASE_EXCEPTION_KINDS: readonly ["counterpart_absent", "counterpart_absent_from_counterparty_records", "counterpart_absent_signer_unknown", "counterpart_ambiguous", "counterpart_malformed", "pair_failed", "record_malformed", "record_unclaimed_by_its_pack", "record_bytes_withheld", "record_bytes_unreadable", "pack_declaration_deviates", "pack_declaration_content_dependent", "pack_declaration_unreadable", "pack_undeclared", "pack_body_type_unknown", "pack_holds_no_records", "pack_key_unreadable", "pack_does_not_verify", "pack_bundle_not_verified", "record_envelope_does_not_verify", "record_does_not_verify_in_its_pack", "record_content_mismatch", "record_profile_quarantined", "case_holds_no_packs", "case_holds_no_handoff_records"];
+export declare const CASE_EXCEPTION_KINDS: readonly ["counterpart_absent", "counterpart_absent_from_counterparty_records", "counterpart_absent_signer_unknown", "counterpart_ambiguous", "counterpart_malformed", "pair_failed", "record_malformed", "record_unclaimed_by_its_pack", "record_bytes_withheld", "record_bytes_unreadable", "pack_declaration_deviates", "pack_declaration_content_dependent", "pack_declaration_unreadable", "pack_undeclared", "pack_body_type_unknown", "pack_holds_no_records", "pack_key_unreadable", "pack_does_not_verify", "pack_grade_not_verified", "pack_bundle_content_dependent", "record_envelope_does_not_verify", "record_does_not_verify_in_its_pack", "record_content_mismatch", "record_content_dependent", "record_profile_quarantined", "case_holds_no_packs"];
 export type CaseExceptionKind = (typeof CASE_EXCEPTION_KINDS)[number];
 /**
  * One pack in a case, as a reader was handed it.
@@ -647,11 +700,18 @@ export interface CaseException {
      * (v1.17, A20), and it is how many were set aside.
      */
     count?: number;
-    /** The pack's own bundle verdict, for `PACK_BUNDLE_NOT_VERIFIED`. */
+    /** The pack's case grade, for `PACK_GRADE_NOT_VERIFIED`. */
     status?: CaseVerdict;
+    /**
+     * The 5.4.5 cause kinds of the grade that decided the case grade, for
+     * `PACK_GRADE_NOT_VERIFIED`, in the grade's order. Empty where the grade was
+     * not computed (an unreadable body, a body that is not one of the two
+     * event-carrying ones, a verifier that graded too few records).
+     */
+    causes?: PackGradeCauseKind[];
     /**
      * What the bundle verifier said, as it said it, for the kinds that carry a
-     * verifier's grading: `PACK_BUNDLE_NOT_VERIFIED` and the three record kinds
+     * verifier's grading: `PACK_GRADE_NOT_VERIFIED` and the three record kinds
      * graded on the record's own envelope and content.
      */
     reasons?: string[];
@@ -672,6 +732,52 @@ export interface CaseRecordReading {
     findings: string[];
     failedChecks: string[];
     counterparts: string[];
+    /**
+     * The role the pack's v2 declaration signs for this record, `handoff` or
+     * `step`, or `null` where the pack's declaration is absent, unreadable or
+     * v1, or does not declare the record (5.5.1 v1.20).
+     */
+    role: DeclarationRole | null;
+}
+/**
+ * One NOTE on the reading (5.5.3 v1.20): something true a reader needs and
+ * nothing a reader could not tell, so it carries no contribution.
+ */
+export interface CaseNote {
+    kind: CaseNoteKind;
+    /** Which pack, by the reader's own name for it. */
+    packRef: string;
+    /**
+     * For `CONTENT_WITHHELD_BY_DECLARATION`, how many of the pack's records its
+     * declaration withholds.
+     */
+    count?: number;
+}
+/**
+ * One pack as the reading read it, in the order the reader was given them
+ * (5.5.4 v1.20). A surface names a pack by `signingKey`, the key that signed
+ * its wrapper, and never by an organization (D10).
+ */
+export interface CasePackReading {
+    ref: string;
+    /** The wrapper key, normalized, or `null` where this reader could not read it. */
+    signingKey: string | null;
+    /**
+     * The case grade (5.5.1 step 1), or `null` where the wrapper did not hold or
+     * the key could not be read.
+     */
+    grade: PackVerdict | null;
+    /**
+     * Records withheld by the pack's declaration (5.4.5): in scope for their
+     * signature and commitment only. Never counted as verified records.
+     */
+    recordsWithheld: number;
+    /**
+     * `sanning.declaration/v1`, `sanning.declaration/v2`, or `null` where the
+     * pack carries no declaration, one this reader does not know, or a body this
+     * reader does not read.
+     */
+    declarationVersion: string | null;
 }
 export interface CaseReading {
     verdict: CaseVerdict;
@@ -714,6 +820,10 @@ export interface CaseReading {
      * checked packs, which is false.
      */
     onChainChecked: boolean;
+    /** The NOTEs, in pack order (5.5.3 v1.20). No contribution. */
+    notes: CaseNote[];
+    /** One reading per pack, in the order the reader was given them. */
+    packs: CasePackReading[];
 }
 /**
  * Read a whole case: several packs in, one verdict and its exceptions out.
@@ -744,11 +854,92 @@ export interface CaseReading {
  */
 export declare function readCase(packs: readonly CasePack[]): Promise<CaseReading>;
 export declare function renderException(exception: CaseException): string;
+/** The house wording for one NOTE. Offered, not imposed, as `renderException` is. */
+export declare function renderCaseNote(note: CaseNote): string;
 /**
- * One line a surface can print for a whole case.
+ * The scope sentence, printed directly under the headline (evidence-bundle
+ * 5.5.6 v1.20, A26), byte for byte the text `render_case_summary` returns.
+ *
+ * The packs in the reading; the distinct keys, compared as keys, that signed
+ * the wrapper of a pack whose wrapper held; the hand-off records; the
+ * exceptions; and that the reading was made offline. Where any pack holds
+ * records withheld by its declaration, their total; where any pack is noted
+ * `pack_undeclared`, how many. Those two lines are part of what the headline
+ * MEANS, and a surface MUST print them with it.
  *
- * Both kernels print this sentence, so a reader who runs the Python command and
- * the TypeScript one over one case archive reads one sentence rather than two
- * that differ by a word.
+ * What was not checked on the public record is no longer a clause here. It is
+ * the witness line (`renderWitnessLine`), printed with every headline.
  */
 export declare function renderCaseSummary(reading: CaseReading): string;
+/**
+ * The one display title of each of the eight 3 words. A surface prints the
+ * title, never the word, and never a title of its own (#173, A18). The wording
+ * is Will's to change through the glossary (DL-71); what each MEANS is pinned
+ * in the spec.
+ */
+export declare const VERDICT_DISPLAY_TITLES: Readonly<Record<string, string>>;
+/**
+ * What a reader may rely on, for each of the six words a case reading reaches
+ * (5.5.6 v1.20, A26; the `verified` text at v1.28, A35), the same for every
+ * drop. `pending` and `not_found` never head a case reading: they are
+ * witness states. `verified` is the base sentence, printed alone where the
+ * drop holds no hand-off record; a caller reads `caseReliance` for
+ * `verified`, never this mapping directly.
+ */
+export declare const CASE_RELIANCE: Readonly<Record<CaseVerdict, string>>;
+/**
+ * The clause a `verified` drop that holds a hand-off record gains, inserted
+ * after `CASE_RELIANCE`'s first sentence (5.5.6, A35). Never printed alone,
+ * and never where `handoffRecords` is zero: most drops hold one agent's
+ * pack and no hand-off to say anything about.
+ */
+export declare const CASE_RELIANCE_HANDOFF_CLAUSE = "Every hand-off with both sides in this drop is intact.";
+/**
+ * What a reader may rely on for one case reading (5.5.6 v1.28, A35), byte
+ * for byte the text `case_reliance`'s Python sibling returns.
+ *
+ * For every word but `verified` this is `CASE_RELIANCE` unchanged. For
+ * `verified`, the hand-off clause is inserted after the first sentence
+ * where `handoffRecords` is not zero, and left out where it is zero: the
+ * base sentence never claims a hand-off the drop does not hold.
+ */
+export declare function caseReliance(verdict: CaseVerdict, handoffRecords: number): string;
+/** The three witness states, and how each is printed (5.5.6, D7). No other. */
+export declare const WITNESS_STATES: {
+    readonly confirmed: "Confirmed on the public record";
+    readonly not_checked: "Not checked";
+    readonly differs: "The public record holds different bytes";
+};
+export type WitnessState = keyof typeof WITNESS_STATES;
+/**
+ * The witness line: a lookup of the public record, reported beside the
+ * headline and never in it (D7). It never raises or lowers the headline and
+ * never changes its title. `reasons` says why a `not_checked` line did not
+ * settle, in a fixed order; `services` names each service that answered, as
+ * the URL the lookup used: named, never trusted (6).
+ */
+export interface WitnessLine {
+    state: WitnessState;
+    reasons: string[];
+    services: string[];
+    /**
+     * Witness times a pack caches that no lookup settled, as `[blockHeight,
+     * blockTime]`, distinct and in time order (5.6.6, v1.25, A30). Printed labelled
+     * not checked, and never as a time a reader may rely on. Absent reads as none.
+     */
+    cached?: [number, number][];
+    /**
+     * Witness times the public record returned where they matched a pack's
+     * cache, distinct and in time order. The gateway's answer, named with the
+     * service, never the cache's value. Absent reads as none.
+     */
+    recorded?: [number, number][];
+}
+/** The line printed where no lookup ran, which is every reading this kernel produces on its own. */
+export declare const WITNESS_NOT_LOOKED_UP: Readonly<WitnessLine>;
+/** The witness line as both kernels print it. */
+/** How a witness time a pack caches is printed where nothing checked it (5.5.6, 5.6.6, v1.25, A30). */
+export declare const WITNESS_TIME_CACHED = "the pack dates the witness, not checked";
+/** How a witness time the public record returned is printed where it matched the cache. */
+export declare const WITNESS_TIME_RECORDED = "the public record dates the witness";
+export declare function renderWitnessLine(line: WitnessLine): string;