kibi-runtime 2.0.1 → 2.1.0

package/dist/engine-daemon.js

@@ -4,36 +4,161 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // ../cli/src/engine-daemon.ts
 import { writeFileSync as writeFileSync3 } from "node:fs";
-import path5 from "node:path";
+import path8 from "node:path";
 import { pathToFileURL } from "node:url";
 
 // ../cli/src/engine.ts
-import { createHash as createHash2 } from "node:crypto";
+import { createHash as createHash2, randomUUID } from "node:crypto";
 import {
   chmodSync,
-  closeSync,
-  existsSync as existsSync4,
+  closeSync as closeSync2,
+  existsSync as existsSync6,
   fsyncSync,
+  lstatSync as lstatSync3,
   mkdirSync as mkdirSync2,
-  openSync,
-  readFileSync as readFileSync3,
+  openSync as openSync2,
+  readFileSync as readFileSync4,
   readdirSync as readdirSync2,
-  realpathSync,
+  realpathSync as realpathSync3,
   renameSync,
   rmSync as rmSync2,
-  statSync as statSync2,
+  statSync as statSync4,
   unlinkSync,
   writeFileSync as writeFileSync2
 } from "node:fs";
 import * as net from "node:net";
 import * as os from "node:os";
-import * as path4 from "node:path";
+import * as path7 from "node:path";
+import { performance as performance2 } from "node:perf_hooks";
+
+// ../cli/src/performance-trace.ts
+import { constants } from "node:fs";
+import {
+  closeSync,
+  existsSync,
+  lstatSync,
+  openSync,
+  realpathSync,
+  statSync,
+  writeSync
+} from "node:fs";
+import path from "node:path";
+var KIBI_PERF_TRACE_DIR_ENV = "KIBI_PERF_TRACE_DIR";
+var KIBI_PERF_TIMINGS_ENV = "KIBI_PERF_TIMINGS";
+var KIBI_PERF_TRACE_MAX_EVENTS = 5000;
+var KIBI_PERF_TRACE_MAX_BYTES = 512 * 1024;
+var states = new Map;
+var MAX_DURATION_MS = 60000;
+var TRACE_LIMIT_RESERVE_BYTES = 96;
+function isWithin(parent, candidate) {
+  const relative = path.relative(parent, candidate);
+  return relative === "" || relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+function privateTraceFile() {
+  if (process.env[KIBI_PERF_TIMINGS_ENV] !== "1")
+    return null;
+  const configuredDirectory = process.env[KIBI_PERF_TRACE_DIR_ENV];
+  if (!configuredDirectory || !path.isAbsolute(configuredDirectory))
+    return null;
+  try {
+    const directoryInfo = lstatSync(configuredDirectory);
+    if (!directoryInfo.isDirectory() || directoryInfo.isSymbolicLink()) {
+      return null;
+    }
+    const directory = realpathSync(configuredDirectory);
+    if (path.resolve(configuredDirectory) !== directory)
+      return null;
+    const directoryStats = statSync(directory);
+    if (typeof process.getuid !== "function" || directoryStats.uid !== process.getuid()) {
+      return null;
+    }
+    if ((directoryStats.mode & 63) !== 0) {
+      return null;
+    }
+    const currentDirectory = realpathSync(process.cwd());
+    if (isWithin(currentDirectory, directory))
+      return null;
+    const file = path.join(directory, `kibi-performance-${process.pid}.jsonl`);
+    let state = states.get(file);
+    if (!state) {
+      if (existsSync(file))
+        return null;
+      state = { bytes: 0, events: 0, disabled: false };
+      states.set(file, state);
+    }
+    if (state.disabled)
+      return null;
+    return { file, state };
+  } catch {
+    return null;
+  }
+}
+function writeAll(fd, bytes) {
+  let offset = 0;
+  while (offset < bytes.length) {
+    const written = writeSync(fd, bytes, offset, bytes.length - offset);
+    if (written <= 0)
+      throw new Error("Performance trace write made no progress");
+    offset += written;
+  }
+}
+function appendLine(file, state, line, exclusive) {
+  const fileInfo = existsSync(file) ? lstatSync(file) : null;
+  if (exclusive && fileInfo !== null || !exclusive && (!fileInfo?.isFile() || fileInfo.isSymbolicLink() || fileInfo.size !== state.bytes)) {
+    throw new Error("Performance trace file changed unexpectedly");
+  }
+  const flags = constants.O_WRONLY | constants.O_CREAT | constants.O_APPEND | (constants.O_NOFOLLOW ?? 0) | (exclusive ? constants.O_EXCL : 0);
+  const fd = openSync(file, flags, 384);
+  try {
+    const bytes = Buffer.from(line, "utf8");
+    writeAll(fd, bytes);
+    state.bytes += bytes.length;
+  } finally {
+    closeSync(fd);
+  }
+}
+function appendLimitMarker(file, state, limit) {
+  const marker = `${JSON.stringify({ kind: "trace-limit", pid: process.pid, limit })}
+`;
+  const byteLength = Buffer.byteLength(marker, "utf8");
+  if (state.bytes + byteLength <= KIBI_PERF_TRACE_MAX_BYTES) {
+    appendLine(file, state, marker, state.events === 0);
+  }
+  state.disabled = true;
+}
+function writePerformanceTraceEvent(event) {
+  if (!Number.isFinite(event.durationMs) || event.durationMs < 0 || event.durationMs > MAX_DURATION_MS) {
+    return;
+  }
+  const trace = privateTraceFile();
+  if (!trace)
+    return;
+  const durationMs = Math.round(event.durationMs * 1000) / 1000;
+  const line = `${JSON.stringify({
+    kind: event.kind,
+    durationMs,
+    pid: process.pid
+  })}
+`;
+  const byteLength = Buffer.byteLength(line, "utf8");
+  try {
+    if (trace.state.events >= KIBI_PERF_TRACE_MAX_EVENTS || trace.state.bytes + byteLength > KIBI_PERF_TRACE_MAX_BYTES - TRACE_LIMIT_RESERVE_BYTES) {
+      appendLimitMarker(trace.file, trace.state, trace.state.events >= KIBI_PERF_TRACE_MAX_EVENTS ? "events" : "bytes");
+      return;
+    }
+    appendLine(trace.file, trace.state, line, trace.state.events === 0);
+    trace.state.events += 1;
+  } catch {
+    trace.state.disabled = true;
+  }
+}
 
 // ../cli/src/prolog.ts
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync as existsSync3 } from "node:fs";
 import { createRequire as createRequire2 } from "node:module";
-import path from "node:path";
+import path3 from "node:path";
+import { performance } from "node:perf_hooks";
 import { fileURLToPath } from "node:url";
 
 // ../cli/src/env.ts
@@ -383,9 +508,337 @@ function unquoteAtom(value) {
   return trimmed;
 }
 
+// ../cli/src/prolog/swipl-resolver.ts
+import { execFileSync, spawnSync } from "node:child_process";
+import {
+  constants as constants2,
+  accessSync,
+  existsSync as existsSync2,
+  readFileSync,
+  statSync as statSync2
+} from "node:fs";
+import path2 from "node:path";
+import {
+  BUNDLED_BINARY_PATH,
+  MANIFEST_FILE,
+  PLATFORM_PACKAGES,
+  locatePlatformPackage,
+  platformKey,
+  sha256File,
+  validateBuildManifest
+} from "kibi-swipl";
+var MINIMUM_SWIPL_MAJOR = 9;
+
+class SwiplResolutionError extends Error {
+  code;
+  platform;
+  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;
+  try {
+    const report = process.report?.getReport?.();
+    if (report !== undefined) {
+      return typeof report.header?.glibcVersionRuntime === "string";
+    }
+  } catch {}
+  return !["/lib/ld-musl-x86_64.so.1", "/lib/ld-musl-aarch64.so.1"].some((loader) => existsSync2(loader));
+}
+function defaultRunVersion(bin) {
+  return execFileSync(bin, ["--version"], {
+    encoding: "utf8",
+    timeout: 1e4,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+}
+function defaultDeps() {
+  return {
+    platform: process.platform,
+    arch: process.arch,
+    glibc: detectGlibc(),
+    locatePackage: (name) => locatePlatformPackage(name),
+    runVersion: defaultRunVersion
+  };
+}
+function parseSwiplVersion(output) {
+  const match = /version\s+(\d+)\.(\d+)(?:\.(\d+))?/i.exec(output);
+  if (match === null)
+    return;
+  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 (!statSync2(candidate).isFile())
+      return false;
+    accessSync(candidate, constants2.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 = path2.join(packageDir, MANIFEST_FILE);
+  const binary = path2.join(packageDir, BUNDLED_BINARY_PATH);
+  if (!existsSync2(manifestPath)) {
+    if (!existsSync2(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(path2.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 = path2.join(packageDir, checked.home);
+  let homeIsDirectory = false;
+  try {
+    homeIsDirectory = statSync2(home).isDirectory();
+  } catch {}
+  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(path2.delimiter)) {
+    if (directory === "" || !path2.isAbsolute(directory))
+      continue;
+    const candidate = path2.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 (!path2.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(`
+`), platform, packageName);
+}
+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(`
+`), hostLabel(deps), bundle.packageName);
+    }
+  }
+  const lookup = findOnPath(env, deps);
+  if (lookup.kind === "ok")
+    return lookup.resolved;
+  throw notFoundError(deps, bundle, lookup);
+}
+var cache = new Map;
+function resolveSwipl(env = process.env) {
+  const key = `${env.KIBI_SWIPL ?? ""}\x00${env.PATH ?? ""}`;
+  const cached = cache.get(key);
+  if (cached !== undefined)
+    return cached;
+  const resolved = resolveSwiplWith(env, defaultDeps());
+  cache.set(key, resolved);
+  return resolved;
+}
+function swiplIdentity(resolved) {
+  return `${resolved.bin}@${resolved.version}`;
+}
+function swiplChildEnv(resolved) {
+  return resolved.home === undefined ? {} : { SWI_HOME_DIR: resolved.home };
+}
+
 // ../cli/src/prolog.ts
-var importMetaDir = path.dirname(fileURLToPath(import.meta.url));
-var PROLOG_OUTPUT_MAX_BUFFER_BYTES = 8 * 1024 * 1024;
+var importMetaDir = path3.dirname(fileURLToPath(import.meta.url));
+var DEFAULT_PROLOG_OUTPUT_MAX_BUFFER_BYTES = 8 * 1024 * 1024;
 var PROLOG_OUTPUT_OVERFLOW_ERROR = "Query exceeded bounded Prolog output capacity (ENOBUFS); narrow the operation or reduce stored entity size";
 var INTERACTIVE_QUERY_FRAME_END = "__KIBI_QUERY_FRAME_END__";
 var require2 = createRequire2(import.meta.url);
@@ -398,9 +851,9 @@ function packageVersion(packagePath) {
   }
 }
 var KIBI_PACKAGE_VERSIONS = [
-  `kibi-cli@${packageVersion(path.join(importMetaDir, "..", "package.json"))}`,
-  `kibi-core@${packageVersion(path.join(importMetaDir, "..", "..", "core", "package.json"))}`,
-  `kibi-mcp@${packageVersion(path.join(importMetaDir, "..", "..", "mcp", "package.json"))}`
+  `kibi-cli@${packageVersion(path3.join(importMetaDir, "..", "package.json"))}`,
+  `kibi-core@${packageVersion(path3.join(importMetaDir, "..", "..", "core", "package.json"))}`,
+  `kibi-mcp@${packageVersion(path3.join(importMetaDir, "..", "..", "mcp", "package.json"))}`
 ].join(",");
 function resolveKbPlPath() {
   const overrideKbPath = getKbPlPathOverride();
@@ -412,20 +865,30 @@ function resolveKbPlPath() {
       return require2.resolve("kibi-core/src/kb.pl");
     } catch {
       const coreMain = require2.resolve("kibi-core");
-      const coreDir = path.dirname(coreMain);
-      return path.join(coreDir, "src", "kb.pl");
+      const coreDir = path3.dirname(coreMain);
+      return path3.join(coreDir, "src", "kb.pl");
     }
   } catch {}
   let currentDir = importMetaDir;
-  while (currentDir !== path.dirname(currentDir)) {
-    const candidate = path.join(currentDir, "packages", "core", "src", "kb.pl");
-    if (existsSync(candidate)) {
+  while (currentDir !== path3.dirname(currentDir)) {
+    const candidate = path3.join(currentDir, "packages", "core", "src", "kb.pl");
+    if (existsSync3(candidate)) {
       return candidate;
     }
-    currentDir = path.dirname(currentDir);
+    currentDir = path3.dirname(currentDir);
   }
   throw new Error("Unable to resolve kb.pl. Expected kibi-core to be installed (node_modules) " + "or to be running inside the monorepo checkout.");
 }
+
+class PrologProcessTerminatedError extends Error {
+  code = "prolog_process_terminated";
+  reason;
+  constructor(reason) {
+    super(`Kibi Prolog process is no longer running (${reason}); the interactive session and its attached KB were lost. The owning engine must restart it before serving more queries — run 'kibi engine stop' and retry if this persists.`);
+    this.name = "PrologProcessTerminatedError";
+    this.reason = reason;
+  }
+}
 function registerProcessExitOnce(current, handler, on = (event, listener) => process.on(event, listener)) {
   if (current)
     return current;
@@ -440,7 +903,8 @@ function bindProcessExitHandler(current, terminate, on = (event, listener) => pr
 
 class PrologProcess {
   process = null;
-  swiplPath;
+  explicitSwiplPath;
+  swiplResolver;
   timeout;
   outputBuffer = "";
   outputBufferBytes = 0;
@@ -454,20 +918,43 @@ class PrologProcess {
   useOneShotMode;
   attachedKbPath = null;
   onProcessExit = null;
+  maxOutputBytes;
+  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 && Number.isInteger(options.maxOutputBytes) && options.maxOutputBytes > 0 ? options.maxOutputBytes : DEFAULT_PROLOG_OUTPUT_MAX_BUFFER_BYTES;
     this.useOneShotMode = options.oneShot ?? false;
   }
   attachProcessExitHandler(on = (event, listener) => process.on(event, listener)) {
     this.onProcessExit = bindProcessExitHandler(this.onProcessExit, () => this.terminate(), on);
   }
+  get oneShotMode() {
+    return this.useOneShotMode || !this.interactiveStarted;
+  }
+  needsRestart() {
+    return this.interactiveStarted && !this.isProcessUsable();
+  }
+  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 && !existsSync3(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.process = spawn(this.swiplPath, [
+    this.interactiveStarted = true;
+    this.terminationReason = null;
+    this.invalidateCache();
+    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"
@@ -475,6 +962,7 @@ 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
@@ -490,6 +978,12 @@ class PrologProcess {
     this.process.stderr.on("data", (chunk) => {
       this.appendErrorChunk(chunk);
     });
+    const child = this.process;
+    child.stdin?.on("error", (error) => {
+      if (this.process === child) {
+        this.terminationReason ??= `stdin ${error.code ?? "error"}`;
+      }
+    });
     this.process.stdin.write(`true.
 `);
     this.attachProcessExitHandler();
@@ -517,12 +1011,22 @@ class PrologProcess {
     this.clearQueryBuffers();
   }
   async query(goal) {
+    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;
       }
     }
@@ -543,10 +1047,10 @@ class PrologProcess {
       return this.query(batchGoal);
     }
     if (!this.isProcessUsable()) {
-      if (this.process === null) {
+      if (this.process === null && !this.interactiveStarted) {
         return this.execOneShot(goal, this.attachedKbPath);
       }
-      throw new Error("Prolog process not started");
+      throw this.lostProcessError();
     }
     const runInteractiveQuery = async () => {
       this.clearQueryBuffers();
@@ -576,6 +1080,7 @@ writeln('${INTERACTIVE_QUERY_FRAME_END}').
             console.error(`[prolog debug] runtime=${runtime ?? "unknown"} packages=${process.env.KIBI_PACKAGE_VERSIONS ?? KIBI_PACKAGE_VERSIONS}`);
           }
           settled = true;
+          this.terminationReason = `query timeout: ${goalLabel}`;
           this.terminate().finally(() => {
             reject(new Error(msg));
           });
@@ -587,6 +1092,7 @@ writeln('${INTERACTIVE_QUERY_FRAME_END}').
           if (this.outputOverflowed) {
             clearTimeout(timeoutId);
             settled = true;
+            this.terminationReason = `output overflow (ENOBUFS): ${goalLabel}`;
             this.terminate().finally(() => {
               resolve({
                 success: false,
@@ -599,6 +1105,7 @@ writeln('${INTERACTIVE_QUERY_FRAME_END}').
           if (!this.isProcessUsable()) {
             clearTimeout(timeoutId);
             settled = true;
+            this.terminationReason ??= `process exited during query: ${goalLabel}`;
             resolve({
               success: false,
               bindings: {},
@@ -664,12 +1171,22 @@ writeln('${INTERACTIVE_QUERY_FRAME_END}').
       releaseQuery = resolve;
     });
     await previousQuery;
+    const tracingEnabled = process.env.KIBI_PERF_TIMINGS === "1";
+    let roundTripStartedAt = null;
     try {
       if (!this.isProcessUsable()) {
-        throw new Error("Prolog process not started");
+        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();
     }
   }
@@ -751,10 +1268,12 @@ writeln('${INTERACTIVE_QUERY_FRAME_END}').
     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,
@@ -784,7 +1303,7 @@ writeln('${INTERACTIVE_QUERY_FRAME_END}').
       if (outputOverflowed)
         return;
       const bytes = target === "stdout" ? outputBytes : errorBytes;
-      const remaining = PROLOG_OUTPUT_MAX_BUFFER_BYTES - bytes;
+      const remaining = this.maxOutputBytes - bytes;
       if (chunk.byteLength > remaining) {
         const clipped = chunk.subarray(0, Math.max(0, remaining)).toString();
         if (target === "stdout")
@@ -897,10 +1416,10 @@ writeln('${INTERACTIVE_QUERY_FRAME_END}').
   appendOutputChunk(chunk) {
     if (this.outputOverflowed)
       return;
-    const remaining = PROLOG_OUTPUT_MAX_BUFFER_BYTES - this.outputBufferBytes;
+    const remaining = this.maxOutputBytes - this.outputBufferBytes;
     if (chunk.byteLength > remaining) {
       this.outputBuffer += chunk.subarray(0, remaining).toString();
-      this.outputBufferBytes = PROLOG_OUTPUT_MAX_BUFFER_BYTES;
+      this.outputBufferBytes = this.maxOutputBytes;
       this.outputOverflowed = true;
       return;
     }
@@ -910,10 +1429,10 @@ writeln('${INTERACTIVE_QUERY_FRAME_END}').
   appendErrorChunk(chunk) {
     if (this.outputOverflowed)
       return;
-    const remaining = PROLOG_OUTPUT_MAX_BUFFER_BYTES - this.errorBufferBytes;
+    const remaining = this.maxOutputBytes - this.errorBufferBytes;
     if (chunk.byteLength > remaining) {
       this.errorBuffer += chunk.subarray(0, remaining).toString();
-      this.errorBufferBytes = PROLOG_OUTPUT_MAX_BUFFER_BYTES;
+      this.errorBufferBytes = this.maxOutputBytes;
       this.outputOverflowed = true;
       return;
     }
@@ -1010,6 +1529,18 @@ writeln('${INTERACTIVE_QUERY_FRAME_END}').
     return { message: this.translateError(errorText) };
   }
   translateError(errorText) {
+    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)";
@@ -1040,6 +1571,8 @@ writeln('${INTERACTIVE_QUERY_FRAME_END}').
     if (cleanError.includes("existence_error") || 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";
     }
@@ -1059,7 +1592,16 @@ writeln('${INTERACTIVE_QUERY_FRAME_END}').
   getPid() {
     return this.process?.pid || 0;
   }
+  lostProcessError() {
+    if (!this.interactiveStarted) {
+      return new Error("Prolog process not started");
+    }
+    return new PrologProcessTerminatedError(this.terminationReason ?? "process exited");
+  }
   async terminate() {
+    if (this.interactiveStarted) {
+      this.terminationReason ??= "terminated";
+    }
     if (this.terminationPromise) {
       await this.terminationPromise;
       return;
@@ -1090,8 +1632,8 @@ writeln('${INTERACTIVE_QUERY_FRAME_END}').
 }
 
 // ../cli/src/prolog/store-lock.ts
-import { existsSync as existsSync2, rmSync } from "node:fs";
-import { readFileSync } from "node:fs";
+import { existsSync as existsSync4, rmSync } from "node:fs";
+import { readFileSync as readFileSync2 } from "node:fs";
 import { dirname, join } from "node:path";
 var cachedBootId;
 function currentBootId() {
@@ -1102,7 +1644,7 @@ function currentBootId() {
     return cachedBootId;
   }
   try {
-    const raw = readFileSync("/proc/sys/kernel/random/boot_id", "utf8");
+    const raw = readFileSync2("/proc/sys/kernel/random/boot_id", "utf8");
     cachedBootId = raw.trim();
   } catch {
     cachedBootId = null;
@@ -1141,7 +1683,7 @@ function breakStoreLock(rdfDirectory) {
     join(dirname(rdfDirectory), ".kibi-lock-owner.json")
   ];
   for (const candidate of candidates) {
-    if (existsSync2(candidate)) {
+    if (existsSync4(candidate)) {
       rmSync(candidate, { force: true });
     }
   }
@@ -1195,31 +1737,31 @@ import {
   execFileSync as rawExecFileSync,
   execSync as rawExecSync
 } from "node:child_process";
-import * as path3 from "node:path";
+import * as path5 from "node:path";
 
 // ../cli/src/utils/branch-store-locator.ts
 import { createHash } from "node:crypto";
 import {
-  existsSync as existsSync3,
+  existsSync as existsSync5,
   mkdirSync,
-  readFileSync as readFileSync2,
+  readFileSync as readFileSync3,
   readdirSync,
-  statSync,
+  statSync as statSync3,
   writeFileSync
 } from "node:fs";
-import path2 from "node:path";
+import path4 from "node:path";
 var BRANCH_STORE_MANIFEST_VERSION = 1;
 function branchStoreKey(branch) {
   return createHash("sha256").update(branch, "utf8").digest("hex");
 }
 function branchStoresRoot(workspaceRoot) {
-  return path2.join(path2.resolve(workspaceRoot), ".kb", "branches");
+  return path4.join(path4.resolve(workspaceRoot), ".kb", "branches");
 }
 function branchStorePath(workspaceRoot, branch) {
-  return path2.join(branchStoresRoot(workspaceRoot), branchStoreKey(branch));
+  return path4.join(branchStoresRoot(workspaceRoot), branchStoreKey(branch));
 }
 function branchStoreManifestPath(storePath) {
-  return path2.join(storePath, "branch.json");
+  return path4.join(storePath, "branch.json");
 }
 function expectedBranchStoreManifest(branch) {
   return {
@@ -1230,10 +1772,10 @@ function expectedBranchStoreManifest(branch) {
 }
 function readBranchStoreManifest(storePath) {
   const manifestPath = branchStoreManifestPath(storePath);
-  if (!existsSync3(manifestPath))
+  if (!existsSync5(manifestPath))
     return null;
   try {
-    const parsed = JSON.parse(readFileSync2(manifestPath, "utf8"));
+    const parsed = JSON.parse(readFileSync3(manifestPath, "utf8"));
     if (parsed.version !== BRANCH_STORE_MANIFEST_VERSION || typeof parsed.branch !== "string" || typeof parsed.key !== "string") {
       return null;
     }
@@ -1249,7 +1791,7 @@ function readBranchStoreManifest(storePath) {
 function branchStoreManifestMatches(storePath, branch) {
   const manifest = readBranchStoreManifest(storePath);
   const expected = expectedBranchStoreManifest(branch);
-  return manifest !== null && manifest.version === expected.version && manifest.branch === expected.branch && manifest.key === expected.key && path2.basename(storePath) === expected.key;
+  return manifest !== null && manifest.version === expected.version && manifest.branch === expected.branch && manifest.key === expected.key && path4.basename(storePath) === expected.key;
 }
 function ensureBranchStoreManifest(workspaceRoot, branch) {
   const storePath = branchStorePath(workspaceRoot, branch);
@@ -1260,7 +1802,7 @@ function ensureBranchStoreManifest(workspaceRoot, branch) {
     throw new Error(`Branch store identity mismatch at ${storePath}; refusing to attach it to '${branch}'.`);
   }
   if (existing === null) {
-    if (existsSync3(manifestPath)) {
+    if (existsSync5(manifestPath)) {
       throw new Error(`Branch store manifest is invalid at ${manifestPath}; refusing to overwrite it.`);
     }
     const entries = readdirSync(storePath);
@@ -1274,7 +1816,7 @@ function ensureBranchStoreManifest(workspaceRoot, branch) {
 }
 
 // ../cli/src/utils/branch-resolver.ts
-var defaultDeps = {
+var defaultDeps2 = {
   execSync: rawExecSync,
   execFileSync: rawExecFileSync
 };
@@ -1294,7 +1836,7 @@ function isValidBranchName(name) {
     const codePoint = character.codePointAt(0) ?? 0;
     return codePoint <= 32 || codePoint === 127;
   });
-  if (name.includes("..") || path3.isAbsolute(name) || name.startsWith("/")) {
+  if (name.includes("..") || path5.isAbsolute(name) || name.startsWith("/")) {
     return false;
   }
   if (name.includes("//") || name.endsWith("/") || name.endsWith(".") || name.includes("\\") || name.startsWith("-") || name.includes("@{") || name.includes("..") || hasControlCharacter || /[~^:?*\[\]]/.test(name)) {
@@ -1305,7 +1847,7 @@ function isValidBranchName(name) {
     return false;
   }
   try {
-    defaultDeps.execFileSync("git", ["check-ref-format", "--branch", name], {
+    defaultDeps2.execFileSync("git", ["check-ref-format", "--branch", name], {
       stdio: ["ignore", "ignore", "ignore"],
       timeout: 5000
     });
@@ -1315,10 +1857,43 @@ function isValidBranchName(name) {
   }
 }
 
+// ../cli/src/utils/canonical-path.ts
+import { lstatSync as lstatSync2, realpathSync as realpathSync2 } from "node:fs";
+import path6 from "node:path";
+function canonicalFilesystemPath(candidate) {
+  let existing = path6.resolve(candidate);
+  const missing = [];
+  for (;; ) {
+    try {
+      return path6.resolve(realpathSync2.native(existing), ...missing);
+    } catch (error) {
+      if (error.code !== "ENOENT")
+        throw error;
+      let entry;
+      try {
+        entry = lstatSync2(existing);
+      } catch (statError) {
+        if (statError.code !== "ENOENT")
+          throw statError;
+      }
+      if (entry !== undefined)
+        throw error;
+      const parent = path6.dirname(existing);
+      if (parent === existing)
+        throw error;
+      missing.unshift(path6.basename(existing));
+      existing = parent;
+    }
+  }
+}
+
 // ../cli/src/engine.ts
 var ENGINE_PROTOCOL_VERSION = 1;
 var ENGINE_IDLE_TIMEOUT_MS = 10 * 60 * 1000;
 var ENGINE_PACKAGE_VERSIONS = process.env.KIBI_PACKAGE_VERSIONS ?? "unknown";
+function engineSwiplIdentity() {
+  return swiplIdentity(resolveSwipl());
+}
 var ENGINE_QUERY_CACHE_MAX_ENTRIES = 128;
 var ENGINE_QUERY_CACHE_MAX_RESULT_BYTES = 8 * 1024 * 1024;
 var ENGINE_FRESHNESS_CACHE_MS = 100;
@@ -1329,18 +1904,18 @@ function requestEngineSignalShutdown(shutdown) {
   };
 }
 function readJournalGeneration(branchPath) {
-  const currentPath = path4.join(branchPath, "CURRENT");
-  if (!existsSync4(currentPath))
+  const currentPath = path7.join(branchPath, "CURRENT");
+  if (!existsSync6(currentPath))
     return "";
-  return readFileSync3(currentPath, "utf8").trim();
+  return readFileSync4(currentPath, "utf8").trim();
 }
 function readEngineAttachmentIdentity(branchPath) {
-  if (!existsSync4(branchPath))
+  if (!existsSync6(branchPath))
     return null;
-  const stats = statSync2(branchPath);
-  let resolved = path4.resolve(branchPath);
+  const stats = statSync4(branchPath);
+  let resolved = path7.resolve(branchPath);
   try {
-    resolved = realpathSync(branchPath);
+    resolved = realpathSync3(branchPath);
   } catch {}
   return {
     path: resolved,
@@ -1448,11 +2023,12 @@ function frame(value) {
   header.writeUInt32BE(payload.byteLength, 0);
   return Buffer.concat([header, payload]);
 }
+function ignoreWriteFailure() {}
 function writeSocketFrame(socket, value) {
   if (socket.destroyed || !socket.writable)
     return;
   try {
-    socket.write(frame(value));
+    socket.write(frame(value), ignoreWriteFailure);
   } catch {}
 }
 function parseFrames(buffer, onFrame) {
@@ -1471,42 +2047,85 @@ function parseFrames(buffer, onFrame) {
   return buffer.subarray(cursor);
 }
 function runtimeDirectory() {
-  const configured = process.env.KIBI_RUNTIME_DIR ?? process.env.XDG_RUNTIME_DIR ?? path4.join(os.tmpdir(), "kibi-runtime");
-  const candidates = [configured, path4.join(os.tmpdir(), "kibi-runtime")];
+  const configured = process.env.KIBI_RUNTIME_DIR ?? process.env.XDG_RUNTIME_DIR ?? path7.join(os.tmpdir(), "kibi-runtime");
+  if (process.platform === "win32") {
+    for (const candidate of [
+      configured,
+      path7.join(os.tmpdir(), "kibi-runtime")
+    ]) {
+      try {
+        mkdirSync2(candidate, { recursive: true, mode: 448 });
+        const probe = path7.join(candidate, `.kibi-write-${process.pid}`);
+        writeFileSync2(probe, "", { mode: 384 });
+        unlinkSync(probe);
+        return candidate;
+      } catch {}
+    }
+    throw new Error("Unable to create a writable Kibi engine runtime directory");
+  }
+  const euid = process.geteuid?.();
+  if (euid === undefined)
+    throw new Error("Kibi engine runtime euid unavailable");
+  let configuredIdentity;
+  try {
+    configuredIdentity = canonicalFilesystemPath(configured);
+  } catch {
+    configuredIdentity = path7.resolve(configured);
+  }
+  const configuredKey = createHash2("sha256").update(configuredIdentity).digest("hex").slice(0, 32);
+  const candidates = [
+    configured,
+    path7.join("/tmp", `kb-${euid}-${configuredKey}`)
+  ];
+  const maximumBytes = process.platform === "linux" ? 107 : 103;
+  const socketName = `kibi-${"0".repeat(32)}.sock`;
   for (const candidate of candidates) {
     try {
+      try {
+        if (lstatSync3(candidate).isSymbolicLink())
+          continue;
+      } catch (error) {
+        if (error.code !== "ENOENT")
+          throw error;
+      }
       mkdirSync2(candidate, { recursive: true, mode: 448 });
-      const probe = path4.join(candidate, `.kibi-write-${process.pid}`);
-      writeFileSync2(probe, "", { mode: 384 });
+      const directory = lstatSync3(candidate);
+      if (!directory.isDirectory() || directory.uid !== euid || (directory.mode & 63) !== 0)
+        continue;
+      const canonical = canonicalFilesystemPath(candidate);
+      if (Buffer.byteLength(path7.join(canonical, socketName), "utf8") > maximumBytes)
+        continue;
+      const probe = path7.join(canonical, `.kibi-write-${randomUUID()}`);
+      writeFileSync2(probe, "", { mode: 384, flag: "wx" });
       unlinkSync(probe);
-      return candidate;
+      return canonical;
     } catch {}
   }
   throw new Error("Unable to create a writable Kibi engine runtime directory");
 }
 function fsyncPath(filePath) {
-  if (!existsSync4(filePath))
+  if (!existsSync6(filePath))
     return;
   let descriptor = null;
   try {
-    descriptor = openSync(filePath, "r");
+    descriptor = openSync2(filePath, "r");
     fsyncSync(descriptor);
   } finally {
     if (descriptor !== null)
-      closeSync(descriptor);
+      closeSync2(descriptor);
   }
 }
 function fsyncJournaledBranchStore(branchPath) {
-  const rdfRoot = path4.join(branchPath, "rdf");
+  const rdfRoot = path7.join(branchPath, "rdf");
   const directories = [];
-  const pending = existsSync4(rdfRoot) ? [rdfRoot] : [];
+  const pending = existsSync6(rdfRoot) ? [rdfRoot] : [];
   while (pending.length > 0) {
     const directory = pending.pop();
     if (directory === undefined)
       break;
     directories.push(directory);
     for (const entry of readdirSync2(directory, { withFileTypes: true })) {
-      const entryPath = path4.join(directory, entry.name);
+      const entryPath = path7.join(directory, entry.name);
       if (entry.isDirectory())
         pending.push(entryPath);
       else if (entry.isFile() && entry.name !== "lock")
@@ -1514,7 +2133,7 @@ function fsyncJournaledBranchStore(branchPath) {
     }
   }
   for (const metadata of ["CURRENT", "storage.json", "kb.rdf"]) {
-    fsyncPath(path4.join(branchPath, metadata));
+    fsyncPath(path7.join(branchPath, metadata));
   }
   if (process.platform !== "win32") {
     for (const directory of directories.reverse())
@@ -1523,33 +2142,27 @@ function fsyncJournaledBranchStore(branchPath) {
   }
 }
 function engineSocketPath(workspaceRoot, branch) {
-  const canonicalRoot = (() => {
-    try {
-      return realpathSync(workspaceRoot);
-    } catch {
-      return path4.resolve(workspaceRoot);
-    }
-  })();
+  const canonicalRoot = canonicalFilesystemPath(workspaceRoot);
   const key = createHash2("sha256").update(`${canonicalRoot}\x00${branch}`).digest("hex").slice(0, 32);
   if (process.platform === "win32") {
     return `\\\\.\\pipe\\kibi-${key}`;
   }
-  return path4.join(runtimeDirectory(), `kibi-${key}.sock`);
+  return path7.join(runtimeDirectory(), `kibi-${key}.sock`);
 }
 function enginePidPath(workspaceRoot, branch) {
   const socket = engineSocketPath(workspaceRoot, branch);
   if (process.platform === "win32") {
-    return path4.join(runtimeDirectory(), `kibi-${createHash2("sha256").update(`${path4.resolve(workspaceRoot)}\x00${branch}`).digest("hex")}.pid`);
+    return path7.join(runtimeDirectory(), `kibi-${createHash2("sha256").update(`${path7.resolve(workspaceRoot)}\x00${branch}`).digest("hex")}.pid`);
   }
   return `${socket}.pid`;
 }
 function recoverStaleJournalLock(branchPath) {
-  const lockPath = path4.join(branchPath, "rdf", "lock");
-  if (!existsSync4(lockPath))
+  const lockPath = path7.join(branchPath, "rdf", "lock");
+  if (!existsSync6(lockPath))
     return;
   let contents = "";
   try {
-    contents = readFileSync3(lockPath, "utf8");
+    contents = readFileSync4(lockPath, "utf8");
   } catch {
     return;
   }
@@ -1597,27 +2210,27 @@ function connectSocket(socketPath, timeoutMs) {
 }
 async function ensureJournaledBranchStoreAsync(branchPath) {
   mkdirSync2(branchPath, { recursive: true });
-  const markerPath = path4.join(branchPath, "storage.json");
-  const marker = existsSync4(markerPath) ? readFileSync3(markerPath, "utf8") : "";
+  const markerPath = path7.join(branchPath, "storage.json");
+  const marker = existsSync6(markerPath) ? readFileSync4(markerPath, "utf8") : "";
   if (marker.includes("kibi.rdf-journal.v1")) {
-    const rdfDirectory = path4.join(branchPath, "rdf");
-    const currentPath = path4.join(branchPath, "CURRENT");
-    const sentinelPath = path4.join(branchPath, "kb.rdf");
-    if (!existsSync4(rdfDirectory) || !existsSync4(currentPath)) {
+    const rdfDirectory = path7.join(branchPath, "rdf");
+    const currentPath = path7.join(branchPath, "CURRENT");
+    const sentinelPath = path7.join(branchPath, "kb.rdf");
+    if (!existsSync6(rdfDirectory) || !existsSync6(currentPath)) {
       recoverInterruptedGeneration(branchPath);
-      if (existsSync4(rdfDirectory) && existsSync4(currentPath)) {
+      if (existsSync6(rdfDirectory) && existsSync6(currentPath)) {
         recoverStaleJournalLock(branchPath);
         archiveLegacyFiles(branchPath);
-        if (!existsSync4(sentinelPath)) {
+        if (!existsSync6(sentinelPath)) {
           writeFileSync2(sentinelPath, `KIBI_STORAGE_FORMAT=kibi.rdf-journal.v1
 `, { mode: 384 });
         }
         return;
       }
-      const legacyRdf = path4.join(branchPath, "kb.rdf");
-      const legacyAudit = path4.join(branchPath, "audit.log");
-      const legacyContents = existsSync4(legacyRdf) ? readFileSync3(legacyRdf, "utf8") : "";
-      if (existsSync4(legacyAudit) || existsSync4(legacyRdf) && !legacyContents.includes("kibi.rdf-journal.v1")) {
+      const legacyRdf = path7.join(branchPath, "kb.rdf");
+      const legacyAudit = path7.join(branchPath, "audit.log");
+      const legacyContents = existsSync6(legacyRdf) ? readFileSync4(legacyRdf, "utf8") : "";
+      if (existsSync6(legacyAudit) || existsSync6(legacyRdf) && !legacyContents.includes("kibi.rdf-journal.v1")) {
         rmSync2(rdfDirectory, { recursive: true, force: true });
         rmSync2(currentPath, { force: true });
         rmSync2(markerPath, { force: true });
@@ -1627,36 +2240,36 @@ async function ensureJournaledBranchStoreAsync(branchPath) {
     } else {
       recoverStaleJournalLock(branchPath);
       archiveLegacyFiles(branchPath);
-      if (!existsSync4(sentinelPath)) {
+      if (!existsSync6(sentinelPath)) {
         writeFileSync2(sentinelPath, `KIBI_STORAGE_FORMAT=kibi.rdf-journal.v1
 `, { mode: 384 });
       }
       return;
     }
   }
-  const legacyRdf = path4.join(branchPath, "kb.rdf");
-  const legacyAudit = path4.join(branchPath, "audit.log");
-  if (!existsSync4(legacyRdf) && !existsSync4(legacyAudit)) {
-    mkdirSync2(path4.join(branchPath, "rdf"), { recursive: true });
+  const legacyRdf = path7.join(branchPath, "kb.rdf");
+  const legacyAudit = path7.join(branchPath, "audit.log");
+  if (!existsSync6(legacyRdf) && !existsSync6(legacyAudit)) {
+    mkdirSync2(path7.join(branchPath, "rdf"), { recursive: true });
     writeFileSync2(markerPath, `{"format":"kibi.rdf-journal.v1","schemaVersion":1}
 `, { mode: 384 });
-    writeFileSync2(path4.join(branchPath, "CURRENT"), `generation-1:0
+    writeFileSync2(path7.join(branchPath, "CURRENT"), `generation-1:0
 `, {
       mode: 384
     });
-    writeFileSync2(path4.join(branchPath, "kb.rdf"), `KIBI_STORAGE_FORMAT=kibi.rdf-journal.v1
+    writeFileSync2(path7.join(branchPath, "kb.rdf"), `KIBI_STORAGE_FORMAT=kibi.rdf-journal.v1
 `, { mode: 384 });
     return;
   }
-  if (existsSync4(legacyRdf)) {
-    const legacyContents = readFileSync3(legacyRdf, "utf8");
+  if (existsSync6(legacyRdf)) {
+    const legacyContents = readFileSync4(legacyRdf, "utf8");
     if (!/<rdf:RDF(?:\s|>)/.test(legacyContents)) {
       throw new Error(`Legacy Kibi store is corrupt at ${legacyRdf}: expected RDF/XML root`);
     }
   }
-  const parent = path4.dirname(branchPath);
-  const migrationKey = createHash2("sha256").update(path4.resolve(branchPath)).digest("hex").slice(0, 16);
-  const staging = path4.join(parent, `.${migrationKey}.migration.${process.pid}.${Date.now()}`);
+  const parent = path7.dirname(branchPath);
+  const migrationKey = createHash2("sha256").update(path7.resolve(branchPath)).digest("hex").slice(0, 16);
+  const staging = path7.join(parent, `.${migrationKey}.migration.${process.pid}.${Date.now()}`);
   mkdirSync2(staging, { recursive: true, mode: 448 });
   const testOneShot = false;
   const migrator = new PrologProcess({
@@ -1684,35 +2297,35 @@ async function ensureJournaledBranchStoreAsync(branchPath) {
     await migrator.terminate();
   }
   for (const file of ["rdf", "storage.json", "CURRENT"]) {
-    const source = path4.join(staging, file);
-    if (!existsSync4(source))
+    const source = path7.join(staging, file);
+    if (!existsSync6(source))
       continue;
-    const target = path4.join(branchPath, file);
-    if (existsSync4(target))
+    const target = path7.join(branchPath, file);
+    if (existsSync6(target))
       rmSync2(target, { recursive: true, force: true });
     renameSync(source, target);
   }
   archiveLegacyFiles(branchPath);
-  writeFileSync2(path4.join(branchPath, "kb.rdf"), `KIBI_STORAGE_FORMAT=kibi.rdf-journal.v1
+  writeFileSync2(path7.join(branchPath, "kb.rdf"), `KIBI_STORAGE_FORMAT=kibi.rdf-journal.v1
 `, { mode: 384 });
   fsyncJournaledBranchStore(branchPath);
   rmSync2(staging, { recursive: true, force: true });
 }
 function archiveLegacyFiles(branchPath) {
-  const legacyDir = path4.join(branchPath, "legacy");
+  const legacyDir = path7.join(branchPath, "legacy");
   mkdirSync2(legacyDir, { recursive: true, mode: 448 });
   for (const file of ["kb.rdf", "audit.log"]) {
-    const source = path4.join(branchPath, file);
-    if (!existsSync4(source))
+    const source = path7.join(branchPath, file);
+    if (!existsSync6(source))
       continue;
     if (file === "kb.rdf") {
-      const contents = readFileSync3(source, "utf8");
+      const contents = readFileSync4(source, "utf8");
       if (contents.includes("kibi.rdf-journal.v1"))
         continue;
     }
-    const destination = path4.join(legacyDir, file);
-    if (existsSync4(destination)) {
-      renameSync(source, path4.join(legacyDir, `${file}.recovery.${Date.now()}`));
+    const destination = path7.join(legacyDir, file);
+    if (existsSync6(destination)) {
+      renameSync(source, path7.join(legacyDir, `${file}.recovery.${Date.now()}`));
     } else {
       renameSync(source, destination);
     }
@@ -1728,62 +2341,123 @@ function recoverInterruptedGeneration(branchPath) {
   const newest = (prefix) => {
     const candidates = entries.filter((entry) => entry.startsWith(prefix)).sort().reverse();
     const candidate = candidates[0];
-    return candidate === undefined ? null : path4.join(branchPath, candidate);
+    return candidate === undefined ? null : path7.join(branchPath, candidate);
   };
   const oldRdf = newest("rdf.old.");
   const oldCurrent = newest("CURRENT.old.");
-  const rdfPath = path4.join(branchPath, "rdf");
-  const currentPath = path4.join(branchPath, "CURRENT");
-  if ((!existsSync4(rdfPath) || !existsSync4(currentPath)) && oldRdf && oldCurrent) {
+  const rdfPath = path7.join(branchPath, "rdf");
+  const currentPath = path7.join(branchPath, "CURRENT");
+  if ((!existsSync6(rdfPath) || !existsSync6(currentPath)) && oldRdf && oldCurrent) {
     try {
-      if (existsSync4(rdfPath))
+      if (existsSync6(rdfPath))
         rmSync2(rdfPath, { recursive: true, force: true });
-      if (existsSync4(currentPath))
+      if (existsSync6(currentPath))
         rmSync2(currentPath, { force: true });
       renameSync(oldRdf, rdfPath);
       renameSync(oldCurrent, currentPath);
       return;
     } catch {}
   }
-  if (!existsSync4(rdfPath) && oldRdf) {
+  if (!existsSync6(rdfPath) && oldRdf) {
     try {
       renameSync(oldRdf, rdfPath);
     } catch {}
   }
-  if (!existsSync4(currentPath) && oldCurrent) {
+  if (!existsSync6(currentPath) && oldCurrent) {
     try {
       renameSync(oldCurrent, currentPath);
     } catch {}
   }
 }
-async function runEngineDaemon(options) {
-  if (!isValidBranchName(options.branch)) {
-    throw new Error(`Invalid Kibi engine branch name: ${options.branch}`);
+function isEngineLifecycleRequest(request) {
+  if (request.method === "stop" || request.method === "cancel" || request.method === "handshake")
+    return true;
+  const kind = request.command?.kind;
+  return request.method === "command" && (kind === "stop" || kind === "cancel" || kind === "lifecycle");
+}
+var ENGINE_PRELOADED_MODULES = [
+  ["status.pl", "status"],
+  ["discovery.pl", "discovery"]
+];
+var USE_MODULE_GOAL = /^use_module\('(?:[^']|'')*'\)$/u;
+
+class EngineSession {
+  prolog;
+  branchPath;
+  modules = [];
+  constructor(prolog, branchPath) {
+    this.prolog = prolog;
+    this.branchPath = branchPath;
+    const coreModuleDir = path7.dirname(resolveKbPlPath());
+    for (const [fileName, label] of ENGINE_PRELOADED_MODULES) {
+      const modulePath = path7.join(coreModuleDir, fileName);
+      this.modules.push({
+        goal: `use_module('${quoteProlog(modulePath.replaceAll("\\", "/"))}')`,
+        label
+      });
+    }
+  }
+  async boot() {
+    await this.prolog.start();
+    const attached = await this.prolog.query(`kb_attach('${quoteProlog(this.branchPath)}')`);
+    if (!attached.success) {
+      const recovered = await retryAttachAfterBreakingStaleLock(this.prolog, this.branchPath, attached);
+      if (!recovered.success)
+        throw new Error(recovered.error ?? "Failed to attach branch KB");
+    }
+    for (const { goal, label } of this.modules) {
+      const loaded = await this.prolog.query(goal);
+      if (!loaded.success) {
+        throw new Error(loaded.error ?? `Failed to load Kibi ${label} module`);
+      }
+    }
+  }
+  recordModuleLoad(goal, result) {
+    const normalized = goal.trim().replace(/\.+\s*$/u, "");
+    if (result.success && USE_MODULE_GOAL.test(normalized) && !this.modules.some((module) => module.goal === normalized)) {
+      this.modules.push({ goal: normalized, label: "client-loaded" });
+    }
+  }
+  needsRecycle() {
+    return this.prolog.needsRestart();
+  }
+  async ensureLive() {
+    if (!this.prolog.needsRestart())
+      return false;
+    console.error("[KIBI] engine Prolog session was lost (output overflow, timeout, or crash); restarting and reattaching the branch store");
+    try {
+      await this.boot();
+    } catch (error) {
+      await this.prolog.terminate().catch(() => {
+        return;
+      });
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`Kibi engine failed to recycle its Prolog session: ${message}`);
+    }
+    return true;
+  }
+}
+async function runEngineDaemon(requestedOptions) {
+  if (!isValidBranchName(requestedOptions.branch)) {
+    throw new Error(`Invalid Kibi engine branch name: ${requestedOptions.branch}`);
   }
+  const options = {
+    ...requestedOptions,
+    workspaceRoot: canonicalFilesystemPath(requestedOptions.workspaceRoot)
+  };
   const branchPath = ensureBranchStoreManifest(options.workspaceRoot, options.branch);
   await ensureJournaledBranchStoreAsync(branchPath);
-  const prolog = new PrologProcess({ timeout: 120000, oneShot: false });
-  await prolog.start();
-  const attached = await prolog.query(`kb_attach('${quoteProlog(branchPath)}')`);
-  if (!attached.success) {
-    const recovered = await retryAttachAfterBreakingStaleLock(prolog, branchPath, attached);
-    if (!recovered.success)
-      throw new Error(recovered.error ?? "Failed to attach branch KB");
-  }
-  const attachedIdentity = readEngineAttachmentIdentity(branchPath);
-  const coreModuleDir = path4.dirname(resolveKbPlPath());
-  for (const [fileName, label] of [
-    ["status.pl", "status"],
-    ["discovery.pl", "discovery"]
-  ]) {
-    const modulePath = path4.join(coreModuleDir, fileName);
-    const loaded = await prolog.query(`use_module('${quoteProlog(modulePath.replaceAll("\\", "/"))}')`);
-    if (!loaded.success) {
-      throw new Error(loaded.error ?? `Failed to load Kibi ${label} module`);
-    }
-  }
-  mkdirSync2(path4.dirname(options.socketPath), { recursive: true, mode: 448 });
-  if (existsSync4(options.socketPath)) {
+  const prolog = new PrologProcess({
+    timeout: 120000,
+    oneShot: false,
+    ...options.maxOutputBytes === undefined ? {} : { maxOutputBytes: options.maxOutputBytes }
+  });
+  const session = new EngineSession(prolog, branchPath);
+  await session.boot();
+  let attachedIdentity = readEngineAttachmentIdentity(branchPath);
+  const serverPrologIdentity = engineSwiplIdentity();
+  mkdirSync2(path7.dirname(options.socketPath), { recursive: true, mode: 448 });
+  if (existsSync6(options.socketPath)) {
     const isLivePeerSignal = (error) => {
       if (error && typeof error === "object") {
         const code = "code" in error ? String(error.code) : "";
@@ -1835,6 +2509,10 @@ async function runEngineDaemon(options) {
   let freshnessCache = null;
   const clients = new Set;
   let shuttingDown = false;
+  let finishShutdown;
+  const shutdownFinished = new Promise((resolve) => {
+    finishShutdown = resolve;
+  });
   const exactBranchStatus = (result) => {
     if (!result.success || typeof result.bindings.JsonString !== "string") {
       return result;
@@ -1863,7 +2541,7 @@ async function runEngineDaemon(options) {
   const workspaceWatchdog = setInterval(() => {
     if (shuttingDown)
       return;
-    if (!existsSync4(options.workspaceRoot)) {
+    if (!existsSync6(options.workspaceRoot)) {
       workspaceMissingStreak += 1;
       if (workspaceMissingStreak < 2)
         return;
@@ -1875,12 +2553,12 @@ async function runEngineDaemon(options) {
   }, engineWorkspaceWatchdogMs());
   workspaceWatchdog.unref();
   const scheduleIdleExit = () => {
-    if (activeClients > 0)
+    if (shuttingDown || activeClients > 0)
       return;
     if (!idleCompactionQueued) {
       idleCompactionQueued = true;
       queue = queue.then(async () => {
-        if (activeClients === 0) {
+        if (activeClients === 0 && !session.needsRecycle()) {
           await prolog.query("kb_storage_compact_if_needed");
         }
       }).catch(() => {
@@ -1904,9 +2582,17 @@ async function runEngineDaemon(options) {
     if (expectedPackages !== undefined && request.packageVersions !== expectedPackages) {
       throw new Error(`Kibi engine package-version mismatch: client=${request.packageVersions ?? "missing"}, server=${expectedPackages}`);
     }
-    if (path4.resolve(request.workspaceRoot ?? "") !== path4.resolve(options.workspaceRoot) || request.branch !== options.branch) {
+    if (canonicalFilesystemPath(request.workspaceRoot ?? "") !== options.workspaceRoot || request.branch !== options.branch) {
       throw new Error("Kibi engine workspace identity mismatch");
     }
+    if (request.method !== "handshake" && request.method !== "stop" && request.prologIdentity !== serverPrologIdentity) {
+      throw new Error(`Kibi engine SWI-Prolog mismatch: client=${request.prologIdentity ?? "missing"}, server=${serverPrologIdentity}`);
+    }
+    if (!isEngineLifecycleRequest(request) && await session.ensureLive()) {
+      queryCache.clear();
+      freshnessCache = null;
+      attachedIdentity = readEngineAttachmentIdentity(branchPath);
+    }
     switch (request.method) {
       case "entities": {
         const limit = request.limit ?? 100;
@@ -2042,7 +2728,14 @@ async function runEngineDaemon(options) {
         }
       }
       case "kbStatus": {
+        const freshnessCacheLookupStartedAt = process.env.KIBI_PERF_TIMINGS === "1" ? performance2.now() : null;
         if (freshnessCache !== null && Date.now() - freshnessCache.capturedAt <= ENGINE_FRESHNESS_CACHE_MS) {
+          if (freshnessCacheLookupStartedAt !== null) {
+            writePerformanceTraceEvent({
+              kind: "engine-freshness-cache-hit",
+              durationMs: performance2.now() - freshnessCacheLookupStartedAt
+            });
+          }
           return freshnessCache.result;
         }
         const result = exactBranchStatus(await prolog.query("status:kb_status_json(JsonString)"));
@@ -2062,11 +2755,20 @@ async function runEngineDaemon(options) {
           freshnessCache = null;
         }
         if (cacheableEngineGoal(request.goal)) {
+          const queryCacheLookupStartedAt = process.env.KIBI_PERF_TIMINGS === "1" ? performance2.now() : null;
           const cached = queryCache.get(request.goal);
-          if (cached !== undefined)
+          if (cached !== undefined) {
+            if (queryCacheLookupStartedAt !== null) {
+              writePerformanceTraceEvent({
+                kind: "engine-query-cache-hit",
+                durationMs: performance2.now() - queryCacheLookupStartedAt
+              });
+            }
             return cached;
+          }
         }
         const result = await prolog.query(request.goal);
+        session.recordModuleLoad(request.goal, result);
         if (result.success && mutatingEngineGoal(request.goal)) {
           fsyncJournaledBranchStore(branchPath);
         }
@@ -2100,6 +2802,8 @@ async function runEngineDaemon(options) {
         if (typeof request.targetDirectory !== "string")
           throw new Error("export.targetDirectory is required");
         return prolog.query(`kb_storage_export('${quoteProlog(request.targetDirectory)}')`);
+      case "handshake":
+        return { prologIdentity: serverPrologIdentity };
       case "stop":
         setImmediate(() => void shutdown());
         return { stopped: true };
@@ -2119,7 +2823,11 @@ async function runEngineDaemon(options) {
     if (idleTimer)
       clearTimeout(idleTimer);
     clearInterval(workspaceWatchdog);
-    const saved = await prolog.query("kb_save").catch(() => null);
+    server.close();
+    await queue.catch(() => {
+      return;
+    });
+    const saved = session.needsRecycle() ? null : await prolog.query("kb_save").catch(() => null);
     if (saved?.success) {
       try {
         fsyncJournaledBranchStore(branchPath);
@@ -2130,22 +2838,29 @@ async function runEngineDaemon(options) {
     });
     for (const client of clients)
       client.destroy();
-    server.close();
     server.unref();
     try {
-      if (existsSync4(options.socketPath))
+      if (existsSync6(options.socketPath))
         rmSync2(options.socketPath, { force: true });
-      if (existsSync4(enginePidPath(options.workspaceRoot, options.branch)))
+      if (existsSync6(enginePidPath(options.workspaceRoot, options.branch)))
         rmSync2(enginePidPath(options.workspaceRoot, options.branch), {
           force: true
         });
     } catch {}
     setTimeout(() => process.exit(0), 50).unref();
+    finishShutdown();
   };
   const requestSignalShutdown = requestEngineSignalShutdown(shutdown);
   process.once("SIGTERM", requestSignalShutdown);
   process.once("SIGINT", requestSignalShutdown);
   server.on("connection", (socket) => {
+    socket.on("error", () => {
+      return;
+    });
+    if (shuttingDown) {
+      socket.destroy();
+      return;
+    }
     clients.add(socket);
     activeClients += 1;
     const cancelledRequests = new Set;
@@ -2155,6 +2870,15 @@ async function runEngineDaemon(options) {
         const bytes = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
         buffer = parseFrames(Buffer.concat([buffer, bytes]), (value) => {
           const request = value;
+          if (shuttingDown) {
+            writeSocketFrame(socket, {
+              id: request.id,
+              ok: false,
+              error: "Kibi engine is shutting down; request was not executed",
+              serverPackageVersions: ENGINE_PACKAGE_VERSIONS
+            });
+            return;
+          }
           if (request.method === "cancel" && typeof request.cancelOf === "number") {
             cancelledRequests.add(request.cancelOf);
           }
@@ -2213,6 +2937,7 @@ async function runEngineDaemon(options) {
   await new Promise((resolve) => {
     server.once("close", resolve);
   });
+  await shutdownFinished;
 }
 
 // ../cli/src/engine-daemon.ts
@@ -2224,7 +2949,7 @@ function isEngineDaemonEntrypoint(argv = process.argv, moduleUrl = import.meta.u
   if (typeof entry !== "string" || entry.length === 0)
     return false;
   try {
-    return moduleUrl === pathToFileURL(path5.resolve(entry)).href;
+    return moduleUrl === pathToFileURL(path8.resolve(entry)).href;
   } catch {
     return false;
   }