knodin 0.8.4 → 0.8.6

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",
@@ -544,6 +547,20 @@ function persistSymbolIdentities(db, repoPath, filePaths) {
         throw error;
     }
 }
+/** Repair-only cancellable identity pass, bounded to one source file per transaction. */
+async function persistSymbolIdentitiesCancellable(db, repoPath, filePaths, signal) {
+    const scope = filePaths === undefined
+        ? db
+            .query("SELECT DISTINCT filePath FROM symbols ORDER BY filePath")
+            .all()
+            .map((row) => row.filePath)
+        : (scopedFilePaths(filePaths) ?? []);
+    for (const file of scope) {
+        throwIfAborted(signal);
+        persistSymbolIdentities(db, repoPath, [file]);
+        await yieldToIndexEventLoop();
+    }
+}
 /** Bind name/file reference rows to exact definitions after identities exist. */
 function persistReferenceEndpoints(db, filePaths) {
     const refs = referencesForFiles(db, filePaths);
@@ -661,7 +678,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 +758,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();
@@ -843,18 +905,127 @@ function getGraphAnalyticsSnapshot(allRepos, resolvedRepoPath, topN = 15, relati
 const statusCache = new Map();
 const repairOperations = new Map();
 const STATUS_CACHE_LIMIT = 16;
-function databaseFileFingerprint(databasePath) {
-    return [databasePath, `${databasePath}-wal`]
+export const ADAPTIVE_STATUS_FILE_THRESHOLD = 50_000;
+const PERSISTED_AUDIT_VERSION = 1;
+export function adaptiveStatusStrategy(indexedFiles) {
+    const testThreshold = process.env.KNODIN_TEST_ADAPTIVE_STATUS_THRESHOLD !== undefined
+        ? Number(process.env.KNODIN_TEST_ADAPTIVE_STATUS_THRESHOLD)
+        : ADAPTIVE_STATUS_FILE_THRESHOLD;
+    return indexedFiles <= testThreshold ? "deep" : "persisted";
+}
+function throwIfAborted(signal) {
+    if (!signal?.aborted)
+        return;
+    throw signal.reason instanceof Error
+        ? signal.reason
+        : new DOMException("The operation was aborted", "AbortError");
+}
+function wasAborted(error, signal) {
+    return (signal.aborted &&
+        (error === signal.reason || (error instanceof Error && error.name === "AbortError")));
+}
+function canonicalRepository(repoPath) {
+    try {
+        return fs.realpathSync.native(repoPath);
+    }
+    catch {
+        return path.resolve(repoPath);
+    }
+}
+function persistedStatusAuditPath(databasePath) {
+    return path.join(path.dirname(databasePath), "status-audit-v1.json");
+}
+function readPersistedStatusAudit(repoPath, databasePath, databaseFingerprint, schemaVersion) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(persistedStatusAuditPath(databasePath), "utf8"));
+        if (parsed.format !== PERSISTED_AUDIT_VERSION ||
+            parsed.repository !== canonicalRepository(repoPath) ||
+            parsed.schemaVersion !== schemaVersion ||
+            parsed.knodinVersion !== KNODIN_VERSION ||
+            parsed.databaseFingerprint !== databaseFingerprint ||
+            parsed.result?.status !== "healthy" ||
+            parsed.result?.verification?.mode !== "deep-audit" ||
+            parsed.auditVerifiedAt !== parsed.result.verification.verifiedAt)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function writePersistedStatusAudit(repoPath, databasePath, databaseFingerprint, result) {
+    if (result.status !== "healthy" || result.verification.mode !== "deep-audit")
+        return;
+    const target = persistedStatusAuditPath(databasePath);
+    const temporary = `${target}.${process.pid}.${crypto.randomUUID()}.tmp`;
+    const snapshot = {
+        format: PERSISTED_AUDIT_VERSION,
+        repository: canonicalRepository(repoPath),
+        schemaVersion: result.schemaVersion,
+        knodinVersion: KNODIN_VERSION,
+        databaseFingerprint,
+        auditVerifiedAt: result.verification.verifiedAt,
+        result: structuredClone(result),
+    };
+    try {
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(temporary, `${JSON.stringify(snapshot)}\n`, { mode: 0o600, flag: "wx" });
+        fs.renameSync(temporary, target);
+    }
+    finally {
+        fs.rmSync(temporary, { force: true });
+    }
+}
+function databaseFileFingerprint(databasePath, db) {
+    const files = [databasePath, `${databasePath}-wal`]
         .map((file) => {
         try {
             const stat = fs.statSync(file);
-            return `${stat.size}:${stat.mtimeMs}`;
+            if (file.endsWith("-wal") && stat.size === 0)
+                return "missing";
+            const descriptor = fs.openSync(file, "r");
+            try {
+                const header = Buffer.alloc(Math.min(100, stat.size));
+                fs.readSync(descriptor, header, 0, header.length, 0);
+                // SQLite rewrites volatile header counters during a clean close even
+                // when graph contents are unchanged. Logical DB evidence below binds
+                // mutations without making process shutdown invalidate the snapshot.
+                if (!file.endsWith("-wal") && header.length >= 40)
+                    header.fill(0, 24, 40);
+                return `${stat.size}:${crypto.createHash("sha256").update(header).digest("hex")}`;
+            }
+            finally {
+                fs.closeSync(descriptor);
+            }
         }
         catch {
             return "missing";
         }
     })
         .join("|");
+    if (!db)
+        return files;
+    try {
+        const counts = ["symbols", "references", "dependencies", "symbol_embeddings", "index_state"]
+            .map((table) => db.query(`SELECT COUNT(*) count FROM "${table}"`).get()?.count ??
+            0)
+            .join(":");
+        const state = db
+            .query("SELECT COUNT(*) count, COALESCE(SUM(mtimeMs),0) mtimes, COALESCE(SUM(size),0) sizes FROM index_state")
+            .get();
+        const meta = db
+            .query("SELECT key, value FROM meta ORDER BY key")
+            .all()
+            .map((row) => `${row.key}=${row.value}`)
+            .join("\0");
+        return `${files}|${crypto
+            .createHash("sha256")
+            .update(`${counts}|${state?.count}:${state?.mtimes}:${state?.sizes}|${meta}`)
+            .digest("hex")}`;
+    }
+    catch {
+        return files;
+    }
 }
 const traversalSnapshotCache = new Map();
 const TRAVERSAL_SNAPSHOT_CACHE_LIMIT = 8;
@@ -6516,9 +6687,10 @@ async function embedPreparedBatch(items, onModelProgress) {
     }
 }
 /** Incrementally generates and saves embeddings for symbols that lack them. */
-async function indexEmbeddings(db, repoPath, progress) {
+async function indexEmbeddings(db, repoPath, progress, signal) {
     return measurePerfPhase("embedding_inference_write", async () => {
         try {
+            throwIfAborted(signal);
             const missingStmt = db.query(`
 			SELECT id, name, kind, filePath, startLine, endLine, summary
 			FROM symbols
@@ -6560,6 +6732,7 @@ async function indexEmbeddings(db, repoPath, progress) {
             const sourceForEmbedding = createEmbeddingSourceReader(repoPath);
             let lastYieldAt = Date.now();
             for (let offset = 0; offset < missing.length; offset += batchSize) {
+                throwIfAborted(signal);
                 const prepared = missing.slice(offset, offset + batchSize).map((sym) => {
                     const source = sourceForEmbedding(sym.filePath, sym.startLine, sym.endLine);
                     return {
@@ -6568,6 +6741,7 @@ async function indexEmbeddings(db, repoPath, progress) {
                     };
                 });
                 const generated = await embedPreparedBatch(prepared, onModelProgress);
+                throwIfAborted(signal);
                 db.run("BEGIN TRANSACTION;");
                 try {
                     for (const { symbol, embedding: embeddingVec } of generated) {
@@ -6590,6 +6764,7 @@ async function indexEmbeddings(db, repoPath, progress) {
             insertEmbedding.finalize();
         }
         catch (error) {
+            throwIfAborted(signal);
             console.error("Error during indexEmbeddings:", error);
         }
     });
@@ -6766,6 +6941,63 @@ function gitTrackedCandidates(repoPath) {
         return null;
     }
 }
+async function execGitAbortable(repoPath, args, signal) {
+    throwIfAborted(signal);
+    return await new Promise((resolve, reject) => {
+        child_process.execFile("git", args, {
+            cwd: repoPath,
+            encoding: "utf8",
+            maxBuffer: 64 * 1024 * 1024,
+            signal,
+        }, (error, stdout) => error
+            ? reject(error instanceof Error
+                ? error
+                : new Error(typeof error === "string" ? error : "Git subprocess failed"))
+            : resolve(stdout));
+    });
+}
+async function collectRepoFilesWithCoverageAbortable(repoPath, signal) {
+    let candidates = null;
+    try {
+        const gitRoot = (await execGitAbortable(repoPath, ["rev-parse", "--show-toplevel"], signal)).trim();
+        if (gitRoot && isSameDir(gitRoot, repoPath)) {
+            candidates = splitNulPaths(await execGitAbortable(repoPath, ["ls-files", "-z", "--cached", "--others", "--exclude-standard"], signal));
+        }
+    }
+    catch {
+        throwIfAborted(signal);
+    }
+    const files = [];
+    const skippedByExtension = new Map();
+    const source = candidates ?? walkRepoFiles(repoPath);
+    for (let index = 0; index < source.length; index++) {
+        if (index % 256 === 0) {
+            throwIfAborted(signal);
+            await yieldToIndexEventLoop();
+        }
+        const file = source[index];
+        if (candidates) {
+            try {
+                if (!fs.statSync(path.join(repoPath, file)).isFile())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+        }
+        if (!isIndexablePath(file))
+            continue;
+        if (!isIndexableSourcePath(file)) {
+            tallyOne(skippedByExtension, extensionBucket(file));
+            continue;
+        }
+        if (!file.endsWith(".json") || isIndexableJsonCandidate(file, repoPath))
+            files.push(file);
+        else
+            tallyOne(skippedByExtension, ".json");
+    }
+    return { files: files.sort(compareBytes), skippedByExtension };
+}
 /**
  * Enumerate the repo-relative files knodin indexes: source files plus dbt
  * `manifest.json` files and Dockerfiles. Shared by the full index and the
@@ -6871,8 +7103,8 @@ function freshnessFingerprint(value) {
         return null;
     return crypto.createHash("sha256").update(value).digest("hex");
 }
-function buildFreshnessEnvelope(repoPath, db, verifiedAt, stateOverride) {
-    const git = gitWorkTreeProbe(repoPath);
+function buildFreshnessEnvelope(repoPath, db, verifiedAt, stateOverride, gitProbe) {
+    const git = gitProbe === undefined ? gitWorkTreeProbe(repoPath) : gitProbe;
     const currentHead = git && isSameDir(git.root, repoPath) ? git.head || null : gitHead(repoPath);
     const indexedHead = db ? getMeta(db, "lastIndexedHead") || null : null;
     const relation = commitRelation(repoPath, indexedHead, currentHead);
@@ -7288,7 +7520,7 @@ function gitWorkTreeProbe(repoPath) {
         // Porcelain: `XY <path>` (or `XY <orig> -> <new>` for renames).
         for (const part of line.slice(3).split(" -> ")) {
             const p = part.trim().replace(/^"|"$/g, "");
-            if (p)
+            if (p && isIndexablePath(p))
                 dirty.push(p);
         }
     }
@@ -7322,7 +7554,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
@@ -7355,8 +7587,8 @@ function recordFreshnessBaseline(repoPath, db) {
  * pretending. A brand-new file in a non-git repo is consequently picked up by
  * the watcher or a cold start, not by this probe.
  */
-function probeDrift(repoPath, db) {
-    const git = gitWorkTreeProbe(repoPath);
+function probeDrift(repoPath, db, gitProbe) {
+    const git = gitProbe === undefined ? gitWorkTreeProbe(repoPath) : gitProbe;
     if (git && isSameDir(git.root, repoPath)) {
         if ((getMeta(db, "lastIndexedHead") ?? "") !== git.head) {
             return { drifted: true, verifiable: true };
@@ -7462,7 +7694,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 +7740,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 +7874,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 +8337,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)
@@ -8892,7 +9209,7 @@ function reviewChangedFiles(base, repoPath, options, modified) {
             args.push(safeReviewRevision(base || "HEAD"));
         args.push("--");
         for (const file of runGit(repoPath, args).split("\0")) {
-            if (file)
+            if (file && isIndexablePath(file))
                 files.add(file);
         }
     }
@@ -8909,7 +9226,7 @@ function reviewChangedFiles(base, repoPath, options, modified) {
                 "--exclude-standard",
                 "-z",
             ]).split("\0")) {
-                if (file)
+                if (file && isIndexablePath(file))
                     files.add(file);
             }
         }
@@ -10222,8 +10539,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 +10601,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 +10633,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 +10673,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 +10701,395 @@ 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",
+                signal: activeOperation.controller.signal,
+            });
+            await suspendFileWatcher(resolved);
+            const activePath = resolveDbPath(resolved);
+            if (fs.existsSync(activePath)) {
+                candidate = await engine.createCandidate(resolved, { empty: true });
+                const existing = dbInstances.get(resolved);
+                const active = existing ?? new Database(activePath, { readonly: true });
+                try {
+                    // VACUUM INTO reads a transactionally consistent image, including WAL
+                    // pages, without checkpointing or rewriting the active graph.
+                    const destination = candidate.databasePath.replaceAll("'", "''");
+                    active.run(`VACUUM INTO '${destination}'`);
+                }
+                finally {
+                    if (!existing)
+                        active.close();
+                }
+            }
+            else {
+                candidate = await engine.createCandidate(resolved);
+            }
+            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 = staged.cancelled
+                    ? before
+                    : 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 +11254,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 +11451,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 +11499,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 +11582,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 +11844,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();
@@ -11157,11 +11893,13 @@ export function createEngine() {
         },
         async status(repoPath, options = {}) {
             const resolved = path.resolve(repoPath);
+            throwIfAborted(options.signal);
             // 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 +11960,7 @@ export function createEngine() {
                     verification: { mode: "live-operation", verifiedAt },
                     repairSteps: [],
                     activity,
+                    freshnessMechanism: freshnessMechanismFor(resolved, openPolicy),
                 };
             }
             if (!db) {
@@ -11253,15 +11992,56 @@ 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.",
                     ],
                 };
             }
-            const databaseFingerprint = databaseFileFingerprint(diskDbPath);
-            const cached = statusCache.get(resolved);
-            if (options.audit !== "deep" &&
+            const databaseFingerprint = databaseFileFingerprint(diskDbPath, db);
+            let effectiveAudit = options.audit ?? "cached";
+            if (effectiveAudit === "adaptive") {
+                let indexedFileCount = 0;
+                try {
+                    indexedFileCount =
+                        db.query("SELECT COUNT(*) count FROM index_state").get()
+                            ?.count ?? 0;
+                }
+                catch {
+                    // A malformed schema needs the existing deep diagnostic path.
+                }
+                if (adaptiveStatusStrategy(indexedFileCount) === "deep") {
+                    effectiveAudit = "deep";
+                }
+                else {
+                    const schemaVersion = db.query("PRAGMA user_version").get()?.user_version ?? 0;
+                    const persisted = readPersistedStatusAudit(resolved, diskDbPath, databaseFingerprint, schemaVersion);
+                    if (persisted) {
+                        throwIfAborted(options.signal);
+                        const gitProbe = measurePerfPhaseSync("freshness_probe", () => gitWorkTreeProbe(resolved));
+                        const drift = probeDrift(resolved, db, gitProbe);
+                        const probeVerifiedAt = new Date().toISOString();
+                        const freshness = buildFreshnessEnvelope(resolved, db, probeVerifiedAt, drift.verifiable ? (drift.drifted ? "stale-working-tree" : undefined) : "unknown", gitProbe);
+                        if (!activeDb)
+                            db.close();
+                        const cachedResult = structuredClone(persisted.result);
+                        return {
+                            ...cachedResult,
+                            status: drift.verifiable && !drift.drifted ? "healthy" : "stale",
+                            freshness,
+                            verification: {
+                                mode: "persisted-audit",
+                                auditVerifiedAt: persisted.auditVerifiedAt,
+                                verifiedAt: probeVerifiedAt,
+                            },
+                        };
+                    }
+                    effectiveAudit = "deep";
+                }
+            }
+            const cached = statusCache.get(statusCacheKey);
+            if (effectiveAudit !== "deep" &&
                 cached?.generation === indexGeneration &&
                 cached.databaseFingerprint === databaseFingerprint) {
                 const auditVerifiedAt = Date.parse(cached.result.verification.verifiedAt);
@@ -11287,6 +12067,8 @@ export function createEngine() {
                             ...cachedResult,
                             verification: {
                                 mode: "cached-after-freshness-probe",
+                                auditVerifiedAt: cached.result.verification.auditVerifiedAt ??
+                                    cached.result.verification.verifiedAt,
                                 verifiedAt: new Date(lease.at).toISOString(),
                             },
                         };
@@ -11301,6 +12083,8 @@ export function createEngine() {
                             ...cachedResult,
                             verification: {
                                 mode: "cached-after-freshness-probe",
+                                auditVerifiedAt: cached.result.verification.auditVerifiedAt ??
+                                    cached.result.verification.verifiedAt,
                                 verifiedAt,
                             },
                         };
@@ -11311,7 +12095,11 @@ export function createEngine() {
                     // reports repair steps instead of hiding the database problem.
                 }
             }
-            const collected = measurePerfPhaseSync("status_audit", () => collectRepoFilesWithCoverage(resolved));
+            throwIfAborted(options.signal);
+            const collected = options.signal
+                ? await measurePerfPhase("status_audit", () => collectRepoFilesWithCoverageAbortable(resolved, options.signal))
+                : measurePerfPhaseSync("status_audit", () => collectRepoFilesWithCoverage(resolved));
+            throwIfAborted(options.signal);
             const sourceFiles = collected.files;
             const coverageSkips = buildCoverageSkips(collected.skippedByExtension, db);
             const schemaVersion = db.query("PRAGMA user_version").get()?.user_version ?? 0;
@@ -11373,6 +12161,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.",
@@ -11394,25 +12183,29 @@ export function createEngine() {
                 .all()
                 .map((r) => r.filePath));
             const missingFiles = sourceFiles.filter((file) => !indexed.has(file));
-            const staleFiles = indexedRows
-                .map((row) => row.filePath)
-                .filter((file) => !sourceFileSet.has(file) && !fs.existsSync(path.join(resolved, file)));
-            const ineligibleFiles = indexedRows
-                .map((row) => row.filePath)
-                .filter((file) => !sourceFileSet.has(file) && fs.existsSync(path.join(resolved, file)));
-            const damagedFiles = indexedRows
-                .filter((row) => {
-                if (!sourceFileSet.has(row.filePath))
-                    return false;
+            const staleFiles = [];
+            const ineligibleFiles = [];
+            const damagedFiles = [];
+            for (let index = 0; index < indexedRows.length; index++) {
+                if (options.signal && index % 256 === 0) {
+                    throwIfAborted(options.signal);
+                    await yieldToIndexEventLoop();
+                }
+                const row = indexedRows[index];
+                const exists = fs.existsSync(path.join(resolved, row.filePath));
+                if (!sourceFileSet.has(row.filePath)) {
+                    (exists ? ineligibleFiles : staleFiles).push(row.filePath);
+                    continue;
+                }
                 try {
                     const stat = fs.statSync(path.join(resolved, row.filePath));
-                    return stat.size !== row.size || Math.abs(stat.mtimeMs - row.mtimeMs) >= 1;
+                    if (stat.size !== row.size || stat.mtimeMs !== row.mtimeMs)
+                        damagedFiles.push(row.filePath);
                 }
                 catch {
-                    return false;
+                    // A concurrently removed file is represented by the next audit/probe.
                 }
-            })
-                .map((row) => row.filePath);
+            }
             const count = (sql) => db.query(sql).get()?.count ?? 0;
             const orphaned = {
                 embeddings: count(`SELECT COUNT(*) count FROM symbol_embeddings WHERE ${ORPHANED_EMBEDDING_PREDICATE}`),
@@ -11462,7 +12255,8 @@ export function createEngine() {
                 lastIndexedHead: getMeta(db, "lastIndexedHead") ?? "",
                 freshness,
                 indexGeneration,
-                verification: { mode: "deep-audit", verifiedAt },
+                verification: { mode: "deep-audit", auditVerifiedAt: verifiedAt, verifiedAt },
+                freshnessMechanism: freshnessMechanismFor(resolved, openPolicy),
                 repairSteps: needsRepair
                     ? [
                         "Run `knodin repair` to rebuild only missing or damaged local state.",
@@ -11470,20 +12264,31 @@ export function createEngine() {
                     ]
                     : [],
             };
-            if (!activeDb)
-                db.close();
             if (!needsRepair && !stale)
                 noteFreshness(resolved, "fresh");
-            setBoundedCache(statusCache, resolved, {
+            if (activeDb) {
+                try {
+                    db.run("PRAGMA wal_checkpoint(PASSIVE);");
+                }
+                catch {
+                    // A concurrent reader can defer checkpointing; the WAL fingerprint remains binding.
+                }
+            }
+            const finalDatabaseFingerprint = databaseFileFingerprint(diskDbPath, db);
+            setBoundedCache(statusCache, statusCacheKey, {
                 generation: indexGeneration,
-                databaseFingerprint,
+                databaseFingerprint: finalDatabaseFingerprint,
                 result: structuredClone(result),
             }, STATUS_CACHE_LIMIT);
+            writePersistedStatusAudit(resolved, diskDbPath, finalDatabaseFingerprint, result);
+            if (!activeDb)
+                db.close();
             return result;
         },
         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 +12308,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,17 +12368,22 @@ export function createEngine() {
             };
             const operation = Promise.resolve()
                 .then(async () => {
-                repairLease = acquireRepairLease(resolved);
-                const cancelBoundary = () => {
-                    if (activeOperation.controller.signal.aborted)
-                        throw activeOperation.controller.signal;
-                };
+                if (!openPolicy.databasePath)
+                    await suspendFileWatcher(resolved);
+                if (openPolicy.repairLease !== "disabled")
+                    repairLease = acquireRepairLease(resolved);
+                const cancelBoundary = () => throwIfAborted(activeOperation.controller.signal);
                 const invalidateCommittedWork = () => {
-                    if (committedWork && indexGeneration === generationBeforeRepair)
+                    if (!openPolicy.databasePath &&
+                        committedWork &&
+                        indexGeneration === generationBeforeRepair)
                         indexGeneration++;
                 };
                 emitProgress("audit", 0, "Auditing repository health");
-                before = await engine.status(resolved);
+                before = await engine.status(resolved, {
+                    audit: "deep",
+                    signal: activeOperation.controller.signal,
+                });
                 emitProgress("audit", 1, "Repository health audit completed", {
                     phaseTotal: 1,
                 });
@@ -11609,9 +12423,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 +12450,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)
@@ -11714,7 +12529,11 @@ export function createEngine() {
                         phaseTotal: 1,
                     });
                     cancelBoundary();
-                    persistSymbolIdentities(db, resolved, inheritedPostprocessing ? undefined : repairPaths);
+                    const identityScope = inheritedPostprocessing ? undefined : repairPaths;
+                    if (options?.signal)
+                        await persistSymbolIdentitiesCancellable(db, resolved, identityScope, activeOperation.controller.signal);
+                    else
+                        persistSymbolIdentities(db, resolved, identityScope);
                     if (repairAffectsTypeScriptDi)
                         reconcileTypeScriptDi(db, resolved);
                     committedWork = true;
@@ -11737,7 +12556,7 @@ export function createEngine() {
                             const model = details.modelFile ? ` (${details.modelFile})` : "";
                             emitProgress("embeddings", 0, `${message}${model}`);
                         }
-                    });
+                    }, activeOperation.controller.signal);
                     committedWork = true;
                     setMeta(db, "repairPostprocessingPending", "0");
                     overallCompleted++;
@@ -11793,7 +12612,10 @@ export function createEngine() {
                     phaseTotal: 1,
                 });
                 cancelBoundary();
-                let after = await engine.status(resolved, { audit: "deep" });
+                let after = await engine.status(resolved, {
+                    audit: "deep",
+                    signal: activeOperation.controller.signal,
+                });
                 cancelBoundary();
                 overallCompleted++;
                 emitProgress("verification", 1, "Repair verification completed", {
@@ -11816,21 +12638,27 @@ export function createEngine() {
                             }
                             setMeta(db, "lastSuccessfulReconciliation", new Date().toISOString());
                             recordFreshnessBaseline(resolved, db);
-                            statusCache.delete(resolved);
-                            const candidate = await engine.status(resolved, { audit: "deep" });
+                            statusCache.delete(databaseCacheKey(resolved, openPolicy.databasePath));
+                            const candidate = await engine.status(resolved, {
+                                audit: "deep",
+                                signal: activeOperation.controller.signal,
+                            });
                             if (candidate.status === "healthy") {
                                 db.run("COMMIT;");
                                 after = candidate;
                             }
                             else {
                                 db.run("ROLLBACK;");
-                                statusCache.delete(resolved);
-                                after = await engine.status(resolved, { audit: "deep" });
+                                statusCache.delete(databaseCacheKey(resolved, openPolicy.databasePath));
+                                after = await engine.status(resolved, {
+                                    audit: "deep",
+                                    signal: activeOperation.controller.signal,
+                                });
                             }
                         }
                         catch (error) {
                             db.run("ROLLBACK;");
-                            statusCache.delete(resolved);
+                            statusCache.delete(databaseCacheKey(resolved, openPolicy.databasePath));
                             throw error;
                         }
                     }
@@ -11855,10 +12683,14 @@ export function createEngine() {
                 return result;
             })
                 .catch(async (error) => {
-                if (error === activeOperation.controller.signal) {
-                    if (committedWork && indexGeneration === generationBeforeRepair)
+                if (wasAborted(error, activeOperation.controller.signal)) {
+                    if (!openPolicy.databasePath &&
+                        committedWork &&
+                        indexGeneration === generationBeforeRepair)
                         indexGeneration++;
-                    const after = await engine.status(resolved, { audit: "deep" });
+                    const after = openPolicy.databasePath
+                        ? before
+                        : await engine.status(resolved, { audit: "deep" });
                     const remaining = Math.max(0, repairPaths.length - completedFiles);
                     emitProgress("cancelled", completedFiles, `Repair cancelled with ${remaining} file(s) remaining`, { phaseTotal: repairPaths.length });
                     return {
@@ -11882,7 +12714,7 @@ export function createEngine() {
                 throw error;
             });
             activeOperation.promise = operation;
-            repairOperations.set(resolved, activeOperation);
+            repairOperations.set(repairKey, activeOperation);
             try {
                 return await operation;
             }
@@ -11891,223 +12723,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,
+                    });
+                }
+                // 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);
                 }
-                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 +13032,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 +13484,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 +15688,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 +15997,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);
 }