kibi-cli 2.0.0 → 2.2.0

package/dist/operations/proof/baseline-diff.js

@@ -0,0 +1,153 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+ */
+// implements REQ-kibi-verification-evidence-contract
+export const PROOF_BASELINE_VERSION = "kibi.proof-baseline.v2";
+function asStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((item) => (typeof item === "string" ? item : String(item)))
+        .sort();
+}
+// implements REQ-kibi-verification-evidence-contract
+export function fingerprintRequirements(rows) {
+    const requirements = {};
+    for (const row of rows) {
+        const id = typeof row.id === "string" ? row.id : "";
+        const proofStatus = typeof row.proofStatus === "string" ? row.proofStatus : "";
+        if (id === "" || proofStatus === "not_applicable")
+            continue;
+        requirements[id] = {
+            proofStatus,
+            gaps: asStringArray(row.proofGaps),
+            uncoveredSymbols: asStringArray(row.proofStages?.productionSymbols?.uncoveredSymbols),
+        };
+    }
+    return requirements;
+}
+// implements REQ-kibi-verification-evidence-contract
+export function diffFingerprints(baseline, current) {
+    const before = baseline ?? {};
+    const ids = [
+        ...new Set([...Object.keys(before), ...Object.keys(current)]),
+    ].sort();
+    const changes = [];
+    for (const id of ids) {
+        const left = before[id];
+        const right = current[id];
+        if (left === undefined && right !== undefined) {
+            changes.push({ id, kind: "added", after: right });
+            continue;
+        }
+        if (left !== undefined && right === undefined) {
+            changes.push({ id, kind: "removed", before: left });
+            continue;
+        }
+        if (left === undefined || right === undefined)
+            continue;
+        if (left.proofStatus !== right.proofStatus ||
+            JSON.stringify(left.gaps) !== JSON.stringify(right.gaps) ||
+            JSON.stringify(left.uncoveredSymbols) !==
+                JSON.stringify(right.uncoveredSymbols)) {
+            changes.push({ id, kind: "changed", before: left, after: right });
+        }
+    }
+    return changes;
+}
+export function explanationsForRequirement(rows, requirementId) {
+    const row = rows.find((item) => item.id === requirementId);
+    const explanations = row?.proofStages?.productionSymbols?.explanations;
+    return Array.isArray(explanations)
+        ? explanations
+        : [];
+}
+function renderCandidate(candidate) {
+    const testId = typeof candidate.testId === "string" ? candidate.testId : "?";
+    const reason = typeof candidate.reason === "string" ? candidate.reason : "";
+    const secondaries = Array.isArray(candidate.secondaryReasons)
+        ? candidate.secondaryReasons.filter((item) => typeof item === "string")
+        : [];
+    const secondaryText = secondaries.length > 0 ? ` secondary=${secondaries.join(",")}` : "";
+    return `      covered_by ${testId}: ${reason}${secondaryText}`;
+}
+// implements REQ-kibi-verification-evidence-contract
+export function renderRequirementDiffs(changes, rows = []) {
+    if (changes.length === 0)
+        return "";
+    const lines = [
+        "Requirement fingerprint diffs vs committed proof/baseline.json:",
+    ];
+    for (const change of changes) {
+        if (change.kind === "added" && change.after) {
+            lines.push(`  ${change.id}: added (${change.after.proofStatus}; gaps=${change.after.gaps.join(",") || "none"})`);
+        }
+        else if (change.kind === "removed" && change.before) {
+            lines.push(`  ${change.id}: removed (was ${change.before.proofStatus})`);
+        }
+        else if (change.kind === "changed" && change.before && change.after) {
+            if (change.before.proofStatus !== change.after.proofStatus) {
+                lines.push(`  ${change.id}: ${change.before.proofStatus} -> ${change.after.proofStatus}`);
+            }
+            else {
+                lines.push(`  ${change.id}: fingerprint changed`);
+            }
+            const beforeGaps = new Set(change.before.gaps);
+            const afterGaps = new Set(change.after.gaps);
+            for (const gap of change.after.gaps) {
+                if (!beforeGaps.has(gap))
+                    lines.push(`    gap added: ${gap}`);
+            }
+            for (const gap of change.before.gaps) {
+                if (!afterGaps.has(gap))
+                    lines.push(`    gap removed: ${gap}`);
+            }
+            const beforeSymbols = new Set(change.before.uncoveredSymbols);
+            const afterSymbols = new Set(change.after.uncoveredSymbols);
+            for (const symbol of change.after.uncoveredSymbols) {
+                if (!beforeSymbols.has(symbol))
+                    lines.push(`    uncovered symbol added: ${symbol}`);
+            }
+            for (const symbol of change.before.uncoveredSymbols) {
+                if (!afterSymbols.has(symbol))
+                    lines.push(`    uncovered symbol removed: ${symbol}`);
+            }
+        }
+        const explanations = explanationsForRequirement(rows, change.id);
+        for (const explanation of explanations) {
+            const symbolId = typeof explanation.symbolId === "string" ? explanation.symbolId : "";
+            const reason = typeof explanation.reason === "string" ? explanation.reason : "";
+            if (symbolId !== "")
+                lines.push(`    ${symbolId}: ${reason}`);
+            const candidates = Array.isArray(explanation.coverageCandidates)
+                ? explanation.coverageCandidates
+                : [];
+            for (const candidate of candidates) {
+                if (candidate && typeof candidate === "object")
+                    lines.push(renderCandidate(candidate));
+            }
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+export function parseSpawnJson(result) {
+    if (result.error)
+        throw result.error;
+    const text = `${result.stdout ?? ""}`.trim();
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        const detail = `${result.stderr || result.stdout || ""}`.trim();
+        if (result.status !== 0 && result.status !== null) {
+            throw new Error(detail || String(error));
+        }
+        throw error;
+    }
+}

package/dist/operations/proof/code-scope.d.ts

@@ -0,0 +1,17 @@
+import type { PrologPort } from "../../public/operations/runtime-types.js";
+/**
+ * Which symbols a proof receipt's per-contract binding covers. Receipt ingest
+ * (which writes `binding_hash`) and coverage (which checks it) must derive
+ * the same set, so both go through this module:
+ *
+ * - the contract's required proof symbols (the test's own executable code),
+ * - any symbols the test declares in `proof_bindings`,
+ * - every production symbol linked `covered_by` this test.
+ *
+ * Editing any of those symbols' source files changes the binding hash, so the
+ * receipt goes stale until the test is proven again on the new code.
+ */
+export declare function receiptCodeScopeSymbolIds(contract: unknown, bindings: unknown, coveredBySymbols: readonly string[]): string[];
+/** Map each test id to the symbols linked `covered_by` it, in one query. */
+export declare function loadCoveredBySymbolsByTest(prolog: Pick<PrologPort, "query">): Promise<ReadonlyMap<string, readonly string[]>>;
+//# sourceMappingURL=code-scope.d.ts.map

package/dist/operations/proof/code-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-scope.d.ts","sourceRoot":"","sources":["../../../src/operations/proof/code-scope.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAE3E;;;;;;;;;;;GAWG;AAEH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,OAAO,EACjB,QAAQ,EAAE,OAAO,EACjB,gBAAgB,EAAE,SAAS,MAAM,EAAE,GAClC,MAAM,EAAE,CAoBV;AAED,4EAA4E;AAE5E,wBAAsB,0BAA0B,CAC9C,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAiBjD"}

package/dist/operations/proof/code-scope.js

@@ -0,0 +1,60 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+ */
+import { normalizeEntityId, parseTriples } from "../../prolog/codec.js";
+/**
+ * Which symbols a proof receipt's per-contract binding covers. Receipt ingest
+ * (which writes `binding_hash`) and coverage (which checks it) must derive
+ * the same set, so both go through this module:
+ *
+ * - the contract's required proof symbols (the test's own executable code),
+ * - any symbols the test declares in `proof_bindings`,
+ * - every production symbol linked `covered_by` this test.
+ *
+ * Editing any of those symbols' source files changes the binding hash, so the
+ * receipt goes stale until the test is proven again on the new code.
+ */
+// implements REQ-kibi-verification-evidence-contract
+export function receiptCodeScopeSymbolIds(contract, bindings, coveredBySymbols) {
+    const ids = new Set();
+    const requiredProofs = contract !== null &&
+        typeof contract === "object" &&
+        Array.isArray(contract.required_proofs)
+        ? contract.required_proofs
+        : [];
+    for (const entry of [
+        ...requiredProofs,
+        ...(Array.isArray(bindings) ? bindings : []),
+    ]) {
+        const symbolId = entry !== null && typeof entry === "object"
+            ? entry.symbol_id
+            : undefined;
+        if (typeof symbolId === "string" && symbolId !== "")
+            ids.add(symbolId);
+    }
+    for (const symbolId of coveredBySymbols)
+        ids.add(symbolId);
+    return [...ids].sort();
+}
+/** Map each test id to the symbols linked `covered_by` it, in one query. */
+// implements REQ-kibi-verification-evidence-contract
+export async function loadCoveredBySymbolsByTest(prolog) {
+    const result = await prolog.query("findall([From,To,'covered_by'], kb_relationship(covered_by, From, To), Rels)");
+    if (!result.success) {
+        throw new Error(`covered_by relationship query failed: ${result.error ?? "Unknown error"}`);
+    }
+    const byTest = new Map();
+    for (const [rawFrom, rawTo] of parseTriples(result.bindings.Rels ?? "[]")) {
+        const testId = normalizeEntityId(rawTo);
+        const symbols = byTest.get(testId) ?? [];
+        symbols.push(normalizeEntityId(rawFrom));
+        byTest.set(testId, symbols);
+    }
+    return byTest;
+}

package/dist/operations/proof/explain.d.ts

@@ -0,0 +1,75 @@
+import type { OperationContext } from "../../public/operations/runtime-types.js";
+export type ProofExplainKind = "requirement" | "symbol";
+export type ProofResolutionRef = {
+    readonly id?: string;
+    readonly sourceFile?: string;
+    readonly path?: string;
+    readonly role?: string;
+    readonly exists?: boolean;
+};
+export type ProofCoverageCandidate = {
+    readonly testId: string;
+    readonly relationship: string;
+    readonly qualifies: boolean;
+    readonly reason: string;
+    readonly reasonText?: string;
+    readonly secondaryReasons: readonly string[];
+    readonly scope?: string;
+    readonly receiptState?: string;
+};
+export type ProofExplainTestBlock = {
+    readonly testId: string;
+    readonly requiredProofs: readonly ProofResolutionRef[];
+    readonly executableFor: readonly ProofResolutionRef[];
+};
+export type ProofExplainSymbolBlock = {
+    readonly symbolId: string;
+    readonly classification: string;
+    readonly status: string;
+    readonly reason: string;
+    readonly reasonText?: string;
+    readonly coverageCandidates: readonly ProofCoverageCandidate[];
+};
+export type RequirementProofExplainView = {
+    readonly kind: "requirement";
+    readonly id: string;
+    readonly proofVersion: string;
+    readonly proofStatus: string;
+    readonly proofGaps: readonly string[];
+    readonly scenarios: readonly {
+        id: string;
+        tests: readonly string[];
+    }[];
+    readonly tests: readonly ProofExplainTestBlock[];
+    readonly productionSymbols: readonly ProofExplainSymbolBlock[];
+    readonly structuralSymbols: readonly ProofExplainSymbolBlock[];
+};
+export type SymbolProofExplainView = {
+    readonly kind: "symbol";
+    readonly id: string;
+    readonly role: string;
+    readonly executableTest: boolean;
+    readonly implementingRequirements: readonly string[];
+    readonly executableFor: readonly string[];
+    readonly coveredBy: readonly string[];
+    readonly proofs: readonly RequirementProofExplainView[];
+};
+export type ProofExplainView = RequirementProofExplainView | SymbolProofExplainView;
+export declare function projectRequirementExplain(proof: Record<string, unknown>): RequirementProofExplainView;
+export declare function projectSymbolExplain(payload: Record<string, unknown>): SymbolProofExplainView;
+export declare function renderProofExplain(view: ProofExplainView): string;
+export declare function classifyExplainTarget(id: string | undefined, options: {
+    requirement?: string;
+    symbol?: string;
+}): {
+    kind: ProofExplainKind;
+    id: string;
+};
+export declare function executeProofExplain(target: {
+    kind: ProofExplainKind;
+    id: string;
+}, context: OperationContext): Promise<{
+    view: ProofExplainView;
+    payload: Record<string, unknown>;
+}>;
+//# sourceMappingURL=explain.d.ts.map

package/dist/operations/proof/explain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.d.ts","sourceRoot":"","sources":["../../../src/operations/proof/explain.ts"],"names":[],"mappings":"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"}

package/dist/operations/proof/explain.js

@@ -0,0 +1,294 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+ */
+import { runOperationJsonQuery, toPrologAtom, } from "../../public/operations/prolog-json.js";
+import { currentProofBindingMode, perContractTestBindings, } from "../../public/operations/specs/reporting.js";
+import { readWorkspaceSnapshot } from "../../public/operations/workspace-snapshot.js";
+import { PROOF_RECEIPT_MAX_AGE_SECONDS } from "../../public/proof-receipt.js";
+function requireProlog(context) {
+    if (context.prolog === undefined) {
+        throw new Error("Proof explain requires a Prolog runtime");
+    }
+    return context.prolog;
+}
+function asRecord(value) {
+    return value !== null && typeof value === "object"
+        ? value
+        : {};
+}
+function asString(value, fallback = "") {
+    return typeof value === "string" ? value : fallback;
+}
+function asStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.map((item) => asString(item)).filter((item) => item !== "");
+}
+function asBoolean(value) {
+    return value === true;
+}
+function asRef(value) {
+    const row = asRecord(value);
+    return {
+        ...(typeof row.id === "string" ? { id: row.id } : {}),
+        ...(typeof row.sourceFile === "string"
+            ? { sourceFile: row.sourceFile }
+            : {}),
+        ...(typeof row.path === "string" ? { path: row.path } : {}),
+        ...(typeof row.role === "string" ? { role: row.role } : {}),
+        ...(row.exists === true || row.exists === false
+            ? { exists: row.exists }
+            : {}),
+    };
+}
+function asCandidate(value) {
+    const row = asRecord(value);
+    return {
+        testId: asString(row.testId),
+        relationship: asString(row.relationship, "covered_by"),
+        qualifies: asBoolean(row.qualifies),
+        reason: asString(row.reason),
+        ...(typeof row.reasonText === "string"
+            ? { reasonText: row.reasonText }
+            : {}),
+        secondaryReasons: asStringArray(row.secondaryReasons),
+        ...(typeof row.scope === "string" ? { scope: row.scope } : {}),
+        ...(typeof row.receiptState === "string"
+            ? { receiptState: row.receiptState }
+            : {}),
+    };
+}
+function asSymbolBlock(value) {
+    const row = asRecord(value);
+    return {
+        symbolId: asString(row.symbolId),
+        classification: asString(row.classification, "unknown"),
+        status: asString(row.status),
+        reason: asString(row.reason),
+        ...(typeof row.reasonText === "string"
+            ? { reasonText: row.reasonText }
+            : {}),
+        coverageCandidates: Array.isArray(row.coverageCandidates)
+            ? row.coverageCandidates.map(asCandidate)
+            : [],
+    };
+}
+// implements REQ-kibi-verification-evidence-contract
+export function projectRequirementExplain(proof) {
+    const stages = asRecord(proof.proofStages);
+    const scenarioStage = asRecord(stages.scenarios);
+    const scenarioTestStage = asRecord(stages.scenarioTests);
+    const production = asRecord(stages.productionSymbols);
+    const obligations = Array.isArray(scenarioTestStage.obligations)
+        ? scenarioTestStage.obligations.map(asRecord)
+        : [];
+    const resolutions = Array.isArray(proof.testResolutions ?? scenarioTestStage.resolutions)
+        ? (proof.testResolutions ?? scenarioTestStage.resolutions)
+        : [];
+    const resolutionByTest = new Map();
+    for (const item of resolutions) {
+        const row = asRecord(item);
+        const testId = asString(row.testId);
+        if (testId === "")
+            continue;
+        resolutionByTest.set(testId, {
+            testId,
+            requiredProofs: Array.isArray(row.requiredProofs)
+                ? row.requiredProofs.map(asRef)
+                : [],
+            executableFor: Array.isArray(row.executableFor)
+                ? row.executableFor.map(asRef)
+                : [],
+        });
+    }
+    const tests = asStringArray(scenarioTestStage.tests).map((testId) => {
+        return (resolutionByTest.get(testId) ?? {
+            testId,
+            requiredProofs: [],
+            executableFor: [],
+        });
+    });
+    const scenarios = (Array.isArray(scenarioStage.scenarios)
+        ? scenarioStage.scenarios
+        : asStringArray(scenarioStage.scenarios)).map((scenarioId) => {
+        const id = asString(scenarioId);
+        const obligation = obligations.find((item) => asString(item.scenarioId) === id);
+        return {
+            id,
+            tests: asStringArray(obligation?.tests),
+        };
+    });
+    const explanations = Array.isArray(production.explanations)
+        ? production.explanations.map(asSymbolBlock)
+        : [];
+    const structuralIds = new Set(asStringArray(production.structuralSymbols));
+    return {
+        kind: "requirement",
+        id: asString(proof.id),
+        proofVersion: asString(proof.proofVersion),
+        proofStatus: asString(proof.proofStatus),
+        proofGaps: asStringArray(proof.proofGaps),
+        scenarios,
+        tests,
+        productionSymbols: explanations.filter((item) => !structuralIds.has(item.symbolId)),
+        structuralSymbols: explanations.filter((item) => structuralIds.has(item.symbolId)),
+    };
+}
+// implements REQ-kibi-verification-evidence-contract
+export function projectSymbolExplain(payload) {
+    const proofs = Array.isArray(payload.proofs)
+        ? payload.proofs.map((item) => projectRequirementExplain(asRecord(item)))
+        : [];
+    return {
+        kind: "symbol",
+        id: asString(payload.symbolId ?? payload.id),
+        role: asString(payload.role, "unknown"),
+        executableTest: asBoolean(payload.executableTest),
+        implementingRequirements: asStringArray(payload.implementingRequirements),
+        executableFor: asStringArray(payload.executableFor),
+        coveredBy: asStringArray(payload.coveredBy),
+        proofs,
+    };
+}
+// implements REQ-kibi-verification-evidence-contract
+export function renderProofExplain(view) {
+    if (view.kind === "symbol")
+        return renderSymbolExplain(view);
+    return renderRequirementExplain(view);
+}
+function renderRequirementExplain(view) {
+    const lines = [
+        `Proof explain for ${view.id}`,
+        `proofVersion: ${view.proofVersion}`,
+        `proofStatus: ${view.proofStatus}`,
+        `proofGaps: ${view.proofGaps.join(", ") || "(none)"}`,
+        "",
+        "Scenarios",
+    ];
+    if (view.scenarios.length === 0)
+        lines.push("  (none)");
+    for (const scenario of view.scenarios) {
+        lines.push(`  ${scenario.id} -> ${scenario.tests.join(", ") || "(no tests)"}`);
+    }
+    lines.push("");
+    for (const test of view.tests) {
+        lines.push(`TEST ${test.testId}`);
+        lines.push("  required_proofs");
+        if (test.requiredProofs.length === 0)
+            lines.push("    (none)");
+        for (const ref of test.requiredProofs) {
+            lines.push(`    ${formatRef(ref)}`);
+        }
+        lines.push("  executable_for");
+        if (test.executableFor.length === 0)
+            lines.push("    (none)");
+        for (const ref of test.executableFor) {
+            lines.push(`    ${formatRef(ref)}`);
+        }
+        lines.push("");
+    }
+    lines.push("Production symbols");
+    if (view.productionSymbols.length === 0)
+        lines.push("  (none)");
+    for (const symbol of view.productionSymbols) {
+        lines.push(renderSymbolCoverage(symbol));
+    }
+    if (view.structuralSymbols.length > 0) {
+        lines.push("");
+        lines.push("Structural symbols");
+        for (const symbol of view.structuralSymbols) {
+            lines.push(renderSymbolCoverage(symbol));
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+function renderSymbolExplain(view) {
+    const lines = [
+        `Proof explain for ${view.id}`,
+        `role: ${view.role}`,
+        `executable_test: ${view.executableTest ? "true" : "false"}`,
+        `implementing requirements: ${view.implementingRequirements.join(", ") || "(none)"}`,
+        "executable_for",
+        ...(view.executableFor.length === 0
+            ? ["  (none)"]
+            : view.executableFor.map((id) => `  ${id}`)),
+        "covered_by",
+        ...(view.coveredBy.length === 0
+            ? ["  (none)"]
+            : view.coveredBy.map((id) => `  ${id}`)),
+    ];
+    for (const proof of view.proofs) {
+        lines.push("");
+        lines.push(`Requirement ${proof.id} (${proof.proofStatus})`);
+        lines.push(renderRequirementExplain(proof).trimEnd());
+    }
+    return `${lines.join("\n")}\n`;
+}
+function renderSymbolCoverage(symbol) {
+    const lines = [
+        `  ${symbol.symbolId} [${symbol.classification}] ${symbol.status} ${symbol.reason}`,
+        "    covered_by",
+    ];
+    if (symbol.coverageCandidates.length === 0)
+        lines.push("      (none)");
+    for (const candidate of symbol.coverageCandidates) {
+        const secondaries = candidate.secondaryReasons.length > 0
+            ? ` secondary=${candidate.secondaryReasons.join(",")}`
+            : "";
+        lines.push(`      ${candidate.testId} qualifies=${candidate.qualifies} reason=${candidate.reason}${secondaries}`);
+    }
+    return lines.join("\n");
+}
+function formatRef(ref) {
+    const id = ref.id ?? "(unresolved)";
+    const path = ref.path ?? ref.sourceFile ?? "";
+    const role = ref.role ? ` role=${ref.role}` : "";
+    return path === "" ? `${id}${role}` : `${id} ${path}${role}`;
+}
+// implements REQ-kibi-verification-evidence-contract
+export function classifyExplainTarget(id, options) {
+    if (options.requirement && options.symbol) {
+        throw new Error("proof explain: choose either --requirement or --symbol, not both");
+    }
+    if (options.requirement)
+        return { kind: "requirement", id: options.requirement };
+    if (options.symbol)
+        return { kind: "symbol", id: options.symbol };
+    if (id?.startsWith("REQ-"))
+        return { kind: "requirement", id };
+    if (id?.startsWith("SYM-"))
+        return { kind: "symbol", id };
+    throw new Error("proof explain: pass REQ-* or SYM-* (or --requirement / --symbol)");
+}
+async function proofQueryContext(context) {
+    const snapshotEvidence = await readWorkspaceSnapshot(context);
+    const snapshot = snapshotEvidence.available
+        ? snapshotEvidence.snapshot.hash
+        : "unknown";
+    const checkedAt = context.clock().toISOString();
+    const bindingsDict = await perContractTestBindings(context);
+    const bindingMode = bindingsDict !== null ? "per_contract" : currentProofBindingMode();
+    const bindings = bindingsDict ?? "_{}";
+    return {
+        snapshot,
+        checkedAt,
+        bindingsGoal: `${bindingMode}, ${bindings}, ${toPrologAtom(snapshot)}, ${toPrologAtom(checkedAt)}, ${PROOF_RECEIPT_MAX_AGE_SECONDS}`,
+    };
+}
+// implements REQ-kibi-verification-evidence-contract
+export async function executeProofExplain(target, context) {
+    const query = await proofQueryContext(context);
+    if (target.kind === "requirement") {
+        const payload = await runOperationJsonQuery(requireProlog(context), "discovery.pl", `discovery:requirement_proof_json(${toPrologAtom(target.id)}, ${query.bindingsGoal}, JsonString)`, "Proof explain");
+        const withId = { id: target.id, ...payload };
+        return { view: projectRequirementExplain(withId), payload: withId };
+    }
+    const payload = await runOperationJsonQuery(requireProlog(context), "discovery.pl", `discovery:symbol_proof_json(${toPrologAtom(target.id)}, ${query.bindingsGoal}, JsonString)`, "Proof explain");
+    return { view: projectSymbolExplain(payload), payload };
+}

package/dist/operations/proof/impact.d.ts

@@ -0,0 +1,45 @@
+import type { OperationContext } from "../../public/operations/runtime-types.js";
+import { type CoverageRowLike, type RequirementFingerprints, diffFingerprints } from "./baseline-diff.js";
+export declare const COMMITTED_BASELINE_PATH = "proof/baseline.json";
+export type ProofBaselineFile = {
+    readonly version?: string;
+    readonly mode?: string;
+    readonly currentRequirements?: number;
+    readonly proofProven?: number;
+    readonly currentUnproven?: number;
+    readonly trackedGaps?: Record<string, number>;
+    readonly requirements?: RequirementFingerprints;
+};
+export type ProofImpactResult = {
+    readonly comparisonTarget: typeof COMMITTED_BASELINE_PATH;
+    readonly baselineVersion: string;
+    readonly currentRequirements: number;
+    readonly proofProven: number;
+    readonly currentUnproven: number;
+    readonly changes: ReturnType<typeof diffFingerprints>;
+};
+export type ReadCommittedFile = (workspaceRoot: string, relativePath: string) => string | Promise<string>;
+export type ProofImpactExecuteOptions = {
+    readonly readCommittedFile?: ReadCommittedFile;
+    readonly loadCoverage?: (context: OperationContext) => Promise<{
+        structuredContent: unknown;
+    }>;
+};
+export declare function readCommittedHeadFile(workspaceRoot: string, relativePath: string): string;
+export declare function loadCommittedBaseline(workspaceRoot: string, readCommittedFile?: ReadCommittedFile): Promise<ProofBaselineFile>;
+/** Diagnostic only: successful evaluation always exits 0. Ratchet lives in check-proof-baseline.mjs. */
+export declare function proofImpactExitCode(_result: ProofImpactResult): 0;
+export declare function buildProofImpact(baseline: ProofBaselineFile, coverage: {
+    summary?: Record<string, unknown>;
+    rows?: unknown;
+}): {
+    result: ProofImpactResult;
+    rows: CoverageRowLike[];
+};
+export declare function renderProofImpact(result: ProofImpactResult, rows: readonly CoverageRowLike[]): string;
+export declare function executeProofImpact(context: OperationContext, options?: ProofImpactExecuteOptions): Promise<{
+    result: ProofImpactResult;
+    rows: CoverageRowLike[];
+    text: string;
+}>;
+//# sourceMappingURL=impact.d.ts.map

package/dist/operations/proof/impact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"impact.d.ts","sourceRoot":"","sources":["../../../src/operations/proof/impact.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAEjF,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,gBAAgB,EAGjB,MAAM,oBAAoB,CAAC;AAG5B,eAAO,MAAM,uBAAuB,wBAAwB,CAAC;AAE7D,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9C,QAAQ,CAAC,YAAY,CAAC,EAAE,uBAAuB,CAAC;CACjD,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,gBAAgB,EAAE,OAAO,uBAAuB,CAAC;IAC1D,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC;CACvD,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,CAC9B,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,KACjB,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAE9B,MAAM,MAAM,yBAAyB,GAAG;IACtC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IAC/C,QAAQ,CAAC,YAAY,CAAC,EAAE,CACtB,OAAO,EAAE,gBAAgB,KACtB,OAAO,CAAC;QAAE,iBAAiB,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAC9C,CAAC;AAgDF,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,GACnB,MAAM,CAcR;AAGD,wBAAsB,qBAAqB,CACzC,aAAa,EAAE,MAAM,EACrB,iBAAiB,GAAE,iBAAyC,GAC3D,OAAO,CAAC,iBAAiB,CAAC,CAS5B;AAED,wGAAwG;AACxG,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,iBAAiB,GAAG,CAAC,CAEjE;AAGD,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,iBAAiB,EAC3B,QAAQ,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,GAC9D;IAAE,MAAM,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,eAAe,EAAE,CAAA;CAAE,CAuBxD;AAGD,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,iBAAiB,EACzB,IAAI,EAAE,SAAS,eAAe,EAAE,GAC/B,MAAM,CAYR;AAGD,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC;IACT,MAAM,EAAE,iBAAiB,CAAC;IAC1B,IAAI,EAAE,eAAe,EAAE,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC,CAmBD"}