@mnemom/mnemom 0.17.34 → 0.17.36

package/node_modules/@mnemom/aip-verifier/dist/claim-lint-CVITIRcU.d.ts

@@ -0,0 +1,478 @@
+/**
+ * Record statements: the four signed statement types the Mnemom record is
+ * built from, their bundle, and the JWKS they verify against.
+ *
+ * Shape (design "The record", decisions T2, T3, T12):
+ *
+ * - Every statement carries `typ` (domain separation), `signing_key_id` (the
+ *   `kid` of an Ed25519 key in the published JWKS) and a detached `signature`:
+ *   base64url Ed25519 over `canonicalJson(statement minus signature)`.
+ * - Statements link by digest. A statement's digest is the lowercase sha256
+ *   hex of that same canonical commitment. `previous_digest` points at the
+ *   previous build of the same record; a PR record lists the conduct records
+ *   it rolls up; an outcome and a share card name the statement they derive
+ *   from.
+ * - A conduct record cites checkpoints by their signed `combined_commitment`
+ *   (T12). A citation with no `card_hash` is flagged "card hash not recorded";
+ *   one with no signed commitment is flagged "card not bound". Flags never
+ *   make a statement invalid: they tell the reader how strong the binding is.
+ * - A share card carries only measured lines, outcome lines, and verdict
+ *   lines shown with their coverage. Any other class fails the card.
+ */
+/**
+ * One key from the published JWKS. Only Ed25519 OKP keys with `alg: EdDSA`
+ * are used: a key whose `alg` is absent or anything else is refused with
+ * `key_not_ed25519`, so the field is required here as it is at runtime.
+ */
+interface RecordJwk {
+    kty: string;
+    crv?: string;
+    x?: string;
+    kid?: string;
+    alg: string;
+    use?: string;
+    [k: string]: unknown;
+}
+/** The published key set, as served at `/v1/.well-known/jwks.json`. */
+interface RecordJwks {
+    keys: RecordJwk[];
+}
+declare const STATEMENT_TYPES: readonly ["AAP-ConductRecord/v1", "AAP-PRRecord/v1", "AAP-Outcome/v1", "AAP-ShareCard/v1"];
+type StatementTyp = (typeof STATEMENT_TYPES)[number];
+declare const BUNDLE_TYP: "AAP-RecordBundle/v1";
+/** Fields every signed statement carries. */
+interface SignedStatementBase {
+    typ: StatementTyp;
+    /** `kid` of the signing key in the JWKS. */
+    signing_key_id: string;
+    /** base64url Ed25519 signature over `canonicalJson(statement minus signature)`. */
+    signature: string;
+    /** Optional, must equal `EdDSA` when present. */
+    alg?: string;
+    /** ISO 8601 time the statement was built. */
+    built_at?: string;
+    /** Digest of the previous build of this record, or null for the first build (T2). */
+    previous_digest?: string | null;
+    /** `kid` of the key that made `commitment_signature`, or null when the attestation failed open. */
+    commitment_key_id?: string | null;
+    /** Generic unit the statement is about, e.g. `pull_request`. */
+    unit_kind?: string;
+    [k: string]: unknown;
+}
+/** A checkpoint cited by a conduct record (T12). */
+interface CheckpointCitation {
+    checkpoint_id: string;
+    /** sha256 hex of the alignment card the checkpoint was judged against, or null when not recorded. */
+    card_hash?: string | null;
+    /** The checkpoint's signed `combined_commitment`, or null when none was signed. */
+    combined_commitment?: string | null;
+    /** The checkpoint certificate's signature over its own payload (own key, own payload per T3). */
+    commitment_signature?: string | null;
+    [k: string]: unknown;
+}
+interface ConductRecordStatement extends SignedStatementBase {
+    typ: "AAP-ConductRecord/v1";
+    /** Lineage the record is keyed on (T1), e.g. a conversation id. */
+    lineage_key?: string;
+    checkpoints?: CheckpointCitation[];
+}
+interface PRRecordStatement extends SignedStatementBase {
+    typ: "AAP-PRRecord/v1";
+    /** Digests of the conduct records this PR record rolls up. */
+    conduct_digests?: string[];
+    /** Head SHA from before the App's bundle commit. */
+    head_sha?: string;
+}
+interface OutcomeStatement extends SignedStatementBase {
+    typ: "AAP-Outcome/v1";
+    /** Digest of the PR record this outcome belongs to. */
+    pr_record_digest?: string;
+    merge_sha?: string;
+}
+/** Claim classes a share card may carry. */
+declare const CARD_LINE_CLASSES: readonly ["measured", "verdict", "outcome"];
+type CardLineClass = (typeof CARD_LINE_CLASSES)[number];
+interface ShareCardLine {
+    class: string;
+    text: string;
+    /** Required on a verdict line: "N of M judged". */
+    coverage?: {
+        judged: number;
+        total: number;
+    } | null;
+    [k: string]: unknown;
+}
+interface ShareCardStatement extends SignedStatementBase {
+    typ: "AAP-ShareCard/v1";
+    /** Digest of the statement the card's lines were taken from. */
+    source_digest?: string;
+    lines?: ShareCardLine[];
+}
+type SignedStatement = ConductRecordStatement | PRRecordStatement | OutcomeStatement | ShareCardStatement;
+/** A customer-held bundle: statements in build order. */
+interface RecordBundle {
+    typ: typeof BUNDLE_TYP;
+    statements: SignedStatement[];
+    [k: string]: unknown;
+}
+/**
+ * Named reasons a statement fails. Stable strings: tampered fixtures assert
+ * on them, and every renderer prints them as they are.
+ */
+declare const REASONS: {
+    readonly not_an_object: "not_an_object";
+    readonly unknown_typ: "unknown_typ";
+    readonly unsupported_alg: "unsupported_alg";
+    readonly signing_key_id_missing: "signing_key_id_missing";
+    readonly signature_missing: "signature_missing";
+    readonly signature_malformed: "signature_malformed";
+    readonly key_not_found: "key_not_found";
+    readonly key_not_ed25519: "key_not_ed25519";
+    readonly signature_invalid: "signature_invalid";
+    readonly bundle_not_an_object: "bundle_not_an_object";
+    readonly bundle_unknown_typ: "bundle_unknown_typ";
+    readonly bundle_statements_missing: "bundle_statements_missing";
+    readonly digest_malformed: "digest_malformed";
+    readonly linked_statement_wrong_typ: "linked_statement_wrong_typ";
+    readonly card_line_class_not_allowed: "card_line_class_not_allowed";
+    readonly card_verdict_without_coverage: "card_verdict_without_coverage";
+};
+type Reason = (typeof REASONS)[keyof typeof REASONS];
+/** Named flags. A flag weakens a binding but never invalidates a statement. */
+declare const FLAGS: {
+    readonly card_hash_not_recorded: "card hash not recorded";
+    readonly card_not_bound: "card not bound";
+    readonly linked_statement_not_in_bundle: "linked statement not in bundle";
+};
+type Flag = (typeof FLAGS)[keyof typeof FLAGS];
+interface StatementFlag {
+    flag: Flag;
+    /** `checkpoint_id` or the digest the flag is about. */
+    subject: string;
+}
+interface StatementVerificationResult {
+    valid: boolean;
+    typ: string | null;
+    /** sha256 hex of the canonical commitment, or null when the input is not an object. */
+    digest: string | null;
+    signing_key_id: string | null;
+    reasons: Reason[];
+    flags: StatementFlag[];
+}
+interface RecordVerificationResult {
+    valid: boolean;
+    /** Reasons at the bundle level, plus every statement reason prefixed by its index. */
+    reasons: string[];
+    flags: StatementFlag[];
+    statements: StatementVerificationResult[];
+    verified_at: string;
+}
+
+/**
+ * The claim table (design decision T5): one table mapping record fields to
+ * the claim class they may be rendered as and, for goal and protection lines,
+ * the verb each mode produces. Every renderer and the verifier read this
+ * table; copy is never written per renderer.
+ *
+ * Rules the table encodes (design "Claim classes and verbs", "Cost",
+ * "Share cards"):
+ * - A line is exactly one class. "Safe", "correct" and "prevented" never appear.
+ * - No protection or goal line carries a dollar figure.
+ * - An implicit goal line never says "sealed"; goals off read "not checked".
+ * - The verb comes from the area's mode at the time of the act and, for a
+ *   protection act, its verdict. "Stopped" shows the tool name and never its
+ *   arguments; on a card, no tool name at all.
+ * - Cards carry measured, outcome and covered verdict lines only. Estimates
+ *   and savings never appear on a card or a PR comment (T8).
+ * - No benchmark line ships until the head-to-head is published with its
+ *   losing arms; no savings percentage appears anywhere until then.
+ */
+declare const CLAIM_CLASSES: readonly ["measured", "verdict", "estimate", "benchmark", "outcome"];
+type ClaimClass = (typeof CLAIM_CLASSES)[number];
+/**
+ * Where a rendering is shown. Cards are the share card and the period card.
+ * `share_card` is the `AAP-ShareCard/v1` record statement's lines
+ * (`RecordShareCardLine`, statements.ts: `{class, text, coverage}`), the shape
+ * `verify` checks; not the MNE-9022 numeric card (sharecard.ts `ShareCardLine`).
+ */
+declare const SURFACES: readonly ["record_page", "check_summary", "pr_comment", "share_card", "period_card"];
+type Surface = (typeof SURFACES)[number];
+declare const CARD_SURFACES: readonly Surface[];
+/** Surfaces that never show the savings estimate, even once it qualifies (T8). */
+declare const ESTIMATE_FORBIDDEN_SURFACES: readonly Surface[];
+/** Protection and goal area modes, as stored at the act. */
+declare const MODES: readonly ["off", "observe", "nudge", "enforce"];
+type Mode = (typeof MODES)[number];
+/**
+ * The verb each mode produces at its strongest verdict. `off` produces no line, or
+ * "not checked". A protection act's verb also depends on its verdict: see
+ * `protectionVerb`.
+ */
+declare const MODE_VERBS: Record<Mode, string>;
+/** A protection act's verdict, as stored at the act (mnemom-api `ProtectionVerdict`). */
+declare const PROTECTION_VERDICTS: readonly ["pass", "warn", "nudge", "quarantine", "block"];
+type ProtectionVerdict = (typeof PROTECTION_VERDICTS)[number];
+/**
+ * The verb one protection act produces, from the mode and verdict stored at the act; null
+ * means the act has no line (mode off, or a pass). Mirrors mnemom-api
+ * `src/record/claims.ts` `protectionVerb`: under enforce only a block or quarantine
+ * "stopped" anything and anything else is "flagged"; under nudge only a nudge verdict
+ * reads "flagged, agent nudged".
+ */
+declare function protectionVerb(mode: Mode, verdict: ProtectionVerdict): string | null;
+/** How the goal was set. An implicit goal is never read as sealed (T16). */
+declare const GOAL_MODES: readonly ["sealed", "implicit", "off"];
+type GoalMode = (typeof GOAL_MODES)[number];
+interface ClaimTableEntry {
+    class: ClaimClass;
+    /** True for the goal and protection areas: the verb comes from the mode. */
+    verb_by_mode: boolean;
+    /** True when the line may carry a money figure (model cost and μ only). */
+    money_allowed: boolean;
+    /** Surfaces this field may appear on; absent means every surface. */
+    surfaces?: readonly Surface[];
+}
+declare const CLAIM_TABLE: {
+    readonly commits_recorded: {
+        readonly class: "measured";
+        readonly verb_by_mode: false;
+        readonly money_allowed: false;
+    };
+    readonly messages_from_person: {
+        readonly class: "measured";
+        readonly verb_by_mode: false;
+        readonly money_allowed: false;
+    };
+    readonly compactions: {
+        readonly class: "measured";
+        readonly verb_by_mode: false;
+        readonly money_allowed: false;
+    };
+    readonly tokens_sent_vs_reaching: {
+        readonly class: "measured";
+        readonly verb_by_mode: false;
+        readonly money_allowed: false;
+    };
+    readonly peak_context: {
+        readonly class: "measured";
+        readonly verb_by_mode: false;
+        readonly money_allowed: false;
+    };
+    readonly model_cost: {
+        readonly class: "measured";
+        readonly verb_by_mode: false;
+        readonly money_allowed: true;
+    };
+    readonly mu_cost: {
+        readonly class: "measured";
+        readonly verb_by_mode: false;
+        readonly money_allowed: true;
+    };
+    readonly approval: {
+        readonly class: "measured";
+        readonly verb_by_mode: false;
+        readonly money_allowed: false;
+    };
+    /** How the goal was set: "sealed contract", "implicit goal" or "not checked" (M7: its own measured line). */
+    readonly goal_mode: {
+        readonly class: "measured";
+        readonly verb_by_mode: false;
+        readonly money_allowed: false;
+    };
+    readonly goal: {
+        readonly class: "verdict";
+        readonly verb_by_mode: true;
+        readonly money_allowed: false;
+    };
+    /** The protection area's mode when no act is shown: "not checked" under off. */
+    readonly protection_mode: {
+        readonly class: "measured";
+        readonly verb_by_mode: false;
+        readonly money_allowed: false;
+    };
+    readonly protection: {
+        readonly class: "verdict";
+        readonly verb_by_mode: true;
+        readonly money_allowed: false;
+    };
+    readonly autonomy: {
+        readonly class: "measured";
+        readonly verb_by_mode: false;
+        readonly money_allowed: false;
+    };
+    readonly savings_estimate: {
+        readonly class: "estimate";
+        readonly verb_by_mode: false;
+        readonly money_allowed: true;
+        readonly surfaces: readonly ["record_page", "check_summary"];
+    };
+    readonly benchmark: {
+        readonly class: "benchmark";
+        readonly verb_by_mode: false;
+        readonly money_allowed: false;
+    };
+    readonly outcome: {
+        readonly class: "outcome";
+        readonly verb_by_mode: false;
+        readonly money_allowed: false;
+    };
+};
+type ClaimField = keyof typeof CLAIM_TABLE;
+declare function isClaimField(field: unknown): field is ClaimField;
+/**
+ * Line keys the builder (mnemom-api `src/record/claims.ts`) writes on a
+ * statement's `lines[]`, mapped to the claim-table field each one renders
+ * (cross-lane pick M6). `protection.act.<n>` maps to `protection` for any n.
+ */
+declare const LINE_KEY_FIELDS: Readonly<Record<string, ClaimField>>;
+/** The claim-table field a statement line key renders, or undefined for a key the table does not know. */
+declare function fieldForLineKey(key: unknown): ClaimField | undefined;
+
+/**
+ * claim-lint: the mechanical check every rendering passes (criterion K1.17).
+ *
+ * A rendering is a surface plus the lines shown on it. Each line names its
+ * class, its text, and when it comes from a mode-bearing area, the mode stored
+ * at the act. The lint returns every violation with a stable rule name; it
+ * never rewrites a line.
+ *
+ * Line shape (cross-lane pick M6): a signed statement carries
+ * `{class, key, text}` per line, with the builder's keys (`cost.model`,
+ * `goal.verdict`, `protection.act.0`, ...). The renderer attaches `mode`,
+ * `verdict`, `goal_mode`, `tool_name` and `coverage` from the statement's
+ * `goal` and `protection` blocks before linting. The lint resolves `field`
+ * from `key` when `field` is absent, and off a card reads a verdict line's
+ * coverage from the "<n> of <m> turns judged" words when no `coverage` object
+ * is attached.
+ *
+ * On `share_card` the lines are the record share card statement's lines
+ * (`RecordShareCardLine`, statements.ts `{class, text, coverage}`), the ones
+ * `verify` checks in `shareCardReasons`. The MNE-9022 card (sharecard.ts,
+ * `{id, kind, label, value, statement_hash}`) carries no `class` and is not a
+ * `Rendering`; linting its lines as-is reports `one_class_per_line` on each.
+ *
+ * Rules, each from the claim table (T5) and the design's claim rules:
+ *   one_class_per_line          class is one of the five, and matches the field's class
+ *   forbidden_word              "safe", "correct", "prevented" never appear
+ *   money_on_goal_or_protection no dollar figure on a goal or protection line
+ *   implicit_goal_sealed        an implicit goal line never says "sealed"
+ *   goal_off_not_checked        with goals off the goal line reads "not checked"
+ *   estimate_on_forbidden_surface  no estimate or savings on a card or PR comment
+ *   verb_mismatch               the verb is the one the mode and the act's verdict produce, exactly
+ *                               (mnemom-api `protectionVerb`); a tool name follows "stopped" only
+ *   enforce_without_tool_name   "stopped" names the tool off-card
+ *   tool_name_on_card           a card never shows a tool name
+ *   tool_arguments_shown        tool arguments never appear
+ *   trust_claim                 no minutes-to-trust, review-time or re-checking claim
+ *   savings_percentage          no savings percentage anywhere until the board exists
+ *   benchmark_not_published     no benchmark line ships yet
+ *   verdict_without_coverage    off a card, a goal verdict always shows its coverage ("N of M turns
+ *                               judged") and a protection act, one recorded decision, carries none;
+ *                               on a card every verdict line carries a `coverage` object, as
+ *                               `verify` requires (`card_verdict_without_coverage`)
+ *   card_class_not_allowed      a card carries measured, outcome and verdict lines only
+ *   period_card_without_revert  a period card renders its reverts
+ *   field_not_on_surface        the field is not shown on this surface
+ *   provisional_mu_on_card      a provisional μ amount ("≈ N μ (pending)", A-S-001) never appears on a card:
+ *                               cards keep K1.17 and read "μ pending" at most
+ *   provisional_mu_off_cost_line a provisional μ amount appears on the μ cost line and nowhere else
+ */
+
+interface RenderedLine {
+    /** Record field the line renders; when present its class must match the claim table. */
+    field?: string;
+    /** Builder line key (`cost.model`, `goal.verdict`, `protection.act.0`, ...); resolves `field` when that is absent. */
+    key?: string;
+    class: string;
+    text: string;
+    /** Mode stored at the act, for goal and protection lines. */
+    mode?: Mode;
+    /** Verdict stored at a protection act; required with nudge and enforce, whose verb depends on it. */
+    verdict?: ProtectionVerdict;
+    /** How the goal was set, for goal lines. */
+    goal_mode?: GoalMode;
+    /** Tool the act concerned; shown only after "stopped", and never on a card. */
+    tool_name?: string;
+    /** Never rendered; present here only so the lint can prove it is absent from the text. */
+    tool_arguments?: unknown;
+    /** "N of M judged". Required on every verdict line on a card; off a card a goal verdict may say it in words instead. */
+    coverage?: {
+        judged: number;
+        total: number;
+    } | null;
+    [k: string]: unknown;
+}
+interface Rendering {
+    surface: Surface;
+    lines: RenderedLine[];
+    [k: string]: unknown;
+}
+declare const LINT_RULES: {
+    readonly one_class_per_line: "one_class_per_line";
+    readonly forbidden_word: "forbidden_word";
+    readonly money_on_goal_or_protection: "money_on_goal_or_protection";
+    readonly implicit_goal_sealed: "implicit_goal_sealed";
+    readonly goal_off_not_checked: "goal_off_not_checked";
+    readonly estimate_on_forbidden_surface: "estimate_on_forbidden_surface";
+    readonly verb_mismatch: "verb_mismatch";
+    readonly enforce_without_tool_name: "enforce_without_tool_name";
+    readonly tool_name_on_card: "tool_name_on_card";
+    readonly tool_arguments_shown: "tool_arguments_shown";
+    readonly trust_claim: "trust_claim";
+    readonly savings_percentage: "savings_percentage";
+    readonly benchmark_not_published: "benchmark_not_published";
+    readonly verdict_without_coverage: "verdict_without_coverage";
+    readonly card_class_not_allowed: "card_class_not_allowed";
+    readonly period_card_without_revert: "period_card_without_revert";
+    readonly field_not_on_surface: "field_not_on_surface";
+    readonly provisional_mu_on_card: "provisional_mu_on_card";
+    readonly provisional_mu_off_cost_line: "provisional_mu_off_cost_line";
+    readonly unknown_surface: "unknown_surface";
+};
+type LintRule = (typeof LINT_RULES)[keyof typeof LINT_RULES];
+interface LintViolation {
+    rule: LintRule;
+    /** Index of the line in the rendering, or -1 for a rendering-level violation. */
+    line: number;
+    text: string;
+}
+interface LintResult {
+    ok: boolean;
+    violations: LintViolation[];
+}
+/** Lint one rendering. Never throws; a malformed rendering is a violation. */
+declare function lintRendering(rendering: unknown): LintResult;
+/** Lint several renderings and keep each result keyed by its position. */
+declare function lintRenderings(renderings: unknown[]): LintResult[];
+/** The `goal` block a conduct record statement carries (mnemom-api `src/record/builder.ts`). */
+interface StatementGoalBlock {
+    mode: GoalMode;
+    [k: string]: unknown;
+}
+/** One entry of a conduct record statement's `protection.acts[]`. */
+interface StatementProtectionAct {
+    mode: Mode;
+    verdict: ProtectionVerdict;
+    tool_name: string | null;
+    [k: string]: unknown;
+}
+/** A statement line as the builder signs it: one class, a stable key, the words shown. */
+interface StatementLine {
+    class: string;
+    key: string;
+    text: string;
+}
+/**
+ * Attach the lint context a signed statement's lines leave out (cross-lane
+ * pick M6). The statement carries `{class, key, text}` only; this returns the
+ * same lines with `goal_mode` on `goal.*` lines, and `mode`, `verdict` and
+ * `tool_name` on `protection.act.*` lines, read from the statement's `goal`
+ * and `protection.acts` blocks (`protection.act.<i>` is `acts[i]`). Coverage
+ * stays in the verdict line's words; a card renderer attaches the `coverage`
+ * object itself. The text is never changed.
+ */
+declare function attachLineContext(lines: readonly StatementLine[], goal: StatementGoalBlock | null | undefined, protection: {
+    acts: readonly StatementProtectionAct[];
+} | null | undefined): RenderedLine[];
+
+export { lintRenderings as $, type RenderedLine as A, BUNDLE_TYP as B, CARD_LINE_CLASSES as C, type Rendering as D, ESTIMATE_FORBIDDEN_SURFACES as E, FLAGS as F, GOAL_MODES as G, STATEMENT_TYPES as H, SURFACES as I, type ShareCardStatement as J, type SignedStatementBase as K, LINE_KEY_FIELDS as L, MODES as M, type StatementFlag as N, type OutcomeStatement as O, PROTECTION_VERDICTS as P, type StatementGoalBlock as Q, type RecordBundle as R, type SignedStatement as S, type StatementLine as T, type StatementProtectionAct as U, type StatementTyp as V, type Surface as W, attachLineContext as X, fieldForLineKey as Y, isClaimField as Z, lintRendering as _, type RecordJwks as a, protectionVerb as a0, type RecordVerificationResult as b, type StatementVerificationResult as c, CARD_SURFACES as d, CLAIM_CLASSES as e, CLAIM_TABLE as f, type CardLineClass as g, type CheckpointCitation as h, type ClaimClass as i, type ClaimField as j, type ClaimTableEntry as k, type ConductRecordStatement as l, type Flag as m, type GoalMode as n, LINT_RULES as o, type LintResult as p, type LintRule as q, type LintViolation as r, MODE_VERBS as s, type Mode as t, type PRRecordStatement as u, type ProtectionVerdict as v, REASONS as w, type Reason as x, type RecordJwk as y, type ShareCardLine as z };