kibi-cli 2.2.0 → 2.4.0

package/dist/prolog/swipl-resolver.js

@@ -0,0 +1,446 @@
+/*
+ * 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.
+ */
+/**
+ * Resolves the SWI-Prolog executable Kibi runs, in this order:
+ *
+ * 1. `KIBI_SWIPL=<absolute path>` (an explicit operator choice always wins).
+ * 2. The bundled platform package (`kibi-swipl-<platform>`), after its build
+ *    manifest and binary checksum verify. `KIBI_SWIPL=system` skips this step.
+ * 3. `swipl` on `PATH`, subject to the SWI-Prolog 9.0 minimum.
+ * 4. Otherwise an error naming the platform, the platform package that would
+ *    have covered it, and the OS install command.
+ */
+import { execFileSync, spawnSync } from "node:child_process";
+import { constants, accessSync, existsSync, readFileSync, statSync, } from "node:fs";
+import path from "node:path";
+import { BUNDLED_BINARY_PATH, MANIFEST_FILE, PLATFORM_PACKAGES, locatePlatformPackage, platformKey, sha256File, validateBuildManifest, } from "kibi-swipl";
+export const MINIMUM_SWIPL_MAJOR = 9;
+/** Structured failure; `message` is the complete operator-facing guidance. */
+export class SwiplResolutionError extends Error {
+    code;
+    /** Detected host, e.g. "linux-x64 (glibc)". */
+    platform;
+    /** Platform package that would have covered this host, when one exists. */
+    packageName;
+    constructor(code, message, platform, packageName) {
+        super(message);
+        this.name = "SwiplResolutionError";
+        this.code = code;
+        this.platform = platform;
+        this.packageName = packageName;
+    }
+}
+function detectGlibc() {
+    if (process.platform !== "linux")
+        return undefined;
+    try {
+        const report = process.report?.getReport?.();
+        if (report !== undefined) {
+            return typeof report.header?.glibcVersionRuntime === "string";
+        }
+    }
+    catch {
+        // Fall back to the musl loader probe below.
+    }
+    return !["/lib/ld-musl-x86_64.so.1", "/lib/ld-musl-aarch64.so.1"].some((loader) => existsSync(loader));
+}
+function defaultRunVersion(bin) {
+    return execFileSync(bin, ["--version"], {
+        encoding: "utf8",
+        timeout: 10_000,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+}
+function defaultDeps() {
+    return {
+        platform: process.platform,
+        arch: process.arch,
+        glibc: detectGlibc(),
+        locatePackage: (name) => locatePlatformPackage(name),
+        runVersion: defaultRunVersion,
+    };
+}
+/** Parse `SWI-Prolog version 10.0.2 for x86_64-linux` into its version. */
+export function parseSwiplVersion(output) {
+    const match = /version\s+(\d+)\.(\d+)(?:\.(\d+))?/i.exec(output);
+    if (match === null)
+        return undefined;
+    const [, major, minor, patch] = match;
+    return {
+        version: `${major}.${minor}${patch === undefined ? "" : `.${patch}`}`,
+        major: Number.parseInt(major ?? "0", 10),
+    };
+}
+function installCommand(platform) {
+    if (platform === "linux") {
+        return "sudo apt-add-repository ppa:swi-prolog/stable && sudo apt-get update && sudo apt-get install swi-prolog";
+    }
+    if (platform === "darwin")
+        return "brew install swi-prolog";
+    return "download the installer from https://www.swi-prolog.org/download/stable and add swipl to PATH";
+}
+function hostLabel(deps) {
+    const libc = deps.platform === "linux" && deps.glibc !== undefined
+        ? ` (${deps.glibc ? "glibc" : "musl"})`
+        : "";
+    return `${deps.platform}-${deps.arch}${libc}`;
+}
+function isExecutableFile(candidate) {
+    try {
+        if (!statSync(candidate).isFile())
+            return false;
+        accessSync(candidate, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function inspectBundle(deps) {
+    const key = platformKey({
+        platform: deps.platform,
+        arch: deps.arch,
+        glibc: deps.glibc,
+    });
+    if (key === undefined)
+        return { kind: "unsupported" };
+    const packageName = PLATFORM_PACKAGES[key].package;
+    const packageDir = deps.locatePackage(packageName);
+    if (packageDir === undefined)
+        return { kind: "missing", key, packageName };
+    const manifestPath = path.join(packageDir, MANIFEST_FILE);
+    const binary = path.join(packageDir, BUNDLED_BINARY_PATH);
+    if (!existsSync(manifestPath)) {
+        // A workspace checkout links the package without the pipeline payload.
+        // A binary without a manifest is a damaged install, not a placeholder.
+        if (!existsSync(binary))
+            return { kind: "empty", key, packageName };
+        return {
+            kind: "corrupt",
+            key,
+            packageName,
+            reason: `${MANIFEST_FILE} is missing next to ${BUNDLED_BINARY_PATH}`,
+        };
+    }
+    const corrupt = (reason) => ({
+        kind: "corrupt",
+        key,
+        packageName,
+        reason,
+    });
+    let manifest;
+    let packageJson;
+    try {
+        manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+    }
+    catch (error) {
+        return corrupt(`${MANIFEST_FILE} is not valid JSON (${error instanceof Error ? error.message : String(error)})`);
+    }
+    try {
+        packageJson = JSON.parse(readFileSync(path.join(packageDir, "package.json"), "utf8"));
+    }
+    catch (error) {
+        return corrupt(`package.json is unreadable (${error instanceof Error ? error.message : String(error)})`);
+    }
+    const packageVersion = packageJson.kibi?.swiplVersion;
+    const checked = validateBuildManifest(manifest, {
+        target: key,
+        swiplVersion: typeof packageVersion === "string" ? packageVersion : undefined,
+    });
+    if (!checked.ok)
+        return corrupt(checked.reason);
+    if (!isExecutableFile(binary)) {
+        return corrupt(`${BUNDLED_BINARY_PATH} is missing or not executable`);
+    }
+    let actual;
+    try {
+        actual = sha256File(binary);
+    }
+    catch (error) {
+        return corrupt(`${BUNDLED_BINARY_PATH} is unreadable (${error instanceof Error ? error.message : String(error)})`);
+    }
+    if (actual !== checked.binarySha256) {
+        return corrupt(`${BUNDLED_BINARY_PATH} SHA-256 ${actual} does not match the manifest (${checked.binarySha256})`);
+    }
+    const home = path.join(packageDir, checked.home);
+    let homeIsDirectory = false;
+    try {
+        homeIsDirectory = statSync(home).isDirectory();
+    }
+    catch {
+        // reported below
+    }
+    if (!homeIsDirectory)
+        return corrupt(`${checked.home} is missing`);
+    return {
+        kind: "ok",
+        key,
+        packageName,
+        resolved: {
+            bin: binary,
+            home,
+            version: checked.swiplVersion,
+            source: "bundled",
+        },
+    };
+}
+function probeVersion(bin, deps) {
+    let output;
+    try {
+        output = deps.runVersion(bin);
+    }
+    catch (error) {
+        return {
+            kind: "unusable",
+            detail: error instanceof Error ? error.message : String(error),
+        };
+    }
+    const parsed = parseSwiplVersion(output);
+    if (parsed === undefined) {
+        return {
+            kind: "unusable",
+            detail: `unrecognized --version output ${JSON.stringify(output.trim().slice(0, 80))}`,
+        };
+    }
+    if (parsed.major < MINIMUM_SWIPL_MAJOR) {
+        return { kind: "too-old", version: parsed.version };
+    }
+    return { kind: "ok", version: parsed.version };
+}
+function findOnPath(env, deps) {
+    for (const directory of (env.PATH ?? "").split(path.delimiter)) {
+        if (directory === "" || !path.isAbsolute(directory))
+            continue;
+        const candidate = path.join(directory, "swipl");
+        if (!isExecutableFile(candidate))
+            continue;
+        const probe = probeVersion(candidate, deps);
+        if (probe.kind === "ok") {
+            return {
+                kind: "ok",
+                resolved: { bin: candidate, version: probe.version, source: "path" },
+            };
+        }
+        return probe.kind === "too-old"
+            ? { kind: "too-old", bin: candidate, version: probe.version }
+            : { kind: "unusable", bin: candidate, detail: probe.detail };
+    }
+    return { kind: "absent" };
+}
+function resolveFromEnv(override, deps) {
+    const platform = hostLabel(deps);
+    const key = platformKey({
+        platform: deps.platform,
+        arch: deps.arch,
+        glibc: deps.glibc,
+    });
+    const packageName = key === undefined ? undefined : PLATFORM_PACKAGES[key].package;
+    const invalid = (detail) => new SwiplResolutionError("swipl_env_invalid", `KIBI_SWIPL=${override} ${detail}. Set KIBI_SWIPL to the absolute path of a SWI-Prolog ${MINIMUM_SWIPL_MAJOR}.0+ executable, to "system" to use swipl from PATH, or unset it to use the bundled runtime.`, platform, packageName);
+    if (!path.isAbsolute(override))
+        return fail(invalid("is not an absolute path"));
+    if (!isExecutableFile(override)) {
+        return fail(invalid("is not an executable file"));
+    }
+    const probe = probeVersion(override, deps);
+    if (probe.kind === "unusable") {
+        return fail(invalid(`could not report its version (${probe.detail})`));
+    }
+    if (probe.kind === "too-old") {
+        return fail(invalid(`is SWI-Prolog ${probe.version}, but ${MINIMUM_SWIPL_MAJOR}.0 or newer is required`));
+    }
+    return { bin: override, version: probe.version, source: "env" };
+}
+function fail(error) {
+    throw error;
+}
+function notFoundError(deps, bundle, lookup) {
+    const platform = hostLabel(deps);
+    const command = installCommand(deps.platform);
+    const lines = [
+        `Kibi could not find a usable SWI-Prolog (${MINIMUM_SWIPL_MAJOR}.0 or newer is required).`,
+        `Detected platform: ${platform}.`,
+    ];
+    let packageName;
+    if (bundle === "skipped") {
+        lines.push("Bundled SWI-Prolog: skipped because KIBI_SWIPL=system.");
+        const key = platformKey({
+            platform: deps.platform,
+            arch: deps.arch,
+            glibc: deps.glibc,
+        });
+        if (key !== undefined)
+            packageName = PLATFORM_PACKAGES[key].package;
+    }
+    else if (bundle.kind === "unsupported") {
+        lines.push(`Bundled SWI-Prolog: no bundled build exists for ${platform} (supported: ${Object.keys(PLATFORM_PACKAGES).join(", ")}).`);
+    }
+    else {
+        packageName = bundle.packageName;
+        if (bundle.kind === "empty") {
+            lines.push(`Bundled SWI-Prolog: package ${bundle.packageName} is installed but carries no runtime (a source checkout that was not populated from a release build).`);
+        }
+        else {
+            lines.push(`Bundled SWI-Prolog: package ${bundle.packageName} would cover this platform but is not installed. It is skipped by installs that omit optional dependencies (npm --omit=optional, --no-optional) and by pnpm supportedArchitectures settings that exclude this platform.`);
+            lines.push(`  Add it with: npm install --save-dev ${bundle.packageName}`);
+        }
+    }
+    if (bundle === "skipped" && packageName !== undefined) {
+        lines.push(`  To use it, unset KIBI_SWIPL and install ${packageName}.`);
+    }
+    switch (lookup.kind) {
+        case "absent":
+            lines.push("System SWI-Prolog: swipl was not found on PATH.");
+            break;
+        case "too-old":
+            lines.push(`System SWI-Prolog: swipl on PATH (${lookup.bin}) is version ${lookup.version}, older than ${MINIMUM_SWIPL_MAJOR}.0.`);
+            break;
+        case "unusable":
+            lines.push(`System SWI-Prolog: swipl on PATH (${lookup.bin}) could not report its version (${lookup.detail}).`);
+            break;
+        case "ok":
+            break;
+    }
+    lines.push(`  Install it with: ${command}`);
+    lines.push(`Or set KIBI_SWIPL to the absolute path of a SWI-Prolog ${MINIMUM_SWIPL_MAJOR}.0+ executable.`);
+    return new SwiplResolutionError("swipl_not_found", lines.join("\n"), platform, packageName);
+}
+/** Uncached resolution with injectable host facts; the test seam. */
+export function resolveSwiplWith(env, deps) {
+    const override = env.KIBI_SWIPL?.trim() ?? "";
+    if (override !== "" && override !== "system") {
+        return resolveFromEnv(override, deps);
+    }
+    let bundle = "skipped";
+    if (override === "") {
+        bundle = inspectBundle(deps);
+        if (bundle.kind === "ok")
+            return bundle.resolved;
+        if (bundle.kind === "corrupt") {
+            throw new SwiplResolutionError("swipl_bundle_corrupt", [
+                `The bundled SWI-Prolog package ${bundle.packageName} is damaged: ${bundle.reason}.`,
+                `Detected platform: ${hostLabel(deps)}.`,
+                `Reinstall it (for example: npm install --save-dev ${bundle.packageName}), or set KIBI_SWIPL=system to use swipl from PATH instead.`,
+            ].join("\n"), hostLabel(deps), bundle.packageName);
+        }
+    }
+    const lookup = findOnPath(env, deps);
+    if (lookup.kind === "ok")
+        return lookup.resolved;
+    throw notFoundError(deps, bundle, lookup);
+}
+const cache = new Map();
+/**
+ * Resolve the SWI-Prolog executable for this process. The result is cached for
+ * the lifetime of the process, keyed by the inputs that select it.
+ */
+export function resolveSwipl(env = process.env) {
+    const key = `${env.KIBI_SWIPL ?? ""}\0${env.PATH ?? ""}`;
+    const cached = cache.get(key);
+    if (cached !== undefined)
+        return cached;
+    const resolved = resolveSwiplWith(env, defaultDeps());
+    cache.set(key, resolved);
+    return resolved;
+}
+/** Test seam: forget every cached resolution. */
+export function resetSwiplResolverCache() {
+    cache.clear();
+}
+/** Stable identity of a resolved runtime, compared across engine processes. */
+export function swiplIdentity(resolved) {
+    return `${resolved.bin}@${resolved.version}`;
+}
+/** Environment additions a child needs to run the resolved SWI-Prolog. */
+export function swiplChildEnv(resolved) {
+    return resolved.home === undefined ? {} : { SWI_HOME_DIR: resolved.home };
+}
+/** Report the bundled package's state without resolving a runtime. */
+export function inspectSwiplBundle(deps = defaultDeps()) {
+    const bundle = inspectBundle(deps);
+    switch (bundle.kind) {
+        case "unsupported":
+            return { state: "unsupported" };
+        case "missing":
+        case "empty":
+            return { state: bundle.kind, packageName: bundle.packageName };
+        case "corrupt":
+            return {
+                state: "corrupt",
+                packageName: bundle.packageName,
+                reason: bundle.reason,
+            };
+        case "ok":
+            return { state: "installed", packageName: bundle.packageName };
+    }
+}
+/** Libraries Kibi loads at runtime; a SWI-Prolog lacking one cannot serve it. */
+export const REQUIRED_SWIPL_LIBRARIES = [
+    "semweb/rdf_db",
+    "semweb/rdf_persistency",
+    "semweb/sparql_client",
+    "pcre",
+    "crypto",
+    "sha",
+    "http/json",
+    "http/json_convert",
+    "chr",
+    "clpfd",
+    "thread",
+    "persistency",
+    "filesex",
+    "readutil",
+    "date",
+    "aggregate",
+    "solution_sequences",
+];
+const MISSING_LIBRARY_MARKER = "__KIBI_MISSING_LIBRARY__:";
+function defaultGoalRunner(bin, args, env) {
+    const result = spawnSync(bin, [...args], {
+        encoding: "utf8",
+        timeout: 60_000,
+        stdio: ["ignore", "pipe", "pipe"],
+        env,
+    });
+    return {
+        status: result.status,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+        ...(result.error === undefined ? {} : { error: result.error }),
+    };
+}
+/**
+ * Load every required library in one throwaway SWI-Prolog process and report
+ * the ones that fail. A probe that cannot run is reported as such, never as a
+ * pass.
+ */
+export function probeRequiredLibraries(resolved, run = defaultGoalRunner, env = process.env) {
+    const goal = `forall(member(L, [${REQUIRED_SWIPL_LIBRARIES.join(", ")}]), (catch(use_module(library(L)), _, fail) -> true ; format("${MISSING_LIBRARY_MARKER}~w~n", [L])))`;
+    const result = run(resolved.bin, ["-q", "-g", goal, "-t", "halt"], {
+        ...env,
+        ...swiplChildEnv(resolved),
+    });
+    if (result.error !== undefined) {
+        return { kind: "failed", detail: result.error.message };
+    }
+    if (result.status !== 0) {
+        const detail = result.stderr.trim().split("\n")[0] ?? "";
+        return {
+            kind: "failed",
+            detail: `exit status ${result.status ?? "none"}${detail === "" ? "" : `: ${detail}`}`,
+        };
+    }
+    const libraries = result.stdout
+        .split("\n")
+        .filter((line) => line.startsWith(MISSING_LIBRARY_MARKER))
+        .map((line) => line.slice(MISSING_LIBRARY_MARKER.length).trim());
+    return libraries.length === 0
+        ? { kind: "ok" }
+        : { kind: "missing", libraries };
+}

package/dist/prolog.d.ts

@@ -1,7 +1,14 @@
 import { type PrologErrorRecord } from "./prolog/error-terms.js";
+import { type ResolvedSwipl } from "./prolog/swipl-resolver.js";
 export declare function resolveKbPlPath(): string;
 export interface PrologOptions {
+    /**
+     * Explicit SWI-Prolog executable. When omitted, the executable comes from
+     * the resolver (KIBI_SWIPL, the bundled platform package, then PATH).
+     */
     swiplPath?: string;
+    /** Resolver seam for tests; defaults to the per-process SWI-Prolog resolver. */
+    swiplResolver?: () => ResolvedSwipl;
     timeout?: number;
     /**
      * Force one-shot SWI execution. Production callers are Node-only and keep
@@ -37,7 +44,8 @@ export declare function registerProcessExitOnce(current: (() => void) | null, ha
 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;
+    private explicitSwiplPath;
+    private readonly swiplResolver;
     private timeout;
     private outputBuffer;
     private outputBufferBytes;
@@ -71,6 +79,12 @@ export declare class PrologProcess {
      * restart it (and re-establish its session state) before querying again.
      */
     needsRestart(): boolean;
+    /**
+     * The executable and SWI home to launch. An explicit `swiplPath` is used
+     * verbatim; otherwise the per-process resolver decides, so a missing or
+     * damaged runtime fails with its complete remediation text.
+     */
+    private launchTarget;
     start(): Promise<void>;
     private waitForReady;
     query(goal: string | string[]): Promise<QueryResult>;

package/dist/prolog.d.ts.map

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

package/dist/prolog.js

@@ -19,9 +19,12 @@ import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
+import { performance } from "node:perf_hooks";
 import { fileURLToPath } from "node:url";
 import { getKbPlPathOverride, isPrologDebugEnabled } from "./env.js";
+import { writePerformanceTraceEvent } from "./performance-trace.js";
 import { extractPrologErrorRecord, } from "./prolog/error-terms.js";
+import { resolveSwipl, swiplChildEnv, } from "./prolog/swipl-resolver.js";
 const importMetaDir = path.dirname(fileURLToPath(import.meta.url));
 const DEFAULT_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";
@@ -110,7 +113,8 @@ export function bindProcessExitHandler(current, terminate, on = (event, listener
 }
 export class PrologProcess {
     process = null;
-    swiplPath;
+    explicitSwiplPath;
+    swiplResolver;
     timeout;
     outputBuffer = "";
     outputBufferBytes = 0;
@@ -133,7 +137,8 @@ export class PrologProcess {
     interactiveStarted = false;
     terminationReason = null;
     constructor(options = {}) {
-        this.swiplPath = options.swiplPath || "swipl";
+        this.explicitSwiplPath = options.swiplPath || undefined;
+        this.swiplResolver = options.swiplResolver ?? (() => resolveSwipl());
         this.timeout = options.timeout || 30000;
         this.maxOutputBytes =
             options.maxOutputBytes !== undefined &&
@@ -164,15 +169,31 @@ export class PrologProcess {
     needsRestart() {
         return this.interactiveStarted && !this.isProcessUsable();
     }
+    /**
+     * The executable and SWI home to launch. An explicit `swiplPath` is used
+     * verbatim; otherwise the per-process resolver decides, so a missing or
+     * damaged runtime fails with its complete remediation text.
+     */
+    launchTarget() {
+        const explicit = this.explicitSwiplPath;
+        if (explicit !== undefined)
+            return { bin: explicit, env: {} };
+        const resolved = this.swiplResolver();
+        return { bin: resolved.bin, env: swiplChildEnv(resolved) };
+    }
     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.`);
+        const explicit = this.explicitSwiplPath;
+        if (explicit !== undefined &&
+            !existsSync(explicit) &&
+            explicit !== "swipl") {
+            throw new Error(`SWI-Prolog not found at ${explicit}. Please install SWI-Prolog or check your PATH.`);
         }
+        const launch = this.launchTarget();
         const kbPath = resolveKbPlPath();
         this.interactiveStarted = true;
         this.terminationReason = null;
         this.invalidateCache();
-        this.process = spawn(this.swiplPath, [
+        this.process = spawn(launch.bin, [
             "-g",
             `use_module('${kbPath}'), use_module(library(semweb/rdf_db)), set_prolog_flag(answer_write_options, [max_depth(0), quoted(true)])`,
             "--quiet",
@@ -180,6 +201,7 @@ export class PrologProcess {
             detached: process.platform !== "win32",
             env: {
                 ...process.env,
+                ...launch.env,
                 KIBI_RUNTIME_NAME: process.versions.bun !== undefined ? "bun" : "node",
                 KIBI_RUNTIME_VERSION: process.versions.bun ?? process.versions.node ?? "unknown",
                 KIBI_PACKAGE_VERSIONS: process.env.KIBI_PACKAGE_VERSIONS ?? KIBI_PACKAGE_VERSIONS,
@@ -243,12 +265,23 @@ export class PrologProcess {
     }
     // implements REQ-core-prolog-process-management
     async query(goal) {
+        // A lost interactive session must fail before any cached answer is served.
+        if (!this.useOneShotMode && this.needsRestart()) {
+            throw this.lostProcessError();
+        }
         const isSingleGoal = typeof goal === "string";
         const goalKey = isSingleGoal ? goal : null;
         const cacheable = goalKey !== null && this.isCacheableGoal(goalKey);
         if (cacheable) {
+            const cacheLookupStartedAt = process.env.KIBI_PERF_TIMINGS === "1" ? performance.now() : null;
             const cachedResult = this.cache.get(goalKey);
             if (cachedResult) {
+                if (cacheLookupStartedAt !== null) {
+                    writePerformanceTraceEvent({
+                        kind: "prolog-process-cache-hit",
+                        durationMs: performance.now() - cacheLookupStartedAt,
+                    });
+                }
                 return cachedResult;
             }
         }
@@ -416,13 +449,23 @@ export class PrologProcess {
             releaseQuery = resolve;
         });
         await previousQuery;
+        const tracingEnabled = process.env.KIBI_PERF_TIMINGS === "1";
+        let roundTripStartedAt = null;
         try {
             if (!this.isProcessUsable()) {
                 throw this.lostProcessError();
             }
+            if (tracingEnabled)
+                roundTripStartedAt = performance.now();
             return await runInteractiveQuery();
         }
         finally {
+            if (roundTripStartedAt !== null) {
+                writePerformanceTraceEvent({
+                    kind: "prolog-round-trip",
+                    durationMs: performance.now() - roundTripStartedAt,
+                });
+            }
             releaseQuery();
         }
     }
@@ -534,10 +577,12 @@ export class PrologProcess {
         const packageVersions = process.env.KIBI_PACKAGE_VERSIONS ?? KIBI_PACKAGE_VERSIONS;
         let child;
         try {
-            child = spawn(this.swiplPath, ["-q", "-g", prologGoal, "-t", "halt"], {
+            const launch = this.launchTarget();
+            child = spawn(launch.bin, ["-q", "-g", prologGoal, "-t", "halt"], {
                 detached: process.platform !== "win32",
                 env: {
                     ...process.env,
+                    ...launch.env,
                     KIBI_GOAL: combinedGoal,
                     KIBI_RUNTIME_NAME: runtimeName,
                     KIBI_RUNTIME_VERSION: runtimeVersion,
@@ -820,6 +865,20 @@ export class PrologProcess {
         // 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.
+        // Preserve only bounded identifiers from the formal existence error. Its
+        // context can contain authored dictionaries or query data and is never shown.
+        const existence = errorText.match(/^__KIBI_ERROR__:error\(existence_error\((key|procedure),([^,()\r\n]+)(?:,|\),)/m);
+        const identifier = existence?.[2]?.trim().replace(/^'([^']+)'$/, "$1");
+        if (existence?.[1] === "key" && identifier !== undefined) {
+            if (/^[A-Za-z][A-Za-z0-9_-]{0,95}$/.test(identifier)) {
+                return `Predicate or file not found (missing dictionary key: ${identifier})`;
+            }
+        }
+        if (existence?.[1] === "procedure" && identifier !== undefined) {
+            if (/^(?:[A-Za-z][A-Za-z0-9_]{0,95}:)?[A-Za-z][A-Za-z0-9_]{0,95}\/[0-9]{1,3}$/.test(identifier)) {
+                return `Predicate or file not found (missing procedure: ${identifier})`;
+            }
+        }
         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)";
@@ -861,6 +920,8 @@ export class PrologProcess {
             cleanError.includes("Unknown procedure")) {
             return "Predicate or file not found";
         }
+        if (existence !== null)
+            return "Predicate or file not found";
         if (cleanError.includes("permission_error")) {
             return "Access denied or KB locked";
         }

package/dist/public/diagnostic-usage.d.ts

@@ -13,5 +13,19 @@ export interface DiagnosticUsageInput {
 }
 export declare function diagnosticMutationFingerprint(args: Readonly<Record<string, unknown>>): string;
 export declare function deriveDiagnosticUsageFields(tool: string, args: Readonly<Record<string, unknown>>, telemetry: Readonly<Record<string, unknown>> | null, result: unknown): Record<string, unknown>;
+/**
+ * Whether the operator opted into usage telemetry through the environment.
+ *
+ * `KIBI_DIAGNOSTIC_MODE` is the one opt-in shared with the MCP server, so a
+ * single setting covers both peer surfaces. `KIBI_CLI_DIAGNOSTIC_MODE` is the
+ * older CLI-only spelling and keeps working.
+ */
+export declare function diagnosticEnvOptIn(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * The host that ran this CLI call. Hosts that launch Kibi set `KIBI_HOST`;
+ * Claude Code marks every shell it runs with `CLAUDECODE=1`, which is the
+ * only ambient signal trusted here. Anything else stays `unknown`.
+ */
+export declare function diagnosticCliHost(env?: NodeJS.ProcessEnv): string;
 export declare function appendCliDiagnosticUsage(input: DiagnosticUsageInput): void;
 //# sourceMappingURL=diagnostic-usage.d.ts.map