knodin 0.8.7 → 0.10.0

package/dist/src/engine/index.js

@@ -25,16 +25,23 @@ 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";
 import { computeSimilarity, generateEmbedding, generateEmbeddings, } from "./embeddings.js";
 import { walkRepoFiles } from "./file-walker.js";
 import { clearGitHistorySignalCache, collectGitHistorySignals, } from "./git-history.js";
+// Runtime import, but not a cycle: parse-pool imports only TYPES from here,
+// which erase at compile time. parse-worker's runtime import of this module
+// resolves inside the worker thread, never in this one.
+import { createParsePool, parseWorkersEnabled } from "./parse-pool.js";
 import { beginPerfPhase, measurePerfPhase, measurePerfPhaseSync } from "./perf.js";
 import { isIndexablePath, makeWatchIgnorePredicate } from "./prune.js";
+import { reflinkCopyFile } from "./reflink-copy.js";
 import { readSarifLog, SARIF_DEFAULT_LIMITS, } from "./sarif-import.js";
 import { readScipIndex, SCIP_DEFAULT_LIMITS, } from "./scip-import.js";
+import { listSealedFiles, readSealedSource } from "./seal.js";
 import { isIndexableSourcePath } from "./source-policy.js";
 import { Database } from "./sqlite.js";
 import { lookupMirror, mayWriteToRepository, resolveDbPath, resolveStateDir, } from "./state-paths.js";
@@ -500,10 +507,13 @@ function persistSymbolIdentities(db, repoPath, filePaths) {
                 }
                 sourceLines.set(row.filePath, lines);
             }
-            const declaration = lines
-                .slice(Math.max(0, row.startLine - 1), row.endLine)
-                .join("\n")
-                .split(/\r?\n/, 1)[0]
+            // Only the symbol's FIRST line is used. This used to slice the whole
+            // body, join it into one string and split that back apart to take
+            // element zero — building the entire declaration text of every symbol
+            // to read one line of it, which cost 2.9ms per symbol on a real
+            // corpus. `lines` comes from `split(/\r?\n/)`, so no element contains
+            // a newline and indexing is exactly equivalent.
+            const declaration = (lines[Math.max(0, row.startLine - 1)] ?? "")
                 // `(?<!\s)` pins the match to the start of a whitespace run; without it
                 // every position inside the run rescans it, which is quadratic.
                 //
@@ -783,8 +793,8 @@ 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;
-const LAST_REBUILD_SCHEMA_VERSION = 22;
+export const KNODIN_SCHEMA_VERSION = 24;
+const LAST_REBUILD_SCHEMA_VERSION = 24;
 let indexGeneration = 0;
 const resourceReachabilityCache = new Map();
 const RESOURCE_REACHABILITY_CACHE_LIMIT = 32;
@@ -969,7 +979,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 {
@@ -1122,6 +1135,19 @@ export function getSearchCacheStats() {
         communityLookupCacheEntries: searchCommunityLookupCache.size,
     };
 }
+/**
+ * How many repositories still have a live engine owner in this process.
+ *
+ * The process-global caches are released only when this reaches zero (see
+ * `close()`), so a test asserting that those caches emptied is really
+ * asserting that it held the last engine. The suite shares one process per
+ * shard (`isolate: false`), where that is a property of the whole shard rather
+ * than of any single spec — hence exposing it, so such an assertion can state
+ * its precondition instead of depending on test ordering.
+ */
+export function getOpenRepositoryEngineCount() {
+    return repositoryEngineOwners.size;
+}
 /** Reset C46 work counters without changing cached production state. */
 export function resetSearchCacheStats() {
     for (const key of Object.keys(searchCacheStats)) {
@@ -1282,12 +1308,8 @@ function computeFlows(db, resolvedRepoPath) {
     const isExported = (relFile, name) => {
         let src = sourceCache.get(relFile);
         if (src === undefined) {
-            try {
-                src = fs.readFileSync(path.join(resolvedRepoPath, relFile), "utf-8");
-            }
-            catch {
-                src = null;
-            }
+            const read = readWholeSource(resolvedRepoPath, relFile);
+            src = read.availability.state === "available" ? read.text : null;
             sourceCache.set(relFile, src);
         }
         if (!src)
@@ -3177,15 +3199,18 @@ function resolveImportPath(sourceFile, importSource, repoPath) {
     // Extensionless specifier: try appending each known source extension.
     for (const e of RESOLVE_EXTS)
         candidates.push(absolutePath + e);
+    // Probed through the resolver, not the filesystem: a sealed repository has
+    // no working tree, and `fs.existsSync` there would fail every candidate and
+    // silently report the module unresolvable rather than erroring.
     for (const c of candidates) {
-        if (fs.existsSync(c) && fs.statSync(c).isFile()) {
+        if (sourceFileExists(repoPath, path.relative(repoPath, c))) {
             return path.relative(repoPath, c);
         }
     }
     // Directory import -> its index file.
     for (const e of RESOLVE_EXTS) {
         const p = path.join(absolutePath, `index${e}`);
-        if (fs.existsSync(p)) {
+        if (sourceFileExists(repoPath, path.relative(repoPath, p))) {
             return path.relative(repoPath, p);
         }
     }
@@ -3209,11 +3234,12 @@ function getPackageMap(repoPath) {
         return cached.value;
     const map = new Map();
     let cacheable = true;
-    for (const rel of walkRepoFiles(repoPath, {
-        accept: (file) => path.posix.basename(file) === "package.json",
-    })) {
+    for (const rel of listSourceFiles(repoPath, (file) => path.posix.basename(file) === "package.json")) {
         try {
-            const pkg = JSON.parse(fs.readFileSync(path.join(repoPath, rel), "utf-8"));
+            const manifest = readWholeSource(repoPath, rel);
+            if (manifest.availability.state !== "available")
+                continue;
+            const pkg = JSON.parse(manifest.text);
             if (pkg && typeof pkg.name === "string") {
                 const dir = path.posix.dirname(rel);
                 map.set(pkg.name, {
@@ -3229,7 +3255,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. */
@@ -3243,7 +3272,7 @@ function resolvePackageEntry(repoPath, dir, pkg) {
     }
     for (const rel of ["src/index.ts", "src/index.tsx", "src/index.js", "index.ts", "index.js"]) {
         const p = path.join(dir, rel);
-        if (fs.existsSync(path.join(repoPath, p)))
+        if (sourceFileExists(repoPath, p))
             return p;
     }
     return null;
@@ -3389,10 +3418,10 @@ function findClassFilePath(className, repoPath) {
  * LWC claim, so the LWC path uses this stricter resolver instead.
  */
 function findUniqueApexClassFilePath(className, repoPath) {
-    const matches = walkRepoFiles(repoPath, {
-        accept: (file) => path.posix.basename(file) === `${className}.cls`,
-        limit: 2,
-    });
+    // Enumerated through the resolver so a sealed repository answers from its
+    // coverage. Still bounded to two matches, because "unique" is the whole
+    // contract: a second match must resolve to null rather than a first hit.
+    const matches = listSourceFiles(repoPath, (file) => path.posix.basename(file) === `${className}.cls`).slice(0, 2);
     return matches.length === 1 ? matches[0] : null;
 }
 /**
@@ -3433,7 +3462,7 @@ function experienceSiteFile(sitePath, category, value, repoPath) {
         return null;
     const extension = category === "assets" ? "" : ".json";
     const target = `${sitePath}/${category}/${name}${extension}`;
-    return fs.existsSync(path.join(repoPath, target)) ? target : null;
+    return sourceFileExists(repoPath, target) ? target : null;
 }
 function findExperienceComponentFile(value, repoPath) {
     if (typeof value !== "string")
@@ -3444,7 +3473,7 @@ function findExperienceComponentFile(value, repoPath) {
     return (findSalesforceLwcComponentFile(component, repoPath) ??
         (() => {
             const candidate = `force-app/main/default/aura/${component}/${component}.cmp`;
-            return fs.existsSync(path.join(repoPath, candidate)) ? candidate : null;
+            return sourceFileExists(repoPath, candidate) ? candidate : null;
         })());
 }
 /**
@@ -3482,7 +3511,7 @@ function auraBundleFile(relativePath) {
 function findLwcComponentFile(fromFile, componentName, repoPath) {
     const lwcRoot = path.dirname(path.dirname(fromFile));
     const candidate = path.join(lwcRoot, componentName, `${componentName}.js`);
-    return fs.existsSync(path.join(repoPath, candidate)) ? candidate : null;
+    return sourceFileExists(repoPath, candidate) ? candidate : null;
 }
 function findApexMethodFilePath(className, methodName, repoPath) {
     const classFile = findUniqueApexClassFilePath(className, repoPath);
@@ -3544,13 +3573,10 @@ function findUniqueInvocableApexMethod(className, methodName, repoPath) {
     const file = findUniqueApexClassFilePath(className, repoPath);
     if (!file)
         return null;
-    let source;
-    try {
-        source = fs.readFileSync(path.join(repoPath, file), "utf8");
-    }
-    catch {
+    const read = readWholeSource(repoPath, file);
+    if (read.availability.state !== "available")
         return null;
-    }
+    const source = read.text;
     const matches = [];
     for (const match of source.matchAll(/@InvocableMethod\b[\s\S]{0,300}?\b(?:global|public)\s+static\s(?:\s|[^({;]*?(?<!\s))\s+([a-z]\w*)\s*\(/gi)) {
         if (!isExecutablePosition(source, match.index ?? 0) || match[1] !== methodName)
@@ -3590,7 +3616,7 @@ function findSalesforceLwcComponentFile(componentName, repoPath) {
     if (!/^[A-Za-z]\w*$/.test(componentName))
         return null;
     const candidate = `force-app/main/default/lwc/${componentName}/${componentName}.js`;
-    return fs.existsSync(path.join(repoPath, candidate)) ? candidate : null;
+    return sourceFileExists(repoPath, candidate) ? candidate : null;
 }
 function apexMethodIsDeclared(content, methodName) {
     const escaped = methodName.replace(/[.*+?^${}()|[\]\\]/g, String.raw `\$&`);
@@ -3746,10 +3772,81 @@ function extractApexPlatformDependencies(content, repoPath) {
     return dependencies;
 }
 /** Index C20's static, deployable Salesforce DX metadata without interpreting formulas or runtime values. */
+/** Symbol kinds emitted for Salesforce DX metadata, one per metadata type. */
+export const SALESFORCE_METADATA_KINDS = [
+    "salesforce_object",
+    "salesforce_field",
+    "salesforce_record_type",
+    "salesforce_permission_set",
+    "salesforce_flow",
+    "salesforce_workflow",
+    "salesforce_approval",
+];
+const SALESFORCE_KIND_BY_TYPE = {
+    object: "salesforce_object",
+    field: "salesforce_field",
+    recordType: "salesforce_record_type",
+    permissionSet: "salesforce_permission_set",
+    flow: "salesforce_flow",
+    workflow: "salesforce_workflow",
+    approval: "salesforce_approval",
+};
+/**
+ * Give a metadata symbol a kind and a summary that describe it.
+ *
+ * Every Salesforce symbol previously shared one kind and one identical
+ * boilerplate summary, which made 36,763 of them indistinguishable to both FTS
+ * (which indexes name, kind and summary) and to embeddings. A field's type,
+ * label and lookup target are sitting in the file and were simply discarded.
+ */
+function describeSalesforceMetadata(metadata, content) {
+    const kind = SALESFORCE_KIND_BY_TYPE[metadata.type] ?? "salesforce_metadata";
+    const first = (tag) => staticXmlTagValues(content, tag)[0]?.value?.trim() || undefined;
+    if (metadata.type === "field") {
+        const fieldType = first("type");
+        const referenceTo = first("referenceTo");
+        const label = first("label");
+        const parts = [
+            `Salesforce field ${metadata.object}.${metadata.field}`,
+            fieldType ? (referenceTo ? `${fieldType}(${referenceTo})` : fieldType) : undefined,
+            label ? `"${label}"` : undefined,
+        ].filter(Boolean);
+        return { kind, summary: parts.join(" — ") };
+    }
+    if (metadata.type === "object") {
+        const label = first("label");
+        // A `__e` suffix is the Platform Event marker, and callers ask about
+        // those specifically ("which Platform Event triggers lack a retry guard").
+        const platformEvent = metadata.object.endsWith("__e");
+        const parts = [
+            `Salesforce ${platformEvent ? "Platform Event" : "object"} ${metadata.object}`,
+            label ? `"${label}"` : undefined,
+        ].filter(Boolean);
+        return { kind, summary: parts.join(" — ") };
+    }
+    const label = first("label") ?? first("masterLabel");
+    const name = metadata.type === "flow"
+        ? metadata.name
+        : metadata.type === "permissionSet"
+            ? metadata.name
+            : metadata.type === "recordType"
+                ? `${metadata.object}.${metadata.recordType}`
+                : metadata.type === "approval"
+                    ? `${metadata.object}.${metadata.name}`
+                    : metadata.object;
+    const parts = [`Salesforce ${metadata.type} ${name}`, label ? `"${label}"` : undefined].filter(Boolean);
+    return { kind, summary: parts.join(" — ") };
+}
 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}`;
@@ -3760,9 +3857,17 @@ async function indexSalesforceMetadataFile(content, relativePath, repoPath, db,
         case "object":
             add(metadata.object, "salesforce_metadata_object", "Salesforce DX CustomObject file path");
             break;
-        case "field":
+        case "field": {
             add(`${metadata.object}.${metadata.field}`, "salesforce_metadata_field", "Salesforce DX CustomField file path");
+            // A Lookup/MasterDetail field names the object it points at. Emitting
+            // it as an edge is what turns "which objects are near the 40-lookup
+            // limit" into a graph query instead of a grep over raw XML.
+            for (const entry of staticXmlTagValues(content, "referenceTo")) {
+                if (staticSalesforceIdentifier(entry.value))
+                    add(entry.value, "salesforce_lookup_target", entry.evidence);
+            }
             break;
+        }
         case "recordType":
             add(`${metadata.object}.${metadata.recordType}`, "salesforce_record_type", "Salesforce DX RecordType file path");
             break;
@@ -3851,16 +3956,17 @@ async function indexSalesforceMetadataFile(content, relativePath, repoPath, db,
         db.run("DELETE FROM dependencies WHERE fromFile = ?", [relativePath]);
         db.run("DELETE FROM mcp_tools WHERE filePath = ?", [relativePath]);
         const flowSymbol = metadata.type === "flow" ? metadata.name : path.basename(relativePath, ".xml");
+        const descriptor = describeSalesforceMetadata(metadata, content);
         db.run(`INSERT INTO symbols (name, kind, filePath, startLine, endLine, startCol, endCol, summary)
 			 VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, [
             flowSymbol,
-            "salesforce-metadata",
+            descriptor.kind,
             relativePath,
             1,
             content.split("\n").length,
             0,
             0,
-            "Salesforce DX metadata (static declarations only; formulas and runtime targets are not resolved).",
+            descriptor.summary,
         ]);
         const insertRef = db.prepare(`INSERT INTO "references" (callerSymbol, callerFile, calleeSymbol, calleeFile, line, column, kind, confidence)
 			 VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
@@ -3899,7 +4005,7 @@ async function refreshFlowsForApexFiles(db, repoPath, apexFiles) {
     if (classNames.size === 0)
         return [];
     const flowFiles = db
-        .query("SELECT DISTINCT filePath FROM symbols WHERE kind = 'salesforce-metadata' AND filePath LIKE 'force-app/main/default/flows/%.flow-meta.xml' ORDER BY filePath")
+        .query("SELECT DISTINCT filePath FROM symbols WHERE kind = 'salesforce_flow' AND filePath LIKE 'force-app/main/default/flows/%.flow-meta.xml' ORDER BY filePath")
         .all();
     const refreshed = [];
     for (const { filePath } of flowFiles) {
@@ -5579,10 +5685,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 +5707,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 +5714,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,
@@ -5891,262 +5987,444 @@ export async function indexDbtManifestFile(content, _absolutePath, relativePath,
     }
 }
 /**
- * Index a single file's symbols and references into the SQLite database.
+ * Builds a `FileIndexResult` from an already-parsed tree -- no DB access,
+ * no `db` parameter. Factored out of `indexFile` so this same logic is
+ * usable both from the current synchronous caller and, later, from a worker
+ * thread that owns its own read+parse step (see the parallel-parsing plan).
+ */
+function buildFileIndexResult(tree, content, isPython, isApex, absolutePath, relativePath, repoPath, mcpRegistrations) {
+    const { definitions, references, fileDependencies, tableDependencies, ormDependencies, importBindings, apiContracts, } = measurePerfPhaseSync("parse_extract", () => extractSymbolsAndReferences(tree.rootNode, isPython, isApex, absolutePath));
+    const apexPlatformDependencies = isApex ? extractApexPlatformDependencies(content, repoPath) : [];
+    // Resolve each callee to the file its definition lives in, so references
+    // are file-qualified instead of name-only. Precedence: an imported name
+    // resolves to its module's file; otherwise a name defined in THIS file
+    // resolves to this file; otherwise unresolved (null) — external, dynamic,
+    // or a member call — which consumers treat as best-effort.
+    const localDefNames = new Set(definitions.map((d) => d.name));
+    const resolveCalleeFile = (calleeName, explicitModule) => {
+        // null means a member call on an ordinary value (`obj.run()`): do not
+        // accidentally reuse an unrelated named import called `run`. undefined
+        // means a bare call and is eligible for normal import-binding resolution.
+        const mod = explicitModule === null ? undefined : (explicitModule ?? importBindings.get(calleeName));
+        if (mod) {
+            // Resolve the module (relative or workspace package alias) to a file,
+            // then follow re-export barrels to the file that actually defines the
+            // symbol (so `@pkg` -> index barrel -> definition file).
+            const moduleFile = resolveModuleToFile(relativePath, mod, repoPath);
+            if (moduleFile)
+                return followReExports(repoPath, moduleFile, calleeName, 0);
+            return null;
+        }
+        if (localDefNames.has(calleeName))
+            return relativePath;
+        return null;
+    };
+    const resolvedReferences = references.map((ref) => ({
+        callerSymbol: ref.callerSymbol,
+        calleeSymbol: ref.calleeSymbol,
+        calleeFile: resolveCalleeFile(ref.calleeSymbol, ref.calleeModule),
+        line: ref.line,
+        column: ref.column,
+        kind: ref.kind ?? "call",
+    }));
+    const dependencies = [];
+    for (const depSource of fileDependencies) {
+        const resolved = resolveImportPath(relativePath, depSource, repoPath);
+        if (resolved)
+            dependencies.push({ toFile: resolved, kind: "import" });
+    }
+    if (tableDependencies) {
+        for (const tableName of tableDependencies)
+            dependencies.push({ toFile: tableName, kind: "table" });
+    }
+    if (ormDependencies) {
+        for (const dep of ormDependencies)
+            dependencies.push({ toFile: dep.to, kind: dep.kind });
+    }
+    const dedupedApexPlatformDependencies = [];
+    const seenApexPlatformDependencies = new Set();
+    for (const dependency of apexPlatformDependencies) {
+        const key = `${dependency.to}\0${dependency.kind}`;
+        if (seenApexPlatformDependencies.has(key))
+            continue;
+        seenApexPlatformDependencies.add(key);
+        dedupedApexPlatformDependencies.push(dependency);
+    }
+    return {
+        relativePath,
+        mcpRegistrations,
+        definitions,
+        references: resolvedReferences,
+        apiContracts,
+        dependencies,
+        apexPlatformDependencies: dedupedApexPlatformDependencies,
+    };
+}
+/**
+ * Writes a single `FileIndexResult` inside its own transaction -- identical
+ * shape to `indexFile`'s previous inline write, just parameterized on
+ * already-extracted data instead of closure-captured locals.
+ */
+function writeFileIndexResult(db, result) {
+    const finishWrite = beginPerfPhase("sqlite_write");
+    db.run("BEGIN TRANSACTION;");
+    try {
+        writeFileIndexResultUnwrapped(db, result);
+        db.run("COMMIT;");
+    }
+    catch (error) {
+        db.run("ROLLBACK;");
+        throw error;
+    }
+    finally {
+        finishWrite();
+    }
+}
+/** The actual delete+insert statements, run inside a transaction/savepoint the caller owns. */
+function writeFileIndexResultUnwrapped(db, result) {
+    const { relativePath, mcpRegistrations, definitions, references, apiContracts, dependencies } = result;
+    db.run('DELETE FROM "references" WHERE callerFile = ?', [relativePath]);
+    deleteSymbolsForFile(db, relativePath);
+    db.run("DELETE FROM dependencies WHERE fromFile = ?", [relativePath]);
+    db.run("DELETE FROM mcp_tools WHERE filePath = ?", [relativePath]);
+    db.run("DELETE FROM api_contracts WHERE filePath = ?", [relativePath]);
+    const insertMcp = db.prepare(`
+		INSERT INTO mcp_tools(name, description, schemaSymbol, handlerSymbol, filePath, line, confidence, associationKey)
+		VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+	`);
+    for (const registration of mcpRegistrations) {
+        insertMcp.run(registration.name, registration.description ?? null, registration.schemaSymbol ?? null, registration.handlerSymbol ?? null, relativePath, registration.line, registration.confidence, registration.associationKey ?? null);
+    }
+    insertMcp.finalize();
+    const insertSym = db.prepare(`
+		INSERT INTO symbols (name, kind, filePath, startLine, endLine, startCol, endCol, summary)
+		VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+	`);
+    for (const def of definitions) {
+        insertSym.run(def.name, def.kind, relativePath, def.startLine, def.endLine, def.startCol, def.endCol, def.summary);
+    }
+    insertSym.finalize();
+    const insertRef = db.prepare(`
+		INSERT INTO "references" (callerSymbol, callerFile, calleeSymbol, calleeFile, line, column, kind)
+		VALUES (?, ?, ?, ?, ?, ?, ?)
+	`);
+    for (const ref of references) {
+        insertRef.run(ref.callerSymbol, relativePath, ref.calleeSymbol, ref.calleeFile, ref.line, ref.column, ref.kind);
+    }
+    insertRef.finalize();
+    const insertApiContract = db.prepare(`
+		INSERT INTO api_contracts (kind, framework, method, path, origin, handler, middleware, responseFields, responseKnown, declaredResponseFields, accessedFields, unresolved, filePath, line, confidence, evidence)
+		VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`);
+    for (const fact of apiContracts) {
+        insertApiContract.run(fact.kind, fact.framework, fact.method, fact.path, fact.origin, fact.handler, JSON.stringify(fact.middleware), JSON.stringify(fact.responseFields), fact.responseKnown ? 1 : 0, JSON.stringify(fact.declaredResponseFields), JSON.stringify(fact.accessedFields), fact.unresolved ? 1 : 0, relativePath, fact.line, fact.confidence, fact.evidence);
+    }
+    insertApiContract.finalize();
+    const insertDep = db.prepare(`
+		INSERT INTO dependencies (fromFile, toFile, kind)
+		VALUES (?, ?, ?)
+	`);
+    const insertApexPlatformDependency = db.prepare("INSERT INTO dependencies (fromFile, toFile, kind, confidence, sourceEvidence) VALUES (?, ?, ?, ?, ?)");
+    for (const dep of dependencies) {
+        insertDep.run(relativePath, dep.toFile, dep.kind);
+    }
+    insertDep.finalize();
+    for (const dependency of result.apexPlatformDependencies) {
+        insertApexPlatformDependency.run(relativePath, dependency.to, dependency.kind, 1, dependency.sourceEvidence);
+    }
+    insertApexPlatformDependency.finalize();
+}
+/**
+ * Write a batch of `FileIndexResult`s in a single transaction, isolating
+ * each file behind its own SAVEPOINT so one file's write failure rolls back
+ * only that file and does not lose the rest of the batch -- the same
+ * per-file error-isolation contract `indexFile`'s single-file transaction
+ * always had, just amortized over one BEGIN/COMMIT per batch instead of per
+ * file. Returns the files whose write failed, mirroring `indexFile`'s own
+ * catch (caller tallies into `unparsedByExtension` the same way).
+ */
+export function writeFileIndexResultBatch(db, results) {
+    if (results.length === 0)
+        return [];
+    const failures = [];
+    const finishWrite = beginPerfPhase("sqlite_write");
+    db.run("BEGIN TRANSACTION;");
+    try {
+        results.forEach((result, i) => {
+            const savepoint = `f${i}`;
+            db.run(`SAVEPOINT ${savepoint};`);
+            try {
+                writeFileIndexResultUnwrapped(db, result);
+                db.run(`RELEASE ${savepoint};`);
+            }
+            catch (error) {
+                db.run(`ROLLBACK TO ${savepoint};`);
+                db.run(`RELEASE ${savepoint};`);
+                failures.push({ relativePath: result.relativePath, error });
+            }
+        });
+        db.run("COMMIT;");
+    }
+    catch (error) {
+        db.run("ROLLBACK;");
+        throw error;
+    }
+    finally {
+        finishWrite();
+    }
+    return failures;
+}
+const INDEX_WRITE_BATCH_SIZE = (() => {
+    const raw = Number(process.env.KNODIN_INDEX_WRITE_BATCH_SIZE);
+    return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 200;
+})();
+/**
+ * Read, parse, and extract one file through the generic tree-sitter path.
  *
- * `unparsed`, when supplied, receives a per-extension tally of files that were
- * collected as indexable but produced no graph facts — no grammar claimed them,
- * they were rejected as minified, or indexing threw. These are invisible
- * otherwise: the function swallows all three cases, so a whole language silently
- * contributing nothing looks exactly like a language with nothing to say.
+ * Deliberately free of any `Database` parameter so the whole read → parse →
+ * extract sequence can run off the main thread. `indexFile` is the only
+ * in-tree caller today; the parse pool becomes the second, and both must go
+ * through here so routing can never drift between them.
  */
-async function indexFile(absolutePath, relativePath, repoPath, db, unparsed) {
+export async function extractGenericFileForIndex(absolutePath, relativePath, repoPath) {
+    const lang = await measurePerfPhase("parser_wasm_init", () => getLanguageForFile(absolutePath));
+    if (!lang)
+        return { kind: "unparsed" };
+    const content = measurePerfPhaseSync("read", () => fs.readFileSync(absolutePath, "utf-8"));
+    // Skip minified / generated bundles (e.g. a `*.bundle.js`): they're not
+    // readable source and would inject thousands of junk "symbols" that pollute
+    // the graph, communities, and hubs. Heuristic: a very high average line
+    // length (minified code packs everything onto a few enormous lines).
+    if (isMinifiedSource(content))
+        return { kind: "unparsed" };
+    const isSql = absolutePath.endsWith(".sql") || absolutePath.endsWith(".pkb") || absolutePath.endsWith(".pks");
+    // SQL: neutralize dollar-quoted bodies that crash the grammar's scanner.
+    // The tree and every downstream indexer must see the SAME string, so pass
+    // `parseContent` (not the raw file) forward.
+    const parseContent = isSql ? sanitizeDollarQuotedSql(content) : content;
+    const parser = new Parser();
+    parser.setLanguage(lang);
+    // A malformed/pathological input can make the wasm parser throw rather than
+    // return an ERROR tree. Skip that one file instead of aborting the file's
+    // index (and without dumping the wasm source into the log).
+    let tree;
+    try {
+        tree = measurePerfPhaseSync("parse_extract", () => parser.parse(parseContent));
+    }
+    catch (e) {
+        console.warn(`knodin: skipped ${relativePath} (parser error: ${e.message})`);
+        return { kind: "skipped", reason: e.message };
+    }
+    if (!tree)
+        return { kind: "skipped", reason: "parser returned no tree" };
+    const mcpRegistrations = /\.[cm]?[jt]sx?$/.test(absolutePath) && /@modelcontextprotocol\/sdk/.test(content)
+        ? extractMcpToolRegistrations(content, relativePath, tree.rootNode)
+        : [];
+    const isPython = absolutePath.endsWith(".py");
+    const isApex = absolutePath.endsWith(".cls") || absolutePath.endsWith(".trigger");
+    const isVisualforce = absolutePath.endsWith(".page") || absolutePath.endsWith(".component");
+    const isPrisma = absolutePath.endsWith(".prisma");
+    const isWorkday = absolutePath.endsWith(".clp") ||
+        absolutePath.endsWith(".ws") ||
+        (absolutePath.endsWith(".xml") && isWorkdayStudioFile(content, absolutePath));
+    const special = (route) => ({
+        kind: "special",
+        route,
+        content,
+        parseContent,
+        tree: tree,
+    });
+    if (isWorkday)
+        return special("workday");
+    if (isVisualforce)
+        return special("visualforce");
+    if (isSql)
+        return special("sql");
+    if (isPrisma)
+        return special("prisma");
+    return {
+        kind: "result",
+        result: buildFileIndexResult(tree, content, isPython, isApex, absolutePath, relativePath, repoPath, mcpRegistrations),
+    };
+}
+/**
+ * The single source of truth for indexer routing.
+ *
+ * `indexFile` dispatches on this, and the parse pool decides worker
+ * eligibility from it. Both must consult the SAME function: a second copy of
+ * this ordering would drift the moment a file type is added, and the failure
+ * mode is silent — a markdown file routed to a worker comes back "unparsed"
+ * rather than reaching `indexMarkdownFile`, which reads as "this file has no
+ * symbols" instead of as an error.
+ *
+ * Order is significant and matches the historical dispatch exactly.
+ */
+export function classifyIndexRoute(absolutePath, relativePath, options) {
+    const baseName = path.basename(absolutePath).toLowerCase();
+    if (!options?.skipDbt && baseName === "manifest.json")
+        return { kind: "dbt-candidate" };
+    if (absolutePath.endsWith(".lsif") || baseName === "dump.lsif")
+        return { kind: "lsif" };
+    if (absolutePath.endsWith(".tf") ||
+        absolutePath.endsWith(".tfvars") ||
+        absolutePath.endsWith(".hcl"))
+        return { kind: "terraform" };
+    if (absolutePath.endsWith(".dockerfile") || baseName === "dockerfile")
+        return { kind: "dockerfile" };
+    const salesforceExperience = salesforceExperienceFile(relativePath);
+    if (salesforceExperience)
+        return { kind: "salesforce-experience", file: salesforceExperience };
+    const lwcBundle = lwcBundleFile(relativePath);
+    if (lwcBundle)
+        return { kind: "lwc-bundle", file: lwcBundle };
+    const auraBundle = auraBundleFile(relativePath);
+    if (auraBundle)
+        return { kind: "aura-bundle", file: auraBundle };
+    const salesforceMetadata = salesforceMetadataFile(relativePath);
+    if (salesforceMetadata)
+        return { kind: "salesforce-metadata", file: salesforceMetadata };
+    if (relativePath.endsWith(".md") || relativePath.endsWith(".mdx"))
+        return { kind: "markdown" };
+    if (relativePath.endsWith(".yml") || relativePath.endsWith(".yaml"))
+        return { kind: "yaml" };
+    if (relativePath.endsWith(".csproj") ||
+        relativePath.endsWith(".sln") ||
+        relativePath.endsWith(".props") ||
+        relativePath.endsWith(".targets"))
+        return { kind: "dotnet-project" };
+    if (relativePath.endsWith(".cshtml") || relativePath.endsWith(".razor"))
+        return { kind: "razor" };
+    return { kind: "generic" };
+}
+/**
+ * Whether a file may be parsed off the main thread.
+ *
+ * Only the generic tree-sitter path qualifies: every other route calls an
+ * indexer that writes to the database, and the database has exactly one
+ * writer. `dbt-candidate` is excluded on purpose — it cannot be resolved
+ * without reading the file, and `manifest.json` is rare enough that sending
+ * it down the sequential path costs nothing.
+ */
+export function isWorkerEligibleFile(absolutePath, relativePath) {
+    if (classifyIndexRoute(absolutePath, relativePath).kind !== "generic")
+        return false;
+    // `generic` is necessary but NOT sufficient. `extractGenericFileForIndex`
+    // can still return a `special` route — visualforce, workday, sql, prisma —
+    // each of which hands off to a main-thread indexer that opens its own
+    // BEGIN/COMMIT against the single-writer database. Sending one to a worker
+    // leaves it to the pool's fallback, which re-indexes it inline while pooled
+    // results are still accumulating for a batched write, and the two
+    // interleave nondeterministically: observed as a Visualforce controller
+    // edge that resolved on some runs and not others, at roughly 1 in 3.
+    //
+    // Decided from the path alone, so it can be answered before reading the
+    // file. `.xml` is excluded conservatively because Workday detection needs
+    // the content; an XML file indexing inline costs nothing.
+    return !SPECIAL_ROUTE_EXTENSIONS.some((extension) => absolutePath.endsWith(extension));
+}
+/**
+ * Extensions that may reach a `special` route in `extractGenericFileForIndex`.
+ *
+ * Kept adjacent to that function's own extension tests on purpose: if a new
+ * special route is added there without a matching entry here, the file becomes
+ * worker-eligible again and the failure is silent rather than loud.
+ */
+const SPECIAL_ROUTE_EXTENSIONS = [
+    ".page",
+    ".component",
+    ".clp",
+    ".ws",
+    ".xml",
+    ".sql",
+    ".pkb",
+    ".pks",
+    ".prisma",
+];
+async function indexFile(absolutePath, relativePath, repoPath, db, unparsed, collectResult) {
     try {
         invalidateScipFacts(db);
-        const baseName = path.basename(absolutePath).toLowerCase();
-        if (baseName === "manifest.json") {
+        const read = () => measurePerfPhaseSync("read", () => fs.readFileSync(absolutePath, "utf-8"));
+        let route = classifyIndexRoute(absolutePath, relativePath);
+        if (route.kind === "dbt-candidate") {
             const content = fs.readFileSync(absolutePath, "utf-8");
             if (isDbtManifest(content)) {
                 await indexDbtManifestFile(content, absolutePath, relativePath, repoPath, db);
                 return;
             }
+            // Not a dbt manifest after all. Re-classify without the dbt check so
+            // the file still reaches whatever route it would otherwise have taken.
+            route = classifyIndexRoute(absolutePath, relativePath, { skipDbt: true });
         }
-        if (absolutePath.endsWith(".lsif") || baseName === "dump.lsif") {
-            await indexLsifDump(absolutePath, relativePath, repoPath, db);
-            return;
-        }
-        const isTerraform = absolutePath.endsWith(".tf") ||
-            absolutePath.endsWith(".tfvars") ||
-            absolutePath.endsWith(".hcl");
-        if (isTerraform) {
-            const content = fs.readFileSync(absolutePath, "utf-8");
-            await indexTerraformFile(content, relativePath, repoPath, db);
-            return;
-        }
-        const isDockerfile = absolutePath.endsWith(".dockerfile") || baseName === "dockerfile";
-        if (isDockerfile) {
-            const content = fs.readFileSync(absolutePath, "utf-8");
-            await indexDockerFile(content, relativePath, repoPath, db);
-            return;
-        }
-        const salesforceExperience = salesforceExperienceFile(relativePath);
-        if (salesforceExperience) {
-            const content = measurePerfPhaseSync("read", () => fs.readFileSync(absolutePath, "utf-8"));
-            await indexSalesforceExperienceFile(content, relativePath, repoPath, db, salesforceExperience);
-            return;
-        }
-        const lwcBundle = lwcBundleFile(relativePath);
-        if (lwcBundle) {
-            const content = measurePerfPhaseSync("read", () => fs.readFileSync(absolutePath, "utf-8"));
-            await indexLwcBundleFile(content, relativePath, repoPath, db, lwcBundle);
-            return;
-        }
-        const auraBundle = auraBundleFile(relativePath);
-        if (auraBundle) {
-            const content = measurePerfPhaseSync("read", () => fs.readFileSync(absolutePath, "utf-8"));
-            await indexAuraBundleFile(content, relativePath, repoPath, db, auraBundle);
-            return;
-        }
-        const salesforceMetadata = salesforceMetadataFile(relativePath);
-        if (salesforceMetadata) {
-            const content = measurePerfPhaseSync("read", () => fs.readFileSync(absolutePath, "utf-8"));
-            await indexSalesforceMetadataFile(content, relativePath, repoPath, db, salesforceMetadata);
-            return;
-        }
-        if (relativePath.endsWith(".md") || relativePath.endsWith(".mdx")) {
-            const content = measurePerfPhaseSync("read", () => fs.readFileSync(absolutePath, "utf-8"));
-            await indexMarkdownFile(content, relativePath, repoPath, db);
-            return;
-        }
-        if (relativePath.endsWith(".yml") || relativePath.endsWith(".yaml")) {
-            const content = measurePerfPhaseSync("read", () => fs.readFileSync(absolutePath, "utf-8"));
-            await indexYamlFile(content, relativePath, repoPath, db);
-            return;
-        }
-        if (relativePath.endsWith(".csproj") ||
-            relativePath.endsWith(".sln") ||
-            relativePath.endsWith(".props") ||
-            relativePath.endsWith(".targets")) {
-            const content = measurePerfPhaseSync("read", () => fs.readFileSync(absolutePath, "utf-8"));
-            await indexDotnetProjectFile(content, relativePath, repoPath, db);
-            return;
-        }
-        if (relativePath.endsWith(".cshtml") || relativePath.endsWith(".razor")) {
-            const content = measurePerfPhaseSync("read", () => fs.readFileSync(absolutePath, "utf-8"));
-            await indexRazorFile(content, relativePath, repoPath, db);
-            return;
-        }
-        const lang = await measurePerfPhase("parser_wasm_init", () => getLanguageForFile(absolutePath));
-        if (!lang) {
-            if (unparsed)
-                tallyOne(unparsed, extensionBucket(relativePath));
-            return;
+        switch (route.kind) {
+            case "lsif":
+                await indexLsifDump(absolutePath, relativePath, repoPath, db);
+                return;
+            case "terraform":
+                await indexTerraformFile(fs.readFileSync(absolutePath, "utf-8"), relativePath, repoPath, db);
+                return;
+            case "dockerfile":
+                await indexDockerFile(fs.readFileSync(absolutePath, "utf-8"), relativePath, repoPath, db);
+                return;
+            case "salesforce-experience":
+                await indexSalesforceExperienceFile(read(), relativePath, repoPath, db, route.file);
+                return;
+            case "lwc-bundle":
+                await indexLwcBundleFile(read(), relativePath, repoPath, db, route.file);
+                return;
+            case "aura-bundle":
+                await indexAuraBundleFile(read(), relativePath, repoPath, db, route.file);
+                return;
+            case "salesforce-metadata":
+                await indexSalesforceMetadataFile(read(), relativePath, repoPath, db, route.file);
+                return;
+            case "markdown":
+                await indexMarkdownFile(read(), relativePath, repoPath, db);
+                return;
+            case "yaml":
+                await indexYamlFile(read(), relativePath, repoPath, db);
+                return;
+            case "dotnet-project":
+                await indexDotnetProjectFile(read(), relativePath, repoPath, db);
+                return;
+            case "razor":
+                await indexRazorFile(read(), relativePath, repoPath, db);
+                return;
+            default:
+                break;
         }
-        const content = measurePerfPhaseSync("read", () => fs.readFileSync(absolutePath, "utf-8"));
-        // Skip minified / generated bundles (e.g. a `*.bundle.js`): they're not
-        // readable source and would inject thousands of junk "symbols" that pollute
-        // the graph, communities, and hubs. Heuristic: a very high average line
-        // length (minified code packs everything onto a few enormous lines).
-        if (isMinifiedSource(content)) {
+        const extraction = await extractGenericFileForIndex(absolutePath, relativePath, repoPath);
+        if (extraction.kind === "unparsed") {
             if (unparsed)
                 tallyOne(unparsed, extensionBucket(relativePath));
             return;
         }
-        const isSql = absolutePath.endsWith(".sql") ||
-            absolutePath.endsWith(".pkb") ||
-            absolutePath.endsWith(".pks");
-        // SQL: neutralize dollar-quoted bodies that crash the grammar's scanner.
-        // The tree and every downstream indexer must see the SAME string, so pass
-        // `parseContent` (not the raw file) forward.
-        const parseContent = isSql ? sanitizeDollarQuotedSql(content) : content;
-        const parser = new Parser();
-        parser.setLanguage(lang);
-        // A malformed/pathological input can make the wasm parser throw rather than
-        // return an ERROR tree. Skip that one file instead of aborting the file's
-        // index (and without dumping the wasm source into the log).
-        let tree;
-        try {
-            tree = measurePerfPhaseSync("parse_extract", () => parser.parse(parseContent));
-        }
-        catch (e) {
-            console.warn(`knodin: skipped ${relativePath} (parser error: ${e.message})`);
-            return;
-        }
-        if (!tree)
-            return;
-        const mcpRegistrations = /\.[cm]?[jt]sx?$/.test(absolutePath) && /@modelcontextprotocol\/sdk/.test(content)
-            ? extractMcpToolRegistrations(content, relativePath, tree.rootNode)
-            : [];
-        const isPython = absolutePath.endsWith(".py");
-        const isApex = absolutePath.endsWith(".cls") || absolutePath.endsWith(".trigger");
-        const isVisualforce = absolutePath.endsWith(".page") || absolutePath.endsWith(".component");
-        const isPrisma = absolutePath.endsWith(".prisma");
-        const isWorkday = absolutePath.endsWith(".clp") ||
-            absolutePath.endsWith(".ws") ||
-            (absolutePath.endsWith(".xml") && isWorkdayStudioFile(content, absolutePath));
-        if (isWorkday) {
-            await indexWorkdayFile(content, tree, relativePath, repoPath, db);
-            return;
-        }
-        if (isVisualforce) {
-            await indexVisualforceFile(content, tree, relativePath, repoPath, db);
-            return;
-        }
-        if (isSql) {
-            await indexSqlFile(parseContent, tree, relativePath, repoPath, db);
+        // A parse failure abandons this one file without tallying it as a
+        // coverage gap: the file IS supported, it just did not parse, and
+        // `extractGenericFileForIndex` has already warned about it.
+        if (extraction.kind === "skipped")
             return;
-        }
-        if (isPrisma) {
-            await indexPrismaFile(content, tree, relativePath, repoPath, db);
-            return;
-        }
-        const { definitions, references, fileDependencies, tableDependencies, ormDependencies, importBindings, apiContracts, } = measurePerfPhaseSync("parse_extract", () => extractSymbolsAndReferences(tree.rootNode, isPython, isApex, absolutePath));
-        const apexPlatformDependencies = isApex
-            ? extractApexPlatformDependencies(content, repoPath)
-            : [];
-        // Resolve each callee to the file its definition lives in, so references
-        // are file-qualified instead of name-only. Precedence: an imported name
-        // resolves to its module's file; otherwise a name defined in THIS file
-        // resolves to this file; otherwise unresolved (null) — external, dynamic,
-        // or a member call — which consumers treat as best-effort.
-        const localDefNames = new Set(definitions.map((d) => d.name));
-        const resolveCalleeFile = (calleeName, explicitModule) => {
-            // null means a member call on an ordinary value (`obj.run()`): do not
-            // accidentally reuse an unrelated named import called `run`. undefined
-            // means a bare call and is eligible for normal import-binding resolution.
-            const mod = explicitModule === null ? undefined : (explicitModule ?? importBindings.get(calleeName));
-            if (mod) {
-                // Resolve the module (relative or workspace package alias) to a file,
-                // then follow re-export barrels to the file that actually defines the
-                // symbol (so `@pkg` -> index barrel -> definition file).
-                const moduleFile = resolveModuleToFile(relativePath, mod, repoPath);
-                if (moduleFile)
-                    return followReExports(repoPath, moduleFile, calleeName, 0);
-                return null;
-            }
-            if (localDefNames.has(calleeName))
-                return relativePath;
-            return null;
-        };
-        // Execute all database operations inside a single transaction synchronously
-        const finishWrite = beginPerfPhase("sqlite_write");
-        db.run("BEGIN TRANSACTION;");
-        try {
-            db.run('DELETE FROM "references" WHERE callerFile = ?', [relativePath]);
-            deleteSymbolsForFile(db, relativePath);
-            db.run("DELETE FROM dependencies WHERE fromFile = ?", [relativePath]);
-            db.run("DELETE FROM mcp_tools WHERE filePath = ?", [relativePath]);
-            db.run("DELETE FROM api_contracts WHERE filePath = ?", [relativePath]);
-            const insertMcp = db.prepare(`
-				INSERT INTO mcp_tools(name, description, schemaSymbol, handlerSymbol, filePath, line, confidence, associationKey)
-				VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-			`);
-            for (const registration of mcpRegistrations) {
-                insertMcp.run(registration.name, registration.description ?? null, registration.schemaSymbol ?? null, registration.handlerSymbol ?? null, relativePath, registration.line, registration.confidence, registration.associationKey ?? null);
-            }
-            insertMcp.finalize();
-            const insertSym = db.prepare(`
-				INSERT INTO symbols (name, kind, filePath, startLine, endLine, startCol, endCol, summary)
-				VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-			`);
-            for (const def of definitions) {
-                insertSym.run(def.name, def.kind, relativePath, def.startLine, def.endLine, def.startCol, def.endCol, def.summary);
-            }
-            insertSym.finalize();
-            const insertRef = db.prepare(`
-				INSERT INTO "references" (callerSymbol, callerFile, calleeSymbol, calleeFile, line, column, kind)
-				VALUES (?, ?, ?, ?, ?, ?, ?)
-			`);
-            for (const ref of references) {
-                insertRef.run(ref.callerSymbol, relativePath, ref.calleeSymbol, resolveCalleeFile(ref.calleeSymbol, ref.calleeModule), ref.line, ref.column, ref.kind ?? "call");
-            }
-            insertRef.finalize();
-            const insertApiContract = db.prepare(`
-				INSERT INTO api_contracts (kind, framework, method, path, origin, handler, middleware, responseFields, responseKnown, declaredResponseFields, accessedFields, unresolved, filePath, line, confidence, evidence)
-				VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-			`);
-            for (const fact of apiContracts) {
-                insertApiContract.run(fact.kind, fact.framework, fact.method, fact.path, fact.origin, fact.handler, JSON.stringify(fact.middleware), JSON.stringify(fact.responseFields), fact.responseKnown ? 1 : 0, JSON.stringify(fact.declaredResponseFields), JSON.stringify(fact.accessedFields), fact.unresolved ? 1 : 0, relativePath, fact.line, fact.confidence, fact.evidence);
-            }
-            insertApiContract.finalize();
-            const insertDep = db.prepare(`
-				INSERT INTO dependencies (fromFile, toFile, kind)
-				VALUES (?, ?, ?)
-			`);
-            for (const depSource of fileDependencies) {
-                const resolved = resolveImportPath(relativePath, depSource, repoPath);
-                if (resolved) {
-                    insertDep.run(relativePath, resolved, "import");
-                }
-            }
-            if (tableDependencies) {
-                for (const tableName of tableDependencies) {
-                    insertDep.run(relativePath, tableName, "table");
-                }
-            }
-            if (ormDependencies) {
-                for (const dep of ormDependencies) {
-                    insertDep.run(relativePath, dep.to, dep.kind);
-                }
-            }
-            insertDep.finalize();
-            const insertApexPlatformDependency = db.prepare("INSERT INTO dependencies (fromFile, toFile, kind, confidence, sourceEvidence) VALUES (?, ?, ?, ?, ?)");
-            const seenApexPlatformDependencies = new Set();
-            for (const dependency of apexPlatformDependencies) {
-                const key = `${dependency.to}\0${dependency.kind}`;
-                if (seenApexPlatformDependencies.has(key))
-                    continue;
-                seenApexPlatformDependencies.add(key);
-                insertApexPlatformDependency.run(relativePath, dependency.to, dependency.kind, 1, dependency.sourceEvidence);
+        if (extraction.kind === "special") {
+            const { content, parseContent, tree } = extraction;
+            switch (extraction.route) {
+                case "workday":
+                    await indexWorkdayFile(content, tree, relativePath, repoPath, db);
+                    return;
+                case "visualforce":
+                    await indexVisualforceFile(content, tree, relativePath, repoPath, db);
+                    return;
+                case "sql":
+                    await indexSqlFile(parseContent, tree, relativePath, repoPath, db);
+                    return;
+                case "prisma":
+                    await indexPrismaFile(content, tree, relativePath, repoPath, db);
+                    return;
             }
-            insertApexPlatformDependency.finalize();
-            db.run("COMMIT;");
         }
-        catch (error) {
-            db.run("ROLLBACK;");
-            throw error;
+        if (collectResult) {
+            collectResult(extraction.result);
         }
-        finally {
-            finishWrite();
+        else {
+            writeFileIndexResult(db, extraction.result);
         }
     }
     catch (error) {
@@ -6252,7 +6530,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 +6588,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 +6756,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 +7132,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
@@ -7196,6 +7486,37 @@ function parseGitStatusPaths(output) {
  * Only files actually re-indexed here are re-embedded (indexEmbeddings is
  * incremental), so a clean reconcile does no work.
  */
+/**
+ * Full mtime/size comparison against `index_state`, used both when there is
+ * no git HEAD at all and as a correctness fallback when a git-diff baseline
+ * turns out to be unresolvable (see `reconcileIndex`). Not a substitute for
+ * the git fast path in general: it only detects drift relative to *this*
+ * checkout's own recorded state, so a database whose `index_state` rows came
+ * from a different physical checkout (fresh mtimes on every file) degrades
+ * to "everything changed" here rather than a cheap targeted diff.
+ */
+function detectDriftByStat(repoPath, db, canonicalFiles) {
+    const changed = new Set();
+    const state = new Map();
+    for (const row of db
+        .query("SELECT filePath, mtimeMs, size FROM index_state")
+        .all()) {
+        state.set(row.filePath, row);
+    }
+    for (const file of canonicalFiles) {
+        const prev = state.get(file);
+        try {
+            const st = fs.statSync(path.join(repoPath, file));
+            if (!prev || Math.abs(prev.mtimeMs - st.mtimeMs) >= 1.0 || prev.size !== st.size) {
+                changed.add(file);
+            }
+        }
+        catch (_) {
+            changed.add(file);
+        }
+    }
+    return changed;
+}
 async function reconcileIndex(repoPath, db, progress) {
     try {
         progress?.("collecting-files", 0, "Checking existing local graph for changes");
@@ -7215,6 +7536,7 @@ async function reconcileIndex(repoPath, db, progress) {
                     changed.add(file);
             }
             catch (_) { }
+            let baselineUnresolved = false;
             if (lastHead && lastHead !== head) {
                 try {
                     const diff = child_process.execFileSync("git", ["diff", "--name-only", "-z", lastHead, head, "--"], {
@@ -7225,7 +7547,26 @@ async function reconcileIndex(repoPath, db, progress) {
                     for (const file of splitNulPaths(diff))
                         changed.add(file);
                 }
-                catch (_) { }
+                catch (_) {
+                    // `lastHead` is not resolvable in this checkout's object database
+                    // (a shallow clone missing that commit, or a database seeded from
+                    // an unrelated checkout). Silently treating this as "nothing
+                    // changed" would let the graph advance `lastIndexedHead` to the
+                    // new HEAD below while having missed every real change in
+                    // between — fall back to a full comparison instead.
+                    baselineUnresolved = true;
+                }
+            }
+            if (baselineUnresolved) {
+                console.warn(`knodin: cached baseline commit ${lastHead} is not resolvable in this checkout (shallow clone or foreign database) — falling back to a full file-drift comparison`);
+                canonicalFiles = collectRepoFiles(repoPath);
+                if (canonicalFiles.length > 50000) {
+                    console.warn(`knodin: skipping full-drift fallback reconcile (${canonicalFiles.length} files exceeds 50k bound)`);
+                }
+                else {
+                    for (const file of detectDriftByStat(repoPath, db, canonicalFiles))
+                        changed.add(file);
+                }
             }
         }
         else {
@@ -7235,24 +7576,8 @@ async function reconcileIndex(repoPath, db, progress) {
                 console.warn(`knodin: skipping freshness reconcile (${canonicalFiles.length} files exceeds 50k bound)`);
                 return 0;
             }
-            const state = new Map();
-            for (const row of db
-                .query("SELECT filePath, mtimeMs, size FROM index_state")
-                .all()) {
-                state.set(row.filePath, row);
-            }
-            for (const file of canonicalFiles) {
-                const prev = state.get(file);
-                try {
-                    const st = fs.statSync(path.join(repoPath, file));
-                    if (!prev || Math.abs(prev.mtimeMs - st.mtimeMs) >= 1.0 || prev.size !== st.size) {
-                        changed.add(file);
-                    }
-                }
-                catch (_) {
-                    changed.add(file);
-                }
-            }
+            for (const file of detectDriftByStat(repoPath, db, canonicalFiles))
+                changed.add(file);
         }
         // A row in index_state whose file is gone or no longer satisfies the
         // canonical source policy must be purged. Keep those legacy rows in the
@@ -7332,6 +7657,7 @@ async function reconcileIndex(repoPath, db, progress) {
         // "dirty, and indexed that way" from "dirty, and moved since".
         if (head)
             setMeta(db, "lastIndexedHead", head);
+        setMeta(db, "knodinVersion", KNODIN_VERSION);
         setMeta(db, "lastSuccessfulReconciliation", new Date().toISOString());
         recordFreshnessBaseline(repoPath, db);
         return reindexed;
@@ -7711,20 +8037,99 @@ async function indexRepo(repoPath, db, progress, skipEmbeddings = false, publish
     db.run("DELETE FROM dependencies;");
     db.run("DELETE FROM mcp_tools;");
     db.run("DELETE FROM index_state;");
-    // Process files sequentially to ensure thread-safe SQLite transactions
+    // Process files sequentially to ensure thread-safe SQLite transactions.
+    // Extraction (buildFileIndexResult, pure) still happens one file at a
+    // time here; only the write is batched, via `pendingWrites`, so the
+    // generic tree-sitter path amortizes one BEGIN/COMMIT over many files
+    // instead of paying it per file (per-file failure isolation is preserved
+    // through per-file SAVEPOINTs inside `writeFileIndexResultBatch`).
     let lastYieldAt = Date.now();
-    for (let offset = 0; offset < files.length; offset++) {
-        const file = files[offset];
-        await indexFile(path.join(repoPath, file), file, repoPath, db, unparsedByExtension);
+    const pendingWrites = [];
+    const flushPendingWrites = () => {
+        if (pendingWrites.length === 0)
+            return;
+        const failures = writeFileIndexResultBatch(db, pendingWrites);
+        for (const failure of failures) {
+            console.error(`Error indexing file ${failure.relativePath}:`, failure.error);
+            tallyOne(unparsedByExtension, extensionBucket(failure.relativePath));
+        }
+        pendingWrites.length = 0;
+    };
+    // Progress is reported against a single counter so the pool and the
+    // sequential path can interleave without the count going backwards.
+    let processed = 0;
+    const afterFile = async (file) => {
+        if (pendingWrites.length >= INDEX_WRITE_BATCH_SIZE)
+            flushPendingWrites();
         recordIndexState(db, repoPath, file);
-        progress?.("indexing-files", offset + 1, `Indexing ${files.length.toLocaleString()} files`, {
+        processed++;
+        progress?.("indexing-files", processed, `Indexing ${files.length.toLocaleString()} files`, {
             phaseTotal: files.length,
         });
         if (Date.now() - lastYieldAt >= INDEX_EVENT_LOOP_YIELD_MS) {
             await yieldToIndexEventLoop();
             lastYieldAt = Date.now();
         }
+    };
+    const indexOneInline = async (file) => {
+        await indexFile(path.join(repoPath, file), file, repoPath, db, unparsedByExtension, (result) => {
+            pendingWrites.push(result);
+        });
+    };
+    // Opt-in for now. `createParsePool` returns null whenever the machine says
+    // not to spawn, so an unsuitable host silently keeps today's behavior
+    // rather than discovering the problem partway through an index.
+    const pool = parseWorkersEnabled() ? createParsePool() : null;
+    try {
+        if (pool) {
+            // Only the generic tree-sitter route may leave the main thread; every
+            // other route calls an indexer that writes to the database, and the
+            // database has exactly one writer. `isWorkerEligibleFile` is derived
+            // from the same classifier `indexFile` dispatches on, so the two
+            // cannot disagree about where a file belongs.
+            const eligible = [];
+            const inline = [];
+            for (const file of files) {
+                if (isWorkerEligibleFile(path.join(repoPath, file), file))
+                    eligible.push({ absolutePath: path.join(repoPath, file), relativePath: file, repoPath });
+                else
+                    inline.push(file);
+            }
+            await pool.run(eligible, async (task, outcome) => {
+                switch (outcome.kind) {
+                    case "result":
+                        pendingWrites.push(outcome.result);
+                        break;
+                    case "unparsed":
+                        tallyOne(unparsedByExtension, extensionBucket(task.relativePath));
+                        break;
+                    case "skipped":
+                        break;
+                    default:
+                        // The pool could not finish this file (worker crash, or it
+                        // turned out to need a main-thread indexer). Never dropped:
+                        // run it through the sequential path exactly as before.
+                        await indexOneInline(task.relativePath);
+                        break;
+                }
+                await afterFile(task.relativePath);
+            });
+            for (const file of inline) {
+                await indexOneInline(file);
+                await afterFile(file);
+            }
+        }
+        else {
+            for (const file of files) {
+                await indexOneInline(file);
+                await afterFile(file);
+            }
+        }
+    }
+    finally {
+        await pool?.close();
     }
+    flushPendingWrites();
     progress?.("finalizing", 0, "Persisting symbol identities and semantic index");
     persistSymbolIdentities(db, repoPath);
     reconcileTypeScriptDi(db, repoPath);
@@ -7736,6 +8141,7 @@ async function indexRepo(repoPath, db, progress, skipEmbeddings = false, publish
         await indexEmbeddings(db, repoPath, progress);
     // Remember the HEAD we indexed at so a later cold start can diff forward.
     setMeta(db, "lastIndexedHead", gitHead(repoPath) ?? "");
+    setMeta(db, "knodinVersion", KNODIN_VERSION);
     setMeta(db, "lastSuccessfulReconciliation", new Date().toISOString());
     setMeta(db, "mcpBackfillVersion", "17");
     setMeta(db, COVERAGE_UNPARSED_META_KEY, JSON.stringify(Object.fromEntries(unparsedByExtension)));
@@ -7932,7 +8338,7 @@ async function suspendFileWatcher(repoPath) {
     return true;
 }
 /** Open and initialize SQLite connection and full repo index. */
-async function getOrInitDb(repoPath, options = {}) {
+export async function getOrInitDb(repoPath, options = {}) {
     const normalizedPath = path.resolve(repoPath);
     const selectedDatabasePath = explicitDatabasePath(normalizedPath, options.databasePath);
     if (!selectedDatabasePath)
@@ -8025,6 +8431,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 +8442,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;");
@@ -8215,9 +8624,21 @@ async function getOrInitDb(repoPath, options = {}) {
 					DELETE FROM symbols_fts WHERE symbolId = old.id;
 				END;
 			`);
+            // Scoped to the columns the FTS table actually mirrors. An unscoped
+            // AFTER UPDATE fires for every column, so writing `identity` -- which
+            // symbols_fts does not index -- rewrote an FTS row each time.
+            // `persistSymbolIdentities` writes identity for every symbol on a full
+            // index, and that alone measured 39.1s of a 40.0s pass (19,638 rows at
+            // ~2ms each) on a 1,926-file corpus.
+            //
+            // Dropped unconditionally rather than guarded by `IF NOT EXISTS`,
+            // because an existing database already carries the unscoped trigger and
+            // would otherwise keep it forever. Recreating a trigger on open is
+            // cheap and needs no schema-version bump or forced reindex.
+            db.run("DROP TRIGGER IF EXISTS after_symbol_update;");
             db.run(`
-				CREATE TRIGGER IF NOT EXISTS after_symbol_update
-				AFTER UPDATE ON symbols
+				CREATE TRIGGER after_symbol_update
+				AFTER UPDATE OF name, kind, summary ON symbols
 				BEGIN
 					UPDATE symbols_fts
 					SET name = new.name,
@@ -8252,6 +8673,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;
@@ -8447,12 +8870,92 @@ function matchEndpoints(clientPath, serverPath) {
                 serverSegment.toLocaleLowerCase("en-US");
     });
 }
-/** Get verbatim source with line numbers. */
-function getSourceRange(repoPath, relativePath, startLine, endLine, maxLines) {
-    const absPath = path.resolve(repoPath, relativePath);
-    if (!fs.existsSync(absPath))
-        return "";
-    const content = fs.readFileSync(absPath, "utf-8");
+/**
+ * Repositories being served from a sealed artifact rather than a working tree.
+ *
+ * Keyed by the repository path a caller passes in, so every existing reader
+ * keeps its signature. This is the ONE place that decides where source bytes
+ * come from: widening the chokepoint instead of threading a resolver through
+ * ~20 call sites is what keeps a sealed answer from depending on whether a
+ * particular reader remembered to ask.
+ */
+const sealedRepositories = new Map();
+export function registerSealedRepository(repoPath, db) {
+    sealedRepositories.set(path.resolve(repoPath), db);
+}
+export function unregisterSealedRepository(repoPath) {
+    sealedRepositories.delete(path.resolve(repoPath));
+}
+export function isSealedRepository(repoPath) {
+    return sealedRepositories.has(path.resolve(repoPath));
+}
+/**
+ * Whole-file source, from the sealed artifact when there is one.
+ *
+ * Returns an availability rather than a bare string, and NEVER `""` for
+ * missing content: an empty string is indistinguishable from an empty file,
+ * and downstream that reads as "this file has nothing in it" rather than "this
+ * was not covered" — the silent false negative a consumer needs to detect in
+ * order to fall back to live source.
+ */
+function readWholeSource(repoPath, relativePath) {
+    const sealed = sealedRepositories.get(path.resolve(repoPath));
+    if (sealed) {
+        const text = readSealedSource(sealed, relativePath);
+        return text === null
+            ? {
+                text: "",
+                availability: {
+                    state: "absent",
+                    reason: `not covered by the sealed artifact: ${relativePath}`,
+                },
+            }
+            : { text, availability: { state: "available" } };
+    }
+    try {
+        return {
+            text: fs.readFileSync(path.resolve(repoPath, relativePath), "utf-8"),
+            availability: { state: "available" },
+        };
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return error?.code === "ENOENT"
+            ? { text: "", availability: { state: "absent", reason } }
+            : { text: "", availability: { state: "read-failed", reason, retryable: true } };
+    }
+}
+/**
+ * Whether a file is present as source, without reading it.
+ *
+ * A sealed artifact answers from its embedded coverage, not the filesystem —
+ * a sealed repository has no working tree, so `fs.existsSync` there would
+ * report every file missing and quietly invert the meaning of any check built
+ * on it (a test file "not present", a module path "unresolvable").
+ */
+function sourceFileExists(repoPath, relativePath) {
+    const sealed = sealedRepositories.get(path.resolve(repoPath));
+    if (sealed)
+        return readSealedSource(sealed, relativePath) !== null;
+    return fs.existsSync(path.resolve(repoPath, relativePath));
+}
+/**
+ * Enumerate source files, from the sealed artifact's coverage when there is
+ * one. A sealed repository has no directory tree, so anything that discovers
+ * files by traversal must ask coverage instead of the filesystem.
+ */
+function listSourceFiles(repoPath, accept) {
+    const sealed = sealedRepositories.get(path.resolve(repoPath));
+    if (sealed)
+        return listSealedFiles(sealed).filter(accept);
+    return walkRepoFiles(repoPath, { accept });
+}
+/** Get verbatim source with line numbers, and say so when it is unavailable. */
+function readSourceRange(repoPath, relativePath, startLine, endLine, maxLines) {
+    const whole = readWholeSource(repoPath, relativePath);
+    if (whole.availability.state !== "available")
+        return { text: "", availability: whole.availability };
+    const content = whole.text;
     const lines = content.split("\n");
     const totalLines = endLine - startLine + 1;
     let slice = lines.slice(startLine - 1, endLine);
@@ -8465,7 +8968,30 @@ function getSourceRange(repoPath, relativePath, startLine, endLine, maxLines) {
     if (truncated) {
         result += `\n... (truncated: showing lines ${startLine}-${startLine + slice.length - 1} of ${totalLines} total — use \`query large_functions\` to confirm size, or read the file directly for the remainder)`;
     }
-    return result;
+    return { text: result, availability: { state: "available" } };
+}
+/**
+ * One trimmed source line, used as edge evidence, or undefined if unreadable.
+ *
+ * The map builders previously read this inline and unguarded, so a single
+ * missing file threw and aborted the ENTIRE map rather than costing one edge
+ * its evidence string. Evidence is decoration on an edge; the edge itself is
+ * derived from the graph and stands without it.
+ */
+function evidenceLine(root, relativePath, line) {
+    const whole = readWholeSource(root, relativePath);
+    if (whole.availability.state !== "available")
+        return undefined;
+    return whole.text.split(/\r?\n/)[line - 1]?.trim().slice(0, 240);
+}
+/**
+ * Text-only view of `readSourceRange`, for callers that genuinely do not
+ * surface availability. Kept deliberately thin and separate so that dropping
+ * the availability is a visible choice at the call site rather than the
+ * default behaviour of the only available helper.
+ */
+function getSourceRange(repoPath, relativePath, startLine, endLine, maxLines) {
+    return readSourceRange(repoPath, relativePath, startLine, endLine, maxLines).text;
 }
 /** Recursively traverse backwards from callee to caller to build dependent trees. */
 function _findCallersRecursive(db, targetSymbol, depth, visited = new Set()) {
@@ -10673,7 +11199,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");
@@ -10682,11 +11210,18 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
     const candidateAudits = new Map();
     const candidates = new Map();
     let closed = false;
+    const sealed = openPolicy.mode === "sealed";
     const openDb = (repoPath, options = {}) => getOrInitDb(repoPath, {
         ...options,
-        watcher: options.watcher ?? openPolicy.watcher,
+        watcher: sealed ? "disabled" : (options.watcher ?? openPolicy.watcher),
         watcherFileLimit: options.watcherFileLimit ?? openPolicy.watcherFileLimit,
         databasePath: options.databasePath ?? openPolicy.databasePath,
+        // A sealed artifact has no working tree. Reconciling against the empty
+        // mount would find none of the indexed files on disk and prune every
+        // symbol, so the artifact would answer "not found" for content it
+        // actually carries — a negative that looks entirely correct.
+        skipContentReconciliation: sealed || options.skipContentReconciliation,
+        skipFreshnessGuard: sealed || options.skipFreshnessGuard,
     });
     const claimRepository = (repoPath) => {
         if (closed)
@@ -10891,8 +11426,19 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     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);
+                    const { reflinked } = reflinkCopyFile(source, candidate.databasePath);
+                    candidate.reflinked = reflinked;
                     fs.chmodSync(candidate.databasePath, 0o600);
+                    if (options.sourceLabel) {
+                        const stamp = new Database(candidate.databasePath);
+                        try {
+                            setMeta(stamp, "seededFromWorktree", options.sourceLabel);
+                            setMeta(stamp, "reflinkBacked", String(reflinked));
+                        }
+                        finally {
+                            stamp.close();
+                        }
+                    }
                 }
                 else {
                     await getOrInitDb(resolved, {
@@ -10979,11 +11525,27 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     }
                 }
             }
+            // A candidate populated from a foreign source (a downloaded shared-index
+            // artifact, or another worktree's database) carries index_state mtimes
+            // stamped wherever that source was built -- not this `resolved` checkout.
+            // Every file outside `reconciled` is, by construction, content-identical
+            // to what the caller already verified via its own diff, so refresh only
+            // the mtime/size bookkeeping against this checkout's actual disk instead
+            // of re-parsing/re-embedding: a plain stat, not a re-index.
+            const reconciledSet = new Set(reconciled);
+            const knownPaths = db
+                .query("SELECT filePath FROM index_state")
+                .all()
+                .map((row) => row.filePath)
+                .filter((file) => !reconciledSet.has(file));
+            for (const file of knownPaths)
+                recordIndexState(db, resolved, file);
             await refreshFlowsForApexFiles(db, resolved, reconciled);
             persistSymbolIdentities(db, resolved, reconciled);
             reconcileTypeScriptDi(db, resolved);
             await indexEmbeddings(db, resolved);
             setMeta(db, "lastIndexedHead", gitHead(resolved) ?? "");
+            setMeta(db, "knodinVersion", KNODIN_VERSION);
             setMeta(db, "lastSuccessfulReconciliation", new Date().toISOString());
             recordFreshnessBaseline(resolved, db);
             return { reconciled };
@@ -11049,14 +11611,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);
@@ -11154,7 +11722,12 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
             }
             const summary = primaryDef.summary ||
                 `Symbol "${symbol}" is a ${primaryDef.kind} defined in ${primaryDef.filePath}.`;
-            const source = getSourceRange(targetRepoPath, primaryDef.filePath, primaryDef.startLine, primaryDef.endLine, 500);
+            // Availability is carried, not discarded: an empty `source` here would
+            // otherwise be indistinguishable from the not-found and ambiguous
+            // branches above, which also return "".
+            const sourceRead = readSourceRange(targetRepoPath, primaryDef.filePath, primaryDef.startLine, primaryDef.endLine, 500);
+            const source = sourceRead.text;
+            const sourceAvailability = sourceRead.availability.state === "available" ? undefined : sourceRead.availability;
             // DIRECT callers/callees (depth 1) — the immediate, navigable neighbours.
             // A deep transitive closure is deliberately NOT returned: on a large repo
             // it explodes to thousands of (often name-conflated) nodes and megabytes
@@ -11185,10 +11758,11 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                         confidence: c.confidence,
                         ...(c.kind?.startsWith("di_")
                             ? {
-                                sourceEvidence: fs
-                                    .readFileSync(path.join(c.repoPath || targetRepoPath, c.evidenceFile ?? c.filePath), "utf8")
-                                    .split(/\r?\n/)[(c.evidenceLine ?? c.lineNumber) - 1]?.trim()
-                                    .slice(0, 240) ?? "",
+                                // Was an unguarded read: a single missing file threw and aborted
+                                // the whole `explain`, rather than costing one caller its
+                                // evidence string. `evidenceLine` also serves a sealed
+                                // repository, which has no working tree to read from.
+                                sourceEvidence: evidenceLine(c.repoPath || targetRepoPath, c.evidenceFile ?? c.filePath, c.evidenceLine ?? c.lineNumber) ?? "",
                             }
                             : {}),
                         ...(definition
@@ -11209,15 +11783,7 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     .all(primaryDef.name, primaryDef.filePath)
                     .map((row) => {
                     const separator = row.calleeSymbol.indexOf(":");
-                    let evidence = "";
-                    try {
-                        evidence =
-                            fs
-                                .readFileSync(path.join(targetRepoPath, row.callerFile), "utf8")
-                                .split(/\r?\n/)[row.line - 1]?.trim()
-                                .slice(0, 240) ?? "";
-                    }
-                    catch { }
+                    const evidence = evidenceLine(targetRepoPath, row.callerFile, row.line) ?? "";
                     return {
                         kind: separator < 0 ? "di_unresolved" : row.calleeSymbol.slice(0, separator),
                         reason: separator < 0 ? row.calleeSymbol : row.calleeSymbol.slice(separator + 1),
@@ -11240,12 +11806,16 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                 symbol,
                 summary,
                 source,
+                ...(sourceAvailability ? { sourceAvailability } : {}),
                 callers: allCallers.slice(0, cap),
                 callerCount: allCallers.length,
                 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,
@@ -11283,7 +11853,10 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     let hasTest = false;
                     const testPaths = getTestFilePaths(filePath);
                     for (const tp of testPaths) {
-                        if (fs.existsSync(path.resolve(repoPath, tp))) {
+                        // Sealed repositories have no working tree, so an `fs.existsSync`
+                        // here would report every test file missing and invert the
+                        // meaning of this flag rather than failing visibly.
+                        if (sourceFileExists(repoPath, tp)) {
                             hasTest = true;
                             break;
                         }
@@ -11292,13 +11865,16 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     let tree = null;
                     try {
                         const absPath = path.resolve(repoPath, filePath);
-                        if (fs.existsSync(absPath)) {
-                            const content = fs.readFileSync(absPath, "utf-8");
+                        // Content comes from the resolver so a sealed repository can be
+                        // reviewed; the language is still chosen from the path, which
+                        // needs no working tree.
+                        const source = readWholeSource(repoPath, filePath);
+                        if (source.availability.state === "available") {
                             const lang = await getLanguageForFile(absPath);
                             if (lang) {
                                 const parser = new Parser();
                                 parser.setLanguage(lang);
-                                tree = parser.parse(content);
+                                tree = parser.parse(source.text);
                             }
                         }
                     }
@@ -11675,10 +12251,7 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                         if (!calleeFile || calleeFile === r.callerFile)
                             continue;
                         addExtractedEdge(r.callerFile, calleeFile, r.kind.startsWith("di_") ? r.kind : "calls", r.confidence, r.kind.startsWith("di_")
-                            ? fs
-                                .readFileSync(path.join(resolvedRepoPath, r.callerFile), "utf8")
-                                .split(/\r?\n/)[r.line - 1]?.trim()
-                                .slice(0, 240)
+                            ? evidenceLine(resolvedRepoPath, r.callerFile, r.line)
                             : undefined);
                     }
                     return {
@@ -11792,10 +12365,7 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                         }
                         if (calleePrefixed && calleePrefixed !== callerPrefixed) {
                             addExtractedEdge(callerPrefixed, calleePrefixed, r.kind.startsWith("di_") ? r.kind : "calls", r.confidence, r.kind.startsWith("di_")
-                                ? fs
-                                    .readFileSync(path.join(repo.path, r.callerFile), "utf8")
-                                    .split(/\r?\n/)[r.line - 1]?.trim()
-                                    .slice(0, 240)
+                                ? evidenceLine(repo.path, r.callerFile, r.line)
                                 : undefined);
                         }
                         // 2. Cross-repo Routing: If it does not exist locally but matches endpoints in other repos
@@ -12209,8 +12779,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)
@@ -12253,9 +12827,18 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                 missing: { files: missingFiles, records },
                 lastSuccessfulReconciliation: getMeta(db, "lastSuccessfulReconciliation") ?? null,
                 lastIndexedHead: getMeta(db, "lastIndexedHead") ?? "",
+                seededFromWorktree: getMeta(db, "seededFromWorktree") || undefined,
+                reflinkBacked: (() => {
+                    const value = getMeta(db, "reflinkBacked");
+                    return value === "" || value === null ? undefined : value === "true";
+                })(),
                 freshness,
                 indexGeneration,
-                verification: { mode: "deep-audit", auditVerifiedAt: verifiedAt, verifiedAt },
+                verification: {
+                    mode: "deep-audit",
+                    auditVerifiedAt: verifiedAt,
+                    verifiedAt,
+                },
                 freshnessMechanism: freshnessMechanismFor(resolved, openPolicy),
                 repairSteps: needsRepair
                     ? [
@@ -12636,6 +13219,7 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                             if (after.freshness.state === "stale-head" || after.freshness.state === "unknown") {
                                 setMeta(db, "lastIndexedHead", gitHead(resolved) ?? "");
                             }
+                            setMeta(db, "knodinVersion", KNODIN_VERSION);
                             setMeta(db, "lastSuccessfulReconciliation", new Date().toISOString());
                             recordFreshnessBaseline(resolved, db);
                             statusCache.delete(databaseCacheKey(resolved, openPolicy.databasePath));
@@ -12736,292 +13320,308 @@ 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);
+                        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;");
+                                }
+                                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 });
                         }
-                        else if (fs.existsSync(absPath)) {
-                            await indexFile(absPath, relativePath, repoPath, db);
-                            recordIndexState(db, repoPath, relativePath);
+                        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++;
                         }
-                        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);
+                        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;
                             }
-                            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);
+                        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);
+                        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);
                     }
-                    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;
-                        }
-                    }
-                    catch (_) { }
-                    if (!clean && hasSymbols) {
-                        progress("collecting-files", 0, "Checking existing local graph for changes");
-                        await reconcileIndex(repoPath, db, progress);
+                    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,
+                            },
+                        };
                     }
-                    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))
-                            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, {
+                    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, "knodinVersion", KNODIN_VERSION);
                         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, "knodinVersion", KNODIN_VERSION);
+                            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));
                     }
-                    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);
+                    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 = {}) {
@@ -14051,7 +14651,10 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                         if (!impactOptions.includeDataFlow)
                             return undefined;
                         try {
-                            const text = fs.readFileSync(path.join(resolvedRepoPath, file), "utf8").split("\n")[line - 1];
+                            const whole = readWholeSource(resolvedRepoPath, file);
+                            if (whole.availability.state !== "available")
+                                return undefined;
+                            const text = whole.text.split("\n")[line - 1];
                             if (!text)
                                 return undefined;
                             const escaped = callee.replace(/[.*+?^${}()|[\]\\]/g, String.raw `\$&`);
@@ -14384,11 +14987,8 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     const readSource = (relFile) => {
                         if (sourceCache.has(relFile))
                             return sourceCache.get(relFile) ?? null;
-                        let src = null;
-                        try {
-                            src = fs.readFileSync(path.join(repoPath, relFile), "utf-8");
-                        }
-                        catch { }
+                        const read = readWholeSource(repoPath, relFile);
+                        const src = read.availability.state === "available" ? read.text : null;
                         sourceCache.set(relFile, src);
                         return src;
                     };
@@ -14452,6 +15052,13 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                             return false;
                         if (isTestFilePath(r.filePath))
                             return false;
+                        // Unreadable file: there is no basis to judge this symbol either
+                        // way. Everything below infers "unused" from the ABSENCE of
+                        // evidence, so a failed read silently produced a confident "dead"
+                        // verdict — and acting on that means deleting live code. Unknown
+                        // must not collapse into dead.
+                        if (readSource(r.filePath) === null)
+                            return false;
                         if (isExportedSymbol(r.filePath, r.name)) {
                             const importers = importersByFile.get(r.filePath) ?? [];
                             // An exported symbol in an otherwise unimported file may be a
@@ -14522,7 +15129,7 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                         });
                     if (!destination.selected)
                         return empty("The destination endpoint was not resolved uniquely.");
-                    if (selectedTarget.kind !== "salesforce-metadata" ||
+                    if (selectedTarget.kind !== "salesforce_flow" ||
                         !selectedTarget.filePath.endsWith(".flow-meta.xml") ||
                         !destination.selected.filePath.endsWith(".cls"))
                         return empty("The endpoints are not a supported Salesforce Flow-to-Apex boundary.");
@@ -14530,7 +15137,10 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     const actionName = `${className}.${destination.selected.name}`;
                     let flowEvidence = "";
                     try {
-                        const flowSource = fs.readFileSync(path.join(primary.path, selectedTarget.filePath), "utf8");
+                        const flowRead = readWholeSource(primary.path, selectedTarget.filePath);
+                        if (flowRead.availability.state !== "available")
+                            throw new Error(flowRead.availability.reason);
+                        const flowSource = flowRead.text;
                         const matchingActions = [
                             ...flowSource.matchAll(/<actionCalls>([\s\S]*?)<\/actionCalls>/g),
                         ]
@@ -14864,7 +15474,10 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                                 return undefined;
                             try {
                                 const absolutePath = path.join(resolvedRepoPath, ref.callerFile);
-                                const content = fs.readFileSync(absolutePath, "utf8");
+                                const read = readWholeSource(resolvedRepoPath, ref.callerFile);
+                                if (read.availability.state !== "available")
+                                    return undefined;
+                                const content = read.text;
                                 const language = await getLanguageForFile(absolutePath);
                                 if (!language)
                                     return undefined;
@@ -15056,21 +15669,27 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     }
                     else {
                         inputs = indexed.flatMap(({ filePath }) => {
-                            const absolute = path.join(resolvedRepoPath, filePath);
-                            try {
-                                const content = fs.readFileSync(absolute, "utf8");
-                                if (fileDriftedFromIndexState(db, resolvedRepoPath, filePath))
-                                    diskDrifted = true;
-                                return [{ path: filePath, content }];
-                            }
-                            catch {
+                            const read = readWholeSource(resolvedRepoPath, filePath);
+                            if (read.availability.state !== "available") {
                                 diskDrifted = true;
                                 return [];
                             }
+                            // Drift is a working-tree concept: a sealed artifact's bytes
+                            // came from the attested commit and cannot have moved since,
+                            // and the mtime/size comparison would report every file
+                            // drifted because there is no file to stat.
+                            if (!isSealedRepository(resolvedRepoPath) &&
+                                fileDriftedFromIndexState(db, resolvedRepoPath, filePath))
+                                diskDrifted = true;
+                            return [{ path: filePath, content: read.text }];
                         });
                         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 +15699,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 +15712,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
@@ -15105,8 +15730,10 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                             : undefined;
                     if (!language)
                         return finish([]);
-                    const content = fs.readFileSync(path.join(resolvedRepoPath, selectedTarget.filePath), "utf8");
-                    const sourceLines = content.split(/\r?\n/);
+                    const flowRead = readWholeSource(resolvedRepoPath, selectedTarget.filePath);
+                    if (flowRead.availability.state !== "available")
+                        return finish([]);
+                    const sourceLines = flowRead.text.split(/\r?\n/);
                     const functionLines = sourceLines.slice(selectedTarget.startLine - 1, selectedTarget.endLine);
                     const facts = [];
                     const variableFilter = options.flowVariable;