knodin 0.12.2 → 0.13.0

package/dist/src/graph-query-health.js

@@ -1,3 +1,4 @@
+import { indexCoverageCore, indexCoverageNotice, indexCoverageSnapshot, } from "./index-coverage-read.js";
 function hasNonReconciliableDamage(graph) {
     if (Object.values(graph.orphaned).some((count) => count > 0))
         return true;
@@ -17,6 +18,14 @@ function unavailableState(graph) {
         return "indexing";
     if (graph.status === "indexing")
         return "indexing";
+    if (graph.indexCoverage?.origin === "invalid")
+        return "repair-needed";
+    if (graph.coverage.sourceFiles === 0 &&
+        graph.indexCoverage &&
+        (graph.indexCoverage.intentState !== "complete" || graph.indexCoverage.mode === "unknown"))
+        return "unknown";
+    if (graph.coverage.sourceFiles === 0 && graph.indexCoverage?.mode === "scoped")
+        return "empty-scope";
     if (graph.schemaVersion === 0)
         return graph.coverage.sourceFiles === 0 ? "empty-repository" : "not-initialized";
     if (graph.coverage.sourceFiles === 0)
@@ -44,6 +53,7 @@ export async function inspectGraphQueryHealth(repo, status) {
             status: "unavailable",
             state,
             graph,
+            ...(graph.indexCoverage ? { indexCoverage: graph.indexCoverage } : {}),
             remediation: graph.repairSteps,
         };
     }
@@ -72,9 +82,40 @@ function hasNoMatches(value) {
     return false;
 }
 /** Add an explicit healthy/no-match outcome without replacing operation data. */
-export function decorateGraphQueryResult(value, graphState = "healthy", freshness) {
+export function decorateGraphQueryResult(value, graphState = "healthy", freshness, ...coverageObservations) {
+    const [indexCoverage, initialCoverage] = coverageObservations;
+    const ownCoverage = value && typeof value === "object" && !Array.isArray(value)
+        ? value.indexCoverage
+        : undefined;
+    const readCoverage = ownCoverage ?? initialCoverage;
+    // Omitted observations on legacy callers are not the same as an explicit
+    // post-read observation that lost coverage metadata. A result's own scope
+    // belongs to its read lease and supersedes an older preflight observation.
+    if (coverageObservations.length >= 1 &&
+        (ownCoverage !== undefined || coverageObservations.length >= 2) &&
+        indexCoverageSnapshot(readCoverage) !== indexCoverageSnapshot(indexCoverage))
+        return {
+            available: false,
+            status: "unavailable",
+            state: "changed-during-read",
+            indexCoverage,
+            indexCoverageAtRead: indexCoverageCore(readCoverage),
+            remediation: [
+                "Index coverage changed during the read; results were withheld. Retry against the current coverage.",
+            ],
+        };
+    const selectedCoverage = ownCoverage ?? indexCoverage;
+    const coverageFields = selectedCoverage
+        ? {
+            indexCoverage: selectedCoverage,
+            ...(indexCoverageNotice(selectedCoverage)
+                ? { coverageNotice: indexCoverageNotice(selectedCoverage) }
+                : {}),
+        }
+        : {};
     if (value === null || value === undefined) {
         return {
+            ...coverageFields,
             status: "no-match",
             result: value ?? null,
             ...(freshness ? { freshness } : {}),
@@ -83,6 +124,7 @@ export function decorateGraphQueryResult(value, graphState = "healthy", freshnes
     }
     if (Array.isArray(value)) {
         return {
+            ...coverageFields,
             status: value.length === 0 ? "no-match" : "ok",
             results: value,
             ...(freshness ? { freshness } : {}),
@@ -95,12 +137,15 @@ export function decorateGraphQueryResult(value, graphState = "healthy", freshnes
     }
     if (typeof value !== "object") {
         return {
+            ...coverageFields,
             result: value,
             ...(freshness ? { freshness } : {}),
             availability: { state: graphState, outcome: "complete" },
         };
     }
     const root = value;
+    if (root.available === false || root.status === "unavailable")
+        return { ...root, ...coverageFields };
     // An unresolved target is not a no-match: nothing was searched for. Calling
     // it `no-match` is what let a misspelled symbol read as proof that nothing
     // calls it (KNODIN-28). Ambiguity is exempted for the same reason.
@@ -109,6 +154,7 @@ export function decorateGraphQueryResult(value, graphState = "healthy", freshnes
     const state = notFound ? "target-not-found" : noMatch ? "no-match" : graphState;
     return {
         ...root,
+        ...coverageFields,
         ...(freshness ? { freshness } : {}),
         ...(notFound && root.status === undefined ? { status: "target-not-found" } : {}),
         ...(noMatch && root.status === undefined ? { status: "no-match" } : {}),

package/dist/src/implementation-search.js

@@ -0,0 +1,69 @@
+/** An explicit discovery lens, never the default for general symbol search. */
+export const IMPLEMENTATION_KINDS = ["function", "method", "class", "constructor"];
+/** Rank possible implementations without choosing one or turning relevance into proof. */
+export async function findImplementationCandidates(engine, repo, request) {
+    const task = request.task.trim();
+    if (!task)
+        throw new Error("Implementation discovery requires a task");
+    const limit = request.limit ?? 10;
+    const offset = request.offset ?? 0;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 50)
+        throw new Error("Implementation discovery limit must be an integer from 1 to 50");
+    if (!Number.isSafeInteger(offset) || offset < 0)
+        throw new Error("Implementation discovery offset must be a nonnegative integer");
+    const page = await engine.search(task, repo, limit, {
+        kinds: [...IMPLEMENTATION_KINDS],
+        federate: false,
+        includeSource: false,
+        offset,
+    });
+    const unresolved = [];
+    if (page.semanticReadiness !== "ready")
+        unresolved.push(`Semantic evidence is ${page.semanticReadiness}; implementations may be missing.`);
+    if (page.results.some((row) => row.staleness !== "fresh" && row.staleness !== "reconciled"))
+        unresolved.push("Some candidate evidence is stale or has unknown freshness.");
+    return {
+        mode: "implementation-discovery",
+        repoPath: repo,
+        task,
+        status: unresolved.length ? "partial" : page.results.length ? "candidates" : "no-candidates",
+        candidates: page.results.map((row) => ({
+            identity: row.identity,
+            symbol: row.symbol,
+            file: row.filePath,
+            kind: row.kind,
+            rankScore: row.rrfScore,
+            staleness: row.staleness,
+            followup: {
+                operation: "context",
+                repoPath: repo,
+                task,
+                symbol: row.symbol,
+                identity: row.identity,
+                file: row.filePath,
+            },
+        })),
+        offset: page.offset,
+        limit: page.limit,
+        hasMore: page.hasMore,
+        continuation: page.hasMore
+            ? {
+                operation: "context",
+                contextMode: "implementation",
+                repoPath: repo,
+                task,
+                offset: page.offset + page.results.length,
+                limit,
+            }
+            : null,
+        retrieval: page.retrieval,
+        semanticReadiness: page.semanticReadiness,
+        unresolved,
+        bounds: {
+            includedKinds: [...IMPLEMENTATION_KINDS],
+            localRepositoryOnly: true,
+            automaticSelection: false,
+            note: "Ranked candidates require inspection. Types, interfaces, constants and other kinds are intentionally excluded; use ordinary search to find them. No completeness or implementation-correctness claim.",
+        },
+    };
+}

package/dist/src/index-coverage-read.js

@@ -0,0 +1,33 @@
+/** Bounded, semantic coverage state. Previews are presentation, not snapshot identity. */
+export function indexCoverageCore(coverage) {
+    if (!coverage)
+        return undefined;
+    const { version, mode, revision, digest, origin, prefixCount, fileCount, intentState, repositoryComplete, negativeScope, } = coverage;
+    return {
+        version,
+        mode,
+        revision,
+        digest,
+        origin,
+        prefixCount,
+        fileCount,
+        intentState,
+        repositoryComplete,
+        negativeScope,
+    };
+}
+export function indexCoverageSnapshot(coverage) {
+    return JSON.stringify(indexCoverageCore(coverage) ?? null);
+}
+/** Inventory coverage cannot certify complete static relationships or runtime nonuse. */
+export function indexCoverageNotice(coverage) {
+    if (!coverage)
+        return undefined;
+    if (coverage.intentState !== "complete" || coverage.negativeScope === "unknown")
+        return "Index coverage completeness is unverified, including within any declared scope; a negative graph answer does not establish absence.";
+    if (coverage.mode === "scoped")
+        return "Indexed graph evidence is limited to the declared index scope; repository-wide completeness is not established. This does not describe separate source, language-server or federated coverage.";
+    if (coverage.mode === "unknown" || !coverage.repositoryComplete)
+        return "Index coverage completeness is unverified; a negative answer does not establish repository-wide absence.";
+    return undefined;
+}

package/dist/src/investigation.js

@@ -0,0 +1,195 @@
+import { compareBytes } from "./compare.js";
+import { indexCoverageCore, indexCoverageNotice, indexCoverageSnapshot, } from "./index-coverage-read.js";
+function snapshot(state) {
+    return JSON.stringify([
+        state.indexGeneration,
+        state.freshness?.currentHead,
+        state.freshness?.indexedHead,
+        state.freshness?.workingTree?.indexedFingerprint,
+        indexCoverageSnapshot(state.indexCoverage),
+    ]);
+}
+/** A bounded investigation over existing facts; never an assertion of runtime completeness. */
+export async function buildTaskInvestigation(engine, repo, request) {
+    const { symbol, task } = request;
+    if (!symbol.trim() || !task.trim())
+        throw new Error("An investigation requires task and symbol");
+    const limit = request.limit ?? 20;
+    const depth = request.depth ?? 3;
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100)
+        throw new Error("Investigation limit must be an integer from 1 to 100");
+    if (!Number.isInteger(depth) || depth < 1 || depth > 6)
+        throw new Error("Investigation depth must be an integer from 1 to 6");
+    const selector = {
+        identity: request.identity,
+        file: request.file,
+        kind: request.kind,
+    };
+    // Establish the read lease before snapshotting: a cold disk graph can
+    // reconcile on its first query without any concurrent source mutation.
+    await engine.query("file_summary", request.file ?? "", repo, undefined, 1);
+    const before = await engine.status(repo);
+    const beforeSnapshot = snapshot(before);
+    const coverageAtRead = indexCoverageSnapshot(before.indexCoverage);
+    const explanation = await engine.explain(symbol, repo, "minimal", selector);
+    // Older adapters may omit per-operation coverage. An explicit observation
+    // must agree with the captured lease, even if status later changes back.
+    const explanationCoverageChanged = explanation.indexCoverage !== undefined &&
+        indexCoverageSnapshot(explanation.indexCoverage) !== coverageAtRead;
+    const base = {
+        mode: "investigation",
+        repoPath: repo,
+        task,
+        symbol: explanation.symbol,
+        ...(before.indexCoverage ? { indexCoverage: indexCoverageCore(before.indexCoverage) } : {}),
+        ...(indexCoverageNotice(before.indexCoverage)
+            ? { coverageNotice: indexCoverageNotice(before.indexCoverage) }
+            : {}),
+    };
+    const changed = (after) => ({
+        ...base,
+        available: false,
+        indexCoverage: indexCoverageCore(after.indexCoverage),
+        coverageNotice: indexCoverageNotice(after.indexCoverage),
+        status: "changed-during-investigation",
+        targetResolution: "unverified",
+        unresolved: [
+            "Graph generation or index coverage changed during investigation; mixed evidence was withheld. Retry against the current source and scope.",
+        ],
+        continuation: { operation: "context", repoPath: repo, task, symbol, ...selector, limit, depth },
+    });
+    if (explanation.ambiguity || !explanation.identity || explanationCoverageChanged) {
+        const after = await engine.status(repo);
+        if (explanationCoverageChanged || beforeSnapshot !== snapshot(after))
+            return changed(after);
+    }
+    if (explanation.ambiguity)
+        return {
+            ...base,
+            status: "ambiguous",
+            ambiguity: explanation.ambiguity,
+            next: "Select one identity or definition file before investigating dependencies.",
+        };
+    if (!explanation.identity)
+        return {
+            ...base,
+            status: "not-found",
+            targetResolution: "not-found",
+            next: "Locate the definition with search, then supply its symbol and file or identity.",
+        };
+    const resolved = { ...selector, identity: explanation.identity };
+    const query = (pattern, target = explanation.symbol, selected = resolved) => engine.query(pattern, target, repo, undefined, limit, depth, "minimal", selected, pattern === "impact" ? { direction: "upstream", includeTests: true } : undefined);
+    const [sites, callers, impact, tests] = await Promise.all([
+        query("rename_preview"),
+        query("callers_of"),
+        query("impact"),
+        query("tests_for"),
+    ]);
+    const definition = sites.results.find((row) => row.kind === "definition" && row.identity === explanation.identity);
+    const importers = definition?.file ? await query("importers_of", definition.file, {}) : undefined;
+    const after = await engine.status(repo);
+    const observationCoverageChanged = [sites, callers, impact, tests, importers].some((result) => result?.indexCoverage !== undefined &&
+        indexCoverageSnapshot(result.indexCoverage) !== coverageAtRead);
+    if (observationCoverageChanged || beforeSnapshot !== snapshot(after))
+        return changed(after);
+    const unresolved = [];
+    const coverageNotice = indexCoverageNotice(after.indexCoverage);
+    if (coverageNotice)
+        unresolved.push(coverageNotice);
+    if (after.freshness?.state !== "fresh")
+        unresolved.push(`Graph freshness is ${after.freshness?.state ?? "unknown"}.`);
+    if (!definition)
+        unresolved.push("Definition location was not returned within the site limit; file importers were not checked.");
+    if (explanation.sourceAvailability && explanation.sourceAvailability.state !== "available")
+        unresolved.push(`Source availability: ${explanation.sourceAvailability.state}`);
+    if (explanation.omissionCount)
+        unresolved.push(`${explanation.omissionCount} static-analysis omissions reported for the target; inspect explain for details.`);
+    const observations = [
+        ["sites", sites],
+        ["callers", callers],
+        ["impact", impact],
+        ["tests", tests],
+        ["importers", importers],
+    ];
+    for (const [name, result] of observations) {
+        if (!result)
+            continue;
+        if (result.staleness !== "fresh")
+            unresolved.push(`${name} evidence freshness is ${result.staleness ?? "unknown"}.`);
+        if (result.hasMore || result.count > result.results.length)
+            unresolved.push(`${name} results exceed the item limit; replay with a larger limit or inspect that relationship separately.`);
+        if (result.available === false || result.ambiguity || result.targetResolution === "not-found")
+            unresolved.push(`${name} could not establish the requested evidence.`);
+    }
+    if (explanation.staleness !== "fresh")
+        unresolved.push(`Target evidence freshness is ${explanation.staleness ?? "unknown"}.`);
+    const section = (result) => result && {
+        count: result.count,
+        returned: result.results.length,
+        truncated: result.hasMore === true || result.count > result.results.length,
+        results: result.results,
+        staleness: result.staleness,
+        continuation: limit < 100
+            ? {
+                operation: "context",
+                repoPath: repo,
+                task,
+                symbol: explanation.symbol,
+                ...resolved,
+                limit: Math.min(limit * 2, 100),
+                depth,
+            }
+            : null,
+        next: limit < 100
+            ? "Replay the investigation with a larger per-query limit; this is not an offset page."
+            : `Investigation limit reached. Inspect ${result.pattern} separately with an explicit larger budget; no completeness claim is made.`,
+    };
+    const source = explanation.source ?? "";
+    const sourceLines = source.split("\n");
+    let selectedSource = "";
+    for (const line of sourceLines) {
+        const next = selectedSource ? `${selectedSource}\n${line}` : line;
+        if (Buffer.byteLength(next, "utf8") > 4096)
+            break;
+        selectedSource = next;
+    }
+    const sourceTruncated = selectedSource !== source;
+    if (sourceTruncated)
+        unresolved.push("Target source exceeds the investigation excerpt; use explain with source detail.");
+    return {
+        ...base,
+        status: unresolved.length ? "partial" : "evidence-ready",
+        targetResolution: "resolved",
+        target: {
+            identity: explanation.identity,
+            file: definition?.file,
+            line: definition?.line,
+            summary: explanation.summary,
+            source: selectedSource,
+            sourceTruncated,
+            continuation: {
+                operation: "explain",
+                repoPath: repo,
+                symbol: explanation.symbol,
+                ...resolved,
+                includeSource: true,
+            },
+        },
+        sites: section(sites),
+        callers: section(callers),
+        impact: section(impact),
+        tests: section(tests),
+        importers: section(importers),
+        filesToInspect: [
+            ...new Set(observations.flatMap(([, result]) => result?.results.flatMap((row) => (row.file ? [row.file] : [])) ?? [])),
+        ].sort(compareBytes),
+        unresolved,
+        bounds: {
+            depth,
+            itemsPerQuery: limit,
+            staticAnalysis: true,
+            runtimeCompleteness: false,
+            note: "Returned sites and tests are evidence to inspect, not a complete edit plan or proof of test coverage.",
+        },
+    };
+}

package/dist/src/mcp-reliability.js

@@ -103,6 +103,10 @@ export function classifyMcpFailure(error) {
         return { kind: "client-disconnected", code: "KNODIN_CLIENT_DISCONNECTED" };
     if (code === "KNODIN_DEADLINE_EXCEEDED")
         return { kind: "deadline-exceeded", code };
+    // Admission failed before dispatch, so preserve this code for safe retry even
+    // for operations that would otherwise mutate repository state.
+    if (code === "KNODIN_WORKER_CAPACITY")
+        return { kind: "worker-capacity", code };
     if (code === "SQLITE_BUSY" ||
         code === "SQLITE_LOCKED" ||
         /database is locked|graph lock/i.test(message))

package/dist/src/mcp-worker-supervisor.js

@@ -21,16 +21,21 @@ function defaultWorkerCommand() {
 export class RepositoryWorker extends EventEmitter {
     repoPath;
     workerCommand;
+    admission;
     child;
     ready;
     pending = new Map();
     tail = Promise.resolve();
     restartTimes = [];
     lastFailureTraceId;
-    constructor(repoPath, workerCommand = defaultWorkerCommand()) {
+    requests = 0;
+    closed = false;
+    closing;
+    constructor(repoPath, workerCommand = defaultWorkerCommand(), admission = Promise.resolve()) {
         super();
         this.repoPath = repoPath;
         this.workerCommand = workerCommand;
+        this.admission = admission;
     }
     start() {
         if (this.child && this.ready)
@@ -54,6 +59,8 @@ export class RepositoryWorker extends EventEmitter {
             // exactly the amount raised, which surfaces as the next request
             // burning its whole deadline in startup rather than as slowness here.
             const startup = setTimeout(() => child.kill("SIGKILL"), 10_000);
+            child.once("exit", () => clearTimeout(startup));
+            child.once("error", () => clearTimeout(startup));
             if (!child.stdout)
                 throw codedError("KNODIN_WORKER_CRASHED", "graph worker stdout unavailable");
             const lines = readline.createInterface({ input: child.stdout });
@@ -167,8 +174,47 @@ export class RepositoryWorker extends EventEmitter {
         }, CANCEL_GRACE_MS);
     }
     async execute(context, args, signal, onProgress) {
+        if (this.closed)
+            throw codedError("KNODIN_WORKER_CLOSED", "graph worker was retired; acquire it again");
+        this.requests++;
+        this.emit("busy");
+        const deadlineAt = Date.now() + operationDeadlineMs(context.operation);
+        try {
+            let admissionTimer;
+            let admissionAbort;
+            try {
+                await Promise.race([
+                    this.admission,
+                    new Promise((_resolve, reject) => {
+                        admissionTimer = setTimeout(() => reject(codedError("KNODIN_DEADLINE_EXCEEDED", "request expired while waiting for worker admission")), Math.max(1, deadlineAt - Date.now()));
+                        admissionAbort = () => reject(codedError("KNODIN_CLIENT_DISCONNECTED", "MCP client disconnected before worker admission"));
+                        signal.addEventListener("abort", admissionAbort, { once: true });
+                        if (signal.aborted)
+                            admissionAbort();
+                    }),
+                ]);
+            }
+            finally {
+                if (admissionTimer)
+                    clearTimeout(admissionTimer);
+                if (admissionAbort)
+                    signal.removeEventListener("abort", admissionAbort);
+            }
+            if (signal.aborted)
+                throw codedError("KNODIN_CLIENT_DISCONNECTED", "MCP client disconnected before worker admission");
+            return await this.executeRequest(context, args, signal, onProgress, deadlineAt);
+        }
+        finally {
+            this.requests--;
+            if (!this.requests)
+                this.emit("idle");
+        }
+    }
+    get busy() {
+        return this.requests > 0;
+    }
+    async executeRequest(context, args, signal, onProgress, deadlineAt = Date.now() + operationDeadlineMs(context.operation)) {
         const deadlineMs = operationDeadlineMs(context.operation);
-        const deadlineAt = Date.now() + deadlineMs;
         const predecessor = this.tail;
         let release;
         this.tail = new Promise((resolve) => {
@@ -181,7 +227,7 @@ export class RepositoryWorker extends EventEmitter {
             await Promise.race([
                 predecessor,
                 new Promise((_resolve, reject) => {
-                    queueTimer = setTimeout(() => reject(codedError("KNODIN_DEADLINE_EXCEEDED", `${context.operation} exceeded its ${deadlineMs}ms deadline while queued`)), deadlineMs);
+                    queueTimer = setTimeout(() => reject(codedError("KNODIN_DEADLINE_EXCEEDED", `${context.operation} exceeded its ${deadlineMs}ms deadline while queued`)), Math.max(1, deadlineAt - Date.now()));
                     queueAbort = () => reject(codedError("KNODIN_CLIENT_DISCONNECTED", "MCP client disconnected while queued"));
                     signal.addEventListener("abort", queueAbort, { once: true });
                 }),
@@ -200,6 +246,10 @@ export class RepositoryWorker extends EventEmitter {
         }
         const { requestId, operation } = context;
         try {
+            if (this.closed)
+                throw codedError("KNODIN_WORKER_CLOSED", "graph worker is closed");
+            if (Date.now() >= deadlineAt)
+                throw codedError("KNODIN_DEADLINE_EXCEEDED", "request expired before worker dispatch");
             // Same race as the startup one below, one phase earlier: the queueAbort
             // arm above reports CLIENT_DISCONNECTED, and this re-check reported
             // CANCELLED for the identical event whenever the queue wait resolved in
@@ -267,6 +317,8 @@ export class RepositoryWorker extends EventEmitter {
             if (signal.aborted)
                 throw codedError("KNODIN_CLIENT_DISCONNECTED", "MCP client disconnected during worker startup");
             const predecessorTraceId = this.lastFailureTraceId;
+            if (this.closed)
+                throw codedError("KNODIN_WORKER_CLOSED", "graph worker is closed");
             if (predecessorTraceId)
                 recordMcpLifecycle(context, "restart", { predecessorTraceId });
             const result = await new Promise((resolve, reject) => {
@@ -317,6 +369,12 @@ export class RepositoryWorker extends EventEmitter {
         this.child?.kill("SIGKILL");
     }
     async close() {
+        this.closed = true;
+        this.closing ??= this.closeChild();
+        return this.closing;
+    }
+    async closeChild() {
+        await this.admission;
         const child = this.child;
         if (child?.exitCode !== null)
             return;
@@ -348,12 +406,23 @@ export class RepositoryWorker extends EventEmitter {
     }
 }
 export class WorkerSupervisor {
+    options;
     workers = new Map();
+    idleTimers = new Map();
+    retiring = new Set();
+    closed = false;
+    maxWorkers;
+    idleTimeoutMs;
     exitHandler = () => void this.close();
-    constructor() {
+    constructor(options = {}) {
+        this.options = options;
+        this.maxWorkers = workerLimit(options.maxWorkers ?? Number(process.env.KNODIN_MCP_MAX_WORKERS ?? 4), "maxWorkers");
+        this.idleTimeoutMs = workerLimit(options.idleTimeoutMs ?? Number(process.env.KNODIN_MCP_IDLE_TIMEOUT_MS ?? 300_000), "idleTimeoutMs");
         process.once("exit", this.exitHandler);
     }
     worker(repoPath) {
+        if (this.closed)
+            throw codedError("KNODIN_WORKER_CLOSED", "worker supervisor is closed");
         const resolved = fs.realpathSync(path.resolve(repoPath));
         let key = resolved;
         try {
@@ -368,14 +437,61 @@ export class WorkerSupervisor {
         }
         let worker = this.workers.get(key);
         if (!worker) {
-            worker = new RepositoryWorker(key);
+            if (this.workers.size >= this.maxWorkers) {
+                const victim = [...this.workers].find(([, candidate]) => !candidate.busy);
+                if (!victim)
+                    throw codedError("KNODIN_WORKER_CAPACITY", `all ${this.maxWorkers} repository workers are busy; retry after an active request completes`);
+                this.retire(victim[0], victim[1]);
+            }
+            worker = new RepositoryWorker(key, this.options.workerCommand, Promise.all([...this.retiring]).then(() => undefined));
             this.workers.set(key, worker);
+            const instance = worker;
+            worker.on("busy", () => this.clearIdleTimer(key));
+            worker.on("idle", () => this.touch(key, instance));
         }
+        this.touch(key, worker);
         return worker;
     }
+    clearIdleTimer(key) {
+        clearTimeout(this.idleTimers.get(key));
+        this.idleTimers.delete(key);
+    }
+    touch(key, worker) {
+        if (this.closed || this.workers.get(key) !== worker)
+            return;
+        this.clearIdleTimer(key);
+        this.workers.delete(key);
+        this.workers.set(key, worker);
+        if (!worker.busy) {
+            const timer = setTimeout(() => {
+                if (!worker.busy && this.workers.get(key) === worker)
+                    this.retire(key, worker);
+            }, this.idleTimeoutMs);
+            timer.unref();
+            this.idleTimers.set(key, timer);
+        }
+    }
+    retire(key, worker) {
+        this.clearIdleTimer(key);
+        this.workers.delete(key);
+        const closing = worker.close();
+        this.retiring.add(closing);
+        void closing.finally(() => this.retiring.delete(closing));
+    }
     async close() {
-        await Promise.all([...this.workers.values()].map((worker) => worker.close()));
+        this.closed = true;
+        for (const key of this.idleTimers.keys())
+            this.clearIdleTimer(key);
+        await Promise.all([
+            ...this.retiring,
+            ...[...this.workers.values()].map((worker) => worker.close()),
+        ]);
         this.workers.clear();
         process.off("exit", this.exitHandler);
     }
 }
+function workerLimit(value, name) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > 2_147_483_647)
+        throw new RangeError(`${name} must be a positive integer at most 2147483647`);
+    return value;
+}

package/dist/src/progressive-evidence.js

@@ -11,7 +11,7 @@ const MIN_PROGRESSIVE_BYTES = 1_600;
 function sha256(value) {
     return createHash("sha256").update(value).digest("hex");
 }
-function normalizeFile(repo, file) {
+export function normalizeEvidenceFile(repo, file) {
     if (!file || path.isAbsolute(file))
         throw new Error("file must be a repository-relative path");
     const root = fs.realpathSync(repo);
@@ -38,7 +38,7 @@ function normalizeFile(repo, file) {
         throw new Error("progressive evidence requires a regular repository file");
     return { absolute, relative, root };
 }
-function handleSecret(root) {
+export function evidenceHandleSecret(root) {
     const stateDirectory = resolveStateDir(root);
     if (fs.existsSync(stateDirectory) && fs.lstatSync(stateDirectory).isSymbolicLink())
         throw new Error("progressive evidence refuses a symlinked .knodin directory");
@@ -201,8 +201,8 @@ function omissionPath(request, handle, currentHash, contentBytes, relative) {
 export function deliverProgressiveEvidence(request) {
     if (!LEVELS.has(request.level))
         throw new Error("invalid progressive evidence level");
-    const { absolute, relative, root } = normalizeFile(request.repo, request.file);
-    const handleKey = handleSecret(root);
+    const { absolute, relative, root } = normalizeEvidenceFile(request.repo, request.file);
+    const handleKey = evidenceHandleSecret(root);
     const fileStat = fs.statSync(absolute);
     const keyStat = fs.statSync(handleKey.path);
     if (fileStat.dev === keyStat.dev && fileStat.ino === keyStat.ino)