kibi-runtime 1.0.1

package/dist/engine-daemon.js

@@ -0,0 +1,2402 @@
+#!/usr/bin/env node
+
+// ../cli/src/engine-daemon.ts
+import { writeFileSync as writeFileSync3 } from "node:fs";
+
+// ../cli/src/engine.ts
+import { spawn as spawn2 } from "node:child_process";
+import { createHash as createHash2 } from "node:crypto";
+import {
+  chmodSync,
+  closeSync,
+  existsSync as existsSync3,
+  fsyncSync,
+  mkdirSync as mkdirSync2,
+  openSync,
+  readFileSync as readFileSync2,
+  readdirSync as readdirSync2,
+  realpathSync,
+  renameSync,
+  rmSync,
+  statSync as statSync2,
+  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 { fileURLToPath as fileURLToPath2 } from "node:url";
+
+// ../cli/src/prolog.ts
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// ../cli/src/env.ts
+function getEnvValue(key) {
+  const value = process.env[key];
+  return typeof value === "string" ? value : undefined;
+}
+function getKbPlPathOverride() {
+  return getEnvValue("KIBI_KB_PL_PATH");
+}
+function isPrologDebugEnabled() {
+  return Boolean(getEnvValue("KIBI_PROLOG_DEBUG"));
+}
+
+// ../cli/src/prolog.ts
+var importMetaDir = path.dirname(fileURLToPath(import.meta.url));
+var 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 = createRequire(import.meta.url);
+function packageVersion(packagePath) {
+  try {
+    const packageJson = require2(packagePath);
+    return typeof packageJson.version === "string" ? packageJson.version : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+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"))}`
+].join(",");
+function resolveKbPlPath() {
+  const overrideKbPath = getKbPlPathOverride();
+  if (overrideKbPath) {
+    return overrideKbPath;
+  }
+  try {
+    try {
+      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");
+    }
+  } catch {}
+  let currentDir = importMetaDir;
+  while (currentDir !== path.dirname(currentDir)) {
+    const candidate = path.join(currentDir, "packages", "core", "src", "kb.pl");
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+    currentDir = path.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 PrologProcess {
+  process = null;
+  swiplPath;
+  timeout;
+  outputBuffer = "";
+  outputBufferBytes = 0;
+  outputOverflowed = false;
+  errorBuffer = "";
+  errorBufferBytes = 0;
+  cache = new Map;
+  interactiveQueryTail = Promise.resolve();
+  terminationPromise = null;
+  oneShotProcesses = new Set;
+  useOneShotMode;
+  attachedKbPath = null;
+  onProcessExit = null;
+  constructor(options = {}) {
+    this.swiplPath = options.swiplPath || "swipl";
+    this.timeout = options.timeout || 30000;
+    this.useOneShotMode = options.oneShot ?? false;
+  }
+  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 kbPath = resolveKbPlPath();
+    this.process = spawn(this.swiplPath, [
+      "-g",
+      `use_module('${kbPath}'), use_module(library(semweb/rdf_db)), set_prolog_flag(answer_write_options, [max_depth(0), quoted(true)])`,
+      "--quiet"
+    ], {
+      detached: process.platform !== "win32",
+      env: {
+        ...process.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
+      }
+    });
+    this.clearQueryBuffers();
+    if (!this.process.stdout || !this.process.stderr || !this.process.stdin) {
+      throw new Error("Failed to spawn Prolog process");
+    }
+    this.process.stdout.on("data", (chunk) => {
+      this.appendOutputChunk(chunk);
+    });
+    this.process.stderr.on("data", (chunk) => {
+      this.appendErrorChunk(chunk);
+    });
+    this.process.stdin.write(`true.
+`);
+    if (!this.onProcessExit) {
+      this.onProcessExit = () => {
+        this.terminate();
+      };
+      process.on("exit", this.onProcessExit);
+    }
+    await this.waitForReady();
+  }
+  async waitForReady() {
+    const start = Date.now();
+    const maxStartWait = 2000;
+    while (Date.now() - start < maxStartWait) {
+      if (!this.process || this.process.killed) {
+        throw new Error(`Prolog process terminated unexpectedly during startup: ${this.translateError(this.errorBuffer)}`);
+      }
+      if (this.errorBuffer.includes("ERROR")) {
+        throw new Error(`Failed to load kb module: ${this.translateError(this.errorBuffer)}`);
+      }
+      if (this.outputBuffer.includes("true.")) {
+        this.clearQueryBuffers();
+        return;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+    if (this.errorBuffer.includes("ERROR")) {
+      throw new Error(`Failed to load kb module: ${this.translateError(this.errorBuffer)}`);
+    }
+    this.clearQueryBuffers();
+  }
+  async query(goal) {
+    const isSingleGoal = typeof goal === "string";
+    const goalKey = isSingleGoal ? goal : null;
+    const cacheable = goalKey !== null && this.isCacheableGoal(goalKey);
+    if (cacheable) {
+      const cachedResult = this.cache.get(goalKey);
+      if (cachedResult) {
+        return cachedResult;
+      }
+    }
+    if (this.useOneShotMode) {
+      const oneShotResult = await this.queryOneShot(goal);
+      const isBatchGoal = isSingleGoal && /^\s*\(/.test(this.normalizeGoal(goal));
+      const shouldCache = cacheable && !isBatchGoal;
+      if (!shouldCache && oneShotResult.success) {
+        this.invalidateCache();
+      }
+      if (shouldCache && oneShotResult.success) {
+        this.cache.set(goalKey, oneShotResult);
+      }
+      return oneShotResult;
+    }
+    if (!isSingleGoal) {
+      const batchGoal = `rdf_transaction((${goal.map((item) => this.normalizeGoal(item)).join(", ")}))`;
+      return this.query(batchGoal);
+    }
+    if (!this.isProcessUsable()) {
+      if (this.process === null) {
+        return this.execOneShot(goal, this.attachedKbPath);
+      }
+      throw new Error("Prolog process not started");
+    }
+    const runInteractiveQuery = async () => {
+      this.clearQueryBuffers();
+      const debug = isPrologDebugEnabled();
+      const normalizedGoal = this.normalizeGoal(goal);
+      const goalLabel = this.goalLabel(normalizedGoal);
+      const shouldPersist = this.isMutatingGoal(normalizedGoal) && !normalizedGoal.includes("kb_save") && !normalizedGoal.includes("kb_commit_upsert");
+      const goalWithPersistence = shouldPersist ? `(${normalizedGoal}, kb_save)` : normalizedGoal;
+      const wrappedGoal = /^once\s*\(/.test(goalWithPersistence) ? `catch(${goalWithPersistence}, _E, (print_message(error, _E), fail))` : `catch(once((${goalWithPersistence})), _E, (print_message(error, _E), fail))`;
+      const start = Date.now();
+      if (debug) {
+        console.error(`[prolog debug] start query: ${goalLabel}`);
+      }
+      this.process?.stdin?.write(`${wrappedGoal}.
+writeln('${INTERACTIVE_QUERY_FRAME_END}').
+`);
+      return new Promise((resolve, reject) => {
+        let settled = false;
+        const timeoutId = setTimeout(() => {
+          const stage = this.lastDiagnosticStage(this.errorBuffer) ?? "unknown";
+          const msg = `Query timeout after ${this.timeout / 1000}s (stage=${stage}, pid=${this.process?.pid ?? 0}, killed=${this.process?.killed ? "yes" : "no"}, exitCode=${this.process?.exitCode ?? "null"}, goal=${goalLabel})`;
+          if (debug) {
+            console.error(`[prolog debug] timeout: ${msg}`);
+            const runtime = this.errorBuffer.split(`
+`).find((line) => line.includes("__KIBI_RUNTIME__"));
+            console.error(`[prolog debug] runtime=${runtime ?? "unknown"} packages=${process.env.KIBI_PACKAGE_VERSIONS ?? KIBI_PACKAGE_VERSIONS}`);
+          }
+          settled = true;
+          this.terminate().finally(() => {
+            reject(new Error(msg));
+          });
+        }, this.timeout);
+        const checkResult = () => {
+          if (settled) {
+            return;
+          }
+          if (this.outputOverflowed) {
+            clearTimeout(timeoutId);
+            settled = true;
+            this.terminate().finally(() => {
+              resolve({
+                success: false,
+                bindings: {},
+                error: PROLOG_OUTPUT_OVERFLOW_ERROR
+              });
+            });
+            return;
+          }
+          if (!this.isProcessUsable()) {
+            clearTimeout(timeoutId);
+            settled = true;
+            resolve({
+              success: false,
+              bindings: {},
+              error: "Query interrupted because the Prolog process terminated"
+            });
+            return;
+          }
+          if (this.errorBuffer.length > 0 && this.errorBuffer.includes("ERROR")) {
+            clearTimeout(timeoutId);
+            settled = true;
+            if (debug) {
+              console.error(`[prolog debug] query error: ${goalLabel} error=${this.errorBuffer.split(`
+`)[0]}`);
+            }
+            resolve({
+              success: false,
+              bindings: {},
+              error: this.addDiagnosticStage(this.translateError(this.errorBuffer), normalizedGoal, this.errorBuffer)
+            });
+            return;
+          }
+          const frameEnd = this.outputBuffer.indexOf(INTERACTIVE_QUERY_FRAME_END);
+          if (frameEnd >= 0) {
+            clearTimeout(timeoutId);
+            settled = true;
+            const framedOutput = this.outputBuffer.slice(0, frameEnd).trimEnd();
+            if (/(?:^|\n)(?:false|fail)\.\s*$/.test(framedOutput)) {
+              resolve({
+                success: false,
+                bindings: {},
+                error: "Query failed"
+              });
+              return;
+            }
+            const result = {
+              success: true,
+              bindings: this.extractBindings(framedOutput)
+            };
+            const isBatchGoal = /^\s*\(/.test(normalizedGoal);
+            const shouldCache = cacheable && !isBatchGoal;
+            if (!shouldCache) {
+              this.invalidateCache();
+            }
+            if (shouldCache) {
+              this.cache.set(goalKey, result);
+            }
+            if (debug) {
+              console.error(`[prolog debug] query success: ${goalLabel} elapsed=${(Date.now() - start) / 1000}s`);
+            }
+            resolve(result);
+            return;
+          }
+          setTimeout(checkResult, 50);
+        };
+        checkResult();
+      });
+    };
+    const previousQuery = this.interactiveQueryTail;
+    let releaseQuery;
+    this.interactiveQueryTail = new Promise((resolve) => {
+      releaseQuery = resolve;
+    });
+    await previousQuery;
+    try {
+      if (!this.isProcessUsable()) {
+        throw new Error("Prolog process not started");
+      }
+      return await runInteractiveQuery();
+    } finally {
+      releaseQuery();
+    }
+  }
+  async queryBatch(goals) {
+    return this.query([...goals]);
+  }
+  invalidateCache() {
+    this.cache.clear();
+  }
+  isCacheableGoal(goal) {
+    const trimmed = goal.trim();
+    if (trimmed.startsWith("rdf_transaction(") || this.isMutatingGoal(trimmed)) {
+      return false;
+    }
+    return !(trimmed.startsWith("kb_attach(") || trimmed.startsWith("kb_detach") || trimmed.startsWith("kb_save") || trimmed.startsWith("kb_storage_status") || trimmed.startsWith("kb_storage_compact") || trimmed.startsWith("kb_storage_export") || trimmed.startsWith("status:") || trimmed.startsWith("kb_commit_upsert(") || trimmed.startsWith("kb_assert_") || trimmed.startsWith("kb_delete_") || trimmed.startsWith("kb_retract_"));
+  }
+  isMutatingGoal(goal) {
+    return /(?:kb_(?:assert|delete|retract|commit|save|log)_|\bkb_save\b|\brdf_(?:assert|retract))/u.test(goal);
+  }
+  isExplicitSaveGoal(goal) {
+    return goal.trim().startsWith("kb_save");
+  }
+  async queryOneShot(goal) {
+    if (Array.isArray(goal)) {
+      return this.execOneShot(goal, this.attachedKbPath);
+    }
+    const trimmedGoal = this.normalizeGoal(goal);
+    if (trimmedGoal.startsWith("kb_detach")) {
+      this.attachedKbPath = null;
+      return { success: true, bindings: {} };
+    }
+    const attachMatch = trimmedGoal.match(/^kb_attach\('(.+)'\)$/);
+    if (attachMatch) {
+      const attachPath = attachMatch[1] ?? null;
+      if (!attachPath) {
+        return {
+          success: false,
+          bindings: {},
+          error: "Invalid KB attach path"
+        };
+      }
+      if (this.attachedKbPath !== null) {
+        return {
+          success: false,
+          bindings: {},
+          error: "KB already attached"
+        };
+      }
+      const attachResult = await this.execOneShot(trimmedGoal, null);
+      if (attachResult.success) {
+        this.attachedKbPath = attachPath;
+      }
+      return attachResult;
+    }
+    return this.execOneShot(trimmedGoal, this.attachedKbPath);
+  }
+  async execOneShot(goal, kbPath) {
+    const originalGoalList = Array.isArray(goal) ? goal.map((item) => this.normalizeGoal(item)) : [this.normalizeGoal(goal)];
+    const explicitSaveRequested = Array.isArray(goal) ? originalGoalList.some((item) => this.isExplicitSaveGoal(item)) : false;
+    const goalList = explicitSaveRequested ? originalGoalList.filter((item) => !this.isExplicitSaveGoal(item)) : originalGoalList;
+    const isBatch = goalList.length > 1;
+    const combinedGoal = goalList.length === 0 ? "true" : goalList.length === 1 ? goalList[0] : `(${goalList.join(", ")})`;
+    const kbModulePath = resolveKbPlPath();
+    const prologGoal = [
+      `use_module('${kbModulePath}')`,
+      "use_module(library(semweb/rdf_db))",
+      "set_prolog_flag(answer_write_options, [max_depth(0), quoted(true)])",
+      "getenv('KIBI_GOAL', GoalAtom)",
+      "read_term_from_atom(GoalAtom, Goal, [variable_names(Vars)])",
+      kbPath ? "getenv('KIBI_KB_PATH', KBPath), kb_attach(KBPath)" : "true",
+      isBatch ? "WrappedGoal = rdf_transaction(Goal)" : "WrappedGoal = Goal",
+      "(catch(call(WrappedGoal), E, (print_message(error, E), fail)) -> QuerySucceeded = true ; QuerySucceeded = false)",
+      kbPath && (explicitSaveRequested || goalList.some((item) => this.isMutatingGoal(item))) ? "(QuerySucceeded == true -> kb_save ; true)" : "true",
+      kbPath ? "kb_detach" : "true",
+      "(QuerySucceeded == true -> (forall(member(Name=Value, Vars), (write(Name), write('='), write_term(Value, [quoted(true), max_depth(0)]), writeln('.'))), writeln('__KIBI_TRUE__.')) ; writeln('__KIBI_FALSE__.'))"
+    ].join(", ");
+    const runtimeName = process.versions.bun !== undefined ? "bun" : "node";
+    const runtimeVersion = process.versions.bun ?? process.versions.node ?? "unknown";
+    const packageVersions = process.env.KIBI_PACKAGE_VERSIONS ?? KIBI_PACKAGE_VERSIONS;
+    let child;
+    try {
+      child = spawn(this.swiplPath, ["-q", "-g", prologGoal, "-t", "halt"], {
+        detached: process.platform !== "win32",
+        env: {
+          ...process.env,
+          KIBI_GOAL: combinedGoal,
+          KIBI_RUNTIME_NAME: runtimeName,
+          KIBI_RUNTIME_VERSION: runtimeVersion,
+          KIBI_PACKAGE_VERSIONS: packageVersions,
+          ...kbPath ? { KIBI_KB_PATH: kbPath } : {}
+        },
+        stdio: ["ignore", "pipe", "pipe"]
+      });
+    } catch (error) {
+      return {
+        success: false,
+        bindings: {},
+        error: error instanceof Error ? error.message : String(error)
+      };
+    }
+    this.oneShotProcesses.add(child);
+    let stdout = "";
+    let stderr = "";
+    let outputBytes = 0;
+    let errorBytes = 0;
+    let outputOverflowed = false;
+    let timedOut = false;
+    let settled = false;
+    let closed = false;
+    let termination = null;
+    const appendChunk = (chunk, target) => {
+      if (outputOverflowed)
+        return;
+      const bytes = target === "stdout" ? outputBytes : errorBytes;
+      const remaining = PROLOG_OUTPUT_MAX_BUFFER_BYTES - bytes;
+      if (chunk.byteLength > remaining) {
+        const clipped = chunk.subarray(0, Math.max(0, remaining)).toString();
+        if (target === "stdout")
+          stdout += clipped;
+        else
+          stderr += clipped;
+        outputOverflowed = true;
+        termination ??= this.terminateProcessTree(child);
+        return;
+      }
+      if (target === "stdout") {
+        stdout += chunk.toString();
+        outputBytes += chunk.byteLength;
+      } else {
+        stderr += chunk.toString();
+        errorBytes += chunk.byteLength;
+      }
+    };
+    child.stdout?.on("data", (chunk) => appendChunk(chunk, "stdout"));
+    child.stderr?.on("data", (chunk) => appendChunk(chunk, "stderr"));
+    const completion = new Promise((resolve) => {
+      child.once("error", (error) => {
+        closed = true;
+        resolve({ code: null, signal: null, error });
+      });
+      child.once("close", (code, signal) => {
+        closed = true;
+        resolve({ code, signal });
+      });
+    });
+    const timeoutId = setTimeout(() => {
+      if (settled || closed)
+        return;
+      timedOut = true;
+      termination ??= this.terminateProcessTree(child);
+    }, this.timeout);
+    const result = await completion;
+    settled = true;
+    clearTimeout(timeoutId);
+    if (termination !== null)
+      await termination;
+    this.oneShotProcesses.delete(child);
+    const stage = this.lastDiagnosticStage(stderr) ?? "unknown";
+    if (isPrologDebugEnabled()) {
+      const runtime = stderr.split(`
+`).find((line) => line.includes("__KIBI_RUNTIME__"));
+      if (runtime !== undefined) {
+        console.error(`[prolog debug] ${runtime}`);
+      }
+      console.error(`[prolog debug] child pid=${child.pid ?? 0} runtime=${runtimeName}@${runtimeVersion} packages=${packageVersions} stage=${stage}`);
+    }
+    if (timedOut) {
+      throw new Error(`Query timeout after ${this.timeout / 1000}s (stage=${stage}, pid=${child.pid ?? 0}, goal=${this.goalLabel(combinedGoal ?? "true")})`);
+    }
+    if (outputOverflowed) {
+      return {
+        success: false,
+        bindings: {},
+        error: this.addDiagnosticStage(PROLOG_OUTPUT_OVERFLOW_ERROR, combinedGoal ?? "true", stderr)
+      };
+    }
+    if (result.error !== undefined) {
+      return {
+        success: false,
+        bindings: {},
+        error: this.addDiagnosticStage(result.error.message, combinedGoal ?? "true", stderr)
+      };
+    }
+    if (stderr.includes("ERROR")) {
+      return {
+        success: false,
+        bindings: {},
+        error: this.addDiagnosticStage(this.translateError(stderr), combinedGoal ?? "true", stderr)
+      };
+    }
+    if (stdout.includes("__KIBI_TRUE__")) {
+      const clean = stdout.split(`
+`).filter((line) => !line.includes("__KIBI_TRUE__")).join(`
+`);
+      return {
+        success: true,
+        bindings: this.extractBindings(clean)
+      };
+    }
+    if (stdout.includes("__KIBI_FALSE__")) {
+      return {
+        success: false,
+        bindings: {},
+        error: "Query returned false"
+      };
+    }
+    return {
+      success: false,
+      bindings: {},
+      error: this.addDiagnosticStage(`Query failed - stdout: ${stdout.substring(0, 200)}, stderr: ${stderr.substring(0, 200)}`, combinedGoal ?? "true", stderr)
+    };
+  }
+  normalizeGoal(goal) {
+    return goal.trim().replace(/\.+\s*$/, "");
+  }
+  clearQueryBuffers() {
+    this.outputBuffer = "";
+    this.outputBufferBytes = 0;
+    this.outputOverflowed = false;
+    this.errorBuffer = "";
+    this.errorBufferBytes = 0;
+  }
+  appendOutputChunk(chunk) {
+    if (this.outputOverflowed)
+      return;
+    const remaining = PROLOG_OUTPUT_MAX_BUFFER_BYTES - this.outputBufferBytes;
+    if (chunk.byteLength > remaining) {
+      this.outputBuffer += chunk.subarray(0, remaining).toString();
+      this.outputBufferBytes = PROLOG_OUTPUT_MAX_BUFFER_BYTES;
+      this.outputOverflowed = true;
+      return;
+    }
+    this.outputBuffer += chunk.toString();
+    this.outputBufferBytes += chunk.byteLength;
+  }
+  appendErrorChunk(chunk) {
+    if (this.outputOverflowed)
+      return;
+    const remaining = PROLOG_OUTPUT_MAX_BUFFER_BYTES - this.errorBufferBytes;
+    if (chunk.byteLength > remaining) {
+      this.errorBuffer += chunk.subarray(0, remaining).toString();
+      this.errorBufferBytes = PROLOG_OUTPUT_MAX_BUFFER_BYTES;
+      this.outputOverflowed = true;
+      return;
+    }
+    this.errorBuffer += chunk.toString();
+    this.errorBufferBytes += chunk.byteLength;
+  }
+  goalLabel(goal) {
+    const match = goal.trim().match(/^([a-z][A-Za-z0-9_]*(?::[a-z][A-Za-z0-9_]*)?)/);
+    return match?.[1] ?? "anonymous";
+  }
+  addDiagnosticStage(message, goal, diagnostics) {
+    if (this.goalLabel(goal) !== "kb_commit_upsert")
+      return message;
+    const stage = this.lastDiagnosticStage(diagnostics);
+    return stage === null ? message : `${message} (stage=${stage})`;
+  }
+  lastDiagnosticStage(text) {
+    const matches = [...text.matchAll(/__KIBI_STAGE__:([^\s\r\n]+)/g)];
+    return matches.at(-1)?.[1] ?? null;
+  }
+  signalProcessTree(child, signal) {
+    const pid = child.pid;
+    if (pid === undefined || pid <= 0)
+      return;
+    if (process.platform !== "win32") {
+      try {
+        process.kill(-pid, signal);
+        return;
+      } catch {}
+    }
+    try {
+      child.kill(signal);
+    } catch {}
+  }
+  async terminateProcessTree(child) {
+    let closed = false;
+    const exited = new Promise((resolve) => {
+      const markExited = () => {
+        closed = true;
+        resolve();
+      };
+      child.once("close", markExited);
+      child.once("error", markExited);
+    });
+    if (child.exitCode === null)
+      this.signalProcessTree(child, "SIGTERM");
+    await Promise.race([
+      exited,
+      new Promise((resolve) => setTimeout(resolve, 1000))
+    ]);
+    if (!closed) {
+      this.signalProcessTree(child, "SIGKILL");
+      await Promise.race([
+        exited,
+        new Promise((resolve) => setTimeout(resolve, 1000))
+      ]);
+    }
+  }
+  isProcessUsable() {
+    return Boolean(this.process?.stdin && !this.process?.killed && this.process?.exitCode === null);
+  }
+  extractBindings(output) {
+    const bindings = {};
+    let variableName;
+    let valueLines = [];
+    const flush = () => {
+      if (variableName === undefined)
+        return;
+      bindings[variableName] = valueLines.join(`
+`).trim().replace(/\.$/, "").replace(/,$/, "");
+      variableName = undefined;
+      valueLines = [];
+    };
+    for (const line of output.split(`
+`)) {
+      const match = line.match(/^([A-Z_][A-Za-z0-9_]*)\s*=\s*(.*)$/);
+      if (match?.[1] !== undefined && match[2] !== undefined) {
+        flush();
+        variableName = match[1];
+        valueLines = [match[2]];
+        continue;
+      }
+      if (variableName !== undefined)
+        valueLines.push(line);
+    }
+    flush();
+    return bindings;
+  }
+  translateError(errorText) {
+    const cleanError = errorText.replace(/^__KIBI_(?:STAGE|RUNTIME)__:[^\r\n]*\r?\n?/gm, "");
+    if (cleanError.includes("stale_snapshot")) {
+      return "KB snapshot is stale; reattach or refresh the runtime before retrying (stale_snapshot)";
+    }
+    if ((cleanError.includes("audit_log") || cleanError.includes("audit.log") || cleanError.includes("Resource temporarily unavailable")) && (cleanError.includes("lock") || cleanError.includes("permission"))) {
+      return "Audit journal is locked by another Kibi runtime; restart the stale MCP/CLI session before retrying";
+    }
+    if (cleanError.includes("does not exist") && /entity [`'"].+?[`'"]/.test(cleanError)) {
+      const entityIdMatch = cleanError.match(/entity [`'"]+(.+?)[`'"]+ does not exist/);
+      const matchedEntityId = entityIdMatch?.[1];
+      const entityId = matchedEntityId !== undefined ? matchedEntityId.replace(/^`?'+|'+`?$/g, "") : "unknown";
+      if (cleanError.includes("Target entity does not exist")) {
+        return `Target entity does not exist: ${entityId}`;
+      }
+      if (cleanError.includes("Source entity does not exist")) {
+        return `Source entity does not exist: ${entityId}`;
+      }
+      return `Entity does not exist: ${entityId}`;
+    }
+    if (cleanError.includes("Type error: `relationship' expected")) {
+      const relMatch = cleanError.match(/\(Invalid relationship: ([^)]+)\)/);
+      const invalidRelationship = relMatch?.[1];
+      if (invalidRelationship !== undefined) {
+        return `Invalid relationship: ${invalidRelationship.trim()}`;
+      }
+      return "Invalid relationship type or direction";
+    }
+    if (cleanError.includes("existence_error") || cleanError.includes("Unknown procedure")) {
+      return "Predicate or file not found";
+    }
+    if (cleanError.includes("permission_error")) {
+      return "Access denied or KB locked";
+    }
+    if (cleanError.includes("syntax_error") || cleanError.includes("Operator expected")) {
+      return "Invalid query syntax";
+    }
+    if (cleanError.includes("timeout_error")) {
+      return `Operation exceeded ${this.timeout / 1000}s timeout`;
+    }
+    const simpleError = (cleanError.replace(/ERROR:\s*/g, "").replace(/^\*\*.*\*\*$/gm, "").replace(/^\s+/gm, "").split(`
+`)[0] ?? "").trim();
+    return simpleError || "Unknown error";
+  }
+  isRunning() {
+    return Boolean(this.process && !this.process.killed && this.process?.exitCode === null);
+  }
+  getPid() {
+    return this.process?.pid || 0;
+  }
+  async terminate() {
+    if (this.terminationPromise) {
+      await this.terminationPromise;
+      return;
+    }
+    if (this.onProcessExit) {
+      process.off("exit", this.onProcessExit);
+      this.onProcessExit = null;
+    }
+    const current = this.process;
+    const oneShots = [...this.oneShotProcesses];
+    this.process = null;
+    this.clearQueryBuffers();
+    if (current || oneShots.length > 0) {
+      this.terminationPromise = (async () => {
+        if (current) {
+          current.stdin?.end();
+          await this.terminateProcessTree(current);
+        }
+        await Promise.all(oneShots.map((child) => this.terminateProcessTree(child)));
+      })();
+      try {
+        await this.terminationPromise;
+      } finally {
+        this.terminationPromise = null;
+      }
+    }
+  }
+}
+
+// ../cli/src/prolog/codec.ts
+function parseListOfLists(listStr) {
+  const cleaned = listStr.trim().replace(/^\[/, "").replace(/\]$/, "");
+  if (cleaned === "") {
+    return [];
+  }
+  const results = [];
+  let depth = 0;
+  let current = "";
+  let currentList = [];
+  for (let i = 0;i < cleaned.length; i++) {
+    const char = cleaned[i];
+    if (char === "[") {
+      depth++;
+      if (depth > 1)
+        current += char;
+    } else if (char === "]") {
+      depth--;
+      if (depth === 0) {
+        if (current) {
+          currentList.push(current.trim());
+          current = "";
+        }
+        if (currentList.length > 0) {
+          results.push(currentList);
+          currentList = [];
+        }
+      } else {
+        current += char;
+      }
+    } else if (char === "," && depth === 1) {
+      if (current) {
+        currentList.push(current.trim());
+        current = "";
+      }
+    } else if (char === "," && depth === 0) {} else {
+      current += char;
+    }
+  }
+  return results;
+}
+function parseEntityFromList(data) {
+  if (data.length < 3) {
+    return {};
+  }
+  const [idPart, typePart, propsPart] = data;
+  if (idPart === undefined || typePart === undefined || propsPart === undefined) {
+    return {};
+  }
+  const id = idPart.trim();
+  const type = typePart.trim();
+  const propsStr = propsPart.trim();
+  const props = parsePropertyList(propsStr);
+  return { ...props, id: normalizeEntityId(stripOuterQuotes(id)), type };
+}
+function parsePropertyList(propsStr) {
+  const props = {};
+  let cleaned = propsStr.trim();
+  if (cleaned.startsWith("[")) {
+    cleaned = cleaned.substring(1);
+  }
+  if (cleaned.endsWith("]")) {
+    cleaned = cleaned.substring(0, cleaned.length - 1);
+  }
+  const pairs = splitTopLevelGeneral(cleaned, ",");
+  for (const pair of pairs) {
+    const eqIndex = pair.indexOf("=");
+    if (eqIndex === -1)
+      continue;
+    const key = pair.substring(0, eqIndex).trim();
+    const value = pair.substring(eqIndex + 1).trim();
+    if (key === "..." || value === "..." || value === "...|...") {
+      continue;
+    }
+    let parsed = parsePrologValue(value);
+    if ((key === "rule_ir" || key === "semantic_inventory" || key === "verification_receipts" || key === "verification_contract") && typeof parsed === "string") {
+      try {
+        parsed = JSON.parse(parsed);
+      } catch {}
+    }
+    if (!Object.hasOwn(props, key)) {
+      props[key] = parsed;
+      continue;
+    }
+    const existing = props[key];
+    props[key] = Array.isArray(existing) ? [...existing, parsed] : [existing, parsed];
+  }
+  return props;
+}
+function parsePrologValue(valueInput) {
+  const value = valueInput.trim();
+  if (value.startsWith("^^(")) {
+    const innerStart = value.indexOf("(") + 1;
+    let depth = 1;
+    let innerEnd = innerStart;
+    for (let i = innerStart;i < value.length; i++) {
+      if (value[i] === "(")
+        depth++;
+      if (value[i] === ")") {
+        depth--;
+        if (depth === 0) {
+          innerEnd = i;
+          break;
+        }
+      }
+    }
+    const innerContent = value.substring(innerStart, innerEnd);
+    const parts = splitTopLevelGeneral(innerContent, ",");
+    if (parts.length >= 2) {
+      const literalPart = parts[0];
+      const datatypePart = parts[1];
+      if (literalPart === undefined || datatypePart === undefined) {
+        return value;
+      }
+      let literalValue = literalPart.trim();
+      const datatype = datatypePart.trim();
+      if (literalValue.startsWith('"') && literalValue.endsWith('"')) {
+        literalValue = literalValue.substring(1, literalValue.length - 1);
+      }
+      if (datatype.includes("#integer")) {
+        return Number.parseInt(literalValue, 10);
+      }
+      if (datatype.includes("#decimal") || datatype.includes("#double")) {
+        return Number.parseFloat(literalValue);
+      }
+      if (datatype.includes("#boolean")) {
+        return literalValue === "true";
+      }
+      if (literalValue.startsWith("[") && literalValue.endsWith("]")) {
+        const listContent = literalValue.substring(1, literalValue.length - 1);
+        if (listContent === "") {
+          return [];
+        }
+        return splitTopLevelGeneral(listContent, ",").map((item) => item.trim());
+      }
+      return literalValue;
+    }
+  }
+  if (value.startsWith("file:///")) {
+    const lastSlash = value.lastIndexOf("/");
+    if (lastSlash !== -1) {
+      return value.substring(lastSlash + 1);
+    }
+    return value;
+  }
+  if (value.startsWith('"') && value.endsWith('"')) {
+    try {
+      return JSON.parse(value);
+    } catch {
+      return value.substring(1, value.length - 1);
+    }
+  }
+  if (value.startsWith("'") && value.endsWith("'")) {
+    return value.substring(1, value.length - 1);
+  }
+  if (value.startsWith("[") && value.endsWith("]")) {
+    const listContent = value.substring(1, value.length - 1);
+    if (listContent === "") {
+      return [];
+    }
+    const items = splitTopLevelGeneral(listContent, ",").map((item) => {
+      return parsePrologValue(item.trim());
+    });
+    return items;
+  }
+  return value;
+}
+function splitTopLevelGeneral(str, delimiter) {
+  const results = [];
+  let current = "";
+  let depth = 0;
+  let inDoubleQuotes = false;
+  let inSingleQuotes = false;
+  for (let i = 0;i < str.length; i++) {
+    const char = str[i];
+    const prevChar = i > 0 ? str[i - 1] : "";
+    if (char === '"' && !inSingleQuotes && prevChar !== "\\") {
+      inDoubleQuotes = !inDoubleQuotes;
+      current += char;
+    } else if (char === "'" && !inDoubleQuotes && prevChar !== "\\") {
+      inSingleQuotes = !inSingleQuotes;
+      current += char;
+    } else if (!inDoubleQuotes && !inSingleQuotes && (char === "[" || char === "(")) {
+      depth++;
+      current += char;
+    } else if (!inDoubleQuotes && !inSingleQuotes && (char === "]" || char === ")")) {
+      depth--;
+      current += char;
+    } else if (!inDoubleQuotes && !inSingleQuotes && depth === 0 && char === delimiter) {
+      if (current) {
+        results.push(current);
+        current = "";
+      }
+    } else {
+      current += char;
+    }
+  }
+  if (current) {
+    results.push(current);
+  }
+  return results;
+}
+function stripOuterQuotes(value) {
+  if (value.startsWith("'") && value.endsWith("'")) {
+    return value.slice(1, -1);
+  }
+  if (value.startsWith('"') && value.endsWith('"')) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+function normalizeEntityId(value) {
+  if (!value.startsWith("file:///")) {
+    return value;
+  }
+  const idx = value.lastIndexOf("/");
+  return idx === -1 ? value : value.slice(idx + 1);
+}
+
+// ../cli/src/utils/branch-resolver.ts
+import {
+  execFileSync as rawExecFileSync,
+  execSync as rawExecSync
+} from "node:child_process";
+import * as path3 from "node:path";
+
+// ../cli/src/utils/branch-store-locator.ts
+import { createHash } from "node:crypto";
+import {
+  existsSync as existsSync2,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  statSync,
+  writeFileSync
+} from "node:fs";
+import path2 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");
+}
+function branchStorePath(workspaceRoot, branch) {
+  return path2.join(branchStoresRoot(workspaceRoot), branchStoreKey(branch));
+}
+function branchStoreManifestPath(storePath) {
+  return path2.join(storePath, "branch.json");
+}
+function expectedBranchStoreManifest(branch) {
+  return {
+    version: BRANCH_STORE_MANIFEST_VERSION,
+    branch,
+    key: branchStoreKey(branch)
+  };
+}
+function readBranchStoreManifest(storePath) {
+  const manifestPath = branchStoreManifestPath(storePath);
+  if (!existsSync2(manifestPath))
+    return null;
+  try {
+    const parsed = JSON.parse(readFileSync(manifestPath, "utf8"));
+    if (parsed.version !== BRANCH_STORE_MANIFEST_VERSION || typeof parsed.branch !== "string" || typeof parsed.key !== "string") {
+      return null;
+    }
+    return {
+      version: BRANCH_STORE_MANIFEST_VERSION,
+      branch: parsed.branch,
+      key: parsed.key
+    };
+  } catch {
+    return null;
+  }
+}
+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;
+}
+function ensureBranchStoreManifest(workspaceRoot, branch) {
+  const storePath = branchStorePath(workspaceRoot, branch);
+  mkdirSync(storePath, { recursive: true });
+  const manifestPath = branchStoreManifestPath(storePath);
+  const existing = readBranchStoreManifest(storePath);
+  if (existing !== null && !branchStoreManifestMatches(storePath, branch)) {
+    throw new Error(`Branch store identity mismatch at ${storePath}; refusing to attach it to '${branch}'.`);
+  }
+  if (existing === null) {
+    if (existsSync2(manifestPath)) {
+      throw new Error(`Branch store manifest is invalid at ${manifestPath}; refusing to overwrite it.`);
+    }
+    const entries = readdirSync(storePath);
+    if (entries.length > 0) {
+      throw new Error(`Branch store at ${storePath} has compiled data but no valid identity manifest; refusing to adopt it.`);
+    }
+    writeFileSync(manifestPath, `${JSON.stringify(expectedBranchStoreManifest(branch), null, 2)}
+`, { mode: 384 });
+  }
+  return storePath;
+}
+
+// ../cli/src/utils/branch-resolver.ts
+var defaultDeps = {
+  execSync: rawExecSync,
+  execFileSync: rawExecFileSync
+};
+var VOLATILE_ARTIFACTS = new Set([
+  "sync-cache.json",
+  "journal.log",
+  "audit.log",
+  "lock",
+  "lockfile",
+  ".lock"
+]);
+var VOLATILE_EXTENSIONS = new Set([".lock", ".tmp", ".temp", ".pid"]);
+function isValidBranchName(name) {
+  if (!name || name.length === 0 || name.length > 255)
+    return false;
+  const hasControlCharacter = [...name].some((character) => {
+    const codePoint = character.codePointAt(0) ?? 0;
+    return codePoint <= 32 || codePoint === 127;
+  });
+  if (name.includes("..") || path3.isAbsolute(name) || name.startsWith("/")) {
+    return false;
+  }
+  if (name.includes("//") || name.endsWith("/") || name.endsWith(".") || name.includes("\\") || name.startsWith("-") || name.includes("@{") || name.includes("..") || hasControlCharacter || /[~^:?*\[\]]/.test(name)) {
+    return false;
+  }
+  const components = name.split("/");
+  if (components.some((component) => component.startsWith(".") || component.endsWith(".lock"))) {
+    return false;
+  }
+  try {
+    defaultDeps.execFileSync("git", ["check-ref-format", "--branch", name], {
+      stdio: ["ignore", "ignore", "ignore"],
+      timeout: 5000
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ../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";
+var ENGINE_QUERY_CACHE_MAX_ENTRIES = 128;
+var ENGINE_QUERY_CACHE_MAX_RESULT_BYTES = 8 * 1024 * 1024;
+var ENGINE_FRESHNESS_CACHE_MS = 100;
+var ENGINE_PUBLICATION_LOCK_STALE_MS = 5000;
+function engineIdleTimeoutMs() {
+  const configured = Number.parseInt(process.env.KIBI_ENGINE_IDLE_TIMEOUT_MS ?? "", 10);
+  return Number.isFinite(configured) && configured >= 100 ? configured : ENGINE_IDLE_TIMEOUT_MS;
+}
+function quoteProlog(value) {
+  return value.replaceAll("'", "''");
+}
+function cacheableEngineGoal(goal) {
+  const normalized = goal.trim();
+  if (!normalized || normalized.startsWith("(") || normalized.includes("kb_storage_status")) {
+    return false;
+  }
+  return normalized.startsWith("findall(") || normalized.startsWith("kb_entity(") || normalized.startsWith("kb_entities_by_source(") || normalized.startsWith("kb_relationship(");
+}
+function mutatingEngineGoal(goal) {
+  return /(?:kb_(?:assert|retract|commit|save|delete)|rdf_transaction|rdf_assert|rdf_retract)/.test(goal);
+}
+function maskPrologData(goal) {
+  const chars = [...goal];
+  let quote = null;
+  let lineComment = false;
+  let blockComment = false;
+  for (let index = 0;index < chars.length; index += 1) {
+    const current = chars[index];
+    const next = chars[index + 1];
+    if (lineComment) {
+      if (current === `
+`)
+        lineComment = false;
+      else
+        chars[index] = " ";
+      continue;
+    }
+    if (blockComment) {
+      if (current === "*" && next === "/") {
+        chars[index] = " ";
+        chars[index + 1] = " ";
+        index += 1;
+        blockComment = false;
+      } else if (current !== `
+`) {
+        chars[index] = " ";
+      }
+      continue;
+    }
+    if (quote !== null) {
+      if (current === "\\") {
+        chars[index] = " ";
+        if (index + 1 < chars.length) {
+          chars[index + 1] = " ";
+          index += 1;
+        }
+      } else if (current === quote) {
+        if (next === quote) {
+          chars[index] = " ";
+          chars[index + 1] = " ";
+          index += 1;
+        } else {
+          chars[index] = " ";
+          quote = null;
+        }
+      } else if (current !== `
+`) {
+        chars[index] = " ";
+      }
+      continue;
+    }
+    if (current === "%") {
+      chars[index] = " ";
+      lineComment = true;
+    } else if (current === "/" && next === "*") {
+      chars[index] = " ";
+      chars[index + 1] = " ";
+      index += 1;
+      blockComment = true;
+    } else if (current === "'" || current === '"' || current === "`") {
+      chars[index] = " ";
+      quote = current;
+    }
+  }
+  return chars.join("");
+}
+function safeEngineGoal(goal) {
+  const executable = maskPrologData(goal);
+  if (/\b(?:halt|abort|shell|system|process_create|consult|load_files|open|close|delete_file|rename_file|make_directory|thread_create|rdf_attach_db|rdf_load|rdf_save|assertz|asserta|retractall|set_prolog_flag)\s*\(/.test(executable)) {
+    return false;
+  }
+  return /(?:^|[(:,\s])(?:kb_|checks:|status:|discovery:|requirement_proof:|findall\(|aggregate_all\(|rdf_transaction\(|use_module\(|atom_json_dict\(|member\(|once\(|true\b|fail\b)/.test(goal.trim());
+}
+function frame(value) {
+  const payload = Buffer.from(JSON.stringify(value), "utf8");
+  const header = Buffer.allocUnsafe(4);
+  header.writeUInt32BE(payload.byteLength, 0);
+  return Buffer.concat([header, payload]);
+}
+function writeSocketFrame(socket, value) {
+  if (socket.destroyed || !socket.writable)
+    return;
+  try {
+    socket.write(frame(value));
+  } catch {}
+}
+function parseFrames(buffer, onFrame) {
+  let cursor = 0;
+  while (buffer.byteLength - cursor >= 4) {
+    const length = buffer.readUInt32BE(cursor);
+    if (length > 64 * 1024 * 1024) {
+      throw new Error("Kibi engine frame exceeds 64 MiB limit");
+    }
+    if (buffer.byteLength - cursor - 4 < length)
+      break;
+    const payload = buffer.subarray(cursor + 4, cursor + 4 + length);
+    onFrame(JSON.parse(payload.toString("utf8")));
+    cursor += 4 + length;
+  }
+  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")];
+  for (const candidate of candidates) {
+    try {
+      mkdirSync2(candidate, { recursive: true, mode: 448 });
+      const probe = path4.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");
+}
+function fsyncPath(filePath) {
+  if (!existsSync3(filePath))
+    return;
+  let descriptor = null;
+  try {
+    descriptor = openSync(filePath, "r");
+    fsyncSync(descriptor);
+  } finally {
+    if (descriptor !== null)
+      closeSync(descriptor);
+  }
+}
+function fsyncJournaledBranchStore(branchPath) {
+  const rdfRoot = path4.join(branchPath, "rdf");
+  const directories = [];
+  const pending = existsSync3(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);
+      if (entry.isDirectory())
+        pending.push(entryPath);
+      else if (entry.isFile() && entry.name !== "lock")
+        fsyncPath(entryPath);
+    }
+  }
+  for (const metadata of ["CURRENT", "storage.json", "kb.rdf"]) {
+    fsyncPath(path4.join(branchPath, metadata));
+  }
+  if (process.platform !== "win32") {
+    for (const directory of directories.reverse())
+      fsyncPath(directory);
+    fsyncPath(branchPath);
+  }
+}
+function engineSocketPath(workspaceRoot, branch) {
+  const canonicalRoot = (() => {
+    try {
+      return realpathSync(workspaceRoot);
+    } catch {
+      return path4.resolve(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`);
+}
+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 `${socket}.pid`;
+}
+function engineStartLockPath(workspaceRoot, branch) {
+  if (process.platform === "win32") {
+    return path4.join(runtimeDirectory(), `kibi-${createHash2("sha256").update(`${path4.resolve(workspaceRoot)}\x00${branch}`).digest("hex")}.start.lock`);
+  }
+  return `${engineSocketPath(workspaceRoot, branch)}.start.lock`;
+}
+function enginePublicationLockPath(workspaceRoot, branch) {
+  return `${engineSocketPath(workspaceRoot, branch)}.publish.lock`;
+}
+function publicationLockOwner(lockPath) {
+  try {
+    const [pidText, createdText] = readFileSync2(lockPath, "utf8").trim().split(":");
+    const pid = Number.parseInt(pidText ?? "", 10);
+    const createdAt = Number.parseInt(createdText ?? "", 10);
+    if (!Number.isInteger(pid) || pid <= 1 || !Number.isFinite(createdAt)) {
+      return null;
+    }
+    return { pid, createdAt };
+  } catch {
+    return null;
+  }
+}
+function processIsAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function clearStalePublicationLock(lockPath) {
+  if (!existsSync3(lockPath))
+    return true;
+  const owner = publicationLockOwner(lockPath);
+  let age = 0;
+  try {
+    age = Date.now() - statSync2(lockPath).mtimeMs;
+  } catch {
+    return false;
+  }
+  if ((owner === null || !processIsAlive(owner.pid)) && age > ENGINE_PUBLICATION_LOCK_STALE_MS) {
+    try {
+      unlinkSync(lockPath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+function publicationLockIsActive(lockPath) {
+  if (!existsSync3(lockPath))
+    return false;
+  if (clearStalePublicationLock(lockPath))
+    return false;
+  return existsSync3(lockPath);
+}
+function tryAcquireStartLock(lockPath) {
+  try {
+    const descriptor = openSync(lockPath, "wx", 384);
+    writeFileSync2(lockPath, `${process.pid}:${Date.now()}
+`, { flag: "w" });
+    return descriptor;
+  } catch {
+    try {
+      const stamp = readFileSync2(lockPath, "utf8").trim().split(":");
+      const pid = Number.parseInt(stamp[0] ?? "", 10);
+      const created = Number.parseInt(stamp[1] ?? "", 10);
+      let age = 0;
+      try {
+        age = Date.now() - statSync2(lockPath).mtimeMs;
+      } catch {
+        age = 0;
+      }
+      if (!Number.isFinite(created) && age <= 5000)
+        return null;
+      let alive = false;
+      if (Number.isFinite(pid) && pid > 0) {
+        try {
+          process.kill(pid, 0);
+          alive = true;
+        } catch {
+          alive = false;
+        }
+      }
+      if (!alive && (Number.isFinite(created) ? Date.now() - created > 5000 : age > 5000)) {
+        unlinkSync(lockPath);
+      }
+    } catch {}
+    return null;
+  }
+}
+function releaseStartLock(lockPath, descriptor) {
+  if (descriptor !== null) {
+    try {
+      closeSync(descriptor);
+    } catch {}
+  }
+  try {
+    unlinkSync(lockPath);
+  } catch {}
+}
+function recoverStaleJournalLock(branchPath) {
+  const lockPath = path4.join(branchPath, "rdf", "lock");
+  if (!existsSync3(lockPath))
+    return;
+  let contents = "";
+  try {
+    contents = readFileSync2(lockPath, "utf8");
+  } catch {
+    return;
+  }
+  const match = /pid\((\d+)\)/.exec(contents);
+  if (!match)
+    return;
+  const pid = Number.parseInt(match[1] ?? "", 10);
+  if (!Number.isFinite(pid) || pid <= 0 || pid === process.pid)
+    return;
+  try {
+    process.kill(pid, 0);
+    return;
+  } catch {
+    try {
+      rmSync(lockPath, { force: true });
+    } catch {}
+  }
+}
+function daemonEntry() {
+  const moduleDirectory = path4.dirname(fileURLToPath2(import.meta.url));
+  const candidates = [
+    path4.join(moduleDirectory, "engine-daemon.js"),
+    path4.join(moduleDirectory, "..", "dist", "engine-daemon.js"),
+    path4.join(moduleDirectory, "..", "node_modules", "kibi-cli", "dist", "engine-daemon.js")
+  ];
+  for (const candidate of candidates) {
+    if (existsSync3(candidate))
+      return candidate;
+  }
+  throw new Error("The Kibi engine is not built. Run `npm run build:cli` before using the CLI engine.");
+}
+function connectSocket(socketPath, timeoutMs) {
+  return new Promise((resolve3, reject) => {
+    const socket = net.createConnection(socketPath);
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled)
+        return;
+      settled = true;
+      socket.destroy();
+      reject(new Error(`Timed out connecting to Kibi engine at ${socketPath}`));
+    }, timeoutMs);
+    socket.once("connect", () => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      resolve3(socket);
+    });
+    socket.on("error", (error) => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      reject(error);
+    });
+  });
+}
+async function connectWithRetry(socketPath, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  let lastError;
+  while (Date.now() < deadline) {
+    const errorPath = `${socketPath}.error`;
+    if (existsSync3(errorPath)) {
+      try {
+        const diagnostic = readFileSync2(errorPath, "utf8").trim();
+        if (diagnostic)
+          throw new Error(diagnostic);
+      } catch (error) {
+        throw new Error(`Kibi engine failed to start: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+    if (process.platform !== "win32" && !existsSync3(socketPath)) {
+      await new Promise((resolve3) => setTimeout(resolve3, 25));
+      continue;
+    }
+    try {
+      return await connectSocket(socketPath, Math.min(250, deadline - Date.now()));
+    } catch (error) {
+      lastError = error;
+      await new Promise((resolve3) => setTimeout(resolve3, 25));
+    }
+  }
+  throw new Error(`Unable to connect to Kibi engine at ${socketPath}: ${lastError instanceof Error ? lastError.message : String(lastError)}`);
+}
+
+class EngineClient {
+  workspaceRoot;
+  branch;
+  timeout;
+  allowPublicationLock;
+  socket = null;
+  daemon = null;
+  inputBuffer = Buffer.alloc(0);
+  requestId = 0;
+  pending = new Map;
+  requestTail = Promise.resolve();
+  lastResult = null;
+  constructor(options) {
+    if (!isValidBranchName(options.branch)) {
+      throw new Error(`Invalid Kibi engine branch name: ${options.branch}`);
+    }
+    const resolvedWorkspaceRoot = path4.resolve(options.workspaceRoot);
+    try {
+      this.workspaceRoot = realpathSync(resolvedWorkspaceRoot);
+    } catch {
+      this.workspaceRoot = resolvedWorkspaceRoot;
+    }
+    this.branch = options.branch;
+    this.timeout = options.timeout ?? 120000;
+    this.allowPublicationLock = options.allowPublicationLock ?? false;
+  }
+  async start(allowSpawn = true) {
+    if (this.socket !== null && !this.socket.destroyed)
+      return;
+    const socketPath = engineSocketPath(this.workspaceRoot, this.branch);
+    const publicationLockPath = enginePublicationLockPath(this.workspaceRoot, this.branch);
+    if (!this.allowPublicationLock && publicationLockIsActive(publicationLockPath)) {
+      throw new Error(`Kibi engine publication is in progress: ${publicationLockPath}`);
+    }
+    try {
+      if (existsSync3(socketPath)) {
+        this.socket = await connectWithRetry(socketPath, 150);
+      } else {
+        throw new Error("engine socket is absent");
+      }
+    } catch {
+      if (!allowSpawn)
+        return;
+      const nodePath = process.env.KIBI_NODE_PATH ?? "node";
+      const entry = daemonEntry();
+      const lockPath = engineStartLockPath(this.workspaceRoot, this.branch);
+      const startDeadline = Date.now() + this.timeout;
+      let lock = null;
+      while (lock === null && Date.now() < startDeadline) {
+        if (existsSync3(socketPath)) {
+          try {
+            this.socket = await connectWithRetry(socketPath, 100);
+            break;
+          } catch {}
+        }
+        if (this.socket === null) {
+          lock = tryAcquireStartLock(lockPath);
+          if (lock === null) {
+            await new Promise((resolve3) => setTimeout(resolve3, 50));
+          }
+        }
+      }
+      if (this.socket === null && lock === null) {
+        throw new Error(`Unable to connect to Kibi engine at ${socketPath} while another starter owns ${lockPath}`);
+      }
+      if (lock !== null) {
+        try {
+          rmSync(`${socketPath}.error`, { force: true });
+          try {
+            const daemon = spawn2(nodePath, [
+              entry,
+              "--workspace",
+              this.workspaceRoot,
+              "--branch",
+              this.branch,
+              "--socket",
+              socketPath
+            ], {
+              detached: true,
+              stdio: "ignore",
+              env: {
+                ...process.env,
+                KIBI_ENGINE_PROTOCOL: String(ENGINE_PROTOCOL_VERSION)
+              }
+            });
+            await new Promise((resolve3, reject) => {
+              daemon.once("spawn", resolve3);
+              daemon.once("error", reject);
+            });
+            this.daemon = daemon;
+          } catch (error) {
+            throw new Error(`Kibi engine requires Node.js >=18 to host the daemon; failed to start '${nodePath}': ${error instanceof Error ? error.message : String(error)}`);
+          }
+          this.daemon.unref();
+          this.socket = await connectWithRetry(socketPath, this.timeout);
+        } finally {
+          releaseStartLock(lockPath, lock);
+        }
+      }
+    }
+    if (this.socket === null)
+      return;
+    this.attachSocket(this.socket);
+  }
+  attachSocket(socket) {
+    socket.on("data", (chunk) => {
+      try {
+        const bytes = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+        this.inputBuffer = parseFrames(Buffer.concat([this.inputBuffer, bytes]), (value) => this.handleResponse(value));
+      } catch (error) {
+        socket.destroy(error instanceof Error ? error : new Error(String(error)));
+      }
+    });
+    socket.on("close", () => {
+      this.socket = null;
+      const error = new Error("Kibi engine connection closed");
+      for (const pending of this.pending.values())
+        pending.reject(error);
+      this.pending.clear();
+    });
+    socket.on("error", (error) => {
+      for (const pending of this.pending.values())
+        pending.reject(error);
+      this.pending.clear();
+    });
+  }
+  handleResponse(value) {
+    if (value === null || typeof value !== "object")
+      return;
+    const response = value;
+    if (typeof response.id !== "number")
+      return;
+    const pending = this.pending.get(response.id);
+    if (!pending)
+      return;
+    this.pending.delete(response.id);
+    if (response.ok)
+      pending.resolve(response.result);
+    else
+      pending.reject(new Error(response.error ?? "Kibi engine request failed"));
+  }
+  async request(request, signal) {
+    await this.start();
+    const socket = this.socket;
+    if (socket === null || socket.destroyed)
+      throw new Error("Kibi engine is not connected");
+    const id = ++this.requestId;
+    const result = new Promise((resolve3, reject) => {
+      this.pending.set(id, {
+        resolve: resolve3,
+        reject
+      });
+      try {
+        socket.write(frame({
+          ...request,
+          id,
+          protocolVersion: ENGINE_PROTOCOL_VERSION,
+          packageVersions: ENGINE_PACKAGE_VERSIONS,
+          workspaceRoot: this.workspaceRoot,
+          branch: this.branch
+        }));
+      } catch (error) {
+        this.pending.delete(id);
+        reject(error instanceof Error ? error : new Error(String(error)));
+        return;
+      }
+      if (signal !== undefined) {
+        const abort = () => {
+          if (!this.pending.has(id))
+            return;
+          this.pending.delete(id);
+          this.cancel(id);
+          reject(new Error("Kibi engine request cancelled"));
+        };
+        if (signal.aborted)
+          abort();
+        else
+          signal.addEventListener("abort", abort, { once: true });
+      }
+    });
+    return result;
+  }
+  async query(goal, signal) {
+    let result;
+    const previous = this.requestTail;
+    let release;
+    this.requestTail = new Promise((resolve3) => {
+      release = resolve3;
+    });
+    await previous;
+    try {
+      result = await this.request({ method: "query", goal }, signal);
+      this.lastResult = result;
+      return result;
+    } finally {
+      release();
+    }
+  }
+  async command(command, signal) {
+    return this.request({ method: "command", command }, signal);
+  }
+  async queryBatch(goals) {
+    const normalized = goals.map((goal) => goal.trim().replace(/\.+\s*$/, ""));
+    return this.query(`rdf_transaction((${normalized.join(", ")}))`);
+  }
+  async queryEntities(input, signal) {
+    const result = await this.command({
+      version: 1,
+      kind: "entities",
+      ...input.type !== undefined ? { type: input.type } : {},
+      ...input.id !== undefined ? { id: input.id } : {},
+      ...input.tags !== undefined ? { tags: input.tags } : {},
+      ...input.sourceFile !== undefined ? { sourceFile: input.sourceFile } : {},
+      limit: input.limit,
+      offset: input.offset
+    }, signal);
+    if (!result.success) {
+      throw new Error(result.error ?? "Indexed entity query failed");
+    }
+    const rows = result.bindings.Rows ? parseListOfLists(result.bindings.Rows).map(parseEntityFromList) : [];
+    const count = Number.parseInt(result.bindings.Count ?? "0", 10);
+    return {
+      entities: rows,
+      count: Number.isFinite(count) ? count : rows.length
+    };
+  }
+  async searchEntities(input, signal) {
+    const result = await this.command({
+      version: 1,
+      kind: "search",
+      query: input.query,
+      ...input.type !== undefined ? { type: input.type } : {},
+      limit: input.limit,
+      offset: input.offset
+    }, signal);
+    if (!result.success) {
+      throw new Error(result.error ?? "Indexed search candidate query failed");
+    }
+    const rows = result.bindings.Rows ? parseListOfLists(result.bindings.Rows).map(parseEntityFromList) : [];
+    const count = Number.parseInt(result.bindings.Count ?? "0", 10);
+    return {
+      entities: rows,
+      count: Number.isFinite(count) ? count : rows.length
+    };
+  }
+  cancel(requestId) {
+    const socket = this.socket;
+    if (socket === null || socket.destroyed)
+      return;
+    const id = ++this.requestId;
+    socket.write(frame({
+      id,
+      method: "cancel",
+      cancelOf: requestId,
+      protocolVersion: ENGINE_PROTOCOL_VERSION,
+      packageVersions: ENGINE_PACKAGE_VERSIONS,
+      workspaceRoot: this.workspaceRoot,
+      branch: this.branch
+    }));
+  }
+  async nextSolution() {
+    const result = this.lastResult;
+    this.lastResult = null;
+    return result;
+  }
+  async save(signal) {
+    return this.query("kb_save", signal);
+  }
+  async storageStatus() {
+    return this.request({ method: "status" });
+  }
+  async checkpoint() {
+    return this.command({ version: 1, kind: "checkpoint" });
+  }
+  async queryStatusJson() {
+    return this.command({ version: 1, kind: "status" });
+  }
+  async compact() {
+    return this.command({ version: 1, kind: "compact" });
+  }
+  async exportStorage(targetDirectory) {
+    return this.request({
+      method: "export",
+      targetDirectory
+    });
+  }
+  invalidateCache() {
+    this.lastResult = null;
+  }
+  isRunning() {
+    return this.socket !== null && !this.socket.destroyed;
+  }
+  getPid() {
+    const pidPath = enginePidPath(this.workspaceRoot, this.branch);
+    try {
+      return Number.parseInt(readFileSync2(pidPath, "utf8").trim(), 10) || 0;
+    } catch {
+      return 0;
+    }
+  }
+  async stop(startIfMissing = true) {
+    const socketPath = engineSocketPath(this.workspaceRoot, this.branch);
+    if (!this.isRunning()) {
+      try {
+        await this.start(startIfMissing);
+      } catch {
+        if (!startIfMissing)
+          return;
+        throw new Error("Unable to start Kibi engine for stop request");
+      }
+    }
+    if (!this.isRunning()) {
+      if (existsSync3(socketPath)) {
+        throw new Error(`Kibi engine socket remains present but is not reachable: ${socketPath}`);
+      }
+      return;
+    }
+    let requestError;
+    try {
+      await this.request({ method: "stop" });
+    } catch (error) {
+      requestError = error;
+    }
+    this.socket?.destroy();
+    this.socket = null;
+    const deadline = Date.now() + 5000;
+    while (existsSync3(socketPath) && Date.now() < deadline) {
+      await new Promise((resolve3) => setTimeout(resolve3, 25));
+    }
+    if (existsSync3(socketPath)) {
+      const detail = requestError instanceof Error ? `: ${requestError.message}` : "";
+      throw new Error(`Kibi engine did not stop within 5 seconds${detail}`);
+    }
+  }
+  async terminate() {
+    this.socket?.end();
+    this.socket?.destroy();
+    this.socket = null;
+    this.daemon = null;
+    this.lastResult = null;
+  }
+}
+async function ensureJournaledBranchStoreAsync(branchPath) {
+  mkdirSync2(branchPath, { recursive: true });
+  const markerPath = path4.join(branchPath, "storage.json");
+  const marker = existsSync3(markerPath) ? readFileSync2(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 (!existsSync3(rdfDirectory) || !existsSync3(currentPath)) {
+      recoverInterruptedGeneration(branchPath);
+      if (existsSync3(rdfDirectory) && existsSync3(currentPath)) {
+        recoverStaleJournalLock(branchPath);
+        archiveLegacyFiles(branchPath);
+        if (!existsSync3(sentinelPath)) {
+          writeFileSync2(sentinelPath, `KIBI_STORAGE_FORMAT=kibi.rdf-journal.v1
+`, { mode: 384 });
+        }
+        return;
+      }
+      const legacyRdf2 = path4.join(branchPath, "kb.rdf");
+      const legacyAudit2 = path4.join(branchPath, "audit.log");
+      const legacyContents = existsSync3(legacyRdf2) ? readFileSync2(legacyRdf2, "utf8") : "";
+      if (existsSync3(legacyAudit2) || existsSync3(legacyRdf2) && !legacyContents.includes("kibi.rdf-journal.v1")) {
+        rmSync(rdfDirectory, { recursive: true, force: true });
+        rmSync(currentPath, { force: true });
+        rmSync(markerPath, { force: true });
+      } else {
+        throw new Error(`Journaled branch store is incomplete at ${branchPath}; restore the immutable legacy/ backup or remove the interrupted generation before retrying`);
+      }
+    } else {
+      recoverStaleJournalLock(branchPath);
+      archiveLegacyFiles(branchPath);
+      if (!existsSync3(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 (!existsSync3(legacyRdf) && !existsSync3(legacyAudit)) {
+    mkdirSync2(path4.join(branchPath, "rdf"), { recursive: true });
+    writeFileSync2(markerPath, `{"format":"kibi.rdf-journal.v1","schemaVersion":1}
+`, { mode: 384 });
+    writeFileSync2(path4.join(branchPath, "CURRENT"), `generation-1:0
+`, {
+      mode: 384
+    });
+    writeFileSync2(path4.join(branchPath, "kb.rdf"), `KIBI_STORAGE_FORMAT=kibi.rdf-journal.v1
+`, { mode: 384 });
+    return;
+  }
+  if (existsSync3(legacyRdf)) {
+    const legacyContents = readFileSync2(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()}`);
+  mkdirSync2(staging, { recursive: true, mode: 448 });
+  const testOneShot = false;
+  const migrator = new PrologProcess({
+    timeout: 120000,
+    oneShot: testOneShot
+  });
+  try {
+    if (!testOneShot)
+      await migrator.start();
+    const attachGoal = `kb_attach('${quoteProlog(branchPath)}')`;
+    const migrateGoal = `kb_migrate_legacy('${quoteProlog(branchPath)}','${quoteProlog(staging)}')`;
+    const migrated = testOneShot ? await migrator.query(`(${attachGoal}, ${migrateGoal})`) : await (async () => {
+      const attach = await migrator.query(attachGoal);
+      if (!attach.success)
+        throw new Error(attach.error ?? "Failed to attach legacy KB");
+      return migrator.query(migrateGoal);
+    })();
+    if (!migrated.success)
+      throw new Error(migrated.error ?? "Legacy KB migration failed");
+    fsyncJournaledBranchStore(staging);
+  } catch (error) {
+    rmSync(staging, { recursive: true, force: true });
+    throw error;
+  } finally {
+    await migrator.terminate();
+  }
+  for (const file of ["rdf", "storage.json", "CURRENT"]) {
+    const source = path4.join(staging, file);
+    if (!existsSync3(source))
+      continue;
+    const target = path4.join(branchPath, file);
+    if (existsSync3(target))
+      rmSync(target, { recursive: true, force: true });
+    renameSync(source, target);
+  }
+  archiveLegacyFiles(branchPath);
+  writeFileSync2(path4.join(branchPath, "kb.rdf"), `KIBI_STORAGE_FORMAT=kibi.rdf-journal.v1
+`, { mode: 384 });
+  fsyncJournaledBranchStore(branchPath);
+  rmSync(staging, { recursive: true, force: true });
+}
+function archiveLegacyFiles(branchPath) {
+  const legacyDir = path4.join(branchPath, "legacy");
+  mkdirSync2(legacyDir, { recursive: true, mode: 448 });
+  for (const file of ["kb.rdf", "audit.log"]) {
+    const source = path4.join(branchPath, file);
+    if (!existsSync3(source))
+      continue;
+    if (file === "kb.rdf") {
+      const contents = readFileSync2(source, "utf8");
+      if (contents.includes("kibi.rdf-journal.v1"))
+        continue;
+    }
+    const destination = path4.join(legacyDir, file);
+    if (existsSync3(destination)) {
+      renameSync(source, path4.join(legacyDir, `${file}.recovery.${Date.now()}`));
+    } else {
+      renameSync(source, destination);
+    }
+  }
+}
+function recoverInterruptedGeneration(branchPath) {
+  let entries = [];
+  try {
+    entries = readdirSync2(branchPath);
+  } catch {
+    return;
+  }
+  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);
+  };
+  const oldRdf = newest("rdf.old.");
+  const oldCurrent = newest("CURRENT.old.");
+  const rdfPath = path4.join(branchPath, "rdf");
+  const currentPath = path4.join(branchPath, "CURRENT");
+  if ((!existsSync3(rdfPath) || !existsSync3(currentPath)) && oldRdf && oldCurrent) {
+    try {
+      if (existsSync3(rdfPath))
+        rmSync(rdfPath, { recursive: true, force: true });
+      if (existsSync3(currentPath))
+        rmSync(currentPath, { force: true });
+      renameSync(oldRdf, rdfPath);
+      renameSync(oldCurrent, currentPath);
+      return;
+    } catch {}
+  }
+  if (!existsSync3(rdfPath) && oldRdf) {
+    try {
+      renameSync(oldRdf, rdfPath);
+    } catch {}
+  }
+  if (!existsSync3(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}`);
+  }
+  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)
+    throw new Error(attached.error ?? "Failed to attach branch KB");
+  const statusModulePath = path4.join(path4.dirname(resolveKbPlPath()), "status.pl");
+  const statusLoaded = await prolog.query(`use_module('${quoteProlog(statusModulePath.replaceAll("\\", "/"))}')`);
+  if (!statusLoaded.success) {
+    throw new Error(statusLoaded.error ?? "Failed to load Kibi status module");
+  }
+  mkdirSync2(path4.dirname(options.socketPath), { recursive: true, mode: 448 });
+  if (existsSync3(options.socketPath)) {
+    let live = false;
+    try {
+      const existing = await connectSocket(options.socketPath, 100);
+      existing.destroy();
+      live = true;
+    } catch {}
+    if (live) {
+      throw new Error(`A Kibi engine is already listening at ${options.socketPath}`);
+    }
+    try {
+      rmSync(options.socketPath, { force: true });
+    } catch {}
+  }
+  writeFileSync2(enginePidPath(options.workspaceRoot, options.branch), `${process.pid}
+`, { mode: 384 });
+  const server = net.createServer();
+  let activeClients = 0;
+  let idleTimer = null;
+  let queue = Promise.resolve();
+  let idleCompactionQueued = false;
+  const queryCache = new Map;
+  let freshnessCache = null;
+  const cancelledRequests = new Set;
+  const clients = new Set;
+  let shuttingDown = false;
+  const exactBranchStatus = (result) => {
+    if (!result.success || typeof result.bindings.JsonString !== "string") {
+      return result;
+    }
+    try {
+      const decoded = JSON.parse(JSON.parse(result.bindings.JsonString));
+      decoded.branch = options.branch;
+      return {
+        ...result,
+        bindings: {
+          ...result.bindings,
+          JsonString: JSON.stringify(JSON.stringify(decoded))
+        }
+      };
+    } catch {
+      return result;
+    }
+  };
+  const scheduleIdleExit = () => {
+    if (activeClients > 0)
+      return;
+    if (!idleCompactionQueued) {
+      idleCompactionQueued = true;
+      queue = queue.then(async () => {
+        if (activeClients === 0) {
+          await prolog.query("kb_storage_compact_if_needed");
+        }
+      }).catch(() => {
+        return;
+      }).finally(() => {
+        idleCompactionQueued = false;
+      });
+    }
+    if (idleTimer)
+      clearTimeout(idleTimer);
+    idleTimer = setTimeout(() => {
+      if (activeClients === 0)
+        shutdown();
+    }, engineIdleTimeoutMs());
+  };
+  const handle = async (request) => {
+    if (request.protocolVersion !== ENGINE_PROTOCOL_VERSION) {
+      throw new Error(`Kibi engine protocol mismatch: client=${request.protocolVersion ?? "missing"}, server=${ENGINE_PROTOCOL_VERSION}`);
+    }
+    const expectedPackages = process.env.KIBI_PACKAGE_VERSIONS;
+    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) {
+      throw new Error("Kibi engine workspace identity mismatch");
+    }
+    switch (request.method) {
+      case "entities": {
+        const limit = request.limit ?? 100;
+        const offset = request.offset ?? 0;
+        if (!Number.isInteger(limit) || !Number.isInteger(offset) || limit < 0 || offset < 0 || limit > 1e5) {
+          throw new Error("entities.limit/offset must be bounded integers");
+        }
+        const type = request.type === undefined ? "none" : `'${quoteProlog(request.type)}'`;
+        const id = request.entityId === undefined ? "none" : `'${quoteProlog(request.entityId)}'`;
+        const tags = `[${(request.tags ?? []).map((tag) => `'${quoteProlog(tag)}'`).join(",")}]`;
+        const source = request.sourceFile === undefined ? "none" : `'${quoteProlog(request.sourceFile)}'`;
+        const result = await prolog.query(`kb_query_entities(${type}, ${id}, ${tags}, ${source}, ${limit}, ${offset}, Rows, Count)`);
+        if (!result.success) {
+          throw new Error(result.error ?? "Indexed entity query failed");
+        }
+        return result;
+      }
+      case "search": {
+        const limit = request.limit ?? 1e4;
+        const offset = request.offset ?? 0;
+        if (typeof request.searchQuery !== "string" || request.searchQuery.trim().length === 0) {
+          throw new Error("search.searchQuery must be a non-empty string");
+        }
+        if (!Number.isInteger(limit) || !Number.isInteger(offset) || limit < 0 || offset < 0 || limit > 1e5) {
+          throw new Error("search.limit/offset must be bounded integers");
+        }
+        const type = request.type === undefined ? "none" : `'${quoteProlog(request.type)}'`;
+        const result = await prolog.query(`kb_search_entities(${type}, '${quoteProlog(request.searchQuery)}', ${limit}, ${offset}, Rows, Count)`);
+        if (!result.success) {
+          throw new Error(result.error ?? "Indexed search candidate query failed");
+        }
+        return result;
+      }
+      case "command": {
+        const command = request.command;
+        if (command === undefined || command.version !== 1) {
+          throw new Error("engine.command must use version 1");
+        }
+        switch (command.kind) {
+          case "status":
+            return exactBranchStatus(await prolog.query("status:kb_status_json(JsonString)"));
+          case "checkpoint": {
+            queryCache.clear();
+            freshnessCache = null;
+            const result = await prolog.query("kb_sync_checkpoint");
+            if (result.success)
+              fsyncJournaledBranchStore(branchPath);
+            return result;
+          }
+          case "compact": {
+            const result = await prolog.query("kb_storage_compact");
+            if (result.success)
+              fsyncJournaledBranchStore(branchPath);
+            return result;
+          }
+          case "save": {
+            const result = await prolog.query("kb_save");
+            if (result.success)
+              fsyncJournaledBranchStore(branchPath);
+            return result;
+          }
+          case "check": {
+            if (command.rule !== undefined && !/^[a-z][a-z0-9_]*$/.test(command.rule)) {
+              throw new Error("engine.check.rule must be a lowercase rule name");
+            }
+            return prolog.query("checks:check_all_json(JsonString)");
+          }
+          case "relationship": {
+            if (!command.type || !command.from || !command.to) {
+              throw new Error("engine.relationship requires type, from, and to");
+            }
+            const type = quoteProlog(command.type);
+            const from = quoteProlog(command.from);
+            const to = quoteProlog(command.to);
+            const goal = command.action === "assert" ? `kb_assert_relationship('${type}', '${from}', '${to}', [])` : `kb_retract_relationship('${type}', '${from}', '${to}')`;
+            const result = await prolog.query(goal);
+            if (result.success) {
+              queryCache.clear();
+              freshnessCache = null;
+              fsyncJournaledBranchStore(branchPath);
+            }
+            return result;
+          }
+          case "persistence": {
+            const goal = command.action === "checkpoint" ? "kb_sync_checkpoint" : command.action === "compact" ? "kb_storage_compact" : command.action === "save" ? "kb_save" : command.targetDirectory ? `kb_storage_export('${quoteProlog(command.targetDirectory)}')` : null;
+            if (goal === null) {
+              throw new Error("engine.persistence.export requires targetDirectory");
+            }
+            const result = await prolog.query(goal);
+            if (result.success)
+              fsyncJournaledBranchStore(branchPath);
+            return result;
+          }
+          case "lifecycle": {
+            if (command.action === "stop") {
+              setImmediate(() => void shutdown());
+              return { stopped: true };
+            }
+            if (!Number.isInteger(command.requestId)) {
+              throw new Error("engine.lifecycle.cancel requires requestId");
+            }
+            const requestId = command.requestId;
+            cancelledRequests.add(requestId);
+            return { cancelled: requestId };
+          }
+          case "stop":
+            setImmediate(() => void shutdown());
+            return { stopped: true };
+          case "cancel":
+            cancelledRequests.add(command.requestId);
+            return { cancelled: command.requestId };
+          case "entities": {
+            if (!Number.isInteger(command.limit) || !Number.isInteger(command.offset) || command.limit < 0 || command.offset < 0 || command.limit > 1e5) {
+              throw new Error("engine.entities.limit/offset must be bounded integers");
+            }
+            const type = command.type === undefined ? "none" : `'${quoteProlog(command.type)}'`;
+            const id = command.id === undefined ? "none" : `'${quoteProlog(command.id)}'`;
+            const tags = `[${(command.tags ?? []).map((tag) => `'${quoteProlog(tag)}'`).join(",")}]`;
+            const source = command.sourceFile === undefined ? "none" : `'${quoteProlog(command.sourceFile)}'`;
+            return prolog.query(`kb_query_entities(${type}, ${id}, ${tags}, ${source}, ${command.limit}, ${command.offset}, Rows, Count)`);
+          }
+          case "search": {
+            if (!command.query.trim())
+              throw new Error("engine.search.query must be non-empty");
+            if (!Number.isInteger(command.limit) || !Number.isInteger(command.offset) || command.limit < 0 || command.offset < 0 || command.limit > 1e5) {
+              throw new Error("engine.search.limit/offset must be bounded integers");
+            }
+            const type = command.type === undefined ? "none" : `'${quoteProlog(command.type)}'`;
+            return prolog.query(`kb_search_entities(${type}, '${quoteProlog(command.query)}', ${command.limit}, ${command.offset}, Rows, Count)`);
+          }
+          default:
+            throw new Error("engine.command kind is unsupported");
+        }
+      }
+      case "kbStatus": {
+        if (freshnessCache !== null && Date.now() - freshnessCache.capturedAt <= ENGINE_FRESHNESS_CACHE_MS) {
+          return freshnessCache.result;
+        }
+        const result = exactBranchStatus(await prolog.query("status:kb_status_json(JsonString)"));
+        if (result.success) {
+          freshnessCache = { capturedAt: Date.now(), result };
+        }
+        return result;
+      }
+      case "query": {
+        if (typeof request.goal !== "string")
+          throw new Error("query.goal must be a string");
+        if (!safeEngineGoal(request.goal)) {
+          throw new Error("Kibi engine accepts only typed Kibi predicates; arbitrary Prolog goals are not exposed");
+        }
+        if (mutatingEngineGoal(request.goal)) {
+          queryCache.clear();
+          freshnessCache = null;
+        }
+        if (cacheableEngineGoal(request.goal)) {
+          const cached = queryCache.get(request.goal);
+          if (cached !== undefined)
+            return cached;
+        }
+        const result = await prolog.query(request.goal);
+        if (result.success && mutatingEngineGoal(request.goal)) {
+          fsyncJournaledBranchStore(branchPath);
+        }
+        if (result.success && cacheableEngineGoal(request.goal) && Buffer.byteLength(JSON.stringify(result), "utf8") <= ENGINE_QUERY_CACHE_MAX_RESULT_BYTES) {
+          if (queryCache.size >= ENGINE_QUERY_CACHE_MAX_ENTRIES) {
+            const oldest = queryCache.keys().next().value;
+            if (typeof oldest === "string")
+              queryCache.delete(oldest);
+          }
+          queryCache.set(request.goal, result);
+        }
+        return result;
+      }
+      case "status":
+        return prolog.query("kb_storage_status(Status), atom_json_dict(Json, Status, [])");
+      case "checkpoint": {
+        queryCache.clear();
+        freshnessCache = null;
+        const result = await prolog.query("kb_sync_checkpoint");
+        if (result.success)
+          fsyncJournaledBranchStore(branchPath);
+        return result;
+      }
+      case "compact": {
+        const result = await prolog.query("kb_storage_compact");
+        if (result.success)
+          fsyncJournaledBranchStore(branchPath);
+        return result;
+      }
+      case "export":
+        if (typeof request.targetDirectory !== "string")
+          throw new Error("export.targetDirectory is required");
+        return prolog.query(`kb_storage_export('${quoteProlog(request.targetDirectory)}')`);
+      case "stop":
+        setImmediate(() => void shutdown());
+        return { stopped: true };
+      case "cancel":
+        if (typeof request.cancelOf === "number") {
+          cancelledRequests.add(request.cancelOf);
+        }
+        return { cancelled: request.cancelOf ?? null };
+    }
+  };
+  const shutdown = async () => {
+    if (shuttingDown)
+      return;
+    shuttingDown = true;
+    process.off("SIGTERM", requestSignalShutdown);
+    process.off("SIGINT", requestSignalShutdown);
+    if (idleTimer)
+      clearTimeout(idleTimer);
+    const saved = await prolog.query("kb_save").catch(() => null);
+    if (saved?.success) {
+      try {
+        fsyncJournaledBranchStore(branchPath);
+      } catch {}
+    }
+    await prolog.terminate().catch(() => {
+      return;
+    });
+    for (const client of clients)
+      client.destroy();
+    server.close();
+    server.unref();
+    try {
+      if (existsSync3(options.socketPath))
+        rmSync(options.socketPath, { force: true });
+      if (existsSync3(enginePidPath(options.workspaceRoot, options.branch)))
+        rmSync(enginePidPath(options.workspaceRoot, options.branch), {
+          force: true
+        });
+    } catch {}
+    setTimeout(() => process.exit(0), 50).unref();
+  };
+  const requestSignalShutdown = () => {
+    shutdown();
+  };
+  process.once("SIGTERM", requestSignalShutdown);
+  process.once("SIGINT", requestSignalShutdown);
+  server.on("connection", (socket) => {
+    clients.add(socket);
+    activeClients += 1;
+    let buffer = Buffer.alloc(0);
+    socket.on("data", (chunk) => {
+      try {
+        const bytes = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+        buffer = parseFrames(Buffer.concat([buffer, bytes]), (value) => {
+          const request = value;
+          if (request.method === "cancel" && typeof request.cancelOf === "number") {
+            cancelledRequests.add(request.cancelOf);
+          }
+          queue = queue.then(async () => {
+            if (cancelledRequests.delete(request.id)) {
+              writeSocketFrame(socket, {
+                id: request.id,
+                ok: false,
+                error: "Kibi engine request cancelled",
+                serverPackageVersions: ENGINE_PACKAGE_VERSIONS
+              });
+              return;
+            }
+            try {
+              const result = await handle(request);
+              writeSocketFrame(socket, {
+                id: request.id,
+                ok: true,
+                result,
+                serverPackageVersions: ENGINE_PACKAGE_VERSIONS
+              });
+            } catch (error) {
+              writeSocketFrame(socket, {
+                id: request.id,
+                ok: false,
+                error: error instanceof Error ? error.message : String(error),
+                serverPackageVersions: ENGINE_PACKAGE_VERSIONS
+              });
+            }
+          }).catch(() => {
+            return;
+          });
+        });
+      } catch (error) {
+        socket.destroy(error instanceof Error ? error : new Error(String(error)));
+      }
+    });
+    socket.on("close", () => {
+      clients.delete(socket);
+      activeClients -= 1;
+      scheduleIdleExit();
+    });
+  });
+  await new Promise((resolve3, reject) => {
+    server.once("error", reject);
+    server.listen(options.socketPath, () => resolve3());
+  });
+  if (process.platform !== "win32") {
+    try {
+      chmodSync(options.socketPath, 384);
+    } catch {}
+  }
+  scheduleIdleExit();
+  await new Promise((resolve3) => {
+    server.once("close", resolve3);
+  });
+}
+
+// ../cli/src/engine-daemon.ts
+function requiredArg(args, name) {
+  const index = args.indexOf(name);
+  const value = index >= 0 ? args[index + 1] : undefined;
+  if (value === undefined || value.length === 0) {
+    throw new Error(`Missing ${name} argument`);
+  }
+  return value;
+}
+var args = process.argv.slice(2);
+try {
+  await runEngineDaemon({
+    workspaceRoot: requiredArg(args, "--workspace"),
+    branch: requiredArg(args, "--branch"),
+    socketPath: requiredArg(args, "--socket")
+  });
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(message);
+  const socketIndex = args.indexOf("--socket");
+  const socketPath = socketIndex >= 0 ? args[socketIndex + 1] : undefined;
+  if (socketPath) {
+    try {
+      writeFileSync3(`${socketPath}.error`, `${message}
+`, { mode: 384 });
+    } catch {}
+  }
+  process.exitCode = 1;
+}