knodin 0.8.3 → 0.8.5

package/dist/src/engine/index.js

@@ -19,6 +19,7 @@ import { fileURLToPath } from "node:url";
 import chokidar from "chokidar";
 import Parser from "web-tree-sitter";
 import { compareBytes } from "../compare.js";
+import { collectFileMetrics } from "../file-metrics.js";
 import { readIndexActivity } from "../index-activity.js";
 import { runReadOnlyLspQuery } from "../lsp-readonly.js";
 import { acquireRepairLease } from "../repair-lease.js";
@@ -26,6 +27,7 @@ import { analyzeResourceReachability, resourceFingerprint, } from "../resource-r
 import { contentFingerprint, writeStructuralSnapshot, } from "../structural-snapshot.js";
 import { KNODIN_VERSION } from "../version.js";
 import * as ann from "./ann-hnsw.js";
+import { allocateCandidate, assertCandidate, discardCandidateFiles, promoteCandidateFile, recoverInterruptedPromotion, } from "./candidate-database.js";
 import { computeSimilarity, generateEmbedding, generateEmbeddings, } from "./embeddings.js";
 import { walkRepoFiles } from "./file-walker.js";
 import { clearGitHistorySignalCache, collectGitHistorySignals, } from "./git-history.js";
@@ -59,6 +61,7 @@ export const REPO_WIDE_QUERY_PATTERNS = [
     "dead_code",
     "large_functions",
     "large_files",
+    "file_metrics",
     "import_cycles",
     "flows",
     "stats",
@@ -661,7 +664,31 @@ function symbolIdentityMatches(candidate, selector) {
 const dbInstances = new Map();
 const initPromises = new Map();
 const watchers = new Map();
+const watcherStates = new Map();
 const WATCH_DEBOUNCE_MS = 50;
+const MAX_RECURSIVE_WATCH_FILES = 20_000;
+function explicitDatabasePath(repoPath, databasePath) {
+    if (!databasePath)
+        return undefined;
+    const stateDir = path.resolve(resolveStateDir(repoPath));
+    const resolved = path.resolve(databasePath);
+    if (resolved === path.resolve(resolveDbPath(repoPath)))
+        throw new Error("knodin candidate database must be distinct from the active database");
+    const relative = path.relative(stateDir, resolved);
+    if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new Error("knodin candidate database must be a distinct path inside repository state");
+    }
+    let cursor = stateDir;
+    for (const segment of relative.split(path.sep)) {
+        cursor = path.join(cursor, segment);
+        if (fs.existsSync(cursor) && fs.lstatSync(cursor).isSymbolicLink())
+            throw new Error("knodin candidate database path must not contain symbolic links");
+    }
+    return resolved;
+}
+function databaseCacheKey(repoPath, databasePath) {
+    return explicitDatabasePath(repoPath, databasePath) ?? path.resolve(repoPath);
+}
 const watchQueues = new Map();
 const repositoryEngineOwners = new Map();
 /**
@@ -717,11 +744,32 @@ export async function __evictRemovedRepoState() {
         }
         dbInstances.delete(key);
         initPromises.delete(key);
+        watcherStates.delete(key);
+    }
+}
+function freshnessMechanismFor(repoPath, policy) {
+    if (policy.watcher === "disabled") {
+        return {
+            strategy: "git-probes-and-lifecycle-hooks",
+            watcher: "disabled",
+        };
+    }
+    const state = watcherStates.get(path.resolve(repoPath));
+    if (state?.watcher === "active") {
+        return {
+            strategy: "watcher-git-probes-and-lifecycle-hooks",
+            watcher: "active",
+        };
     }
+    return {
+        strategy: "git-probes-and-lifecycle-hooks",
+        watcher: state?.watcher ?? "disabled",
+        ...(state?.diagnostic ? { diagnostic: state.diagnostic } : {}),
+    };
 }
 // Bumped whenever any repo is (re)indexed, so cached community-detection results
 // below can be invalidated cheaply instead of recomputed on every call.
-const KNODIN_SCHEMA_VERSION = 22;
+export const KNODIN_SCHEMA_VERSION = 22;
 const LAST_REBUILD_SCHEMA_VERSION = 22;
 let indexGeneration = 0;
 const resourceReachabilityCache = new Map();
@@ -7322,7 +7370,7 @@ function fileDriftedFromIndexState(db, repoPath, relPath) {
         return st !== null;
     if (!st)
         return true;
-    return Math.abs(row.mtimeMs - st.mtimeMs) >= 1.0 || row.size !== st.size;
+    return row.mtimeMs !== st.mtimeMs || row.size !== st.size;
 }
 /**
  * Record the working-tree state the index now reflects. Called at the end of a
@@ -7462,7 +7510,7 @@ function stalenessFor(repoPath) {
     return freshnessProbes.get(path.resolve(repoPath))?.staleness ?? "unknown";
 }
 /** Recursively indexes all matching files within the repository. */
-async function indexRepo(repoPath, db, progress, skipEmbeddings = false) {
+async function indexRepo(repoPath, db, progress, skipEmbeddings = false, publishProcessState = true) {
     progress?.("collecting-files", 0, "Discovering indexable files");
     const collected = measurePerfPhaseSync("file_collection", () => collectRepoFilesWithCoverage(repoPath));
     const files = collected.files;
@@ -7508,17 +7556,26 @@ async function indexRepo(repoPath, db, progress, skipEmbeddings = false) {
     setMeta(db, "mcpBackfillVersion", "17");
     setMeta(db, COVERAGE_UNPARSED_META_KEY, JSON.stringify(Object.fromEntries(unparsedByExtension)));
     recordFreshnessBaseline(repoPath, db);
-    indexGeneration++;
+    if (publishProcessState)
+        indexGeneration++;
 }
 // makeWatchIgnorePredicate: single source of truth is src/engine/prune.ts
 // (R14) — imported above, no local copy here. chokidar v4/v5 accept only a
 // function/regex/literal path (no globs), which is what that shared
 // predicate provides.
 /** Starts a chokidar file watcher to incrementally update SQLite indexes in real-time. */
-function startFileWatcher(repoPath, db) {
+function startFileWatcher(repoPath, db, watcherFileLimit = MAX_RECURSIVE_WATCH_FILES) {
     const resolvedRepoPath = path.resolve(repoPath);
     if (watchers.has(resolvedRepoPath))
         return;
+    const indexedFileCount = db.query("SELECT COUNT(*) count FROM index_state").get()?.count ?? 0;
+    if (indexedFileCount > watcherFileLimit) {
+        watcherStates.set(resolvedRepoPath, {
+            watcher: "scale-limited",
+            diagnostic: "repository-too-large",
+        });
+        return;
+    }
     const queue = {
         pending: new Set(),
         timer: null,
@@ -7633,21 +7690,85 @@ function startFileWatcher(repoPath, db) {
     watcher.on("unlink", enqueue);
     watcher.on("ready", () => {
         queue.ready = true;
+        watcherStates.set(resolvedRepoPath, { watcher: "active" });
+    });
+    watcher.on("error", (error) => {
+        const code = typeof error === "object" && error !== null && "code" in error
+            ? String(error.code)
+            : "";
+        if (degradeWatcherForResourceLimit(resolvedRepoPath, code))
+            return;
+        console.error(`File watcher error for ${resolvedRepoPath}:`, error);
     });
-    watcher.on("error", (error) => console.error(`File watcher error for ${resolvedRepoPath}:`, error));
     watchers.set(resolvedRepoPath, watcher);
+    watcherStates.set(resolvedRepoPath, { watcher: "active" });
+}
+/** Convert native watch exhaustion into a bounded, query-safe freshness fallback. */
+export function degradeWatcherForResourceLimit(repoPath, code) {
+    if (code !== "EMFILE" && code !== "ENOSPC")
+        return false;
+    const resolved = path.resolve(repoPath);
+    const queue = watchQueues.get(resolved);
+    if (queue) {
+        queue.closed = true;
+        if (queue.timer)
+            clearTimeout(queue.timer);
+        queue.timer = null;
+    }
+    watcherStates.set(resolved, {
+        watcher: "resource-limited",
+        diagnostic: "file-descriptor-limit",
+    });
+    const watcher = watchers.get(resolved);
+    if (watcher) {
+        void watcher.close().finally(() => {
+            watchers.delete(resolved);
+            watchQueues.delete(resolved);
+        });
+    }
+    return true;
+}
+async function suspendFileWatcher(repoPath) {
+    const resolved = path.resolve(repoPath);
+    const watcher = watchers.get(resolved);
+    if (!watcher)
+        return false;
+    await watcher.close();
+    watchers.delete(resolved);
+    const queue = watchQueues.get(resolved);
+    if (queue) {
+        queue.closed = true;
+        if (queue.timer)
+            clearTimeout(queue.timer);
+        queue.timer = null;
+        await queue.drain();
+        watchQueues.delete(resolved);
+    }
+    watcherStates.set(resolved, { watcher: "disabled" });
+    return true;
 }
 /** Open and initialize SQLite connection and full repo index. */
 async function getOrInitDb(repoPath, options = {}) {
     const normalizedPath = path.resolve(repoPath);
-    let promise = initPromises.get(normalizedPath);
+    const selectedDatabasePath = explicitDatabasePath(normalizedPath, options.databasePath);
+    if (!selectedDatabasePath)
+        recoverInterruptedPromotion(normalizedPath);
+    const cacheKey = databaseCacheKey(normalizedPath, selectedDatabasePath);
+    let promise = initPromises.get(cacheKey);
     if (!promise) {
         promise = (async () => {
             const isTest = process.env.VITEST || process.env.NODE_ENV === "test";
             let dbPath;
-            if (isTest) {
+            if (isTest && !selectedDatabasePath) {
                 dbPath = ":memory:";
             }
+            else if (selectedDatabasePath) {
+                await fs.promises.mkdir(path.dirname(selectedDatabasePath), {
+                    recursive: true,
+                    mode: 0o700,
+                });
+                dbPath = selectedDatabasePath;
+            }
             else {
                 const stateDir = resolveStateDir(normalizedPath);
                 await fs.promises.mkdir(stateDir, { recursive: true });
@@ -8032,15 +8153,27 @@ async function getOrInitDb(repoPath, options = {}) {
                 }
                 noteFreshness(normalizedPath, reindexed > 0 ? "reconciled" : "fresh");
             }
-            if (!isTest) {
-                startFileWatcher(normalizedPath, db);
+            if (!selectedDatabasePath && !isTest && options.watcher !== "disabled") {
+                startFileWatcher(normalizedPath, db, options.watcherFileLimit);
+            }
+            else if (!watchers.has(normalizedPath)) {
+                watcherStates.set(normalizedPath, { watcher: "disabled" });
             }
-            dbInstances.set(normalizedPath, db);
+            dbInstances.set(cacheKey, db);
             return db;
         })();
-        initPromises.set(normalizedPath, promise);
+        initPromises.set(cacheKey, promise);
     }
     const db = await promise;
+    if (!selectedDatabasePath &&
+        !process.env.VITEST &&
+        process.env.NODE_ENV !== "test" &&
+        options.watcher !== "disabled" &&
+        !watchers.has(normalizedPath) &&
+        watcherStates.get(normalizedPath)?.watcher !== "scale-limited" &&
+        watcherStates.get(normalizedPath)?.watcher !== "resource-limited") {
+        startFileWatcher(normalizedPath, db, options.watcherFileLimit);
+    }
     // Cold start reconciles once (above); this guard covers everything after it,
     // so a session whose watcher dies still answers from a verified index.
     if (!options.skipFreshnessGuard)
@@ -10222,8 +10355,32 @@ function findImportSpecifierLines(absPath, symbol) {
  * threaded through each operation's many return sites, so the tag cannot be
  * forgotten on an early return (a not-found explain, a refused rename).
  */
-function withStaleness(engine, claimRepository) {
+function withStaleness(engine, claimRepository, openDb, openPolicy) {
     return {
+        createCandidate(repoPath, options) {
+            claimRepository(repoPath);
+            return engine.createCandidate(repoPath, options);
+        },
+        openCandidate(candidate) {
+            claimRepository(candidate.repo);
+            return engine.openCandidate(candidate);
+        },
+        reconcileCandidate(candidate, repoPath, changes, options) {
+            claimRepository(repoPath);
+            return engine.reconcileCandidate(candidate, repoPath, changes, options);
+        },
+        auditCandidate(candidate, options) {
+            claimRepository(candidate.repo);
+            return engine.auditCandidate(candidate, options);
+        },
+        promoteCandidate(candidate) {
+            claimRepository(candidate.repo);
+            return engine.promoteCandidate(candidate);
+        },
+        discardCandidate(candidate) {
+            claimRepository(candidate.repo);
+            return engine.discardCandidate(candidate);
+        },
         async explain(symbol, repoPath, detailLevel, selector) {
             claimRepository(repoPath);
             const result = await engine.explain(symbol, repoPath, detailLevel, selector);
@@ -10260,7 +10417,7 @@ function withStaleness(engine, claimRepository) {
                     const repos = await getFederatedRepos(repoPath);
                     const allRepos = await Promise.all(repos.map(async (repo) => ({
                         path: repo,
-                        db: await getOrInitDb(repo),
+                        db: await openDb(repo),
                     })));
                     const analytics = await getGraphAnalyticsSnapshot(allRepos, path.resolve(repoPath), n, options.relationKinds);
                     result.communities = analytics.communities;
@@ -10292,9 +10449,11 @@ function withStaleness(engine, claimRepository) {
             result.staleness = stalenessFor(repoPath);
             return result;
         },
-        status(repoPath, options) {
+        async status(repoPath, options) {
             claimRepository(repoPath);
-            return engine.status(repoPath, options);
+            const result = await engine.status(repoPath, options);
+            result.freshnessMechanism = freshnessMechanismFor(repoPath, openPolicy);
+            return result;
         },
         repair(repoPath, options) {
             claimRepository(repoPath);
@@ -10330,15 +10489,27 @@ function withStaleness(engine, claimRepository) {
         },
     };
 }
+const DEFAULT_ENGINE_OPEN_POLICY = Object.freeze({ watcher: "enabled" });
 /** Default SQLite + Tree-Sitter engine. */
-export function createEngine() {
+export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
     const owner = Symbol("knodin-engine");
     const ownedRepositories = new Set();
+    const explicitDatabaseKeys = new Set();
+    const candidateAudits = new Map();
+    const candidates = new Map();
     let closed = false;
+    const openDb = (repoPath, options = {}) => getOrInitDb(repoPath, {
+        ...options,
+        watcher: options.watcher ?? openPolicy.watcher,
+        watcherFileLimit: options.watcherFileLimit ?? openPolicy.watcherFileLimit,
+        databasePath: options.databasePath ?? openPolicy.databasePath,
+    });
     const claimRepository = (repoPath) => {
         if (closed)
             throw new Error("knodin engine is closed");
         const resolved = path.resolve(repoPath);
+        if (openPolicy.databasePath)
+            explicitDatabaseKeys.add(databaseCacheKey(resolved, openPolicy.databasePath));
         if (ownedRepositories.has(resolved))
             return;
         ownedRepositories.add(resolved);
@@ -10346,14 +10517,386 @@ export function createEngine() {
         owners.add(owner);
         repositoryEngineOwners.set(resolved, owners);
     };
+    const closeDatabaseKey = (key) => {
+        const db = dbInstances.get(key);
+        if (db) {
+            try {
+                db.run("PRAGMA wal_checkpoint(TRUNCATE);");
+            }
+            finally {
+                db.close();
+            }
+        }
+        dbInstances.delete(key);
+        initPromises.delete(key);
+    };
+    const closeCandidateDatabase = (candidate) => {
+        const key = databaseCacheKey(candidate.repo, candidate.databasePath);
+        closeDatabaseKey(key);
+        for (const suffix of ["-wal", "-shm"])
+            fs.rmSync(`${candidate.databasePath}${suffix}`, { force: true });
+    };
+    const candidateDigest = (candidate) => crypto.createHash("sha256").update(fs.readFileSync(candidate.databasePath)).digest("hex");
+    async function repairThroughCandidate(resolved, repairKey, options) {
+        let outerLease;
+        let candidate;
+        let candidateEngine;
+        let before;
+        const activeOperation = {
+            promise: undefined,
+            subscribers: new Set(options?.onProgress ? [options.onProgress] : []),
+            controller: new AbortController(),
+        };
+        const abortShared = () => activeOperation.controller.abort();
+        if (options?.signal?.aborted)
+            abortShared();
+        else
+            options?.signal?.addEventListener("abort", abortShared, { once: true });
+        let pendingCompleted;
+        const deliver = (event) => {
+            for (const subscriber of [...activeOperation.subscribers]) {
+                try {
+                    subscriber(event);
+                }
+                catch {
+                    // Progress subscribers cannot change repair correctness.
+                }
+            }
+        };
+        const forward = (event) => {
+            if (event.phase === "completed")
+                pendingCompleted = event;
+            else
+                deliver(event);
+        };
+        const operation = Promise.resolve()
+            .then(async () => {
+            outerLease = acquireRepairLease(resolved);
+            before = await engine.status(resolved, { audit: "deep" });
+            await suspendFileWatcher(resolved);
+            const activePath = resolveDbPath(resolved);
+            if (fs.existsSync(activePath)) {
+                const active = dbInstances.get(resolved) ?? new Database(activePath);
+                try {
+                    active.run("PRAGMA wal_checkpoint(TRUNCATE);");
+                }
+                finally {
+                    active.close();
+                }
+                dbInstances.delete(resolved);
+                initPromises.delete(resolved);
+                for (const suffix of ["-wal", "-shm"])
+                    fs.rmSync(`${activePath}${suffix}`, { force: true });
+            }
+            candidate = await engine.createCandidate(resolved, fs.existsSync(activePath) ? { sourceDatabasePath: activePath } : undefined);
+            candidateEngine = createEngine({
+                watcher: "disabled",
+                databasePath: candidate.databasePath,
+                repairLease: "disabled",
+            });
+            const staged = await candidateEngine.repair(resolved, {
+                ...options,
+                signal: activeOperation.controller.signal,
+                onProgress: forward,
+            });
+            await candidateEngine.close();
+            candidateEngine = undefined;
+            if (staged.cancelled || !staged.verified) {
+                await engine.discardCandidate(candidate);
+                candidate = undefined;
+                const after = await engine.status(resolved, { audit: "deep" });
+                if (pendingCompleted)
+                    deliver(pendingCompleted);
+                return {
+                    ...staged,
+                    before,
+                    after,
+                    repaired: [],
+                    remaining: after.missing.files.length + after.missing.records.length,
+                    outstandingIssues: {
+                        files: after.missing.files.length,
+                        records: after.missing.records.length,
+                        total: after.missing.files.length + after.missing.records.length,
+                    },
+                };
+            }
+            const audit = await engine.auditCandidate(candidate, { mode: "deep" });
+            if (!audit.healthy)
+                throw new Error(`repair candidate audit failed: ${audit.issues.join(", ")}`);
+            await engine.promoteCandidate(candidate);
+            candidate = undefined;
+            const after = await engine.status(resolved, { audit: "deep" });
+            if (pendingCompleted)
+                deliver(pendingCompleted);
+            return {
+                ...staged,
+                before,
+                after,
+                verified: after.status === "healthy",
+                outstandingIssues: {
+                    files: after.missing.files.length,
+                    records: after.missing.records.length,
+                    total: after.missing.files.length + after.missing.records.length,
+                },
+            };
+        })
+            .catch((error) => {
+            if (pendingCompleted)
+                deliver({
+                    ...pendingCompleted,
+                    phase: "failed",
+                    message: "Repair candidate failed before promotion",
+                });
+            throw error;
+        });
+        activeOperation.promise = operation;
+        repairOperations.set(repairKey, activeOperation);
+        try {
+            return await operation;
+        }
+        finally {
+            if (candidateEngine)
+                await candidateEngine.close();
+            if (candidate && candidates.has(candidate.id))
+                await engine.discardCandidate(candidate);
+            outerLease?.release();
+            options?.signal?.removeEventListener("abort", abortShared);
+            if (options?.onProgress)
+                activeOperation.subscribers.delete(options.onProgress);
+            if (repairOperations.get(repairKey) === activeOperation)
+                repairOperations.delete(repairKey);
+            if (openPolicy.watcher === "enabled" &&
+                before?.schemaVersion === KNODIN_SCHEMA_VERSION &&
+                fs.existsSync(resolveDbPath(resolved))) {
+                await openDb(resolved, {
+                    skipContentReconciliation: true,
+                    skipFreshnessGuard: true,
+                });
+            }
+        }
+    }
     // Bound to a name (rather than returned as a bare object literal) so the
     // `wiki` method below can call `engine.map(..., "standard")` and reuse its output
     // instead of duplicating community-detection logic. Safe: `wiki`'s body
     // only runs after this whole object has been constructed and assigned.
     const engine = {
+        async createCandidate(repoPath, options) {
+            const resolved = path.resolve(repoPath);
+            recoverInterruptedPromotion(resolved);
+            const candidate = allocateCandidate(resolved);
+            try {
+                if (options?.empty) {
+                    // Restore writes verified snapshot bytes here while the engine retains
+                    // ownership, keeping deep audit and promotion mandatory.
+                }
+                else if (options?.sourceDatabasePath) {
+                    const source = path.resolve(options.sourceDatabasePath);
+                    if (!fs.existsSync(source) ||
+                        !fs.statSync(source).isFile() ||
+                        fs.lstatSync(source).isSymbolicLink())
+                        throw new Error("candidate source database must be a regular non-symbolic-link file");
+                    const header = fs.readFileSync(source).subarray(0, 16).toString("binary");
+                    if (header !== "SQLite format 3\u0000")
+                        throw new Error("candidate source is not a SQLite database");
+                    fs.copyFileSync(source, candidate.databasePath, fs.constants.COPYFILE_EXCL);
+                    fs.chmodSync(candidate.databasePath, 0o600);
+                }
+                else {
+                    await getOrInitDb(resolved, {
+                        databasePath: candidate.databasePath,
+                        watcher: "disabled",
+                        skipContentReconciliation: true,
+                        skipFreshnessGuard: true,
+                    });
+                    closeCandidateDatabase(candidate);
+                }
+                candidates.set(candidate.id, candidate);
+                return candidate;
+            }
+            catch (error) {
+                closeCandidateDatabase(candidate);
+                discardCandidateFiles(resolved, candidate);
+                throw error;
+            }
+        },
+        async openCandidate(candidate) {
+            assertCandidate(candidate.repo, candidate);
+            if (!candidates.has(candidate.id))
+                throw new Error("candidate is not owned by this engine");
+            if (!fs.existsSync(candidate.databasePath))
+                throw new Error("candidate database is missing");
+            const header = fs.readFileSync(candidate.databasePath).subarray(0, 16).toString("binary");
+            if (header !== "SQLite format 3\u0000")
+                throw new Error("candidate is not a SQLite database");
+            const probe = new Database(candidate.databasePath, { readonly: true });
+            try {
+                const integrity = probe.query("PRAGMA quick_check").all();
+                if (integrity.length !== 1 || Object.values(integrity[0] ?? {})[0] !== "ok")
+                    throw new Error("candidate SQLite integrity check failed");
+                const schemaVersion = probe.query("PRAGMA user_version").get()?.user_version ?? 0;
+                if (schemaVersion !== KNODIN_SCHEMA_VERSION)
+                    throw new Error(`candidate schema ${schemaVersion} is incompatible with ${KNODIN_SCHEMA_VERSION}`);
+            }
+            finally {
+                probe.close();
+            }
+            await getOrInitDb(candidate.repo, {
+                databasePath: candidate.databasePath,
+                watcher: "disabled",
+                skipContentReconciliation: true,
+                skipFreshnessGuard: true,
+            });
+            return candidate;
+        },
+        async reconcileCandidate(candidate, repoPath, changes, options) {
+            const resolved = path.resolve(repoPath);
+            assertCandidate(resolved, candidate);
+            await engine.openCandidate(candidate);
+            candidateAudits.delete(candidate.id);
+            const db = dbInstances.get(databaseCacheKey(resolved, candidate.databasePath));
+            if (!db)
+                throw new Error("candidate database did not open");
+            if (!changes) {
+                await indexRepo(resolved, db, options?.onProgress, options?.skipEmbeddings === true, false);
+                return { reconciled: collectRepoFiles(resolved) };
+            }
+            const reconciled = [...new Set(changes)]
+                .map((file) => path.relative(resolved, path.resolve(resolved, file)))
+                .filter((file) => file !== "" && !file.startsWith("..") && !path.isAbsolute(file))
+                .sort(compareBytes);
+            for (const file of reconciled) {
+                const absolute = path.join(resolved, file);
+                if (fs.existsSync(absolute) && isIndexableSourcePath(file)) {
+                    await indexFile(absolute, file, resolved, db);
+                    recordIndexState(db, resolved, file);
+                }
+                else {
+                    db.run("BEGIN TRANSACTION;");
+                    try {
+                        deleteSymbolsForFile(db, file);
+                        db.run('DELETE FROM "references" WHERE callerFile = ?', [file]);
+                        db.run("DELETE FROM dependencies WHERE fromFile = ?", [file]);
+                        db.run("DELETE FROM mcp_tools WHERE filePath = ?", [file]);
+                        db.run("COMMIT;");
+                        removeIndexState(db, file);
+                    }
+                    catch (error) {
+                        db.run("ROLLBACK;");
+                        throw error;
+                    }
+                }
+            }
+            await refreshFlowsForApexFiles(db, resolved, reconciled);
+            persistSymbolIdentities(db, resolved, reconciled);
+            reconcileTypeScriptDi(db, resolved);
+            await indexEmbeddings(db, resolved);
+            setMeta(db, "lastIndexedHead", gitHead(resolved) ?? "");
+            setMeta(db, "lastSuccessfulReconciliation", new Date().toISOString());
+            recordFreshnessBaseline(resolved, db);
+            return { reconciled };
+        },
+        async auditCandidate(candidate) {
+            assertCandidate(candidate.repo, candidate);
+            if (!candidates.has(candidate.id))
+                throw new Error("candidate is not owned by this engine");
+            closeCandidateDatabase(candidate);
+            const issues = [];
+            const db = new Database(candidate.databasePath, { readonly: true });
+            try {
+                const quick = db.query("PRAGMA quick_check").all();
+                if (quick.length !== 1 || Object.values(quick[0] ?? {})[0] !== "ok")
+                    issues.push("sqlite-integrity");
+                if (db.query("PRAGMA foreign_key_check").all().length > 0)
+                    issues.push("foreign-key-integrity");
+                const schema = db.query("PRAGMA user_version").get()?.user_version ?? 0;
+                if (schema !== KNODIN_SCHEMA_VERSION)
+                    issues.push("database-schema-version");
+                const required = [
+                    "symbols",
+                    "references",
+                    "dependencies",
+                    "symbol_embeddings",
+                    "index_state",
+                    "meta",
+                ];
+                const tables = new Set(db
+                    .query("SELECT name FROM sqlite_master WHERE type='table'")
+                    .all()
+                    .map((row) => row.name));
+                for (const table of required)
+                    if (!tables.has(table))
+                        issues.push(`missing-table:${table}`);
+                if (tables.has("symbols") && tables.has("symbol_embeddings")) {
+                    const symbols = db.query("SELECT COUNT(*) count FROM symbols").get()?.count ?? 0;
+                    const embeddings = db.query("SELECT COUNT(*) count FROM symbol_embeddings").get()
+                        ?.count ?? 0;
+                    if (symbols !== embeddings)
+                        issues.push("semantic-index-incomplete");
+                }
+                if (tables.has("index_state")) {
+                    const sourceFiles = collectRepoFiles(candidate.repo);
+                    const sourceSet = new Set(sourceFiles);
+                    const indexed = db
+                        .query("SELECT filePath, mtimeMs, size FROM index_state")
+                        .all();
+                    const indexedSet = new Set(indexed.map((row) => row.filePath));
+                    if (sourceFiles.some((file) => !indexedSet.has(file)))
+                        issues.push("source-coverage");
+                    if (indexed.some((row) => !sourceSet.has(row.filePath)))
+                        issues.push("ineligible-index-state");
+                    if (indexed.some((row) => fileDriftedFromIndexState(db, candidate.repo, row.filePath)))
+                        issues.push("source-snapshot-drift");
+                }
+            }
+            finally {
+                db.close();
+            }
+            const databaseSha256 = candidateDigest(candidate);
+            if (issues.length === 0)
+                candidateAudits.set(candidate.id, databaseSha256);
+            else
+                candidateAudits.delete(candidate.id);
+            return { healthy: issues.length === 0, issues: [...new Set(issues)], databaseSha256 };
+        },
+        async promoteCandidate(candidate) {
+            assertCandidate(candidate.repo, candidate);
+            const auditedDigest = candidateAudits.get(candidate.id);
+            if (!auditedDigest)
+                throw new Error("candidate must pass deep audit before promotion");
+            const confirmation = await engine.auditCandidate(candidate, { mode: "deep" });
+            if (!confirmation.healthy || confirmation.databaseSha256 !== auditedDigest)
+                throw new Error("candidate or repository changed after deep audit");
+            closeCandidateDatabase(candidate);
+            if (candidateDigest(candidate) !== auditedDigest)
+                throw new Error("candidate changed after deep audit");
+            const resolved = candidate.repo;
+            await suspendFileWatcher(resolved);
+            const active = dbInstances.get(resolved);
+            if (active) {
+                active.run("PRAGMA wal_checkpoint(TRUNCATE);");
+                active.close();
+            }
+            dbInstances.delete(resolved);
+            initPromises.delete(resolved);
+            for (const suffix of ["-wal", "-shm"])
+                fs.rmSync(`${resolveDbPath(resolved)}${suffix}`, { force: true });
+            const backupPath = promoteCandidateFile(resolved, candidate);
+            candidates.delete(candidate.id);
+            candidateAudits.delete(candidate.id);
+            invalidateResolutionCaches(resolved);
+            indexGeneration++;
+            return { backupPath };
+        },
+        async discardCandidate(candidate) {
+            assertCandidate(candidate.repo, candidate);
+            closeCandidateDatabase(candidate);
+            discardCandidateFiles(candidate.repo, candidate);
+            candidateAudits.delete(candidate.id);
+            candidates.delete(candidate.id);
+        },
         async explain(symbol, repoPath, detailLevel = "standard", selector = {}) {
             const repos = await getFederatedRepos(repoPath);
-            const allRepos = await Promise.all(repos.map(async (r) => ({ path: r, db: await getOrInitDb(r) })));
+            const allRepos = await Promise.all(repos.map(async (r) => ({ path: r, db: await openDb(r) })));
             let targetRepoPath = repoPath;
             let primaryDef = null;
             const matches = [];
@@ -10518,7 +11061,7 @@ export function createEngine() {
             };
         },
         async review(base, repoPath, detailLevel = "standard", options = {}) {
-            const db = await getOrInitDb(repoPath);
+            const db = await openDb(repoPath);
             const { modifiedFiles, changedFiles } = measurePerfPhaseSync("review_diff_discovery", () => {
                 const modifiedFiles = parseGitDiff(base, repoPath, options);
                 return {
@@ -10715,7 +11258,7 @@ export function createEngine() {
             };
         },
         async dependencyGraph(repoPath) {
-            const db = await getOrInitDb(repoPath);
+            const db = await openDb(repoPath);
             const rows = db
                 .query("SELECT fromFile, toFile, kind, COALESCE(confidence, 1.0) AS confidence, sourceEvidence FROM dependencies")
                 .all();
@@ -10763,7 +11306,7 @@ export function createEngine() {
                 const repos = await getFederatedRepos(repoPath);
                 const allRepos = await Promise.all(repos.map(async (repo) => ({
                     path: repo,
-                    db: await getOrInitDb(repo),
+                    db: await openDb(repo),
                 })));
                 const cacheKey = JSON.stringify([
                     resolvedRepoPath,
@@ -10846,7 +11389,7 @@ export function createEngine() {
                 return cached.result;
             const computeMap = (async () => {
                 const repos = await getFederatedRepos(repoPath);
-                const allRepos = await Promise.all(repos.map(async (r) => ({ path: r, db: await getOrInitDb(r) })));
+                const allRepos = await Promise.all(repos.map(async (r) => ({ path: r, db: await openDb(r) })));
                 const formatPath = makePathFormatter(resolvedRepoPath);
                 const analytics = await getGraphAnalyticsSnapshot(allRepos, resolvedRepoPath);
                 const { communities, symbolCommunity } = analytics;
@@ -11108,7 +11651,7 @@ export function createEngine() {
             // Minimal mode
             const languageOfFile = createLanguageMemo();
             const repos = await getFederatedRepos(repoPath);
-            const allRepos = await Promise.all(repos.map(async (r) => ({ path: r, db: await getOrInitDb(r) })));
+            const allRepos = await Promise.all(repos.map(async (r) => ({ path: r, db: await openDb(r) })));
             const minimalCommunities = await Promise.all(fullMap.communities.map(async (c) => {
                 const files = c.files ?? [];
                 const langs = new Map();
@@ -11160,8 +11703,9 @@ export function createEngine() {
             // Audit must not run the cold-start reconciler: otherwise status would
             // repair and timestamp drift before reporting it. Reuse an active DB in
             // long-lived processes, or open the existing local DB read-only.
-            const activeDb = dbInstances.get(resolved);
-            const diskDbPath = resolveDbPath(resolved);
+            const diskDbPath = explicitDatabasePath(resolved, openPolicy.databasePath) ?? resolveDbPath(resolved);
+            const statusCacheKey = databaseCacheKey(resolved, openPolicy.databasePath);
+            const activeDb = dbInstances.get(statusCacheKey);
             const db = activeDb ??
                 (fs.existsSync(diskDbPath) ? new Database(diskDbPath, { readonly: true }) : null);
             const verifiedAt = new Date().toISOString();
@@ -11222,6 +11766,7 @@ export function createEngine() {
                     verification: { mode: "live-operation", verifiedAt },
                     repairSteps: [],
                     activity,
+                    freshnessMechanism: freshnessMechanismFor(resolved, openPolicy),
                 };
             }
             if (!db) {
@@ -11253,6 +11798,7 @@ export function createEngine() {
                     lastIndexedHead: "",
                     freshness: buildFreshnessEnvelope(resolved, null, verifiedAt, "repair-needed"),
                     verification: { mode: "deep-audit", verifiedAt },
+                    freshnessMechanism: freshnessMechanismFor(resolved, openPolicy),
                     repairSteps: [
                         "Run `knodin repair` to create the local index.",
                         "Run `knodin status` again to verify health.",
@@ -11260,7 +11806,7 @@ export function createEngine() {
                 };
             }
             const databaseFingerprint = databaseFileFingerprint(diskDbPath);
-            const cached = statusCache.get(resolved);
+            const cached = statusCache.get(statusCacheKey);
             if (options.audit !== "deep" &&
                 cached?.generation === indexGeneration &&
                 cached.databaseFingerprint === databaseFingerprint) {
@@ -11373,6 +11919,7 @@ export function createEngine() {
                     lastIndexedHead: "",
                     freshness: buildFreshnessEnvelope(resolved, db, verifiedAt, "repair-needed"),
                     verification: { mode: "deep-audit", verifiedAt },
+                    freshnessMechanism: freshnessMechanismFor(resolved, openPolicy),
                     repairSteps: schemaVersion > KNODIN_SCHEMA_VERSION
                         ? [
                             "Upgrade knodin to a version that supports this local graph schema.",
@@ -11406,7 +11953,7 @@ export function createEngine() {
                     return false;
                 try {
                     const stat = fs.statSync(path.join(resolved, row.filePath));
-                    return stat.size !== row.size || Math.abs(stat.mtimeMs - row.mtimeMs) >= 1;
+                    return stat.size !== row.size || stat.mtimeMs !== row.mtimeMs;
                 }
                 catch {
                     return false;
@@ -11463,6 +12010,7 @@ export function createEngine() {
                 freshness,
                 indexGeneration,
                 verification: { mode: "deep-audit", verifiedAt },
+                freshnessMechanism: freshnessMechanismFor(resolved, openPolicy),
                 repairSteps: needsRepair
                     ? [
                         "Run `knodin repair` to rebuild only missing or damaged local state.",
@@ -11474,7 +12022,7 @@ export function createEngine() {
                 db.close();
             if (!needsRepair && !stale)
                 noteFreshness(resolved, "fresh");
-            setBoundedCache(statusCache, resolved, {
+            setBoundedCache(statusCache, statusCacheKey, {
                 generation: indexGeneration,
                 databaseFingerprint,
                 result: structuredClone(result),
@@ -11483,7 +12031,8 @@ export function createEngine() {
         },
         async repair(repoPath, options) {
             const resolved = path.resolve(repoPath);
-            const inFlight = repairOperations.get(resolved);
+            const repairKey = databaseCacheKey(resolved, openPolicy.databasePath);
+            const inFlight = repairOperations.get(repairKey);
             if (inFlight) {
                 if (options?.onProgress)
                     inFlight.subscribers.add(options.onProgress);
@@ -11503,7 +12052,11 @@ export function createEngine() {
                     options?.signal?.removeEventListener("abort", abortShared);
                 }
             }
-            invalidateResolutionCaches(resolved);
+            if (!openPolicy.databasePath && !process.env.VITEST && process.env.NODE_ENV !== "test")
+                return repairThroughCandidate(resolved, repairKey, options);
+            const watcherStateBefore = watcherStates.get(resolved)?.watcher;
+            if (!openPolicy.databasePath)
+                invalidateResolutionCaches(resolved);
             const operationId = crypto.randomUUID();
             const startedAt = Date.now();
             let sequence = 0;
@@ -11559,13 +12112,18 @@ export function createEngine() {
             };
             const operation = Promise.resolve()
                 .then(async () => {
-                repairLease = acquireRepairLease(resolved);
+                if (!openPolicy.databasePath)
+                    await suspendFileWatcher(resolved);
+                if (openPolicy.repairLease !== "disabled")
+                    repairLease = acquireRepairLease(resolved);
                 const cancelBoundary = () => {
                     if (activeOperation.controller.signal.aborted)
                         throw activeOperation.controller.signal;
                 };
                 const invalidateCommittedWork = () => {
-                    if (committedWork && indexGeneration === generationBeforeRepair)
+                    if (!openPolicy.databasePath &&
+                        committedWork &&
+                        indexGeneration === generationBeforeRepair)
                         indexGeneration++;
                 };
                 emitProgress("audit", 0, "Auditing repository health");
@@ -11609,9 +12167,9 @@ export function createEngine() {
                 // Repair partial current-schema databases before normal initialization,
                 // whose reconciliation queries require these columns. ALTER preserves all
                 // healthy index_state rows; the reconciler then refreshes their snapshots.
-                const diskDbPath = resolveDbPath(resolved);
+                const diskDbPath = explicitDatabasePath(resolved, openPolicy.databasePath) ?? resolveDbPath(resolved);
                 if (fs.existsSync(diskDbPath)) {
-                    const activeDb = dbInstances.get(resolved);
+                    const activeDb = dbInstances.get(repairKey);
                     const schemaDb = activeDb ?? new Database(diskDbPath);
                     const hasIndexState = schemaDb
                         .query("SELECT COUNT(*) count FROM sqlite_master WHERE type='table' AND name='index_state'")
@@ -11636,10 +12194,11 @@ export function createEngine() {
                 // A preceding audit already established the exact repair set. Reuse an
                 // active writable handle so getOrInitDb does not run the freshness guard
                 // again and independently reconcile the same paths.
-                const db = dbInstances.get(resolved) ??
-                    (await getOrInitDb(resolved, {
+                const db = dbInstances.get(repairKey) ??
+                    (await openDb(resolved, {
                         skipContentReconciliation: true,
                         skipFreshnessGuard: true,
+                        watcher: "disabled",
                     }));
                 const schemaPrepared = before.schemaVersion !== KNODIN_SCHEMA_VERSION;
                 if (schemaPrepared)
@@ -11816,7 +12375,7 @@ export function createEngine() {
                             }
                             setMeta(db, "lastSuccessfulReconciliation", new Date().toISOString());
                             recordFreshnessBaseline(resolved, db);
-                            statusCache.delete(resolved);
+                            statusCache.delete(databaseCacheKey(resolved, openPolicy.databasePath));
                             const candidate = await engine.status(resolved, { audit: "deep" });
                             if (candidate.status === "healthy") {
                                 db.run("COMMIT;");
@@ -11824,13 +12383,13 @@ export function createEngine() {
                             }
                             else {
                                 db.run("ROLLBACK;");
-                                statusCache.delete(resolved);
+                                statusCache.delete(databaseCacheKey(resolved, openPolicy.databasePath));
                                 after = await engine.status(resolved, { audit: "deep" });
                             }
                         }
                         catch (error) {
                             db.run("ROLLBACK;");
-                            statusCache.delete(resolved);
+                            statusCache.delete(databaseCacheKey(resolved, openPolicy.databasePath));
                             throw error;
                         }
                     }
@@ -11856,7 +12415,9 @@ export function createEngine() {
             })
                 .catch(async (error) => {
                 if (error === activeOperation.controller.signal) {
-                    if (committedWork && indexGeneration === generationBeforeRepair)
+                    if (!openPolicy.databasePath &&
+                        committedWork &&
+                        indexGeneration === generationBeforeRepair)
                         indexGeneration++;
                     const after = await engine.status(resolved, { audit: "deep" });
                     const remaining = Math.max(0, repairPaths.length - completedFiles);
@@ -11882,7 +12443,7 @@ export function createEngine() {
                 throw error;
             });
             activeOperation.promise = operation;
-            repairOperations.set(resolved, activeOperation);
+            repairOperations.set(repairKey, activeOperation);
             try {
                 return await operation;
             }
@@ -11891,223 +12452,306 @@ export function createEngine() {
                 options?.signal?.removeEventListener("abort", abortShared);
                 if (options?.onProgress)
                     activeOperation.subscribers.delete(options.onProgress);
-                if (repairOperations.get(resolved) === activeOperation)
-                    repairOperations.delete(resolved);
+                if (repairOperations.get(repairKey) === activeOperation)
+                    repairOperations.delete(repairKey);
+                const activeDb = dbInstances.get(resolved);
+                if (!openPolicy.databasePath &&
+                    activeDb &&
+                    openPolicy.watcher === "enabled" &&
+                    watcherStateBefore !== "scale-limited" &&
+                    watcherStateBefore !== "resource-limited")
+                    startFileWatcher(resolved, activeDb, openPolicy.watcherFileLimit);
             }
         },
         async index(repoPath, files, clean = false, options) {
-            invalidateResolutionCaches(repoPath);
-            const indexed = [];
-            const unchanged = [];
-            let scipReport;
-            let sarifReport;
-            const progress = createIndexProgressReporter(options?.onProgress);
-            progress("starting", 0, "Opening local graph database");
-            const db = await getOrInitDb(repoPath, {
-                onProgress: progress,
-                // The explicit lifecycle operation owns all content work. Otherwise
-                // getOrInitDb's freshness guard can perform a full, invisible
-                // reconciliation before a targeted index even starts.
-                skipContentReconciliation: true,
-                skipFreshnessGuard: true,
-            });
-            let completionMessage = "Local graph is current";
-            if (files && files.length > 0) {
-                progress("indexing-files", 0, `Checking ${files.length.toLocaleString()} requested files`, {
-                    phaseTotal: files.length,
+            const resolved = path.resolve(repoPath);
+            if (clean &&
+                (!files || files.length === 0) &&
+                !openPolicy.databasePath &&
+                !process.env.VITEST &&
+                process.env.NODE_ENV !== "test") {
+                const progress = createIndexProgressReporter(options?.onProgress);
+                progress("starting", 0, "Creating isolated clean-index candidate");
+                const candidate = await engine.createCandidate(resolved);
+                let promoted = false;
+                try {
+                    const reconciliation = await engine.reconcileCandidate(candidate, resolved, undefined, {
+                        onProgress: progress,
+                        skipEmbeddings: options?.skipEmbeddings,
+                    });
+                    progress("verifying", 0, "Deep-auditing clean-index candidate", { phaseTotal: 1 });
+                    const audit = await engine.auditCandidate(candidate, { mode: "deep" });
+                    if (!audit.healthy)
+                        throw new Error(`clean-index candidate audit failed: ${audit.issues.join(", ")}`);
+                    await engine.promoteCandidate(candidate);
+                    promoted = true;
+                    const activeDb = await openDb(resolved, {
+                        skipContentReconciliation: true,
+                        skipFreshnessGuard: true,
+                        watcher: openPolicy.watcher,
+                    });
+                    if (!process.env.VITEST && process.env.NODE_ENV !== "test")
+                        publishStructuralSnapshot(resolved, activeDb);
+                    const health = await engine.status(resolved, {
+                        audit: "deep",
+                        ignoreActiveOperation: true,
+                    });
+                    const issueCount = health.missing.files.length + health.missing.records.length;
+                    progress("verifying", 1, health.status === "healthy"
+                        ? "Clean-index candidate promoted and verified"
+                        : `Promoted graph has ${issueCount.toLocaleString()} issue(s)`, { phaseTotal: 1 });
+                    progress("completed", reconciliation.reconciled.length, "Clean index completed", {
+                        phaseTotal: reconciliation.reconciled.length,
+                    });
+                    return {
+                        indexed: reconciliation.reconciled,
+                        unchanged: [],
+                        verification: {
+                            status: health.status,
+                            issueCount,
+                            missing: health.missing,
+                            verifiedAt: health.verification.verifiedAt,
+                        },
+                    };
+                }
+                catch (error) {
+                    if (!promoted && candidates.has(candidate.id))
+                        await engine.discardCandidate(candidate);
+                    if (openPolicy.watcher === "enabled" && fs.existsSync(resolveDbPath(resolved)))
+                        await openDb(resolved, {
+                            skipContentReconciliation: true,
+                            skipFreshnessGuard: true,
+                        });
+                    throw error;
+                }
+            }
+            const watcherStateBefore = watcherStates.get(resolved)?.watcher;
+            if (!openPolicy.databasePath)
+                await suspendFileWatcher(resolved);
+            try {
+                invalidateResolutionCaches(repoPath);
+                const indexed = [];
+                const unchanged = [];
+                let scipReport;
+                let sarifReport;
+                const progress = createIndexProgressReporter(options?.onProgress);
+                progress("starting", 0, "Opening local graph database");
+                const db = await openDb(repoPath, {
+                    onProgress: progress,
+                    watcher: "disabled",
+                    // The explicit lifecycle operation owns all content work. Otherwise
+                    // getOrInitDb's freshness guard can perform a full, invisible
+                    // reconciliation before a targeted index even starts.
+                    skipContentReconciliation: true,
+                    skipFreshnessGuard: true,
                 });
-                for (const [fileIndex, file] of files.entries()) {
-                    const relativePath = path.isAbsolute(file) ? path.relative(repoPath, file) : file;
-                    const absPath = path.resolve(repoPath, relativePath);
-                    const needsUpdate = clean || fileDriftedFromIndexState(db, repoPath, relativePath);
-                    if (!needsUpdate) {
-                        unchanged.push(relativePath);
-                    }
-                    else if (fs.existsSync(absPath)) {
-                        await indexFile(absPath, relativePath, repoPath, db);
-                        recordIndexState(db, repoPath, relativePath);
-                    }
-                    else {
-                        // File was deleted
-                        db.run("BEGIN TRANSACTION;");
-                        try {
-                            deleteSymbolsForFile(db, relativePath);
-                            db.run('DELETE FROM "references" WHERE callerFile = ?', [relativePath]);
-                            db.run("DELETE FROM dependencies WHERE fromFile = ?", [relativePath]);
-                            db.run("DELETE FROM mcp_tools WHERE filePath = ?", [relativePath]);
-                            db.run("COMMIT;");
+                let completionMessage = "Local graph is current";
+                if (files && files.length > 0) {
+                    progress("indexing-files", 0, `Checking ${files.length.toLocaleString()} requested files`, {
+                        phaseTotal: files.length,
+                    });
+                    for (const [fileIndex, file] of files.entries()) {
+                        const relativePath = path.isAbsolute(file) ? path.relative(repoPath, file) : file;
+                        const absPath = path.resolve(repoPath, relativePath);
+                        const needsUpdate = clean || fileDriftedFromIndexState(db, repoPath, relativePath);
+                        if (!needsUpdate) {
+                            unchanged.push(relativePath);
                         }
-                        catch (e) {
-                            db.run("ROLLBACK;");
-                            console.error(`Error deleting file from index: ${relativePath}`, e);
+                        else if (fs.existsSync(absPath)) {
+                            await indexFile(absPath, relativePath, repoPath, db);
+                            recordIndexState(db, repoPath, relativePath);
                         }
-                        removeIndexState(db, relativePath);
-                    }
-                    if (needsUpdate)
-                        indexed.push(relativePath);
-                    progress("indexing-files", fileIndex + 1, `Checking ${files.length.toLocaleString()} requested files`, { phaseTotal: files.length });
-                }
-                const refreshedFlows = await refreshFlowsForApexFiles(db, repoPath, indexed);
-                for (const flow of refreshedFlows)
-                    if (!indexed.includes(flow))
-                        indexed.push(flow);
-                if (indexed.length > 0) {
-                    progress("finalizing", 0, "Refreshing identities and semantic embeddings");
-                    persistSymbolIdentities(db, repoPath, indexed);
-                    reconcileTypeScriptDi(db, repoPath);
-                    await indexEmbeddings(db, repoPath, progress);
-                    indexGeneration++;
-                }
-                const alreadyCurrent = unchanged.length === 1
-                    ? "1 requested file already current"
-                    : `${unchanged.length.toLocaleString()} requested files already current`;
-                completionMessage =
-                    indexed.length === 0
-                        ? alreadyCurrent
-                        : `Indexed ${indexed.length.toLocaleString()} requested file(s); ${alreadyCurrent}`;
-            }
-            else {
-                // Full re-index or incremental sync
-                let hasSymbols = false;
-                try {
-                    const countResult = db
-                        .query("SELECT COUNT(*) as count FROM symbols")
-                        .all();
-                    if (countResult && countResult.length > 0 && countResult[0].count > 0) {
-                        hasSymbols = true;
+                        else {
+                            // File was deleted
+                            db.run("BEGIN TRANSACTION;");
+                            try {
+                                deleteSymbolsForFile(db, relativePath);
+                                db.run('DELETE FROM "references" WHERE callerFile = ?', [relativePath]);
+                                db.run("DELETE FROM dependencies WHERE fromFile = ?", [relativePath]);
+                                db.run("DELETE FROM mcp_tools WHERE filePath = ?", [relativePath]);
+                                db.run("COMMIT;");
+                            }
+                            catch (e) {
+                                db.run("ROLLBACK;");
+                                console.error(`Error deleting file from index: ${relativePath}`, e);
+                            }
+                            removeIndexState(db, relativePath);
+                        }
+                        if (needsUpdate)
+                            indexed.push(relativePath);
+                        progress("indexing-files", fileIndex + 1, `Checking ${files.length.toLocaleString()} requested files`, { phaseTotal: files.length });
+                    }
+                    const refreshedFlows = await refreshFlowsForApexFiles(db, repoPath, indexed);
+                    for (const flow of refreshedFlows)
+                        if (!indexed.includes(flow))
+                            indexed.push(flow);
+                    if (indexed.length > 0) {
+                        progress("finalizing", 0, "Refreshing identities and semantic embeddings");
+                        persistSymbolIdentities(db, repoPath, indexed);
+                        reconcileTypeScriptDi(db, repoPath);
+                        await indexEmbeddings(db, repoPath, progress);
+                        indexGeneration++;
                     }
-                }
-                catch (_) { }
-                if (!clean && hasSymbols) {
-                    progress("collecting-files", 0, "Checking existing local graph for changes");
-                    await reconcileIndex(repoPath, db, progress);
+                    const alreadyCurrent = unchanged.length === 1
+                        ? "1 requested file already current"
+                        : `${unchanged.length.toLocaleString()} requested files already current`;
+                    completionMessage =
+                        indexed.length === 0
+                            ? alreadyCurrent
+                            : `Indexed ${indexed.length.toLocaleString()} requested file(s); ${alreadyCurrent}`;
                 }
                 else {
-                    await indexRepo(repoPath, db, progress, options?.skipEmbeddings === true);
-                }
-                // Reuse the same candidate set as indexing/reconciliation. This keeps
-                // LWC HTML/CSS bundle members visible in the response without admitting
-                // arbitrary web assets to the source index.
-                // Appended in a loop, not `push(...files)`: spreading an array as
-                // arguments overflows the call stack once a repository is large
-                // enough. Observed on a 40k-file checkout, which is well within the
-                // range knodin is meant to index.
-                for (const file of collectRepoFiles(repoPath))
-                    indexed.push(file);
-                completionMessage = `${indexed.length.toLocaleString()} repository file(s) are current`;
-            }
-            if (options?.scip) {
-                const facts = readScipIndex(repoPath, options.scip);
-                const affectedFiles = persistScipFacts(db, repoPath, facts);
-                progress("finalizing", 0, "Refreshing SCIP identities and semantic embeddings");
-                await indexEmbeddings(db, repoPath, progress);
-                indexGeneration++;
-                const bounds = { ...SCIP_DEFAULT_LIMITS, ...options.scip };
-                scipReport = {
-                    provenance: "scip",
-                    inputPath: facts.inputPath,
-                    bytes: facts.bytes,
-                    files: facts.files,
-                    facts: facts.facts,
-                    languages: facts.languages,
-                    indexers: facts.indexers,
-                    elapsedMs: facts.elapsedMs,
-                    bounds: {
-                        maxBytes: bounds.maxBytes,
-                        maxFiles: bounds.maxFiles,
-                        maxFacts: bounds.maxFacts,
-                        timeoutMs: bounds.timeoutMs,
-                    },
-                };
-                for (const file of affectedFiles)
-                    if (!indexed.includes(file))
+                    // Full re-index or incremental sync
+                    let hasSymbols = false;
+                    try {
+                        const countResult = db
+                            .query("SELECT COUNT(*) as count FROM symbols")
+                            .all();
+                        if (countResult && countResult.length > 0 && countResult[0].count > 0) {
+                            hasSymbols = true;
+                        }
+                    }
+                    catch (_) { }
+                    if (!clean && hasSymbols) {
+                        progress("collecting-files", 0, "Checking existing local graph for changes");
+                        await reconcileIndex(repoPath, db, progress);
+                    }
+                    else {
+                        await indexRepo(repoPath, db, progress, options?.skipEmbeddings === true);
+                    }
+                    // Reuse the same candidate set as indexing/reconciliation. This keeps
+                    // LWC HTML/CSS bundle members visible in the response without admitting
+                    // arbitrary web assets to the source index.
+                    // Appended in a loop, not `push(...files)`: spreading an array as
+                    // arguments overflows the call stack once a repository is large
+                    // enough. Observed on a 40k-file checkout, which is well within the
+                    // range knodin is meant to index.
+                    for (const file of collectRepoFiles(repoPath))
                         indexed.push(file);
-            }
-            if (options?.sarif) {
-                const facts = readSarifLog(repoPath, options.sarif);
-                persistSarifFindings(db, facts);
-                // Findings are not graph facts, so no re-embedding and no generation
-                // bump: the graph is unchanged and existing answers stay valid.
-                const bounds = { ...SARIF_DEFAULT_LIMITS, ...options.sarif };
-                sarifReport = {
-                    provenance: "sarif",
-                    inputPath: facts.inputPath,
-                    bytes: facts.bytes,
-                    tools: facts.tools,
-                    rules: facts.rules,
-                    files: facts.files,
-                    findings: facts.findings.length,
-                    skippedUnresolved: facts.skippedUnresolved,
-                    elapsedMs: facts.elapsedMs,
-                    bounds: {
-                        maxBytes: bounds.maxBytes,
-                        maxFindings: bounds.maxFindings,
-                        timeoutMs: bounds.timeoutMs,
-                    },
-                };
-            }
-            progress("verifying", 0, "Verifying local graph health", {
-                phaseTotal: 1,
-            });
-            let health = await engine.status(repoPath, {
-                audit: "deep",
-                ignoreActiveOperation: true,
-            });
-            const contentVerified = health.coverage.sourceFiles === health.coverage.indexedFiles &&
-                health.missing.files.length === 0 &&
-                health.missing.records.length === 0 &&
-                Object.values(health.orphaned).every((count) => count === 0);
-            if (contentVerified &&
-                (health.freshness.state === "stale-head" || health.freshness.state === "unknown")) {
-                setMeta(db, "lastIndexedHead", gitHead(repoPath) ?? "");
-                setMeta(db, "lastSuccessfulReconciliation", new Date().toISOString());
-                recordFreshnessBaseline(repoPath, db);
-                statusCache.delete(path.resolve(repoPath));
-                health = await engine.status(repoPath, {
+                    completionMessage = `${indexed.length.toLocaleString()} repository file(s) are current`;
+                }
+                if (options?.scip) {
+                    const facts = readScipIndex(repoPath, options.scip);
+                    const affectedFiles = persistScipFacts(db, repoPath, facts);
+                    progress("finalizing", 0, "Refreshing SCIP identities and semantic embeddings");
+                    await indexEmbeddings(db, repoPath, progress);
+                    indexGeneration++;
+                    const bounds = { ...SCIP_DEFAULT_LIMITS, ...options.scip };
+                    scipReport = {
+                        provenance: "scip",
+                        inputPath: facts.inputPath,
+                        bytes: facts.bytes,
+                        files: facts.files,
+                        facts: facts.facts,
+                        languages: facts.languages,
+                        indexers: facts.indexers,
+                        elapsedMs: facts.elapsedMs,
+                        bounds: {
+                            maxBytes: bounds.maxBytes,
+                            maxFiles: bounds.maxFiles,
+                            maxFacts: bounds.maxFacts,
+                            timeoutMs: bounds.timeoutMs,
+                        },
+                    };
+                    for (const file of affectedFiles)
+                        if (!indexed.includes(file))
+                            indexed.push(file);
+                }
+                if (options?.sarif) {
+                    const facts = readSarifLog(repoPath, options.sarif);
+                    persistSarifFindings(db, facts);
+                    // Findings are not graph facts, so no re-embedding and no generation
+                    // bump: the graph is unchanged and existing answers stay valid.
+                    const bounds = { ...SARIF_DEFAULT_LIMITS, ...options.sarif };
+                    sarifReport = {
+                        provenance: "sarif",
+                        inputPath: facts.inputPath,
+                        bytes: facts.bytes,
+                        tools: facts.tools,
+                        rules: facts.rules,
+                        files: facts.files,
+                        findings: facts.findings.length,
+                        skippedUnresolved: facts.skippedUnresolved,
+                        elapsedMs: facts.elapsedMs,
+                        bounds: {
+                            maxBytes: bounds.maxBytes,
+                            maxFindings: bounds.maxFindings,
+                            timeoutMs: bounds.timeoutMs,
+                        },
+                    };
+                }
+                progress("verifying", 0, "Verifying local graph health", {
+                    phaseTotal: 1,
+                });
+                let health = await engine.status(repoPath, {
                     audit: "deep",
                     ignoreActiveOperation: true,
                 });
-            }
-            // The postcondition belongs to this index result. Do not turn the next
-            // explicit `status` call into a cache hit against an internal audit.
-            statusCache.delete(path.resolve(repoPath));
-            const issueCount = health.missing.files.length + health.missing.records.length;
-            if (health.status === "healthy") {
-                // Explicit indexing counts as a successful reconciliation only after
-                // the audit proves that no requested or unrequested drift remains.
-                if (files && files.length > 0) {
+                const contentVerified = health.coverage.sourceFiles === health.coverage.indexedFiles &&
+                    health.missing.files.length === 0 &&
+                    health.missing.records.length === 0 &&
+                    Object.values(health.orphaned).every((count) => count === 0);
+                if (contentVerified &&
+                    (health.freshness.state === "stale-head" || health.freshness.state === "unknown")) {
                     setMeta(db, "lastIndexedHead", gitHead(repoPath) ?? "");
                     setMeta(db, "lastSuccessfulReconciliation", new Date().toISOString());
                     recordFreshnessBaseline(repoPath, db);
+                    statusCache.delete(databaseCacheKey(repoPath, openPolicy.databasePath));
+                    health = await engine.status(repoPath, {
+                        audit: "deep",
+                        ignoreActiveOperation: true,
+                    });
                 }
-                noteFreshness(repoPath, "fresh");
-                // Test engines use an in-memory graph and must not create untracked
-                // repository artifacts that pollute Git-diff/review fixtures.
-                if (!process.env.VITEST && process.env.NODE_ENV !== "test")
-                    publishStructuralSnapshot(repoPath, db);
+                // The postcondition belongs to this index result. Do not turn the next
+                // explicit `status` call into a cache hit against an internal audit.
+                statusCache.delete(databaseCacheKey(repoPath, openPolicy.databasePath));
+                const issueCount = health.missing.files.length + health.missing.records.length;
+                if (health.status === "healthy") {
+                    // Explicit indexing counts as a successful reconciliation only after
+                    // the audit proves that no requested or unrequested drift remains.
+                    if (files && files.length > 0) {
+                        setMeta(db, "lastIndexedHead", gitHead(repoPath) ?? "");
+                        setMeta(db, "lastSuccessfulReconciliation", new Date().toISOString());
+                        recordFreshnessBaseline(repoPath, db);
+                    }
+                    noteFreshness(repoPath, "fresh");
+                    // Test engines use an in-memory graph and must not create untracked
+                    // repository artifacts that pollute Git-diff/review fixtures.
+                    if (!process.env.VITEST && process.env.NODE_ENV !== "test")
+                        publishStructuralSnapshot(repoPath, db);
+                }
+                else {
+                    freshnessProbes.delete(path.resolve(repoPath));
+                }
+                progress("verifying", 1, health.status === "healthy"
+                    ? "Local graph health verified"
+                    : `Local graph still has ${issueCount.toLocaleString()} issue(s)`, { phaseTotal: 1 });
+                const completed = files?.length ?? indexed.length;
+                progress("completed", completed, health.status === "healthy"
+                    ? completionMessage
+                    : `${completionMessage}; verification found ${issueCount.toLocaleString()} issue(s)`, { phaseTotal: completed });
+                return {
+                    indexed,
+                    unchanged,
+                    scip: scipReport,
+                    sarif: sarifReport,
+                    verification: {
+                        status: health.status,
+                        issueCount,
+                        missing: health.missing,
+                        verifiedAt: health.verification.verifiedAt,
+                    },
+                };
+            }
+            finally {
+                const activeDb = dbInstances.get(resolved);
+                if (!openPolicy.databasePath &&
+                    activeDb &&
+                    openPolicy.watcher === "enabled" &&
+                    watcherStateBefore !== "scale-limited" &&
+                    watcherStateBefore !== "resource-limited")
+                    startFileWatcher(resolved, activeDb, openPolicy.watcherFileLimit);
             }
-            else {
-                freshnessProbes.delete(path.resolve(repoPath));
-            }
-            progress("verifying", 1, health.status === "healthy"
-                ? "Local graph health verified"
-                : `Local graph still has ${issueCount.toLocaleString()} issue(s)`, { phaseTotal: 1 });
-            const completed = files?.length ?? indexed.length;
-            progress("completed", completed, health.status === "healthy"
-                ? completionMessage
-                : `${completionMessage}; verification found ${issueCount.toLocaleString()} issue(s)`, { phaseTotal: completed });
-            return {
-                indexed,
-                unchanged,
-                scip: scipReport,
-                sarif: sarifReport,
-                verification: {
-                    status: health.status,
-                    issueCount,
-                    missing: health.missing,
-                    verifiedAt: health.verification.verifiedAt,
-                },
-            };
         },
         async search(query, repoPath, limit, options = {}) {
             const resolvedRepoPath = path.resolve(repoPath);
@@ -12117,7 +12761,7 @@ export function createEngine() {
             if (options.testScope && !["all", "test", "production"].includes(options.testScope))
                 throw new Error("knodin search: invalid testScope");
             const repos = options.federate === false ? [resolvedRepoPath] : await getFederatedRepos(repoPath);
-            const allRepos = await Promise.all(repos.map(async (r) => ({ path: r, db: await getOrInitDb(r) })));
+            const allRepos = await Promise.all(repos.map(async (r) => ({ path: r, db: await openDb(r) })));
             // Computed before any retrieval route runs, so every exit path can report
             // it: a short result list caused by missing embeddings must not be
             // indistinguishable from a short list caused by the query.
@@ -12569,8 +13213,21 @@ export function createEngine() {
                 pattern === "lsp_implementations") {
                 return await runReadOnlyLspQuery(pattern, target, path.resolve(repoPath));
             }
+            if (pattern === "file_metrics") {
+                const fileMetrics = collectFileMetrics(path.resolve(repoPath), {
+                    base: options.base,
+                    testScope: options.testScope,
+                });
+                return {
+                    pattern,
+                    target: "",
+                    count: fileMetrics.files.length,
+                    results: [],
+                    fileMetrics,
+                };
+            }
             const repos = await getFederatedRepos(repoPath);
-            const allRepos = await Promise.all(repos.map(async (r) => ({ path: r, db: await getOrInitDb(r) })));
+            const allRepos = await Promise.all(repos.map(async (r) => ({ path: r, db: await openDb(r) })));
             const resolvedRepoPath = path.resolve(repoPath);
             const formatPath = makePathFormatter(resolvedRepoPath);
             const primary = allRepos.find((r) => r.path === repoPath || r.path === resolvedRepoPath) ?? allRepos[0];
@@ -14760,7 +15417,7 @@ export function createEngine() {
             }
         },
         async rename(oldName, newName, repoPath, apply = false, verify = true, selector = {}) {
-            const db = await getOrInitDb(repoPath);
+            const db = await openDb(repoPath);
             const resolvedRepoPath = path.resolve(repoPath);
             const resolution = resolveSymbolRows(db, resolvedRepoPath, oldName, selector);
             if (resolution.ambiguity)
@@ -15069,26 +15726,37 @@ export function createEngine() {
                     db.close();
                 dbInstances.delete(repo);
                 initPromises.delete(repo);
+                watcherStates.delete(repo);
+            }
+            for (const key of explicitDatabaseKeys) {
+                const db = dbInstances.get(key);
+                if (db)
+                    db.close();
+                dbInstances.delete(key);
+                initPromises.delete(key);
+                statusCache.delete(key);
+            }
+            if (repositoryEngineOwners.size === 0) {
+                freshnessProbes.clear();
+                mapCache.clear();
+                minimalMapCache.clear();
+                graphAnalyticsCache.clear();
+                architectureMetadataCache.clear();
+                architectureOverviewCache.clear();
+                traversalSnapshotCache.clear();
+                statusCache.clear();
+                flowsCache.clear();
+                fileToFlowLookupCache.clear();
+                clearGitHistorySignalCache();
+                annIndexCache.clear();
+                searchMetadataCache.clear();
+                searchCommunityLookupCache.clear();
+                resourceCorpusCache.clear();
+                resourceReachabilityCache.clear();
+                packageMapCache.clear();
+                reExportCache.clear();
             }
-            freshnessProbes.clear();
-            mapCache.clear();
-            minimalMapCache.clear();
-            graphAnalyticsCache.clear();
-            architectureMetadataCache.clear();
-            architectureOverviewCache.clear();
-            traversalSnapshotCache.clear();
-            statusCache.clear();
-            flowsCache.clear();
-            fileToFlowLookupCache.clear();
-            clearGitHistorySignalCache();
-            annIndexCache.clear();
-            searchMetadataCache.clear();
-            searchCommunityLookupCache.clear();
-            resourceCorpusCache.clear();
-            resourceReachabilityCache.clear();
-            packageMapCache.clear();
-            reExportCache.clear();
         },
     };
-    return withStaleness(engine, claimRepository);
+    return withStaleness(engine, claimRepository, openDb, openPolicy);
 }