kibi-cli 0.19.0 → 2.0.0

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

@@ -0,0 +1,307 @@
+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 { join } from "node:path";
+import { resolveBoundSymbolScope } from "../../extractors/manifest.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 existingReceipts(test) {
+    return Array.isArray(test.proof_receipts)
+        ? test.proof_receipts.filter(record).map((value) => ({ ...value }))
+        : [];
+}
+// implements REQ-kibi-proof-evidence-protocol
+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);
+        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,CA6ED"}

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

@@ -0,0 +1,88 @@
+/*
+ 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-proof-evidence-protocol
+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);
+        const hasLegacy = Array.isArray(test.verification_receipts);
+        const hasProofContract = test.proof_contract !== null && typeof test.proof_contract === "object";
+        if (!hasLegacy || !hasProofContract)
+            continue;
+        const source = typeof test.source === "string" ? test.source : "";
+        let patchedContent;
+        if (context.fs && source !== "" && /\.(md|mdx)$/i.test(source)) {
+            const absolute = resolveContainedSourcePath(context.workspaceRoot, source);
+            const before = await context.fs.readFile(absolute);
+            patchedContent =
+                removeFrontmatterBlock(before, "verification_receipts") ?? undefined;
+            if (patchedContent === undefined) {
+                throw new Error(`Legacy receipt migration failed for ${testId}: ${source} is not a patchable frontmatter document`);
+            }
+        }
+        else {
+            throw new Error(`Legacy receipt migration failed for ${testId}: test source '${source || "unknown"}' is not an authored markdown document`);
+        }
+        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.
+        const upsertOptions = patchedContent === undefined
+            ? {}
+            : { sourceDocumentOverride: patchedContent };
+        await executeUpsert({
+            type: "test",
+            id: testId,
+            properties: { ...properties },
+        }, context, upsertOptions);
+        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

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

@@ -0,0 +1 @@
+{"version":3,"file":"prune-receipts.d.ts","sourceRoot":"","sources":["../../../src/operations/proof/prune-receipts.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AASjF,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,uDAAuD;IAEvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC,CAAC;AAGH,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAE7C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IAEzC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,SAAS,uBAAuB,EAAE,CAAC;CAC3C,CAAC,CAAC;AAYH;;;;;;;;;GASG;AAEH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,iBAAiB,EACvB,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,mBAAmB,CAAC;CACxC,CAAC,CAoED"}

package/dist/operations/proof/prune-receipts.js

@@ -0,0 +1,91 @@
+/*
+ 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 { proofReceiptHistoryErrors, } from "../../public/proof-receipt.js";
+import { projectEntityProperties } from "../mutation/entity-projection.js";
+import { executeUpsert } from "../mutation/upsert.js";
+function parseKeep(value) {
+    if (value === undefined)
+        return 1;
+    if (!Number.isSafeInteger(value) || value < 1 || value > 50) {
+        throw new Error("Proof prune failed: keep must be an integer between 1 and 50");
+    }
+    return value;
+}
+/**
+ * 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).
+ */
+// implements REQ-kibi-proof-evidence-protocol
+export async function executePruneReceipts(args, context) {
+    if (!context.prolog)
+        throw new Error("Proof prune requires a Prolog runtime");
+    if (context.fs === undefined)
+        throw new Error("Proof prune failed: this maintenance action rewrites authored test documents and requires a filesystem-capable runtime");
+    const keep = parseKeep(args.keep);
+    const tests = await loadEntities(context.prolog, {
+        type: "test",
+        ...(args.testId === undefined ? {} : { id: args.testId }),
+    });
+    if (args.testId !== undefined && tests.length === 0) {
+        throw new Error(`Proof prune failed: test ${args.testId} was not found`);
+    }
+    const results = [];
+    for (const test of tests) {
+        const testId = String(test.id);
+        const receipts = Array.isArray(test.proof_receipts)
+            ? test.proof_receipts.filter((value) => typeof value === "object" &&
+                value !== null &&
+                !Array.isArray(value))
+            : [];
+        if (receipts.length <= keep)
+            continue;
+        const nextReceipts = receipts.slice(-keep);
+        const historyErrors = proofReceiptHistoryErrors(testId, test.verification_scope, nextReceipts);
+        if (historyErrors.length > 0) {
+            throw new Error(`Proof prune failed for ${testId}: pruned history is invalid: ${historyErrors.join("; ")}`);
+        }
+        const properties = projectEntityProperties(test);
+        properties.proof_receipts = undefined;
+        await executeUpsert({
+            type: "test",
+            id: testId,
+            properties: { ...properties, proof_receipts: nextReceipts },
+        }, context, { allowReceiptsPrune: true });
+        results.push({
+            testId,
+            before: receipts.length,
+            after: nextReceipts.length,
+            pruned: receipts.length - nextReceipts.length,
+        });
+    }
+    const pruned = results.reduce((sum, row) => sum + row.pruned, 0);
+    const summary = results.length === 0
+        ? "No test had receipts beyond the keep window."
+        : `Pruned ${pruned} receipt(s) across ${results.length} test(s).`;
+    return {
+        content: [{ type: "text", text: `Proof receipts pruned. ${summary}` }],
+        structuredContent: { pruned, tests: results },
+    };
+}

package/dist/operations/proof/receipt-document.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Remove a top-level frontmatter block (`key:` plus its nested lines) from a
+ * markdown document, leaving every other byte untouched. Returns the patched
+ * content, or null when the content is not a well-formed frontmatter
+ * document the remover can safely splice.
+ *
+ * Used by proof maintenance to drop legacy `verification_receipts` blocks
+ * once a `proof_contract` exists, without canonicalizing the document.
+ */
+export declare function removeFrontmatterBlock(content: string, key: string): string | null;
+/**
+ * Patch the `proof_receipts` frontmatter block of an authored test document
+ * without re-rendering anything else.
+ *
+ * Receipt ingest used to route every append through the canonical entity
+ * renderer, which re-dumps the whole frontmatter: inline tag lists became
+ * block lists, timestamps gained milliseconds, and so on. Those non-receipt
+ * edits are not stripped by the workspace snapshotter, so the snapshot hash
+ * changed on the first ingest that touched a hand-authored document and every
+ * later integration in the same `kibi prove --all` run refused with
+ * "changed the tracked workspace". This patcher splices ONLY the receipts
+ * block, leaving the rest of the document byte-for-byte identical.
+ *
+ * Returns null when the content is not a well-formed frontmatter document the
+ * patcher can safely splice; the caller then falls back to the canonical
+ * render.
+ */
+export declare function patchReceiptsIntoDocument(content: string, receipts: readonly Readonly<Record<string, unknown>>[]): string | null;
+//# sourceMappingURL=receipt-document.d.ts.map

package/dist/operations/proof/receipt-document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipt-document.d.ts","sourceRoot":"","sources":["../../../src/operations/proof/receipt-document.ts"],"names":[],"mappings":"AAoBA;;;;;;;;GAQG;AAEH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,GACV,MAAM,GAAG,IAAI,CA4Bf;AAED;;;;;;;;;;;;;;;;GAgBG;AAEH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,GACrD,MAAM,GAAG,IAAI,CAyCf"}