@alisio/core 0.6.0 → 0.8.0

package/dist/proof/divergence.js

@@ -0,0 +1,120 @@
+/** Only this much of the answer is read: the cost is bounded whatever the model writes. */
+const MAX_TEXT = 100_000;
+const MAX_CLAIM = 200;
+const H = "[ \\t]+";
+const SUBJECTS = {
+    test: `(?:(?:unit|integration|e2e)${H})?tests?(?:${H}suite)?(?:${H}(?:unitarios|unitarias|e2e|de${H}integración))?|(?:suite${H}de${H})?(?:tests|pruebas)(?:${H}(?:unitarias|de${H}integración))?`,
+    typecheck: `type${H}?check(?:ing|s)?|typecheck(?:ing)?|(?:verificación|chequeo|comprobación)${H}de${H}tipos|tsc`,
+    lint: "lint(?:ing|er)?",
+};
+const ARTICLE = `(?:(?:the|el|la|los|las)${H})?`;
+const SUBJECT = `${ARTICLE}(?:${Object.values(SUBJECTS).join("|")})`;
+const SEPARATOR = `[ \\t]*,[ \\t]*(?:(?:and|y)${H})?|${H}(?:and|y)${H}|[ \\t]*&[ \\t]*`;
+const FILLER = `(?:is|are|now|also|all|both|still|were|have|has|been|ya|ahora|todos|todas|están|está|esta|siguen)`;
+const VERDICT = `(?:passe[sd]|pass(?:ing)?|ok|okay|clean|green|succeed(?:s|ed)?|successful|fine|pasan|pasa|pasó|pasaron|pasando|limpi[oa]s?|verdes?|en${H}verde|correct[oa]s?|bien)`;
+const CLAIM = new RegExp(`(?<![\\p{L}\\p{N}])(?:(?:all|todos|todas)${H})?(?:(?:the|los|las|el|la)${H})?` +
+    `((${SUBJECT}(?:(?:${SEPARATOR})${SUBJECT}){0,4})(?:${H}${FILLER})*${H}${VERDICT})` +
+    "(?![\\p{L}\\p{N}])", "giu");
+const KIND_IN_LIST = Object.entries(SUBJECTS).map(([kind, source]) => [
+    kind,
+    new RegExp(`(?<![\\p{L}\\p{N}])(?:${source})(?![\\p{L}\\p{N}])`, "iu"),
+]);
+const WORD = (alternatives) => new RegExp(`(?<![\\p{L}\\p{N}])(?:${alternatives})(?![\\p{L}\\p{N}])|\\p{L}+n['’]t`, "iu");
+/** Words that make a following "tests pass" a wish, a condition, an instruction or a denial. */
+const HEDGE = WORD([
+    "not|never|no|cannot|unable|if|once|until|unless|whether|when|whenever|should|shall|would|could|might|may",
+    "hope|hoping|expect|expecting|need|needs|want|ensure|ensuring|make|makes|making|get|gets|getting",
+    "verify|confirm|check|let's|lets",
+    "nunca|jamás|sin|si|cuando|hasta|salvo|debe|deben|debería|deberían|espero|esperamos|quiero",
+    "necesito|necesitamos|asegura|asegúrate|asegurar|verifica|verificar|comprueba|comprobar",
+    "confirma|confirmar|hacer|haz",
+].join("|"));
+const CLAUSE_BOUNDARY = /[.!?;:\n]|(?<![\p{L}\p{N}])(?:but|however|pero|aunque|sin embargo)(?![\p{L}\p{N}])/giu;
+const CLAUSE_WINDOW = 60;
+/** Removes what quotes rather than asserts: code (fenced, inline), block quotes and quoted text. */
+function unquoted(text) {
+    return text
+        .slice(0, MAX_TEXT)
+        .replace(/(```|~~~)[\s\S]*?\1/g, "\n")
+        .replace(/(```|~~~)[\s\S]*$/, "\n")
+        .replace(/^[ \t]*>.*$/gm, "")
+        .replace(/`[^`\n]{0,300}`/g, " ")
+        .replace(/"[^"\n]{0,300}"|“[^”\n]{0,300}”|«[^»\n]{0,300}»|‘[^’\n]{0,300}’/g, " ");
+}
+/** Whether the words just before `index`, inside its clause, hedge or deny the claim. */
+function hedged(text, index) {
+    const before = text.slice(Math.max(0, index - 200), index);
+    let start = 0;
+    for (const boundary of before.matchAll(CLAUSE_BOUNDARY))
+        start = boundary.index + boundary[0].length;
+    return HEDGE.test(before.slice(start).slice(-CLAUSE_WINDOW));
+}
+function claimsIn(finalText) {
+    const text = unquoted(finalText);
+    const found = [];
+    const seen = new Set();
+    for (const match of text.matchAll(CLAIM)) {
+        if (hedged(text, match.index))
+            continue;
+        const wording = (match[1] ?? "").replace(/\s+/g, " ").trim().slice(0, MAX_CLAIM);
+        for (const [kind, pattern] of KIND_IN_LIST) {
+            if (seen.has(kind) || !pattern.test(match[2] ?? ""))
+                continue;
+            seen.add(kind);
+            found.push({ claim: wording, kind });
+        }
+    }
+    return found;
+}
+const TYPECHECK_CMD = /(?<![\w-])(?:tsc|typecheck|type-check|check-types|mypy|pyright)(?![\w-])/i;
+const LINT_CMD = /(?<![\w-])(?:lint|eslint|biome|ruff|flake8|pylint|clippy|golangci-lint|stylelint|oxlint)(?![\w-])/i;
+const TEST_CMD = /(?<![\w-])(?:tests?|vitest|jest|pytest|mocha|rspec)(?![\w-])/i;
+const TYPECHECK_TEXT = /(?<![\p{L}\p{N}])type[ -]?check|tipos(?![\p{L}\p{N}])/iu;
+const LINT_TEXT = /(?<![\p{L}\p{N}])lint(?:ing|er)?(?![\p{L}\p{N}])/iu;
+const TEST_TEXT = /(?<![\p{L}\p{N}])(?:tests?|pruebas)(?![\p{L}\p{N}])/iu;
+/** The kind of check a criterion stands for: its command when it has one, else its text. */
+function kindOf(criterion) {
+    const verifier = criterion.verifier;
+    if (verifier && (verifier.kind === "command" || verifier.kind === "coverage")) {
+        if (TYPECHECK_CMD.test(verifier.command))
+            return "typecheck";
+        if (LINT_CMD.test(verifier.command))
+            return "lint";
+        if (TEST_CMD.test(verifier.command))
+            return "test";
+        return undefined;
+    }
+    if (TYPECHECK_TEXT.test(criterion.text))
+        return "typecheck";
+    if (LINT_TEXT.test(criterion.text))
+        return "lint";
+    if (TEST_TEXT.test(criterion.text))
+        return "test";
+    return undefined;
+}
+/**
+ * The claims of `finalText` that `ledger` does not back, in order of appearance. An empty ledger
+ * yields nothing (D7: without criteria Proof stays out of the way).
+ */
+export function detectDivergence(finalText, ledger) {
+    if (ledger.criteria.length === 0)
+        return [];
+    const out = [];
+    for (const { claim, kind } of claimsIn(finalText)) {
+        const equivalent = ledger.criteria.filter((c) => c.status !== "not_applicable" && kindOf(c) === kind);
+        if (equivalent.length === 0) {
+            out.push({ claim, kind, expected: "verified", actualState: "not_checked" });
+            continue;
+        }
+        for (const c of equivalent)
+            if (c.status !== "verified")
+                out.push({
+                    claim,
+                    kind,
+                    expected: "verified",
+                    actualState: c.status,
+                    criterionId: c.criterionId,
+                });
+    }
+    return out;
+}

package/dist/proof/export.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The surfaces of Proof (specs/011 phase 5) read ONE ledger and share these pure helpers: the
+ * versioned `proof/v1` export, the Markdown report, the CI exit code and the parsing of criteria
+ * a user or a CLI flag supplies. Nothing here touches a database or a clock.
+ */
+import type { ArtifactPublisher, ArtifactRef, ProofCriterion, ProofEvidence, ProofLedger } from "@alisio/sdk";
+import type { NewCriterion } from "./types.ts";
+/** The `schema` of the JSON export. A breaking change to the shape is a new version. */
+export declare const PROOF_EXPORT_SCHEMA = "proof/v1";
+export interface ProofSummary {
+    total: number;
+    required: number;
+    /** Required criteria that are `failed`, `not_checked` or `manual_review`. */
+    requiredUnmet: number;
+    verified: number;
+    failed: number;
+    notChecked: number;
+    manualReview: number;
+    notApplicable: number;
+}
+/** The JSON export (`proof.json`): one object, fixed key order, versioned. */
+export interface ProofExportV1 {
+    schema: typeof PROOF_EXPORT_SCHEMA;
+    sessionId: string;
+    generatedAt: string;
+    summary: ProofSummary;
+    criteria: ProofCriterion[];
+    evidence: ProofEvidence[];
+    divergences: ProofLedger["divergences"];
+}
+export declare function proofSummary(ledger: ProofLedger): ProofSummary;
+export declare function proofExportV1(ledger: ProofLedger): ProofExportV1;
+/** `proof.json`: pretty JSON ending in a newline. */
+export declare const renderProofJson: (ledger: ProofLedger) => string;
+/** `proof.md`: the same statuses as the JSON, readable. The output excerpts are not repeated. */
+export declare function renderProofMarkdown(ledger: ProofLedger): string;
+/** The plain-text view of the ledger (terminal and headless report): one line per criterion. */
+export declare function renderProofText(ledger: ProofLedger): string;
+export interface ProofExitCodes {
+    /** At least one required criterion is `failed`. */
+    failed: number;
+    /** No failure, but a required criterion is `not_checked` or `manual_review`. */
+    unverified: number;
+}
+export declare const DEFAULT_PROOF_EXIT_CODES: ProofExitCodes;
+/** The CI exit code of a ledger (specs/011 3.7): failures win over unchecked criteria. */
+export declare function proofExitCode(ledger: ProofLedger, codes?: ProofExitCodes): number;
+/** Publishes `proof.md` and `proof.json` as artifacts of the calling session. */
+export declare function publishProofExport(publisher: Pick<ArtifactPublisher, "publishText">, ledger: ProofLedger): Promise<ArtifactRef[]>;
+export interface CriteriaInputError {
+    index: number;
+    reason: string;
+}
+/**
+ * Turns user-supplied criteria (HTTP body, `--proof-file`, `--criterion/--verify`) into
+ * `NewCriterion` values without a session. `verify` is shorthand for a `command` verifier and the
+ * default for `required` is true: a criterion the user wrote is one the user wants met.
+ */
+export declare function parseCriteriaInput(raw: unknown, options: {
+    origin: "user" | "cli";
+    defaultRequired?: boolean;
+}): {
+    criteria: Array<Omit<NewCriterion, "sessionId">>;
+    errors: CriteriaInputError[];
+};

package/dist/proof/export.js

@@ -0,0 +1,144 @@
+import { validateCriteriaDrafts } from "../plan/criteria.js";
+/** The `schema` of the JSON export. A breaking change to the shape is a new version. */
+export const PROOF_EXPORT_SCHEMA = "proof/v1";
+const UNMET = new Set(["failed", "not_checked", "manual_review"]);
+export function proofSummary(ledger) {
+    const count = (status) => ledger.criteria.filter((c) => c.status === status).length;
+    return {
+        total: ledger.criteria.length,
+        required: ledger.criteria.filter((c) => c.required).length,
+        requiredUnmet: ledger.criteria.filter((c) => c.required && UNMET.has(c.status)).length,
+        verified: count("verified"),
+        failed: count("failed"),
+        notChecked: count("not_checked"),
+        manualReview: count("manual_review"),
+        notApplicable: count("not_applicable"),
+    };
+}
+export function proofExportV1(ledger) {
+    return {
+        schema: PROOF_EXPORT_SCHEMA,
+        sessionId: ledger.sessionId,
+        generatedAt: ledger.generatedAt,
+        summary: proofSummary(ledger),
+        criteria: ledger.criteria,
+        evidence: ledger.evidence,
+        divergences: ledger.divergences,
+    };
+}
+/** `proof.json`: pretty JSON ending in a newline. */
+export const renderProofJson = (ledger) => `${JSON.stringify(proofExportV1(ledger), null, 2)}\n`;
+const cell = (text) => text.replace(/\|/g, "\\|").replace(/\s+/g, " ").trim();
+/** `proof.md`: the same statuses as the JSON, readable. The output excerpts are not repeated. */
+export function renderProofMarkdown(ledger) {
+    const s = proofSummary(ledger);
+    const byId = new Map(ledger.evidence.map((e) => [e.evidenceId, e]));
+    const lines = [
+        "# Proof",
+        "",
+        `Session \`${ledger.sessionId}\` · generated ${ledger.generatedAt} · schema \`${PROOF_EXPORT_SCHEMA}\``,
+        "",
+        `${s.total} criteria · ${s.verified} verified · ${s.failed} failed · ${s.notChecked} not checked · ` +
+            `${s.manualReview} manual review · ${s.notApplicable} not applicable · ` +
+            `${s.requiredUnmet} required not verified`,
+        "",
+    ];
+    if (!ledger.criteria.length)
+        lines.push("_No criteria._", "");
+    else {
+        lines.push("| Status | Required | Criterion | Evidence |", "| --- | --- | --- | --- |");
+        for (const c of ledger.criteria) {
+            const latest = [...c.evidenceIds]
+                .map((id) => byId.get(id))
+                .filter((e) => !!e)
+                .at(-1);
+            const status = c.stale ? `${c.status} (stale)` : c.status;
+            const evidence = latest
+                ? `${latest.callId} · exit ${latest.exitCode ?? "-"} · ${latest.capturedAt}`
+                : c.notApplicableReason
+                    ? `n/a: ${c.notApplicableReason}`
+                    : "-";
+            lines.push(`| ${status} | ${c.required ? "yes" : "no"} | ${cell(c.text)} | ${cell(evidence)} |`);
+        }
+        lines.push("");
+    }
+    if (ledger.divergences.length) {
+        lines.push("## Claims without evidence", "");
+        for (const d of ledger.divergences)
+            lines.push(`- "${cell(d.claim)}" (${d.actual})`);
+        lines.push("");
+    }
+    lines.push("_Proof records operational evidence; it does not prove that the code is correct._", "");
+    return lines.join("\n");
+}
+/** The plain-text view of the ledger (terminal and headless report): one line per criterion. */
+export function renderProofText(ledger) {
+    const s = proofSummary(ledger);
+    const head = !s.total
+        ? "Proof: no criteria"
+        : `Proof: ${s.verified} of ${s.total} criteria verified` +
+            (s.required ? ` · ${s.requiredUnmet} of ${s.required} required not verified` : "");
+    const lines = [head];
+    const width = Math.max(0, ...ledger.criteria.map((c) => statusLabel(c).length));
+    for (const c of ledger.criteria)
+        lines.push(`  ${statusLabel(c).padEnd(width)}  ${c.text.replace(/\s+/g, " ").trim()}${c.required ? " (required)" : ""}`);
+    for (const d of ledger.divergences)
+        lines.push(`  ! claim without evidence: "${d.claim.replace(/\s+/g, " ").trim()}" (${d.actual})`);
+    return lines.join("\n");
+}
+const statusLabel = (c) => (c.stale ? `${c.status}(stale)` : c.status);
+export const DEFAULT_PROOF_EXIT_CODES = { failed: 10, unverified: 11 };
+/** The CI exit code of a ledger (specs/011 3.7): failures win over unchecked criteria. */
+export function proofExitCode(ledger, codes = DEFAULT_PROOF_EXIT_CODES) {
+    const required = ledger.criteria.filter((c) => c.required);
+    if (required.some((c) => c.status === "failed"))
+        return codes.failed;
+    if (required.some((c) => c.status === "not_checked" || c.status === "manual_review"))
+        return codes.unverified;
+    return 0;
+}
+/** Publishes `proof.md` and `proof.json` as artifacts of the calling session. */
+export async function publishProofExport(publisher, ledger) {
+    const md = await publisher.publishText({
+        fileName: "proof.md",
+        title: "Proof",
+        text: renderProofMarkdown(ledger),
+    });
+    const json = await publisher.publishText({
+        fileName: "proof.json",
+        title: "Proof (JSON)",
+        text: renderProofJson(ledger),
+    });
+    return [md, json];
+}
+/**
+ * Turns user-supplied criteria (HTTP body, `--proof-file`, `--criterion/--verify`) into
+ * `NewCriterion` values without a session. `verify` is shorthand for a `command` verifier and the
+ * default for `required` is true: a criterion the user wrote is one the user wants met.
+ */
+export function parseCriteriaInput(raw, options) {
+    const list = Array.isArray(raw) ? raw : [];
+    const normalized = list.map((entry) => {
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry))
+            return entry;
+        const e = entry;
+        const { verify, ...rest } = e;
+        return {
+            ...rest,
+            required: e.required === undefined ? (options.defaultRequired ?? true) : e.required,
+            ...(typeof verify === "string" && e.verifier === undefined
+                ? { verifier: { kind: "command", command: verify } }
+                : {}),
+        };
+    });
+    if (!Array.isArray(raw))
+        return { criteria: [], errors: [{ index: 0, reason: "criteria must be an array" }] };
+    const checked = validateCriteriaDrafts(normalized);
+    return {
+        criteria: checked.accepted.map(({ origin: _inferred, ...draft }) => ({
+            ...draft,
+            origin: options.origin,
+        })),
+        errors: checked.dropped.map((d) => ({ index: d.index, reason: d.reason })),
+    };
+}

package/dist/proof/index.d.ts

@@ -0,0 +1,12 @@
+export * from "./command.ts";
+export * from "./divergence.ts";
+export * from "./export.ts";
+export * from "./ledger.ts";
+export * from "./plugin-verifiers.ts";
+export * from "./recorder.ts";
+export * from "./scope.ts";
+export * from "./store.ts";
+export * from "./tree.ts";
+export * from "./types.ts";
+export * from "./verifiers.ts";
+export * from "./verify.ts";

package/dist/proof/index.js

@@ -0,0 +1,12 @@
+export * from "./command.js";
+export * from "./divergence.js";
+export * from "./export.js";
+export * from "./ledger.js";
+export * from "./plugin-verifiers.js";
+export * from "./recorder.js";
+export * from "./scope.js";
+export * from "./store.js";
+export * from "./tree.js";
+export * from "./types.js";
+export * from "./verifiers.js";
+export * from "./verify.js";

package/dist/proof/ledger.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Pure derivation of the Proof ledger (specs/011 section 3.2). Nothing here reads a clock, a
+ * database or the filesystem: the same inputs always give the same statuses (D4).
+ */
+import type { ProofEvidence, ProofLedger, ProofStatus, ProofVerifierSpec } from "@alisio/sdk";
+import type { CriterionRecord } from "./types.ts";
+export interface DerivedStatus {
+    status: ProofStatus;
+    /** True when the criterion had successful evidence that a later edit in its scope invalidated. */
+    stale: boolean;
+}
+export interface DeriveOptions {
+    /** ISO time of the latest edit inside the criterion scope (D5), when there was one. */
+    lastEditAt?: string;
+}
+/**
+ * Derives the status of one criterion from its own evidence.
+ *
+ * - user `not_applicable` wins; no verifier is `not_checked` whatever evidence exists (D1);
+ *   a `manual` verifier is `manual_review`.
+ * - the latest backed evidence decides (later `capturedAt` wins; ties go to the later entry); a
+ *   latest evidence of kind `manual` means a verifier degraded the criterion to `manual_review`;
+ * - an edit at or after that evidence expires it (D5, fail safe on equal instants): an expired
+ *   success is `not_checked` and stale, an expired failure is just `not_checked`.
+ */
+export declare function deriveStatus(criterion: {
+    verifier?: ProofVerifierSpec;
+    notApplicableReason?: string;
+}, evidence: readonly ProofEvidence[], options?: DeriveOptions): DerivedStatus;
+export interface BuildLedgerOptions {
+    /** ISO time stamped on the ledger; the caller owns the clock. */
+    now: string;
+    /** Latest edit time inside the scope of a criterion (Fase 3 supplies it). */
+    lastEditAt?: (criterion: CriterionRecord) => string | undefined;
+    divergences?: ProofLedger["divergences"];
+}
+/** Assembles the ledger of one session: every criterion derived from its own evidence. */
+export declare function buildLedger(sessionId: string, criteria: readonly CriterionRecord[], evidence: readonly ProofEvidence[], options: BuildLedgerOptions): ProofLedger;

package/dist/proof/ledger.js

@@ -0,0 +1,57 @@
+const time = (iso) => Date.parse(iso);
+/** D2: only evidence that names its run, its call and a real date can back a status. */
+const backs = (e) => e.runId.length > 0 && e.callId.length > 0 && Number.isFinite(time(e.capturedAt));
+/**
+ * Derives the status of one criterion from its own evidence.
+ *
+ * - user `not_applicable` wins; no verifier is `not_checked` whatever evidence exists (D1);
+ *   a `manual` verifier is `manual_review`.
+ * - the latest backed evidence decides (later `capturedAt` wins; ties go to the later entry); a
+ *   latest evidence of kind `manual` means a verifier degraded the criterion to `manual_review`;
+ * - an edit at or after that evidence expires it (D5, fail safe on equal instants): an expired
+ *   success is `not_checked` and stale, an expired failure is just `not_checked`.
+ */
+export function deriveStatus(criterion, evidence, options = {}) {
+    if (criterion.notApplicableReason)
+        return { status: "not_applicable", stale: false };
+    if (!criterion.verifier)
+        return { status: "not_checked", stale: false };
+    if (criterion.verifier.kind === "manual")
+        return { status: "manual_review", stale: false };
+    let latest;
+    for (const e of evidence) {
+        if (backs(e) && (!latest || time(e.capturedAt) >= time(latest.capturedAt)))
+            latest = e;
+    }
+    if (!latest)
+        return { status: "not_checked", stale: false };
+    const edited = options.lastEditAt !== undefined && time(options.lastEditAt) >= time(latest.capturedAt);
+    if (edited)
+        return { status: "not_checked", stale: latest.ok };
+    // A verifier handed the criterion to a person (a plugin result with no traceable evidence).
+    if (latest.verifierKind === "manual")
+        return { status: "manual_review", stale: false };
+    return { status: latest.ok ? "verified" : "failed", stale: false };
+}
+/** Assembles the ledger of one session: every criterion derived from its own evidence. */
+export function buildLedger(sessionId, criteria, evidence, options) {
+    const derived = criteria.map((criterion) => {
+        const own = evidence.filter((e) => e.criterionId === criterion.criterionId);
+        const { status, stale } = deriveStatus(criterion, own, {
+            lastEditAt: options.lastEditAt?.(criterion),
+        });
+        return {
+            ...criterion,
+            status,
+            ...(stale ? { stale } : {}),
+            evidenceIds: own.map((e) => e.evidenceId),
+        };
+    });
+    return {
+        sessionId,
+        criteria: derived,
+        evidence: [...evidence],
+        divergences: options.divergences ?? [],
+        generatedAt: options.now,
+    };
+}

package/dist/proof/plugin-verifiers.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Registry of the Proof verifiers plugins contribute (`api.proof.registerVerifier`, specs/011
+ * 3.8). Criteria bind to a verifier as `<pluginId>:<id>`, exactly like plugin commands, so two
+ * plugins cannot shadow each other. The registry holds code only: it never creates criteria or
+ * evidence, and it grants no permission (a verifier's tool calls go through the core gate).
+ */
+import type { ProofVerifierRegistration } from "@alisio/sdk";
+export interface RegisteredVerifier {
+    plugin: string;
+    verifier: ProofVerifierRegistration;
+}
+export declare class ProofVerifierRegistry {
+    private readonly verifiers;
+    /** Registers `verifier` for `plugin`; returns the function that removes exactly this entry. */
+    register(plugin: string, verifier: ProofVerifierRegistration): () => void;
+    get(verifierId: string): RegisteredVerifier | undefined;
+    /** What is registered, sorted by id (no handlers). */
+    list(): Array<{
+        verifierId: string;
+        plugin: string;
+        describe: string;
+    }>;
+}

package/dist/proof/plugin-verifiers.js

@@ -0,0 +1,39 @@
+const VERIFIER_ID = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+const DESCRIBE_MAX = 500;
+export class ProofVerifierRegistry {
+    verifiers = new Map();
+    /** Registers `verifier` for `plugin`; returns the function that removes exactly this entry. */
+    register(plugin, verifier) {
+        if (typeof verifier?.id !== "string" || !VERIFIER_ID.test(verifier.id))
+            throw new Error(`Invalid verifier id: ${String(verifier?.id)}`);
+        if (typeof verifier.describe !== "string" || !verifier.describe.trim())
+            throw new Error("A verifier needs a description");
+        if (typeof verifier.run !== "function")
+            throw new Error("A verifier needs a run function");
+        const key = `${plugin}:${verifier.id}`;
+        if (this.verifiers.has(key))
+            throw new Error(`Duplicate verifier ${key}`);
+        const entry = {
+            plugin,
+            verifier: { ...verifier, describe: verifier.describe.trim().slice(0, DESCRIBE_MAX) },
+        };
+        this.verifiers.set(key, entry);
+        return () => {
+            if (this.verifiers.get(key) === entry)
+                this.verifiers.delete(key);
+        };
+    }
+    get(verifierId) {
+        return this.verifiers.get(verifierId);
+    }
+    /** What is registered, sorted by id (no handlers). */
+    list() {
+        return [...this.verifiers.entries()]
+            .map(([verifierId, { plugin, verifier }]) => ({
+            verifierId,
+            plugin,
+            describe: verifier.describe,
+        }))
+            .sort((a, b) => (a.verifierId < b.verifierId ? -1 : a.verifierId > b.verifierId ? 1 : 0));
+    }
+}

package/dist/proof/recorder.d.ts

@@ -0,0 +1,69 @@
+import type { RunEventDataMap, SqlDatabase, ToolResult } from "@alisio/sdk";
+import { type Divergence } from "./divergence.ts";
+export type ProofUpdate = RunEventDataMap["proof_updated"];
+/** A tool call that already executed, as the runner reports it. */
+export interface ExecutedCall {
+    sessionId: string;
+    runId: string;
+    callId: string;
+    name: string;
+    input: Record<string, unknown>;
+    /** The result exactly as the tool returned it. */
+    result: ToolResult;
+    workspace: string;
+    durationMs: number;
+}
+/** The last `EXCERPT_BYTES` bytes of the redacted output (the end holds the summary and errors). */
+export declare function excerptOf(output: string): string;
+export declare class ProofRecorder {
+    private readonly db;
+    private readonly options;
+    private readonly store;
+    /** `bg_run` calls whose exit code has not been seen yet, by session and task id. */
+    private readonly background;
+    constructor(db: SqlDatabase, options?: {
+        now?: () => Date;
+        /** `proof.coverage.enabled`, read on every call so a config reload applies at once. */
+        coverage?: () => boolean;
+    });
+    /** Records the evidence a just-executed call yields; returns the ledger changes to announce. */
+    capture(call: ExecutedCall): ProofUpdate[];
+    /**
+     * A `read_file` that threw because the file is not there (the runner reports it here: a throw
+     * never reaches `capture`). It refutes every `file` criterion on that path; any other failure
+     * proves nothing.
+     */
+    captureFailure(call: ExecutedCall): ProofUpdate[];
+    /** The criteria of the session the recorder can capture evidence for (not marked N/A). */
+    private tracked;
+    private finding;
+    private fileFindings;
+    private dataFindings;
+    private commandFindings;
+    /** Appends one evidence per finding, once the call is proven to be in the session journal. */
+    private persist;
+    private clock;
+    /**
+     * Notes a successful write/edit of a workspace file (D5) and announces the criteria whose
+     * derived status or staleness changed because of it. Edits outside the workspace cannot touch
+     * a workspace criterion and are ignored.
+     */
+    private captureEdit;
+    /**
+     * The claims of a final answer that the ledger does not back (D8: shown, never acted on). Empty
+     * without criteria, after one indexed read (D7).
+     */
+    divergences(sessionId: string, finalText: string): Divergence[];
+    /** Reads what a command call proved, or undefined when it proved nothing (yet). */
+    private outcome;
+    private processOutcome;
+    private startedBackground;
+    /** `bg_output` carries the exit code of a task this recorder saw start; once per task. */
+    private backgroundOutcome;
+    private key;
+    /**
+     * D2/D3: the call must exist in the session's tool-call journal under this run and name, which
+     * the runner writes before the tool executes. A forged or foreign `runId`/`callId` fails here.
+     */
+    private executed;
+}