knodin 0.7.5 → 0.8.2

package/dist/src/server.js

@@ -12,7 +12,9 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { recordDiagnosticFailure } from "./diagnostics.js";
-import { getKnodinTools, handleKnodinTool } from "./tools/knodin-tools.js";
+import { assertMcpMemoryHeadroom, classifyMcpFailure, createMcpRequestContext, recordMcpLifecycle, superviseMcpRequest, } from "./mcp-reliability.js";
+import { WorkerSupervisor } from "./mcp-worker-supervisor.js";
+import { attachMcpRequestSignal, getKnodinTools, handleKnodinTool } from "./tools/knodin-tools.js";
 import { KNODIN_VERSION } from "./version.js";
 const RETRY_SAFE_OPERATIONS = new Set([
     "architecture_overview",
@@ -25,11 +27,12 @@ const RETRY_SAFE_OPERATIONS = new Set([
     "search",
     "status",
 ]);
-class GatewayRequestQueue {
+const RECOVERY_LANE_OPERATIONS = new Set(["docs"]);
+class SafeGatewayScheduler {
     tail = Promise.resolve();
-    pending = 0;
-    async run(signal, task) {
-        const position = this.pending++;
+    async run(operation, signal, task) {
+        if (RECOVERY_LANE_OPERATIONS.has(operation))
+            return task();
         const predecessor = this.tail;
         let release;
         this.tail = new Promise((resolve) => {
@@ -41,10 +44,9 @@ class GatewayRequestQueue {
                 throw Object.assign(new Error("MCP request cancelled before dispatch"), {
                     code: "KNODIN_REQUEST_CANCELLED",
                 });
-            return await task(position);
+            return await task();
         }
         finally {
-            this.pending--;
             release();
         }
     }
@@ -65,16 +67,21 @@ export function recordMcpDiagnosticFailure(args, error, defaultRepo = process.cw
         phase: "dispatch",
         error,
     });
+    const message = error instanceof Error ? error.message : String(error);
     return diagnostic.recorded
-        ? new Error(`${error instanceof Error ? error.message : String(error)} [diagnostic ${diagnostic.correlationId}]`, { cause: error })
+        ? new Error(`${message} [diagnostic ${diagnostic.correlationId}]`, { cause: error })
         : error;
 }
 export function createServer(dispatch = handleKnodinTool) {
-    const queue = new GatewayRequestQueue();
+    const scheduler = new SafeGatewayScheduler();
+    const workers = new WorkerSupervisor();
     const server = new Server({ name: "knodin", version: KNODIN_VERSION }, {
         capabilities: { tools: {} },
         instructions: "Use knodin first for cold or unfamiliar codebase work: context to orient, explain for source-evidenced symbol context, query impact before meaningful edits, and review before handoff. Prefer direct reads for exact literals, non-code files, or files just edited this turn. If status reports repair-needed, follow its typed repair steps: repair graph damage or init displaced lifecycle routing before relying on graph evidence.",
     });
+    server.onclose = () => {
+        void workers.close();
+    };
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: getKnodinTools(),
     }));
@@ -88,53 +95,90 @@ export function createServer(dispatch = handleKnodinTool) {
         const progressToken = extra._meta?.progressToken;
         const requestId = String(extra.requestId);
         const startedAt = Date.now();
+        const repoPath = typeof values?.repoPath === "string" ? values.repoPath : process.cwd();
+        const context = createMcpRequestContext(requestId, operation, repoPath);
+        let progressSequence = 0;
         let heartbeat;
+        recordMcpLifecycle(context, "start");
         try {
-            const result = await queue.run(extra.signal, async (position) => {
-                const notify = async (message) => {
-                    if (progressToken === undefined)
-                        return;
-                    await extra.sendNotification({
-                        method: "notifications/progress",
-                        params: {
-                            progressToken,
-                            progress: Date.now() - startedAt,
-                            message,
-                        },
-                    });
+            assertMcpMemoryHeadroom();
+            const supervised = dispatch === handleKnodinTool && operation !== "docs";
+            const execution = supervised
+                ? await workers.worker(repoPath).execute(context, args, extra.signal, (sequence, phase) => {
+                    progressSequence = sequence;
+                    recordMcpLifecycle(context, "progress", { sequence });
+                    if (progressToken !== undefined)
+                        void extra
+                            .sendNotification({
+                            method: "notifications/progress",
+                            params: { progressToken, progress: sequence, message: phase },
+                        })
+                            .catch(ignoreNotificationFailure);
+                })
+                : {
+                    result: await scheduler.run(operation, extra.signal, () => superviseMcpRequest(context, extra.signal, async (operationSignal) => {
+                        const notify = async (message) => {
+                            if (progressToken === undefined)
+                                return;
+                            progressSequence++;
+                            recordMcpLifecycle(context, "progress", { sequence: progressSequence });
+                            await extra.sendNotification({
+                                method: "notifications/progress",
+                                params: {
+                                    progressToken,
+                                    progress: progressSequence,
+                                    message,
+                                },
+                            });
+                        };
+                        await notify(`Starting ${operation} (deadline ${context.deadlineMs}ms)`);
+                        heartbeat = startHeartbeat(notify, operation, startedAt);
+                        // Keep the production handler explicit: knodin's own source-evidence
+                        // extractor maps this low-level MCP registration to its dispatcher.
+                        if (dispatch === handleKnodinTool) {
+                            attachMcpRequestSignal(args, operationSignal);
+                            return await handleKnodinTool(args);
+                        }
+                        return await dispatch(args, { signal: operationSignal });
+                    }, { cooperativeCancellation: operation === "repair" })),
                 };
-                await notify(position > 0
-                    ? `Starting ${operation} after waiting behind ${position} earlier request(s)`
-                    : `Starting ${operation}`);
-                heartbeat = startHeartbeat(notify, operation, startedAt);
-                // Keep the production handler explicit: knodin's own source-evidence
-                // extractor maps this low-level MCP registration to its dispatcher.
-                return dispatch === handleKnodinTool ? await handleKnodinTool(args) : await dispatch(args);
-            });
+            const result = execution.result;
+            recordMcpLifecycle(context, "success", { elapsedMs: Date.now() - startedAt });
             return {
+                _meta: {
+                    requestId: context.requestId,
+                    traceId: context.traceId,
+                    ...("predecessorTraceId" in execution
+                        ? { predecessorTraceId: execution.predecessorTraceId }
+                        : {}),
+                },
                 content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
             };
         }
         catch (error) {
+            const failure = classifyMcpFailure(error);
+            recordMcpLifecycle(context, "failure", {
+                kind: failure.kind,
+                elapsedMs: Date.now() - startedAt,
+            });
             const recorded = recordMcpDiagnosticFailure(values, error);
             const message = recorded instanceof Error ? recorded.message : String(recorded);
-            const traceId = /\[diagnostic ([a-f0-9]{16})\]/.exec(message)?.[1] ?? `mcp-${requestId}`;
             const retrySafe = RETRY_SAFE_OPERATIONS.has(operation);
             return {
                 isError: true,
+                _meta: { requestId: context.requestId, traceId: context.traceId },
                 content: [
                     {
                         type: "text",
                         text: JSON.stringify({
-                            code: error?.code === "KNODIN_REQUEST_CANCELLED"
-                                ? "KNODIN_REQUEST_CANCELLED"
-                                : "KNODIN_OPERATION_FAILED",
+                            code: failure.code,
+                            kind: failure.kind,
                             message,
-                            traceId,
+                            traceId: context.traceId,
                             requestId,
                             operation,
-                            repository: typeof values?.repoPath === "string" ? values.repoPath : process.cwd(),
                             phase: "dispatch",
+                            deadlineMs: context.deadlineMs,
                             retrySafe,
                             diagnosticLog: ".knodin/diagnostics/events.jsonl (only when opt-in diagnostics are enabled)",
                             recovery: retrySafe
@@ -148,6 +192,7 @@ export function createServer(dispatch = handleKnodinTool) {
         finally {
             if (heartbeat)
                 clearInterval(heartbeat);
+            recordMcpLifecycle(context, "cleanup", { elapsedMs: Date.now() - startedAt });
         }
     });
     return server;

package/dist/src/structural-fast-path.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { compareBytes } from "./compare.js";
 import { contentFingerprint, readStructuralSnapshot, } from "./structural-snapshot.js";
 function exactFile(repo, file) {
     try {
@@ -124,7 +125,7 @@ function directSymbols(filePath, content) {
         }
         if (found) {
             const { kind, symbol } = found;
-            const visibility = line.match(/\b(public|private|protected|internal)\b/)?.[1] ??
+            const visibility = /\b(public|private|protected|internal)\b/.exec(line)?.[1] ??
                 (python && symbol.startsWith("_") ? "private" : "default");
             symbols.push({
                 identity: null,
@@ -212,7 +213,9 @@ export function runStructuralFastPath(repo, pattern, target, limit = 100) {
             directories.set(directory, value);
         }
         rows = [...directories]
-            .sort(([a], [b]) => a.localeCompare(b))
+            // Byte order: this sort decides which directories survive the
+            // `rows.slice(0, limit)` below, not merely how they read.
+            .sort(([a], [b]) => compareBytes(a, b))
             .map(([symbol, value]) => ({ symbol, kind: "directory", ...value }));
         fingerprint = contentFingerprint(JSON.stringify(matching.map(({ path: file, contentFingerprint: hash }) => [file, hash])));
     }
@@ -226,6 +229,13 @@ export function runStructuralFastPath(repo, pattern, target, limit = 100) {
         rows = files.flatMap((file) => file.symbols.map((symbol) => ({ ...symbol, file: file.path })));
     }
     const selected = rows.slice(0, limit);
+    let upgrade;
+    if (pattern === "file_summary")
+        upgrade = { operation: "explain", target };
+    else if (pattern === "project_overview")
+        upgrade = { operation: "query", pattern: "architecture_overview", target: "" };
+    else
+        upgrade = { operation: "query", pattern: "impact", target };
     return {
         pattern,
         target,
@@ -243,11 +253,7 @@ export function runStructuralFastPath(repo, pattern, target, limit = 100) {
             uniqueness: pattern === "project_overview" ? "not-applicable" : "file-scoped-only",
             evidenceGeneratedAt: snapshot?.generatedAt ?? new Date().toISOString(),
         },
-        upgrade: pattern === "file_summary"
-            ? { operation: "explain", target }
-            : pattern === "project_overview"
-                ? { operation: "query", pattern: "architecture_overview", target: "" }
-                : { operation: "query", pattern: "impact", target },
+        upgrade,
     };
 }
 export function runExactSymbolFastPath(repo, symbol, filePath) {
@@ -306,7 +312,7 @@ export function runExactSymbolFastPath(repo, symbol, filePath) {
         upgrade: { operation: "explain", target: symbol },
     };
 }
-export function tryStructuralFastPath(argv, cwd = process.cwd()) {
+export function tryStructuralFastPath(argv, cwd) {
     const valueAfter = (flag) => {
         const index = argv.indexOf(flag);
         return index >= 0
@@ -314,7 +320,7 @@ export function tryStructuralFastPath(argv, cwd = process.cwd()) {
             : argv.find((value) => value.startsWith(`${flag}=`))?.slice(flag.length + 1);
     };
     if (argv[0] === "explain" && argv[1] && valueAfter("--file")) {
-        const repo = path.resolve(valueAfter("--repo") ?? cwd);
+        const repo = path.resolve(valueAfter("--repo") ?? cwd ?? process.cwd());
         const result = runExactSymbolFastPath(repo, argv[1], valueAfter("--file"));
         if (!result)
             return false;
@@ -325,7 +331,7 @@ export function tryStructuralFastPath(argv, cwd = process.cwd()) {
         !["file_summary", "batch_outline", "project_overview"].includes(argv[1] ?? ""))
         return false;
     const pattern = argv[1];
-    const repo = path.resolve(valueAfter("--repo") ?? cwd);
+    const repo = path.resolve(valueAfter("--repo") ?? cwd ?? process.cwd());
     const target = pattern === "project_overview" ? "" : (argv[2] ?? "");
     const limit = Number(valueAfter("--limit") ?? 100);
     if (!target && pattern !== "project_overview")

package/dist/src/structural-snapshot.js

@@ -1,12 +1,14 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { compareBytes } from "./compare.js";
+import { resolveStateDir } from "./engine/state-paths.js";
 export const STRUCTURAL_SNAPSHOT_VERSION = 1;
 export function contentFingerprint(content) {
     return `sha256:${crypto.createHash("sha256").update(content).digest("hex")}`;
 }
 export function structuralSnapshotPath(repo) {
-    return path.join(path.resolve(repo), ".knodin", "structural-v1.json");
+    return path.join(resolveStateDir(repo), "structural-v1.json");
 }
 export function writeStructuralSnapshot(repo, files) {
     const destination = structuralSnapshotPath(repo);
@@ -14,7 +16,9 @@ export function writeStructuralSnapshot(repo, files) {
     const snapshot = {
         schemaVersion: STRUCTURAL_SNAPSHOT_VERSION,
         generatedAt: new Date().toISOString(),
-        files: [...files].sort((left, right) => left.path.localeCompare(right.path)),
+        // Byte order, not collation: this array is written to disk and read back
+        // on any host, so the snapshot's bytes must not depend on the locale.
+        files: [...files].sort((left, right) => compareBytes(left.path, right.path)),
     };
     const temporary = `${destination}.${process.pid}.tmp`;
     fs.writeFileSync(temporary, `${JSON.stringify(snapshot)}\n`, { mode: 0o600 });

package/dist/src/system-config.js

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { parseDocument } from "yaml";
+import { compareBytes } from "./compare.js";
 import { detectDuplicateCandidates, extractRepositoryRelationships, trackedRepositoryFiles, } from "./relationship-adapters.js";
 export const RELATIONSHIP_TYPES = [
     "depends_on",
@@ -52,6 +53,24 @@ function stringValue(value, field) {
         throw new Error(`${field} must be a string`);
     return value;
 }
+function repositoryInitialization(value) {
+    if (value === undefined)
+        return undefined;
+    const record = asRecord(value);
+    if (record.memoryLimitMiB === undefined)
+        return {};
+    const mib = record.memoryLimitMiB;
+    if (typeof mib !== "number" ||
+        !Number.isSafeInteger(mib) ||
+        mib < 128 ||
+        !Number.isSafeInteger(mib * 1024 * 1024))
+        throw new Error("repositoryInitialization.memoryLimitMiB must be an integer of at least 128");
+    return { memoryLimitMiB: mib };
+}
+export function configuredRepositoryInitMemoryLimitBytes(config) {
+    const mib = config.repositoryInitialization?.memoryLimitMiB;
+    return mib === undefined ? undefined : mib * 1024 * 1024;
+}
 function stableLegacyIdentity(portableReference) {
     let normalized = portableReference.replaceAll("\\", "/");
     while (normalized.endsWith("/"))
@@ -321,6 +340,7 @@ export function loadSystemConfiguration(repoPath, options = {}) {
     const repositories = (Array.isArray(team.repositories) ? team.repositories : []).map((value, index) => configuredRepository(value, index));
     const systems = (Array.isArray(team.systems) ? team.systems : []).map((value, index) => configuredSystem(value, index));
     const relationships = (Array.isArray(team.relationships) ? team.relationships : []).map((value, index) => declaredRelationship(value, index));
+    const initialization = repositoryInitialization(team.repositoryInitialization);
     const xdgConfigHome = options.xdgConfigHome ?? process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), ".config");
     applyPersonalMappings(repositories, xdgConfigHome);
     const legacyFederation = applyLegacyFederation(repo, repositories, relationships);
@@ -338,12 +358,15 @@ export function loadSystemConfiguration(repoPath, options = {}) {
             relationship,
         ])).values(),
     ];
-    uniqueRelationships.sort((left, right) => `${left.from}\0${left.type}\0${left.to}`.localeCompare(`${right.from}\0${right.type}\0${right.to}`));
+    // Byte order over a NUL-joined composite key: collation may ignore the NUL
+    // separators, blurring the field boundaries the key depends on.
+    uniqueRelationships.sort((left, right) => compareBytes(`${left.from}\0${left.type}\0${left.to}`, `${right.from}\0${right.type}\0${right.to}`));
     return {
         schemaVersion: 1,
         repositories,
         systems,
         relationships: uniqueRelationships,
+        ...(initialization === undefined ? {} : { repositoryInitialization: initialization }),
         compatibility: { legacyFederation },
     };
 }
@@ -525,7 +548,7 @@ export async function enrichSystemRelationships(config) {
         return config;
     return {
         ...config,
-        relationships: [...config.relationships, ...duplicates].sort((left, right) => `${left.from}\0${left.type}\0${left.to}\0${left.evidence.location}`.localeCompare(`${right.from}\0${right.type}\0${right.to}\0${right.evidence.location}`)),
+        relationships: [...config.relationships, ...duplicates].sort((left, right) => compareBytes(`${left.from}\0${left.type}\0${left.to}\0${left.evidence.location}`, `${right.from}\0${right.type}\0${right.to}\0${right.evidence.location}`)),
     };
 }
 function repositoryForIdentity(config, identity) {