knodin 0.12.2 → 0.13.0

package/dist/src/response-budget.js

@@ -1,6 +1,8 @@
+import { isDeepStrictEqual } from "node:util";
 import { compareBytes } from "./compare.js";
 const encoder = new TextEncoder();
 export const MIN_RESPONSE_BUDGET_BYTES = 256;
+export const MIN_FLOW_ANALYSIS_BUDGET_BYTES = 1536;
 const MAX_REPORTED_TOTAL_PATHS = 128;
 function bytes(value) {
     return encoder.encode(JSON.stringify(value)).byteLength;
@@ -46,9 +48,34 @@ const PROTECTED_CONTRACT_KEYS = new Set([
     "target",
     "to",
 ]);
-const PROTECTED_CONTRACT_ARRAY_PATHS = new Set(["$/agents/clients"]);
+const PROTECTED_CONTRACT_ARRAY_PATHS = new Set(["$/agents/clients", "$/flowAnalysis/limitations"]);
+// Only the fixed scalar contract is mandatory. In particular, selector previews
+// and arbitrary arrays beneath indexCoverage must still obey normal budgets.
+const COVERAGE_SCALAR_PATH = /\/indexCoverage\/(?:version|mode|revision|digest|origin|prefixCount|fileCount|intentState|repositoryComplete|negativeScope)$/;
+// Scope coverage and impact uncertainty are independent qualifications. Keep
+// the generated impact contract intact before dropping evidence/detail rows.
+const IMPACT_CONTRACT_PATH = /\/impact\/(?:mode|direction|summary)$/;
+function coveragePreviews(value) {
+    if (!value || typeof value !== "object")
+        return [];
+    const found = [];
+    for (const [key, child] of Object.entries(value)) {
+        if (key === "indexCoverage" && child && typeof child === "object" && !Array.isArray(child)) {
+            const coverage = child;
+            if ("selectorPreview" in coverage)
+                found.push(coverage);
+        }
+        found.push(...coveragePreviews(child));
+    }
+    return found;
+}
 function isTruncatableDetail(entry) {
-    return (!entry.path.startsWith("$/sharedIndex/") &&
+    return (!entry.path.startsWith("$/flowAnalysis/limitations/") &&
+        !entry.path.startsWith("$/sharedIndex/") &&
+        !COVERAGE_SCALAR_PATH.test(entry.path) &&
+        !IMPACT_CONTRACT_PATH.test(entry.path) &&
+        !/^\$\/availability\/(?:state|graphState|outcome)$/.test(entry.path) &&
+        !/\/freshness\/(?:state|currentHead|indexedHead)$/.test(entry.path) &&
         (typeof entry.key !== "string" || !PROTECTED_CONTRACT_KEYS.has(entry.key)));
 }
 function synchronizeNestedCapabilityBudget(root, metadata, operation) {
@@ -83,6 +110,23 @@ function synchronizeNestedCapabilityBudget(root, metadata, operation) {
 }
 function truncatePayloadToBytes(root, byteLimit) {
     let truncated = false;
+    for (const coverage of coveragePreviews(root)) {
+        if (bytes(root) <= byteLimit)
+            break;
+        const removedArrays = new Set(collectArrays(coverage.selectorPreview).map((entry) => entry.value));
+        const metadata = root.responseBudget;
+        if (metadata?.totals) {
+            for (const entry of collectArrays(root)) {
+                if (removedArrays.has(entry.value) && Object.hasOwn(metadata.totals, entry.path)) {
+                    delete metadata.totals[entry.path];
+                    metadata.omittedTotalPaths = (metadata.omittedTotalPaths ?? 0) + 1;
+                }
+            }
+        }
+        delete coverage.selectorPreview;
+        truncated = true;
+    }
+    truncated = trimEmptyFreshnessDiagnostics(root, byteLimit) || truncated;
     while (bytes(root) > byteLimit) {
         const candidate = collectStrings(root)
             .filter((entry) => !entry.path.startsWith("$/responseBudget") &&
@@ -105,6 +149,7 @@ function truncatePayloadToBytes(root, byteLimit) {
         }
         truncated = true;
     }
+    truncated = trimEmptyFreshnessDiagnostics(root, byteLimit) || truncated;
     while (bytes(root) > byteLimit) {
         const candidate = collectArrays(root)
             .filter((entry) => !entry.path.startsWith("$/responseBudget") &&
@@ -116,6 +161,63 @@ function truncatePayloadToBytes(root, byteLimit) {
         candidate.value.pop();
         truncated = true;
     }
+    truncated = trimDiagnosticTotals(root, byteLimit) || truncated;
+    return truncated;
+}
+function trimEmptyFreshnessDiagnostics(root, byteLimit) {
+    if (bytes(root) <= byteLimit)
+        return false;
+    let truncated = false;
+    const freshness = root.freshness;
+    if (freshness && typeof freshness === "object" && !Array.isArray(freshness)) {
+        const record = freshness;
+        for (const key of ["currentHead", "indexedHead", "commitDistance", "lastSuccessfulRefresh"]) {
+            if (record[key] === null) {
+                delete record[key];
+                truncated = true;
+            }
+        }
+        const workingTree = record.workingTree;
+        if (workingTree && typeof workingTree === "object" && !Array.isArray(workingTree)) {
+            const diagnostics = workingTree;
+            for (const key of ["pendingPaths", "indexedFingerprint"]) {
+                if (diagnostics[key] === null) {
+                    delete diagnostics[key];
+                    truncated = true;
+                }
+            }
+            if (Object.keys(diagnostics).length === 0) {
+                delete record.workingTree;
+                truncated = true;
+            }
+        }
+    }
+    const availability = root.availability;
+    if (availability &&
+        typeof availability === "object" &&
+        Object.keys(availability).length === 0 &&
+        !Array.isArray(availability)) {
+        delete root.availability;
+        truncated = true;
+    }
+    return truncated;
+}
+function trimDiagnosticTotals(root, byteLimit) {
+    let truncated = false;
+    // Totals are diagnostic metadata, not source evidence. The path-count cap
+    // already permits omitting them with an explicit count; byte pressure uses
+    // the same contract rather than discarding mandatory scope/freshness facts.
+    const metadata = root.responseBudget;
+    if (metadata?.totals) {
+        const paths = Object.keys(metadata.totals).sort((a, b) => b.length - a.length || compareBytes(a, b));
+        for (const path of paths) {
+            if (bytes(root) <= byteLimit)
+                break;
+            delete metadata.totals[path];
+            metadata.omittedTotalPaths = (metadata.omittedTotalPaths ?? 0) + 1;
+            truncated = true;
+        }
+    }
     return truncated;
 }
 /**
@@ -127,6 +229,9 @@ export function applyResponseBudget(value, operation, request, defaults) {
     const byteRequest = positiveInt(request.bytes, defaults.bytes);
     const tokenLimit = positiveInt(request.tokens, defaults.tokens);
     const byteLimit = Math.min(byteRequest, tokenLimit * 4);
+    if (operation === "query:flow_analysis" && byteLimit < MIN_FLOW_ANALYSIS_BUDGET_BYTES) {
+        throw new RangeError(`query:flow_analysis response budget must allow at least ${MIN_FLOW_ANALYSIS_BUDGET_BYTES} serialized bytes (384 estimated tokens)`);
+    }
     if (byteLimit < MIN_RESPONSE_BUDGET_BYTES) {
         throw new RangeError(`response budget must allow at least ${MIN_RESPONSE_BUDGET_BYTES} serialized bytes (64 estimated tokens)`);
     }
@@ -136,8 +241,28 @@ export function applyResponseBudget(value, operation, request, defaults) {
         ? payload
         : { result: payload };
     const root = Array.isArray(payload) ? { results: payload } : objectRoot;
+    // Producers stamp coverage on both the result and its freshness snapshot.
+    // When they are identical, one authoritative root copy carries the same
+    // evidence; do not make tight budgets pay twice for a mandatory contract.
+    const freshness = root.freshness;
+    if (root.indexCoverage &&
+        typeof root.indexCoverage === "object" &&
+        !Array.isArray(root.indexCoverage) &&
+        freshness &&
+        typeof freshness === "object" &&
+        !Array.isArray(freshness) &&
+        isDeepStrictEqual(root.indexCoverage, freshness.indexCoverage))
+        delete freshness.indexCoverage;
     const totals = {};
     let truncated = false;
+    // A shortened preview must not retain its original truncated:false claim.
+    // Drop it as one optional unit instead of mutating its selector arrays.
+    for (const coverage of coveragePreviews(root)) {
+        if (collectArrays(coverage.selectorPreview).some((entry) => entry.value.length > itemLimit)) {
+            delete coverage.selectorPreview;
+            truncated = true;
+        }
+    }
     const initialArrays = collectArrays(root);
     const reportedTotals = [...initialArrays]
         // Byte order: this tie-break decides which paths survive the slice below,
@@ -199,7 +324,8 @@ export function applyResponseBudget(value, operation, request, defaults) {
         metadata.serializedBytes = actual;
         metadata.estimatedTokens = tokens;
     }
-    if (bytes(root) > byteLimit)
+    if (bytes(root) > byteLimit) {
         throw new RangeError(`response budget ${byteLimit} cannot preserve the ${operation} response contract; narrow the request or increase the budget`);
+    }
     return root;
 }

package/dist/src/server.js

@@ -152,6 +152,10 @@ export function createServer(dispatch = handleKnodinTool) {
                     }, { cooperativeCancellation: operation === "repair" })),
                 };
             const result = execution.result;
+            // Bundle receipts and budgets cover compact JSON text. Pretty-printing
+            // afterward would exceed the advertised bytes without changing its budget.
+            const selfBudgetedBundle = operation === "evidence" &&
+                result?.protocol === "knodin-evidence-bundle-v1";
             recordMcpLifecycle(context, "success", {
                 elapsedMs: Date.now() - startedAt,
             });
@@ -163,7 +167,12 @@ export function createServer(dispatch = handleKnodinTool) {
                         ? { predecessorTraceId: execution.predecessorTraceId }
                         : {}),
                 },
-                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                content: [
+                    {
+                        type: "text",
+                        text: selfBudgetedBundle ? JSON.stringify(result) : JSON.stringify(result, null, 2),
+                    },
+                ],
             };
         }
         catch (error) {
@@ -174,7 +183,9 @@ export function createServer(dispatch = handleKnodinTool) {
             });
             const recorded = recordMcpDiagnosticFailure(values, error);
             const message = recorded instanceof Error ? recorded.message : String(recorded);
-            const retrySafe = RETRY_SAFE_OPERATIONS.has(operation);
+            // Admission was rejected before dispatch, including for mutating operations.
+            const capacityRejected = failure.code === "KNODIN_WORKER_CAPACITY";
+            const retrySafe = capacityRejected || RETRY_SAFE_OPERATIONS.has(operation);
             return {
                 isError: true,
                 _meta: { requestId: context.requestId, traceId: context.traceId },
@@ -192,9 +203,11 @@ export function createServer(dispatch = handleKnodinTool) {
                             deadlineMs: context.deadlineMs,
                             retrySafe,
                             diagnosticLog: ".knodin/diagnostics/events.jsonl (only when opt-in diagnostics are enabled)",
-                            recovery: retrySafe
-                                ? "Retry once. If the transport closes, restart the MCP client and run `knodin doctor`; include `knodin diagnostics export` when diagnostics are enabled."
-                                : "Do not retry automatically. Run `knodin doctor`, inspect repository state, and include `knodin diagnostics export` when diagnostics are enabled.",
+                            recovery: capacityRejected
+                                ? "Retry after an active repository request finishes; this request was not dispatched."
+                                : retrySafe
+                                    ? "Retry once. If the transport closes, restart the MCP client and run `knodin doctor`; include `knodin diagnostics export` when diagnostics are enabled."
+                                    : "Do not retry automatically. Run `knodin doctor`, inspect repository state, and include `knodin diagnostics export` when diagnostics are enabled.",
                         }, null, 2),
                     },
                 ],

package/dist/src/shared-index/publisher.js

@@ -61,6 +61,36 @@ function countingHash(hash, count) {
         },
     });
 }
+function createPublisherSnapshot(databasePath, snapshotPath, metadata) {
+    const source = new Database(databasePath, { readonly: true });
+    try {
+        // A consistent copy includes committed WAL state without changing the
+        // live cache or requiring the original database to remain idle while
+        // compression streams it.
+        source.run("VACUUM INTO ?", [snapshotPath]);
+    }
+    finally {
+        source.close();
+    }
+    const snapshot = new Database(snapshotPath);
+    try {
+        const value = (key) => snapshot.query("SELECT value FROM meta WHERE key = ?").get(key)
+            ?.value;
+        if (value("lastIndexedHead") !== metadata.commit ||
+            value("sharedIndexInputFingerprint") !== metadata.inputFingerprint)
+            throw new SharedIndexError("integrity", "shared-index publisher graph changed before snapshot");
+        // Historical exact-input vectors are local acceleration only. Current
+        // symbol_embeddings remain in the shared-index contract.
+        snapshot.run("DROP TABLE IF EXISTS embedding_reuse_v1");
+        // DROP alone leaves vector bytes on freelist pages in the exported file.
+        snapshot.run("VACUUM");
+        snapshot.run("PRAGMA wal_checkpoint(TRUNCATE)");
+        snapshot.run("PRAGMA journal_mode = DELETE");
+    }
+    finally {
+        snapshot.close();
+    }
+}
 export async function createSharedPublisherBundle(options) {
     if (!options.config.enabled)
         throw new SharedIndexError("configuration", "shared-index publishing is disabled");
@@ -86,7 +116,17 @@ export async function createSharedPublisherBundle(options) {
     const compressedHash = crypto.createHash("sha256");
     const uncompressed = { bytes: 0 };
     const compressed = { bytes: 0 };
-    await pipeline(fs.createReadStream(databasePath), countingHash(uncompressedHash, uncompressed), createZstdCompress(), countingHash(compressedHash, compressed), fs.createWriteStream(graphFile, { flags: "wx", mode: 0o600 }));
+    // A private, exclusively created directory belongs to this invocation only.
+    // A competing publisher must never clean up another process's snapshot.
+    const snapshotDirectory = fs.mkdtempSync(path.join(output, ".publisher-snapshot-"));
+    const snapshotPath = path.join(snapshotDirectory, "graph.sqlite");
+    try {
+        createPublisherSnapshot(databasePath, snapshotPath, metadata);
+        await pipeline(fs.createReadStream(snapshotPath), countingHash(uncompressedHash, uncompressed), createZstdCompress(), countingHash(compressedHash, compressed), fs.createWriteStream(graphFile, { flags: "wx", mode: 0o600 }));
+    }
+    finally {
+        fs.rmSync(snapshotDirectory, { recursive: true, force: true });
+    }
     if (uncompressed.bytes <= 0 ||
         uncompressed.bytes > SHARED_INDEX_LIMITS.uncompressedBytes ||
         compressed.bytes <= 0 ||