sweet-search 2.6.8 → 2.6.10

package/core/indexing/indexer-build.js

@@ -9,7 +9,7 @@ import { existsSync } from 'fs';
 import path from 'path';
 
 import { DB_PATHS, EMBEDDING_CONFIG, PROJECT_ROOT } from '../infrastructure/config/index.js';
-import { GraphExtractor, createGraphSchema, insertGraph } from '../graph/graph-extractor.js';
+import { GraphExtractor, createGraphSchema, insertGraph, rebuildGraphFts } from '../graph/graph-extractor.js';
 import { resolveRelationshipTargets } from '../graph/relationship-resolver.js';
 import { populatePageRankColumn } from '../graph/structural-pagerank.js';
 import { getEmbeddings, getModelInfo } from '../embedding/embedding-service.js';
@@ -153,6 +153,7 @@ export async function buildCodeGraph(files, dryRun = false) {
   let errors = 0;
   let totalEntities = 0;
   let totalRelationships = 0;
+  let graphFlushed = false;
 
   for (let i = 0; i < files.length; i++) {
     try {
@@ -170,10 +171,14 @@ export async function buildCodeGraph(files, dryRun = false) {
       errors++;
     }
 
-    // Flush batch every GRAPH_BATCH_SIZE files or at the end
+    // Flush batch every GRAPH_BATCH_SIZE files or at the end. FTS5 sync is
+    // deferred to ONE rebuild after the loop — 'rebuild' reconstructs the
+    // whole index from the entities table, so per-batch rebuilds were
+    // O(entities × batches) work discarded by the next batch.
     if ((i + 1) % GRAPH_BATCH_SIZE === 0 || i === files.length - 1) {
       if (entityBatch.length > 0 || relBatch.length > 0) {
-        insertGraph(db, entityBatch, relBatch, hasFts5);
+        insertGraph(db, entityBatch, relBatch, hasFts5, { syncFts: false });
+        graphFlushed = true;
         totalEntities += entityBatch.length;
         totalRelationships += relBatch.length;
         entityBatch = [];
@@ -186,6 +191,13 @@ export async function buildCodeGraph(files, dryRun = false) {
     }
   }
 
+  // Single FTS5 rebuild at the exact point the last per-batch rebuild used to
+  // run (before relationship resolution, whose entity updates were never
+  // reflected in FTS).
+  if (graphFlushed && hasFts5) {
+    rebuildGraphFts(db);
+  }
+
   log(`\n✓ Extracted ${totalEntities} entities, ${totalRelationships} relationships`, 'green');
   if (errors > 0) {
     log(`⚠ ${errors} files had errors`, 'yellow');
@@ -360,7 +372,9 @@ function annotateChunksForVectorInsert(chunks) {
       const idx = indices[i];
       annotations[idx] = {
         ...ids[i],
-        hashes: chunkInputHashes(chunks[idx]),
+        // Full indexing never persists dedup_fingerprint (only the reconcile
+        // delta writer does) — skip that hash.
+        hashes: chunkInputHashes(chunks[idx], { includeDedup: false }),
       };
     }
   }

package/core/indexing/indexer-phases.js

@@ -10,7 +10,7 @@ import path from 'path';
 import { DB_PATHS, PROJECT_ROOT, EMBEDDING_CONFIG, HCGS_CONFIG } from '../infrastructure/config/index.js';
 import { getChangedFiles, updateState, getStats as getIncrementalStats, updatePhaseProgress, markPhaseComplete, clearPhaseProgress } from './incremental-tracker.js';
 import { backupSummaries, restoreSummaries, markForRegeneration } from '../graph/summary-manager.js';
-import { colors, log, logProgress, logError, discoverFiles, readFilesFromStdin, atomicSwapDatabase } from './indexer-utils.js';
+import { colors, log, logProgress, logError, discoverFiles, readFilesFromStdin, atomicSwapDatabase, shouldStreamVectors } from './indexer-utils.js';
 import { buildCodeGraph, buildVectorIndex, chunkFiles } from './indexer-build.js';
 import { runDedupPhase, formatDedupSummary } from './dedup/dedup-phase.js';
 import { DEDUP_CONFIG } from '../infrastructure/config/index.js';
@@ -420,15 +420,24 @@ export async function buildVectorsAndArtifactsPhase(options = {}) {
   // model. For large full rebuilds we instead spill chunks to disk and embed/LI
   // in bounded windows (see streaming-vectors.js) so peak heap is O(window).
   //
-  // Gated by file count so small repos + incremental runs keep the original
-  // in-memory path byte-for-byte (benchmark indexes unaffected). Auto-selected,
-  // no opt-in flag; SWEET_SEARCH_STREAM_VECTORS=0 forces the legacy path and
-  // SWEET_SEARCH_STREAM_MIN_FILES tunes the threshold.
-  const streamMinFiles = Number(process.env.SWEET_SEARCH_STREAM_MIN_FILES) || 5000;
-  const useStreaming = !dryRun
-    && fullReindex
-    && filesToIndex.length >= streamMinFiles
-    && process.env.SWEET_SEARCH_STREAM_VECTORS !== '0';
+  // Gated by file count OR total admitted source bytes (see shouldStreamVectors
+  // in indexer-utils.js) so small repos + incremental runs keep the original
+  // in-memory path byte-for-byte (benchmark indexes unaffected). The byte
+  // trigger catches few-files-huge-bytes repos (amalgamations, vendored blobs)
+  // that OOM the in-memory path while staying under the file gate.
+  // Auto-selected, no opt-in flag; SWEET_SEARCH_STREAM_VECTORS=0 forces the
+  // legacy path, SWEET_SEARCH_STREAM_MIN_FILES / SWEET_SEARCH_STREAM_MIN_BYTES
+  // tune the thresholds.
+  const streamingDecision = await shouldStreamVectors({ filesToIndex, dryRun, fullReindex });
+  const useStreaming = streamingDecision.useStreaming;
+  if (streamingDecision.reason === 'bytes') {
+    log(
+      `  Streaming vectors: ${filesToIndex.length} files total ` +
+      `${(streamingDecision.totalBytes / 1048576).toFixed(0)}+ MB >= ` +
+      `${(streamingDecision.thresholdBytes / 1048576).toFixed(0)} MB (bounded memory)`,
+      'dim'
+    );
+  }
 
   // The in-memory path pre-chunks up front so both vector + LI encoders share
   // one chunk list. The streaming path does its own windowed chunking + dedup,
@@ -814,20 +823,32 @@ export async function updateIncrementalStatePhase(options = {}) {
     log('\nIncremental state updated', 'green');
   } else if (fullReindex) {
     const hashes = {};
-    for (const file of allFiles) {
-      try {
-        const fullPath = path.join(PROJECT_ROOT, file);
-        const [content, stat] = await Promise.all([
-          fs.readFile(fullPath),
-          fs.stat(fullPath, { bigint: true }).catch(() => null),
-        ]);
-        hashes[file] = {
-          hash: contentHashSync(content),
-          size: stat ? stat.size.toString() : null,
-          mtime_ns: stat ? stat.mtimeNs.toString() : null,
-          inode: stat ? stat.ino.toString() : null,
-        };
-      } catch (e) { /* skip */ }
+    // Batched read+stat (order-preserving assignment — key insertion order,
+    // and therefore the serialized state file, matches the sequential loop).
+    // Mirrors the H6 batching in incremental-tracker.getChangedFiles.
+    const HASH_BATCH = 100;
+    for (let i = 0; i < allFiles.length; i += HASH_BATCH) {
+      const batch = allFiles.slice(i, i + HASH_BATCH);
+      const results = await Promise.all(batch.map(async (file) => {
+        try {
+          const fullPath = path.join(PROJECT_ROOT, file);
+          const [content, stat] = await Promise.all([
+            fs.readFile(fullPath),
+            fs.stat(fullPath, { bigint: true }).catch(() => null),
+          ]);
+          return {
+            hash: contentHashSync(content),
+            size: stat ? stat.size.toString() : null,
+            mtime_ns: stat ? stat.mtimeNs.toString() : null,
+            inode: stat ? stat.ino.toString() : null,
+          };
+        } catch (e) {
+          return null; // skip
+        }
+      }));
+      for (let j = 0; j < batch.length; j++) {
+        if (results[j]) hashes[batch[j]] = results[j];
+      }
     }
     await updateState(hashes, {
       totalChunks: vectorStats.chunks,

package/core/indexing/indexer-utils.js

@@ -395,16 +395,22 @@ export async function discoverFiles(options = {}) {
 
   const files = [];
   let oversized = 0;
-  for (const file of allFiles) {
-    try {
-      const stat = await fs.stat(path.join(projectRoot, file));
+  // Stat in batches (order-preserving) instead of one serialized await per
+  // file; results are consumed in the original allFiles order.
+  const STAT_BATCH = 200;
+  for (let i = 0; i < allFiles.length; i += STAT_BATCH) {
+    const batch = allFiles.slice(i, i + STAT_BATCH);
+    const stats = await Promise.all(
+      batch.map((file) => fs.stat(path.join(projectRoot, file)).catch(() => null)),
+    );
+    for (let j = 0; j < batch.length; j++) {
+      const stat = stats[j];
+      if (!stat) continue; // File disappeared between glob and stat
       if (stat.size > maxFileSize) {
         oversized++;
       } else {
-        files.push(file);
+        files.push(batch[j]);
       }
-    } catch {
-      // File disappeared between glob and stat
     }
   }
 
@@ -426,3 +432,87 @@ export async function discoverFiles(options = {}) {
 
   return files;
 }
+
+// =============================================================================
+// STREAMING-VECTORS GATE
+// =============================================================================
+
+/**
+ * Sum on-disk sizes of `files` (relative to `projectRoot`), stopping as soon
+ * as the running total crosses `stopAt`. The streaming gate only needs to
+ * know whether the total crosses the threshold, not the exact figure, so on
+ * large-byte repos this exits after a fraction of the stats.
+ */
+export async function sumFileSizesUpTo(files, stopAt, projectRoot = PROJECT_ROOT) {
+  let total = 0;
+  for (const file of files) {
+    try {
+      const stat = await fs.stat(path.isAbsolute(file) ? file : path.join(projectRoot, file));
+      total += stat.size;
+      if (total >= stopAt) return total;
+    } catch {
+      // File disappeared between discovery and this gate — skip it.
+    }
+  }
+  return total;
+}
+
+/**
+ * Decide whether a full rebuild should take the bounded-memory streaming
+ * vectors path (see streaming-vectors.js) instead of the in-memory path.
+ *
+ * Two independent triggers, either is sufficient:
+ *   - file count ≥ SWEET_SEARCH_STREAM_MIN_FILES (default 5000)
+ *   - total admitted source bytes ≥ SWEET_SEARCH_STREAM_MIN_BYTES
+ *     (default 512 MB; set to 0 to disable the byte trigger)
+ *
+ * The byte trigger exists because peak heap on the in-memory path scales
+ * with the chunk corpus (≈ source bytes), not file count: a repo with
+ * few-but-huge files (amalgamations, vendored/generated blobs, extreme
+ * duplication) can OOM the default ~4 GB heap while staying far under the
+ * file gate.
+ *
+ * The 512 MB default is deliberately conservative so the trigger only fires
+ * where the in-memory path would fail outright, never where it would merely
+ * be tight. The one MEASURED failure at this scale is libsql (596 MB
+ * admitted source; the in-memory path needed a 9.6+ GB heap); the wider
+ * crash zone is ESTIMATED — not measured — to start around ~200 MB of
+ * admitted source on a default ~4 GB heap. A repo the byte trigger newly
+ * moves to streaming was therefore not getting a usable in-memory index at
+ * all, so streaming strictly improves on a crash; every repo below the
+ * threshold keeps the byte-for-byte-identical in-memory path and identical
+ * retrieval behaviour.
+ *
+ * Sizes are only stat'd when the (free) count trigger hasn't already fired,
+ * so the byte check costs at most one stat per file on sub-threshold repos.
+ * The re-stat duplicates work discoverFiles already did for its size cap —
+ * accepted deliberately: threading sizes through would change discoverFiles'
+ * public return shape, and ≤5000 extra stats on a full rebuild is noise next
+ * to chunking + embedding.
+ *
+ * @returns {Promise<{useStreaming: boolean, reason?: 'files'|'bytes', totalBytes?: number, thresholdBytes?: number}>}
+ */
+export async function shouldStreamVectors({ filesToIndex, dryRun, fullReindex, projectRoot = PROJECT_ROOT, env = process.env }) {
+  if (dryRun || !fullReindex || env.SWEET_SEARCH_STREAM_VECTORS === '0') {
+    return { useStreaming: false };
+  }
+  const streamMinFiles = Number(env.SWEET_SEARCH_STREAM_MIN_FILES) || 5000;
+  if (filesToIndex.length >= streamMinFiles) {
+    return { useStreaming: true, reason: 'files' };
+  }
+  // Unset/empty/invalid → 512 MB default; an explicit 0 (or negative)
+  // disables the byte trigger alone, leaving the count trigger active.
+  const rawMinBytes = env.SWEET_SEARCH_STREAM_MIN_BYTES;
+  const parsedMinBytes = (rawMinBytes === undefined || rawMinBytes === '') ? NaN : Number(rawMinBytes);
+  const streamMinBytes = Number.isFinite(parsedMinBytes)
+    ? (parsedMinBytes > 0 ? parsedMinBytes : Infinity)
+    : 512 * 1024 * 1024;
+  if (!Number.isFinite(streamMinBytes)) {
+    return { useStreaming: false };
+  }
+  const totalBytes = await sumFileSizesUpTo(filesToIndex, streamMinBytes, projectRoot);
+  if (totalBytes >= streamMinBytes) {
+    return { useStreaming: true, reason: 'bytes', totalBytes, thresholdBytes: streamMinBytes };
+  }
+  return { useStreaming: false };
+}

package/core/indexing/indexing-file-policy.js

@@ -8,7 +8,7 @@
  */
 
 import { existsSync, readFileSync } from 'fs';
-import { minimatch } from 'minimatch';
+import { Minimatch } from 'minimatch';
 import { loadProjectConfig } from '../infrastructure/config/index.js';
 
 const MM_OPTS = { dot: true, nocase: false };
@@ -54,6 +54,31 @@ function getExcludes(projectRoot) {
 function resetCache() {
   _excludesByRoot.clear();
   _cachedExtraPatterns = null;
+  _excludeMatchersByRoot.clear();
+  _cachedExtraMatchers = null;
+}
+
+// Precompiled Minimatch instances — `minimatch(p, g, opts)` recompiles the
+// glob to a regex on every call; `new Minimatch(g, opts).match(p)` is the
+// documented equivalent with the compile amortized.
+const _excludeMatchersByRoot = new Map();
+
+function getExcludeMatchers(projectRoot) {
+  const key = projectRoot || '__cwd__';
+  let cached = _excludeMatchersByRoot.get(key);
+  if (cached) return cached;
+  cached = getExcludes(projectRoot)
+    .filter((g) => typeof g === 'string')
+    .map((g) => new Minimatch(g, MM_OPTS));
+  _excludeMatchersByRoot.set(key, cached);
+  return cached;
+}
+
+let _cachedExtraMatchers = null;
+function getExtraMatchers() {
+  if (_cachedExtraMatchers !== null) return _cachedExtraMatchers;
+  _cachedExtraMatchers = loadExtraPatternsFromFile().map((g) => new Minimatch(g, MM_OPTS));
+  return _cachedExtraMatchers;
 }
 
 const GENERATED_MARKERS = [
@@ -87,13 +112,11 @@ function loadExtraPatternsFromFile() {
 export function isExcludedByConfig(filePath, projectRoot) {
   if (!filePath) return false;
   const p = normalizePath(filePath);
-  const excludes = getExcludes(projectRoot);
-  for (const g of excludes) {
-    if (typeof g === 'string' && minimatch(p, g, MM_OPTS)) return true;
+  for (const m of getExcludeMatchers(projectRoot)) {
+    if (m.match(p)) return true;
   }
-  const extras = loadExtraPatternsFromFile();
-  for (const g of extras) {
-    if (minimatch(p, g, MM_OPTS)) return true;
+  for (const m of getExtraMatchers()) {
+    if (m.match(p)) return true;
   }
   return false;
 }

package/core/indexing/model-pool.js

@@ -29,12 +29,15 @@ import {
   getLocalPipeline,
   callLocalModelCpu,
   unloadLocalModel,
+  configureLocalModelRuntime,
 } from '../embedding/embedding-local-model.js';
 import {
   getLateInteractionPipeline,
   encodeDocumentsCpu,
   unloadLateInteractionModel,
+  configureLateInteractionRuntime,
 } from '../ranking/late-interaction-model.js';
+import { backgroundIntraOpThreads } from '../infrastructure/onnx-session-utils.js';
 
 /**
  * Small-changeset threshold. Incremental runs with fewer files than this use
@@ -69,6 +72,29 @@ export function selectAcceleratorDeviceKind(pref) {
   return null;
 }
 
+/**
+ * G3: arm the BACKGROUND/maintainer ORT profile for BOTH resident CPU
+ * sessions — dense (embedding-local-model) and late-interaction. The profile
+ * (force_spinning_stop + arena-off + 2–4 intra-op threads) prevents the two
+ * resident-daemon pathologies: idle spinning workers (~a core of idle CPU)
+ * and monotonic RSS from ORT arena extension (#25325; measured 354 × 128MB
+ * ≈ 34GB after one edit-heavy day when the LI session was left on the
+ * foreground profile). MUST run before the first encode — both session
+ * singletons are built once; configuring after is a silent no-op.
+ *
+ * Lives here (model-pool owns indexing-side model lifecycle) so daemon
+ * entrypoints don't need their own cross-context imports of the two model
+ * modules.
+ *
+ * @returns {{armed: boolean}}
+ */
+export function armBackgroundOrtProfiles() {
+  const intraOpThreads = backgroundIntraOpThreads();
+  configureLocalModelRuntime({ intraOpThreads, background: true });
+  configureLateInteractionRuntime({ intraOpThreads, background: true });
+  return { armed: true };
+}
+
 /**
  * Whether this process can use an inference accelerator (Metal / CoreML
  * cascade / CUDA) for indexing. Requires both accelerator-capable hardware

package/core/indexing/rss-budget.mjs

@@ -112,6 +112,71 @@ export function isOverBudget(totalRssBytes, budgetBytesValue) {
   );
 }
 
+// =============================================================================
+// D.5: per-process maintainer RSS recycle ceiling
+// =============================================================================
+//
+// The fleet budget above evicts the longest-IDLE daemon, so a single fat
+// ACTIVE maintainer can legitimately ride up to the whole fleet budget
+// (~76 GB on a 128 GB host) — measured in the wild when a session-config
+// regression left the LI ORT session on the foreground arena profile
+// (354 × 128MB arena extensions ≈ 34 GB RSS). This ceiling is the
+// per-process backstop: when the maintainer's OWN rss crosses the line at a
+// tick boundary, it requests the same graceful shutdown the idle-TTL uses
+// (finish tick, publish, release lock, exit). The O_EXCL launch trigger
+// respawns a fresh few-hundred-MB process on the next dirty event, so the
+// index is unchanged — exit-to-reclaim is already the sanctioned way to
+// return ORT memory (#25325).
+//
+// Guards against restart-thrash:
+//   - at least one COMPLETED tick (never abort startup work),
+//   - minimum uptime (default 10 min ⇒ worst case 6 recycles/hour even when
+//     the ceiling is misconfigured below the resident floor — visible via
+//     the per-recycle WARN, which names the env knob to raise).
+//
+// Measured anchors (2026-07-03, arena-off profile): steady floor ~2.7-2.9 GB
+// on a mid-size repo, encode-active peaks ~4.7 GB — hence the 4 GiB default
+// floor and 8 GiB cap.
+
+const MAINTAINER_RSS_CEILING_FRACTION = 0.25;
+const MAINTAINER_RSS_CEILING_MIN_BYTES = 4 * 1024 * 1024 * 1024;  // 4 GiB
+const MAINTAINER_RSS_CEILING_MAX_BYTES = 8 * 1024 * 1024 * 1024;  // 8 GiB
+const MAINTAINER_RSS_MIN_UPTIME_MS_DEFAULT = 10 * 60 * 1000;      // 10 min
+
+/**
+ * Resolve the per-process maintainer RSS ceiling in bytes.
+ * `SWEET_SEARCH_MAINTAINER_RSS_MAX_MB` set: explicit MB value; 0/garbage
+ * disables (returns 0). Unset: clamp(25% of RAM, 4 GiB, 8 GiB).
+ */
+export function maintainerRssCeilingBytes(env = process.env, totalMem = os.totalmem()) {
+  const raw = env.SWEET_SEARCH_MAINTAINER_RSS_MAX_MB;
+  if (raw != null && raw !== '') {
+    const mb = Number(raw);
+    if (!Number.isFinite(mb) || mb <= 0) return 0;
+    return Math.floor(mb * 1024 * 1024);
+  }
+  const scaled = Math.floor(totalMem * MAINTAINER_RSS_CEILING_FRACTION);
+  return Math.min(MAINTAINER_RSS_CEILING_MAX_BYTES, Math.max(MAINTAINER_RSS_CEILING_MIN_BYTES, scaled));
+}
+
+/** Minimum uptime before an RSS recycle may fire. */
+export function maintainerRssMinUptimeMs(env = process.env) {
+  const raw = Number(env.SWEET_SEARCH_MAINTAINER_RSS_MIN_UPTIME_MS);
+  return Number.isFinite(raw) && raw >= 0 ? raw : MAINTAINER_RSS_MIN_UPTIME_MS_DEFAULT;
+}
+
+/**
+ * Pure recycle decision — evaluated at tick boundaries only.
+ * @returns {{recycle: boolean, reason: string}}
+ */
+export function shouldRecycleForRss({ rssBytes, ceilingBytes, uptimeMs, minUptimeMs, ticksCompleted }) {
+  if (!Number.isFinite(ceilingBytes) || ceilingBytes <= 0) return { recycle: false, reason: 'disabled' };
+  if (!Number.isFinite(rssBytes) || rssBytes <= ceilingBytes) return { recycle: false, reason: 'under-ceiling' };
+  if (!(ticksCompleted >= 1)) return { recycle: false, reason: 'no-completed-tick' };
+  if (!(uptimeMs >= minUptimeMs)) return { recycle: false, reason: 'min-uptime' };
+  return { recycle: true, reason: 'over-ceiling' };
+}
+
 /**
  * Read the resident-set size (bytes) of an arbitrary pid, best-effort and
  * cross-platform. Returns a non-negative integer, or 0 when unknown (dead pid,

package/core/infrastructure/code-graph-repository.js

@@ -10,7 +10,7 @@
 
 import Database from 'better-sqlite3';
 import { existsSync, statSync } from 'fs';
-import { applyReadPragmas } from './db-utils.js';
+import { applyReadPragmas, prepareCached } from './db-utils.js';
 import { readAdjacentManifest, resolveManifestCodeGraphPath, sqlAliasPrefix } from './code-graph-visibility.js';
 
 export class CodeGraphRepository {
@@ -72,7 +72,7 @@ export class CodeGraphRepository {
   }
 
   _hasColumns(db, table, columns) {
-    const rows = db.prepare(`PRAGMA table_info(${table})`).all();
+    const rows = prepareCached(db, `PRAGMA table_info(${table})`).all();
     const names = new Set(rows.map((row) => row.name));
     return columns.every((column) => names.has(column));
   }
@@ -138,7 +138,7 @@ export class CodeGraphRepository {
     const db = this._open();
     if (!db) return null;
     try {
-      const row = db.prepare(`
+      const row = prepareCached(db, `
         SELECT id, name, type, start_line, end_line, parent_class
         FROM entities
         WHERE file_path = ?
@@ -207,7 +207,7 @@ export class CodeGraphRepository {
       // in the chunk range (catches entities like a multi-chunk struct whose
       // declaration starts in this chunk but body extends beyond — e.g. gin
       // Engine struct at gin.go:92-189 split across chunks 92-133 and 134-189).
-      const containedRows = db.prepare(`
+      const containedRows = prepareCached(db, `
         SELECT name, type, start_line, end_line FROM entities
         WHERE file_path = ? AND start_line >= ? AND end_line <= ? AND ${this._entityVisibilitySql(db)}
         ORDER BY (end_line - start_line) DESC
@@ -219,7 +219,7 @@ export class CodeGraphRepository {
           return { name: row.name, type: row.type, startLine: row.start_line, endLine: row.end_line };
         }
       }
-      const startsInRows = db.prepare(`
+      const startsInRows = prepareCached(db, `
         SELECT name, type, start_line, end_line FROM entities
         WHERE file_path = ? AND start_line >= ? AND start_line <= ? AND ${this._entityVisibilitySql(db)}
         ORDER BY (end_line - start_line) DESC
@@ -245,7 +245,7 @@ export class CodeGraphRepository {
     const db = this._open();
     if (!db) return null;
     try {
-      const row = db.prepare(`
+      const row = prepareCached(db, `
         SELECT id, name, type, start_line, end_line, parent_class
         FROM entities
         WHERE file_path = ?
@@ -289,7 +289,7 @@ export class CodeGraphRepository {
     const db = this._open();
     if (!db) return [];
     try {
-      const rows = db.prepare(`
+      const rows = prepareCached(db, `
         SELECT id, name, type, start_line, end_line, parent_class
         FROM entities
         WHERE file_path = ?
@@ -322,7 +322,7 @@ export class CodeGraphRepository {
     const db = this._open();
     if (!db) return null;
     try {
-      const row = db.prepare(`
+      const row = prepareCached(db, `
         SELECT id, name, type, file_path, start_line, end_line, parent_class
         FROM entities
         WHERE id = ? AND ${this._entityVisibilitySql(db)}
@@ -379,7 +379,7 @@ export class CodeGraphRepository {
       const args = types
         ? [...this._entityVisibilityParams(db), sourceId, ...this._relationshipVisibilityParams(db), ...types, limit]
         : [...this._entityVisibilityParams(db), sourceId, ...this._relationshipVisibilityParams(db), limit];
-      const rows = db.prepare(baseSql).all(...args);
+      const rows = prepareCached(db, baseSql).all(...args);
       return rows.map(r => ({
         type: r.rel_type,
         targetName: r.target_name,
@@ -445,7 +445,7 @@ export class CodeGraphRepository {
       const args = excludeFile
         ? [...uniq, ...types, ...this._entityVisibilityParams(db), excludeFile, limit]
         : [...uniq, ...types, ...this._entityVisibilityParams(db), limit];
-      const rows = db.prepare(sql).all(...args);
+      const rows = prepareCached(db, sql).all(...args);
       // De-dup by name+type, keeping the first (smallest body).
       const seen = new Set();
       const out = [];
@@ -493,7 +493,7 @@ export class CodeGraphRepository {
         ORDER BY (end_line - start_line) ASC
         LIMIT ?
       `;
-      const rows = db.prepare(sql).all(...uniq, ...types, ...this._entityVisibilityParams(db), limit);
+      const rows = prepareCached(db, sql).all(...uniq, ...types, ...this._entityVisibilityParams(db), limit);
       return rows.map(row => ({
         id: row.id,
         name: row.name,
@@ -549,7 +549,7 @@ export class CodeGraphRepository {
         ORDER BY (end_line - start_line) ASC
         LIMIT ?
       `;
-      const rows = db.prepare(sql).all(...uniq, ...exclude, ...this._entityVisibilityParams(db), limit);
+      const rows = prepareCached(db, sql).all(...uniq, ...exclude, ...this._entityVisibilityParams(db), limit);
       return rows.map(row => ({
         id: row.id,
         name: row.name,
@@ -598,7 +598,7 @@ export class CodeGraphRepository {
           AND ${this._entityVisibilitySql(db)}
         GROUP BY lname
       `;
-      const rows = db.prepare(sql).all(...uniq, ...exclude, ...this._entityVisibilityParams(db));
+      const rows = prepareCached(db, sql).all(...uniq, ...exclude, ...this._entityVisibilityParams(db));
       const map = new Map();
       for (const r of rows) map.set(r.lname, r.count);
       // Names with no row are absent — caller treats absent as 0.
@@ -640,7 +640,7 @@ export class CodeGraphRepository {
       const args = types
         ? [...this._entityVisibilityParams(db), targetId, ...this._relationshipVisibilityParams(db), ...types, limit]
         : [...this._entityVisibilityParams(db), targetId, ...this._relationshipVisibilityParams(db), limit];
-      const rows = db.prepare(baseSql).all(...args);
+      const rows = prepareCached(db, baseSql).all(...args);
       return rows.map(r => ({
         type: r.rel_type,
         contextLine: r.context_line || null,
@@ -689,7 +689,7 @@ export class CodeGraphRepository {
       return Number.isFinite(n) && n > 0 ? n : 12;
     })();
     try {
-      const rows = db.prepare(`
+      const rows = prepareCached(db, `
         SELECT r.target_name, COUNT(*) as cnt
         FROM relationships r
         LEFT JOIN entities e ON e.id = r.target_id AND ${this._entityVisibilitySql(db, 'e')}
@@ -798,7 +798,7 @@ export class CodeGraphRepository {
     if (!db) return null;
     try {
       if (this._hasColumns(db, 'entities', ['epoch_written', 'epoch_retired'])) {
-        const visible = db.prepare(`
+        const visible = prepareCached(db, `
           SELECT 1 FROM entities
           WHERE file_path = ? AND ${this._entityVisibilitySql(db)}
           LIMIT 1
@@ -827,10 +827,10 @@ export class CodeGraphRepository {
         const staleArgs = this._manifestEpoch !== null
           ? [filePath, this._manifestEpoch, this._manifestEpoch]
           : [filePath];
-        const staleRow = db.prepare(staleSql).get(...staleArgs);
+        const staleRow = prepareCached(db, staleSql).get(...staleArgs);
         return staleRow ? { staleSince: staleRow.stale_since || null } : null;
       }
-      const row = db.prepare(`
+      const row = prepareCached(db, `
         SELECT stale_since, MIN(ROWID) as first_row
         FROM entities
         WHERE file_path = ?

package/core/infrastructure/db-utils.js

@@ -17,6 +17,35 @@ import Database from 'better-sqlite3';
  */
 export const SAFE_IN_CLAUSE_BATCH = 999;
 
+// Per-connection prepared-statement cache. Statements belong to their
+// Database object, so the WeakMap self-invalidates when a connection object
+// is dropped (closed connections are never passed back in by callers).
+// Only use for .get/.all/.run statements — never .iterate (a cached statement
+// mid-iteration cannot be re-entered).
+const _stmtCaches = new WeakMap();
+
+/**
+ * db.prepare with a per-connection cache — compiles each distinct SQL string
+ * once per Database object instead of once per call.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} sql
+ * @returns {import('better-sqlite3').Statement}
+ */
+export function prepareCached(db, sql) {
+  let cache = _stmtCaches.get(db);
+  if (!cache) {
+    cache = new Map();
+    _stmtCaches.set(db, cache);
+  }
+  let stmt = cache.get(sql);
+  if (!stmt) {
+    stmt = db.prepare(sql);
+    cache.set(sql, stmt);
+  }
+  return stmt;
+}
+
 /**
  * Apply read-path PRAGMA optimizations to a read-only database connection.
  *