@wrongstack/tools 0.306.4 → 0.307.0

package/dist/codebase-index/project-server.js

@@ -566,17 +566,44 @@ function fallbackParse(filePath, content, lang) {
     const col = line.length - trimmed.length + 1;
     const fn = /^func\s+(?:\([^)]*\)\s*)?([A-Za-z_]\w*)\s*\(/.exec(trimmed);
     if (fn?.[1]) {
-      addFallbackSymbol(symbols, { filePath, lang, kind: trimmed.startsWith("func (") ? "method" : "function", name: fn[1], line: idx + 1, col, signature: trimmed, scope: packageName ? `${packageName}.${fn[1]}` : fn[1] });
+      addFallbackSymbol(symbols, {
+        filePath,
+        lang,
+        kind: trimmed.startsWith("func (") ? "method" : "function",
+        name: fn[1],
+        line: idx + 1,
+        col,
+        signature: trimmed,
+        scope: packageName ? `${packageName}.${fn[1]}` : fn[1]
+      });
       continue;
     }
     const typeDecl = /^type\s+([A-Za-z_]\w*)\b/.exec(trimmed);
     if (typeDecl?.[1]) {
-      addFallbackSymbol(symbols, { filePath, lang, kind: "type", name: typeDecl[1], line: idx + 1, col, signature: trimmed, scope: packageName });
+      addFallbackSymbol(symbols, {
+        filePath,
+        lang,
+        kind: "type",
+        name: typeDecl[1],
+        line: idx + 1,
+        col,
+        signature: trimmed,
+        scope: packageName
+      });
       continue;
     }
     const valueDecl = /^(const|var)\s+([A-Za-z_]\w*)\b/.exec(trimmed);
     if (valueDecl?.[1] && valueDecl[2]) {
-      addFallbackSymbol(symbols, { filePath, lang, kind: valueDecl[1], name: valueDecl[2], line: idx + 1, col, signature: trimmed, scope: packageName });
+      addFallbackSymbol(symbols, {
+        filePath,
+        lang,
+        kind: valueDecl[1],
+        name: valueDecl[2],
+        line: idx + 1,
+        col,
+        signature: trimmed,
+        scope: packageName
+      });
     }
   }
   return { file: filePath, lang, symbols, mtimeMs: Date.now() };
@@ -1027,7 +1054,10 @@ function parseGeneric(opts) {
   const seen = /* @__PURE__ */ new Set();
   const nlOffsets = newlineOffsets2(content);
   for (const pattern of patterns) {
-    const re = new RegExp(pattern.re.source, pattern.re.flags.includes("g") ? pattern.re.flags : `${pattern.re.flags}g`);
+    const re = new RegExp(
+      pattern.re.source,
+      pattern.re.flags.includes("g") ? pattern.re.flags : `${pattern.re.flags}g`
+    );
     re.lastIndex = 0;
     for (const match of content.matchAll(re)) {
       if (symbols.length >= maxSymbols) break;
@@ -1134,7 +1164,10 @@ var init_generic_parser = __esm({
       ],
       kotlin: [
         { re: /\b(?:fun)\s+([A-Za-z_]\w*)/g, kind: "function" },
-        { re: /\b(?:class|interface|object|enum\s+class|data\s+class)\s+([A-Za-z_]\w*)/g, kind: "class" }
+        {
+          re: /\b(?:class|interface|object|enum\s+class|data\s+class)\s+([A-Za-z_]\w*)/g,
+          kind: "class"
+        }
       ],
       scala: [
         { re: /\b(?:def)\s+([A-Za-z_]\w*)/g, kind: "function" },
@@ -1145,14 +1178,13 @@ var init_generic_parser = __esm({
         { re: /^([A-Za-z_][\w]*)\s*\(\)\s*\{/gm, kind: "function" }
       ],
       sql: [
-        { re: /\bCREATE\s+(?:OR\s+REPLACE\s+)?(?:TABLE|VIEW|INDEX|FUNCTION|PROCEDURE|TRIGGER)\s+(?:IF\s+NOT\s+EXISTS\s+)?([A-Za-z_"][\w."]*)/gi, kind: "type" }
-      ],
-      md: [
-        { re: /^(#{1,6})\s+(.+)$/gm, kind: "namespace" }
-      ],
-      toml: [
-        { re: /^\[([^\]]+)\]/gm, kind: "namespace" }
+        {
+          re: /\bCREATE\s+(?:OR\s+REPLACE\s+)?(?:TABLE|VIEW|INDEX|FUNCTION|PROCEDURE|TRIGGER)\s+(?:IF\s+NOT\s+EXISTS\s+)?([A-Za-z_"][\w."]*)/gi,
+          kind: "type"
+        }
       ],
+      md: [{ re: /^(#{1,6})\s+(.+)$/gm, kind: "namespace" }],
+      toml: [{ re: /^\[([^\]]+)\]/gm, kind: "namespace" }],
       html: [
         { re: /\bid\s*=\s*["']([^"']+)["']/gi, kind: "property" },
         { re: /<(?:script|template|style)\b/gi, kind: "namespace" }
@@ -1162,11 +1194,17 @@ var init_generic_parser = __esm({
         { re: /@(?:keyframes|media|supports)\s+([^{\s]+)/g, kind: "namespace" }
       ],
       vue: [
-        { re: /\b(?:function|const|let|var|class|export\s+(?:default\s+)?(?:function|class|const))\s+([A-Za-z_]\w*)/g, kind: "function" },
+        {
+          re: /\b(?:function|const|let|var|class|export\s+(?:default\s+)?(?:function|class|const))\s+([A-Za-z_]\w*)/g,
+          kind: "function"
+        },
         { re: /<(?:script|template|style)\b/gi, kind: "namespace" }
       ],
       svelte: [
-        { re: /\b(?:function|const|let|var|class|export\s+(?:default\s+)?(?:function|class|const))\s+([A-Za-z_]\w*)/g, kind: "function" }
+        {
+          re: /\b(?:function|const|let|var|class|export\s+(?:default\s+)?(?:function|class|const))\s+([A-Za-z_]\w*)/g,
+          kind: "function"
+        }
       ],
       dart: [
         { re: /\b(?:class|enum|mixin|extension)\s+([A-Za-z_]\w*)/g, kind: "class" },
@@ -1380,12 +1418,7 @@ async function syncPyParse(filePath, content, lang) {
     cachedPyBinary ??= resolvePython();
     const pyBinary = await cachedPyBinary;
     if (!pyBinary) return null;
-    const { code, stdout } = await spawnPyParser(
-      pyBinary,
-      _cachedScriptPath,
-      filePath,
-      content
-    );
+    const { code, stdout } = await spawnPyParser(pyBinary, _cachedScriptPath, filePath, content);
     if (code !== 0 || !stdout.trim()) {
       return { file: filePath, lang, symbols: [], mtimeMs: Date.now() };
     }
@@ -2579,7 +2612,8 @@ __export(tree_sitter_parser_exports, {
   getGrammarWasmPath: () => getGrammarWasmPath,
   isTreeSitterSupported: () => isTreeSitterSupported,
   loadTreeSitterLanguage: () => loadTreeSitterLanguage,
-  parseSymbols: () => parseSymbols8
+  parseSymbols: () => parseSymbols8,
+  parseTreeSitterAst: () => parseTreeSitterAst
 });
 import * as path9 from "node:path";
 import { fileURLToPath } from "node:url";
@@ -2671,6 +2705,26 @@ async function __smokeRootType(opts) {
     parser.delete();
   }
 }
+async function parseTreeSitterAst(opts) {
+  const grammar = resolveGrammarName(opts.lang) ?? (opts.lang === "go" ? "go" : opts.lang === "py" ? "python" : opts.lang === "rs" ? "rust" : void 0);
+  if (!grammar) return null;
+  try {
+    const { Parser, Language, init } = await getRuntime();
+    await init();
+    const wasmPath = path9.join(WASM_DIR, grammar, `tree-sitter-${grammar}.wasm`);
+    const languageObj = await Language.load(wasmPath);
+    const parser = new Parser();
+    parser.setLanguage(languageObj);
+    const tree = parser.parse(opts.content);
+    if (!tree) {
+      parser.delete();
+      return null;
+    }
+    return { tree, parser };
+  } catch {
+    return null;
+  }
+}
 var WASM_DIR, RUNTIME_WASM, LANG_TO_GRAMMAR, GO_OPT_IN, PY_OPT_IN, RS_OPT_IN, runtimePromise, languageCache;
 var init_tree_sitter_parser = __esm({
   "src/codebase-index/tree-sitter-parser.ts"() {
@@ -3482,10 +3536,7 @@ var LANG_IMPORTS = {
     // quoted path. A stray match elsewhere resolves to no file and is dropped.
     { re: /^[ \t]*(?:[A-Za-z_.]\w*\s+)?"([^"]+)"\s*$/gm }
   ],
-  py: [
-    { re: /^[ \t]*import\s+([\w.]+)/gm },
-    { re: /^[ \t]*from\s+([.\w]+)\s+import\b/gm }
-  ],
+  py: [{ re: /^[ \t]*import\s+([\w.]+)/gm }, { re: /^[ \t]*from\s+([.\w]+)\s+import\b/gm }],
   rs: [
     // use a::b::C;  |  use a::b::{C, D};  → the path before any brace
     { re: /^[ \t]*(?:pub\s+)?use\s+([\w:]+?)(?:::\{|\s*;|\s+as\b)/gm },
@@ -3822,10 +3873,7 @@ function defaultWorkerCount() {
   return Math.max(1, Math.min(4, cores - 1));
 }
 function resolveWorkerScriptUrl() {
-  for (const rel of [
-    "./parser-worker-script.js",
-    "./codebase-index/parser-worker-script.js"
-  ]) {
+  for (const rel of ["./parser-worker-script.js", "./codebase-index/parser-worker-script.js"]) {
     try {
       const url = new URL(rel, import.meta.url);
       if (url.protocol === "file:" && fs6.existsSync(fileURLToPath2(url))) return url;
@@ -3841,7 +3889,6 @@ function getParserPool() {
 }
 
 // src/codebase-index/writer.ts
-import { expectDefined as expectDefined4 } from "@wrongstack/core/utils";
 import * as fs8 from "node:fs";
 import * as path11 from "node:path";
 
@@ -3937,39 +3984,6 @@ var Bm25Index = class {
 // src/codebase-index/writer.ts
 init_languages();
 
-// src/codebase-index/lsp-kind.ts
-function lspKindToInternalKind(k) {
-  switch (k) {
-    case 5 /* Class */:
-      return "class";
-    case 6 /* Method */:
-      return "method";
-    case 7 /* Property */:
-    case 8 /* Field */:
-      return "property";
-    case 9 /* Constructor */:
-      return "class";
-    case 10 /* Enum */:
-      return "enum";
-    case 11 /* Interface */:
-      return "interface";
-    case 12 /* Function */:
-      return "function";
-    case 13 /* Variable */:
-      return "var";
-    case 14 /* Constant */:
-      return "const";
-    case 22 /* EnumMember */:
-      return "enum";
-    case 26 /* TypeParameter */:
-      return "type";
-    case 3 /* Namespace */:
-      return "namespace";
-    default:
-      return null;
-  }
-}
-
 // src/codebase-index/schema.ts
 var SCHEMA_VERSION = 4;
 
@@ -4116,91 +4130,14 @@ function runSqliteWithRetry(fn) {
   throw lastError;
 }
 
-// src/codebase-index/vector-search.ts
-var RRF_K = 60;
-var VECTOR_DIMENSIONS = 384;
-var NGRAM_SIZE = 3;
-function embedText(text) {
-  const vec = new Float32Array(VECTOR_DIMENSIONS);
-  const normalized = text.toLowerCase().trim();
-  if (normalized.length < NGRAM_SIZE) {
-    const padded = ` ${normalized} `.slice(0, Math.max(NGRAM_SIZE, normalized.length + 2));
-    for (let i = 0; i <= padded.length - NGRAM_SIZE; i++) {
-      const ngram = padded.slice(i, i + NGRAM_SIZE);
-      const bucket = hashNgram(ngram) % VECTOR_DIMENSIONS;
-      vec[bucket] += 1;
-    }
-  } else {
-    for (let i = 0; i <= normalized.length - NGRAM_SIZE; i++) {
-      const ngram = normalized.slice(i, i + NGRAM_SIZE);
-      const bucket = hashNgram(ngram) % VECTOR_DIMENSIONS;
-      vec[bucket] += 1;
-    }
-  }
-  let norm = 0;
-  for (let i = 0; i < VECTOR_DIMENSIONS; i++) {
-    norm += vec[i] * vec[i];
-  }
-  norm = Math.sqrt(norm);
-  if (norm > 0) {
-    for (let i = 0; i < VECTOR_DIMENSIONS; i++) {
-      vec[i] /= norm;
-    }
-  }
-  return vec;
-}
-function hashNgram(str) {
-  let hash = 2166136261;
-  for (let i = 0; i < str.length; i++) {
-    hash ^= str.charCodeAt(i);
-    hash = Math.imul(hash, 16777619);
-  }
-  return hash >>> 0;
-}
-function cosineSimilarity(a, b) {
-  let dot = 0;
-  const len = Math.min(a.length, b.length);
-  for (let i = 0; i < len; i++) {
-    dot += a[i] * b[i];
-  }
-  return dot;
-}
-function encodeVector(vec) {
-  return Buffer.from(vec.buffer, vec.byteOffset, vec.byteLength);
-}
-function decodeVector(buf) {
-  const view = new DataView(
-    buf.buffer,
-    buf.byteOffset,
-    buf.byteLength
-  );
-  const copy = new Float32Array(buf.byteLength / 4);
-  for (let i = 0; i < copy.length; i++) {
-    copy[i] = view.getFloat32(i * 4, true);
-  }
-  return copy;
-}
-function reciprocalRankFusion(bm25Ranks, vectorRanks, k = RRF_K) {
-  const allIds = /* @__PURE__ */ new Set([...bm25Ranks.keys(), ...vectorRanks.keys()]);
-  const scored = [];
-  for (const id of allIds) {
-    const bm25Rank = bm25Ranks.get(id);
-    const vecRank = vectorRanks.get(id);
-    let score = 0;
-    if (bm25Rank !== void 0) score += 1 / (k + bm25Rank);
-    if (vecRank !== void 0) score += 1 / (k + vecRank);
-    scored.push([id, score]);
-  }
-  scored.sort((a, b) => b[1] - a[1]);
-  return scored;
-}
-
 // src/codebase-index/writer-admin.ts
 import * as fs7 from "node:fs";
 import * as path10 from "node:path";
 var DB_FILE = "index.db";
 function getAllIndexableWithStatement(stmt) {
-  return stmt("SELECT id, text FROM symbols").all().map(({ id, text }) => ({ id, text }));
+  return stmt("SELECT id, text FROM symbols").all().map(
+    ({ id, text }) => ({ id, text })
+  );
 }
 function getMaxSymbolIdWithStatement(stmt) {
   const rows = stmt("SELECT MAX(id) AS m FROM symbols").all();
@@ -4540,7 +4477,8 @@ function resolveSymbolIds(stmt, symbolName, file) {
 }
 function findIncomingCallsByName(stmt, symbolName, file, limit) {
   const targetIds = resolveSymbolIds(stmt, symbolName, file);
-  if (targetIds.length === 0) return { calls: [], symbolFound: false, ambiguous: false, totalMatches: 0 };
+  if (targetIds.length === 0)
+    return { calls: [], symbolFound: false, ambiguous: false, totalMatches: 0 };
   let matchIds = targetIds;
   let ambiguous = false;
   if (file !== void 0) {
@@ -4591,11 +4529,17 @@ function findIncomingCallsByName(stmt, symbolName, file, limit) {
   }
   rows.sort((a, b) => a.ref_line - b.ref_line || a.sym_id - b.sym_id);
   const allCalls = rows.map(mapCallSiteRow);
-  return { calls: allCalls.slice(0, limit), symbolFound: true, ambiguous, totalMatches: allCalls.length };
+  return {
+    calls: allCalls.slice(0, limit),
+    symbolFound: true,
+    ambiguous,
+    totalMatches: allCalls.length
+  };
 }
 function findOutgoingCallsByName(stmt, symbolName, file, limit) {
   const sourceIds = resolveSymbolIds(stmt, symbolName, file);
-  if (sourceIds.length === 0) return { calls: [], symbolFound: false, unresolvedCount: 0, totalMatches: 0 };
+  if (sourceIds.length === 0)
+    return { calls: [], symbolFound: false, unresolvedCount: 0, totalMatches: 0 };
   const unresolvedCount = chunkedIdScalar(
     stmt,
     sourceIds,
@@ -4999,6 +4943,184 @@ function resolveIndexDir(projectRoot2, override) {
   return override ?? resolveWstackPaths({ projectRoot: projectRoot2 }).projectCodebaseIndex;
 }
 
+// src/codebase-index/vector-search.ts
+var RRF_K = 60;
+var VECTOR_DIMENSIONS = 384;
+var NGRAM_SIZE = 3;
+function embedText(text) {
+  const vec = new Float32Array(VECTOR_DIMENSIONS);
+  const normalized = text.toLowerCase().trim();
+  if (normalized.length < NGRAM_SIZE) {
+    const padded = ` ${normalized} `.slice(0, Math.max(NGRAM_SIZE, normalized.length + 2));
+    for (let i = 0; i <= padded.length - NGRAM_SIZE; i++) {
+      const ngram = padded.slice(i, i + NGRAM_SIZE);
+      const bucket = hashNgram(ngram) % VECTOR_DIMENSIONS;
+      vec[bucket] += 1;
+    }
+  } else {
+    for (let i = 0; i <= normalized.length - NGRAM_SIZE; i++) {
+      const ngram = normalized.slice(i, i + NGRAM_SIZE);
+      const bucket = hashNgram(ngram) % VECTOR_DIMENSIONS;
+      vec[bucket] += 1;
+    }
+  }
+  let norm = 0;
+  for (let i = 0; i < VECTOR_DIMENSIONS; i++) {
+    norm += vec[i] * vec[i];
+  }
+  norm = Math.sqrt(norm);
+  if (norm > 0) {
+    for (let i = 0; i < VECTOR_DIMENSIONS; i++) {
+      vec[i] /= norm;
+    }
+  }
+  return vec;
+}
+function hashNgram(str) {
+  let hash = 2166136261;
+  for (let i = 0; i < str.length; i++) {
+    hash ^= str.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}
+function cosineSimilarity(a, b) {
+  let dot = 0;
+  const len = Math.min(a.length, b.length);
+  for (let i = 0; i < len; i++) {
+    dot += a[i] * b[i];
+  }
+  return dot;
+}
+function encodeVector(vec) {
+  return Buffer.from(vec.buffer, vec.byteOffset, vec.byteLength);
+}
+function decodeVector(buf) {
+  const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+  const copy = new Float32Array(buf.byteLength / 4);
+  for (let i = 0; i < copy.length; i++) {
+    copy[i] = view.getFloat32(i * 4, true);
+  }
+  return copy;
+}
+function reciprocalRankFusion(bm25Ranks, vectorRanks, k = RRF_K) {
+  const allIds = /* @__PURE__ */ new Set([...bm25Ranks.keys(), ...vectorRanks.keys()]);
+  const scored = [];
+  for (const id of allIds) {
+    const bm25Rank = bm25Ranks.get(id);
+    const vecRank = vectorRanks.get(id);
+    let score = 0;
+    if (bm25Rank !== void 0) score += 1 / (k + bm25Rank);
+    if (vecRank !== void 0) score += 1 / (k + vecRank);
+    scored.push([id, score]);
+  }
+  scored.sort((a, b) => b[1] - a[1]);
+  return scored;
+}
+
+// src/codebase-index/writer-mutations.ts
+function commitBatchWithStatement(stmtFn, maxSqlVars, ftsAvailable, vectorsAvailable, allocateSymbolIds, invalidateIncomingRefsForFiles, resolveRefsForNamesUnsafe2, entries, options = {}) {
+  if (entries.length === 0 && (options.deleteForFiles?.length ?? 0) === 0) {
+    return [];
+  }
+  const affectedNames = /* @__PURE__ */ new Set();
+  for (const entry of entries) {
+    for (const symbol of entry.symbols) affectedNames.add(symbol.name);
+    for (const ref of entry.refs) affectedNames.add(ref.toName);
+  }
+  if (options.deleteForFiles && options.deleteForFiles.length > 0) {
+    const placeholders = options.deleteForFiles.map(() => "?").join(",");
+    for (const name of invalidateIncomingRefsForFiles(options.deleteForFiles)) {
+      affectedNames.add(name);
+    }
+    if (ftsAvailable) {
+      stmtFn(
+        `DELETE FROM symbols_fts WHERE rowid IN (SELECT id FROM symbols WHERE file IN (${placeholders}))`
+      ).run(...options.deleteForFiles);
+    }
+    if (vectorsAvailable) {
+      stmtFn(
+        `DELETE FROM symbol_vectors WHERE symbol_id IN (SELECT id FROM symbols WHERE file IN (${placeholders}))`
+      ).run(...options.deleteForFiles);
+    }
+    stmtFn(
+      `DELETE FROM refs WHERE from_id IN (SELECT id FROM symbols WHERE file IN (${placeholders}))`
+    ).run(...options.deleteForFiles);
+    stmtFn(`DELETE FROM symbols WHERE file IN (${placeholders})`).run(...options.deleteForFiles);
+  }
+  const totalSymbols = entries.reduce((n, e) => n + e.symbols.length, 0);
+  let nextId = allocateSymbolIds(totalSymbols);
+  const allInserted = [];
+  const refsToInsert = [];
+  const bulkSyms = [];
+  const ftsRows = [];
+  const vectorRows = [];
+  for (const entry of entries) {
+    const insertedForEntry = [];
+    for (const s of entry.symbols) {
+      const id = nextId++;
+      bulkSyms.push({
+        id,
+        lang: s.lang,
+        kind: s.kind,
+        name: s.name,
+        file: s.file,
+        line: s.line,
+        col: s.col,
+        signature: s.signature,
+        docComment: s.docComment,
+        scope: s.scope,
+        text: s.text
+      });
+      if (ftsAvailable) {
+        ftsRows.push({
+          id,
+          text: buildIndexableText(s.name, s.signature, s.docComment)
+        });
+      }
+      vectorRows.push({
+        id,
+        vector: encodeVector(
+          embedText(s.text || buildIndexableText(s.name, s.signature, s.docComment))
+        )
+      });
+      const inserted = { ...s, id };
+      allInserted.push(inserted);
+      insertedForEntry.push(inserted);
+    }
+    refsToInsert.push(...assignRefsToSymbols(entry.refs, insertedForEntry));
+  }
+  bulkInsertSymbolsWithStatement((sql) => stmtFn(sql), maxSqlVars, bulkSyms);
+  bulkInsertFtsWithStatement((sql) => stmtFn(sql), maxSqlVars, ftsAvailable, ftsRows);
+  if (vectorsAvailable) {
+    bulkInsertVectorsWithStatement((sql) => stmtFn(sql), maxSqlVars, vectorRows);
+  }
+  bulkInsertRefsWithStatement((sql) => stmtFn(sql), maxSqlVars, refsToInsert);
+  const upsertStmt = stmtFn(
+    `INSERT INTO files(file, lang, mtime_ms, content_hash, symbol_count, last_indexed)
+     VALUES (?, ?, ?, ?, ?, ?)
+     ON CONFLICT(file) DO UPDATE SET
+       lang = excluded.lang,
+       mtime_ms = excluded.mtime_ms,
+       content_hash = excluded.content_hash,
+       symbol_count = excluded.symbol_count,
+       last_indexed = excluded.last_indexed`
+  );
+  const now = Date.now();
+  for (const entry of entries) {
+    upsertStmt.run(
+      entry.file,
+      entry.lang,
+      entry.mtimeMs,
+      entry.contentHash ?? "",
+      entry.symbolCount,
+      now
+    );
+  }
+  resolveRefsForNamesUnsafe2(affectedNames);
+  return allInserted;
+}
+
 // src/codebase-index/writer-pragmas.ts
 import { sqliteCachePragmas } from "@wrongstack/core/utils";
 function applyIndexStorePragmas(db) {
@@ -5111,24 +5233,255 @@ var SYMBOL_VECTORS_TABLE_SQL = `
   );
 `;
 
-// src/codebase-index/writer-search-helpers.ts
-var SEARCH_CANDIDATE_SCAN_CAP = 5e3;
-function normalizeSearchLimit(limit) {
-  return typeof limit === "number" && Number.isFinite(limit) ? Math.max(0, Math.trunc(limit)) : void 0;
+// src/codebase-index/writer-refs.ts
+var FAMILY_MATCH_SQL = `(
+  sym.lang = refs.lang
+  OR EXISTS (
+    SELECT 1 FROM lang_family lf1
+      JOIN lang_family lf2 ON lf1.family = lf2.family
+     WHERE lf1.lang = sym.lang AND lf2.lang = refs.lang
+  )
+  OR ? IN (
+    SELECT family FROM lang_family WHERE lang = refs.lang
+  )
+)`;
+function getNamespaceDeclarationsWithStatement(stmtFn) {
+  return stmtFn(
+    `SELECT name, file FROM symbols WHERE kind = 'namespace' ORDER BY file, id`
+  ).all();
 }
-function buildWriterSearchWhere(query, filter) {
-  const conditions = [];
-  const values = [];
-  let effectiveKind = filter?.kind;
-  if (filter?.lspKind !== void 0) {
-    const mapped = lspKindToInternalKind(filter.lspKind);
-    if (mapped !== null) {
-      effectiveKind = mapped;
-    } else {
-      return null;
-    }
+function getFilePackagesWithStatement(stmtFn) {
+  const rows = stmtFn("SELECT file, package FROM files WHERE package != ''").all();
+  return new Map(rows.map((row) => [row.file, row.package]));
+}
+function getUnresolvedImportsWithStatement(stmtFn, maxSqlVars, onlyFiles) {
+  const base = `SELECT DISTINCT s.file AS fromFile, r.lang AS lang, r.module AS module
+                  FROM refs r
+                  JOIN symbols s ON s.id = r.from_id
+                 WHERE r.call_type = 'import' AND r.module IS NOT NULL`;
+  if (!onlyFiles?.length) {
+    return stmtFn(base).all();
   }
-  if (effectiveKind) {
+  const out = [];
+  for (let i = 0; i < onlyFiles.length; i += maxSqlVars) {
+    const chunk = onlyFiles.slice(i, i + maxSqlVars);
+    const placeholders = chunk.map(() => "?").join(",");
+    out.push(
+      ...stmtFn(`${base} AND s.file IN (${placeholders})`).all(...chunk)
+    );
+  }
+  return out;
+}
+function getAllResolvedRefsWithStatement(stmtFn) {
+  return stmtFn(
+    "SELECT from_id AS fromId, to_id AS toId, call_type AS callType FROM refs WHERE to_id IS NOT NULL"
+  ).all();
+}
+function getAllImportRefsWithStatement(stmtFn) {
+  return stmtFn(
+    `SELECT s.file AS sourceFile, r.to_name AS toName, r.to_id AS toId,
+            r.call_type AS callType, r.line
+     FROM refs r
+     LEFT JOIN symbols s ON r.from_id = s.id
+     WHERE r.call_type = 'import'
+     ORDER BY r.line`
+  ).all();
+}
+function resolveRefsWithStatement(stmtFn) {
+  try {
+    const result = stmtFn(
+      `UPDATE refs
+       SET to_id = s.id
+       FROM (
+             SELECT sym.name AS name, lf.family AS family, MIN(sym.id) AS id
+               FROM symbols sym
+               JOIN lang_family lf ON lf.lang = sym.lang
+              GROUP BY sym.name, lf.family
+             UNION ALL
+             SELECT sym.name AS name, '${LANG_FAMILY_WILDCARD}' AS family, MIN(sym.id) AS id
+               FROM symbols sym
+              GROUP BY sym.name
+           ) AS s,
+           lang_family AS rf
+       WHERE refs.to_id IS NULL
+         AND refs.to_name IS NOT NULL
+         AND rf.lang = refs.lang
+         AND s.name = refs.to_name
+         AND s.family = rf.family`
+    ).run();
+    return result.changes ?? 0;
+  } catch {
+    const result = stmtFn(
+      `UPDATE refs SET to_id = (
+         SELECT sym.id FROM symbols sym
+          WHERE sym.name = refs.to_name AND ${FAMILY_MATCH_SQL}
+          ORDER BY sym.id LIMIT 1
+       ) WHERE to_id IS NULL AND to_name IS NOT NULL
+         AND EXISTS (
+           SELECT 1 FROM symbols sym
+            WHERE sym.name = refs.to_name AND ${FAMILY_MATCH_SQL}
+         )`
+    ).run(LANG_FAMILY_WILDCARD, LANG_FAMILY_WILDCARD);
+    return result.changes ?? 0;
+  }
+}
+function applyImportResolutionsWithStatement(db, stmtFn, runWithRetry, maxSqlVars, resolutions) {
+  if (resolutions.length === 0) return 0;
+  return runWithRetry(() => {
+    db.exec("DROP TABLE IF EXISTS temp.import_resolution");
+    db.exec(
+      `CREATE TEMP TABLE import_resolution (
+         from_file TEXT NOT NULL,
+         lang TEXT NOT NULL,
+         module TEXT NOT NULL,
+         to_file TEXT NOT NULL
+       )`
+    );
+    const chunkSize = Math.max(1, Math.floor(maxSqlVars / 4));
+    for (let i = 0; i < resolutions.length; i += chunkSize) {
+      const chunk = resolutions.slice(i, i + chunkSize);
+      const placeholders = chunk.map(() => "(?, ?, ?, ?)").join(", ");
+      const binds = [];
+      for (const entry of chunk) {
+        binds.push(entry.fromFile, entry.lang, entry.module, entry.toFile);
+      }
+      stmtFn(
+        `INSERT INTO temp.import_resolution(from_file, lang, module, to_file)
+         VALUES ${placeholders}`
+      ).run(...binds);
+    }
+    db.exec(
+      `CREATE INDEX IF NOT EXISTS temp.idx_ir
+         ON import_resolution(module, lang, from_file)`
+    );
+    const result = stmtFn(
+      `UPDATE refs
+          SET to_file = (
+            SELECT ir.to_file
+              FROM temp.import_resolution ir
+              JOIN symbols s ON s.id = refs.from_id
+             WHERE ir.module = refs.module
+               AND ir.lang = refs.lang
+               AND ir.from_file = s.file
+             LIMIT 1
+          )
+        WHERE refs.call_type = 'import'
+          AND refs.module IS NOT NULL
+          AND EXISTS (
+            SELECT 1
+              FROM temp.import_resolution ir
+              JOIN symbols s ON s.id = refs.from_id
+             WHERE ir.module = refs.module
+               AND ir.lang = refs.lang
+               AND ir.from_file = s.file
+          )`
+    ).run();
+    db.exec("DROP TABLE IF EXISTS temp.import_resolution");
+    return result.changes ?? 0;
+  });
+}
+function resolveRefsForNamesUnsafe(stmtFn, maxSqlVars, names) {
+  const list = [...names].filter((name) => name.length > 0);
+  if (list.length === 0) return 0;
+  let total = 0;
+  for (let i = 0; i < list.length; i += maxSqlVars) {
+    const chunk = list.slice(i, i + maxSqlVars);
+    const placeholders = chunk.map(() => "?").join(",");
+    try {
+      const result = stmtFn(
+        `UPDATE refs
+         SET to_id = s.id
+         FROM (
+               SELECT sym.name AS name, lf.family AS family, MIN(sym.id) AS id
+                 FROM symbols sym
+                 JOIN lang_family lf ON lf.lang = sym.lang
+                WHERE sym.name IN (${placeholders})
+                GROUP BY sym.name, lf.family
+               UNION ALL
+               SELECT sym.name AS name, '${LANG_FAMILY_WILDCARD}' AS family, MIN(sym.id) AS id
+                 FROM symbols sym
+                WHERE sym.name IN (${placeholders})
+                GROUP BY sym.name
+             ) AS s,
+             lang_family AS rf
+         WHERE refs.to_name IN (${placeholders})
+           AND rf.lang = refs.lang
+           AND s.name = refs.to_name
+           AND s.family = rf.family`
+      ).run(...chunk, ...chunk, ...chunk);
+      total += result.changes ?? 0;
+    } catch {
+      const result = stmtFn(
+        `UPDATE refs SET to_id = (
+           SELECT sym.id FROM symbols sym
+            WHERE sym.name = refs.to_name AND ${FAMILY_MATCH_SQL}
+            ORDER BY sym.id LIMIT 1
+         ) WHERE refs.to_name IN (${placeholders})
+           AND EXISTS (
+             SELECT 1 FROM symbols sym
+              WHERE sym.name = refs.to_name AND ${FAMILY_MATCH_SQL}
+           )`
+      ).run(LANG_FAMILY_WILDCARD, ...chunk, LANG_FAMILY_WILDCARD);
+      total += result.changes ?? 0;
+    }
+  }
+  return total;
+}
+
+// src/codebase-index/writer-search.ts
+import { expectDefined as expectDefined4 } from "@wrongstack/core/utils";
+
+// src/codebase-index/lsp-kind.ts
+function lspKindToInternalKind(k) {
+  switch (k) {
+    case 5 /* Class */:
+      return "class";
+    case 6 /* Method */:
+      return "method";
+    case 7 /* Property */:
+    case 8 /* Field */:
+      return "property";
+    case 9 /* Constructor */:
+      return "class";
+    case 10 /* Enum */:
+      return "enum";
+    case 11 /* Interface */:
+      return "interface";
+    case 12 /* Function */:
+      return "function";
+    case 13 /* Variable */:
+      return "var";
+    case 14 /* Constant */:
+      return "const";
+    case 22 /* EnumMember */:
+      return "enum";
+    case 26 /* TypeParameter */:
+      return "type";
+    case 3 /* Namespace */:
+      return "namespace";
+    default:
+      return null;
+  }
+}
+
+// src/codebase-index/writer-search-helpers.ts
+var SEARCH_CANDIDATE_SCAN_CAP = 5e3;
+function normalizeSearchLimit(limit) {
+  return typeof limit === "number" && Number.isFinite(limit) ? Math.max(0, Math.trunc(limit)) : void 0;
+}
+function buildWriterSearchWhere(query, filter) {
+  const conditions = [];
+  const values = [];
+  let effectiveKind = filter?.kind;
+  if (filter?.lspKind !== void 0) {
+    const mapped = lspKindToInternalKind(filter.lspKind);
+    if (mapped !== null) {
+      effectiveKind = mapped;
+    } else {
+      return null;
+    }
+  }
+  if (effectiveKind) {
     conditions.push("kind = ?");
     values.push(effectiveKind);
   }
@@ -5164,6 +5517,173 @@ function mapWriterSearchRow(row, lspKind, score = 0, snippet = "") {
   };
 }
 
+// src/codebase-index/writer-search.ts
+function searchWithStatement(stmtFn, query, filter, opts) {
+  const built = buildWriterSearchWhere(query, filter);
+  if (built === null) return [];
+  const { where, values } = built;
+  const limit = normalizeSearchLimit(opts?.limit);
+  const limitSql = limit !== void 0 ? " LIMIT ?" : "";
+  const sql = `SELECT id, lang, kind, name, file, line, col, signature, doc_comment FROM symbols ${where}${limitSql}`;
+  const binds = limit !== void 0 ? [...values, limit] : values;
+  const rows = stmtFn(sql).all(...binds);
+  return rows.map((row) => mapWriterSearchRow(row, filter?.lspKind));
+}
+function countSearchWithStatement(stmtFn, query, filter) {
+  const built = buildWriterSearchWhere(query, filter);
+  if (built === null) return 0;
+  const row = stmtFn(`SELECT COUNT(*) AS n FROM symbols ${built.where}`).get(
+    ...built.values
+  );
+  return Number(row?.n ?? 0);
+}
+function searchRankedWithStatement(stmtFn, searchFn, ftsAvailable, vectorsAvailable, getOrBuildBm25, query, filter, limit) {
+  const rawLimit = Number.isFinite(limit) ? Math.trunc(limit) : 20;
+  const safeLimit = Math.max(1, Math.min(rawLimit, 100));
+  const tokens = tokenise(query);
+  if (tokens.length === 0 || !ftsAvailable) {
+    return searchRankedFallbackWithStatement(
+      stmtFn,
+      searchFn,
+      getOrBuildBm25,
+      query,
+      filter,
+      safeLimit
+    );
+  }
+  let effectiveKind = filter?.kind;
+  if (filter?.lspKind !== void 0) {
+    const mapped = lspKindToInternalKind(filter.lspKind);
+    if (mapped === null) return { results: [], total: 0 };
+    effectiveKind = mapped;
+  }
+  const longTokens = tokens.filter((t) => t.length >= 3);
+  const shortTokens = tokens.filter((t) => t.length < 3);
+  if (longTokens.length === 0) {
+    return searchRankedFallbackWithStatement(
+      stmtFn,
+      searchFn,
+      getOrBuildBm25,
+      query,
+      filter,
+      safeLimit
+    );
+  }
+  const match = longTokens.map((t) => `"${t.replaceAll('"', "")}"`).join(" OR ");
+  const conditions = ["symbols_fts MATCH ?"];
+  const values = [match];
+  for (const shortTok of shortTokens) {
+    conditions.push("s.text LIKE ? ESCAPE '\\'");
+    values.push(`%${escapeLike(shortTok)}%`);
+  }
+  if (effectiveKind) {
+    conditions.push("s.kind = ?");
+    values.push(effectiveKind);
+  }
+  if (filter?.lang) {
+    conditions.push("s.lang = ?");
+    values.push(filter.lang);
+  }
+  if (filter?.file) {
+    conditions.push("replace(s.file, '\\', '/') LIKE ? ESCAPE '\\'");
+    values.push(`%${escapeLike(filter.file.replace(/\\/g, "/"))}%`);
+  }
+  const where = conditions.join(" AND ");
+  const countRows = stmtFn(
+    `SELECT COUNT(*) AS n FROM symbols_fts JOIN symbols s ON s.id = symbols_fts.rowid WHERE ${where}`
+  ).all(...values);
+  const total = countRows[0] ? Number(countRows[0].n) : 0;
+  if (total === 0) return { results: [], total: 0 };
+  const bm25Rows = stmtFn(
+    `SELECT s.id, s.lang, s.kind, s.name, s.file, s.line, s.col, s.signature, s.doc_comment,
+            -bm25(symbols_fts) AS score,
+            snippet(symbols_fts, 0, '', '', '\u2026', 12) AS snippet
+     FROM symbols_fts JOIN symbols s ON s.id = symbols_fts.rowid
+     WHERE ${where}
+     ORDER BY
+       CASE WHEN lower(s.name) = lower(?) THEN 0
+            WHEN lower(s.name) LIKE lower(?) ESCAPE '\\' THEN 1
+            ELSE 2 END,
+       bm25(symbols_fts), lower(s.name), s.file, s.line, s.col, s.id
+     LIMIT ?`
+  ).all(...values, query.trim(), `${escapeLike(query.trim())}%`, safeLimit);
+  if (vectorsAvailable && bm25Rows.length > 0) {
+    const queryVec = embedText(query);
+    const candidateIds = bm25Rows.map((r) => r.id);
+    const placeholders = candidateIds.map(() => "?").join(",");
+    const vecRows = stmtFn(
+      `SELECT sv.symbol_id, sv.vector FROM symbol_vectors sv WHERE sv.symbol_id IN (${placeholders})`
+    ).all(...candidateIds);
+    const vecScores = vecRows.map((r) => ({
+      id: r.symbol_id,
+      sim: cosineSimilarity(queryVec, decodeVector(r.vector))
+    })).sort((a, b) => b.sim - a.sim);
+    const bm25Rank = /* @__PURE__ */ new Map();
+    bm25Rows.forEach((r, i) => {
+      bm25Rank.set(r.id, i);
+    });
+    const vecRank = /* @__PURE__ */ new Map();
+    vecScores.forEach((r, i) => {
+      vecRank.set(r.id, i);
+    });
+    const fused = reciprocalRankFusion(bm25Rank, vecRank, 60);
+    const fusedScore = new Map(fused);
+    const sorted = [...bm25Rows].sort(
+      (a, b) => (fusedScore.get(b.id) ?? 0) - (fusedScore.get(a.id) ?? 0)
+    );
+    return {
+      results: sorted.map(
+        (row) => mapWriterSearchRow(row, filter?.lspKind, Math.max(1e-4, row.score), row.snippet)
+      ),
+      total
+    };
+  }
+  return {
+    results: bm25Rows.map(
+      (row) => mapWriterSearchRow(row, filter?.lspKind, Math.max(1e-4, row.score), row.snippet)
+    ),
+    total
+  };
+}
+function searchRankedFallbackWithStatement(stmtFn, searchFn, getOrBuildBm25, query, filter, limit) {
+  if (!query.trim()) {
+    const total2 = countSearchWithStatement(stmtFn, query, filter);
+    if (total2 === 0) return { results: [], total: 0 };
+    return { results: searchFn(query, filter, { limit }), total: total2 };
+  }
+  const total = countSearchWithStatement(stmtFn, query, filter);
+  if (total === 0) return { results: [], total: 0 };
+  const candidates = searchFn(query, filter, {
+    limit: SEARCH_CANDIDATE_SCAN_CAP
+  });
+  if (candidates.length === 0) return { results: [], total: 0 };
+  const candidateById = new Map(candidates.map((c) => [c.id, c]));
+  const bm25 = getOrBuildBm25();
+  const scored = bm25.score(query, (id) => candidateById.has(id));
+  const q = query.trim().toLowerCase();
+  const rank = (id) => {
+    const name = candidateById.get(id)?.name.toLowerCase() ?? "";
+    if (name === q) return 0;
+    if (name.startsWith(q)) return 1;
+    return 2;
+  };
+  scored.sort((a, b) => {
+    const rankDiff = rank(a.id) - rank(b.id);
+    if (rankDiff !== 0) return rankDiff;
+    const scoreDiff = b.score - a.score;
+    if (scoreDiff !== 0) return scoreDiff;
+    const left = expectDefined4(candidateById.get(a.id));
+    const right = expectDefined4(candidateById.get(b.id));
+    return left.name.localeCompare(right.name) || left.file.localeCompare(right.file) || left.line - right.line || left.col - right.col || left.id - right.id;
+  });
+  const qTokens = tokenise(query);
+  const results = scored.slice(0, limit).map(({ id, score }) => {
+    const c = expectDefined4(candidateById.get(id));
+    return { ...c, score, snippet: bm25.extractSnippet(id, qTokens) };
+  });
+  return { results, total };
+}
+
 // src/codebase-index/writer-store-pool.ts
 var DEFAULT_MAX_WARM_STORES = 2;
 var StorePool = class {
@@ -5255,68 +5775,14 @@ var DB_FILE2 = "index.db";
 var MAX_STATEMENT_CACHE = 128;
 var IndexStore = class _IndexStore {
   db;
-  /**
-   * True while an index run owns one outer SQLite transaction. Individual
-   * writer methods normally protect themselves with BEGIN/COMMIT, but during
-   * a refresh they join this transaction so readers observe either the last
-   * completed index or the next completed index, never an in-between batch.
-   */
   atomicIndexUpdateActive = false;
   writeSavepointSequence = 0;
-  /** Absolute path to this project's index directory. */
   indexDir;
-  /**
-   * True when the SQLite build provides FTS5 (Node's bundled SQLite does).
-   * When false, ranked search falls back to the LIKE + in-process BM25 path.
-   */
   ftsAvailable = false;
-  /**
-   * Phase 3: true when the `symbol_vectors` table was created successfully.
-   * When false, hybrid search skips the vector pass and falls back to FTS5
-   * (or LIKE) only.
-   */
   vectorsAvailable = false;
-  /**
-   * Cache of prepared statements keyed by their SQL text. `DatabaseSync`
-   * compiles SQL on every `.prepare()` call; for the fixed-SQL methods
-   * (upsertFile, getFileMeta, deleteFile, insertRefs, …) that runs thousands
-   * of times during a full reindex. `StatementSync` objects are reusable
-   * across calls on the same connection, so we compile each distinct SQL once
-   * and reuse it. Cleared in {@link close} when the connection is torn down.
-   */
   stmtCache = /* @__PURE__ */ new Map();
-  /**
-   * Cached full-corpus BM25 index for the FTS5-unavailable fallback path.
-   * Built lazily on the first `searchRankedFallback` call and invalidated
-   * (via `bm25Dirty`) whenever the `symbols` table is mutated. Computing
-   * IDF over the full corpus is also more correct than the old per-query
-   * candidate-subset IDF.
-   *
-   * Cache-lifecycle invariants (single source of truth lives at the
-   * `invalidateBm25()` helper — see its docblock for the "every mutation
-   * MUST call this" contract):
-   *   - declaration: this field + `bm25Dirty` (here)
-   *   - invalidation: `invalidateBm25()` flips the flag and nulls the cache
-   *   - build: `getOrBuildBm25()` rebuilds against current `symbols` rows
-   *   - teardown: `close()` resets the flag and nulls the cache
-   */
   bm25Cache = null;
-  // Dirty on open so the first getOrBuildBm25() rebuilds against current rows;
-  // an empty or pre-existing corpus makes a stale IDF table meaningless.
   bm25Dirty = true;
-  /**
-   * Prepare-once helper: compile `sql` on first use, reuse thereafter.
-   *
-   * Bounded LRU rather than an open Map. The cache is keyed by SQL TEXT, and
-   * the fallback search builder emits one `text LIKE ?` clause per query token
-   * — so the SQL varies with the token count and a stream of differently-sized
-   * queries grew the cache without limit. Sage's store already bounds its
-   * equivalent at 128 (WS-096).
-   *
-   * Re-inserting on a hit keeps the hot fixed-SQL statements (upsertFile,
-   * insertRefs, …) at the young end, so a burst of one-off search SQL evicts
-   * itself rather than the reindex hot path.
-   */
   stmt(sql) {
     const cached = this.stmtCache.get(sql);
     if (cached !== void 0) {
@@ -5343,7 +5809,6 @@ var IndexStore = class _IndexStore {
   runWithRetry(fn) {
     return runSqliteWithRetry(fn);
   }
-  /** Run a complete index mutation as one WAL-visible publication. */
   async runAtomicIndexUpdate(job) {
     if (this.atomicIndexUpdateActive) return job();
     this.runWithRetry(() => this.db.exec("BEGIN IMMEDIATE"));
@@ -5362,11 +5827,6 @@ var IndexStore = class _IndexStore {
       this.atomicIndexUpdateActive = false;
     }
   }
-  /**
-   * Begin a method-local transaction. Inside an atomic index publication a
-   * SAVEPOINT preserves the old per-batch rollback boundary, which is needed
-   * when commitBatch falls back to per-file writes after one batch fails.
-   */
   beginWriteTransaction() {
     if (this.atomicIndexUpdateActive) {
       const savepoint = `index_write_${++this.writeSavepointSequence}`;
@@ -5388,35 +5848,11 @@ var IndexStore = class _IndexStore {
       this.db.exec("ROLLBACK");
     }
   }
-  /**
-   * Mirror the in-process language→family map into SQLite.
-   *
-   * Rewritten on every open rather than only on schema bumps: the mapping is
-   * static lookup data, so a code-side change (a new language, a language
-   * moving families) must take effect without forcing a full reindex.
-   */
   seedLangFamilies() {
     const insert = this.stmt("INSERT OR REPLACE INTO lang_family(lang, family) VALUES (?, ?)");
     for (const [lang, family] of LANG_FAMILY_ENTRIES) insert.run(lang, family);
     insert.run("", LANG_FAMILY_WILDCARD);
   }
-  /**
-   * Add any column the current schema expects but the on-disk table lacks.
-   *
-   * `CREATE TABLE IF NOT EXISTS` silently keeps an existing table's old shape,
-   * and the version check above only rebuilds on a version *mismatch*. That
-   * leaves a real gap: several wstack processes share this database, and while
-   * a version upgrade is rolling out one of them may still be running the
-   * previous build. That older process sees the newer version number, drops the
-   * tables, and recreates them from *its* DDL — without the newer columns —
-   * while the metadata row still reads the new version. Every later query for
-   * one of those columns then fails with `no such column`, and no amount of
-   * reindexing fixes it, because the version numbers already agree.
-   *
-   * Repairing column-by-column makes the schema self-healing from any of those
-   * states. Table and column names are compile-time literals from this module,
-   * never user input.
-   */
   repairMissingColumns() {
     const expected = [
       {
@@ -5521,27 +5957,8 @@ var IndexStore = class _IndexStore {
     }
     this.ensureNextSymbolIdSeeded();
   }
-  // ─── ID allocation & bulk helpers ────────────────────────────────────────────
   static NEXT_SYMBOL_ID_KEY = "next_symbol_id";
-  /** Stay under typical SQLite SQLITE_MAX_VARIABLE_NUMBER (often 999). */
   static MAX_SQL_VARS = 900;
-  /**
-   * Correlated predicate: the ref in `refs` and the candidate symbol aliased
-   * `sym` belong to the same language family — or the ref carries no language,
-   * in which case the wildcard bind matches everything.
-   *
-   * Each textual occurrence consumes one `?` bind of {@link LANG_FAMILY_WILDCARD}.
-   */
-  static FAMILY_MATCH_SQL = `(
-    (SELECT family FROM lang_family WHERE lang = refs.lang) = ?
-    OR (SELECT family FROM lang_family WHERE lang = sym.lang)
-       = (SELECT family FROM lang_family WHERE lang = refs.lang)
-  )`;
-  /**
-   * Ensure `metadata.next_symbol_id` exists. Safe to call outside a write
-   * transaction on open; the first concurrent writer under BEGIN IMMEDIATE
-   * re-reads and advances the counter atomically.
-   */
   ensureNextSymbolIdSeeded() {
     const existing = this.stmt("SELECT value FROM metadata WHERE key = ?").get(
       _IndexStore.NEXT_SYMBOL_ID_KEY
@@ -5554,10 +5971,6 @@ var IndexStore = class _IndexStore {
       String(next)
     );
   }
-  /**
-   * Reserve `count` consecutive symbol ids. MUST run inside BEGIN IMMEDIATE
-   * so concurrent indexers cannot hand out overlapping ranges.
-   */
   allocateSymbolIds(count) {
     if (count <= 0) return this.getMaxSymbolId() + 1;
     this.ensureNextSymbolIdSeeded();
@@ -5571,16 +5984,8 @@ var IndexStore = class _IndexStore {
     );
     return start;
   }
-  /**
-   * Disconnect inbound refs before their target symbols are replaced and
-   * return the affected names for scoped re-resolution.
-   *
-   * This also repairs a long-standing dangling-id edge case: `refs.to_id` has
-   * no physical FK, so deleting a symbol previously left callers pointing at a
-   * non-existent row.
-   */
   invalidateIncomingRefsForFiles(files) {
-    if (files.length === 0) return [];
+    if (files.length === 0) return /* @__PURE__ */ new Set();
     const placeholders = files.map(() => "?").join(",");
     const names = this.stmt(`SELECT DISTINCT name FROM symbols WHERE file IN (${placeholders})`).all(
       ...files
@@ -5589,36 +5994,11 @@ var IndexStore = class _IndexStore {
       `UPDATE refs SET to_id = NULL
        WHERE to_id IN (SELECT id FROM symbols WHERE file IN (${placeholders}))`
     ).run(...files);
-    return names;
+    return new Set(names);
   }
-  /** Resolve only refs whose target names may have changed. */
   resolveRefsForNamesUnsafe(names) {
-    const unique = [...new Set(names)].filter(Boolean);
-    let changes = 0;
-    for (let start = 0; start < unique.length; start += _IndexStore.MAX_SQL_VARS) {
-      const chunk = unique.slice(start, start + _IndexStore.MAX_SQL_VARS);
-      const placeholders = chunk.map(() => "?").join(",");
-      const result = this.stmt(
-        `UPDATE refs
-         SET to_id = (
-           SELECT MIN(sym.id) FROM symbols sym
-            WHERE sym.name = refs.to_name AND ${_IndexStore.FAMILY_MATCH_SQL}
-         )
-         WHERE to_name IN (${placeholders})`
-      ).run(LANG_FAMILY_WILDCARD, ...chunk);
-      changes += result.changes ?? 0;
-    }
-    return changes;
+    return resolveRefsForNamesUnsafe((sql) => this.stmt(sql), _IndexStore.MAX_SQL_VARS, names);
   }
-  // ─── Symbol CRUD ─────────────────────────────────────────────────────────────
-  /**
-   * Insert symbols, assigning IDs atomically inside `BEGIN IMMEDIATE` /
-   * `COMMIT`. Id ranges come from the `next_symbol_id` metadata counter
-   * (O(1)); multi-row INSERT amortizes bind overhead for large files.
-   *
-   * @returns The symbols array with `id` fields populated so the caller can
-   *          use them for refs without re-reading from the DB.
-   */
   insertSymbols(symbols) {
     this.invalidateBm25();
     return this.runWithRetry(() => {
@@ -5647,12 +6027,6 @@ var IndexStore = class _IndexStore {
           if (this.ftsAvailable) {
             ftsRows.push({ id, text: buildIndexableText(s.name, s.signature, s.docComment) });
           }
-          vectorRows.push({
-            id,
-            vector: encodeVector(
-              embedText(s.text || buildIndexableText(s.name, s.signature, s.docComment))
-            )
-          });
           result.push({ ...s, id });
         }
         bulkInsertSymbolsWithStatement((sql) => this.stmt(sql), _IndexStore.MAX_SQL_VARS, bulk);
@@ -5702,11 +6076,6 @@ var IndexStore = class _IndexStore {
       }
     });
   }
-  /**
-   * Remove every trace of a file (refs, symbols, FTS rows, file meta). Used
-   * when a source file disappears between index runs — previously this only
-   * dropped the `files` row, leaving its symbols orphaned but still searchable.
-   */
   deleteFile(file) {
     this.invalidateBm25();
     this.runWithRetry(() => {
@@ -5736,7 +6105,6 @@ var IndexStore = class _IndexStore {
       }
     });
   }
-  // ─── File metadata ──────────────────────────────────────────────────────────
   upsertFile(meta) {
     this.runWithRetry(() => {
       this.stmt(
@@ -5764,8 +6132,6 @@ var IndexStore = class _IndexStore {
   getAllFileMetas() {
     return getAllFileMetasWithStatement((sql) => this.stmt(sql));
   }
-  // ─── Project structure & module resolution ──────────────────────────────────
-  /** Store the Code Atlas grouping label for each indexed file. */
   setFilePackages(entries) {
     if (entries.size === 0) return;
     this.runWithRetry(() => {
@@ -5773,272 +6139,50 @@ var IndexStore = class _IndexStore {
       for (const [file, label] of entries) update.run(label, file);
     });
   }
-  /**
-   * Every indexed `namespace`/`module` declaration, for ecosystems whose import
-   * specifiers name a namespace rather than a path (C#, PHP, Elixir, Haskell).
-   * Ordered so the resolver's choice among duplicate declarations is stable.
-   */
   getNamespaceDeclarations() {
-    return this.stmt(
-      `SELECT name, file FROM symbols WHERE kind = 'namespace' ORDER BY file, id`
-    ).all();
+    return getNamespaceDeclarationsWithStatement((sql) => this.stmt(sql));
   }
-  /** `file → package` for every indexed file that has a label. */
   getFilePackages() {
-    const rows = this.stmt("SELECT file, package FROM files WHERE package != ''").all();
-    return new Map(rows.map((row) => [row.file, row.package]));
+    return getFilePackagesWithStatement((sql) => this.stmt(sql));
   }
-  /**
-   * Distinct `(fromFile, lang, module)` triples needing module resolution.
-   *
-   * Distinct rather than per-ref because resolution depends only on these three
-   * values: a file importing the same module twenty times resolves it once.
-   */
   getUnresolvedImports(onlyFiles) {
-    const base = `SELECT DISTINCT s.file AS fromFile, r.lang AS lang, r.module AS module
-                    FROM refs r
-                    JOIN symbols s ON s.id = r.from_id
-                   WHERE r.call_type = 'import' AND r.module IS NOT NULL`;
-    if (!onlyFiles?.length) {
-      return this.stmt(base).all();
-    }
-    const out = [];
-    for (let i = 0; i < onlyFiles.length; i += _IndexStore.MAX_SQL_VARS) {
-      const chunk = onlyFiles.slice(i, i + _IndexStore.MAX_SQL_VARS);
-      const placeholders = chunk.map(() => "?").join(",");
-      out.push(
-        ...this.stmt(`${base} AND s.file IN (${placeholders})`).all(...chunk)
-      );
-    }
-    return out;
+    return getUnresolvedImportsWithStatement(
+      (sql) => this.stmt(sql),
+      _IndexStore.MAX_SQL_VARS,
+      onlyFiles
+    );
   }
-  /**
-   * Write resolved import targets back onto `refs.to_file`.
-   *
-   * Applied through a temp table and a single UPDATE: one statement per
-   * resolution would mean thousands of round-trips on a first index.
-   */
   applyImportResolutions(resolutions) {
-    if (resolutions.length === 0) return 0;
-    return this.runWithRetry(() => {
-      this.db.exec("DROP TABLE IF EXISTS temp.import_resolution");
-      this.db.exec(
-        `CREATE TEMP TABLE import_resolution (
-           from_file TEXT NOT NULL,
-           lang TEXT NOT NULL,
-           module TEXT NOT NULL,
-           to_file TEXT NOT NULL
-         )`
-      );
-      const chunkSize = Math.max(1, Math.floor(_IndexStore.MAX_SQL_VARS / 4));
-      for (let i = 0; i < resolutions.length; i += chunkSize) {
-        const chunk = resolutions.slice(i, i + chunkSize);
-        const placeholders = chunk.map(() => "(?, ?, ?, ?)").join(", ");
-        const binds = [];
-        for (const entry of chunk) {
-          binds.push(entry.fromFile, entry.lang, entry.module, entry.toFile);
-        }
-        this.stmt(
-          `INSERT INTO temp.import_resolution(from_file, lang, module, to_file)
-           VALUES ${placeholders}`
-        ).run(...binds);
-      }
-      this.db.exec(
-        `CREATE INDEX IF NOT EXISTS temp.idx_ir
-           ON import_resolution(module, lang, from_file)`
-      );
-      const result = this.stmt(
-        `UPDATE refs
-            SET to_file = (
-              SELECT ir.to_file
-                FROM temp.import_resolution ir
-                JOIN symbols s ON s.id = refs.from_id
-               WHERE ir.module = refs.module
-                 AND ir.lang = refs.lang
-                 AND ir.from_file = s.file
-               LIMIT 1
-            )
-          WHERE refs.call_type = 'import'
-            AND refs.module IS NOT NULL
-            AND EXISTS (
-              SELECT 1
-                FROM temp.import_resolution ir
-                JOIN symbols s ON s.id = refs.from_id
-               WHERE ir.module = refs.module
-                 AND ir.lang = refs.lang
-                 AND ir.from_file = s.file
-            )`
-      ).run();
-      this.db.exec("DROP TABLE IF EXISTS temp.import_resolution");
-      return result.changes ?? 0;
-    });
-  }
-  // ─── Search ──────────────────────────────────────────────────────────────────
-  search(query, filter, opts) {
-    const built = this.buildSearchWhere(query, filter);
-    if (built === null) return [];
-    const { where, values } = built;
-    const limit = normalizeSearchLimit(opts?.limit);
-    const limitSql = limit !== void 0 ? " LIMIT ?" : "";
-    const sql = `SELECT id, lang, kind, name, file, line, col, signature, doc_comment FROM symbols ${where}${limitSql}`;
-    const binds = limit !== void 0 ? [...values, limit] : values;
-    const rows = this.stmt(sql).all(
-      ...binds
+    return applyImportResolutionsWithStatement(
+      this.db,
+      (sql) => this.stmt(sql),
+      this.runWithRetry.bind(this),
+      _IndexStore.MAX_SQL_VARS,
+      resolutions
     );
-    return rows.map((row) => mapWriterSearchRow(row, filter?.lspKind));
   }
-  /** Shared WHERE builder for {@link search} / empty-query ranked totals. */
-  buildSearchWhere(query, filter) {
-    return buildWriterSearchWhere(query, filter);
+  search(query, filter, opts) {
+    return searchWithStatement((sql) => this.stmt(sql), query, filter, opts);
   }
   countSearch(query, filter) {
-    const built = this.buildSearchWhere(query, filter);
-    if (built === null) return 0;
-    const row = this.stmt(`SELECT COUNT(*) AS n FROM symbols ${built.where}`).get(
-      ...built.values
-    );
-    return Number(row?.n ?? 0);
+    return countSearchWithStatement((sql) => this.stmt(sql), query, filter);
   }
-  /**
-   * Ranked search — the one-stop query the codebase-search tool and plug-lsp
-   * use. With FTS5 this is a single indexed `MATCH` ranked by SQLite's native
-   * `bm25()` with a built-in `snippet()`; without FTS5 it falls back to the
-   * legacy LIKE scan + in-process BM25 (identical semantics, slower).
-   *
-   * Tokens are matched as prefixes (`"tok"*`), mirroring the old
-   * `LIKE '%tok%'` recall for the common symbol-search shapes ("user" finds
-   * "users", camelCase-split text makes "complex" find "complexOperation").
-   */
   searchRanked(query, filter, limit) {
-    const rawLimit = Number.isFinite(limit) ? Math.trunc(limit) : 20;
-    const safeLimit = Math.max(1, Math.min(rawLimit, 100));
-    const tokens = tokenise(query);
-    if (tokens.length === 0 || !this.ftsAvailable) {
-      return this.searchRankedFallback(query, filter, safeLimit);
-    }
-    let effectiveKind = filter?.kind;
-    if (filter?.lspKind !== void 0) {
-      const mapped = lspKindToInternalKind(filter.lspKind);
-      if (mapped === null) return { results: [], total: 0 };
-      effectiveKind = mapped;
-    }
-    const longTokens = tokens.filter((t) => t.length >= 3);
-    const shortTokens = tokens.filter((t) => t.length < 3);
-    if (longTokens.length === 0) {
-      return this.searchRankedFallback(query, filter, safeLimit);
-    }
-    const match = longTokens.map((t) => `"${t.replaceAll('"', "")}"`).join(" OR ");
-    const conditions = ["symbols_fts MATCH ?"];
-    const values = [match];
-    for (const shortTok of shortTokens) {
-      conditions.push("s.text LIKE ? ESCAPE '\\'");
-      values.push(`%${escapeLike(shortTok)}%`);
-    }
-    if (effectiveKind) {
-      conditions.push("s.kind = ?");
-      values.push(effectiveKind);
-    }
-    if (filter?.lang) {
-      conditions.push("s.lang = ?");
-      values.push(filter.lang);
-    }
-    if (filter?.file) {
-      conditions.push("replace(s.file, '\\', '/') LIKE ? ESCAPE '\\'");
-      values.push(`%${escapeLike(filter.file.replace(/\\/g, "/"))}%`);
-    }
-    const where = conditions.join(" AND ");
-    const countRows = this.stmt(
-      `SELECT COUNT(*) AS n FROM symbols_fts JOIN symbols s ON s.id = symbols_fts.rowid WHERE ${where}`
-    ).all(...values);
-    const total = countRows[0] ? Number(countRows[0].n) : 0;
-    if (total === 0) return { results: [], total: 0 };
-    const bm25Rows = this.stmt(
-      `SELECT s.id, s.lang, s.kind, s.name, s.file, s.line, s.col, s.signature, s.doc_comment,
-                -bm25(symbols_fts) AS score,
-                snippet(symbols_fts, 0, '', '', '\u2026', 12) AS snippet
-         FROM symbols_fts JOIN symbols s ON s.id = symbols_fts.rowid
-         WHERE ${where}
-         ORDER BY
-           CASE WHEN lower(s.name) = lower(?) THEN 0
-                WHEN lower(s.name) LIKE lower(?) ESCAPE '\\' THEN 1
-                ELSE 2 END,
-           bm25(symbols_fts), lower(s.name), s.file, s.line, s.col, s.id
-         LIMIT ?`
-    ).all(...values, query.trim(), `${escapeLike(query.trim())}%`, safeLimit);
-    if (this.vectorsAvailable && bm25Rows.length > 0) {
-      const queryVec = embedText(query);
-      const candidateIds = bm25Rows.map((r) => r.id);
-      const placeholders = candidateIds.map(() => "?").join(",");
-      const vecRows = this.stmt(
-        `SELECT sv.symbol_id, sv.vector FROM symbol_vectors sv WHERE sv.symbol_id IN (${placeholders})`
-      ).all(...candidateIds);
-      const vecScores = vecRows.map((r) => ({
-        id: r.symbol_id,
-        sim: cosineSimilarity(queryVec, decodeVector(r.vector))
-      })).sort((a, b) => b.sim - a.sim);
-      const bm25Rank = /* @__PURE__ */ new Map();
-      bm25Rows.forEach((r, i) => {
-        bm25Rank.set(r.id, i);
-      });
-      const vecRank = /* @__PURE__ */ new Map();
-      vecScores.forEach((r, i) => {
-        vecRank.set(r.id, i);
-      });
-      const fused = reciprocalRankFusion(bm25Rank, vecRank, 60);
-      const fusedScore = new Map(fused);
-      const sorted = [...bm25Rows].sort(
-        (a, b) => (fusedScore.get(b.id) ?? 0) - (fusedScore.get(a.id) ?? 0)
-      );
-      return {
-        results: sorted.map(
-          (row) => mapWriterSearchRow(row, filter?.lspKind, Math.max(1e-4, row.score), row.snippet)
-        ),
-        total
-      };
-    }
-    return {
-      results: bm25Rows.map(
-        (row) => mapWriterSearchRow(row, filter?.lspKind, Math.max(1e-4, row.score), row.snippet)
-      ),
-      total
-    };
+    return searchRankedWithStatement(
+      (sql) => this.stmt(sql),
+      this.search.bind(this),
+      this.ftsAvailable,
+      this.vectorsAvailable,
+      this.getOrBuildBm25.bind(this),
+      query,
+      filter,
+      limit
+    );
   }
-  /**
-   * Invalidate the cached BM25 index.
-   *
-   * **Contract: every method that mutates `symbols` MUST call this before
-   * returning.** (`refs` mutations do not affect the BM25 fallback because
-   * the corpus is built from `symbols.text` via `getAllIndexable()` and the
-   * BM25 score is filtered by the LIKE-selected candidate set in
-   * `searchRankedFallback`.) Today the call sites are `repairDrift`,
-   * `insertSymbols`, `deleteSymbolsForFile`, `deleteFile`, `clearAll`, and
-   * `commitBatch`. A future mutation that adds a new write path (e.g.
-   * `renameFile`, `updateSignature`) MUST also call this — otherwise the
-   * FTS5-unavailable fallback will serve stale search results. The
-   * `close()` reset at L1820-1821 tears the cache down on store shutdown,
-   * which is the only legitimate place that flips the flag outside this
-   * helper.
-   *
-   * Called *before* `runWithRetry` on purpose: if the write fails all
-   * retries the flag stays set, forcing a rebuild on the next search rather
-   * than trusting a cache that may not reflect the intended mutation.
-   * Do not move this inside the retry closure.
-   */
   invalidateBm25() {
     this.bm25Dirty = true;
     this.bm25Cache = null;
   }
-  /**
-   * Return the cached full-corpus BM25 index, rebuilding it only when the
-   * symbols table has been mutated since the last build. The full-corpus IDF
-   * is more correct than the old per-query candidate-subset IDF, and the
-   * amortized build cost drops from O(symbols × tokens) per search to once
-   * per write batch.
-   *
-   * Note: the first call after a long idle (or on a freshly opened store)
-   * pays the full corpus rebuild synchronously on the search path. For a
-   * 5 500+ symbol corpus this is a visible one-time latency spike.
-   */
   getOrBuildBm25() {
     if (this.bm25Cache && !this.bm25Dirty) return this.bm25Cache;
     const docs = this.getAllIndexable();
@@ -6046,57 +6190,12 @@ var IndexStore = class _IndexStore {
     this.bm25Dirty = false;
     return this.bm25Cache;
   }
-  /** Legacy ranked path: LIKE candidates + in-process BM25 + JS snippets. */
-  searchRankedFallback(query, filter, limit) {
-    if (!query.trim()) {
-      const total2 = this.countSearch(query, filter);
-      if (total2 === 0) return { results: [], total: 0 };
-      return { results: this.search(query, filter, { limit }), total: total2 };
-    }
-    const total = this.countSearch(query, filter);
-    if (total === 0) return { results: [], total: 0 };
-    const candidates = this.search(query, filter, { limit: SEARCH_CANDIDATE_SCAN_CAP });
-    if (candidates.length === 0) return { results: [], total: 0 };
-    const candidateById = new Map(candidates.map((c) => [c.id, c]));
-    const bm25 = this.getOrBuildBm25();
-    const scored = bm25.score(query, (id) => candidateById.has(id));
-    const q = query.trim().toLowerCase();
-    const rank = (id) => {
-      const name = candidateById.get(id)?.name.toLowerCase() ?? "";
-      if (name === q) return 0;
-      if (name.startsWith(q)) return 1;
-      return 2;
-    };
-    scored.sort((a, b) => {
-      const rankDiff = rank(a.id) - rank(b.id);
-      if (rankDiff !== 0) return rankDiff;
-      const scoreDiff = b.score - a.score;
-      if (scoreDiff !== 0) return scoreDiff;
-      const left = expectDefined4(candidateById.get(a.id));
-      const right = expectDefined4(candidateById.get(b.id));
-      return left.name.localeCompare(right.name) || left.file.localeCompare(right.file) || left.line - right.line || left.col - right.col || left.id - right.id;
-    });
-    const qTokens = tokenise(query);
-    const results = scored.slice(0, limit).map(({ id, score }) => {
-      const c = expectDefined4(candidateById.get(id));
-      return { ...c, score, snippet: bm25.extractSnippet(id, qTokens) };
-    });
-    return { results, total };
-  }
   getAllIndexable() {
     return getAllIndexableWithStatement((sql) => this.stmt(sql));
   }
-  /**
-   * Largest symbol id currently in the table (0 when empty). New ids must be
-   * allocated from this, NOT from `COUNT(*)`: incremental reindexes delete a
-   * changed file's rows, so the row count drops below the max id and a
-   * count-based id would collide with a surviving row (UNIQUE constraint on
-   * `symbols.id`). Ids may have gaps — that is fine.
-   */
   getMaxSymbolId() {
     return getMaxSymbolIdWithStatement((sql) => this.stmt(sql));
   }
-  // ─── Stats ───────────────────────────────────────────────────────────────────
   getStats() {
     return getStatsWithStatement((sql) => this.stmt(sql), this.indexDir);
   }
@@ -6139,11 +6238,6 @@ var IndexStore = class _IndexStore {
       }
     });
   }
-  // ─── Ref CRUD ────────────────────────────────────────────────────────────────
-  /**
-   * Insert cross-references for a given source symbol id.
-   * Replaces any existing refs from the same source (idempotent on re-index).
-   */
   insertRefs(fromId, refs) {
     this.runWithRetry(() => {
       this.stmt("DELETE FROM refs WHERE from_id = ?").run(fromId);
@@ -6155,167 +6249,36 @@ var IndexStore = class _IndexStore {
       );
     });
   }
-  /**
-   * Bulk-insert refs for many source symbols in a single transaction.
-   *
-   * Unlike {@link insertRefs} this does NOT delete per source id — the caller
-   * (the indexer) has already cleared stale refs for the file via
-   * {@link deleteRefsForFile}, so the per-source DELETE would be redundant work
-   * repeated once per symbol. One transaction for the whole file instead of one
-   * per symbol turns an O(symbols) transaction count into O(1).
-   *
-   * Each ref's own {@link Ref.fromId} is used; pass an empty array to no-op.
-   */
   insertRefsBatch(refs) {
     if (refs.length === 0) return;
     this.runWithRetry(() => {
       bulkInsertRefsWithStatement((sql) => this.stmt(sql), _IndexStore.MAX_SQL_VARS, refs);
     });
   }
-  /**
-   * Commit a batch of file-level symbol/refs/upserts in a single transaction.
-   *
-   * Used by the indexer to amortize SQLite commit overhead across many files.
-   * Before this, the indexer issued one transaction per file (BEGIN IMMEDIATE
-   * for symbols, plus per-file deletes and an upsertFile call), so a 20-file
-   * parallel batch cost ~5+ transactions × 20 files = 100+ commits. With
-   * this entry point we do exactly one BEGIN/COMMIT per parallel batch.
-   *
-   * Each entry must already be a fully-parsed FileSymbols (symbols + refs).
-   * The caller is responsible for the per-file prefix accounting
-   * (refsByLine → flat list with `fromId` populated). `deleteForFiles` lets
-   * the caller clear stale symbols/refs for any files being re-indexed before
-   * the inserts run (required to keep refs → symbols FK invariants).
-   *
-   * Returns the symbols back with their assigned `id` (same shape as
-   * {@link insertSymbols}) so callers can build final per-file results.
-   */
   commitBatch(entries, options = {}) {
-    if (entries.length === 0 && (options.deleteForFiles?.length ?? 0) === 0) {
-      return [];
-    }
     this.invalidateBm25();
     return this.runWithRetry(() => {
       const ownsTransaction = this.beginWriteTransaction();
       try {
-        const affectedNames = /* @__PURE__ */ new Set();
-        for (const entry of entries) {
-          for (const symbol of entry.symbols) affectedNames.add(symbol.name);
-          for (const ref of entry.refs) affectedNames.add(ref.toName);
-        }
-        if (options.deleteForFiles && options.deleteForFiles.length > 0) {
-          const placeholders = options.deleteForFiles.map(() => "?").join(",");
-          for (const name of this.invalidateIncomingRefsForFiles(options.deleteForFiles)) {
-            affectedNames.add(name);
-          }
-          if (this.ftsAvailable) {
-            this.stmt(
-              `DELETE FROM symbols_fts WHERE rowid IN (SELECT id FROM symbols WHERE file IN (${placeholders}))`
-            ).run(...options.deleteForFiles);
-          }
-          if (this.vectorsAvailable) {
-            this.stmt(
-              `DELETE FROM symbol_vectors WHERE symbol_id IN (SELECT id FROM symbols WHERE file IN (${placeholders}))`
-            ).run(...options.deleteForFiles);
-          }
-          this.stmt(
-            `DELETE FROM refs WHERE from_id IN (SELECT id FROM symbols WHERE file IN (${placeholders}))`
-          ).run(...options.deleteForFiles);
-          this.stmt(`DELETE FROM symbols WHERE file IN (${placeholders})`).run(
-            ...options.deleteForFiles
-          );
-        }
-        const totalSymbols = entries.reduce((n, e) => n + e.symbols.length, 0);
-        let nextId = this.allocateSymbolIds(totalSymbols);
-        const allInserted = [];
-        const refsToInsert = [];
-        const bulkSyms = [];
-        const ftsRows = [];
-        const vectorRows = [];
-        for (const entry of entries) {
-          const insertedForEntry = [];
-          for (const s of entry.symbols) {
-            const id = nextId++;
-            bulkSyms.push({
-              id,
-              lang: s.lang,
-              kind: s.kind,
-              name: s.name,
-              file: s.file,
-              line: s.line,
-              col: s.col,
-              signature: s.signature,
-              docComment: s.docComment,
-              scope: s.scope,
-              text: s.text
-            });
-            if (this.ftsAvailable) {
-              ftsRows.push({
-                id,
-                text: buildIndexableText(s.name, s.signature, s.docComment)
-              });
-            }
-            vectorRows.push({
-              id,
-              vector: encodeVector(
-                embedText(s.text || buildIndexableText(s.name, s.signature, s.docComment))
-              )
-            });
-            const inserted = { ...s, id };
-            allInserted.push(inserted);
-            insertedForEntry.push(inserted);
-          }
-          refsToInsert.push(...assignRefsToSymbols(entry.refs, insertedForEntry));
-        }
-        bulkInsertSymbolsWithStatement((sql) => this.stmt(sql), _IndexStore.MAX_SQL_VARS, bulkSyms);
-        bulkInsertFtsWithStatement(
+        const result = commitBatchWithStatement(
           (sql) => this.stmt(sql),
           _IndexStore.MAX_SQL_VARS,
           this.ftsAvailable,
-          ftsRows
-        );
-        if (this.vectorsAvailable) {
-          bulkInsertVectorsWithStatement(
-            (sql) => this.stmt(sql),
-            _IndexStore.MAX_SQL_VARS,
-            vectorRows
-          );
-        }
-        bulkInsertRefsWithStatement((sql) => this.stmt(sql), _IndexStore.MAX_SQL_VARS, refsToInsert);
-        const upsertStmt = this.stmt(
-          `INSERT INTO files(file, lang, mtime_ms, content_hash, symbol_count, last_indexed)
-           VALUES (?, ?, ?, ?, ?, ?)
-           ON CONFLICT(file) DO UPDATE SET
-             lang = excluded.lang,
-             mtime_ms = excluded.mtime_ms,
-             content_hash = excluded.content_hash,
-             symbol_count = excluded.symbol_count,
-             last_indexed = excluded.last_indexed`
+          this.vectorsAvailable,
+          this.allocateSymbolIds.bind(this),
+          this.invalidateIncomingRefsForFiles.bind(this),
+          this.resolveRefsForNamesUnsafe.bind(this),
+          entries,
+          options
         );
-        const now = Date.now();
-        for (const entry of entries) {
-          upsertStmt.run(
-            entry.file,
-            entry.lang,
-            entry.mtimeMs,
-            entry.contentHash ?? "",
-            entry.symbolCount,
-            now
-          );
-        }
-        this.resolveRefsForNamesUnsafe(affectedNames);
         this.commitWriteTransaction(ownsTransaction);
-        return allInserted;
+        return result;
       } catch (err) {
         this.rollbackWriteTransaction(ownsTransaction);
         throw err;
       }
     });
   }
-  /**
-   * Delete all refs whose source symbols are in a given file.
-   * Used when re-indexing a file to clear stale refs.
-   */
   deleteRefsForFile(file) {
     this.runWithRetry(() => {
       this.stmt("DELETE FROM refs WHERE from_id IN (SELECT id FROM symbols WHERE file = ?)").run(
@@ -6323,64 +6286,12 @@ var IndexStore = class _IndexStore {
       );
     });
   }
-  /**
-   * Resolve `to_name` → `to_id` for all refs that have a name but no id.
-   * Call this after all symbols have been inserted to fill in cross-references.
-   *
-   * A match additionally requires the referencing ref and the target symbol to
-   * be in the same {@link LangFamily}. Without that guard a name match is a
-   * cross-language accident waiting to happen — `main`, `New`, `Parse` and
-   * `Config` are declared in most languages at once, and each collision draws a
-   * Code Atlas edge between files that never reference each other. Refs stored
-   * without a language keep the old global behaviour via the `'*'` wildcard row.
-   */
   resolveRefs() {
-    return this.runWithRetry(() => {
-      try {
-        const result = this.stmt(
-          `UPDATE refs
-           SET to_id = s.id
-           FROM (
-                 SELECT sym.name AS name, lf.family AS family, MIN(sym.id) AS id
-                   FROM symbols sym
-                   JOIN lang_family lf ON lf.lang = sym.lang
-                  GROUP BY sym.name, lf.family
-                 UNION ALL
-                 SELECT sym.name AS name, '${LANG_FAMILY_WILDCARD}' AS family, MIN(sym.id) AS id
-                   FROM symbols sym
-                  GROUP BY sym.name
-               ) AS s,
-               lang_family AS rf
-           WHERE refs.to_id IS NULL
-             AND refs.to_name IS NOT NULL
-             AND rf.lang = refs.lang
-             AND s.name = refs.to_name
-             AND s.family = rf.family`
-        ).run();
-        return result.changes ?? 0;
-      } catch {
-        const result = this.stmt(
-          `UPDATE refs SET to_id = (
-             SELECT sym.id FROM symbols sym
-              WHERE sym.name = refs.to_name AND ${_IndexStore.FAMILY_MATCH_SQL}
-              ORDER BY sym.id LIMIT 1
-           ) WHERE to_id IS NULL AND to_name IS NOT NULL
-             AND EXISTS (
-               SELECT 1 FROM symbols sym
-                WHERE sym.name = refs.to_name AND ${_IndexStore.FAMILY_MATCH_SQL}
-             )`
-        ).run(LANG_FAMILY_WILDCARD, LANG_FAMILY_WILDCARD);
-        return result.changes ?? 0;
-      }
-    });
+    return this.runWithRetry(() => resolveRefsWithStatement((sql) => this.stmt(sql)));
   }
   resolveRefsForNames(names) {
     return this.runWithRetry(() => this.resolveRefsForNamesUnsafe(names));
   }
-  /**
-   * Clear symbols/refs for a file and mark it as indexed with zero symbols.
-   * Used by the indexer for empty-parse results so three writes share one txn.
-   */
   replaceEmptyFile(meta) {
     this.invalidateBm25();
     this.runWithRetry(() => {
@@ -6426,20 +6337,12 @@ var IndexStore = class _IndexStore {
       }
     });
   }
-  /** Best-effort query planner refresh after a large reindex. */
   optimize() {
     try {
       this.db.exec("PRAGMA optimize");
     } catch {
     }
   }
-  /**
-   * Reclaim page churn left by repeated force rebuilds.
-   *
-   * SQLite's DROP/CREATE path makes rebuilds fast but leaves pages on the
-   * freelist. Compact only large, materially sparse databases and only when the
-   * caller is already on a full-index maintenance path.
-   */
   compactIfNeeded(options = {}) {
     const minBytes = options.minBytes ?? 256 * 1024 * 1024;
     const minFreeRatio = options.minFreeRatio ?? 0.35;
@@ -6466,115 +6369,44 @@ var IndexStore = class _IndexStore {
       return false;
     }
   }
-  /**
-   * Find all symbols that reference the named target symbol (incoming callers).
-   * Accepts a name instead of an id so the agent doesn't need a prior lookup.
-   */
   findIncomingCallsByName(symbolName, file, limit = 100) {
     return findIncomingCallsByName((sql) => this.stmt(sql), symbolName, file, limit);
   }
-  /**
-   * Find all symbols that the named source symbol references (outgoing callees).
-   * Accepts a name instead of an id so the agent doesn't need a prior lookup.
-   */
   findOutgoingCallsByName(symbolName, file, limit = 100) {
     return findOutgoingCallsByName((sql) => this.stmt(sql), symbolName, file, limit);
   }
-  /**
-   * Transitive incoming-call tree: all symbols that transitively call the
-   * target, to an unbounded depth (cycle-safe via SQL UNION deduplication).
-   * Used by `codebase-incoming-calls` when the caller wants the full call
-   * chain rather than just direct callers.
-   */
   findTransitiveIncomingCallsByName(symbolName, file, limit = 200) {
     return findTransitiveIncomingCallsByName((sql) => this.stmt(sql), symbolName, file, limit);
   }
-  /**
-   * Transitive outgoing-call tree: all symbols the target transitively calls.
-   * Used by `codebase-outgoing-calls` when the caller wants the full
-   * dependency chain rather than just direct callees.
-   */
   findTransitiveOutgoingCallsByName(symbolName, file, limit = 200) {
     return findTransitiveOutgoingCallsByName((sql) => this.stmt(sql), symbolName, file, limit);
   }
-  /**
-   * Compute the set of symbol IDs reachable from the given seed IDs using a
-   * native SQLite recursive CTE. Used by dead-code detection to replace the
-   * in-memory BFS.
-   */
   findReachableSymbolIds(seedIds) {
     return findReachableSymbolIds((sql) => this.stmt(sql), seedIds);
   }
-  /**
-   * Find all references TO a given symbol (who calls / uses this symbol?).
-   */
   findRefsTo(symbolId) {
     return findRefsToWithStatement((sql) => this.stmt(sql), symbolId);
   }
-  /**
-   * Find all references FROM a given symbol (what does this symbol call/use?).
-   */
   findRefsFrom(symbolId) {
     return findRefsFromWithStatement((sql) => this.stmt(sql), symbolId);
   }
-  // ─── CodeMap graph aggregation ──────────────────────────────────────────────
-  /**
-   * Package-level graph: each workspace package is a node; edges are derived
-   * from cross-package symbol references (a symbol in package A references a
-   * symbol resolved in package B). Node metadata includes symbol/file counts.
-   */
   getPackageGraph() {
     return getPackageGraphWithStatement((sql) => this.stmt(sql));
   }
-  /**
-   * File-level graph for a single package: each file is a node; edges are
-   * derived from cross-file symbol references within the package.
-   */
   getFileGraph(packageFilter) {
     return getFileGraphWithStatement((sql) => this.stmt(sql), packageFilter);
   }
-  /**
-   * Symbol-level graph for a single file: each symbol is a node; edges are
-   * derived from intra-file and cross-file symbol references (who calls whom).
-   */
   getSymbolGraph(fileFilter) {
     return getSymbolGraphWithStatement((sql) => this.stmt(sql), fileFilter);
   }
-  /**
-   * Returns every symbol in the index. Used by dead-code analysis to
-   * build the full symbol universe for the reachability scan.
-   */
   getAllSymbols() {
     return this.stmt("SELECT id, name, file, kind, line FROM symbols ORDER BY id").all().map((r) => ({ ...r, kind: r.kind }));
   }
-  /**
-   * Returns every resolved reference (to_id IS NOT NULL). Used by
-   * dead-code analysis to build the consumer-ship graph. Refs whose
-   * target symbol id is null (unresolved imports) are excluded.
-   */
   getAllResolvedRefs() {
-    return this.stmt(
-      "SELECT from_id AS fromId, to_id AS toId, call_type AS callType FROM refs WHERE to_id IS NOT NULL"
-    ).all();
+    return getAllResolvedRefsWithStatement((sql) => this.stmt(sql));
   }
-  /**
-   * Returns ALL import refs (including unresolved) with their source-file
-   * path and resolved target id.  Used by the dead-code scan's file-level
-   * graph traversal to handle barrel-only entry points where no symbol
-   * carries the ref.
-   *
-   * Refs whose `from_id` doesn't match a known symbol (e.g. pure-barrel
-   * files with no declarations) will have `sourceFile === null`.
-   */
   getAllImportRefs() {
-    return this.stmt(
-      `SELECT s.file AS sourceFile, r.to_name AS toName, r.to_id AS toId,
-              r.call_type AS callType, r.line
-       FROM refs r
-       LEFT JOIN symbols s ON r.from_id = s.id
-       WHERE r.call_type = 'import'
-       ORDER BY r.line`
-    ).all();
+    return getAllImportRefsWithStatement((sql) => this.stmt(sql));
   }
   close() {
     this.stmtCache.clear();
@@ -7448,7 +7280,9 @@ var stopMemoryWatchdog = startSharedHeapWatchdog({
 var lastProgressBroadcastAt = 0;
 var externalWatcher;
 var DEFAULT_EXTERNAL_DEBOUNCE_MS = 400;
+var DEFAULT_EXTERNAL_COALESCE_WINDOW_MS = 50;
 var externalDebounceMs = DEFAULT_EXTERNAL_DEBOUNCE_MS;
+var externalCoalesceWindowMs = DEFAULT_EXTERNAL_COALESCE_WINDOW_MS;
 var externalDebounceTimers = /* @__PURE__ */ new Map();
 var externalReadyFiles = /* @__PURE__ */ new Set();
 var externalReadyFlush;
@@ -7720,9 +7554,14 @@ async function handleMessage(state, message) {
   if (message.type === "configure") {
     const previousWatchExternal = state.watchExternal;
     const previousDebounceMs = state.debounceMs;
+    const previousCoalesceWindowMs = state.coalesceWindowMs;
     try {
       state.watchExternal = message.watchExternal;
       state.debounceMs = Math.max(0, message.debounceMs);
+      state.coalesceWindowMs = Math.max(
+        0,
+        message.coalesceWindowMs ?? DEFAULT_EXTERNAL_COALESCE_WINDOW_MS
+      );
       reconcileExternalWatcher();
       send(state, {
         type: "response",
@@ -7736,6 +7575,7 @@ async function handleMessage(state, message) {
     } catch (error) {
       state.watchExternal = previousWatchExternal;
       state.debounceMs = previousDebounceMs;
+      state.coalesceWindowMs = previousCoalesceWindowMs;
       try {
         reconcileExternalWatcher();
       } catch {
@@ -7791,25 +7631,24 @@ function enqueueExternalFile(file) {
   const timer = setTimeout(() => {
     externalDebounceTimers.delete(file);
     externalReadyFiles.add(file);
-    if (!externalReadyFlush) {
-      externalReadyFlush = setImmediate(() => {
-        externalReadyFlush = void 0;
-        const files = [...externalReadyFiles].sort();
-        externalReadyFiles.clear();
-        void withIndexWrite(
-          (onProgress) => indexService(
-            {
-              projectRoot,
-              indexDir,
-              files
-            },
-            { onProgress }
-          )
-        ).catch(() => {
-        });
+    if (externalReadyFlush) clearTimeout(externalReadyFlush);
+    externalReadyFlush = setTimeout(() => {
+      externalReadyFlush = void 0;
+      const files = [...externalReadyFiles].sort();
+      externalReadyFiles.clear();
+      void withIndexWrite(
+        (onProgress) => indexService(
+          {
+            projectRoot,
+            indexDir,
+            files
+          },
+          { onProgress }
+        )
+      ).catch(() => {
       });
-      externalReadyFlush.unref?.();
-    }
+    }, externalCoalesceWindowMs);
+    externalReadyFlush.unref?.();
   }, externalDebounceMs);
   timer.unref?.();
   externalDebounceTimers.set(file, timer);
@@ -7841,7 +7680,7 @@ function stopExternalWatcher() {
   externalWatcher = void 0;
   for (const timer of externalDebounceTimers.values()) clearTimeout(timer);
   externalDebounceTimers.clear();
-  if (externalReadyFlush) clearImmediate(externalReadyFlush);
+  if (externalReadyFlush) clearTimeout(externalReadyFlush);
   externalReadyFlush = void 0;
   externalReadyFiles.clear();
 }
@@ -7849,10 +7688,12 @@ function reconcileExternalWatcher() {
   const owners = [...clients].filter((client) => client.watchExternal);
   if (owners.length === 0) {
     externalDebounceMs = DEFAULT_EXTERNAL_DEBOUNCE_MS;
+    externalCoalesceWindowMs = DEFAULT_EXTERNAL_COALESCE_WINDOW_MS;
     stopExternalWatcher();
     return;
   }
   externalDebounceMs = Math.min(...owners.map((client) => client.debounceMs));
+  externalCoalesceWindowMs = Math.min(...owners.map((client) => client.coalesceWindowMs));
   ensureExternalWatcher();
 }
 function consume(state, chunk) {
@@ -7919,6 +7760,7 @@ var server = net.createServer((socket) => {
     cancel: /* @__PURE__ */ new Map(),
     watchExternal: false,
     debounceMs: DEFAULT_EXTERNAL_DEBOUNCE_MS,
+    coalesceWindowMs: DEFAULT_EXTERNAL_COALESCE_WINDOW_MS,
     lastSeenAt: Date.now()
   };
   clients.add(state);