kibi-cli 2.4.0 → 2.5.1

package/dist/diagnostics.js

@@ -6,7 +6,7 @@
  * and respond to issues programmatically.
  */
 export function branchErrorToDiagnostic(
-// implements REQ-008
+// implements REQ-branch-store-recovery-v4
 _code, message, branch) {
     return {
         category: "BRANCH_RESOLUTION_FAILURE",

package/dist/engine-limits.d.ts

@@ -0,0 +1,74 @@
+/** Envelope error code for a read stopped at its limit. */
+export declare const QUERY_LIMIT_EXCEEDED_CODE = "QUERY_LIMIT_EXCEEDED";
+/** Environment opt-in for read limits on every engine client. */
+export declare const ENGINE_READ_TIME_LIMIT_ENV = "KIBI_ENGINE_READ_TIME_LIMIT_MS";
+export declare const ENGINE_READ_INFERENCE_LIMIT_ENV = "KIBI_ENGINE_READ_INFERENCE_LIMIT";
+/**
+ * Upper bound for a requested time limit. The daemon's SWI process kills a
+ * query at 120 s and recycles the session; a bounded read must end first.
+ */
+export declare const ENGINE_READ_TIME_LIMIT_CAP_MS = 115000;
+export type EngineQueryLimits = Readonly<{
+    /** Wall-clock budget for the Prolog goal, in milliseconds. */
+    timeMs?: number;
+    /** Logical-inference budget for the Prolog goal. */
+    inferences?: number;
+}>;
+export type EngineLimitExceeded = Readonly<{
+    kind: "time" | "inferences";
+    limit: number;
+}>;
+/**
+ * Validate limits received over the engine socket. Out-of-range values are
+ * dropped (the read runs unbounded, as before); a time limit is capped below
+ * the hard per-query timeout.
+ */
+export declare function normalizeQueryLimits(value: unknown): EngineQueryLimits | undefined;
+/** Read limits configured through the environment, if any. */
+export declare function queryLimitsFromEnv(env?: NodeJS.ProcessEnv): EngineQueryLimits | undefined;
+/**
+ * Clauses the engine session defines at boot (and after a recycle) so a
+ * bounded read needs one call and one answer binding. Helper variables stay
+ * clause-local, so the toplevel prints only the goal's own bindings plus the
+ * outcome, whose compound value cannot be grouped with a goal's binding.
+ *
+ * A goal that swallows the limit exception itself (a catch-all inside a
+ * predicate) could otherwise return a partial answer or fail; measuring the
+ * elapsed time and inferences around the goal reports the limit regardless.
+ */
+export declare const BOUNDED_READ_HELPER_DEFINITION: string;
+/**
+ * Wrap a read-only goal in its limits. The goal's own variables keep their
+ * names, so its answer bindings are unchanged; the outcome arrives in the
+ * KibiReadOutcome binding that settleBoundedRead strips. The surrounding
+ * parentheses keep PrologProcess from caching a bounded answer.
+ */
+export declare function boundedReadGoal(goal: string, limits: EngineQueryLimits): string;
+type BoundedResult = {
+    readonly success: boolean;
+    readonly bindings: Readonly<Record<string, string>>;
+    readonly error?: string;
+};
+/**
+ * Turn a bounded read's answer back into the unbounded answer shape, or into
+ * an explicit limitExceeded failure when a limit stopped the goal.
+ */
+export declare function settleBoundedRead<T extends BoundedResult>(result: T, limits: EngineQueryLimits): T | (BoundedResult & {
+    readonly limitExceeded: EngineLimitExceeded;
+});
+/** A read the engine stopped at its limit; never an empty answer. */
+export declare class EngineQueryLimitError extends Error {
+    readonly limitExceeded: EngineLimitExceeded;
+    readonly code = "QUERY_LIMIT_EXCEEDED";
+    readonly retryable = false;
+    constructor(limitExceeded: EngineLimitExceeded);
+}
+/**
+ * The limit that stopped a read, from the typed error or from the message an
+ * executor rewrapped it into; null for every other error.
+ */
+export declare function queryLimitExceededOf(error: unknown): EngineLimitExceeded | null;
+/** Reject an engine answer that reports a limit hit. */
+export declare function assertWithinQueryLimits(value: unknown): void;
+export {};
+//# sourceMappingURL=engine-limits.d.ts.map

package/dist/engine-limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-limits.d.ts","sourceRoot":"","sources":["../src/engine-limits.ts"],"names":[],"mappings":"AA6BA,2DAA2D;AAE3D,eAAO,MAAM,yBAAyB,yBAAyB,CAAC;AAEhE,iEAAiE;AAEjE,eAAO,MAAM,0BAA0B,mCAAmC,CAAC;AAE3E,eAAO,MAAM,+BAA+B,qCACR,CAAC;AAErC;;;GAGG;AAEH,eAAO,MAAM,6BAA6B,SAAU,CAAC;AAIrD,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC,CAAC;AAGH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IACzC,IAAI,EAAE,MAAM,GAAG,YAAY,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;CACf,CAAC,CAAC;AAWH;;;;GAIG;AAEH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,GACb,iBAAiB,GAAG,SAAS,CAiB/B;AAED,8DAA8D;AAE9D,wBAAgB,kBAAkB,CAChC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,iBAAiB,GAAG,SAAS,CAW/B;AAED;;;;;;;;;GASG;AAEH,eAAO,MAAM,8BAA8B,QAI5B,CAAC;AAKhB;;;;;GAKG;AAEH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,iBAAiB,GACxB,MAAM,CAMR;AAED,KAAK,aAAa,GAAG;IACnB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF;;;GAGG;AAEH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,aAAa,EACvD,MAAM,EAAE,CAAC,EACT,MAAM,EAAE,iBAAiB,GACxB,CAAC,GAAG,CAAC,aAAa,GAAG;IAAE,QAAQ,CAAC,aAAa,EAAE,mBAAmB,CAAA;CAAE,CAAC,CAiBvE;AAiBD,qEAAqE;AAErE,qBAAa,qBAAsB,SAAQ,KAAK;IAIlC,QAAQ,CAAC,aAAa,EAAE,mBAAmB;IAHvD,QAAQ,CAAC,IAAI,0BAA6B;IAC1C,QAAQ,CAAC,SAAS,SAAS;gBAEN,aAAa,EAAE,mBAAmB;CAIxD;AAED;;;GAGG;AAEH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,GACb,mBAAmB,GAAG,IAAI,CAkB5B;AAED,wDAAwD;AAExD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAQ5D"}

package/dist/engine-limits.js

@@ -0,0 +1,201 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+/*
+ * Per-request bounds for read-only engine work.
+ *
+ * The engine serves every client from one serialized SWI-Prolog queue, and a
+ * goal already running inside SWI cannot be cancelled from outside. A read
+ * that carries limits runs under call_with_time_limit/2 and
+ * call_with_inference_limit/3, so a runaway read ends inside Prolog and frees
+ * the queue. Hitting a limit is reported explicitly (limitExceeded) and is
+ * never presented as an empty or partial answer.
+ */
+/** Envelope error code for a read stopped at its limit. */
+// implements REQ-core-engine-read-limits
+export const QUERY_LIMIT_EXCEEDED_CODE = "QUERY_LIMIT_EXCEEDED";
+/** Environment opt-in for read limits on every engine client. */
+// implements REQ-core-engine-read-limits
+export const ENGINE_READ_TIME_LIMIT_ENV = "KIBI_ENGINE_READ_TIME_LIMIT_MS";
+// implements REQ-core-engine-read-limits
+export const ENGINE_READ_INFERENCE_LIMIT_ENV = "KIBI_ENGINE_READ_INFERENCE_LIMIT";
+/**
+ * Upper bound for a requested time limit. The daemon's SWI process kills a
+ * query at 120 s and recycles the session; a bounded read must end first.
+ */
+// implements REQ-core-engine-read-limits
+export const ENGINE_READ_TIME_LIMIT_CAP_MS = 115_000;
+const ENGINE_READ_INFERENCE_LIMIT_CAP = 1_000_000_000_000;
+function boundedInteger(value, max) {
+    return typeof value === "number" &&
+        Number.isSafeInteger(value) &&
+        value > 0 &&
+        value <= max
+        ? value
+        : undefined;
+}
+/**
+ * Validate limits received over the engine socket. Out-of-range values are
+ * dropped (the read runs unbounded, as before); a time limit is capped below
+ * the hard per-query timeout.
+ */
+// implements REQ-core-engine-read-limits
+export function normalizeQueryLimits(value) {
+    if (value === null || typeof value !== "object")
+        return undefined;
+    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 undefined;
+    return {
+        ...(timeMs !== undefined ? { timeMs } : {}),
+        ...(inferences !== undefined ? { inferences } : {}),
+    };
+}
+/** Read limits configured through the environment, if any. */
+// implements REQ-core-engine-read-limits
+export function queryLimitsFromEnv(env = process.env) {
+    const parse = (name) => {
+        const raw = env[name]?.trim();
+        if (!raw)
+            return undefined;
+        const parsed = Number(raw);
+        return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined;
+    };
+    return normalizeQueryLimits({
+        timeMs: parse(ENGINE_READ_TIME_LIMIT_ENV),
+        inferences: parse(ENGINE_READ_INFERENCE_LIMIT_ENV),
+    });
+}
+/**
+ * Clauses the engine session defines at boot (and after a recycle) so a
+ * bounded read needs one call and one answer binding. Helper variables stay
+ * clause-local, so the toplevel prints only the goal's own bindings plus the
+ * outcome, whose compound value cannot be grouped with a goal's binding.
+ *
+ * A goal that swallows the limit exception itself (a catch-all inside a
+ * predicate) could otherwise return a partial answer or fail; measuring the
+ * elapsed time and inferences around the goal reports the limit regardless.
+ */
+// implements REQ-core-engine-read-limits
+export const 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(", ")})`;
+/** Answer binding that carries a bounded read's outcome. */
+const OUTCOME_BINDING = "KibiReadOutcome";
+/**
+ * Wrap a read-only goal in its limits. The goal's own variables keep their
+ * names, so its answer bindings are unchanged; the outcome arrives in the
+ * KibiReadOutcome binding that settleBoundedRead strips. The surrounding
+ * parentheses keep PrologProcess from caching a bounded answer.
+ */
+// implements REQ-core-engine-read-limits
+export 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}))`;
+}
+/**
+ * Turn a bounded read's answer back into the unbounded answer shape, or into
+ * an explicit limitExceeded failure when a limit stopped the goal.
+ */
+// implements REQ-core-engine-read-limits
+export 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,
+    };
+}
+/**
+ * The message names the limit in a fixed form, so the signal survives an
+ * executor that rewraps the error with its own prefix.
+ */
+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.`;
+}
+const QUERY_LIMIT_MESSAGE = /QUERY_LIMIT_EXCEEDED: read stopped at its (time|inference) limit of (\d+)/;
+/** A read the engine stopped at its limit; never an empty answer. */
+// implements REQ-core-engine-read-limits
+export class EngineQueryLimitError extends Error {
+    limitExceeded;
+    code = QUERY_LIMIT_EXCEEDED_CODE;
+    retryable = false;
+    constructor(limitExceeded) {
+        super(queryLimitMessage(limitExceeded));
+        this.limitExceeded = limitExceeded;
+        this.name = "EngineQueryLimitError";
+    }
+}
+/**
+ * The limit that stopped a read, from the typed error or from the message an
+ * executor rewrapped it into; null for every other error.
+ */
+// implements REQ-core-engine-read-limits
+export function queryLimitExceededOf(error) {
+    if (!(error instanceof Error))
+        return null;
+    const typed = error.limitExceeded;
+    if (error.code === QUERY_LIMIT_EXCEEDED_CODE &&
+        typed !== null &&
+        typeof typed === "object") {
+        const { kind, limit } = typed;
+        if ((kind === "time" || kind === "inferences") && typeof limit === "number")
+            return { kind, limit };
+    }
+    const match = error.message.match(QUERY_LIMIT_MESSAGE);
+    if (match?.[1] === undefined || match[2] === undefined)
+        return null;
+    return {
+        kind: match[1] === "time" ? "time" : "inferences",
+        limit: Number(match[2]),
+    };
+}
+/** Reject an engine answer that reports a limit hit. */
+// implements REQ-core-engine-read-limits
+export function assertWithinQueryLimits(value) {
+    if (value === null || typeof value !== "object")
+        return;
+    const hit = value.limitExceeded;
+    if (hit === null || typeof hit !== "object")
+        return;
+    const { kind, limit } = hit;
+    if ((kind !== "time" && kind !== "inferences") || typeof limit !== "number")
+        return;
+    throw new EngineQueryLimitError({ kind, limit });
+}

package/dist/engine.d.ts

@@ -1,8 +1,11 @@
+import { type EngineQueryLimits } from "./engine-limits.js";
 import type { EngineAttachmentIdentity, EngineCommandV1 } from "./engine-types.js";
 import { PrologProcess } from "./prolog.js";
 import type { PrologQueryResult } from "./public/operations/runtime-types.js";
 import type { PrologEntityQueryInput, PrologEntityQueryResult, PrologSearchQueryInput, PrologSearchQueryResult } from "./public/operations/runtime-types.js";
 export type { EngineAttachmentIdentity, EngineCommandV1, EngineRequest, } from "./engine-types.js";
+export { EngineQueryLimitError, QUERY_LIMIT_EXCEEDED_CODE, queryLimitExceededOf, } from "./engine-limits.js";
+export type { EngineLimitExceeded, EngineQueryLimits, } from "./engine-limits.js";
 export declare const ENGINE_PROTOCOL_VERSION = 1;
 export declare const ENGINE_IDLE_TIMEOUT_MS: number;
 export declare const ENGINE_PACKAGE_VERSIONS: string;
@@ -46,6 +49,12 @@ export type EngineClientOptions = {
     readonly timeout?: number;
     /** Internal stop-before-publish client may attach while it owns the lease. */
     readonly allowPublicationLock?: boolean;
+    /**
+     * Bounds for this client's read-only requests. Defaults to
+     * KIBI_ENGINE_READ_TIME_LIMIT_MS / KIBI_ENGINE_READ_INFERENCE_LIMIT; null
+     * sends none (sync and other maintenance clients).
+     */
+    readonly readLimits?: EngineQueryLimits | null;
 };
 /** PrologPort-compatible client used by CLI and MCP operation runtimes. */
 export declare class EngineClient {
@@ -53,6 +62,7 @@ export declare class EngineClient {
     private readonly branch;
     private readonly timeout;
     private readonly allowPublicationLock;
+    private readonly readLimits;
     private socket;
     private daemon;
     private inputBuffer;

package/dist/engine.d.ts.map

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

package/dist/engine.js

@@ -13,6 +13,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { performance } from "node:perf_hooks";
 import { fileURLToPath } from "node:url";
+import { BOUNDED_READ_HELPER_DEFINITION, assertWithinQueryLimits, boundedReadGoal, normalizeQueryLimits, queryLimitsFromEnv, settleBoundedRead, } from "./engine-limits.js";
 import { writePerformanceTraceEvent } from "./performance-trace.js";
 import { PrologProcess, resolveKbPlPath } from "./prolog.js";
 import { parseEntityFromList, parseListOfLists } from "./prolog/codec.js";
@@ -22,6 +23,14 @@ import { queryEntityChunks } from "./public/operations/discovery-entities.js";
 import { isValidBranchName } from "./utils/branch-resolver.js";
 import { branchStorePath, ensureBranchStoreManifest, } from "./utils/branch-store-locator.js";
 import { canonicalFilesystemPath } from "./utils/canonical-path.js";
+export { EngineQueryLimitError, QUERY_LIMIT_EXCEEDED_CODE, queryLimitExceededOf, } from "./engine-limits.js";
+/** Request methods whose read-only work may carry per-request limits. */
+const READ_LIMITED_METHODS = new Set([
+    "query",
+    "command",
+    "entities",
+    "search",
+]);
 export const ENGINE_PROTOCOL_VERSION = 1;
 export const ENGINE_IDLE_TIMEOUT_MS = 10 * 60 * 1000;
 export const ENGINE_PACKAGE_VERSIONS = process.env.KIBI_PACKAGE_VERSIONS ?? "unknown";
@@ -727,6 +736,7 @@ export class EngineClient {
     branch;
     timeout;
     allowPublicationLock;
+    readLimits;
     socket = null;
     daemon = null;
     inputBuffer = Buffer.alloc(0);
@@ -743,6 +753,10 @@ export class EngineClient {
         this.branch = options.branch;
         this.timeout = options.timeout ?? 120_000;
         this.allowPublicationLock = options.allowPublicationLock ?? false;
+        this.readLimits =
+            options.readLimits === undefined
+                ? queryLimitsFromEnv()
+                : (options.readLimits ?? undefined);
     }
     async start(allowSpawn = true) {
         const wasConnected = this.socket !== null && !this.socket.destroyed;
@@ -948,7 +962,11 @@ export class EngineClient {
             if (socket === null || socket.destroyed)
                 throw new Error("Kibi engine is not connected");
             const id = ++this.requestId;
-            return await new Promise((resolve, reject) => {
+            const limits = this.readLimits !== undefined &&
+                READ_LIMITED_METHODS.has(request.method)
+                ? { limits: this.readLimits }
+                : {};
+            const value = await new Promise((resolve, reject) => {
                 this.pending.set(id, {
                     resolve: resolve,
                     reject,
@@ -957,6 +975,7 @@ export class EngineClient {
                 try {
                     socket.write(frame({
                         ...request,
+                        ...limits,
                         id,
                         protocolVersion: ENGINE_PROTOCOL_VERSION,
                         packageVersions: ENGINE_PACKAGE_VERSIONS,
@@ -988,6 +1007,10 @@ export class EngineClient {
                         signal.addEventListener("abort", abort, { once: true });
                 }
             });
+            // A bounded read stopped at its limit has no answer; never let it pass
+            // as an empty or failed lookup.
+            assertWithinQueryLimits(value);
+            return value;
         }
         finally {
             release();
@@ -1621,6 +1644,20 @@ export async function runEngineDaemon(requestedOptions) {
     let queue = Promise.resolve();
     let idleCompactionQueued = false;
     const queryCache = new Map();
+    // The bounded-read helper lives in the Prolog session; a recycled session
+    // (new pid) defines it again before its first bounded read.
+    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;
@@ -1727,6 +1764,11 @@ export async function runEngineDaemon(requestedOptions) {
             freshnessCache = null;
             attachedIdentity = readEngineAttachmentIdentity(branchPath);
         }
+        // Read-only work runs inside the request's limits, when it has any.
+        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;
@@ -1750,8 +1792,8 @@ export async function runEngineDaemon(requestedOptions) {
                 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;
@@ -1773,8 +1815,8 @@ export async function runEngineDaemon(requestedOptions) {
                 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;
@@ -1814,7 +1856,7 @@ export async function runEngineDaemon(requestedOptions) {
                         }
                         // Rule selection is intentionally resolved inside the engine. A
                         // caller never supplies a Prolog goal over the command boundary.
-                        return prolog.query("checks:check_all_json(JsonString)");
+                        return runRead("checks:check_all_json(JsonString)");
                     }
                     case "relationship": {
                         if (!command.type || !command.from || !command.to) {
@@ -1888,7 +1930,7 @@ export async function runEngineDaemon(requestedOptions) {
                         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())
@@ -1903,7 +1945,7 @@ export async function runEngineDaemon(requestedOptions) {
                         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");
@@ -1950,7 +1992,13 @@ export async function runEngineDaemon(requestedOptions) {
                         return cached;
                     }
                 }
-                const result = await prolog.query(request.goal);
+                // Writes and module loads always run to completion; a limit may
+                // only stop a read.
+                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/extractors/manifest.d.ts

@@ -1,3 +1,4 @@
+import { type EntityOrigin } from "../public/entity-origin.js";
 export interface ExtractedEntity {
     id: string;
     type: string;
@@ -12,6 +13,7 @@ export interface ExtractedEntity {
     severity?: string;
     text_ref?: string;
     granularity_reason?: string;
+    origin?: EntityOrigin;
 }
 export interface ExtractedRelationship {
     type: string;
@@ -71,5 +73,11 @@ export interface ReceiptCodeScopeEntry {
     readonly symbolId: string;
     readonly sourceHash: string;
 }
+/**
+ * Scope hash of a symbol whose recorded source file lies outside the
+ * repository. Only repository content can be compared between a CI checkout
+ * and a developer machine, so such a file is never read.
+ */
+export declare const OUTSIDE_WORKSPACE_SCOPE_HASH = "outside-workspace";
 export declare function resolveBoundSymbolScope(manifestPath: string, symbolIds: readonly string[]): ReceiptCodeScopeEntry[];
 //# sourceMappingURL=manifest.d.ts.map

package/dist/extractors/manifest.d.ts.map

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

package/dist/extractors/manifest.js

@@ -19,7 +19,9 @@ import { createHash } from "node:crypto";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import * as path from "node:path";
 import { load as parseYAML } from "js-yaml";
+import { normalizeEntityOrigin, } from "../public/entity-origin.js";
 import { DEFAULT_COORDINATES_PATH } from "../utils/manifest-paths.js";
+import { normalizeRepoRelativePath } from "../utils/repo-relative-path.js";
 import { mergeCoordinatesWithManifest, parseCoordinateArtifact, } from "./symbol-coordinates.js";
 const VALID_RELATIONSHIP_TYPES = new Set([
     "depends_on",
@@ -38,6 +40,8 @@ const VALID_RELATIONSHIP_TYPES = new Set([
     "consumes",
     "supersedes",
     "restates",
+    "assumes",
+    "exempts",
     "relates_to",
 ]);
 const VALID_RELATIONSHIP_DIRECTIONS = [
@@ -62,6 +66,8 @@ const VALID_RELATIONSHIP_DIRECTIONS = [
     { type: "supersedes", from: "adr", to: "adr" },
     { type: "supersedes", from: "req", to: "req" },
     { type: "restates", from: "req", to: "req" },
+    { type: "assumes", from: "scenario", to: "fact" },
+    { type: "exempts", from: "req", to: "req" },
 ];
 const RELATIONSHIP_TYPE_DISPLAY_LIST = Array.from(VALID_RELATIONSHIP_TYPES)
     .sort()
@@ -183,6 +189,15 @@ export function extractManifestSymbolRecords(manifestSymbols, filePath) {
             throw new ManifestError("Missing required field: title", filePath);
         }
         const id = symbol.id || generateId(filePath, symbol.title);
+        // implements REQ-004
+        let origin;
+        if (symbol.origin !== undefined) {
+            const normalized = normalizeEntityOrigin(symbol.origin);
+            if ("error" in normalized) {
+                throw new ManifestError(`Invalid origin for symbol ${id}: ${normalized.error}`, filePath);
+            }
+            origin = normalized.origin;
+        }
         const entity = {
             id,
             type: "symbol",
@@ -199,6 +214,7 @@ export function extractManifestSymbolRecords(manifestSymbols, filePath) {
             ...(symbol.granularity_reason !== undefined
                 ? { granularity_reason: symbol.granularity_reason }
                 : {}),
+            ...(origin !== undefined ? { origin } : {}),
             ...(typeof symbol.symbol_kind === "string"
                 ? { symbol_kind: symbol.symbol_kind }
                 : {}),
@@ -386,23 +402,36 @@ function scopeFileHash(absolutePath) {
     scopeFileHashCache.set(absolutePath, { stamp, hash });
     return hash;
 }
+/**
+ * Scope hash of a symbol whose recorded source file lies outside the
+ * repository. Only repository content can be compared between a CI checkout
+ * and a developer machine, so such a file is never read.
+ */
+// implements REQ-kibi-fresh-verification-receipts-v2
+export const OUTSIDE_WORKSPACE_SCOPE_HASH = "outside-workspace";
+// implements REQ-kibi-fresh-verification-receipts-v2
 export function resolveBoundSymbolScope(manifestPath, symbolIds) {
     const wanted = [...new Set(symbolIds)];
     if (wanted.length === 0)
         return [];
     const sourceFiles = scopeSourceFiles(manifestPath);
     // The manifest lives at <workspace>/.kb/symbols.yaml; source files are
-    // workspace-relative.
+    // workspace-relative. Every recorded path is normalized to its
+    // repo-relative form first, so `./a.ts`, `a\b.ts` and an absolute path
+    // inside this checkout hash the same file wherever the checkout lives.
     const workspaceRoot = path.dirname(path.dirname(path.resolve(manifestPath)));
     const scope = [];
     for (const symbolId of wanted) {
         const sourceFile = sourceFiles.get(symbolId);
         if (sourceFile === undefined)
             continue;
-        const absolute = path.isAbsolute(sourceFile)
-            ? sourceFile
-            : path.resolve(workspaceRoot, sourceFile);
-        scope.push({ symbolId, sourceHash: scopeFileHash(absolute) });
+        const relative = normalizeRepoRelativePath(workspaceRoot, sourceFile);
+        scope.push({
+            symbolId,
+            sourceHash: relative === null
+                ? OUTSIDE_WORKSPACE_SCOPE_HASH
+                : scopeFileHash(path.join(workspaceRoot, relative)),
+        });
     }
     scope.sort((left, right) => left.symbolId.localeCompare(right.symbolId));
     return scope;