kibi-cli 0.16.1 → 0.18.1

package/dist/prolog.js

@@ -15,7 +15,7 @@
  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/>.
 */
-import { spawn, spawnSync } from "node:child_process";
+import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
@@ -26,6 +26,22 @@ const 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);
+function packageVersion(packagePath) {
+    try {
+        const packageJson = require(packagePath);
+        return typeof packageJson.version === "string"
+            ? packageJson.version
+            : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+const 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(",");
 export function resolveKbPlPath() {
     // implements REQ-009
     const overrideKbPath = getKbPlPathOverride();
@@ -74,6 +90,7 @@ export class PrologProcess {
     cache = new Map();
     interactiveQueryTail = Promise.resolve();
     terminationPromise = null;
+    oneShotProcesses = new Set();
     useOneShotMode = typeof globalThis.Bun !== "undefined";
     attachedKbPath = null;
     onProcessExit = null;
@@ -90,7 +107,15 @@ export class PrologProcess {
             "-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");
@@ -150,10 +175,15 @@ export class PrologProcess {
         }
         if (this.useOneShotMode) {
             const oneShotResult = await this.queryOneShot(goal);
-            if (!cacheable && oneShotResult.success) {
+            // Compound goals are read-after-write sensitive, so keep them out of the
+            // cache to mirror the interactive path and let later reads observe
+            // same-session writes (e.g. kb_status freshness after a file lands).
+            const isBatchGoal = isSingleGoal && /^\s*\(/.test(this.normalizeGoal(goal));
+            const shouldCache = cacheable && !isBatchGoal;
+            if (!shouldCache && oneShotResult.success) {
                 this.invalidateCache();
             }
-            if (cacheable && oneShotResult.success) {
+            if (shouldCache && oneShotResult.success) {
                 this.cache.set(goalKey, oneShotResult);
             }
             return oneShotResult;
@@ -169,24 +199,26 @@ export class PrologProcess {
             this.clearQueryBuffers();
             const debug = isPrologDebugEnabled();
             const normalizedGoal = this.normalizeGoal(goal);
+            const goalLabel = this.goalLabel(normalizedGoal);
             const wrappedGoal = /^once\s*\(/.test(normalizedGoal)
                 ? `catch(${normalizedGoal}, _E, (print_message(error, _E), fail))`
                 : `catch(once((${normalizedGoal})), _E, (print_message(error, _E), fail))`;
             const start = Date.now();
             if (debug) {
-                console.error(`[prolog debug] start query: ${normalizedGoal}`);
+                console.error(`[prolog debug] start query: ${goalLabel}`);
             }
             this.process?.stdin?.write(`${wrappedGoal}.\nwriteln('${INTERACTIVE_QUERY_FRAME_END}').\n`);
             return new Promise((resolve, reject) => {
                 let settled = false;
                 const timeoutId = setTimeout(() => {
-                    const msg = `Query timeout after ${this.timeout / 1000}s (pid=${this.process?.pid ?? 0}, killed=${this.process?.killed ? "yes" : "no"}, exitCode=${this.process?.exitCode ?? "null"}, goal=${JSON.stringify(normalizedGoal.slice(0, 120))})`;
+                    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) {
-                        const tailOut = this.outputBuffer.slice(-2048);
-                        const tailErr = this.errorBuffer.slice(-2048);
                         console.error(`[prolog debug] timeout: ${msg}`);
-                        console.error(`[prolog debug] last stdout: ---\n${tailOut}\n---`);
-                        console.error(`[prolog debug] last stderr: ---\n${tailErr}\n---`);
+                        const runtime = this.errorBuffer
+                            .split("\n")
+                            .find((line) => line.includes("__KIBI_RUNTIME__"));
+                        console.error(`[prolog debug] runtime=${runtime ?? "unknown"} packages=${process.env.KIBI_PACKAGE_VERSIONS ?? KIBI_PACKAGE_VERSIONS}`);
                     }
                     settled = true;
                     void this.terminate().finally(() => {
@@ -224,12 +256,12 @@ export class PrologProcess {
                         clearTimeout(timeoutId);
                         settled = true;
                         if (debug) {
-                            console.error(`[prolog debug] query error: ${normalizedGoal} error=${this.errorBuffer.split("\n")[0]}`);
+                            console.error(`[prolog debug] query error: ${goalLabel} error=${this.errorBuffer.split("\n")[0]}`);
                         }
                         resolve({
                             success: false,
                             bindings: {},
-                            error: this.translateError(this.errorBuffer),
+                            error: this.addDiagnosticStage(this.translateError(this.errorBuffer), normalizedGoal, this.errorBuffer),
                         });
                         return;
                     }
@@ -263,7 +295,7 @@ export class PrologProcess {
                             this.cache.set(goalKey, result);
                         }
                         if (debug) {
-                            console.error(`[prolog debug] query success: ${normalizedGoal} elapsed=${(Date.now() - start) / 1000}s`);
+                            console.error(`[prolog debug] query success: ${goalLabel} elapsed=${(Date.now() - start) / 1000}s`);
                         }
                         resolve(result);
                         return;
@@ -297,6 +329,7 @@ export class PrologProcess {
         return !(trimmed.startsWith("kb_attach(") ||
             trimmed.startsWith("kb_detach") ||
             trimmed.startsWith("kb_save") ||
+            trimmed.startsWith("kb_commit_upsert(") ||
             trimmed.startsWith("kb_assert_") ||
             trimmed.startsWith("kb_delete_") ||
             trimmed.startsWith("kb_retract_"));
@@ -339,7 +372,7 @@ export class PrologProcess {
                     error: "KB already attached",
                 };
             }
-            const attachResult = this.execOneShot(trimmedGoal, null);
+            const attachResult = await this.execOneShot(trimmedGoal, null);
             if (attachResult.success) {
                 this.attachedKbPath = attachPath;
             }
@@ -347,7 +380,7 @@ export class PrologProcess {
         }
         return this.execOneShot(trimmedGoal, this.attachedKbPath);
     }
-    execOneShot(goal, kbPath) {
+    async execOneShot(goal, kbPath) {
         const originalGoalList = Array.isArray(goal)
             ? goal.map((item) => this.normalizeGoal(item))
             : [this.normalizeGoal(goal)];
@@ -381,37 +414,121 @@ export class PrologProcess {
             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 result = spawnSync(this.swiplPath, ["-q", "-g", prologGoal, "-t", "halt"], {
-            encoding: "utf8",
-            timeout: this.timeout,
-            maxBuffer: PROLOG_OUTPUT_MAX_BUFFER_BYTES,
-            env: {
-                ...process.env,
-                KIBI_GOAL: combinedGoal,
-                ...(kbPath ? { KIBI_KB_PATH: kbPath } : {}),
-            },
-            stdio: ["ignore", "pipe", "pipe"],
+        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 });
+            });
         });
-        if (result.error &&
-            (result.error.message.includes("timed out") ||
-                // Bun/Node differ here; keep a conservative timeout detection.
-                result.error.message.includes("ETIMEDOUT"))) {
-            throw new Error(`Query timeout after ${this.timeout / 1000}s`);
+        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("\n")
+                .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?.message.includes("ENOBUFS")) {
+        if (result.error !== undefined) {
             return {
                 success: false,
                 bindings: {},
-                error: PROLOG_OUTPUT_OVERFLOW_ERROR,
+                error: this.addDiagnosticStage(result.error.message, combinedGoal ?? "true", stderr),
             };
         }
-        const stdout = result.stdout ?? "";
-        const stderr = result.stderr ?? "";
         if (stderr.includes("ERROR")) {
             return {
                 success: false,
                 bindings: {},
-                error: this.translateError(stderr),
+                error: this.addDiagnosticStage(this.translateError(stderr), combinedGoal ?? "true", stderr),
             };
         }
         if (stdout.includes("__KIBI_TRUE__")) {
@@ -434,7 +551,7 @@ export class PrologProcess {
         return {
             success: false,
             bindings: {},
-            error: `Query failed - stdout: ${stdout.substring(0, 200)}, stderr: ${stderr.substring(0, 200)}`,
+            error: this.addDiagnosticStage(`Query failed - stdout: ${stdout.substring(0, 200)}, stderr: ${stderr.substring(0, 200)}`, combinedGoal ?? "true", stderr),
         };
     }
     normalizeGoal(goal) {
@@ -473,6 +590,66 @@ export class PrologProcess {
         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 {
+                // Fall back to the direct child when a process group is unavailable.
+            }
+        }
+        try {
+            child.kill(signal);
+        }
+        catch {
+            // The child may have exited between the group and direct kill attempts.
+        }
+    }
+    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)),
+            ]);
+        }
+    }
     // implements REQ-009
     isProcessUsable() {
         return Boolean(this.process?.stdin &&
@@ -495,26 +672,39 @@ export class PrologProcess {
     }
     // implements REQ-core-prolog-process-management
     translateError(errorText) {
+        // 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.
+        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";
+        }
         // SWI-Prolog print_message/2 formats errors as human-readable messages,
         // not raw Prolog terms. Match the actual output format.
-        if (errorText.includes("does not exist") &&
-            /entity [`'"].+?[`'"]/.test(errorText)) {
+        if (cleanError.includes("does not exist") &&
+            /entity [`'"].+?[`'"]/.test(cleanError)) {
             // SWI-Prolog doubles single quotes in formatted messages: ''REQ-TEST''
-            const entityIdMatch = errorText.match(/entity [`'"]+(.+?)[`'"]+ does not exist/);
+            const entityIdMatch = cleanError.match(/entity [`'"]+(.+?)[`'"]+ does not exist/);
             const matchedEntityId = entityIdMatch?.[1];
             const entityId = matchedEntityId !== undefined
                 ? matchedEntityId.replace(/^`?'+|'+`?$/g, "")
                 : "unknown";
-            if (errorText.includes("Target entity does not exist")) {
+            if (cleanError.includes("Target entity does not exist")) {
                 return `Target entity does not exist: ${entityId}`;
             }
-            if (errorText.includes("Source entity does not exist")) {
+            if (cleanError.includes("Source entity does not exist")) {
                 return `Source entity does not exist: ${entityId}`;
             }
             return `Entity does not exist: ${entityId}`;
         }
-        if (errorText.includes("Type error: `relationship' expected")) {
-            const relMatch = errorText.match(/\(Invalid relationship: ([^)]+)\)/);
+        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()}`;
@@ -522,21 +712,21 @@ export class PrologProcess {
             return "Invalid relationship type or direction";
         }
         // Fallback: check for raw Prolog error terms (used by other tools)
-        if (errorText.includes("existence_error") ||
-            errorText.includes("Unknown procedure")) {
+        if (cleanError.includes("existence_error") ||
+            cleanError.includes("Unknown procedure")) {
             return "Predicate or file not found";
         }
-        if (errorText.includes("permission_error")) {
+        if (cleanError.includes("permission_error")) {
             return "Access denied or KB locked";
         }
-        if (errorText.includes("syntax_error") ||
-            errorText.includes("Operator expected")) {
+        if (cleanError.includes("syntax_error") ||
+            cleanError.includes("Operator expected")) {
             return "Invalid query syntax";
         }
-        if (errorText.includes("timeout_error")) {
+        if (cleanError.includes("timeout_error")) {
             return `Operation exceeded ${this.timeout / 1000}s timeout`;
         }
-        const simpleError = (errorText
+        const simpleError = (cleanError
             .replace(/ERROR:\s*/g, "")
             .replace(/^\*\*.*\*\*$/gm, "")
             .replace(/^\s+/gm, "")
@@ -559,22 +749,16 @@ export class PrologProcess {
             this.onProcessExit = null;
         }
         const current = this.process;
+        const oneShots = [...this.oneShotProcesses];
         this.process = null;
         this.clearQueryBuffers();
-        if (current) {
+        if (current || oneShots.length > 0) {
             this.terminationPromise = (async () => {
-                current.stdin?.end();
-                current.kill("SIGTERM");
-                await new Promise((resolve) => {
-                    const timeout = setTimeout(() => {
-                        current.kill("SIGKILL");
-                        resolve(undefined);
-                    }, 1000);
-                    current.on("exit", () => {
-                        clearTimeout(timeout);
-                        resolve(undefined);
-                    });
-                });
+                if (current) {
+                    current.stdin?.end();
+                    await this.terminateProcessTree(current);
+                }
+                await Promise.all(oneShots.map((child) => this.terminateProcessTree(child)));
             })();
             try {
                 await this.terminationPromise;

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

@@ -0,0 +1,17 @@
+export interface DiagnosticUsageInput {
+    readonly workspaceRoot: string;
+    readonly tool: string;
+    readonly businessArgs: Readonly<Record<string, unknown>>;
+    readonly telemetry: Readonly<Record<string, unknown>> | null;
+    readonly startedAt: Date;
+    readonly finishedAt?: Date;
+    readonly status: "success" | "error";
+    readonly result?: unknown;
+    readonly error?: string;
+    readonly requestId?: string;
+    readonly logPath?: string;
+}
+export declare function diagnosticMutationFingerprint(args: Readonly<Record<string, unknown>>): string;
+export declare function deriveDiagnosticUsageFields(tool: string, args: Readonly<Record<string, unknown>>, telemetry: Readonly<Record<string, unknown>> | null, result: unknown): Record<string, unknown>;
+export declare function appendCliDiagnosticUsage(input: DiagnosticUsageInput): void;
+//# sourceMappingURL=diagnostic-usage.d.ts.map

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

@@ -0,0 +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;AA4BD,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACtC,MAAM,CAIR;AAiED,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,CAmDzB;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,oBAAoB,GAAG,IAAI,CAgC1E"}

package/dist/public/diagnostic-usage.js

@@ -0,0 +1,152 @@
+import { createHash, randomUUID } from "node:crypto";
+import { appendFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function resultRecord(result) {
+    if (!isRecord(result))
+        return undefined;
+    return isRecord(result.structuredContent) ? result.structuredContent : result;
+}
+function stringArray(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === "string")
+        : [];
+}
+function canonicalValue(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalValue);
+    if (!isRecord(value))
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .filter(([key]) => key !== "_diagnostic_telemetry")
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, child]) => [key, canonicalValue(child)]));
+}
+export function diagnosticMutationFingerprint(args) {
+    return createHash("sha256")
+        .update(JSON.stringify(canonicalValue(args)))
+        .digest("hex");
+}
+function appendMutationFields(fields, args) {
+    fields.mutation_fingerprint = diagnosticMutationFingerprint(args);
+    const type = typeof args.type === "string" ? args.type : "unknown";
+    const id = typeof args.id === "string" ? args.id : "unknown";
+    fields.mutation_target = `${type}:${id}`;
+}
+function appendSemanticFields(fields, receipt) {
+    if (!isRecord(receipt))
+        return;
+    const inventory = isRecord(receipt.inventory_contract)
+        ? receipt.inventory_contract
+        : undefined;
+    if (typeof inventory?.source_hash === "string") {
+        fields.semantic_source_hash = inventory.source_hash;
+    }
+    if (typeof receipt.logic_readiness === "string") {
+        fields.semantic_logic_readiness = receipt.logic_readiness;
+    }
+    if (typeof receipt.candidate_lane === "string") {
+        fields.semantic_candidate_lane = receipt.candidate_lane;
+    }
+}
+const RECEIPT_GAP_CODES = new Set([
+    "missing_verification_receipt",
+    "stale_verification_receipt",
+    "failed_verification_receipt",
+    "invalid_verification_receipt",
+    "verification_snapshot_unavailable",
+]);
+function appendCoverageFields(fields, args, result) {
+    const rows = Array.isArray(result.rows) ? result.rows.filter(isRecord) : [];
+    const summary = isRecord(result.summary) ? result.summary : {};
+    const gapCodes = rows.flatMap((row) => stringArray(row.proofGaps));
+    const repairPlan = isRecord(result.repairPlan)
+        ? result.repairPlan
+        : undefined;
+    const scope = isRecord(repairPlan?.scope) ? repairPlan.scope : undefined;
+    fields.coverage_by = typeof args.by === "string" ? args.by : "req";
+    fields.coverage_requirement_count = Number(summary.total ?? rows.length);
+    fields.coverage_proven_count = Number(summary.proofProven ?? 0);
+    fields.coverage_proof_missing_count = Number(summary.proofMissing ?? 0);
+    fields.coverage_proof_gap_count = gapCodes.length;
+    fields.coverage_gap_codes = [...new Set(gapCodes)].sort();
+    fields.coverage_receipt_gap_count = gapCodes.filter((code) => RECEIPT_GAP_CODES.has(code)).length;
+    if (typeof scope?.complete === "boolean") {
+        fields.coverage_scope_complete = scope.complete;
+    }
+}
+export function deriveDiagnosticUsageFields(tool, args, telemetry, result) {
+    const fields = {
+        telemetry_status: telemetry ? "provided" : "missing",
+    };
+    if (telemetry) {
+        fields.telemetry_is_autonomous = telemetry.is_autonomous ?? null;
+        fields.telemetry_confidence_score = telemetry.confidence_score ?? null;
+        fields.telemetry_attempt_number = telemetry.attempt_number ?? null;
+        if (typeof telemetry.session_id === "string") {
+            fields.session_id = telemetry.session_id;
+        }
+        if (typeof telemetry.actor_id === "string") {
+            fields.actor_id = telemetry.actor_id;
+        }
+    }
+    const structured = resultRecord(result);
+    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`;
+    }
+    if (tool === "kb_check") {
+        const count = Number(structured?.count ?? 0);
+        fields.violation_count = count;
+        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);
+        fields.result_summary = `${String(fields.coverage_proven_count)} proven; ${String(fields.coverage_proof_gap_count)} proof gaps`;
+    }
+    if (tool === "kb_semantic_advisor" && structured) {
+        appendSemanticFields(fields, structured.receipt);
+    }
+    if (tool === "kb_validate_upsert") {
+        appendMutationFields(fields, args);
+        fields.validation_valid = structured?.valid === true;
+        appendSemanticFields(fields, structured?.semanticAdvisor);
+    }
+    if (tool === "kb_upsert") {
+        appendMutationFields(fields, args);
+        appendSemanticFields(fields, structured?.semanticAdvisor);
+    }
+    if (!fields.result_summary)
+        fields.result_summary = `${tool} completed`;
+    return fields;
+}
+export function appendCliDiagnosticUsage(input) {
+    const finishedAt = input.finishedAt ?? new Date();
+    const requestId = input.requestId ?? `cli-${randomUUID()}`;
+    const logPath = input.logPath ??
+        process.env.KIBI_CLI_DIAGNOSTIC_USAGE_LOG_PATH ??
+        path.join(input.workspaceRoot, ".kb", "usage.log");
+    mkdirSync(path.dirname(logPath), { recursive: true });
+    appendFileSync(logPath, `${JSON.stringify({
+        timestamp: finishedAt.toISOString(),
+        request_id: requestId,
+        tool: input.tool,
+        interface: "cli_json",
+        telemetry: input.telemetry,
+        business_args: input.businessArgs,
+        status: input.status,
+        started_at: input.startedAt.toISOString(),
+        finished_at: finishedAt.toISOString(),
+        duration_ms: finishedAt.getTime() - input.startedAt.getTime(),
+        active_branch: process.env.KIBI_BRANCH ?? null,
+        ...(input.error ? { error_message: input.error } : {}),
+        ...deriveDiagnosticUsageFields(input.tool, input.businessArgs, input.telemetry, input.result),
+    })}\n`, "utf8");
+}