knodin 0.8.7 → 0.9.0

package/dist/src/engine/index.js

@@ -25,6 +25,7 @@ import { runReadOnlyLspQuery } from "../lsp-readonly.js";
 import { acquireRepairLease } from "../repair-lease.js";
 import { analyzeResourceReachability, resourceFingerprint, } from "../resource-reachability.js";
 import { contentFingerprint, writeStructuralSnapshot, } from "../structural-snapshot.js";
+import { acquireLifecycleCoordination } from "../update-coordination.js";
 import { KNODIN_VERSION } from "../version.js";
 import * as ann from "./ann-hnsw.js";
 import { allocateCandidate, assertCandidate, discardCandidateFiles, promoteCandidateFile, recoverInterruptedPromotion, } from "./candidate-database.js";
@@ -783,7 +784,7 @@ function freshnessMechanismFor(repoPath, policy) {
 }
 // Bumped whenever any repo is (re)indexed, so cached community-detection results
 // below can be invalidated cheaply instead of recomputed on every call.
-export const KNODIN_SCHEMA_VERSION = 22;
+export const KNODIN_SCHEMA_VERSION = 23;
 const LAST_REBUILD_SCHEMA_VERSION = 22;
 let indexGeneration = 0;
 const resourceReachabilityCache = new Map();
@@ -969,7 +970,10 @@ function writePersistedStatusAudit(repoPath, databasePath, databaseFingerprint,
     };
     try {
         fs.mkdirSync(path.dirname(target), { recursive: true });
-        fs.writeFileSync(temporary, `${JSON.stringify(snapshot)}\n`, { mode: 0o600, flag: "wx" });
+        fs.writeFileSync(temporary, `${JSON.stringify(snapshot)}\n`, {
+            mode: 0o600,
+            flag: "wx",
+        });
         fs.renameSync(temporary, target);
     }
     finally {
@@ -3229,7 +3233,10 @@ function getPackageMap(repoPath) {
         }
     }
     if (cacheable)
-        packageMapCache.set(resolvedRepoPath, { generation: indexGeneration, value: map });
+        packageMapCache.set(resolvedRepoPath, {
+            generation: indexGeneration,
+            value: map,
+        });
     return map;
 }
 /** Best source entry file for a package: prefer source-y fields, else src/index, else index. */
@@ -3749,7 +3756,13 @@ function extractApexPlatformDependencies(content, repoPath) {
 async function indexSalesforceMetadataFile(content, relativePath, repoPath, db, metadata) {
     const dependencies = [];
     const add = (to, kind, sourceEvidence, methodReference) => {
-        dependencies.push({ to, kind, confidence: 1, sourceEvidence, methodReference });
+        dependencies.push({
+            to,
+            kind,
+            confidence: 1,
+            sourceEvidence,
+            methodReference,
+        });
     };
     const addField = (object, value, kind, evidence) => {
         const qualified = value.includes(".") ? value : `${object}.${value}`;
@@ -5579,10 +5592,6 @@ async function indexPrismaFile(content, tree, relativePath, _repoPath, db) {
                                 const hasRelation = colDecl.text.includes("@relation");
                                 if (hasRelation) {
                                     dependencies.push({
-                                        from: modelName,
-                                        to: targetModel,
-                                        kind: "orm-relation",
-                                    }, {
                                         from: relativePath,
                                         to: targetModel,
                                         kind: "orm-relation",
@@ -5605,7 +5614,6 @@ async function indexPrismaFile(content, tree, relativePath, _repoPath, db) {
     const modelBlockRegex = /model\s+(\w+)\s*\{([^}]+)\}/g;
     let mBlock = modelBlockRegex.exec(content);
     while (mBlock !== null) {
-        const srcModel = mBlock[1];
         const blockContent = mBlock[2];
         // `(?<!\w)` pins the leading field name to a word start; without it the scan
         // restarts inside every identifier and re-walks it, which is quadratic.
@@ -5613,11 +5621,6 @@ async function indexPrismaFile(content, tree, relativePath, _repoPath, db) {
         let rel = relationRegex.exec(blockContent);
         while (rel !== null) {
             const targetModel = rel[1];
-            dependencies.push({
-                from: srcModel,
-                to: targetModel,
-                kind: "orm-relation",
-            });
             dependencies.push({
                 from: relativePath,
                 to: targetModel,
@@ -6252,7 +6255,10 @@ function reconcileTypeScriptDi(db, repoPath) {
                     .replace(/^type\s+/, "")
                     .split(/\s+as\s+/);
                 if (parts[0])
-                    imports.set(parts[1] ?? parts[0], { original: parts[0], module: match[2] });
+                    imports.set(parts[1] ?? parts[0], {
+                        original: parts[0],
+                        module: match[2],
+                    });
             }
         }
         for (const match of masked.matchAll(/\bimport\s+([A-Za-z_$][\w$]*)\s+from\s*["']([^"']+)["']/g))
@@ -6307,11 +6313,15 @@ function reconcileTypeScriptDi(db, repoPath) {
                     return { reason: `Token import ${token} does not resolve uniquely.` };
                 const definitionFile = followReExports(repoPath, moduleFile, imported.original, 0);
                 if (!exactSymbol(definitionFile, imported.original))
-                    return { reason: `Token ${token} does not have one indexed declaration.` };
+                    return {
+                        reason: `Token ${token} does not have one indexed declaration.`,
+                    };
                 return { value: `symbol:${definitionFile}#${imported.original}` };
             }
             if (!exactSymbol(file, token))
-                return { reason: `Token ${token} does not have one indexed declaration.` };
+                return {
+                    reason: `Token ${token} does not have one indexed declaration.`,
+                };
             return { value: `symbol:${file}#${token}` };
         };
         const implementation = (name) => {
@@ -6471,7 +6481,10 @@ function reconcileTypeScriptDi(db, repoPath) {
             ? bindingCandidates.filter((binding) => binding.framework === resolution.framework && binding.token === resolution.token)
             : (bindingsByToken.get(`${resolution.framework}\0${resolution.registry}\0${resolution.token}`) ?? []);
         if (bindings.length === 1)
-            candidates.push({ ...resolution, implementation: bindings[0].implementation });
+            candidates.push({
+                ...resolution,
+                implementation: bindings[0].implementation,
+            });
         else
             candidates.push({
                 ...resolution,
@@ -6844,7 +6857,9 @@ function mirrorSnapshotFor(repoPath) {
     const record = lookupMirror(repoPath);
     if (!record)
         return {};
-    return { mirror: { url: record.url, sha: record.sha, fetchedAt: record.fetchedAt } };
+    return {
+        mirror: { url: record.url, sha: record.sha, fetchedAt: record.fetchedAt },
+    };
 }
 /**
  * Compares indexed symbols against embedded ones. A repository with no symbols
@@ -8025,6 +8040,8 @@ async function getOrInitDb(repoPath, options = {}) {
             // newly indexable JSON files. v22 admits markdown as a link-only
             // participant, so previously skipped documentation must be visited once
             // to populate its doc_link / doc_link_broken edges.
+            // v23 changes the embedding runtime from FP32 to q8. Source topology is
+            // unchanged, so migrate in place and regenerate only semantic vectors.
             // Highest version whose upgrade needs the stored data REBUILT. Versions
             // above it migrate in place, so an upgrade costs a DELETE rather than a
             // full re-index + re-embed (~40 min of CPU on an 18k-symbol corpus).
@@ -8034,6 +8051,7 @@ async function getOrInitDb(repoPath, options = {}) {
             // v13 -> v14 purges embeddings orphaned while the FK cascade was inert.
             // Runs after the CREATE TABLEs below, since the table must exist.
             const needsOrphanPurge = storedVersion < KNODIN_SCHEMA_VERSION;
+            const needsEmbeddingRepresentationRefresh = storedVersion >= 22 && storedVersion < 23;
             if (storedVersion < LAST_REBUILD_SCHEMA_VERSION) {
                 db.run("DROP TRIGGER IF EXISTS after_symbol_insert;");
                 db.run("DROP TRIGGER IF EXISTS after_symbol_delete;");
@@ -8252,6 +8270,8 @@ async function getOrInitDb(repoPath, options = {}) {
             if (needsOrphanPurge) {
                 purgeOrphanEmbeddings(db);
             }
+            if (needsEmbeddingRepresentationRefresh)
+                db.run("DELETE FROM symbol_embeddings;");
             finishDbOpenMigration();
             // Check if we need to do a full index (e.g. if the database is brand new/empty)
             let needsIndex = true;
@@ -10673,7 +10693,9 @@ function withStaleness(engine, claimRepository, openDb, openPolicy) {
         },
     };
 }
-const DEFAULT_ENGINE_OPEN_POLICY = Object.freeze({ watcher: "enabled" });
+const DEFAULT_ENGINE_OPEN_POLICY = Object.freeze({
+    watcher: "enabled",
+});
 /** Default SQLite + Tree-Sitter engine. */
 export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
     const owner = Symbol("knodin-engine");
@@ -11049,14 +11071,20 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                 candidateAudits.set(candidate.id, databaseSha256);
             else
                 candidateAudits.delete(candidate.id);
-            return { healthy: issues.length === 0, issues: [...new Set(issues)], databaseSha256 };
+            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" });
+            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);
@@ -11245,7 +11273,10 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                 callees: allCallees.slice(0, cap),
                 calleeCount: allCallees.length,
                 ...(omissions.length > 0
-                    ? { omissions: omissions.slice(0, cap), omissionCount: omissions.length }
+                    ? {
+                        omissions: omissions.slice(0, cap),
+                        omissionCount: omissions.length,
+                    }
                     : {}),
                 blastRadius: allBlastFiles.slice(0, cap),
                 blastRadiusCount: allBlastFiles.length,
@@ -12209,8 +12240,12 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
             const count = (sql) => db.query(sql).get()?.count ?? 0;
             const orphaned = {
                 embeddings: count(`SELECT COUNT(*) count FROM symbol_embeddings WHERE ${ORPHANED_EMBEDDING_PREDICATE}`),
-                references: count('SELECT COUNT(*) count FROM "references" r WHERE NOT EXISTS (SELECT 1 FROM index_state i WHERE i.filePath=r.callerFile)'),
-                dependencies: count("SELECT COUNT(*) count FROM dependencies d WHERE NOT EXISTS (SELECT 1 FROM index_state i WHERE i.filePath=d.fromFile)"),
+                references: count(`SELECT COUNT(*) count FROM "references" r
+					 WHERE NOT EXISTS (SELECT 1 FROM index_state i WHERE i.filePath=r.callerFile)
+					   AND NOT (r.callerFile LIKE '.knodin/dbt/%' AND EXISTS (SELECT 1 FROM symbols s WHERE s.filePath=r.callerFile))`),
+                dependencies: count(`SELECT COUNT(*) count FROM dependencies d
+					 WHERE NOT EXISTS (SELECT 1 FROM index_state i WHERE i.filePath=d.fromFile)
+					   AND NOT (d.fromFile LIKE '.knodin/dbt/%' AND EXISTS (SELECT 1 FROM symbols s WHERE s.filePath=d.fromFile))`),
             };
             const records = staleFiles.map((file) => `indexed file no longer exists: ${file}`);
             for (const file of ineligibleFiles)
@@ -12255,7 +12290,11 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                 lastIndexedHead: getMeta(db, "lastIndexedHead") ?? "",
                 freshness,
                 indexGeneration,
-                verification: { mode: "deep-audit", auditVerifiedAt: verifiedAt, verifiedAt },
+                verification: {
+                    mode: "deep-audit",
+                    auditVerifiedAt: verifiedAt,
+                    verifiedAt,
+                },
                 freshnessMechanism: freshnessMechanismFor(resolved, openPolicy),
                 repairSteps: needsRepair
                     ? [
@@ -12736,292 +12775,306 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
         },
         async index(repoPath, files, clean = false, options) {
             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;
+            const indexCoordination = acquireLifecycleCoordination({
+                command: "index",
+                repository: resolved,
+                verificationToken: process.env.KNODIN_UPDATE_VERIFICATION_TOKEN,
+            });
+            try {
+                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 {
-                    const reconciliation = await engine.reconcileCandidate(candidate, resolved, undefined, {
+                    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,
-                        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, {
+                        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,
-                        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,
+                    let completionMessage = "Local graph is current";
+                    if (files && files.length > 0) {
+                        progress("indexing-files", 0, `Checking ${files.length.toLocaleString()} requested files`, {
+                            phaseTotal: files.length,
                         });
-                    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,
-                });
-                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);
-                        }
-                        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;");
+                        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);
+                            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 });
                         }
-                        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;
+                        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(databaseCacheKey(repoPath, openPolicy.databasePath));
-                    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(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) {
+                    const contentVerified = health.coverage.sourceFiles === health.coverage.indexedFiles &&
+                        health.missing.files.length === 0 &&
+                        health.missing.records.length === 0 &&
+                        Object.values(health.orphaned).every((count) => count === 0);
+                    if (contentVerified &&
+                        (health.freshness.state === "stale-head" || health.freshness.state === "unknown")) {
                         setMeta(db, "lastIndexedHead", gitHead(repoPath) ?? "");
                         setMeta(db, "lastSuccessfulReconciliation", new Date().toISOString());
                         recordFreshnessBaseline(repoPath, db);
+                        statusCache.delete(databaseCacheKey(repoPath, openPolicy.databasePath));
+                        health = await engine.status(repoPath, {
+                            audit: "deep",
+                            ignoreActiveOperation: true,
+                        });
                     }
-                    noteFreshness(repoPath, "fresh");
-                    // Test engines use an in-memory graph and must not create untracked
-                    // repository artifacts that pollute Git-diff/review fixtures.
-                    if (!process.env.VITEST && process.env.NODE_ENV !== "test")
-                        publishStructuralSnapshot(repoPath, db);
+                    // The postcondition belongs to this index result. Do not turn the next
+                    // explicit `status` call into a cache hit against an internal audit.
+                    statusCache.delete(databaseCacheKey(repoPath, openPolicy.databasePath));
+                    const issueCount = health.missing.files.length + health.missing.records.length;
+                    if (health.status === "healthy") {
+                        // Explicit indexing counts as a successful reconciliation only after
+                        // the audit proves that no requested or unrequested drift remains.
+                        if (files && files.length > 0) {
+                            setMeta(db, "lastIndexedHead", gitHead(repoPath) ?? "");
+                            setMeta(db, "lastSuccessfulReconciliation", new Date().toISOString());
+                            recordFreshnessBaseline(repoPath, db);
+                        }
+                        noteFreshness(repoPath, "fresh");
+                        // Test engines use an in-memory graph and must not create untracked
+                        // repository artifacts that pollute Git-diff/review fixtures.
+                        if (!process.env.VITEST && process.env.NODE_ENV !== "test")
+                            publishStructuralSnapshot(repoPath, db);
+                    }
+                    else {
+                        freshnessProbes.delete(path.resolve(repoPath));
+                    }
+                    progress("verifying", 1, health.status === "healthy"
+                        ? "Local graph health verified"
+                        : `Local graph still has ${issueCount.toLocaleString()} issue(s)`, { phaseTotal: 1 });
+                    const completed = files?.length ?? indexed.length;
+                    progress("completed", completed, health.status === "healthy"
+                        ? completionMessage
+                        : `${completionMessage}; verification found ${issueCount.toLocaleString()} issue(s)`, { phaseTotal: completed });
+                    return {
+                        indexed,
+                        unchanged,
+                        scip: scipReport,
+                        sarif: sarifReport,
+                        verification: {
+                            status: health.status,
+                            issueCount,
+                            missing: health.missing,
+                            verifiedAt: health.verification.verifiedAt,
+                        },
+                    };
+                }
+                finally {
+                    const activeDb = dbInstances.get(resolved);
+                    if (!openPolicy.databasePath &&
+                        activeDb &&
+                        openPolicy.watcher === "enabled" &&
+                        watcherStateBefore !== "scale-limited" &&
+                        watcherStateBefore !== "resource-limited")
+                        startFileWatcher(resolved, activeDb, openPolicy.watcherFileLimit);
                 }
-                else {
-                    freshnessProbes.delete(path.resolve(repoPath));
-                }
-                progress("verifying", 1, health.status === "healthy"
-                    ? "Local graph health verified"
-                    : `Local graph still has ${issueCount.toLocaleString()} issue(s)`, { phaseTotal: 1 });
-                const completed = files?.length ?? indexed.length;
-                progress("completed", completed, health.status === "healthy"
-                    ? completionMessage
-                    : `${completionMessage}; verification found ${issueCount.toLocaleString()} issue(s)`, { phaseTotal: completed });
-                return {
-                    indexed,
-                    unchanged,
-                    scip: scipReport,
-                    sarif: sarifReport,
-                    verification: {
-                        status: health.status,
-                        issueCount,
-                        missing: health.missing,
-                        verifiedAt: health.verification.verifiedAt,
-                    },
-                };
             }
             finally {
-                const activeDb = dbInstances.get(resolved);
-                if (!openPolicy.databasePath &&
-                    activeDb &&
-                    openPolicy.watcher === "enabled" &&
-                    watcherStateBefore !== "scale-limited" &&
-                    watcherStateBefore !== "resource-limited")
-                    startFileWatcher(resolved, activeDb, openPolicy.watcherFileLimit);
+                indexCoordination.release();
             }
         },
         async search(query, repoPath, limit, options = {}) {
@@ -15070,7 +15123,11 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                         });
                         diskFingerprint = resourceFingerprint(inputs);
                         if (!diskDrifted)
-                            setBoundedCache(resourceCorpusCache, resolvedRepoPath, { generation: indexGeneration, inputs, fingerprint: diskFingerprint }, RESOURCE_CORPUS_CACHE_LIMIT);
+                            setBoundedCache(resourceCorpusCache, resolvedRepoPath, {
+                                generation: indexGeneration,
+                                inputs,
+                                fingerprint: diskFingerprint,
+                            }, RESOURCE_CORPUS_CACHE_LIMIT);
                     }
                     // Disk state is part of the cache identity. A generation-only key can
                     // return a previously fresh result during the freshness-probe TTL after
@@ -15080,7 +15137,10 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     const cached = resourceReachabilityCache.get(cacheKey);
                     if (cached?.generation === indexGeneration) {
                         const result = structuredClone(cached.result);
-                        return finish([], { count: result.paths.length, resourceReachability: result });
+                        return finish([], {
+                            count: result.paths.length,
+                            resourceReachability: result,
+                        });
                     }
                     const result = analyzeResourceReachability(inputs, {
                         maxItems: cap,
@@ -15090,7 +15150,10 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                         expectedFingerprint: diskDrifted ? `indexed:${diskFingerprint}` : diskFingerprint,
                     });
                     setBoundedCache(resourceReachabilityCache, cacheKey, { generation: indexGeneration, result: structuredClone(result) }, RESOURCE_REACHABILITY_CACHE_LIMIT);
-                    return finish([], { count: result.paths.length, resourceReachability: result });
+                    return finish([], {
+                        count: result.paths.length,
+                        resourceReachability: result,
+                    });
                 }
                 case "flow_analysis": {
                     // C8 deliberately does not persist a PDG. This is a bounded, local