@sanning/proof 0.11.1 → 0.13.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
@@ -185,7 +187,8 @@
  *    (F2).
  * 10. **`counterpart_absent`** (`continue`). Skips the ambiguity and pair
  *     reporting, and there is nothing to skip: 4.1 emits that finding only
- *     for an EMPTY candidate list. Which of the three counterpart kinds it
+ *     where no candidate is left to read, an EMPTY candidate list or one whose
+ *     every candidate another record accounts for (4.1 v1.17, A20). Which of the three counterpart kinds it
  *     gets reads the keys of the packs that verified, counted before exit 4,
  *     and whether any pack took exit 2 or 3.
  *
@@ -206,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
  * ===============================
@@ -225,17 +230,19 @@
  *   with that verdict and its reasons, so the case never reads above its
  *   weakest pack. On-chain re-fetch and `gradePack` are a caller's to run.
  *
- * THE COST OF 4.1's "GRADE EVERY CANDIDATE", INHERITED HERE AND STATED RATHER
- * THAN LEFT TO BE FOUND (proof#134, ratified by Phil 2026-09-22). A reader
- * whose pile holds two or more records of the complementary type signed by one
- * counterparty key cannot reach `verified`: the other exchanges' records are
- * candidates too, they commit to other messages, and they fail. One agent
- * sending two messages to the same counterparty inside one case lands there,
- * and it surfaces as `COUNTERPART_AMBIGUOUS` beside the failure. An
- * alternating exchange (A sends, B replies) does NOT, because a reply is
- * signed by the other key and is the other type. Narrowing that here with
- * `handoffs[]` is precisely the move that would reopen proof#137's door.
- */
+ * THE COST OF 4.1's "GRADE EVERY CANDIDATE", AND WHAT IS LEFT OF IT (4.1
+ * v1.17, amendment A20, which reopens proof#134). Up to v1.16 a pile holding
+ * two or more records of the complementary type signed by one counterparty key
+ * could not reach `verified`. 4.1 now sets such a candidate aside where a
+ * record the subject's own key signed pairs with it verified at another
+ * sequence, so two messages in one direction, and the demo's A to B, B to A,
+ * A to B, read clean. What is left surfaces as `COUNTERPART_AMBIGUOUS` beside
+ * the failure: fan-in, fan-out, and the same pair in two cases at the same
+ * 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
@@ -281,7 +288,9 @@ export declare const CASE_QUARANTINED_PROFILES: readonly ["sanning.mlflow/v1"];
 /**
  * A conformant hand-off record with no counterpart among the records this
  * reader read, where every pack in the case verified under a key this reader
- * can read and NO pack in the case is signed by the key the record names.
+ * can read and NO pack in the case is signed by the key the record names,
+ * or where every candidate it had was accounted for by another record under
+ * A20 (the exception then carries `count`, and names no pack).
  * **An exception, never a failure** (anchor#198, criterion 3).
  *
  * That is ALL it says. It does not say the counterparty's account is absent,
@@ -367,9 +376,11 @@ export declare const COUNTERPART_ABSENT_FROM_COUNTERPARTY_RECORDS = "counterpart
  */
 export declare const COUNTERPART_ABSENT_SIGNER_UNKNOWN = "counterpart_absent_signer_unknown";
 /**
- * More than one candidate counterpart (4.1, and proof#134's stated cost). The
- * reading is the worst of them and the ambiguity is named: a reader permitted
- * to take one match can be handed an honest decoy beside a tampered record.
+ * More than one candidate counterpart that nothing accounts for (4.1 v1.17,
+ * A20). The reading is the worst of them and the ambiguity is named: a reader
+ * permitted to take one match can be handed an honest decoy beside a tampered
+ * record. `count` is how many of the candidates are live, which is the number
+ * the ambiguity is about.
  */
 export declare const COUNTERPART_AMBIGUOUS = "counterpart_ambiguous";
 /**
@@ -545,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
@@ -576,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.
@@ -591,16 +638,19 @@ 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 two NOTEs (5.5.3 v1.20): findings on the reading with no contribution,
+ * printed in the scope sentence so a clean verdict never hides either.
+ * `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 CASE_HOLDS_NO_HANDOFF_RECORDS = "case_holds_no_handoff_records";
+export declare const CONTENT_WITHHELD_BY_DECLARATION = "content_withheld_by_declaration";
+export declare const CASE_NOTE_KINDS: readonly ["pack_undeclared", "content_withheld_by_declaration"];
+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.
@@ -636,13 +686,24 @@ export interface CaseException {
     counterpartyKey?: string | null;
     /** Which checks a formed pair failed, in 4.1's fixed order. */
     failedChecks?: string[];
-    /** How many of a thing the exception is about, where it is about a count. */
+    /**
+     * How many of a thing the exception is about, where it is about a count. On
+     * `COUNTERPART_ABSENT` it is set only where 4.1 set every candidate aside
+     * (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[];
@@ -663,6 +724,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;
@@ -705,6 +812,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.
@@ -735,11 +846,56 @@ 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.
  *
- * 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.
+ * 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.
+ *
+ * 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 same for every drop. `pending` and `not_found`
+ * never head a case reading: they are witness states.
+ */
+export declare const CASE_RELIANCE: Readonly<Record<CaseVerdict, 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[];
+}
+/** 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. */
+export declare function renderWitnessLine(line: WitnessLine): string;