kibi-runtime 2.1.0 → 2.3.0

package/dist/engine-daemon.js

@@ -31,6 +31,60 @@ import * as os from "node:os";
 import * as path7 from "node:path";
 import { performance as performance2 } from "node:perf_hooks";
 
+// ../cli/src/engine-limits.ts
+var QUERY_LIMIT_EXCEEDED_CODE = "QUERY_LIMIT_EXCEEDED";
+var ENGINE_READ_TIME_LIMIT_ENV = "KIBI_ENGINE_READ_TIME_LIMIT_MS";
+var ENGINE_READ_INFERENCE_LIMIT_ENV = "KIBI_ENGINE_READ_INFERENCE_LIMIT";
+var ENGINE_READ_TIME_LIMIT_CAP_MS = 115000;
+var ENGINE_READ_INFERENCE_LIMIT_CAP = 1000000000000;
+function boundedInteger(value, max) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0 && value <= max ? value : undefined;
+}
+function normalizeQueryLimits(value) {
+  if (value === null || typeof value !== "object")
+    return;
+  const raw = value;
+  const requestedTime = boundedInteger(raw.timeMs, Number.MAX_SAFE_INTEGER);
+  const timeMs = requestedTime === undefined ? undefined : Math.min(requestedTime, ENGINE_READ_TIME_LIMIT_CAP_MS);
+  const inferences = boundedInteger(raw.inferences, ENGINE_READ_INFERENCE_LIMIT_CAP);
+  if (timeMs === undefined && inferences === undefined)
+    return;
+  return {
+    ...timeMs !== undefined ? { timeMs } : {},
+    ...inferences !== undefined ? { inferences } : {}
+  };
+}
+var BOUNDED_READ_HELPER_DEFINITION = `(current_predicate(kibi_engine_bounded_read/4) -> true ; ${[
+  "assertz((kibi_engine_bounded_read(Goal, Seconds, Inferences, kibi_read_outcome(Outcome)) :- get_time(T0), statistics(inferences, I0), (catch(kibi_engine_bounded_call(Goal, Seconds, Inferences, Inner), time_limit_exceeded, Inner = time) -> Failed = false ; Failed = true), get_time(T1), statistics(inferences, I1), (Inner == time -> Outcome = time ; Inner == inferences -> Outcome = inferences ; number(Seconds), T1 - T0 >= Seconds -> Outcome = time ; integer(Inferences), I1 - I0 >= Inferences -> Outcome = inferences ; Failed == true -> fail ; Outcome = none)))",
+  "assertz((kibi_engine_bounded_call(Goal, Seconds, Inferences, Inner) :- (number(Seconds) -> call_with_time_limit(Seconds, kibi_engine_inference_call(Goal, Inferences, Inner)) ; kibi_engine_inference_call(Goal, Inferences, Inner))))",
+  "assertz((kibi_engine_inference_call(Goal, Inferences, Inner) :- (integer(Inferences) -> call_with_inference_limit(Goal, Inferences, Result), (Result == inference_limit_exceeded -> Inner = inferences ; Inner = none) ; once(Goal), Inner = none)))"
+].join(", ")})`;
+var OUTCOME_BINDING = "KibiReadOutcome";
+function boundedReadGoal(goal, limits) {
+  const seconds = limits.timeMs === undefined ? "none" : (limits.timeMs / 1000).toFixed(3);
+  const inferences = limits.inferences === undefined ? "none" : String(limits.inferences);
+  return `(kibi_engine_bounded_read((${goal}), ${seconds}, ${inferences}, ${OUTCOME_BINDING}))`;
+}
+function settleBoundedRead(result, limits) {
+  if (!result.success)
+    return result;
+  const { [OUTCOME_BINDING]: rawOutcome, ...bindings } = result.bindings;
+  const outcome = rawOutcome?.match(/^kibi_read_outcome\((\w+)\)$/)?.[1];
+  const hit = outcome === "time" && limits.timeMs !== undefined ? { kind: "time", limit: limits.timeMs } : outcome === "inferences" && limits.inferences !== undefined ? { kind: "inferences", limit: limits.inferences } : null;
+  if (hit === null)
+    return { ...result, bindings };
+  return {
+    success: false,
+    bindings: {},
+    error: queryLimitMessage(hit),
+    limitExceeded: hit
+  };
+}
+function queryLimitMessage(hit) {
+  const budget = hit.kind === "time" ? `time limit of ${hit.limit} ms (${ENGINE_READ_TIME_LIMIT_ENV})` : `inference limit of ${hit.limit} (${ENGINE_READ_INFERENCE_LIMIT_ENV})`;
+  return `${QUERY_LIMIT_EXCEEDED_CODE}: read stopped at its ${budget} before computing an answer. Narrow the query or raise the limit.`;
+}
+
 // ../cli/src/performance-trace.ts
 import { constants } from "node:fs";
 import {
@@ -921,6 +975,8 @@ class PrologProcess {
   maxOutputBytes;
   interactiveStarted = false;
   terminationReason = null;
+  outputWaiter = null;
+  outputWakeScheduled = false;
   constructor(options = {}) {
     this.explicitSwiplPath = options.swiplPath || undefined;
     this.swiplResolver = options.swiplResolver ?? (() => resolveSwipl());
@@ -1070,6 +1126,15 @@ writeln('${INTERACTIVE_QUERY_FRAME_END}').
 `);
       return new Promise((resolve, reject) => {
         let settled = false;
+        let pollTimer = null;
+        const settle = () => {
+          settled = true;
+          clearTimeout(timeoutId);
+          if (pollTimer !== null)
+            clearTimeout(pollTimer);
+          if (this.outputWaiter === wake)
+            this.outputWaiter = null;
+        };
         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"}, signal=${this.process?.signalCode ?? "null"}, goal=${goalLabel}). If several fresh Kibi commands hang or crawl the same way, the engine state is likely wedged: run 'kibi engine stop' (then 'kibi sync --rebuild' if needed) and retry.`;
@@ -1079,7 +1144,7 @@ writeln('${INTERACTIVE_QUERY_FRAME_END}').
 `).find((line) => line.includes("__KIBI_RUNTIME__"));
             console.error(`[prolog debug] runtime=${runtime ?? "unknown"} packages=${process.env.KIBI_PACKAGE_VERSIONS ?? KIBI_PACKAGE_VERSIONS}`);
           }
-          settled = true;
+          settle();
           this.terminationReason = `query timeout: ${goalLabel}`;
           this.terminate().finally(() => {
             reject(new Error(msg));
@@ -1090,8 +1155,7 @@ writeln('${INTERACTIVE_QUERY_FRAME_END}').
             return;
           }
           if (this.outputOverflowed) {
-            clearTimeout(timeoutId);
-            settled = true;
+            settle();
             this.terminationReason = `output overflow (ENOBUFS): ${goalLabel}`;
             this.terminate().finally(() => {
               resolve({
@@ -1103,8 +1167,7 @@ writeln('${INTERACTIVE_QUERY_FRAME_END}').
             return;
           }
           if (!this.isProcessUsable()) {
-            clearTimeout(timeoutId);
-            settled = true;
+            settle();
             this.terminationReason ??= `process exited during query: ${goalLabel}`;
             resolve({
               success: false,
@@ -1114,8 +1177,7 @@ writeln('${INTERACTIVE_QUERY_FRAME_END}').
             return;
           }
           if (this.errorBuffer.length > 0 && this.errorBuffer.includes("ERROR")) {
-            clearTimeout(timeoutId);
-            settled = true;
+            settle();
             if (debug) {
               console.error(`[prolog debug] query error: ${goalLabel} error=${this.errorBuffer.split(`
 `)[0]}`);
@@ -1131,8 +1193,7 @@ writeln('${INTERACTIVE_QUERY_FRAME_END}').
           }
           const frameEnd = this.outputBuffer.indexOf(INTERACTIVE_QUERY_FRAME_END);
           if (frameEnd >= 0) {
-            clearTimeout(timeoutId);
-            settled = true;
+            settle();
             const framedOutput = this.outputBuffer.slice(0, frameEnd).trimEnd();
             if (/(?:^|\n)(?:false|fail)\.\s*$/.test(framedOutput)) {
               resolve({
@@ -1160,8 +1221,23 @@ writeln('${INTERACTIVE_QUERY_FRAME_END}').
             resolve(result);
             return;
           }
-          setTimeout(checkResult, 50);
+          if (pollTimer === null) {
+            pollTimer = setTimeout(() => {
+              pollTimer = null;
+              checkResult();
+            }, 50);
+          }
+        };
+        let frameScanFrom = 0;
+        const wake = () => {
+          if (settled)
+            return;
+          const found = this.outputBuffer.indexOf(INTERACTIVE_QUERY_FRAME_END, frameScanFrom) >= 0;
+          frameScanFrom = Math.max(0, this.outputBuffer.length - INTERACTIVE_QUERY_FRAME_END.length);
+          if (found || this.outputOverflowed)
+            checkResult();
         };
+        this.outputWaiter = wake;
         checkResult();
       });
     };
@@ -1425,6 +1501,7 @@ writeln('${INTERACTIVE_QUERY_FRAME_END}').
     }
     this.outputBuffer += chunk.toString();
     this.outputBufferBytes += chunk.byteLength;
+    this.wakeOutputWaiter();
   }
   appendErrorChunk(chunk) {
     if (this.outputOverflowed)
@@ -1438,6 +1515,16 @@ writeln('${INTERACTIVE_QUERY_FRAME_END}').
     }
     this.errorBuffer += chunk.toString();
     this.errorBufferBytes += chunk.byteLength;
+    this.wakeOutputWaiter();
+  }
+  wakeOutputWaiter() {
+    if (this.outputWaiter === null || this.outputWakeScheduled)
+      return;
+    this.outputWakeScheduled = true;
+    setImmediate(() => {
+      this.outputWakeScheduled = false;
+      this.outputWaiter?.();
+    });
   }
   goalLabel(goal) {
     const match = goal.trim().match(/^([a-z][A-Za-z0-9_]*(?::[a-z][A-Za-z0-9_]*)?)/);
@@ -1888,6 +1975,12 @@ function canonicalFilesystemPath(candidate) {
 }
 
 // ../cli/src/engine.ts
+var READ_LIMITED_METHODS = new Set([
+  "query",
+  "command",
+  "entities",
+  "search"
+]);
 var ENGINE_PROTOCOL_VERSION = 1;
 var ENGINE_IDLE_TIMEOUT_MS = 10 * 60 * 1000;
 var ENGINE_PACKAGE_VERSIONS = process.env.KIBI_PACKAGE_VERSIONS ?? "unknown";
@@ -2506,6 +2599,18 @@ async function runEngineDaemon(requestedOptions) {
   let queue = Promise.resolve();
   let idleCompactionQueued = false;
   const queryCache = new Map;
+  let boundedReadHelperPid = null;
+  const runBoundedRead = async (goal, limits) => {
+    const pid = prolog.getPid();
+    if (boundedReadHelperPid !== pid) {
+      const defined = await prolog.query(BOUNDED_READ_HELPER_DEFINITION);
+      if (!defined.success) {
+        throw new Error(defined.error ?? "Failed to define the bounded-read helper");
+      }
+      boundedReadHelperPid = pid;
+    }
+    return settleBoundedRead(await prolog.query(boundedReadGoal(goal, limits)), limits);
+  };
   let freshnessCache = null;
   const clients = new Set;
   let shuttingDown = false;
@@ -2593,6 +2698,8 @@ async function runEngineDaemon(requestedOptions) {
       freshnessCache = null;
       attachedIdentity = readEngineAttachmentIdentity(branchPath);
     }
+    const readLimits = normalizeQueryLimits(request.limits);
+    const runRead = (goal) => readLimits === undefined ? prolog.query(goal) : runBoundedRead(goal, readLimits);
     switch (request.method) {
       case "entities": {
         const limit = request.limit ?? 100;
@@ -2604,8 +2711,8 @@ async function runEngineDaemon(requestedOptions) {
         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) {
+        const result = await runRead(`kb_query_entities(${type}, ${id}, ${tags}, ${source}, ${limit}, ${offset}, Rows, Count)`);
+        if (!result.success && result.limitExceeded === undefined) {
           throw new Error(result.error ?? "Indexed entity query failed");
         }
         return result;
@@ -2620,8 +2727,8 @@ async function runEngineDaemon(requestedOptions) {
           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) {
+        const result = await runRead(`kb_search_entities(${type}, '${quoteProlog(request.searchQuery)}', ${limit}, ${offset}, Rows, Count)`);
+        if (!result.success && result.limitExceeded === undefined) {
           throw new Error(result.error ?? "Indexed search candidate query failed");
         }
         return result;
@@ -2658,7 +2765,7 @@ async function runEngineDaemon(requestedOptions) {
             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)");
+            return runRead("checks:check_all_json(JsonString)");
           }
           case "relationship": {
             if (!command.type || !command.from || !command.to) {
@@ -2712,7 +2819,7 @@ async function runEngineDaemon(requestedOptions) {
             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)`);
+            return runRead(`kb_query_entities(${type}, ${id}, ${tags}, ${source}, ${command.limit}, ${command.offset}, Rows, Count)`);
           }
           case "search": {
             if (!command.query.trim())
@@ -2721,7 +2828,7 @@ async function runEngineDaemon(requestedOptions) {
               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)`);
+            return runRead(`kb_search_entities(${type}, '${quoteProlog(command.query)}', ${command.limit}, ${command.offset}, Rows, Count)`);
           }
           default:
             throw new Error("engine.command kind is unsupported");
@@ -2767,7 +2874,8 @@ async function runEngineDaemon(requestedOptions) {
             return cached;
           }
         }
-        const result = await prolog.query(request.goal);
+        const boundable = !mutatingEngineGoal(request.goal) && !/\b(?:use_module|consult|load_files|ensure_loaded)\s*\(/.test(request.goal);
+        const result = boundable ? await runRead(request.goal) : await prolog.query(request.goal);
         session.recordModuleLoad(request.goal, result);
         if (result.success && mutatingEngineGoal(request.goal)) {
           fsyncJournaledBranchStore(branchPath);

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export type { Clock, OperationContext, OperationPlugins, OperationRuntime, Runti
 export type { EngineCommandV1, EnginePort } from "./engine.js";
 export { executeOperation } from "kibi-cli/operations/runtime-types";
 export type { KibiResult, KibiResultStatus, OperationContent, OperationEffect, OperationName, OperationResult, OperationSpec, } from "kibi-cli/operations";
-export { VALID_ENTITY_TYPES, OPERATION_CATALOG, applyPlanSpec, planBootstrapSpec, checkSpec, prepareImpactReviewSpec, executePrepareImpactReview, compileIntentSpec, coverageSpec, deleteSpec, dedupeEntities, executeApplyPlan, executePlanBootstrap, executeCompileIntent, executeCoverage, executeIngestProof, executeFindGaps, executeGraph, executeIntentSearch, executeQuery, executeSearch, executeSemanticAdvisor, executeStatus, buildEntityGoal, findGapsSpec, getSpec, graphSpec, ingestProofSpec, loadEntities, listSpecs, modelRequirementSpec, nodeFilesystem, nodeGit, nodeNetwork, paginateResults, presentBootstrap, querySpec, searchSpec, selectBootstrapCandidates, semanticAdvisorSpec, sparqlRemoteSpec, statusSpec, suggestPredicatesSpec, upsertSpec, validateEntityType, validateUpsertSpec, withContractDefaults, } from "kibi-cli/operations";
+export { VALID_ENTITY_TYPES, OPERATION_CATALOG, MODEL_ROUTES, SKILL_ROUTES, dispatchComposite, modelSpec, skillsSpec, applyPlanSpec, planBootstrapSpec, checkSpec, prepareImpactReviewSpec, executePrepareImpactReview, compileIntentSpec, coverageSpec, deleteSpec, dedupeEntities, executeApplyPlan, executePlanBootstrap, executeCompileIntent, executeCoverage, executeIngestProof, executeFindGaps, executeGraph, executeIntentSearch, executeQuery, executeSearch, executeSemanticAdvisor, executeStatus, buildEntityGoal, findGapsSpec, getSpec, graphSpec, ingestProofSpec, loadEntities, listSpecs, modelRequirementSpec, nodeFilesystem, nodeGit, nodeNetwork, paginateResults, presentBootstrap, querySpec, searchSpec, selectBootstrapCandidates, semanticAdvisorSpec, sparqlRemoteSpec, statusSpec, suggestPredicatesSpec, upsertSpec, validateEntityType, validateUpsertSpec, withContractDefaults, } from "kibi-cli/operations";
 export type { ImpactReviewPreparationScope, PrepareImpactReviewInput, } from "kibi-cli/operations";
 export type { BootstrapAction, BootstrapPlanV1 } from "kibi-cli/operations";
 export { skillsListSpec, skillsLoadSpec, skillsReadSpec, } from "./skill-operations.js";
@@ -34,7 +34,8 @@ export { branchStorePath, branchStoreManifestPath, branchStoresRoot, branchStore
 export { KIBI_PROTOCOL_VERSION, appendPayloadCountField, normalizeResultPayload, operationData, resultVersion, toKibiResult, } from "kibi-cli/operations/result-envelope";
 export type { NormalizedResultPayload } from "kibi-cli/operations/result-envelope";
 export * from "kibi-cli/public/branch-resolver";
-export { EngineClient, engineSocketPath } from "kibi-cli/engine";
+export { EngineClient, EngineQueryLimitError, QUERY_LIMIT_EXCEEDED_CODE, engineSocketPath, queryLimitExceededOf, } from "kibi-cli/engine";
+export type { EngineLimitExceeded, EngineQueryLimits } from "kibi-cli/engine";
 export { PrologProcess, resolveKbPlPath } from "kibi-cli/prolog";
 export { escapeAtomContent, splitTopLevel, } from "kibi-cli/prolog/codec";
 export { createCliRuntime } from "kibi-cli/runtime/cli-runtime";