@optave/codegraph 3.4.1 → 3.5.0

package/src/domain/graph/builder/stages/build-edges.ts

@@ -6,8 +6,9 @@
  */
 import path from 'node:path';
 import { performance } from 'node:perf_hooks';
-import { getNodeId } from '../../../../db/index.js';
-import { loadNative } from '../../../../infrastructure/native.js';
+import { getNodeId } from '#db/index.js';
+import { debug } from '#infrastructure/logger.js';
+import { loadNative } from '#infrastructure/native.js';
 import type {
   BetterSqlite3Database,
   Call,
@@ -17,7 +18,7 @@ import type {
   NativeAddon,
   NodeRow,
   TypeMapEntry,
-} from '../../../../types.js';
+} from '#types';
 import { computeConfidence } from '../../resolve.js';
 import type { PipelineContext } from '../context.js';
 import { BUILTIN_RECEIVERS, batchInsertEdges } from '../helpers.js';
@@ -561,22 +562,94 @@ function buildClassHierarchyEdges(
 
 // ── Main entry point ────────────────────────────────────────────────────
 
+/**
+ * For small incremental builds (≤5 changed files on a large codebase), scope
+ * the node loading query to only files that are relevant: changed files +
+ * their import targets. Falls back to loading ALL nodes for full builds or
+ * larger incremental changes.
+ */
+function loadNodes(ctx: PipelineContext): { rows: QueryNodeRow[]; scoped: boolean } {
+  const { db, fileSymbols, isFullBuild, batchResolved } = ctx;
+  const nodeKindFilter = `kind IN ('function','method','class','interface','struct','type','module','enum','trait','record','constant')`;
+
+  // Gate: only scope for small incremental on large codebases
+  if (!isFullBuild && fileSymbols.size <= 5) {
+    const existingFileCount = (
+      db.prepare("SELECT COUNT(*) as c FROM nodes WHERE kind = 'file'").get() as { c: number }
+    ).c;
+    if (existingFileCount > 20) {
+      // Collect relevant files: changed files + their import targets
+      const relevantFiles = new Set<string>(fileSymbols.keys());
+      if (batchResolved) {
+        for (const resolvedPath of batchResolved.values()) {
+          relevantFiles.add(resolvedPath);
+        }
+      }
+      // Also add barrel-only files
+      for (const barrelPath of ctx.barrelOnlyFiles) {
+        relevantFiles.add(barrelPath);
+      }
+
+      const placeholders = [...relevantFiles].map(() => '?').join(',');
+      const rows = db
+        .prepare(
+          `SELECT id, name, kind, file, line FROM nodes WHERE ${nodeKindFilter} AND file IN (${placeholders})`,
+        )
+        .all(...relevantFiles) as QueryNodeRow[];
+      return { rows, scoped: true };
+    }
+  }
+
+  const rows = db
+    .prepare(`SELECT id, name, kind, file, line FROM nodes WHERE ${nodeKindFilter}`)
+    .all() as QueryNodeRow[];
+  return { rows, scoped: false };
+}
+
+/**
+ * For scoped node loading, patch nodesByName.get with a lazy SQL fallback
+ * so global name-only lookups (resolveByMethodOrGlobal, supplementReceiverEdges)
+ * can still find nodes outside the scoped set.
+ */
+function addLazyFallback(ctx: PipelineContext, scopedLoad: boolean): void {
+  if (!scopedLoad) return;
+  const { db } = ctx;
+  const fallbackStmt = db.prepare(
+    `SELECT id, name, kind, file, line FROM nodes WHERE name = ? AND kind != 'file'`,
+  );
+  const originalGet = ctx.nodesByName.get.bind(ctx.nodesByName);
+  ctx.nodesByName.get = (name: string) => {
+    const result = originalGet(name);
+    if (result !== undefined) return result;
+    const rows = fallbackStmt.all(name) as unknown as NodeRow[];
+    if (rows.length > 0) {
+      ctx.nodesByName.set(name, rows);
+      return rows;
+    }
+    return undefined;
+  };
+}
+
 export async function buildEdges(ctx: PipelineContext): Promise<void> {
   const { db, engineName } = ctx;
 
   const getNodeIdStmt = makeGetNodeIdStmt(db);
 
-  const allNodes = db
-    .prepare(
-      `SELECT id, name, kind, file, line FROM nodes WHERE kind IN ('function','method','class','interface','struct','type','module','enum','trait','record','constant')`,
-    )
-    .all() as QueryNodeRow[];
-  setupNodeLookups(ctx, allNodes);
+  const { rows: allNodesBefore, scoped: scopedLoad } = loadNodes(ctx);
+  setupNodeLookups(ctx, allNodesBefore);
+  addLazyFallback(ctx, scopedLoad);
 
   const t0 = performance.now();
-  const buildEdgesTx = db.transaction(() => {
-    // Delete stale outgoing edges for barrel-only files inside the transaction
-    // so that deletion and re-creation are atomic (no edge loss on mid-build crash).
+  const native = engineName === 'native' ? loadNative() : null;
+
+  // Phase 1: Compute edges inside a better-sqlite3 transaction.
+  // Barrel-edge deletion lives here so that the JS path (which also inserts
+  // edges in this transaction) keeps deletion + insertion atomic.
+  // When using the native rusqlite path, insertion happens in Phase 2 on a
+  // separate connection — a crash between Phase 1 and Phase 2 would leave
+  // barrel edges missing until the next incremental rebuild re-creates them.
+  const allEdgeRows: EdgeRowTuple[] = [];
+  const computeEdgesTx = db.transaction(() => {
     if (ctx.barrelOnlyFiles.size > 0) {
       const deleteOutgoingEdges = db.prepare(
         'DELETE FROM edges WHERE source_id IN (SELECT id FROM nodes WHERE file = ?)',
@@ -586,19 +659,44 @@ export async function buildEdges(ctx: PipelineContext): Promise<void> {
       }
     }
 
-    const allEdgeRows: EdgeRowTuple[] = [];
-
     buildImportEdges(ctx, getNodeIdStmt, allEdgeRows);
 
-    const native = engineName === 'native' ? loadNative() : null;
-    if (native?.buildCallEdges) {
-      buildCallEdgesNative(ctx, getNodeIdStmt, allEdgeRows, allNodes, native);
+    // Skip native call-edge path for small incremental builds (≤3 files):
+    // napi-rs marshaling overhead for allNodes exceeds computation savings.
+    const useNativeCallEdges =
+      native?.buildCallEdges && (ctx.isFullBuild || ctx.fileSymbols.size > 3);
+    if (useNativeCallEdges) {
+      buildCallEdgesNative(ctx, getNodeIdStmt, allEdgeRows, allNodesBefore, native!);
     } else {
       buildCallEdgesJS(ctx, getNodeIdStmt, allEdgeRows);
     }
 
-    batchInsertEdges(db, allEdgeRows);
+    // When using native edge insert, skip JS insert here — do it after tx commits.
+    // Otherwise insert edges within this transaction for atomicity.
+    const useNativeEdgeInsert = !!ctx.nativeDb?.bulkInsertEdges;
+    if (!useNativeEdgeInsert) {
+      batchInsertEdges(db, allEdgeRows);
+    }
   });
-  buildEdgesTx();
+  computeEdgesTx();
+
+  // Phase 2: Native rusqlite bulk insert (outside better-sqlite3 transaction
+  // to avoid SQLITE_BUSY contention). Uses NativeDatabase persistent connection.
+  // Standalone napi functions were removed in 6.17.
+  if (ctx.nativeDb?.bulkInsertEdges && allEdgeRows.length > 0) {
+    const nativeEdges = allEdgeRows.map((r) => ({
+      sourceId: r[0],
+      targetId: r[1],
+      kind: r[2],
+      confidence: r[3],
+      dynamic: r[4],
+    }));
+    const ok = ctx.nativeDb.bulkInsertEdges(nativeEdges);
+    if (!ok) {
+      debug('Native bulkInsertEdges failed — falling back to JS batchInsertEdges');
+      batchInsertEdges(db, allEdgeRows);
+    }
+  }
+
   ctx.timing.edgesMs = performance.now() - t0;
 }

package/src/domain/graph/builder/stages/build-structure.ts

@@ -5,9 +5,9 @@
  */
 import path from 'node:path';
 import { performance } from 'node:perf_hooks';
-import { debug } from '../../../../infrastructure/logger.js';
-import { normalizePath } from '../../../../shared/constants.js';
-import type { ExtractorOutput } from '../../../../types.js';
+import { debug } from '#infrastructure/logger.js';
+import { normalizePath } from '#shared/constants.js';
+import type { ExtractorOutput } from '#types';
 import type { PipelineContext } from '../context.js';
 import { readFileSafe } from '../helpers.js';
 
@@ -40,7 +40,13 @@ export async function buildStructure(ctx: PipelineContext): Promise<void> {
   // Gate: ≤5 changed files AND significantly more existing files (>20) to
   // avoid triggering on small test fixtures where directory metrics matter.
   const existingFileCount = !isFullBuild
-    ? (db.prepare("SELECT COUNT(*) as c FROM nodes WHERE kind = 'file'").get() as { c: number }).c
+    ? (
+        (ctx.nativeDb
+          ? ctx.nativeDb.queryGet("SELECT COUNT(*) as c FROM nodes WHERE kind = 'file'", [])
+          : db.prepare("SELECT COUNT(*) as c FROM nodes WHERE kind = 'file'").get()) as {
+          c: number;
+        }
+      ).c
     : 0;
   const useSmallIncrementalFastPath =
     !isFullBuild &&
@@ -86,13 +92,43 @@ export async function buildStructure(ctx: PipelineContext): Promise<void> {
   // Classify node roles (incremental: only reclassify changed files' nodes)
   const t1 = performance.now();
   try {
-    const { classifyNodeRoles } = (await import('../../../../features/structure.js')) as {
-      classifyNodeRoles: (
-        db: PipelineContext['db'],
-        changedFiles?: string[] | null,
-      ) => Record<string, number>;
-    };
-    const roleSummary = classifyNodeRoles(db, changedFileList);
+    let roleSummary: Record<string, number> | null = null;
+
+    // Use NativeDatabase persistent connection (Phase 6.15+).
+    // Standalone napi functions were removed in 6.17 — falls through to JS if nativeDb unavailable.
+    if (ctx.nativeDb?.classifyRolesFull) {
+      const nativeResult =
+        changedFileList && changedFileList.length > 0
+          ? ctx.nativeDb.classifyRolesIncremental(changedFileList)
+          : ctx.nativeDb.classifyRolesFull();
+      if (nativeResult) {
+        roleSummary = {
+          entry: nativeResult.entry,
+          core: nativeResult.core,
+          utility: nativeResult.utility,
+          adapter: nativeResult.adapter,
+          dead: nativeResult.dead,
+          'dead-leaf': nativeResult.deadLeaf,
+          'dead-entry': nativeResult.deadEntry,
+          'dead-ffi': nativeResult.deadFfi,
+          'dead-unresolved': nativeResult.deadUnresolved,
+          'test-only': nativeResult.testOnly,
+          leaf: nativeResult.leaf,
+        };
+      }
+    }
+
+    // Fall back to JS path
+    if (!roleSummary) {
+      const { classifyNodeRoles } = (await import('../../../../features/structure.js')) as {
+        classifyNodeRoles: (
+          db: PipelineContext['db'],
+          changedFiles?: string[] | null,
+        ) => Record<string, number>;
+      };
+      roleSummary = classifyNodeRoles(db, changedFileList);
+    }
+
     debug(
       `Roles${changedFileList ? ` (incremental, ${changedFileList.length} files)` : ''}: ${Object.entries(
         roleSummary,

package/src/domain/graph/builder/stages/collect-files.ts

@@ -2,14 +2,78 @@
  * Stage: collectFiles
  *
  * Collects all source files to process. Handles both normal and scoped rebuilds.
+ * For incremental builds with a valid journal, reconstructs the file list from
+ * the DB's file_hashes table + journal deltas, skipping the filesystem scan.
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { info } from '../../../../infrastructure/logger.js';
-import { normalizePath } from '../../../../shared/constants.js';
+import { debug, info } from '#infrastructure/logger.js';
+import { normalizePath } from '#shared/constants.js';
+import { readJournal } from '../../journal.js';
 import type { PipelineContext } from '../context.js';
 import { collectFiles as collectFilesUtil } from '../helpers.js';
 
+/**
+ * Reconstruct allFiles from DB file_hashes + journal deltas.
+ * Returns null when the fast path isn't applicable (first build, no journal, etc).
+ */
+function tryFastCollect(
+  ctx: PipelineContext,
+): { files: string[]; directories: Set<string> } | null {
+  const { db, rootDir } = ctx;
+
+  // 1. Check that file_hashes table exists and has entries
+  let dbFileCount: number;
+  try {
+    dbFileCount = (db.prepare('SELECT COUNT(*) as c FROM file_hashes').get() as { c: number }).c;
+  } catch {
+    return null;
+  }
+  if (dbFileCount === 0) return null;
+
+  // 2. Read the journal — only use fast path when journal has entries,
+  // proving the watcher was active and tracking changes. An empty-but-valid
+  // journal (no watcher) could miss file deletions.
+  const journal = readJournal(rootDir);
+  if (!journal.valid) return null;
+  const hasEntries =
+    (journal.changed && journal.changed.length > 0) ||
+    (journal.removed && journal.removed.length > 0);
+  if (!hasEntries) return null;
+
+  // 3. Load existing file list from file_hashes (relative paths)
+  const dbFiles = (db.prepare('SELECT file FROM file_hashes').all() as Array<{ file: string }>).map(
+    (r) => r.file,
+  );
+
+  // 4. Apply journal deltas: remove deleted files, add new/changed files
+  const fileSet = new Set(dbFiles);
+  if (journal.removed) {
+    for (const removed of journal.removed) {
+      fileSet.delete(removed);
+    }
+  }
+  if (journal.changed) {
+    for (const changed of journal.changed) {
+      fileSet.add(changed);
+    }
+  }
+
+  // 5. Convert to absolute paths and compute directories
+  const files: string[] = [];
+  const directories = new Set<string>();
+  for (const relPath of fileSet) {
+    const absPath = path.join(rootDir, relPath);
+    files.push(absPath);
+    directories.add(path.dirname(absPath));
+  }
+
+  debug(
+    `collectFiles fast path: ${dbFiles.length} from DB, journal: +${journal.changed?.length ?? 0}/-${journal.removed?.length ?? 0} → ${files.length} files`,
+  );
+  return { files, directories };
+}
+
 export async function collectFiles(ctx: PipelineContext): Promise<void> {
   const { rootDir, config, opts } = ctx;
 
@@ -33,10 +97,23 @@ export async function collectFiles(ctx: PipelineContext): Promise<void> {
     ctx.removed = missing;
     ctx.isFullBuild = false;
     info(`Scoped rebuild: ${existing.length} files to rebuild, ${missing.length} to purge`);
-  } else {
-    const collected = collectFilesUtil(rootDir, [], config, new Set<string>());
-    ctx.allFiles = collected.files;
-    ctx.discoveredDirs = collected.directories;
-    info(`Found ${ctx.allFiles.length} files to parse`);
+    return;
   }
+
+  // Incremental fast path: reconstruct file list from DB + journal deltas
+  // instead of full recursive filesystem scan (~8ms savings on 473 files).
+  if (ctx.incremental && !ctx.forceFullRebuild) {
+    const fast = tryFastCollect(ctx);
+    if (fast) {
+      ctx.allFiles = fast.files;
+      ctx.discoveredDirs = fast.directories;
+      info(`Found ${ctx.allFiles.length} files (cached)`);
+      return;
+    }
+  }
+
+  const collected = collectFilesUtil(rootDir, [], config, new Set<string>());
+  ctx.allFiles = collected.files;
+  ctx.discoveredDirs = collected.directories;
+  info(`Found ${ctx.allFiles.length} files to parse`);
 }

package/src/domain/graph/builder/stages/detect-changes.ts

@@ -10,7 +10,7 @@ import path from 'node:path';
 import { closeDb } from '../../../../db/index.js';
 import { debug, info } from '../../../../infrastructure/logger.js';
 import { normalizePath } from '../../../../shared/constants.js';
-import type { BetterSqlite3Database, ExtractorOutput } from '../../../../types.js';
+import type { BetterSqlite3Database, ExtractorOutput, NativeDatabase } from '../../../../types.js';
 import { parseFilesAuto } from '../../../parser.js';
 import { readJournal, writeJournalHeader } from '../../journal.js';
 import type { PipelineContext } from '../context.js';
@@ -58,10 +58,16 @@ function getChangedFiles(
   db: BetterSqlite3Database,
   allFiles: string[],
   rootDir: string,
+  nativeDb?: NativeDatabase,
 ): ChangeResult {
   let hasTable = false;
   try {
-    db.prepare('SELECT 1 FROM file_hashes LIMIT 1').get();
+    if (nativeDb) {
+      nativeDb.queryGet('SELECT 1 FROM file_hashes LIMIT 1', []);
+    } else {
+      db.prepare('SELECT 1 FROM file_hashes LIMIT 1').get();
+    }
+    // Query succeeded → table exists (result may be undefined if table is empty)
     hasTable = true;
   } catch {
     /* table doesn't exist */
@@ -75,11 +81,11 @@ function getChangedFiles(
     };
   }
 
-  const existing = new Map<string, FileHashRow>(
-    (db.prepare('SELECT file, hash, mtime, size FROM file_hashes').all() as FileHashRow[]).map(
-      (r) => [r.file, r],
-    ),
-  );
+  const sql = 'SELECT file, hash, mtime, size FROM file_hashes';
+  const rows = nativeDb
+    ? (nativeDb.queryAll(sql, []) as unknown as FileHashRow[])
+    : (db.prepare(sql).all() as FileHashRow[]);
+  const existing = new Map<string, FileHashRow>(rows.map((r) => [r.file, r]));
 
   const removed = detectRemovedFiles(existing, allFiles, rootDir);
   const journalResult = tryJournalTier(db, existing, rootDir, removed);
@@ -325,21 +331,33 @@ function purgeAndAddReverseDeps(
   reverseDeps: Set<string>,
 ): void {
   const { db, rootDir } = ctx;
-  if (changePaths.length > 0 || ctx.removed.length > 0) {
-    purgeFilesFromGraph(db, [...ctx.removed, ...changePaths], { purgeHashes: false });
-  }
-  if (reverseDeps.size > 0) {
-    const deleteOutgoingEdgesForFile = db.prepare(
-      'DELETE FROM edges WHERE source_id IN (SELECT id FROM nodes WHERE file = ?)',
-    );
-    for (const relPath of reverseDeps) {
-      deleteOutgoingEdgesForFile.run(relPath);
-    }
-    for (const relPath of reverseDeps) {
-      const absPath = path.join(rootDir, relPath);
-      ctx.parseChanges.push({ file: absPath, relPath, _reverseDepOnly: true });
+  const hasPurge = changePaths.length > 0 || ctx.removed.length > 0;
+  const hasReverseDeps = reverseDeps.size > 0;
+  const reverseDepList = hasReverseDeps ? [...reverseDeps] : [];
+
+  if (hasPurge || hasReverseDeps) {
+    const filesToPurge = hasPurge ? [...ctx.removed, ...changePaths] : [];
+    // Prefer NativeDatabase: purge + reverse-dep edge deletion in one transaction (#670)
+    if (ctx.nativeDb?.purgeFilesData) {
+      ctx.nativeDb.purgeFilesData(filesToPurge, false, hasReverseDeps ? reverseDepList : undefined);
+    } else {
+      if (hasPurge) {
+        purgeFilesFromGraph(db, filesToPurge, { purgeHashes: false });
+      }
+      if (hasReverseDeps) {
+        const deleteOutgoingEdgesForFile = db.prepare(
+          'DELETE FROM edges WHERE source_id IN (SELECT id FROM nodes WHERE file = ?)',
+        );
+        for (const relPath of reverseDepList) {
+          deleteOutgoingEdgesForFile.run(relPath);
+        }
+      }
     }
   }
+  for (const relPath of reverseDeps) {
+    const absPath = path.join(rootDir, relPath);
+    ctx.parseChanges.push({ file: absPath, relPath, _reverseDepOnly: true });
+  }
 }
 
 function detectHasEmbeddings(db: BetterSqlite3Database): boolean {
@@ -415,7 +433,7 @@ export async function detectChanges(ctx: PipelineContext): Promise<void> {
   }
   const increResult =
     incremental && !forceFullRebuild
-      ? getChangedFiles(db, allFiles, rootDir)
+      ? getChangedFiles(db, allFiles, rootDir, ctx.nativeDb)
       : {
           changed: allFiles.map((f): ChangedFile => ({ file: f })),
           removed: [] as string[],

package/src/domain/graph/builder/stages/finalize.ts

@@ -6,7 +6,12 @@
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { performance } from 'node:perf_hooks';
-import { closeDb, closeDbDeferred, getBuildMeta, setBuildMeta } from '../../../../db/index.js';
+import {
+  closeDbPair,
+  closeDbPairDeferred,
+  getBuildMeta,
+  setBuildMeta,
+} from '../../../../db/index.js';
 import { debug, info, warn } from '../../../../infrastructure/logger.js';
 import { CODEGRAPH_VERSION } from '../../../../shared/version.js';
 import { writeJournalHeader } from '../../journal.js';
@@ -43,8 +48,12 @@ export async function finalize(ctx: PipelineContext): Promise<void> {
   // Incremental drift detection — skip for small incremental changes where
   // count fluctuation is expected (reverse-dep edge churn).
   if (!isFullBuild && allSymbols.size > 3) {
-    const prevNodes = getBuildMeta(db, 'node_count');
-    const prevEdges = getBuildMeta(db, 'edge_count');
+    const prevNodes = ctx.nativeDb
+      ? ctx.nativeDb.getBuildMeta('node_count')
+      : getBuildMeta(db, 'node_count');
+    const prevEdges = ctx.nativeDb
+      ? ctx.nativeDb.getBuildMeta('edge_count')
+      : getBuildMeta(db, 'edge_count');
     if (prevNodes && prevEdges) {
       const prevN = Number(prevNodes);
       const prevE = Number(prevEdges);
@@ -67,17 +76,33 @@ export async function finalize(ctx: PipelineContext): Promise<void> {
   // built_at is only used by stale-embeddings check (skipped for incremental),
   // and counts are only used by drift detection (skipped for ≤3 files).
   // This avoids a transaction commit + WAL fsync (~15-30ms).
-  if (isFullBuild || allSymbols.size > 5) {
+  // Threshold aligned with drift detection gate (allSymbols.size > 3) so stored
+  // counts stay fresh whenever drift detection reads them.
+  if (isFullBuild || allSymbols.size > 3) {
     try {
-      setBuildMeta(db, {
-        engine: ctx.engineName,
-        engine_version: ctx.engineVersion || '',
-        codegraph_version: CODEGRAPH_VERSION,
-        schema_version: String(schemaVersion),
-        built_at: buildNow.toISOString(),
-        node_count: nodeCount,
-        edge_count: actualEdgeCount,
-      });
+      if (ctx.nativeDb) {
+        ctx.nativeDb.setBuildMeta(
+          Object.entries({
+            engine: ctx.engineName,
+            engine_version: ctx.engineVersion || '',
+            codegraph_version: CODEGRAPH_VERSION,
+            schema_version: String(schemaVersion),
+            built_at: buildNow.toISOString(),
+            node_count: String(nodeCount),
+            edge_count: String(actualEdgeCount),
+          }).map(([key, value]) => ({ key, value: String(value) })),
+        );
+      } else {
+        setBuildMeta(db, {
+          engine: ctx.engineName,
+          engine_version: ctx.engineVersion || '',
+          codegraph_version: CODEGRAPH_VERSION,
+          schema_version: String(schemaVersion),
+          built_at: buildNow.toISOString(),
+          node_count: nodeCount,
+          edge_count: actualEdgeCount,
+        });
+      }
     } catch (err) {
       warn(`Failed to write build metadata: ${(err as Error).message}`);
     }
@@ -157,17 +182,22 @@ export async function finalize(ctx: PipelineContext): Promise<void> {
     }
   }
 
+  // Intentionally measured before closeDb / writeJournalHeader / auto-registration:
+  // for the deferred-close path the close is async (setImmediate), and for full
+  // builds the metric captures finalize logic only — DB close cost is tracked
+  // separately via timing.closeDbMs when available.
   ctx.timing.finalizeMs = performance.now() - t0;
 
-  // For small incremental builds, defer db.close() to the next event loop tick.
-  // The WAL checkpoint in db.close() costs ~250ms on Windows NTFS due to fsync.
-  // Deferring lets buildGraph() return immediately; the checkpoint runs after.
-  // Skip for temp directories (tests) — they rmSync immediately after build.
+  // Close NativeDatabase (fast, ~1ms) then better-sqlite3 (WAL checkpoint).
+  // For small incremental builds, defer the expensive WAL checkpoint to the
+  // next event loop tick. Skip for temp directories (tests) — they rmSync
+  // immediately after build.
+  const pair = { db, nativeDb: ctx.nativeDb };
   const isTempDir = path.resolve(rootDir).startsWith(path.resolve(tmpdir()));
   if (!isFullBuild && allSymbols.size <= 5 && !isTempDir) {
-    closeDbDeferred(db);
+    closeDbPairDeferred(pair);
   } else {
-    closeDb(db);
+    closeDbPair(pair);
   }
 
   // Write journal header after successful build
@@ -177,7 +207,6 @@ export async function finalize(ctx: PipelineContext): Promise<void> {
   // registered during the initial full build. The dynamic import + file I/O
   // costs ~100ms which dominates incremental finalize time.
   if (!opts.skipRegistry && isFullBuild) {
-    const { tmpdir } = await import('node:os');
     const tmpDir = path.resolve(tmpdir());
     const resolvedRoot = path.resolve(rootDir);
     if (resolvedRoot.startsWith(tmpDir)) {