@alisio/core 0.7.0 → 0.8.0

package/dist/proof/command.js

@@ -0,0 +1,109 @@
+/**
+ * Command fingerprint v1 (specs/011, Fase 0 decision): `sha256(JSON.stringify({v:1, argv, cwd}))`.
+ * `run_process` uses `[command, ...args]`; `shell` and `bg_run` use `["sh","-c", normalized]`; the
+ * working directory is relative to the workspace with `/` and `.` by default. No environment.
+ */
+import { createHash } from "node:crypto";
+import { isAbsolute, relative, resolve } from "node:path";
+/** The canonical workspace-relative directory: forward slashes, no `./` prefix, `.` when empty. */
+export function normalizeCwd(cwd) {
+    return (cwd
+        .split("\\")
+        .join("/")
+        .replace(/^(\.\/)+/, "")
+        .replace(/\/+$/, "") || ".");
+}
+/** Directory of a call relative to the workspace (`.` when it is the workspace itself). */
+export function relativeCwd(workspace, cwd) {
+    if (!cwd)
+        return ".";
+    const abs = isAbsolute(cwd) ? cwd : resolve(workspace, cwd);
+    return normalizeCwd(relative(workspace, abs));
+}
+export function commandFingerprint(argv, cwd) {
+    return createHash("sha256")
+        .update(JSON.stringify({ v: 1, argv, cwd: normalizeCwd(cwd) }))
+        .digest("hex");
+}
+/** Trims and collapses whitespace runs OUTSIDE single/double quotes; quoted text stays verbatim. */
+export function normalizeShell(command) {
+    let out = "";
+    let quote;
+    let pendingSpace = false;
+    for (const ch of command.trim()) {
+        if (quote) {
+            out += ch;
+            if (ch === quote)
+                quote = undefined;
+        }
+        else if (/\s/.test(ch)) {
+            pendingSpace = true;
+        }
+        else {
+            if (pendingSpace)
+                out += " ";
+            pendingSpace = false;
+            out += ch;
+            if (ch === '"' || ch === "'")
+                quote = ch;
+        }
+    }
+    return out;
+}
+/** Fingerprint of a call as the tool received it. */
+export function callFingerprint(tool, input, cwd) {
+    const argv = tool === "run_process"
+        ? [input.command, ...(input.args ?? [])]
+        : ["sh", "-c", normalizeShell(input.command)];
+    return commandFingerprint(argv, cwd);
+}
+const SHELL_OPERATORS = /[|&;<>()$`\\*?~#{}!\n]/;
+/**
+ * Splits a plain command line into an argv (single and double quotes group words). Returns
+ * undefined when the line needs a shell (operators, expansions, unbalanced quotes): only the
+ * shell form can then match it.
+ */
+export function splitCommand(command) {
+    const argv = [];
+    let word;
+    let quote;
+    for (const ch of command.trim()) {
+        if (quote) {
+            if (ch === quote)
+                quote = undefined;
+            else
+                word += ch;
+        }
+        else if (ch === '"' || ch === "'") {
+            quote = ch;
+            word ??= "";
+        }
+        else if (/\s/.test(ch)) {
+            if (word !== undefined)
+                argv.push(word);
+            word = undefined;
+        }
+        else if (SHELL_OPERATORS.test(ch)) {
+            return undefined;
+        }
+        else {
+            word = (word ?? "") + ch;
+        }
+    }
+    if (quote)
+        return undefined;
+    if (word !== undefined)
+        argv.push(word);
+    return argv.length ? argv : undefined;
+}
+/**
+ * Every fingerprint a call may have to satisfy the criterion command `command` run in `cwd`: the
+ * `shell` form always and the `run_process` form when the line is a plain argv.
+ */
+export function criterionFingerprints(command, cwd) {
+    const out = [callFingerprint("shell", { command }, cwd)];
+    const argv = splitCommand(command);
+    if (argv)
+        out.unshift(commandFingerprint(argv, cwd));
+    return out;
+}

package/dist/proof/coverage.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Pure parser and judge of the `coverage` verifier (specs/011 3.1, Fase 7). They read the text a
+ * coverage command printed and say whether the overall percentage reaches `minPercent`; they never
+ * run anything and never generate tests. The evidence itself is captured by the recorder from the
+ * RAW result of a call the runner executed under its gate (D3, D6).
+ *
+ * Formats, tried from the most explicit overall figure to the least:
+ *  1. `coverage.py` / pytest-cov: the `TOTAL` row (last percentage) or `Total coverage: N%`.
+ *  2. A text table (vitest, c8, istanbul): the `All files` row, `% Lines` column.
+ *  3. An istanbul `text-summary`: the `Lines : N%` row.
+ *  4. `lcov --summary`: the `lines......: N%` row.
+ *  5. Raw `lcov` tracefile: sum of `LH` over sum of `LF`.
+ * Per-file rows never stand in for the total: a missing overall figure is "not found", so an
+ * unparseable output can never verify a criterion. Several matches of one format: the last wins.
+ */
+import type { ProofVerifierSpec } from "@alisio/sdk";
+export type CoverageSpec = Extract<ProofVerifierSpec, {
+    kind: "coverage";
+}>;
+export type CoverageFormat = "coverage.py" | "table" | "summary" | "lcov-summary" | "lcov";
+export interface ParsedCoverage {
+    percent: number;
+    format: CoverageFormat;
+}
+/** The overall coverage percentage a command printed, or undefined when there is none to trust. */
+export declare function parseCoverage(output: string): ParsedCoverage | undefined;
+/** What a coverage judgement concluded: the verdict and a short, secret-free sentence about it. */
+export interface CoverageJudgement {
+    ok: boolean;
+    summary: string;
+}
+/**
+ * Judges what the coverage command did. It verifies only when the command exited 0 AND an overall
+ * percentage was found AND it reaches `minPercent` (inclusive); every other case is a failure with
+ * a reason, so an unparseable output or a crashed run is never silently verified.
+ */
+export declare function judgeCoverage(spec: CoverageSpec, run: {
+    exitCode: number;
+    output: string;
+}): CoverageJudgement;

package/dist/proof/coverage.js

@@ -0,0 +1,102 @@
+const ANSI = /\u001b\[[0-9;]*[A-Za-z]/g;
+const NUMBER = String.raw `(\d{1,3}(?:\.\d+)?)`;
+const valid = (value) => Number.isFinite(value) && value >= 0 && value <= 100;
+const lastMatch = (text, pattern) => {
+    let found;
+    for (const match of text.matchAll(pattern))
+        found = match;
+    return found;
+};
+function pythonTotal(text) {
+    // pytest-cov prints the precise figure on its own line; prefer it over the rounded TOTAL row.
+    const line = lastMatch(text, new RegExp(String.raw `Total coverage:\s*${NUMBER}%`, "gi"));
+    if (line?.[1])
+        return Number(line[1]);
+    const row = lastMatch(text, new RegExp(String.raw `^\s*TOTAL\b[^\n]*?(?<![\d.])${NUMBER}%[ \t]*$`, "gim"));
+    return row?.[1] ? Number(row[1]) : undefined;
+}
+function tableTotal(text) {
+    const lines = text.split("\n");
+    let column = -1;
+    let result;
+    for (const line of lines) {
+        if (!line.includes("|"))
+            continue;
+        const cells = line.split("|").map((cell) => cell.trim());
+        const header = cells.findIndex((cell) => /^%\s*lines?$/i.test(cell));
+        if (header >= 0) {
+            column = header;
+            continue;
+        }
+        if (column < 0 || !/^all files$/i.test(cells[0] ?? ""))
+            continue;
+        const raw = (cells[column] ?? "").replace(/%$/, "");
+        result = /^\d{1,3}(?:\.\d+)?$/.test(raw) ? Number(raw) : undefined;
+    }
+    return result;
+}
+function summaryLines(text) {
+    const row = lastMatch(text, new RegExp(String.raw `^\s*Lines\s*:\s*${NUMBER}%`, "gim"));
+    return row?.[1] ? Number(row[1]) : undefined;
+}
+function lcovSummary(text) {
+    const row = lastMatch(text, new RegExp(String.raw `^\s*lines\.+:\s*${NUMBER}%`, "gim"));
+    return row?.[1] ? Number(row[1]) : undefined;
+}
+function lcovTracefile(text) {
+    let found = 0;
+    let hit = 0;
+    for (const match of text.matchAll(/^(LF|LH):(\d+)\s*$/gm)) {
+        if (match[1] === "LF")
+            found += Number(match[2]);
+        else
+            hit += Number(match[2]);
+    }
+    return found > 0 ? (hit / found) * 100 : undefined;
+}
+const PARSERS = [
+    ["coverage.py", pythonTotal],
+    ["table", tableTotal],
+    ["summary", summaryLines],
+    ["lcov-summary", lcovSummary],
+    ["lcov", lcovTracefile],
+];
+/** The overall coverage percentage a command printed, or undefined when there is none to trust. */
+export function parseCoverage(output) {
+    const text = output.replace(ANSI, "");
+    for (const [format, parse] of PARSERS) {
+        const percent = parse(text);
+        if (percent !== undefined && valid(percent))
+            return { percent, format };
+    }
+    return undefined;
+}
+const shown = (value) => String(Math.round(value * 100) / 100);
+/**
+ * Judges what the coverage command did. It verifies only when the command exited 0 AND an overall
+ * percentage was found AND it reaches `minPercent` (inclusive); every other case is a failure with
+ * a reason, so an unparseable output or a crashed run is never silently verified.
+ */
+export function judgeCoverage(spec, run) {
+    const parsed = parseCoverage(run.output);
+    if (!parsed)
+        return {
+            ok: false,
+            summary: `no coverage percentage found in the output (command exited ${run.exitCode}); expected lcov, a vitest/istanbul table or coverage.py report`,
+        };
+    const percent = `${shown(parsed.percent)}%`;
+    if (run.exitCode !== 0)
+        return {
+            ok: false,
+            summary: `the coverage command exited ${run.exitCode} (reported ${percent}, ${parsed.format})`,
+        };
+    if (parsed.percent < spec.minPercent)
+        return {
+            ok: false,
+            summary: `coverage ${percent} is below the minimum ${shown(spec.minPercent)}% (${parsed.format})`,
+        };
+    return {
+        ok: true,
+        summary: `coverage ${percent} reaches the minimum ${shown(spec.minPercent)}% (${parsed.format})`,
+    };
+}

package/dist/proof/divergence.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Claim/evidence divergence (specs/011 3.5, D7, D8). `detectDivergence` is pure: it reads closed
+ * EN/ES claim patterns in a final answer ("tests pass", "typecheck ok", "lint clean", "los tests
+ * pasan"...), cross-references them with the criteria of an equivalent kind and reports the ones
+ * the ledger does not back. It never edits text or statuses; it is a heuristic signal, not a
+ * guarantee, and claims inside quotes and code are ignored to limit false positives.
+ */
+import type { ProofLedger, ProofStatus } from "@alisio/sdk";
+export type ClaimKind = "test" | "typecheck" | "lint";
+export interface Divergence {
+    /** The matched wording, whitespace-collapsed and capped. */
+    claim: string;
+    kind: ClaimKind;
+    /** What would have backed the claim. */
+    expected: "verified";
+    /** The status of the equivalent criterion (`not_checked` when there is none). */
+    actualState: ProofStatus;
+    criterionId?: string;
+}
+/**
+ * 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 declare function detectDivergence(finalText: string, ledger: ProofLedger): Divergence[];

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;