kibi-cli 0.19.0 → 2.0.0

package/dist/prolog/store-lock.js

@@ -0,0 +1,195 @@
+/*
+ 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 { existsSync, rmSync } from "node:fs";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { escapeAtom } from "./codec.js";
+/**
+ * Stewardship for the branch-store lock.
+ *
+ * rdf_persistency holds the store lock while an engine is attached, and the
+ * ownership journal written by kb.pl records who the holder is. This module
+ * classifies a recorded holder (alive, dead, unknown) and breaks the lock
+ * only when the holder is provably dead — a crash, a kill, or a removed
+ * worktree then self-heals on the next attach instead of wedging the store
+ * behind an opaque "Access denied or KB locked".
+ */
+// implements REQ-core-journaled-engine-persistence
+let cachedBootId;
+/** Linux boot id; guards against PID reuse across reboots. Null elsewhere. */
+export function currentBootId() {
+    if (cachedBootId !== undefined)
+        return cachedBootId;
+    if (process.platform !== "linux") {
+        cachedBootId = null;
+        return cachedBootId;
+    }
+    try {
+        const raw = readFileSync("/proc/sys/kernel/random/boot_id", "utf8");
+        cachedBootId = raw.trim();
+    }
+    catch {
+        cachedBootId = null;
+    }
+    return cachedBootId;
+}
+export function isProcessAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        const code = error?.code;
+        // EPERM means the process exists but is owned by another user.
+        return code === "EPERM";
+    }
+}
+export function classifyStoreLockHolder(owner) {
+    if (owner === null || typeof owner.pid !== "number")
+        return "unknown";
+    if (owner.pid === process.pid)
+        return "self";
+    const alive = isProcessAlive(owner.pid);
+    if (!alive)
+        return "dead";
+    const bootId = currentBootId();
+    // A recorded boot id that differs from ours means the holder ran before a
+    // reboot: the PID cannot be trusted as a sign of life.
+    if (bootId !== null && owner.bootId !== undefined && owner.bootId !== "") {
+        return owner.bootId === bootId ? "alive" : "dead";
+    }
+    return "alive";
+}
+/**
+ * Read an ownership journal from a branch store. Older builds kept the
+ * journal beside the rdf lock; the store-root location wins when both exist.
+ * Shared by the janitor sweep and the status stale-reason surfacing so both
+ * classify the same evidence with the same boot-id-aware semantics.
+ */
+// implements REQ-core-journaled-engine-persistence
+export function readStoreLockOwner(storePath) {
+    const candidates = [
+        join(storePath, ".kibi-lock-owner.json"),
+        join(storePath, "rdf", ".kibi-lock-owner.json"),
+    ];
+    for (const journalPath of candidates) {
+        if (!existsSync(journalPath))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(journalPath, "utf8"));
+        }
+        catch {
+            continue;
+        }
+        if (parsed === null || typeof parsed !== "object")
+            continue;
+        const record = parsed;
+        const owner = {
+            ...(typeof record.pid === "number" ? { pid: record.pid } : {}),
+            ...(typeof record.workspaceRoot === "string"
+                ? { workspaceRoot: record.workspaceRoot }
+                : {}),
+            ...(typeof record.bootId === "string" ? { bootId: record.bootId } : {}),
+            ...(typeof record.startedAt === "string"
+                ? { startedAt: record.startedAt }
+                : {}),
+        };
+        return { owner, journalPath };
+    }
+    return null;
+}
+/**
+ * Remove the stale lock artifacts so a fresh attach can take the store.
+ * The rdf lock lives inside the persistency directory; the ownership journal
+ * lives at the branch-store root (older builds kept it beside the lock).
+ */
+export function breakStoreLock(rdfDirectory) {
+    const candidates = [
+        join(rdfDirectory, "lock"),
+        join(rdfDirectory, ".kibi-lock-owner.json"),
+        join(dirname(rdfDirectory), ".kibi-lock-owner.json"),
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(candidate)) {
+            rmSync(candidate, { force: true });
+        }
+    }
+}
+/**
+ * Decide whether a store-locked failure may be auto-healed. Only a provably
+ * dead holder (or a holder from a previous boot) is broken; live or unknown
+ * holders are surfaced so the operator can close the real session.
+ */
+export function decideStoreLockTakeover(owner) {
+    const state = classifyStoreLockHolder(owner);
+    switch (state) {
+        case "dead":
+            return {
+                action: "break",
+                reason: `recorded holder pid ${owner?.pid ?? "?"} is no longer running`,
+            };
+        case "unknown":
+            return {
+                action: "surface",
+                reason: "no ownership journal; the holder cannot be verified",
+            };
+        case "self":
+        case "alive":
+            return {
+                action: "surface",
+                reason: `holder pid ${owner?.pid ?? "?"} is still running${owner?.workspaceRoot !== undefined ? ` for ${owner.workspaceRoot}` : ""}`,
+            };
+    }
+}
+/**
+ * A store-locked attach failure with a provably dead holder (crashed or
+ * killed engine, removed worktree) is safe to auto-heal: break the stale
+ * lock artifacts and retry once on the same port. Live or unverifiable
+ * holders are surfaced with the holder identity and remediation. Shared by
+ * the CLI runtime and the engine daemon attach paths.
+ */
+// implements REQ-core-journaled-engine-persistence
+export async function retryAttachAfterBreakingStaleLock(prolog, kbPath, failed) {
+    const record = failed.errorRecord;
+    const storeLocked = record?.storeLocked;
+    if (storeLocked === undefined)
+        return failed;
+    const decision = decideStoreLockTakeover(storeLocked.owner);
+    if (decision.action !== "break") {
+        const holderSummary = storeLocked.owner === null
+            ? decision.reason
+            : `pid ${storeLocked.owner.pid ?? "?"} (${decision.reason})`;
+        return {
+            ...failed,
+            error: `${failed.error}
+Store lock holder: ${holderSummary}. Close that session, or run 'kibi engine stop' for its workspace, then retry.`,
+        };
+    }
+    const lockDirectory = storeLocked.lockDirectory !== ""
+        ? storeLocked.lockDirectory
+        : join(kbPath, "rdf");
+    breakStoreLock(lockDirectory);
+    const retried = await prolog.query(`kb_attach('${escapeAtom(kbPath)}')`);
+    if (retried.success) {
+        console.warn(`[KIBI] Broke a stale branch-store lock (${decision.reason}) and reattached.`);
+    }
+    return retried;
+}

package/dist/prolog.d.ts

@@ -1,3 +1,4 @@
+import { type PrologErrorRecord } from "./prolog/error-terms.js";
 export declare function resolveKbPlPath(): string;
 export interface PrologOptions {
     swiplPath?: string;
@@ -13,7 +14,10 @@ export interface QueryResult {
     success: boolean;
     bindings: Record<string, string>;
     error?: string;
+    errorRecord?: PrologErrorRecord;
 }
+export declare function registerProcessExitOnce(current: (() => void) | null, handler: () => void, on?: (event: "exit", listener: () => void) => void): () => void;
+export declare function bindProcessExitHandler(current: (() => void) | null, terminate: () => void | Promise<void>, on?: (event: "exit", listener: () => void) => void): () => void;
 export declare class PrologProcess {
     private process;
     private swiplPath;
@@ -31,6 +35,7 @@ export declare class PrologProcess {
     private attachedKbPath;
     private onProcessExit;
     constructor(options?: PrologOptions);
+    attachProcessExitHandler(on?: (event: "exit", listener: () => void) => void): void;
     start(): Promise<void>;
     private waitForReady;
     query(goal: string | string[]): Promise<QueryResult>;
@@ -53,6 +58,8 @@ export declare class PrologProcess {
     private terminateProcessTree;
     private isProcessUsable;
     private extractBindings;
+    /** Prefer the structured error term; fall back to text heuristics. */
+    private classifyErrorOutput;
     private translateError;
     isRunning(): boolean;
     getPid(): number;

package/dist/prolog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prolog.d.ts","sourceRoot":"","sources":["../src/prolog.ts"],"names":[],"mappings":"AAkDA,wBAAgB,eAAe,IAAI,MAAM,CAsCxC;AACD,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,YAAY,CAAM;IAC1B,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,WAAW,CAAM;IACzB,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,KAAK,CAAuC;IACpD,OAAO,CAAC,oBAAoB,CAAoC;IAChE,OAAO,CAAC,kBAAkB,CAA8B;IACxD,OAAO,CAAC,gBAAgB,CAA2B;IACnD,OAAO,CAAC,cAAc,CAAU;IAChC,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,aAAa,CAA6B;gBAEtC,OAAO,GAAE,aAAkB;IASjC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAsDd,YAAY;IAyCpB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC;IAgN1D,wEAAwE;IAClE,UAAU,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC;IAIhE,eAAe,IAAI,IAAI;IAIvB,OAAO,CAAC,eAAe;IAwBvB,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,kBAAkB;YAIZ,YAAY;IA2C1B,OAAO,CAAC,WAAW;IA8NnB,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,iBAAiB;IAQzB,OAAO,CAAC,iBAAiB;IAazB,OAAO,CAAC,gBAAgB;IAaxB,OAAO,CAAC,SAAS;IAOjB,OAAO,CAAC,kBAAkB;IAU1B,OAAO,CAAC,mBAAmB;IAK3B,OAAO,CAAC,iBAAiB;YAkBX,oBAAoB;IAyBlC,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,eAAe;IAkBvB,OAAO,CAAC,cAAc;IA+EtB,SAAS,IAAI,OAAO;IAMpB,MAAM,IAAI,MAAM;IAIV,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;CAkCjC"}
+{"version":3,"file":"prolog.d.ts","sourceRoot":"","sources":["../src/prolog.ts"],"names":[],"mappings":"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"}

package/dist/prolog.js

@@ -21,6 +21,7 @@ import { createRequire } from "node:module";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { getKbPlPathOverride, isPrologDebugEnabled } from "./env.js";
+import { extractPrologErrorRecord, } from "./prolog/error-terms.js";
 const importMetaDir = path.dirname(fileURLToPath(import.meta.url));
 const PROLOG_OUTPUT_MAX_BUFFER_BYTES = 8 * 1024 * 1024;
 const PROLOG_OUTPUT_OVERFLOW_ERROR = "Query exceeded bounded Prolog output capacity (ENOBUFS); narrow the operation or reduce stored entity size";
@@ -78,6 +79,19 @@ export function resolveKbPlPath() {
     throw new Error("Unable to resolve kb.pl. Expected kibi-core to be installed (node_modules) " +
         "or to be running inside the monorepo checkout.");
 }
+// implements REQ-core-prolog-process-management
+export function registerProcessExitOnce(current, handler, on = (event, listener) => process.on(event, listener)) {
+    if (current)
+        return current;
+    on("exit", handler);
+    return handler;
+}
+// implements REQ-core-prolog-process-management
+export function bindProcessExitHandler(current, terminate, on = (event, listener) => process.on(event, listener)) {
+    return registerProcessExitOnce(current, () => {
+        void terminate();
+    }, on);
+}
 export class PrologProcess {
     process = null;
     swiplPath;
@@ -102,6 +116,10 @@ export class PrologProcess {
                 (process.env.NODE_ENV === "test" &&
                     typeof globalThis.Bun !== "undefined");
     }
+    // implements REQ-core-prolog-process-management
+    attachProcessExitHandler(on = (event, listener) => process.on(event, listener)) {
+        this.onProcessExit = bindProcessExitHandler(this.onProcessExit, () => this.terminate(), on);
+    }
     async start() {
         if (!existsSync(this.swiplPath) && this.swiplPath !== "swipl") {
             throw new Error(`SWI-Prolog not found at ${this.swiplPath}. Please install SWI-Prolog or check your PATH.`);
@@ -131,12 +149,7 @@ export class PrologProcess {
             this.appendErrorChunk(chunk);
         });
         this.process.stdin.write("true.\n");
-        if (!this.onProcessExit) {
-            this.onProcessExit = () => {
-                void this.terminate();
-            };
-            process.on("exit", this.onProcessExit);
-        }
+        this.attachProcessExitHandler();
         await this.waitForReady();
     }
     async waitForReady() {
@@ -144,8 +157,13 @@ export class PrologProcess {
         const start = Date.now();
         const maxStartWait = 2000; // ms
         while (Date.now() - start < maxStartWait) {
-            // If process exited or was killed, surface the error buffer.
-            if (!this.process || this.process.killed) {
+            // If process exited or was killed, surface the error buffer. A signal
+            // kill leaves exitCode null but populates signalCode, so both must be
+            // checked or an externally killed child looks "still starting".
+            if (!this.process ||
+                this.process.killed ||
+                this.process.exitCode !== null ||
+                this.process.signalCode !== null) {
                 throw new Error(`Prolog process terminated unexpectedly during startup: ${this.translateError(this.errorBuffer)}`);
             }
             // If stderr contains an ERROR, fail fast with translated message.
@@ -221,9 +239,13 @@ export class PrologProcess {
             const goalWithPersistence = shouldPersist
                 ? `(${normalizedGoal}, kb_save)`
                 : normalizedGoal;
+            // Report the thrown term structurally ahead of SWI's human-readable
+            // print_message output. Built-ins only, so the wrapper works against
+            // any installed kibi-core version.
+            const errorReport = `(write(user_error, '__KIBI_ERROR__:'), write_term(user_error, _E, [quoted(true), max_depth(8)]), nl(user_error), print_message(error, _E), fail)`;
             const wrappedGoal = /^once\s*\(/.test(goalWithPersistence)
-                ? `catch(${goalWithPersistence}, _E, (print_message(error, _E), fail))`
-                : `catch(once((${goalWithPersistence})), _E, (print_message(error, _E), fail))`;
+                ? `catch(${goalWithPersistence}, _E, ${errorReport})`
+                : `catch(once((${goalWithPersistence})), _E, ${errorReport})`;
             const start = Date.now();
             if (debug) {
                 console.error(`[prolog debug] start query: ${goalLabel}`);
@@ -233,7 +255,7 @@ export class PrologProcess {
                 let settled = false;
                 const timeoutId = setTimeout(() => {
                     const stage = this.lastDiagnosticStage(this.errorBuffer) ?? "unknown";
-                    const msg = `Query timeout after ${this.timeout / 1000}s (stage=${stage}, pid=${this.process?.pid ?? 0}, killed=${this.process?.killed ? "yes" : "no"}, exitCode=${this.process?.exitCode ?? "null"}, goal=${goalLabel})`;
+                    const msg = `Query timeout after ${this.timeout / 1000}s (stage=${stage}, pid=${this.process?.pid ?? 0}, killed=${this.process?.killed ? "yes" : "no"}, exitCode=${this.process?.exitCode ?? "null"}, signal=${this.process?.signalCode ?? "null"}, goal=${goalLabel}). If several fresh Kibi commands hang or crawl the same way, the engine state is likely wedged: run 'kibi engine stop' (then 'kibi sync --rebuild' if needed) and retry.`;
                     if (debug) {
                         console.error(`[prolog debug] timeout: ${msg}`);
                         const runtime = this.errorBuffer
@@ -279,10 +301,12 @@ export class PrologProcess {
                         if (debug) {
                             console.error(`[prolog debug] query error: ${goalLabel} error=${this.errorBuffer.split("\n")[0]}`);
                         }
+                        const classified = this.classifyErrorOutput(this.errorBuffer);
                         resolve({
                             success: false,
                             bindings: {},
-                            error: this.addDiagnosticStage(this.translateError(this.errorBuffer), normalizedGoal, this.errorBuffer),
+                            error: this.addDiagnosticStage(classified.message, normalizedGoal, this.errorBuffer),
+                            ...(classified.record ? { errorRecord: classified.record } : {}),
                         });
                         return;
                     }
@@ -436,7 +460,7 @@ export class PrologProcess {
             "read_term_from_atom(GoalAtom, Goal, [variable_names(Vars)])",
             kbPath ? "getenv('KIBI_KB_PATH', KBPath), kb_attach(KBPath)" : "true",
             isBatch ? "WrappedGoal = rdf_transaction(Goal)" : "WrappedGoal = Goal",
-            "(catch(call(WrappedGoal), E, (print_message(error, E), fail)) -> QuerySucceeded = true ; QuerySucceeded = false)",
+            "(catch(call(WrappedGoal), E, (write(user_error, '__KIBI_ERROR__:'), write_term(user_error, E, [quoted(true), max_depth(8)]), nl(user_error), print_message(error, E), fail)) -> QuerySucceeded = true ; QuerySucceeded = false)",
             kbPath &&
                 (explicitSaveRequested ||
                     goalList.some((item) => this.isMutatingGoal(item)))
@@ -556,10 +580,12 @@ export class PrologProcess {
             };
         }
         if (stderr.includes("ERROR")) {
+            const classified = this.classifyErrorOutput(stderr);
             return {
                 success: false,
                 bindings: {},
-                error: this.addDiagnosticStage(this.translateError(stderr), combinedGoal ?? "true", stderr),
+                error: this.addDiagnosticStage(classified.message, combinedGoal ?? "true", stderr),
+                ...(classified.record ? { errorRecord: classified.record } : {}),
             };
         }
         if (stdout.includes("__KIBI_TRUE__")) {
@@ -685,28 +711,56 @@ export class PrologProcess {
     isProcessUsable() {
         return Boolean(this.process?.stdin &&
             !this.process?.killed &&
-            this.process?.exitCode === null);
+            this.process?.exitCode === null &&
+            this.process?.signalCode === null);
     }
     extractBindings(output) {
         const bindings = {};
-        const lines = output.split("\n");
-        for (const line of lines) {
-            const match = line.match(/^([A-Z_][A-Za-z0-9_]*)\s*=\s*(.+)\.?\s*$/);
-            if (match) {
-                const [, varName, value] = match;
-                if (varName !== undefined && value !== undefined) {
-                    bindings[varName] = value.trim().replace(/\.$/, "").replace(/,$/, "");
-                }
+        let variableName;
+        let valueLines = [];
+        const flush = () => {
+            if (variableName === undefined)
+                return;
+            bindings[variableName] = valueLines
+                .join("\n")
+                .trim()
+                .replace(/\.$/, "")
+                .replace(/,$/, "");
+            variableName = undefined;
+            valueLines = [];
+        };
+        // Prolog may print a quoted string over multiple physical lines when the
+        // long-lived session's answer formatting is configured for readable JSON.
+        // Parse assignment records as blocks instead of dropping every continuation
+        // line after the first one (which previously reduced JsonString to "{").
+        for (const line of output.split("\n")) {
+            const match = line.match(/^([A-Z_][A-Za-z0-9_]*)\s*=\s*(.*)$/);
+            if (match?.[1] !== undefined && match[2] !== undefined) {
+                flush();
+                variableName = match[1];
+                valueLines = [match[2]];
+                continue;
             }
+            if (variableName !== undefined)
+                valueLines.push(line);
         }
+        flush();
         return bindings;
     }
+    /** Prefer the structured error term; fall back to text heuristics. */
+    classifyErrorOutput(errorText) {
+        const record = extractPrologErrorRecord(errorText);
+        if (record) {
+            return { message: record.message, record };
+        }
+        return { message: this.translateError(errorText) };
+    }
     // implements REQ-core-prolog-process-management
     translateError(errorText) {
         // Diagnostic markers intentionally contain words such as `lock` and the
         // audit path. Remove them before classifying the actual Prolog error so a
         // contradiction at the check stage is not mistaken for an audit lock.
-        const cleanError = errorText.replace(/^__KIBI_(?:STAGE|RUNTIME)__:[^\r\n]*\r?\n?/gm, "");
+        const cleanError = errorText.replace(/^__KIBI_(?:STAGE|RUNTIME|ERROR)__:[^\r\n]*\r?\n?/gm, "");
         if (cleanError.includes("stale_snapshot")) {
             return "KB snapshot is stale; reattach or refresh the runtime before retrying (stale_snapshot)";
         }
@@ -765,7 +819,10 @@ export class PrologProcess {
         return simpleError || "Unknown error";
     }
     isRunning() {
-        return Boolean(this.process && !this.process.killed && this.process?.exitCode === null);
+        return Boolean(this.process &&
+            !this.process.killed &&
+            this.process?.exitCode === null &&
+            this.process?.signalCode === null);
     }
     getPid() {
         return this.process?.pid || 0;

package/dist/proof/evaluate.d.ts

@@ -0,0 +1,27 @@
+import type { ProofContract, ProofResult, ProofRunArtifact } from "../public/proof-protocol.js";
+import type { ProofReceiptOutcome } from "./receipt-outcome.js";
+export type ProofGap = Readonly<{
+    symbol_id: string;
+    target: string;
+    reason: string;
+}>;
+export type ContractEvaluation = Readonly<{
+    satisfied: boolean;
+    outcome: ProofReceiptOutcome;
+    gaps: readonly ProofGap[];
+    projectedResults: readonly ProofResult[];
+}>;
+export declare function mapRunOutcome(outcome: ProofRunArtifact["run"]["outcome"]): ProofReceiptOutcome;
+/**
+ * Kibi evaluates proof. Producers only report what happened.
+ *
+ * - The run must have completed successfully; a failed run never proves
+ *   anything, no matter how many individual results passed.
+ * - `native_case` results must carry complete attempt history with a passing
+ *   first attempt; unknown history fails closed.
+ * - `aggregate_run` results are satisfied by the one Kibi-launched process
+ *   invocation itself (the process attempt), never by invented native-case
+ *   evidence.
+ */
+export declare function evaluateContractAgainstRun(artifact: ProofRunArtifact, contract: ProofContract): ContractEvaluation;
+//# sourceMappingURL=evaluate.d.ts.map

package/dist/proof/evaluate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate.d.ts","sourceRoot":"","sources":["../../src/proof/evaluate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,WAAW,EACX,gBAAgB,EACjB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,MAAM,MAAM,QAAQ,GAAG,QAAQ,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IACxC,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,mBAAmB,CAAC;IAC7B,IAAI,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC1B,gBAAgB,EAAE,SAAS,WAAW,EAAE,CAAC;CAC1C,CAAC,CAAC;AAEH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,gBAAgB,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,GAC1C,mBAAmB,CAgBrB;AA6CD;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,gBAAgB,EAC1B,QAAQ,EAAE,aAAa,GACtB,kBAAkB,CA4GpB"}

package/dist/proof/evaluate.js

@@ -0,0 +1,151 @@
+export function mapRunOutcome(outcome) {
+    switch (outcome) {
+        case "passed":
+            return "passed";
+        case "errored":
+            return "errored";
+        case "cancelled":
+            return "cancelled";
+        case "timed_out":
+            return "timed_out";
+        case "interrupted":
+            return "interrupted";
+        case "no_results":
+        case "failed":
+            return "failed";
+    }
+}
+const MAX_ATTRIBUTED_MEMBERS = 5;
+/**
+ * When a run fails, attribute the failure to the individual proof results
+ * that did not pass. Consumers prove domain contracts through aggregate
+ * bindings, so a single slow member would otherwise refuse every contract
+ * with an opaque "run did not pass" even though each obligation's own result
+ * passed. Diagnostics only: attribution never changes pass/fail semantics.
+ */
+function failingMemberSummary(artifact, observed) {
+    const failing = artifact.proof_results.filter((result) => result.outcome !== "passed");
+    if (failing.length === 0)
+        return "";
+    const ownOutcome = observed === undefined
+        ? undefined
+        : observed.outcome === "passed"
+            ? "passed"
+            : observed.outcome;
+    const others = failing.filter((result) => result !== observed);
+    const parts = [];
+    if (ownOutcome !== undefined && ownOutcome !== "passed") {
+        parts.push(`this obligation's own result outcome is '${ownOutcome}'`);
+    }
+    else if (ownOutcome === "passed") {
+        parts.push("this obligation's own result passed");
+    }
+    if (others.length > 0) {
+        const listed = others
+            .slice(0, MAX_ATTRIBUTED_MEMBERS)
+            .map((result) => `${result.symbol_id} (${result.outcome})`);
+        const overflow = others.length > MAX_ATTRIBUTED_MEMBERS
+            ? ` +${others.length - MAX_ATTRIBUTED_MEMBERS} more`
+            : "";
+        parts.push(`failing member result(s): ${listed.join(", ")}${overflow}`);
+    }
+    return parts.length === 0 ? "" : `; ${parts.join("; ")}`;
+}
+/**
+ * Kibi evaluates proof. Producers only report what happened.
+ *
+ * - The run must have completed successfully; a failed run never proves
+ *   anything, no matter how many individual results passed.
+ * - `native_case` results must carry complete attempt history with a passing
+ *   first attempt; unknown history fails closed.
+ * - `aggregate_run` results are satisfied by the one Kibi-launched process
+ *   invocation itself (the process attempt), never by invented native-case
+ *   evidence.
+ */
+export function evaluateContractAgainstRun(artifact, contract) {
+    const runPassed = artifact.run.outcome === "passed";
+    const gaps = [];
+    const projectedResults = [];
+    for (const obligation of contract.required_proofs) {
+        const observed = artifact.proof_results.find((result) => result.symbol_id === obligation.symbol_id &&
+            result.target === obligation.target);
+        if (observed)
+            projectedResults.push(observed);
+        if (!runPassed) {
+            const attribution = failingMemberSummary(artifact, observed);
+            gaps.push({
+                symbol_id: obligation.symbol_id,
+                target: obligation.target,
+                reason: artifact.run.outcome === "no_results"
+                    ? `run produced no results (outcome: no_results${artifact.run.failure_phase ? `, phase: ${artifact.run.failure_phase}` : ""})`
+                    : `run did not pass (outcome: ${artifact.run.outcome}${artifact.run.failure_phase ? `, phase: ${artifact.run.failure_phase}` : ""})${attribution}`,
+            });
+            continue;
+        }
+        if (!observed) {
+            gaps.push({
+                symbol_id: obligation.symbol_id,
+                target: obligation.target,
+                reason: "missing proof result: the run reported no result for this obligation",
+            });
+            continue;
+        }
+        if (observed.outcome !== "passed") {
+            gaps.push({
+                symbol_id: obligation.symbol_id,
+                target: obligation.target,
+                reason: `proof result outcome is '${observed.outcome}'`,
+            });
+            continue;
+        }
+        if (observed.binding === "native_case") {
+            if (observed.attempts.status === "unavailable") {
+                gaps.push({
+                    symbol_id: obligation.symbol_id,
+                    target: obligation.target,
+                    reason: "attempt history unavailable: strict first-attempt policy cannot verify a native-case pass",
+                });
+                continue;
+            }
+            const first = observed.attempts.entries[0];
+            if (!first || first.outcome !== "passed") {
+                gaps.push({
+                    symbol_id: obligation.symbol_id,
+                    target: obligation.target,
+                    reason: `first attempt outcome is '${first?.outcome ?? "unknown"}'`,
+                });
+            }
+            continue;
+        }
+        // aggregate_run: the single Kibi-launched command invocation is known
+        // first-attempt process evidence when the run passed with exit code 0.
+        if (artifact.run.exit_code !== 0) {
+            gaps.push({
+                symbol_id: obligation.symbol_id,
+                target: obligation.target,
+                reason: `aggregate run exit code is ${artifact.run.exit_code}`,
+            });
+        }
+    }
+    if (!runPassed) {
+        return {
+            satisfied: false,
+            outcome: mapRunOutcome(artifact.run.outcome),
+            gaps,
+            projectedResults,
+        };
+    }
+    if (gaps.length > 0) {
+        let outcome = "failed";
+        if (projectedResults.some((result) => contract.required_proofs.some((obligation) => obligation.symbol_id === result.symbol_id &&
+            obligation.target === result.target) && result.outcome === "interrupted")) {
+            outcome = "interrupted";
+        }
+        else if (projectedResults.some((result) => contract.required_proofs.some((obligation) => obligation.symbol_id === result.symbol_id &&
+            obligation.target === result.target) && result.outcome === "timed_out")) {
+            outcome = "timed_out";
+        }
+        return { satisfied: false, outcome, gaps, projectedResults };
+    }
+    return { satisfied: true, outcome: "passed", gaps: [], projectedResults };
+}

package/dist/proof/inspect.d.ts

@@ -0,0 +1,12 @@
+export type ProofInspection = Readonly<{
+    languages: readonly string[];
+    buildSystems: readonly string[];
+    detectedRunners: readonly string[];
+    ciWorkflows: readonly string[];
+    currentIntegration: string | null;
+    recommendation: string;
+    missing: readonly string[];
+}>;
+export declare function directoryEntriesMatch(directory: string, regex: RegExp): boolean;
+export declare function inspectProofEnvironment(root: string): ProofInspection;
+//# sourceMappingURL=inspect.d.ts.map

package/dist/proof/inspect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.d.ts","sourceRoot":"","sources":["../../src/proof/inspect.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B,CAAC,CAAC;AAwIH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACZ,OAAO,CAMT;AA2BD,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAoFrE"}