@sanning/proof 0.19.0 → 0.20.0

package/dist/claims.d.ts

@@ -0,0 +1,211 @@
+import type { EnvelopeFault } from "./types.js";
+export declare const CLAIMS: readonly ["signed", "unchanged", "witnessed", "complete", "agreed", "follows_rules"];
+export type Claim = (typeof CLAIMS)[number];
+export declare const CLAIM_LABELS: Readonly<Record<Claim, string>>;
+/** The question each claim answers, as a page prints it beside the label. */
+export declare const CLAIM_QUESTIONS: Readonly<Record<Claim, string>>;
+export declare const CLAIM_STATES: readonly ["proven", "disproven", "not_proven", "not_in_scope"];
+export type ClaimState = (typeof CLAIM_STATES)[number];
+export declare const NOT_PROVEN_REASONS: readonly ["missing", "unreadable", "not_checked"];
+export type NotProvenReason = (typeof NOT_PROVEN_REASONS)[number];
+/** Why a claim is `not_in_scope`: nothing in the pack or case is about it. */
+export declare const NOT_IN_SCOPE_REASONS: readonly ["no_declaration", "no_declaration_and_no_handoff", "no_handoff", "no_agent_records", "no_agent_or_handoff_records"];
+export type NotInScopeReason = (typeof NOT_IN_SCOPE_REASONS)[number];
+export declare const VERDICTS: readonly ["verified", "failed", "incomplete"];
+export type Verdict = (typeof VERDICTS)[number];
+export declare const REASON_KINDS: readonly ["changed", "nonconforming"];
+export type ReasonKind = (typeof REASON_KINDS)[number];
+export declare const VERDICT_TITLES: Readonly<Record<Verdict, string>>;
+export declare const VERDICT_COLOURS: Readonly<Record<Verdict, string>>;
+/** The headline the person layer prints, by verdict and reason kind (`status:reason_kind`). */
+export declare const PERSON_TITLES: Readonly<Record<string, string>>;
+/** The same headline as a word and a sentence, for a surface that sets them apart. */
+export declare const PERSON_TITLE_PARTS: Readonly<Record<string, {
+    word: string;
+    sentence: string | null;
+}>>;
+export declare const SANDBOX_PERSON_LINE = "these records are sandbox records, not production evidence.";
+type Mapping = readonly [Claim, ClaimState, NotProvenReason | null];
+/** kind -> [claim, state, reason]. The reason is set only on `not_proven`. */
+export declare const KIND_CLAIMS: Readonly<Record<string, Mapping>>;
+export declare const RECORD_REASON_CLAIMS: Readonly<Record<string, Mapping>>;
+/** One plain line per record-layer rule. */
+export declare const RECORD_REASON_LINES: Readonly<Record<string, string>>;
+/** Every record-layer finding is a note (agent-events.md section 10.1). One plain sentence each. */
+export declare const NOTE_FINDINGS: Readonly<Record<string, string>>;
+/**
+ * Why a record's envelope does not verify (`ENVELOPE_FAULTS`), to the kind that says so.
+ * Read from the envelope layer's own classification, never from its prose.
+ */
+export declare const ENVELOPE_FAULT_KINDS: Readonly<Record<EnvelopeFault, string>>;
+/**
+ * What a problem is about: `[pack, record]` by position. `[p, null]` is a pack, `[null, null]`
+ * the case, and `[p, null, eventId]` a record pack `p` names and does not hold.
+ */
+export type ProblemItem = readonly [number | null, number | null] | readonly [number | null, null, string];
+/**
+ * One detailed kind, mapped to its claim and state. The optional values are what the
+ * person line reads; an absent one is `undefined`.
+ */
+export interface Problem {
+    readonly kind: string;
+    readonly claim: Claim;
+    readonly state: ClaimState;
+    readonly reason: NotProvenReason | null;
+    readonly items: readonly ProblemItem[];
+    readonly count?: number;
+    readonly of?: number;
+    readonly presented?: number;
+    readonly key?: string;
+    readonly rule?: string;
+}
+/** A problem as the machine layer carries it. */
+export interface ProblemJson {
+    kind: string;
+    claim: Claim;
+    state: ClaimState;
+    items: {
+        pack: number | null;
+        record: number | null;
+        event_id?: string;
+    }[];
+    reason?: NotProvenReason;
+    count?: number;
+    of?: number;
+    presented?: number;
+    key?: string;
+    rule?: string;
+}
+export declare function problemToJson(p: Problem): ProblemJson;
+export interface ProblemValues {
+    rule?: string | null;
+    count?: number | null;
+    of?: number | null;
+    presented?: number | null;
+    key?: string | null;
+}
+/**
+ * The `Problem` of a detailed kind. A kind with no mapping throws: a new kind is a
+ * decision, never a quiet `verified`. `rule` is a record-layer reason; for
+ * `agent_record_incomplete` it decides the claim.
+ */
+export declare function problem(kind: string, items?: readonly ProblemItem[], values?: ProblemValues): Problem;
+/** The same problem about other items. */
+export declare function withItems(p: Problem, items: readonly ProblemItem[]): Problem;
+/**
+ * A disproof that rests on bytes nobody signed: the claim is `not_proven`
+ * (`not_checked`), never `disproven`.
+ */
+export declare function downgraded(p: Problem): Problem;
+/**
+ * The problems of a pack read with the bytes handed in beside it (`full`), where each
+ * disproof the same pack read without them (`signed`) does not also make is `downgraded`.
+ * A disproof only the signed reading makes is kept, and so is one the public record makes.
+ */
+export declare function restOnSigned(full: readonly Problem[], signed: readonly Problem[]): Problem[];
+/** One item a claim is about, with the names a person reads. */
+export interface ClaimItem {
+    pack: number | null;
+    record: number | null;
+    pack_ref: string | null;
+    event_id: string | null;
+}
+/** One claim as the machine layer carries it. */
+export interface ClaimEntry {
+    claim: Claim;
+    label: string;
+    question: string;
+    state: ClaimState;
+    items: ClaimItem[];
+    problems: ProblemJson[];
+    /** Why it is not proven, or, for `not_in_scope`, why nothing is about it. */
+    reason?: NotProvenReason | NotInScopeReason;
+}
+/** An item's `[pack_ref, event_id]`, the names a person reads. */
+export type Labels = (pack: number | null, record: number | null) => readonly [string | null, string | null];
+/**
+ * The claims, in claim order, as the machine layer carries them, each with its label and
+ * its question. A claim is in scope when it is named in `inScope` or a problem is about
+ * it; `signed`, `unchanged` and `witnessed` always are. A claim not in scope is left out,
+ * unless `notInScope` gives the reason, which it then carries as `not_in_scope`.
+ *
+ * `labels(pack, record)` gives an item's `[pack_ref, event_id]`; a record a pack names and
+ * does not hold carries its own `event_id`.
+ */
+export declare function claimsOf(problems: readonly Problem[], inScope?: Iterable<string>, options?: {
+    notInScope?: Readonly<Partial<Record<Claim, NotInScopeReason>>>;
+    labels?: Labels;
+}): ClaimEntry[];
+/** A verdict: `reason_kind` only on `failed`. */
+export interface VerdictJson {
+    status: Verdict;
+    reason_kind?: ReasonKind;
+}
+/** The verdict of a set of claims: failed, then incomplete, then verified. */
+export declare function verdictOf(claims: readonly {
+    claim: string;
+    state: string;
+}[]): VerdictJson;
+/** One note for a record-layer finding carried by `records` records. */
+export declare function renderFindingNote(finding: string, records: number): string;
+/** One note as the machine layer carries it: its kind and its sentence. */
+export interface NoteEntry {
+    kind: string;
+    text: string;
+}
+/** One person line, laid out: the claim, its state, what it is about and why. */
+export interface LinePart {
+    claim: Claim;
+    state: ClaimState;
+    reason: NotProvenReason | NotInScopeReason | null;
+    count: number | null;
+    noun: string;
+    scope: string;
+    why: string;
+    text: string;
+}
+/** The person layer: what a reader is told, from the machine layer alone. */
+export interface Person {
+    title: string;
+    title_parts: {
+        word: string;
+        sentence: string | null;
+    };
+    lines: string[];
+    line_parts: LinePart[];
+    next: string | null;
+    notes: string[];
+    note_parts: NoteEntry[];
+    sandbox: string | null;
+    witness: string;
+    witness_state: string;
+}
+export declare const NOTE_ORDER: readonly string[];
+/**
+ * One note as the machine layer carries it. A kind with no place in `NOTE_ORDER` throws:
+ * a new note is a decision about where it is printed.
+ */
+export declare function note(kind: string, text: string): NoteEntry;
+/** The notes in `NOTE_ORDER`, each kind's notes in the order they came. */
+export declare function orderedNotes(notes: readonly NoteEntry[]): NoteEntry[];
+/**
+ * The person layer, from the machine layer alone: the title, one line per claim that is
+ * disproven or not proven (disproven first, then the claim order), one next action from the
+ * first line, the notes, the sandbox line and the witness line.
+ *
+ * Each string member has a structured twin for a surface that lays the words out:
+ * `title_parts` (the verdict word and the sentence), `line_parts` (each line's claim,
+ * state, reason, what it is about and why), `note_parts` (each note's kind) and
+ * `witness_state`. The text in a twin is the string member's, word for word.
+ */
+export declare function renderPerson(verdict: VerdictJson, claims: readonly ClaimEntry[], notes: readonly NoteEntry[], environmentMarker: string | null, witness: string, witnessState: string): Person;
+/** The person layer as the text report prints it, first, before the detail. */
+export declare function personText(person: Person): string[];
+/**
+ * Every problem the bundle verifier found, mapped. `pack` is the pack's position in a
+ * case (`null` for a single pack read on its own). The result is read structurally, so a
+ * field a result does not carry is never read as a failure; a result whose status is not
+ * `verified` always yields at least one problem, and a `failed` one a disproof.
+ */
+export declare function bundleProblems(result: unknown, pack?: number | null): Problem[];
+export {};