kibi-cli 1.0.1 → 2.1.0

package/dist/operations/proof/impact.js

@@ -0,0 +1,118 @@
+/*
+ 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 { execFileSync } from "node:child_process";
+import { executeCoverage } from "../../public/operations/specs/reporting.js";
+import { diffFingerprints, fingerprintRequirements, renderRequirementDiffs, } from "./baseline-diff.js";
+// implements REQ-kibi-verification-evidence-contract
+export const COMMITTED_BASELINE_PATH = "proof/baseline.json";
+function asNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+function gitErrorText(error) {
+    if (error && typeof error === "object" && "stderr" in error) {
+        const stderr = error.stderr;
+        if (typeof stderr === "string" && stderr.trim() !== "")
+            return stderr;
+        if (Buffer.isBuffer(stderr) && stderr.length > 0) {
+            return stderr.toString("utf8");
+        }
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+function committedBaselineReadError(relativePath, error) {
+    const text = gitErrorText(error);
+    if (/not a git repository/i.test(text) ||
+        /ambiguous argument 'HEAD'/i.test(text) ||
+        /unknown revision/i.test(text) ||
+        /needed a single revision/i.test(text) ||
+        /bad revision 'HEAD'/i.test(text)) {
+        return new Error(`proof impact: repository is not in a suitable Git state to read HEAD:${relativePath}`);
+    }
+    if (/does not exist in 'HEAD'/i.test(text) ||
+        /exists on disk, but not in 'HEAD'/i.test(text) ||
+        /path '.*' does not exist/i.test(text)) {
+        return new Error(`proof impact: HEAD:${relativePath} is missing or unreadable`);
+    }
+    return new Error(`proof impact: could not read HEAD:${relativePath}: ${text.trim()}`);
+}
+// implements REQ-kibi-verification-evidence-contract
+export function readCommittedHeadFile(workspaceRoot, relativePath) {
+    try {
+        return execFileSync("git", ["-C", workspaceRoot, "show", `HEAD:${relativePath}`], {
+            encoding: "utf8",
+            maxBuffer: 64 * 1024 * 1024,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+    }
+    catch (error) {
+        throw committedBaselineReadError(relativePath, error);
+    }
+}
+// implements REQ-kibi-verification-evidence-contract
+export async function loadCommittedBaseline(workspaceRoot, readCommittedFile = readCommittedHeadFile) {
+    const raw = await readCommittedFile(workspaceRoot, COMMITTED_BASELINE_PATH);
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`proof impact: HEAD:${COMMITTED_BASELINE_PATH} is not valid JSON`);
+    }
+}
+/** Diagnostic only: successful evaluation always exits 0. Ratchet lives in check-proof-baseline.mjs. */
+export function proofImpactExitCode(_result) {
+    return 0;
+}
+// implements REQ-kibi-verification-evidence-contract
+export function buildProofImpact(baseline, coverage) {
+    const rows = Array.isArray(coverage.rows)
+        ? coverage.rows
+        : [];
+    const summary = coverage.summary ?? {};
+    const proofNotApplicable = asNumber(summary.proofNotApplicable);
+    const total = asNumber(summary.total);
+    const proofProven = asNumber(summary.proofProven);
+    const currentUnproven = asNumber(summary.proofMissing) + asNumber(summary.proofUnresolved);
+    const current = fingerprintRequirements(rows);
+    const changes = diffFingerprints(baseline.requirements, current);
+    return {
+        rows,
+        result: {
+            comparisonTarget: COMMITTED_BASELINE_PATH,
+            baselineVersion: baseline.version ?? "unknown",
+            currentRequirements: total - proofNotApplicable,
+            proofProven,
+            currentUnproven,
+            changes,
+        },
+    };
+}
+// implements REQ-kibi-verification-evidence-contract
+export function renderProofImpact(result, rows) {
+    const header = [
+        `Proof impact compared to committed ${result.comparisonTarget}`,
+        `baseline version: ${result.baselineVersion}`,
+        `current requirements: ${result.currentRequirements}`,
+        `proofProven: ${result.proofProven}`,
+        `currentUnproven: ${result.currentUnproven}`,
+        `changed requirements: ${result.changes.length}`,
+        "",
+    ];
+    const diff = renderRequirementDiffs(result.changes, rows);
+    return `${header.join("\n")}${diff || "No requirement fingerprint changes versus the committed baseline.\n"}`;
+}
+// implements REQ-kibi-verification-evidence-contract
+export async function executeProofImpact(context, options = {}) {
+    const baseline = await loadCommittedBaseline(context.workspaceRoot, options.readCommittedFile ?? readCommittedHeadFile);
+    const coverage = options.loadCoverage
+        ? await options.loadCoverage(context)
+        : await executeCoverage({ by: "req", includePassing: true, limit: 100_000, offset: 0 }, context);
+    const { result, rows } = buildProofImpact(baseline, coverage.structuredContent);
+    return { result, rows, text: renderProofImpact(result, rows) };
+}

package/dist/operations/proof/ingest-proof.d.ts

@@ -0,0 +1,34 @@
+import { type ProofGap } from "../../proof/evaluate.js";
+import type { OperationContext } from "../../public/operations/runtime-types.js";
+import { type ProofReceipt } from "../../public/proof-receipt.js";
+export type IngestProofArgs = Readonly<{
+    snapshot: string;
+    artifact: Readonly<Record<string, unknown>>;
+    testIds?: readonly string[];
+}>;
+export type IngestProofTestResult = Readonly<{
+    testId: string;
+    outcome: ProofReceipt["outcome"];
+    receiptId: string;
+    applied: boolean;
+    duplicate: boolean;
+    receiptCount: number;
+    gaps: readonly ProofGap[];
+}>;
+export type IngestProofResult = Readonly<{
+    artifactDigest: string;
+    environmentHash: string;
+    integration: string | null;
+    passed: number;
+    failed: number;
+    unchanged: number;
+    results: readonly IngestProofTestResult[];
+}>;
+export declare function executeIngestProof(args: IngestProofArgs, context: OperationContext): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    structuredContent: IngestProofResult;
+}>;
+//# sourceMappingURL=ingest-proof.d.ts.map

package/dist/operations/proof/ingest-proof.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest-proof.d.ts","sourceRoot":"","sources":["../../../src/operations/proof/ingest-proof.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,QAAQ,EAEd,MAAM,yBAAyB,CAAC;AAOjC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAkBjF,OAAO,EAEL,KAAK,YAAY,EAGlB,MAAM,+BAA+B,CAAC;AAUvC,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC5C,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B,CAAC,CAAC;AAEH,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,SAAS,QAAQ,EAAE,CAAC;CAC3B,CAAC,CAAC;AAGH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,SAAS,qBAAqB,EAAE,CAAC;CAC3C,CAAC,CAAC;AAoKH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC;IACT,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,iBAAiB,EAAE,iBAAiB,CAAC;CACtC,CAAC,CAgSD"}

package/dist/operations/proof/ingest-proof.js

@@ -0,0 +1,348 @@
+import { join } from "node:path";
+import { resolveBoundSymbolScope } from "../../extractors/manifest.js";
+import { evaluateContractAgainstRun, } from "../../proof/evaluate.js";
+import { loadProofIntegrations, resolveIntegration, toExecution, } from "../../proof/integrations.js";
+import { loadEntities } from "../../public/operations/discovery-entities.js";
+import { readWorkspaceSnapshot } from "../../public/operations/workspace-snapshot.js";
+import { environmentHash as canonicalEnvironmentHash, effectiveProofFingerprint, jsonDigest, proofContractHash, receiptBindingHash, } from "../../public/proof-fingerprint.js";
+import { PROOF_CONTRACT_VERSION, PROOF_RECEIPT_VERSION, proofBindingsErrors, proofRunArtifactErrors, } from "../../public/proof-protocol.js";
+import { MAX_PROOF_RECEIPTS, proofReceiptCurrentBindingErrors, proofReceiptHistoryErrors, } from "../../public/proof-receipt.js";
+import { projectEntityProperties } from "../mutation/entity-projection.js";
+import { resolveContainedSourcePath } from "../mutation/source-authoring.js";
+import { executeUpsert } from "../mutation/upsert.js";
+import { patchReceiptsIntoDocument, removeFrontmatterBlock, } from "./receipt-document.js";
+function text(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function requiredString(value, label) {
+    const result = text(value);
+    if (!result)
+        throw new Error(`Proof ingest failed: ${label} must be non-empty`);
+    return result;
+}
+function parseContract(test) {
+    const contract = record(test.proof_contract);
+    const candidate = contract ?? {};
+    const { version, integration, required_proofs, success_policy } = candidate;
+    const normalized = {
+        version: version,
+        integration: String(integration ?? ""),
+        required_proofs: Array.isArray(required_proofs)
+            ? required_proofs.map((entry) => {
+                const row = record(entry);
+                return {
+                    symbol_id: String(row?.symbol_id ?? ""),
+                    target: String(row?.target ?? ""),
+                };
+            })
+            : [],
+        success_policy: success_policy,
+    };
+    if (!contract || contract.version !== PROOF_CONTRACT_VERSION)
+        throw new Error(`Proof ingest failed: test ${String(test.id)} has no proof_contract (${PROOF_CONTRACT_VERSION})`);
+    return normalized;
+}
+function parseBindings(test) {
+    const raw = test.proof_bindings;
+    if (raw === undefined || raw === null)
+        return [];
+    if (!Array.isArray(raw))
+        throw new Error(`Proof ingest failed: test ${String(test.id)} proof_bindings must be an array`);
+    const errors = proofBindingsErrors(raw);
+    if (errors.length > 0)
+        throw new Error(`Proof ingest failed: test ${String(test.id)} ${errors.join("; ")}`);
+    return raw.map((entry) => {
+        const row = record(entry) ?? {};
+        return {
+            symbol_id: String(row.symbol_id ?? ""),
+            target: String(row.target ?? ""),
+            ...(row.native_id !== undefined
+                ? { native_id: String(row.native_id) }
+                : {}),
+            ...(row.aliases !== undefined
+                ? { aliases: row.aliases.map(String) }
+                : {}),
+            ...(row.source_file !== undefined
+                ? { source_file: String(row.source_file) }
+                : {}),
+            ...(row.line !== undefined ? { line: Number(row.line) } : {}),
+        };
+    });
+}
+function enforceNativeCaseBindings(testId, contract, bindings, artifact) {
+    const requiredKeys = new Set(contract.required_proofs.map((obligation) => `${obligation.target}\0${obligation.symbol_id}`));
+    const nativeResults = artifact.proof_results.filter((result) => result.binding === "native_case" &&
+        requiredKeys.has(`${result.target}\0${result.symbol_id}`));
+    const seenNativeIds = new Set();
+    for (const result of nativeResults) {
+        const nativeId = typeof result.native_id === "string" ? result.native_id : "";
+        const resultLabel = `${result.symbol_id}/${result.target}`;
+        if (!nativeId) {
+            throw new Error(`Proof ingest failed: test ${testId} native_case result ${resultLabel} has no native_id`);
+        }
+        if (seenNativeIds.has(nativeId)) {
+            throw new Error(`Proof ingest failed: test ${testId} duplicate native result for native_id '${nativeId}'`);
+        }
+        seenNativeIds.add(nativeId);
+        const matchingBindings = bindings.filter((binding) => binding.symbol_id === result.symbol_id &&
+            binding.target === result.target);
+        if (matchingBindings.length === 0) {
+            throw new Error(`Proof ingest failed: test ${testId} native_case result ${resultLabel} has no matching proof_binding`);
+        }
+        if (matchingBindings.length !== 1) {
+            throw new Error(`Proof ingest failed: test ${testId} native_case result ${resultLabel} has an ambiguous proof_binding`);
+        }
+        const binding = matchingBindings[0];
+        if (binding === undefined) {
+            throw new Error(`Proof ingest failed: test ${testId} native_case result ${resultLabel} has an ambiguous proof_binding`);
+        }
+        const boundNativeIds = [
+            binding.native_id,
+            ...(binding.aliases ?? []),
+        ].filter((value) => typeof value === "string" && value !== "");
+        if (!boundNativeIds.includes(nativeId)) {
+            throw new Error(`Proof ingest failed: test ${testId} native_case result ${resultLabel} native_id '${nativeId}' does not match its proof_binding native_id or aliases`);
+        }
+        const ambiguousOwners = bindings.filter((candidate) => [candidate.native_id, ...(candidate.aliases ?? [])].includes(nativeId));
+        if (ambiguousOwners.length !== 1) {
+            throw new Error(`Proof ingest failed: test ${testId} native_id '${nativeId}' has an ambiguous proof_binding`);
+        }
+    }
+}
+function existingReceipts(test) {
+    return Array.isArray(test.proof_receipts)
+        ? test.proof_receipts.filter(record).map((value) => ({ ...value }))
+        : [];
+}
+// implements REQ-kibi-verification-evidence-contract
+export async function executeIngestProof(args, context) {
+    if (!context.prolog)
+        throw new Error("Proof ingest requires a Prolog runtime");
+    const snapshot = requiredString(args.snapshot, "snapshot");
+    const artifactValue = record(args.artifact);
+    if (!artifactValue)
+        throw new Error("Proof ingest failed: artifact must be a kibi.proof-run.v1 object with version, producer, command_argv, code_snapshot, environment, run, and proof_results");
+    // One generic pipeline: validate, bind, fingerprint, evaluate, derive, apply.
+    const artifactErrors = proofRunArtifactErrors(artifactValue);
+    if (artifactErrors.length > 0)
+        throw new Error(`Proof ingest failed: ${artifactErrors.join("; ")}`);
+    const artifact = artifactValue;
+    const workspace = await readWorkspaceSnapshot(context);
+    if (!workspace.available)
+        throw new Error(`Proof ingest failed: ${workspace.error}`);
+    if (workspace.snapshot.hash !== snapshot)
+        throw new Error("Proof ingest failed: captured snapshot is not the live workspace snapshot");
+    if (artifact.code_snapshot !== snapshot)
+        throw new Error("Proof ingest failed: artifact code_snapshot does not match captured snapshot");
+    const requestedTestIds = args.testIds?.map((id) => requiredString(id, "testIds")) ?? [];
+    if (new Set(requestedTestIds).size !== requestedTestIds.length)
+        throw new Error("Proof ingest failed: testIds contains duplicates");
+    if (requestedTestIds.length === 0 && text(artifact.integration) === "")
+        throw new Error("Proof ingest failed: provide testIds, or set artifact.integration to select the contracted tests this artifact is evaluated against");
+    const integrationId = text(artifact.integration) || null;
+    const integrations = loadProofIntegrations(context.workspaceRoot);
+    if (!integrations.available)
+        throw new Error(`Proof ingest failed: ${integrations.error}`);
+    const tests = [];
+    if (requestedTestIds.length > 0) {
+        for (const testId of requestedTestIds) {
+            const found = await loadEntities(context.prolog, {
+                id: testId,
+                type: "test",
+            });
+            const test = found[0];
+            if (!test)
+                throw new Error(`Proof ingest failed: test ${testId} was not found`);
+            tests.push(test);
+        }
+    }
+    else {
+        const all = await loadEntities(context.prolog, { type: "test" });
+        for (const test of all) {
+            const contract = record(test.proof_contract);
+            if (contract &&
+                contract.version === PROOF_CONTRACT_VERSION &&
+                text(contract.integration) === integrationId) {
+                tests.push(test);
+            }
+        }
+        if (tests.length === 0)
+            throw new Error(`Proof ingest failed: no tests declare proof_contract.integration '${integrationId}'`);
+    }
+    const prepared = [];
+    for (const test of tests) {
+        const testId = String(test.id);
+        const contract = parseContract(test);
+        if (integrationId !== null && contract.integration !== integrationId)
+            throw new Error(`Proof ingest failed: test ${testId} binds integration '${contract.integration}' but the artifact was produced by '${integrationId}'`);
+        const effectiveIntegrationId = integrationId ?? contract.integration;
+        const integration = resolveIntegration(integrations.integrations, effectiveIntegrationId);
+        if (!integration)
+            throw new Error(`Proof ingest failed: integration '${effectiveIntegrationId}' is not configured in .kb/proof/integrations.json`);
+        if (jsonDigest(artifact.command_argv) !== jsonDigest([...integration.command]))
+            throw new Error(`Proof ingest failed: artifact command_argv does not match the configured command for integration '${effectiveIntegrationId}'`);
+        const bindings = parseBindings(test);
+        enforceNativeCaseBindings(testId, contract, bindings, artifact);
+        const { fingerprint, components } = effectiveProofFingerprint({
+            contract,
+            integration: toExecution(integration),
+            bindings,
+        });
+        const evaluation = evaluateContractAgainstRun(artifact, contract);
+        const environmentHash = canonicalEnvironmentHash(artifact.environment);
+        const artifactDigest = jsonDigest(artifact);
+        // Per-contract receipt binding (W2): hash the receipt-stripped authored
+        // document, the contract, and the bound symbols' source hashes so the
+        // receipt survives unrelated workspace changes and stales only when its
+        // own inputs (contract, document, production code scope) change.
+        let bindingHash;
+        const source = typeof test.source === "string" ? test.source : "";
+        if (context.fs && source !== "" && /\.(md|mdx)$/i.test(source)) {
+            try {
+                const absolute = resolveContainedSourcePath(context.workspaceRoot, source);
+                const authored = await context.fs.readFile(absolute);
+                const stripped = removeFrontmatterBlock(authored, "proof_receipts");
+                const codeScope = resolveBoundSymbolScope(join(context.workspaceRoot, ".kb", "symbols.yaml"), bindings.map((binding) => binding.symbol_id));
+                bindingHash = receiptBindingHash(contract, stripped ?? authored, codeScope);
+            }
+            catch {
+                bindingHash = undefined;
+            }
+        }
+        const receipt = {
+            version: PROOF_RECEIPT_VERSION,
+            receipt_id: `PR-${jsonDigest({
+                artifact_digest: artifactDigest,
+                test_id: testId,
+                fingerprint,
+            }).slice(0, 24)}`,
+            test_id: testId,
+            scope: (text(test.verification_scope) ||
+                "end_to_end"),
+            outcome: evaluation.outcome,
+            code_snapshot: snapshot,
+            environment_hash: environmentHash,
+            started_at: artifact.run.started_at,
+            finished_at: artifact.run.finished_at,
+            artifact_digest: artifactDigest,
+            contract_hash: proofContractHash(contract),
+            ...(bindingHash !== undefined ? { binding_hash: bindingHash } : {}),
+            fingerprint,
+            fingerprint_components: components,
+            integration_id: effectiveIntegrationId,
+            producer: artifact.producer,
+            command_argv: [...artifact.command_argv],
+            run_outcome: artifact.run.outcome,
+            proof_results: evaluation.projectedResults.map((result) => ({
+                ...result,
+            })),
+            ...(evaluation.gaps.length > 0 ? { gaps: evaluation.gaps } : {}),
+        };
+        prepared.push({
+            testId,
+            test,
+            contract,
+            evaluation,
+            receipt,
+            existing: existingReceipts(test),
+        });
+    }
+    const results = [];
+    let passed = 0;
+    let failed = 0;
+    let unchanged = 0;
+    for (const entry of prepared) {
+        const { testId, test, contract, evaluation, receipt, existing } = entry;
+        // Idempotent re-ingestion: the same artifact against the same effective
+        // contract+fingerprint derives the same receipt id and must not re-append.
+        if (existing.some((row) => row.receipt_id === receipt.receipt_id)) {
+            unchanged += 1;
+            if (receipt.outcome === "passed")
+                passed += 1;
+            else
+                failed += 1;
+            results.push({
+                testId,
+                outcome: receipt.outcome,
+                receiptId: receipt.receipt_id,
+                applied: false,
+                duplicate: true,
+                receiptCount: existing.length,
+                gaps: evaluation.gaps,
+            });
+            continue;
+        }
+        const nextReceipts = [
+            ...existing,
+            receipt,
+        ].slice(-MAX_PROOF_RECEIPTS);
+        const historyErrors = proofReceiptHistoryErrors(testId, test.verification_scope, nextReceipts);
+        const bindingErrors = proofReceiptCurrentBindingErrors(testId, test.verification_scope, receipt, contract, receipt.fingerprint);
+        const receiptErrors = [...historyErrors, ...bindingErrors];
+        if (receiptErrors.length > 0)
+            throw new Error(`Proof ingest failed for ${testId}: ${receiptErrors.join("; ")}`);
+        const properties = projectEntityProperties(test);
+        properties.proof_receipts = undefined;
+        // Surgical receipt append: splice only the proof_receipts block into the
+        // authored document so unrelated frontmatter keeps its authored form.
+        // Canonical re-rendering here would change non-receipt bytes, shift the
+        // workspace snapshot hash mid-campaign, and make later integrations in
+        // the same `kibi prove --all` refuse with "changed the tracked
+        // workspace". Falls back to the canonical render when the document is
+        // not a patchable markdown file.
+        let sourceDocumentOverride;
+        const source = typeof test.source === "string" ? test.source : "";
+        if (context.fs && source !== "" && /\.(md|mdx)$/i.test(source)) {
+            try {
+                const absolute = resolveContainedSourcePath(context.workspaceRoot, source);
+                const before = await context.fs.readFile(absolute);
+                sourceDocumentOverride =
+                    patchReceiptsIntoDocument(before, nextReceipts) ?? undefined;
+            }
+            catch {
+                sourceDocumentOverride = undefined;
+            }
+        }
+        // exactOptionalPropertyTypes: only pass the override when one exists.
+        const upsertOptions = sourceDocumentOverride === undefined ? {} : { sourceDocumentOverride };
+        const upsert = await executeUpsert({
+            type: "test",
+            id: testId,
+            properties: { ...properties, proof_receipts: nextReceipts },
+        }, context, upsertOptions);
+        void upsert;
+        if (receipt.outcome === "passed")
+            passed += 1;
+        else
+            failed += 1;
+        results.push({
+            testId,
+            outcome: receipt.outcome,
+            receiptId: receipt.receipt_id,
+            applied: true,
+            duplicate: false,
+            receiptCount: nextReceipts.length,
+            gaps: evaluation.gaps,
+        });
+    }
+    const summary = passed > 0
+        ? `Proved ${passed} test(s)${failed > 0 ? `, ${failed} failed` : ""}${unchanged > 0 ? `, ${unchanged} unchanged` : ""}.`
+        : `No passing proof: ${failed} failed, ${unchanged} unchanged.`;
+    return {
+        content: [{ type: "text", text: `Ingested proof evidence. ${summary}` }],
+        structuredContent: {
+            artifactDigest: jsonDigest(artifact),
+            environmentHash: canonicalEnvironmentHash(artifact.environment),
+            integration: integrationId,
+            passed,
+            failed,
+            unchanged,
+            results,
+        },
+    };
+}

package/dist/operations/proof/migrate-legacy-receipts.d.ts

@@ -0,0 +1,30 @@
+import type { OperationContext } from "../../public/operations/runtime-types.js";
+export type MigrateLegacyReceiptsArgs = Readonly<{
+    /** Migrate a single test entity only. */
+    testId?: string;
+}>;
+export type MigrateLegacyReceiptsResult = Readonly<{
+    migrated: number;
+    tests: readonly {
+        readonly testId: string;
+    }[];
+}>;
+/**
+ * Drop legacy `verification_receipts` frontmatter blocks from test documents
+ * that already carry a `proof_contract`.
+ *
+ * The proof architecture replaced verification evidence with proof
+ * contracts/receipts, but hand-migrated workspaces kept the old blocks (with
+ * stale snapshot hashes) in ~dozens of test files, making live-receipt
+ * greps error-prone. This maintenance action strips the legacy block from
+ * the authored document and the compiled entity — one block splice, no
+ * canonical re-render.
+ */
+export declare function executeMigrateLegacyReceipts(args: MigrateLegacyReceiptsArgs, context: OperationContext): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    structuredContent: MigrateLegacyReceiptsResult;
+}>;
+//# sourceMappingURL=migrate-legacy-receipts.d.ts.map

package/dist/operations/proof/migrate-legacy-receipts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate-legacy-receipts.d.ts","sourceRoot":"","sources":["../../../src/operations/proof/migrate-legacy-receipts.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAOjF,MAAM,MAAM,yBAAyB,GAAG,QAAQ,CAAC;IAC/C,yCAAyC;IAEzC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC,CAAC;AAGH,MAAM,MAAM,2BAA2B,GAAG,QAAQ,CAAC;IAEjD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,SAAS;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC/C,CAAC,CAAC;AAEH;;;;;;;;;;GAUG;AAEH,wBAAsB,4BAA4B,CAChD,IAAI,EAAE,yBAAyB,EAC/B,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC;IACT,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,iBAAiB,EAAE,2BAA2B,CAAC;CAChD,CAAC,CAkFD"}

package/dist/operations/proof/migrate-legacy-receipts.js

@@ -0,0 +1,92 @@
+/*
+ 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.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+import { loadEntities } from "../../public/operations/discovery-entities.js";
+import { projectEntityProperties } from "../mutation/entity-projection.js";
+import { resolveContainedSourcePath } from "../mutation/source-authoring.js";
+import { executeUpsert } from "../mutation/upsert.js";
+import { removeFrontmatterBlock } from "./receipt-document.js";
+/**
+ * Drop legacy `verification_receipts` frontmatter blocks from test documents
+ * that already carry a `proof_contract`.
+ *
+ * The proof architecture replaced verification evidence with proof
+ * contracts/receipts, but hand-migrated workspaces kept the old blocks (with
+ * stale snapshot hashes) in ~dozens of test files, making live-receipt
+ * greps error-prone. This maintenance action strips the legacy block from
+ * the authored document and the compiled entity — one block splice, no
+ * canonical re-render.
+ */
+// implements REQ-kibi-verification-evidence-contract
+export async function executeMigrateLegacyReceipts(args, context) {
+    if (!context.prolog)
+        throw new Error("Legacy receipt migration requires a Prolog runtime");
+    if (context.fs === undefined)
+        throw new Error("Legacy receipt migration failed: this maintenance action rewrites authored test documents and requires a filesystem-capable runtime");
+    const tests = await loadEntities(context.prolog, {
+        type: "test",
+        ...(args.testId === undefined ? {} : { id: args.testId }),
+    });
+    if (args.testId !== undefined && tests.length === 0) {
+        throw new Error(`Legacy receipt migration failed: test ${args.testId} was not found`);
+    }
+    const migratedTests = [];
+    for (const test of tests) {
+        const testId = String(test.id);
+        // The compiled lane only survives in stores compiled by older versions:
+        // current sync does not extract verification_receipts, so the authored
+        // document is the durable carrier of the legacy block. Both signals must
+        // trigger the migration.
+        const hasCompiledLegacy = Array.isArray(test.verification_receipts);
+        const hasProofContract = test.proof_contract !== null && typeof test.proof_contract === "object";
+        if (!hasProofContract)
+            continue;
+        const source = typeof test.source === "string" ? test.source : "";
+        const patchableSource = source !== "" && /\.(md|mdx)$/i.test(source) && context.fs !== undefined;
+        if (!patchableSource) {
+            if (hasCompiledLegacy) {
+                throw new Error(`Legacy receipt migration failed for ${testId}: test source '${source || "unknown"}' is not an authored markdown document`);
+            }
+            continue;
+        }
+        const absolute = resolveContainedSourcePath(context.workspaceRoot, source);
+        const before = await context.fs.readFile(absolute);
+        const patchedContent = removeFrontmatterBlock(before, "verification_receipts");
+        if (patchedContent === null) {
+            if (hasCompiledLegacy) {
+                throw new Error(`Legacy receipt migration failed for ${testId}: ${source} is not a patchable frontmatter document`);
+            }
+            continue;
+        }
+        const properties = Object.fromEntries(Object.entries(projectEntityProperties(test)).filter(([key]) => key !== "verification_receipts"));
+        // Drop the legacy lane from the compiled entity; proof_receipts stay
+        // untouched so append-only validation keeps holding.
+        await executeUpsert({
+            type: "test",
+            id: testId,
+            properties: { ...properties },
+        }, context, { sourceDocumentOverride: patchedContent });
+        migratedTests.push({ testId });
+    }
+    const summary = migratedTests.length === 0
+        ? "No test carries a legacy verification_receipts block alongside a proof_contract."
+        : `Removed legacy verification_receipts from ${migratedTests.length} test(s).`;
+    return {
+        content: [{ type: "text", text: `Legacy receipts migrated. ${summary}` }],
+        structuredContent: { migrated: migratedTests.length, tests: migratedTests },
+    };
+}

package/dist/operations/proof/prune-receipts.d.ts

@@ -0,0 +1,35 @@
+import type { OperationContext } from "../../public/operations/runtime-types.js";
+export type PruneReceiptsArgs = Readonly<{
+    /** Keep the newest N receipts per test (default 1). */
+    keep?: number;
+    /** Prune a single test entity only. */
+    testId?: string;
+}>;
+export type PruneReceiptsTestResult = Readonly<{
+    testId: string;
+    before: number;
+    after: number;
+    pruned: number;
+}>;
+export type PruneReceiptsResult = Readonly<{
+    pruned: number;
+    tests: readonly PruneReceiptsTestResult[];
+}>;
+/**
+ * Shrink each test's proof_receipts history to its newest entries.
+ *
+ * Re-proving the same snapshot appends duplicate passed receipts (one block
+ * per run), and consumers previously deduped them by hand. This is the one
+ * sanctioned history-shrinking mutation: pruned histories are still ordered,
+ * structurally valid evidence, and every shrink goes through the typed upsert
+ * with the prune carve-out (append-only validation is skipped for exactly
+ * this maintenance action).
+ */
+export declare function executePruneReceipts(args: PruneReceiptsArgs, context: OperationContext): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    structuredContent: PruneReceiptsResult;
+}>;
+//# sourceMappingURL=prune-receipts.d.ts.map