kibi-cli 2.1.0 → 2.3.0

package/dist/prolog.js

@@ -19,11 +19,14 @@ import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
+import { performance } from "node:perf_hooks";
 import { fileURLToPath } from "node:url";
 import { getKbPlPathOverride, isPrologDebugEnabled } from "./env.js";
+import { writePerformanceTraceEvent } from "./performance-trace.js";
 import { extractPrologErrorRecord, } from "./prolog/error-terms.js";
+import { resolveSwipl, swiplChildEnv, } from "./prolog/swipl-resolver.js";
 const importMetaDir = path.dirname(fileURLToPath(import.meta.url));
-const PROLOG_OUTPUT_MAX_BUFFER_BYTES = 8 * 1024 * 1024;
+const DEFAULT_PROLOG_OUTPUT_MAX_BUFFER_BYTES = 8 * 1024 * 1024;
 const PROLOG_OUTPUT_OVERFLOW_ERROR = "Query exceeded bounded Prolog output capacity (ENOBUFS); narrow the operation or reduce stored entity size";
 const INTERACTIVE_QUERY_FRAME_END = "__KIBI_QUERY_FRAME_END__";
 const require = createRequire(import.meta.url);
@@ -79,6 +82,22 @@ export function resolveKbPlPath() {
     throw new Error("Unable to resolve kb.pl. Expected kibi-core to be installed (node_modules) " +
         "or to be running inside the monorepo checkout.");
 }
+/**
+ * Raised when a query reaches an interactive process that was started and
+ * later terminated (output overflow, timeout, crash, or explicit terminate).
+ * Such a port must be restarted by its owner (the engine daemon recycles it);
+ * it never degrades into isolated one-shot SWI processes, which would lose
+ * the attached KB and every module loaded into the interactive session.
+ */
+export class PrologProcessTerminatedError extends Error {
+    code = "prolog_process_terminated";
+    reason;
+    constructor(reason) {
+        super(`Kibi Prolog process is no longer running (${reason}); the interactive session and its attached KB were lost. The owning engine must restart it before serving more queries — run 'kibi engine stop' and retry if this persists.`);
+        this.name = "PrologProcessTerminatedError";
+        this.reason = reason;
+    }
+}
 // implements REQ-core-prolog-process-management
 export function registerProcessExitOnce(current, handler, on = (event, listener) => process.on(event, listener)) {
     if (current)
@@ -94,7 +113,8 @@ export function bindProcessExitHandler(current, terminate, on = (event, listener
 }
 export class PrologProcess {
     process = null;
-    swiplPath;
+    explicitSwiplPath;
+    swiplResolver;
     timeout;
     outputBuffer = "";
     outputBufferBytes = 0;
@@ -108,9 +128,24 @@ export class PrologProcess {
     useOneShotMode;
     attachedKbPath = null;
     onProcessExit = null;
+    maxOutputBytes;
+    /**
+     * Set once start() spawned an interactive process. From then on the
+     * isolated one-shot fallback is unreachable: a lost interactive process
+     * must fail loudly instead of silently changing execution semantics.
+     */
+    interactiveStarted = false;
+    terminationReason = null;
     constructor(options = {}) {
-        this.swiplPath = options.swiplPath || "swipl";
+        this.explicitSwiplPath = options.swiplPath || undefined;
+        this.swiplResolver = options.swiplResolver ?? (() => resolveSwipl());
         this.timeout = options.timeout || 30000;
+        this.maxOutputBytes =
+            options.maxOutputBytes !== undefined &&
+                Number.isInteger(options.maxOutputBytes) &&
+                options.maxOutputBytes > 0
+                ? options.maxOutputBytes
+                : DEFAULT_PROLOG_OUTPUT_MAX_BUFFER_BYTES;
         this.useOneShotMode =
             options.oneShot ??
                 (process.env.NODE_ENV === "test" &&
@@ -120,12 +155,45 @@ export class PrologProcess {
     attachProcessExitHandler(on = (event, listener) => process.on(event, listener)) {
         this.onProcessExit = bindProcessExitHandler(this.onProcessExit, () => this.terminate(), on);
     }
+    /**
+     * True when every query runs in its own isolated SWI process, so callers
+     * must not rely on state (loaded modules) carried between queries.
+     */
+    get oneShotMode() {
+        return this.useOneShotMode || !this.interactiveStarted;
+    }
+    /**
+     * True once a started interactive process has been lost. The owner must
+     * restart it (and re-establish its session state) before querying again.
+     */
+    needsRestart() {
+        return this.interactiveStarted && !this.isProcessUsable();
+    }
+    /**
+     * The executable and SWI home to launch. An explicit `swiplPath` is used
+     * verbatim; otherwise the per-process resolver decides, so a missing or
+     * damaged runtime fails with its complete remediation text.
+     */
+    launchTarget() {
+        const explicit = this.explicitSwiplPath;
+        if (explicit !== undefined)
+            return { bin: explicit, env: {} };
+        const resolved = this.swiplResolver();
+        return { bin: resolved.bin, env: swiplChildEnv(resolved) };
+    }
     async start() {
-        if (!existsSync(this.swiplPath) && this.swiplPath !== "swipl") {
-            throw new Error(`SWI-Prolog not found at ${this.swiplPath}. Please install SWI-Prolog or check your PATH.`);
+        const explicit = this.explicitSwiplPath;
+        if (explicit !== undefined &&
+            !existsSync(explicit) &&
+            explicit !== "swipl") {
+            throw new Error(`SWI-Prolog not found at ${explicit}. Please install SWI-Prolog or check your PATH.`);
         }
+        const launch = this.launchTarget();
         const kbPath = resolveKbPlPath();
-        this.process = spawn(this.swiplPath, [
+        this.interactiveStarted = true;
+        this.terminationReason = null;
+        this.invalidateCache();
+        this.process = spawn(launch.bin, [
             "-g",
             `use_module('${kbPath}'), use_module(library(semweb/rdf_db)), set_prolog_flag(answer_write_options, [max_depth(0), quoted(true)])`,
             "--quiet",
@@ -133,6 +201,7 @@ export class PrologProcess {
             detached: process.platform !== "win32",
             env: {
                 ...process.env,
+                ...launch.env,
                 KIBI_RUNTIME_NAME: process.versions.bun !== undefined ? "bun" : "node",
                 KIBI_RUNTIME_VERSION: process.versions.bun ?? process.versions.node ?? "unknown",
                 KIBI_PACKAGE_VERSIONS: process.env.KIBI_PACKAGE_VERSIONS ?? KIBI_PACKAGE_VERSIONS,
@@ -148,6 +217,16 @@ export class PrologProcess {
         this.process.stderr.on("data", (chunk) => {
             this.appendErrorChunk(chunk);
         });
+        // A write racing the child's death (native crash, external kill) fails
+        // asynchronously with EPIPE. Unhandled, that error event crashes the
+        // whole host (the engine daemon); record the loss instead so the owner
+        // sees needsRestart() and the in-flight query reports the termination.
+        const child = this.process;
+        child.stdin?.on("error", (error) => {
+            if (this.process === child) {
+                this.terminationReason ??= `stdin ${error.code ?? "error"}`;
+            }
+        });
         this.process.stdin.write("true.\n");
         this.attachProcessExitHandler();
         await this.waitForReady();
@@ -186,12 +265,23 @@ export class PrologProcess {
     }
     // implements REQ-core-prolog-process-management
     async query(goal) {
+        // A lost interactive session must fail before any cached answer is served.
+        if (!this.useOneShotMode && this.needsRestart()) {
+            throw this.lostProcessError();
+        }
         const isSingleGoal = typeof goal === "string";
         const goalKey = isSingleGoal ? goal : null;
         const cacheable = goalKey !== null && this.isCacheableGoal(goalKey);
         if (cacheable) {
+            const cacheLookupStartedAt = process.env.KIBI_PERF_TIMINGS === "1" ? performance.now() : null;
             const cachedResult = this.cache.get(goalKey);
             if (cachedResult) {
+                if (cacheLookupStartedAt !== null) {
+                    writePerformanceTraceEvent({
+                        kind: "prolog-process-cache-hit",
+                        durationMs: performance.now() - cacheLookupStartedAt,
+                    });
+                }
                 return cachedResult;
             }
         }
@@ -223,10 +313,10 @@ export class PrologProcess {
             // runtimes provide an EngineClient, while explicitly attached callers
             // call start() and stay interactive; this fallback never participates
             // in the engine-backed workflow.
-            if (this.process === null) {
+            if (this.process === null && !this.interactiveStarted) {
                 return this.execOneShot(goal, this.attachedKbPath);
             }
-            throw new Error("Prolog process not started");
+            throw this.lostProcessError();
         }
         const runInteractiveQuery = async () => {
             this.clearQueryBuffers();
@@ -264,6 +354,7 @@ export class PrologProcess {
                         console.error(`[prolog debug] runtime=${runtime ?? "unknown"} packages=${process.env.KIBI_PACKAGE_VERSIONS ?? KIBI_PACKAGE_VERSIONS}`);
                     }
                     settled = true;
+                    this.terminationReason = `query timeout: ${goalLabel}`;
                     void this.terminate().finally(() => {
                         reject(new Error(msg));
                     });
@@ -275,6 +366,7 @@ export class PrologProcess {
                     if (this.outputOverflowed) {
                         clearTimeout(timeoutId);
                         settled = true;
+                        this.terminationReason = `output overflow (ENOBUFS): ${goalLabel}`;
                         void this.terminate().finally(() => {
                             resolve({
                                 success: false,
@@ -287,6 +379,7 @@ export class PrologProcess {
                     if (!this.isProcessUsable()) {
                         clearTimeout(timeoutId);
                         settled = true;
+                        this.terminationReason ??= `process exited during query: ${goalLabel}`;
                         resolve({
                             success: false,
                             bindings: {},
@@ -356,13 +449,23 @@ export class PrologProcess {
             releaseQuery = resolve;
         });
         await previousQuery;
+        const tracingEnabled = process.env.KIBI_PERF_TIMINGS === "1";
+        let roundTripStartedAt = null;
         try {
             if (!this.isProcessUsable()) {
-                throw new Error("Prolog process not started");
+                throw this.lostProcessError();
             }
+            if (tracingEnabled)
+                roundTripStartedAt = performance.now();
             return await runInteractiveQuery();
         }
         finally {
+            if (roundTripStartedAt !== null) {
+                writePerformanceTraceEvent({
+                    kind: "prolog-round-trip",
+                    durationMs: performance.now() - roundTripStartedAt,
+                });
+            }
             releaseQuery();
         }
     }
@@ -474,10 +577,12 @@ export class PrologProcess {
         const packageVersions = process.env.KIBI_PACKAGE_VERSIONS ?? KIBI_PACKAGE_VERSIONS;
         let child;
         try {
-            child = spawn(this.swiplPath, ["-q", "-g", prologGoal, "-t", "halt"], {
+            const launch = this.launchTarget();
+            child = spawn(launch.bin, ["-q", "-g", prologGoal, "-t", "halt"], {
                 detached: process.platform !== "win32",
                 env: {
                     ...process.env,
+                    ...launch.env,
                     KIBI_GOAL: combinedGoal,
                     KIBI_RUNTIME_NAME: runtimeName,
                     KIBI_RUNTIME_VERSION: runtimeVersion,
@@ -508,7 +613,7 @@ export class PrologProcess {
             if (outputOverflowed)
                 return;
             const bytes = target === "stdout" ? outputBytes : errorBytes;
-            const remaining = PROLOG_OUTPUT_MAX_BUFFER_BYTES - bytes;
+            const remaining = this.maxOutputBytes - bytes;
             if (chunk.byteLength > remaining) {
                 const clipped = chunk.subarray(0, Math.max(0, remaining)).toString();
                 if (target === "stdout")
@@ -624,10 +729,10 @@ export class PrologProcess {
     appendOutputChunk(chunk) {
         if (this.outputOverflowed)
             return;
-        const remaining = PROLOG_OUTPUT_MAX_BUFFER_BYTES - this.outputBufferBytes;
+        const remaining = this.maxOutputBytes - this.outputBufferBytes;
         if (chunk.byteLength > remaining) {
             this.outputBuffer += chunk.subarray(0, remaining).toString();
-            this.outputBufferBytes = PROLOG_OUTPUT_MAX_BUFFER_BYTES;
+            this.outputBufferBytes = this.maxOutputBytes;
             this.outputOverflowed = true;
             return;
         }
@@ -637,10 +742,10 @@ export class PrologProcess {
     appendErrorChunk(chunk) {
         if (this.outputOverflowed)
             return;
-        const remaining = PROLOG_OUTPUT_MAX_BUFFER_BYTES - this.errorBufferBytes;
+        const remaining = this.maxOutputBytes - this.errorBufferBytes;
         if (chunk.byteLength > remaining) {
             this.errorBuffer += chunk.subarray(0, remaining).toString();
-            this.errorBufferBytes = PROLOG_OUTPUT_MAX_BUFFER_BYTES;
+            this.errorBufferBytes = this.maxOutputBytes;
             this.outputOverflowed = true;
             return;
         }
@@ -760,6 +865,20 @@ export class PrologProcess {
         // Diagnostic markers intentionally contain words such as `lock` and the
         // audit path. Remove them before classifying the actual Prolog error so a
         // contradiction at the check stage is not mistaken for an audit lock.
+        // Preserve only bounded identifiers from the formal existence error. Its
+        // context can contain authored dictionaries or query data and is never shown.
+        const existence = errorText.match(/^__KIBI_ERROR__:error\(existence_error\((key|procedure),([^,()\r\n]+)(?:,|\),)/m);
+        const identifier = existence?.[2]?.trim().replace(/^'([^']+)'$/, "$1");
+        if (existence?.[1] === "key" && identifier !== undefined) {
+            if (/^[A-Za-z][A-Za-z0-9_-]{0,95}$/.test(identifier)) {
+                return `Predicate or file not found (missing dictionary key: ${identifier})`;
+            }
+        }
+        if (existence?.[1] === "procedure" && identifier !== undefined) {
+            if (/^(?:[A-Za-z][A-Za-z0-9_]{0,95}:)?[A-Za-z][A-Za-z0-9_]{0,95}\/[0-9]{1,3}$/.test(identifier)) {
+                return `Predicate or file not found (missing procedure: ${identifier})`;
+            }
+        }
         const cleanError = errorText.replace(/^__KIBI_(?:STAGE|RUNTIME|ERROR)__:[^\r\n]*\r?\n?/gm, "");
         if (cleanError.includes("stale_snapshot")) {
             return "KB snapshot is stale; reattach or refresh the runtime before retrying (stale_snapshot)";
@@ -801,6 +920,8 @@ export class PrologProcess {
             cleanError.includes("Unknown procedure")) {
             return "Predicate or file not found";
         }
+        if (existence !== null)
+            return "Predicate or file not found";
         if (cleanError.includes("permission_error")) {
             return "Access denied or KB locked";
         }
@@ -827,7 +948,16 @@ export class PrologProcess {
     getPid() {
         return this.process?.pid || 0;
     }
+    lostProcessError() {
+        if (!this.interactiveStarted) {
+            return new Error("Prolog process not started");
+        }
+        return new PrologProcessTerminatedError(this.terminationReason ?? "process exited");
+    }
     async terminate() {
+        if (this.interactiveStarted) {
+            this.terminationReason ??= "terminated";
+        }
         if (this.terminationPromise) {
             await this.terminationPromise;
             return;

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

@@ -1 +1 @@
-{"version":3,"file":"diagnostic-usage.d.ts","sourceRoot":"","sources":["../../src/public/diagnostic-usage.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACzD,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAC7D,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,IAAI,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAiCD,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACtC,MAAM,CAIR;AAkHD,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACvC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,EACnD,MAAM,EAAE,OAAO,GACd,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA2EzB;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,oBAAoB,GAAG,IAAI,CAgC1E"}
+{"version":3,"file":"diagnostic-usage.d.ts","sourceRoot":"","sources":["../../src/public/diagnostic-usage.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACzD,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAC7D,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,IAAI,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAuBD,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACtC,MAAM,CAIR;AAkHD,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACvC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,EACnD,MAAM,EAAE,OAAO,GACd,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAwEzB;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,oBAAoB,GAAG,IAAI,CAgC1E"}

package/dist/public/diagnostic-usage.js

@@ -1,21 +1,10 @@
 import { createHash, randomUUID } from "node:crypto";
 import { appendFileSync, mkdirSync } from "node:fs";
 import path from "node:path";
+import { appendPayloadCountField, normalizeResultPayload, } from "./operations/result-envelope.js";
 function isRecord(value) {
     return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
-function resultRecord(result) {
-    if (!isRecord(result))
-        return undefined;
-    if (isRecord(result.structuredContent))
-        return result.structuredContent;
-    // CLI JSON operations return the same versioned KibiResult envelope as MCP
-    // structuredContent.  Unwrap its data before deriving operation-specific
-    // telemetry fields (coverage/proof fields in particular).
-    if (result.kibiProtocol === 1 && isRecord(result.data))
-        return result.data;
-    return result;
-}
 function stringArray(value) {
     return Array.isArray(value)
         ? value.filter((item) => typeof item === "string")
@@ -141,10 +130,7 @@ export function deriveDiagnosticUsageFields(tool, args, telemetry, result) {
             fields.actor_id = telemetry.actor_id;
         }
     }
-    const structured = resultRecord(result);
-    const envelope = isRecord(structured) && structured.kibiProtocol === 1
-        ? structured
-        : undefined;
+    const { envelope, data: structured } = normalizeResultPayload(result);
     if (envelope) {
         fields.protocol_version = envelope.kibiProtocol;
         fields.result_version =
@@ -162,18 +148,14 @@ export function deriveDiagnosticUsageFields(tool, args, telemetry, result) {
         fields.unsafe_original_retry = telemetry?.unsafe_original_retry === true;
     }
     if (tool === "kb_query" || tool === "kb_search") {
-        const resultCount = Number(structured?.count ?? 0);
-        fields.result_count = resultCount;
-        fields.zero_results = resultCount === 0;
-        fields.result_summary =
-            resultCount === 0 ? "0 results" : `${resultCount} results`;
+        appendPayloadCountField(fields, "result_count", "results", structured);
+        if (typeof fields.result_count === "number") {
+            fields.zero_results = fields.result_count === 0;
+        }
     }
     if (tool === "kb_check") {
-        const count = Number(structured?.count ?? 0);
-        fields.violation_count = count;
+        appendPayloadCountField(fields, "violation_count", "violations", structured);
         fields.requested_rules = Array.isArray(args.rules) ? args.rules : [];
-        fields.result_summary =
-            count === 0 ? "0 violations" : `${count} violations`;
     }
     if (tool === "kb_coverage" && structured) {
         appendCoverageFields(fields, args, structured);

package/dist/public/impact/analyzer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../../../src/public/impact/analyzer.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EACV,wBAAwB,EACxB,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAEpB,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,uBAAuB,CAAC,CAmElC"}
+{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../../../src/public/impact/analyzer.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EACV,wBAAwB,EACxB,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAEpB,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,uBAAuB,CAAC,CA2IlC"}

package/dist/public/impact/analyzer.js

@@ -1,27 +1,76 @@
 import * as path from "node:path";
+import { createMaintenanceSourceAnalysisService, readSnapshotSourceConfig, } from "../../plugins/maintenance-source-analysis.js";
+import { analyzeSourceChanges, assertSourceAnalysisGate, } from "../../plugins/source-change-analysis.js";
+import { captureStagedSnapshot } from "../../traceability/git-change-snapshot.js";
+import { readSnapshotKnowledge } from "../../traceability/snapshot-knowledge.js";
 import { extractSymbolsFromStagedFileAsync } from "../../traceability/symbol-extract.js";
 import { createSemanticReviewDiagnostics, createSymbolGranularityDiagnostics, } from "./diagnostics.js";
 import { createImpactManifestLookup, readImpactManifestResults, } from "./manifest.js";
+import { normalizeSourceFile } from "./source-changes.js";
 import { collectSourceChanges, uniqueSorted } from "./source-changes.js";
 import { buildNextActions, collectLinkedEntities, formatExtractedSymbols, } from "./summaries.js";
 import { createSymbolQualityDiagnostics } from "./symbol-quality.js";
 export async function analyzeChangedFileImpact(options) {
     const workspaceRoot = path.resolve(options.workspaceRoot);
-    const sourceChanges = collectSourceChanges({ ...options, workspaceRoot });
-    const sourceFiles = uniqueSorted(sourceChanges.map((change) => change.file));
-    const manifestResults = readImpactManifestResults(workspaceRoot);
+    const snapshot = options.staged
+        ? captureStagedSnapshot(workspaceRoot)
+        : undefined;
+    const filter = new Set((options.sourceFiles ?? []).map((file) => normalizeSourceFile(workspaceRoot, file)));
+    const snapshotAnalysisInventory = snapshot
+        ? snapshot.inventory.filter((file) => filter.size === 0 || filter.has(file.path))
+        : undefined;
+    const snapshotSourceInventory = snapshot
+        ? snapshot.inventory.filter((file) => file.analysisDepth !== "metadata" &&
+            !file.skipReason &&
+            file.content !== undefined &&
+            (filter.size === 0 || filter.has(file.path)))
+        : undefined;
+    const sourceChanges = snapshot
+        ? (snapshotSourceInventory ?? []).map((file) => ({
+            file: file.path,
+            status: file.status,
+            hunkRanges: file.hunkRanges,
+            content: file.content ?? "",
+        }))
+        : collectSourceChanges({ ...options, workspaceRoot });
+    const service = createMaintenanceSourceAnalysisService(workspaceRoot, snapshot ? readSnapshotSourceConfig(snapshot) : undefined);
+    const analyses = snapshot
+        ? await analyzeSourceChanges(snapshotAnalysisInventory ?? [], service)
+        : undefined;
+    if (analyses)
+        assertSourceAnalysisGate(snapshotAnalysisInventory ?? [], analyses);
+    const sourceFiles = uniqueSorted(snapshot
+        ? snapshot.inventory
+            .filter((file) => file.analysisDepth !== "metadata" &&
+            (filter.size === 0 || filter.has(file.path)))
+            .map((file) => file.path)
+        : sourceChanges.map((change) => change.file));
+    const manifestResults = snapshot
+        ? readSnapshotKnowledge(snapshot.readGit, snapshot.headTree, snapshot.readBlobs).filter((result) => result.entity.type === "symbol")
+        : readImpactManifestResults(workspaceRoot);
     const manifestLookup = createImpactManifestLookup(manifestResults);
     const symbolsByFile = new Map();
     const sourceContentByFile = new Map();
+    const sourceSymbolsByFile = new Map();
     for (const change of sourceChanges) {
         sourceContentByFile.set(change.file, change.content);
-        // Maintenance path: builtin-only (do not pass registry / workspaceRoot).
+        const analysis = analyses?.get(change.file)?.after ??
+            (await service.analyzeTextV2(change.file, change.content));
         const extracted = await extractSymbolsFromStagedFileAsync({
             path: change.file,
             status: change.status,
             hunkRanges: [...change.hunkRanges],
             content: change.content,
-        }, manifestLookup, {});
+        }, manifestLookup, { analyzeText: async () => analysis });
+        const allSymbols = await extractSymbolsFromStagedFileAsync({
+            path: change.file,
+            status: change.status,
+            content: change.content,
+            hunkRanges: [
+                { start: 1, end: Math.max(1, change.content.split("\n").length) },
+            ],
+        }, manifestLookup, { analyzeText: async () => analysis });
+        sourceSymbolsByFile.set(change.file, allSymbols);
         symbolsByFile.set(change.file, extracted.filter((symbol) => symbol.hunkRanges.length > 0));
     }
     const activeSourceFiles = new Set(sourceFiles);
@@ -34,6 +83,7 @@ export async function analyzeChangedFileImpact(options) {
                 manifestResults: activeManifestResults,
                 symbolsByFile,
                 sourceContentByFile,
+                sourceSymbolsByFile,
                 workspaceRoot,
             }),
             ...createSymbolQualityDiagnostics({
@@ -46,6 +96,7 @@ export async function analyzeChangedFileImpact(options) {
     const cappedDiagnostics = maxDiagnostics !== undefined && maxDiagnostics >= 0
         ? impactDiagnostics.slice(0, maxDiagnostics)
         : impactDiagnostics;
+    snapshot?.assertUnchanged();
     return {
         impactDiagnostics: cappedDiagnostics,
         sourceFiles,

package/dist/public/impact/diagnostics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../../src/public/impact/diagnostics.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0CAA0C,CAAC;AAYrF,OAAO,KAAK,EACV,iBAAiB,EACjB,gCAAgC,EAChC,mCAAmC,EACpC,MAAM,YAAY,CAAC;AA2FpB,wBAAgB,kCAAkC,CAChD,OAAO,EAAE,mCAAmC,GAC3C,oBAAoB,EAAE,CA+CxB;AAED,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,gCAAgC,GACxC,oBAAoB,EAAE,CAsBxB;AAED,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,SAAS,oBAAoB,EAAE,GAC3C,OAAO,CAET;AAED,wBAAgB,6BAA6B,CAC3C,WAAW,EAAE,SAAS,iBAAiB,EAAE,GACxC,OAAO,CAIT"}
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../../src/public/impact/diagnostics.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0CAA0C,CAAC;AAYrF,OAAO,KAAK,EACV,iBAAiB,EACjB,gCAAgC,EAChC,mCAAmC,EACpC,MAAM,YAAY,CAAC;AA6FpB,wBAAgB,kCAAkC,CAChD,OAAO,EAAE,mCAAmC,GAC3C,oBAAoB,EAAE,CA+CxB;AAED,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,gCAAgC,GACxC,oBAAoB,EAAE,CAsBxB;AAED,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,SAAS,oBAAoB,EAAE,GAC3C,OAAO,CAET;AAED,wBAAgB,6BAA6B,CAC3C,WAAW,EAAE,SAAS,iBAAiB,EAAE,GACxC,OAAO,CAIT"}

package/dist/public/impact/diagnostics.js

@@ -38,7 +38,9 @@ function readSourceSymbols(sourceFile, sourceContentByFile, workspaceRoot) {
     });
 }
 function getGranularSymbolsForSourceFile(sourceFile, options) {
-    const sourceSymbols = readSourceSymbols(sourceFile, options.sourceContentByFile, options.workspaceRoot ?? process.cwd());
+    const sourceSymbols = options.sourceSymbolsByFile
+        ? (options.sourceSymbolsByFile.get(sourceFile) ?? [])
+        : readSourceSymbols(sourceFile, options.sourceContentByFile, options.workspaceRoot ?? process.cwd());
     const changedSymbols = options.symbolsByFile.get(sourceFile);
     return {
         candidateSymbols: changedSymbols ?? sourceSymbols,

package/dist/public/impact/full-kb-quality.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"full-kb-quality.d.ts","sourceRoot":"","sources":["../../../src/public/impact/full-kb-quality.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAEV,gBAAgB,EACjB,MAAM,8BAA8B,CAAC;AAatC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAWjE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AASpD,KAAK,+BAA+B,GAAG;IACrC,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,GAAG,eAAe,CAAC,CAAC;IAC7D,QAAQ,CAAC,sBAAsB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACtD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B,CAAC;AAmgBF,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,GAAG,eAAe,CAAC,GAClD,OAAO,CAAC,gBAAgB,EAAE,CAAC,CA0D7B;AAED,wBAAgB,eAAe,CAC7B,UAAU,EAAE,OAAO,GAClB,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAM/C;AA2ID,wBAAsB,+BAA+B,CACnD,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CAkCvC"}
+{"version":3,"file":"full-kb-quality.d.ts","sourceRoot":"","sources":["../../../src/public/impact/full-kb-quality.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAEV,gBAAgB,EACjB,MAAM,8BAA8B,CAAC;AAatC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAWjE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AASpD,KAAK,+BAA+B,GAAG;IACrC,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,GAAG,eAAe,CAAC,CAAC;IAC7D,QAAQ,CAAC,sBAAsB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACtD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B,CAAC;AAmgBF,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,GAAG,eAAe,CAAC,GAClD,OAAO,CAAC,gBAAgB,EAAE,CAAC,CA8C7B;AAED,wBAAgB,eAAe,CAC7B,UAAU,EAAE,OAAO,GAClB,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAM/C;AA2ID,wBAAsB,+BAA+B,CACnD,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CAkCvC"}

package/dist/public/impact/full-kb-quality.js

@@ -404,18 +404,10 @@ export async function loadKbExtractionResults(prolog) {
         entities = await loadIndexedEntityProjection(prolog.queryEntities.bind(prolog));
     }
     else {
-        const entityResult = await prolog.query("findall([Id,Type,Props], kb_entity(Id, Type, Props), Results)");
-        if (entityResult.success) {
-            entities = entityResult.bindings.Results
-                ? parseListOfLists(entityResult.bindings.Results).map(parseEntityFromList)
-                : [];
-        }
-        else if (isOutputCapacityError(entityResult.error)) {
-            entities = await loadBoundedEntityProjection(prolog);
-        }
-        else {
-            throw new Error(`Full KB entity projection query failed: ${entityResult.error ?? "Unknown error"}`);
-        }
+        // Never probe with an unbounded all-entities findall: receipt histories
+        // make that answer grow without limit, and an overflow terminates the
+        // interactive Prolog process that serves every later query.
+        entities = await loadBoundedEntityProjection(prolog);
     }
     const relationships = new Map();
     for (const relationshipType of RELATIONSHIP_TYPES) {

package/dist/public/impact/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/public/impact/manifest.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sCAAsC,CAAC;AAc3E,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,MAAM,GACpB,SAAS,gBAAgB,EAAE,CAkB7B;AAED,wBAAgB,0BAA0B,CACxC,eAAe,EAAE,SAAS,gBAAgB,EAAE,GAC3C,cAAc,CAYhB"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/public/impact/manifest.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sCAAsC,CAAC;AAc3E,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,MAAM,GACpB,SAAS,gBAAgB,EAAE,CAkB7B;AAED,wBAAgB,0BAA0B,CACxC,eAAe,EAAE,SAAS,gBAAgB,EAAE,GAC3C,cAAc,CAwBhB"}

package/dist/public/impact/manifest.js

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import * as path from "node:path";
 import { extractFromManifest } from "../../extractors/manifest.js";
+import { createManifestLookupSentinelKey } from "../../traceability/symbol-extract.js";
 import { CANONICAL_ENTITY_PATHS } from "../../utils/kb-paths.js";
 import { isTraceabilityRelationshipType } from "../symbol-granularity.js";
 import { normalizeSourceFile } from "./source-changes.js";
@@ -29,9 +30,22 @@ export function readImpactManifestResults(workspaceRoot) {
 }
 export function createImpactManifestLookup(manifestResults) {
     const manifestLookup = new Map();
+    manifestLookup.set(createManifestLookupSentinelKey(".kb/symbols.yaml"), {
+        id: "__captured_manifest__",
+        relationships: [],
+    });
+    const ambiguous = new Set();
     for (const result of manifestResults) {
         const sourceFile = result.sourceFile ?? result.entity.source;
-        manifestLookup.set(`${sourceFile}:${result.entity.title}`, {
+        const key = `${sourceFile}:${result.entity.title}`;
+        if (ambiguous.has(key))
+            continue;
+        if (manifestLookup.has(key)) {
+            manifestLookup.delete(key);
+            ambiguous.add(key);
+            continue;
+        }
+        manifestLookup.set(key, {
             id: result.entity.id,
             relationships: toTraceabilityRelationships(result.relationships),
         });

package/dist/public/impact/source-changes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"source-changes.d.ts","sourceRoot":"","sources":["../../../src/public/impact/source-changes.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,wBAAwB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAiBzE,wBAAgB,mBAAmB,CACjC,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,GACjB,MAAM,CAKR;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CAE/D;AA6HD,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,wBAAwB,GAChC,YAAY,EAAE,CAchB"}
+{"version":3,"file":"source-changes.d.ts","sourceRoot":"","sources":["../../../src/public/impact/source-changes.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,wBAAwB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAMzE,wBAAgB,mBAAmB,CACjC,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,GACjB,MAAM,CAKR;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CAE/D;AA4ID,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,wBAAwB,GAChC,YAAY,EAAE,CAchB"}