knodin 0.9.0 → 0.10.0

package/dist/src/engine/index.js

@@ -32,10 +32,16 @@ import { allocateCandidate, assertCandidate, discardCandidateFiles, promoteCandi
 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";
@@ -501,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.
                 //
@@ -784,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 = 23;
-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;
@@ -1126,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)) {
@@ -1286,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)
@@ -3181,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);
         }
     }
@@ -3213,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, {
@@ -3250,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;
@@ -3396,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;
 }
 /**
@@ -3440,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")
@@ -3451,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;
         })());
 }
 /**
@@ -3489,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);
@@ -3551,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)
@@ -3597,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 `\$&`);
@@ -3753,6 +3772,71 @@ 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) => {
@@ -3773,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;
@@ -3864,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 (?, ?, ?, ?, ?, ?, ?, ?)`);
@@ -3912,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) {
@@ -5894,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.
+ *
+ * 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.
+ */
+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`.
  *
- * `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.
+ * 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.
  */
-async function indexFile(absolutePath, relativePath, repoPath, db, unparsed) {
+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) {
@@ -7211,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");
@@ -7230,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, "--"], {
@@ -7240,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 {
@@ -7250,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
@@ -7347,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;
@@ -7726,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);
@@ -7751,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)));
@@ -7947,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)
@@ -8233,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,
@@ -8467,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);
@@ -8485,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()) {
@@ -10704,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)
@@ -10913,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, {
@@ -11001,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 };
@@ -11182,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
@@ -11213,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
@@ -11237,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),
@@ -11268,6 +11806,7 @@ 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),
@@ -11314,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;
                         }
@@ -11323,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);
                             }
                         }
                     }
@@ -11706,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 {
@@ -11823,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
@@ -12288,6 +12827,11 @@ 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: {
@@ -12675,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));
@@ -13014,6 +13559,7 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     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));
@@ -13031,6 +13577,7 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                         // 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);
                         }
@@ -14104,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 `\$&`);
@@ -14437,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;
                     };
@@ -14505,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
@@ -14575,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.");
@@ -14583,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),
                         ]
@@ -14917,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;
@@ -15109,17 +15669,19 @@ 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)
@@ -15168,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;