perf(builder): defer NativeDatabase init to after no-op early exit (#884)

* perf(builder): defer NativeDatabase init to after no-op early exit

On no-op rebuilds, the native engine opened NativeDatabase, ran
initSchema, checkpointed WAL, then immediately closed it — all before
detectChanges even ran. This added ~5ms overhead on every no-op rebuild
where the connection was never used.

Move NativeDatabase.openReadWrite() from setupPipeline to on-demand:
- tryNativeOrchestrator opens it when the Rust fast path will run
- runPipelineStages defers it until after the early-exit check
- setupPipeline now only probes loadNative() for availability
- checkEngineSchemaMismatch uses better-sqlite3 (reads are WAL-safe)
- Remove dead batched native path from getChangedFiles (nativeDb was
  already undefined during detectChanges due to suspendNativeDb)

* fix(builder): restore WAL checkpoint callbacks after reopenNativeDb (#884)

suspendJsDb and resumeJsDb were initialized to undefined in
initializeEngine and never reassigned when nativeDb was reopened for the
analysis phase. This silently removed the dual-connection WAL corruption
guard introduced in #696/#715. Assign both callbacks alongside
engineOpts.nativeDb in the reopenNativeDb('analyses') block.

Author: carlos-alm

src/domain/graph/builder/context.ts

@@ -33,6 +33,8 @@ export class PipelineContext {
   forceFullRebuild: boolean = false;
   schemaVersion!: number;
   nativeDb?: NativeDatabase;
+  /** Whether native engine is available (deferred — DB opened only when needed). */
+  nativeAvailable: boolean = false;
 
   // ── File collection (set by collectFiles stage) ────────────────────
   allFiles!: string[];

src/domain/graph/builder/pipeline.ts

@@ -43,29 +43,11 @@ function initializeEngine(ctx: PipelineContext): void {
     engine: ctx.opts.engine || 'auto',
     dataflow: ctx.opts.dataflow !== false,
     ast: ctx.opts.ast !== false,
-    nativeDb: ctx.nativeDb,
-    // WAL checkpoint callbacks for dual-connection WAL guard (#696, #715).
-    // Feature modules (ast, cfg, complexity, dataflow) receive `db` as a
-    // parameter and cannot tolerate close/reopen (stale reference). Instead,
-    // checkpoint the WAL so native writes start with a clean slate.
-    // After native writes, resumeJsDb checkpoints through rusqlite so
-    // better-sqlite3 never reads WAL frames from a different SQLite library.
-    suspendJsDb: ctx.nativeDb
-      ? () => {
-          ctx.db.pragma('wal_checkpoint(TRUNCATE)');
-        }
-      : undefined,
-    resumeJsDb: ctx.nativeDb
-      ? () => {
-          try {
-            ctx.nativeDb?.exec('PRAGMA wal_checkpoint(TRUNCATE)');
-          } catch (e) {
-            debug(
-              `resumeJsDb: WAL checkpoint failed (nativeDb may already be closed): ${toErrorMessage(e)}`,
-            );
-          }
-        }
-      : undefined,
+    // nativeDb and WAL callbacks are set later when NativeDatabase is opened
+    // (deferred to skip overhead on no-op rebuilds).
+    nativeDb: undefined,
+    suspendJsDb: undefined,
+    resumeJsDb: undefined,
   };
   const { name: engineName, version: engineVersion } = getActiveEngine(ctx.engineOpts);
   ctx.engineName = engineName as 'native' | 'wasm';
@@ -79,11 +61,10 @@ function checkEngineSchemaMismatch(ctx: PipelineContext): void {
   ctx.forceFullRebuild = false;
   if (!ctx.incremental) return;
 
-  // Route metadata reads through NativeDatabase only when using the native engine,
-  // to avoid dual-SQLite WAL conflicts (rusqlite + better-sqlite3 on same file).
-  const useNativeDb = ctx.engineName === 'native' && !!ctx.nativeDb;
-  const meta = (key: string): string | null =>
-    useNativeDb ? ctx.nativeDb!.getBuildMeta(key) : getBuildMeta(ctx.db, key);
+  // NativeDatabase is deferred until after change detection, so always use
+  // better-sqlite3 for metadata reads here. Reads are safe — WAL conflicts
+  // only arise from concurrent writes.
+  const meta = (key: string): string | null => getBuildMeta(ctx.db, key);
 
   const prevEngine = meta('engine');
   if (prevEngine && prevEngine !== ctx.engineName) {
@@ -130,35 +111,13 @@ function setupPipeline(ctx: PipelineContext): void {
   ctx.rootDir = path.resolve(ctx.rootDir);
   ctx.dbPath = path.join(ctx.rootDir, '.codegraph', 'graph.db');
   ctx.db = openDb(ctx.dbPath);
+  initSchema(ctx.db);
 
-  // Use NativeDatabase for schema init when native engine is available (Phase 6.13).
-  // better-sqlite3 (ctx.db) is still always opened — needed for queries and stages
-  // that haven't been migrated to rusqlite yet.
-  // Skip native DB entirely when user explicitly requested --engine wasm.
+  // Detect whether native engine is available, but defer opening NativeDatabase.
+  // The native orchestrator opens it on demand; the JS pipeline defers until
+  // after change detection — avoiding ~5ms open+initSchema+close on no-op rebuilds.
   const enginePref = ctx.opts.engine || 'auto';
-  const native = enginePref !== 'wasm' ? loadNative() : null;
-  if (native?.NativeDatabase) {
-    try {
-      ctx.nativeDb = native.NativeDatabase.openReadWrite(ctx.dbPath);
-      ctx.nativeDb.initSchema();
-      // Checkpoint WAL through rusqlite so better-sqlite3 sees a clean DB
-      // with no cross-library WAL frames (#715, #717).
-      ctx.nativeDb.exec('PRAGMA wal_checkpoint(TRUNCATE)');
-    } catch (err) {
-      warn(`NativeDatabase setup failed, falling back to JS: ${toErrorMessage(err)}`);
-      try {
-        ctx.nativeDb?.close();
-      } catch (e) {
-        debug(`setupNativeDb: close failed during fallback: ${toErrorMessage(e)}`);
-      }
-      ctx.nativeDb = undefined;
-    }
-    // Always run JS initSchema so better-sqlite3 sees the schema —
-    // nativeDb is closed during pipeline stages and reopened for analyses.
-    initSchema(ctx.db);
-  } else {
-    initSchema(ctx.db);
-  }
+  ctx.nativeAvailable = enginePref !== 'wasm' && !!loadNative()?.NativeDatabase;
 
   ctx.config = loadConfig(ctx.rootDir);
   ctx.incremental =
@@ -553,6 +512,28 @@ async function tryNativeOrchestrator(
     debug(`Skipping native orchestrator: ${skipReason}`);
     return undefined;
   }
+
+  // Open NativeDatabase on demand for the orchestrator.
+  // Deferred from setupPipeline so no-op JS pipeline rebuilds skip the overhead.
+  if (!ctx.nativeDb && ctx.nativeAvailable) {
+    const native = loadNative();
+    if (native?.NativeDatabase) {
+      try {
+        ctx.nativeDb = native.NativeDatabase.openReadWrite(ctx.dbPath);
+        ctx.nativeDb.initSchema();
+        ctx.nativeDb.exec('PRAGMA wal_checkpoint(TRUNCATE)');
+      } catch (err) {
+        warn(`NativeDatabase setup failed, falling back to JS: ${toErrorMessage(err)}`);
+        try {
+          ctx.nativeDb?.close();
+        } catch (e) {
+          debug(`tryNativeOrchestrator: close failed during fallback: ${toErrorMessage(e)}`);
+        }
+        ctx.nativeDb = undefined;
+      }
+    }
+  }
+
   if (!ctx.nativeDb?.buildGraph) return undefined;
 
   const resultJson = ctx.nativeDb.buildGraph(
@@ -639,12 +620,11 @@ async function tryNativeOrchestrator(
 // ── Pipeline stages execution ───────────────────────────────────────────
 
 async function runPipelineStages(ctx: PipelineContext): Promise<void> {
-  // Prevent dual-connection WAL corruption during pipeline stages: when both
-  // better-sqlite3 (ctx.db) and rusqlite (ctx.nativeDb) are open to the same
-  // WAL-mode file, native writes corrupt the DB. Close nativeDb so stages
-  // use JS fallback paths. Reopened before runAnalyses for feature modules
-  // that use suspendJsDb/resumeJsDb WAL checkpoint pattern (#696).
-  const hadNativeDb = !!ctx.nativeDb;
+  // NativeDatabase is deferred — not opened during setup. collectFiles and
+  // detectChanges only need better-sqlite3. If no files changed, we exit
+  // early without ever opening the native connection, saving ~5ms.
+  // If nativeDb was opened by tryNativeOrchestrator (which fell through),
+  // suspend it now to avoid dual-connection WAL corruption during stages.
   if (ctx.db && ctx.nativeDb) {
     suspendNativeDb(ctx, 'pre-collect');
   }
@@ -659,7 +639,7 @@ async function runPipelineStages(ctx: PipelineContext): Promise<void> {
   // Temporarily reopen nativeDb for insertNodes — it uses the WAL checkpoint
   // guard internally (same pattern as feature modules). Closed again before
   // resolveImports/buildEdges which don't yet have the guard (#709).
-  if (hadNativeDb && ctx.engineName === 'native') {
+  if (ctx.nativeAvailable && ctx.engineName === 'native') {
     reopenNativeDb(ctx, 'insertNodes');
   }
 
@@ -677,13 +657,27 @@ async function runPipelineStages(ctx: PipelineContext): Promise<void> {
 
   // Reopen nativeDb for feature modules (ast, cfg, complexity, dataflow)
   // which use suspendJsDb/resumeJsDb WAL checkpoint before native writes.
-  if (hadNativeDb) {
+  if (ctx.nativeAvailable) {
     reopenNativeDb(ctx, 'analyses');
     if (ctx.nativeDb && ctx.engineOpts) {
       ctx.engineOpts.nativeDb = ctx.nativeDb;
+      ctx.engineOpts.suspendJsDb = () => {
+        ctx.db.pragma('wal_checkpoint(TRUNCATE)');
+      };
+      ctx.engineOpts.resumeJsDb = () => {
+        try {
+          ctx.nativeDb?.exec('PRAGMA wal_checkpoint(TRUNCATE)');
+        } catch (e) {
+          debug(
+            `resumeJsDb: WAL checkpoint failed (nativeDb may already be closed): ${toErrorMessage(e)}`,
+          );
+        }
+      };
     }
     if (!ctx.nativeDb && ctx.engineOpts) {
       ctx.engineOpts.nativeDb = undefined;
+      ctx.engineOpts.suspendJsDb = undefined;
+      ctx.engineOpts.resumeJsDb = undefined;
     }
   }
 

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

@@ -58,26 +58,9 @@ function getChangedFiles(
   db: BetterSqlite3Database,
   allFiles: string[],
   rootDir: string,
-  nativeDb?: NativeDatabase,
 ): ChangeResult {
-  // Batched native path: single napi call for table check + all rows + max mtime
-  if (nativeDb?.getFileHashData) {
-    const data = nativeDb.getFileHashData();
-    if (!data.exists) {
-      return {
-        changed: allFiles.map((f) => ({ file: f })),
-        removed: [],
-        isFullBuild: true,
-      };
-    }
-    const existing = new Map<string, FileHashRow>(data.rows.map((r) => [r.file, r]));
-    const removed = detectRemovedFiles(existing, allFiles, rootDir);
-    const journalResult = tryJournalTier(db, existing, rootDir, removed, data.maxMtime);
-    if (journalResult) return journalResult;
-    return mtimeAndHashTiers(existing, allFiles, rootDir, removed);
-  }
-
-  // WASM / fallback path
+  // NativeDatabase is not open during change detection (deferred to after
+  // early-exit check). All queries use better-sqlite3 here.
   let hasTable = false;
   try {
     db.prepare('SELECT 1 FROM file_hashes LIMIT 1').get();
@@ -487,12 +470,7 @@ export async function detectChanges(ctx: PipelineContext): Promise<void> {
   }
   const increResult =
     incremental && !forceFullRebuild
-      ? getChangedFiles(
-          db,
-          allFiles,
-          rootDir,
-          ctx.engineName === 'native' ? ctx.nativeDb : undefined,
-        )
+      ? getChangedFiles(db, allFiles, rootDir)
       : {
           changed: allFiles.map((f): ChangedFile => ({ file: f })),
           removed: [] as string[],