@optave/codegraph 3.9.1 → 3.9.3

package/src/domain/graph/builder/pipeline.ts

@@ -4,14 +4,17 @@
  * This is the heart of the builder refactor (ROADMAP 3.9): the monolithic buildGraph()
  * is decomposed into independently testable stages that communicate via PipelineContext.
  */
+import fs from 'node:fs';
 import path from 'node:path';
 import { performance } from 'node:perf_hooks';
 import {
+  acquireAdvisoryLock,
   closeDbPair,
   getBuildMeta,
   initSchema,
   MIGRATIONS,
   openDb,
+  releaseAdvisoryLock,
   setBuildMeta,
 } from '../../../db/index.js';
 import { detectWorkspaces, loadConfig } from '../../../infrastructure/config.js';
@@ -20,11 +23,18 @@ import { loadNative } from '../../../infrastructure/native.js';
 import { semverCompare } from '../../../infrastructure/update-check.js';
 import { toErrorMessage } from '../../../shared/errors.js';
 import { CODEGRAPH_VERSION } from '../../../shared/version.js';
-import type { BuildGraphOpts, BuildResult, Definition, ExtractorOutput } from '../../../types.js';
+import type {
+  BetterSqlite3Database,
+  BuildGraphOpts,
+  BuildResult,
+  Definition,
+  ExtractorOutput,
+} from '../../../types.js';
 import { getActiveEngine } from '../../parser.js';
 import { setWorkspaces } from '../resolve.js';
 import { PipelineContext } from './context.js';
 import { loadPathAliases } from './helpers.js';
+import { NativeDbProxy } from './native-db-proxy.js';
 import { buildEdges } from './stages/build-edges.js';
 import { buildStructure } from './stages/build-structure.js';
 // Pipeline stages
@@ -43,29 +53,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 +71,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) {
@@ -129,34 +120,42 @@ function loadAliases(ctx: PipelineContext): void {
 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);
 
-  // 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.
   const enginePref = ctx.opts.engine || 'auto';
   const native = enginePref !== 'wasm' ? loadNative() : null;
-  if (native?.NativeDatabase) {
+  ctx.nativeAvailable = !!native?.NativeDatabase;
+
+  // When native is available, use a NativeDbProxy backed by a single rusqlite
+  // connection. This eliminates the dual-connection WAL corruption problem.
+  // The Rust orchestrator handles the full pipeline; the proxy is used for any
+  // JS post-processing (e.g. structure fallback on large builds).
+  if (ctx.nativeAvailable && native?.NativeDatabase) {
     try {
+      const dir = path.dirname(ctx.dbPath);
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+      acquireAdvisoryLock(ctx.dbPath);
       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)');
+      const proxy = new NativeDbProxy(ctx.nativeDb);
+      proxy.__lockPath = `${ctx.dbPath}.lock`;
+      ctx.db = proxy as unknown as typeof ctx.db;
+      ctx.nativeFirstProxy = true;
     } catch (err) {
-      warn(`NativeDatabase setup failed, falling back to JS: ${toErrorMessage(err)}`);
+      warn(`NativeDatabase setup failed, falling back to better-sqlite3: ${toErrorMessage(err)}`);
       try {
         ctx.nativeDb?.close();
-      } catch (e) {
-        debug(`setupNativeDb: close failed during fallback: ${toErrorMessage(e)}`);
+      } catch {
+        /* ignore */
       }
       ctx.nativeDb = undefined;
+      ctx.nativeFirstProxy = false;
+      releaseAdvisoryLock(`${ctx.dbPath}.lock`);
+      ctx.db = openDb(ctx.dbPath);
+      initSchema(ctx.db);
     }
-    // Always run JS initSchema so better-sqlite3 sees the schema —
-    // nativeDb is closed during pipeline stages and reopened for analyses.
-    initSchema(ctx.db);
   } else {
+    ctx.db = openDb(ctx.dbPath);
     initSchema(ctx.db);
   }
 
@@ -267,15 +266,19 @@ interface NativeOrchestratorResult {
   structureScope?: string[];
   /** Whether the Rust pipeline handled the structure phase (small-incremental fast path). */
   structureHandled?: boolean;
+  /** Whether the Rust pipeline wrote AST/complexity/CFG/dataflow to DB. */
+  analysisComplete?: boolean;
 }
 
 // ── Native orchestrator helpers ───────────────────────────────────────
 
 /** Determine whether the native orchestrator should be skipped. Returns a reason string, or null if it should run. */
 function shouldSkipNativeOrchestrator(ctx: PipelineContext): string | null {
-  if (process.env.CODEGRAPH_FORCE_JS_PIPELINE === '1') return 'CODEGRAPH_FORCE_JS_PIPELINE=1';
   if (ctx.forceFullRebuild) return 'forceFullRebuild';
-  const orchestratorBuggy = !!ctx.engineVersion && semverCompare(ctx.engineVersion, '3.10.0') < 0;
+  // v3.9.0 addon had buggy incremental purge (wrong SQL on analysis tables,
+  // scoped removal over-detection). Fixed in v3.9.1 by PR #865. Gate on
+  // < 3.9.1 so v3.9.1+ uses the fast Rust orchestrator path.
+  const orchestratorBuggy = !!ctx.engineVersion && semverCompare(ctx.engineVersion, '3.9.1') < 0;
   if (orchestratorBuggy) return `buggy addon ${ctx.engineVersion}`;
   if (ctx.engineName !== 'native') return `engine=${ctx.engineName}`;
   return null;
@@ -452,7 +455,11 @@ async function runPostNativeStructure(
   return performance.now() - structureStart;
 }
 
-/** Run AST/complexity/CFG/dataflow analysis after native orchestrator. */
+/**
+ * JS fallback for AST/complexity/CFG/dataflow analysis after native orchestrator.
+ * Used when the Rust addon doesn't include analysis persistence (older addon
+ * version) or when analysis failed on the Rust side.
+ */
 async function runPostNativeAnalysis(
   ctx: PipelineContext,
   allFileSymbols: Map<string, ExtractorOutput>,
@@ -484,14 +491,31 @@ async function runPostNativeAnalysis(
     }
   }
 
+  // Flush JS WAL pages once so Rust can see them, then no-op callbacks.
+  // Previously each feature called wal_checkpoint(TRUNCATE) individually
+  // (~68ms each × 3-4 features). One FULL checkpoint suffices.
+  if (ctx.nativeDb && ctx.engineOpts) {
+    ctx.db.pragma('wal_checkpoint(FULL)');
+    ctx.engineOpts.suspendJsDb = () => {};
+    ctx.engineOpts.resumeJsDb = () => {};
+  }
+
   try {
-    const { runAnalyses: runAnalysesFn } = await import('../../../ast-analysis/engine.js');
+    const { runAnalyses: runAnalysesFn } = (await import('../../../ast-analysis/engine.js')) as {
+      runAnalyses: (
+        db: BetterSqlite3Database,
+        fileSymbols: Map<string, ExtractorOutput>,
+        rootDir: string,
+        opts: Record<string, unknown>,
+        engineOpts?: Record<string, unknown>,
+      ) => Promise<{ astMs?: number; complexityMs?: number; cfgMs?: number; dataflowMs?: number }>;
+    };
     const result = await runAnalysesFn(
       ctx.db,
       analysisFileSymbols,
       ctx.rootDir,
-      ctx.opts,
-      ctx.engineOpts,
+      ctx.opts as Record<string, unknown>,
+      ctx.engineOpts as unknown as Record<string, unknown> | undefined,
     );
     timing.astMs = result.astMs ?? 0;
     timing.complexityMs = result.complexityMs ?? 0;
@@ -501,7 +525,9 @@ async function runPostNativeAnalysis(
     warn(`Analysis phases failed after native build: ${toErrorMessage(err)}`);
   }
 
-  // Close nativeDb after analyses
+  // Close nativeDb after analyses — TRUNCATE checkpoint flushes all Rust
+  // WAL writes so JS and external readers can see them. Runs once after
+  // all analysis features complete (not per-feature).
   if (ctx.nativeDb) {
     try {
       ctx.nativeDb.exec('PRAGMA wal_checkpoint(TRUNCATE)');
@@ -514,7 +540,11 @@ async function runPostNativeAnalysis(
       /* ignore close errors */
     }
     ctx.nativeDb = undefined;
-    if (ctx.engineOpts) ctx.engineOpts.nativeDb = undefined;
+    if (ctx.engineOpts) {
+      ctx.engineOpts.nativeDb = undefined;
+      ctx.engineOpts.suspendJsDb = undefined;
+      ctx.engineOpts.resumeJsDb = undefined;
+    }
   }
 
   return timing;
@@ -553,6 +583,28 @@ async function tryNativeOrchestrator(
     debug(`Skipping native orchestrator: ${skipReason}`);
     return undefined;
   }
+
+  // In native-first mode, nativeDb is already open from setupPipeline.
+  // Otherwise, open it on demand (deferred to skip overhead on no-op rebuilds).
+  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(
@@ -594,29 +646,40 @@ async function tryNativeOrchestrator(
   );
 
   // ── Post-native structure + analysis ──────────────────────────────
-  let analysisTiming = { astMs: 0, complexityMs: 0, cfgMs: 0, dataflowMs: 0 };
+  let analysisTiming = {
+    astMs: +(p.astMs ?? 0),
+    complexityMs: +(p.complexityMs ?? 0),
+    cfgMs: +(p.cfgMs ?? 0),
+    dataflowMs: +(p.dataflowMs ?? 0),
+  };
   let structurePatchMs = 0;
-  const needsAnalysis =
-    ctx.opts.ast !== false ||
-    ctx.opts.complexity !== false ||
-    ctx.opts.cfg !== false ||
-    ctx.opts.dataflow !== false;
   // Skip JS structure when the Rust pipeline's small-incremental fast path
   // already handled it. For full builds and large incrementals where Rust
   // skipped structure, we must run the JS fallback.
   const needsStructure = !result.structureHandled;
-
-  if (needsAnalysis || needsStructure) {
-    if (!handoffWalAfterNativeBuild(ctx)) {
+  // When the Rust addon doesn't include analysis persistence (older addon
+  // version or analysis failed), fall back to JS-side analysis.
+  const needsAnalysisFallback =
+    !result.analysisComplete &&
+    (ctx.opts.ast !== false ||
+      ctx.opts.complexity !== false ||
+      ctx.opts.cfg !== false ||
+      ctx.opts.dataflow !== false);
+
+  if (needsStructure || needsAnalysisFallback) {
+    // When analysis fallback is needed, handoff to better-sqlite3 — the
+    // analysis engine uses the suspend/resume WAL pattern that requires a
+    // real better-sqlite3 connection, not the NativeDbProxy.
+    if (needsAnalysisFallback && ctx.nativeFirstProxy) {
+      closeNativeDb(ctx, 'pre-analysis-fallback');
+      ctx.db = openDb(ctx.dbPath);
+      ctx.nativeFirstProxy = false;
+    } else if (!ctx.nativeFirstProxy && !handoffWalAfterNativeBuild(ctx)) {
       // DB reopen failed — return partial result
       return formatNativeTimingResult(p, 0, analysisTiming);
     }
 
-    // When structure was handled by Rust, we only need changed files for
-    // analysis — no need to load the entire graph from DB. When structure
-    // was NOT handled, we need all files to build the complete directory tree.
-    const scopeFiles = needsStructure ? undefined : result.changedFiles;
-    const fileSymbols = reconstructFileSymbolsFromDb(ctx, scopeFiles);
+    const fileSymbols = reconstructFileSymbolsFromDb(ctx);
 
     if (needsStructure) {
       structurePatchMs = await runPostNativeStructure(
@@ -627,7 +690,7 @@ async function tryNativeOrchestrator(
       );
     }
 
-    if (needsAnalysis) {
+    if (needsAnalysisFallback) {
       analysisTiming = await runPostNativeAnalysis(ctx, fileSymbols, result.changedFiles);
     }
   }
@@ -639,14 +702,21 @@ 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;
+  // ── WASM / fallback dual-connection mode ─────────────────────────────
+  // 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');
+    // When nativeFirstProxy is true, ctx.db is a NativeDbProxy wrapping the
+    // now-closed NativeDatabase. Replace it with a real better-sqlite3
+    // connection so the JS pipeline stages can operate normally.
+    if (ctx.nativeFirstProxy) {
+      ctx.db = openDb(ctx.dbPath);
+      ctx.nativeFirstProxy = false;
+    }
   }
 
   await collectFiles(ctx);
@@ -656,10 +726,13 @@ async function runPipelineStages(ctx: PipelineContext): Promise<void> {
 
   await parseFiles(ctx);
 
-  // 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') {
+  // For small incremental builds (≤smallFilesThreshold files), skip the nativeDb open/close
+  // cycle for insertNodes — the WAL checkpoint + connection churn (~5-10ms)
+  // exceeds the napi bulk-insert savings on a handful of files. The JS
+  // fallback path inside insertNodes handles this case efficiently.
+  const smallIncremental =
+    !ctx.isFullBuild && ctx.allSymbols.size <= ctx.config.build.smallFilesThreshold;
+  if (ctx.nativeAvailable && ctx.engineName === 'native' && !smallIncremental) {
     reopenNativeDb(ctx, 'insertNodes');
   }
 
@@ -675,25 +748,39 @@ async function runPipelineStages(ctx: PipelineContext): Promise<void> {
   await buildEdges(ctx);
   await buildStructure(ctx);
 
-  // Reopen nativeDb for feature modules (ast, cfg, complexity, dataflow)
-  // which use suspendJsDb/resumeJsDb WAL checkpoint before native writes.
-  if (hadNativeDb) {
+  // Reopen nativeDb for feature modules (ast, cfg, complexity, dataflow).
+  // Skip for small incremental builds — same rationale as insertNodes above.
+  //
+  // Perf: do ONE upfront FULL checkpoint to flush JS WAL pages so Rust
+  // can see the latest rows, then make suspendJsDb/resumeJsDb no-ops.
+  // Previously each feature called wal_checkpoint(TRUNCATE) individually
+  // (~68ms each × 3-4 features = ~200-270ms overhead on incremental builds).
+  if (ctx.nativeAvailable && !smallIncremental) {
     reopenNativeDb(ctx, 'analyses');
     if (ctx.nativeDb && ctx.engineOpts) {
+      ctx.db.pragma('wal_checkpoint(FULL)');
       ctx.engineOpts.nativeDb = ctx.nativeDb;
+      ctx.engineOpts.suspendJsDb = () => {};
+      ctx.engineOpts.resumeJsDb = () => {};
     }
     if (!ctx.nativeDb && ctx.engineOpts) {
       ctx.engineOpts.nativeDb = undefined;
+      ctx.engineOpts.suspendJsDb = undefined;
+      ctx.engineOpts.resumeJsDb = undefined;
     }
   }
 
   await runAnalyses(ctx);
 
-  // Keep nativeDb open through finalize so persistBuildMetadata, advisory
-  // checks, and count queries use the native path.  closeDbPair inside
-  // finalize handles both connections.  Refresh the JS db so it has a
-  // valid page cache in case finalize falls back to JS paths (#751).
+  // Flush Rust WAL writes (AST, complexity, CFG, dataflow) so the JS
+  // connection and any post-build readers can see them.  One TRUNCATE
+  // here replaces the N per-feature resumeJsDb checkpoints (#checkpoint-opt).
   if (ctx.nativeDb) {
+    try {
+      ctx.nativeDb.exec('PRAGMA wal_checkpoint(TRUNCATE)');
+    } catch (e) {
+      debug(`post-analyses WAL checkpoint failed: ${toErrorMessage(e)}`);
+    }
     refreshJsDb(ctx);
   }
 

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

@@ -342,7 +342,7 @@ function buildCallEdgesNative(
     if (!fileNodeRow) continue;
 
     const importedNames = buildImportedNamesForNative(ctx, relPath, symbols, rootDir);
-    const typeMap: Array<{ name: string; typeName: string; confidence: number }> =
+    const typeMapRaw: Array<{ name: string; typeName: string; confidence: number }> =
       symbols.typeMap instanceof Map
         ? [...symbols.typeMap.entries()].map(([name, entry]) => ({
             name,
@@ -352,6 +352,19 @@ function buildCallEdgesNative(
         : Array.isArray(symbols.typeMap)
           ? (symbols.typeMap as Array<{ name: string; typeName: string; confidence: number }>)
           : [];
+    // Deduplicate: keep highest-confidence entry per name (first-wins on tie),
+    // matching JS setTypeMapEntry semantics.  The Map branch is already
+    // deduped by setTypeMapEntry — this loop is only needed for the Array
+    // branch (pre-rebuilt native addon) but runs unconditionally as
+    // belt-and-suspenders since it's a cheap O(n) pass.
+    const typeMapDedup = new Map<string, { name: string; typeName: string; confidence: number }>();
+    for (const entry of typeMapRaw) {
+      const existing = typeMapDedup.get(entry.name);
+      if (!existing || entry.confidence > existing.confidence) {
+        typeMapDedup.set(entry.name, entry);
+      }
+    }
+    const typeMap = [...typeMapDedup.values()];
     nativeFiles.push({
       file: relPath,
       fileNodeId: fileNodeRow.id,
@@ -699,7 +712,7 @@ function loadNodes(ctx: PipelineContext): { rows: QueryNodeRow[]; scoped: boolea
   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) {
+  if (!isFullBuild && fileSymbols.size <= ctx.config.build.smallFilesThreshold) {
     const existingFileCount = (
       db.prepare("SELECT COUNT(*) as c FROM nodes WHERE kind = 'file'").get() as { c: number }
     ).c;

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

@@ -37,7 +37,7 @@ export async function buildStructure(ctx: PipelineContext): Promise<void> {
   // For small incremental builds on large codebases, use a fast path that
   // updates only the changed files' metrics via targeted SQL instead of
   // loading ALL definitions from DB (~8ms) and recomputing ALL metrics (~15ms).
-  // Gate: ≤5 changed files AND significantly more existing files (>20) to
+  // Gate: ≤smallFilesThreshold changed files AND significantly more existing files (>20) to
   // avoid triggering on small test fixtures where directory metrics matter.
   const useNativeReads = ctx.engineName === 'native' && !!ctx.nativeDb;
   const existingFileCount = !isFullBuild
@@ -52,7 +52,7 @@ export async function buildStructure(ctx: PipelineContext): Promise<void> {
   const useSmallIncrementalFastPath =
     !isFullBuild &&
     changedFileList != null &&
-    changedFileList.length <= 5 &&
+    changedFileList.length <= ctx.config.build.smallFilesThreshold &&
     existingFileCount > 20;
 
   if (!isFullBuild && !useSmallIncrementalFastPath) {

package/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();
@@ -294,14 +277,14 @@ async function runPendingAnalysis(ctx: PipelineContext): Promise<boolean> {
     rootDir,
     analysisOpts,
   );
-  if (needsCfg) {
-    const { buildCFGData } = await import('../../../../features/cfg.js');
-    await buildCFGData(db, analysisSymbols, rootDir, engineOpts);
-  }
-  if (needsDataflow) {
-    const { buildDataflowEdges } = await import('../../../../features/dataflow.js');
-    await buildDataflowEdges(db, analysisSymbols, rootDir, engineOpts);
-  }
+  const { runAnalyses } = await import('../../../../ast-analysis/engine.js');
+  await runAnalyses(
+    db,
+    analysisSymbols,
+    rootDir,
+    { ast: false, complexity: false, cfg: needsCfg, dataflow: needsDataflow },
+    engineOpts,
+  );
   return true;
 }
 
@@ -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[],

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

@@ -258,7 +258,7 @@ export async function finalize(ctx: PipelineContext): Promise<void> {
   // immediately after build.
   const pair = { db: ctx.db, nativeDb: ctx.nativeDb };
   const isTempDir = path.resolve(rootDir).startsWith(path.resolve(tmpdir()));
-  if (!isFullBuild && allSymbols.size <= 5 && !isTempDir) {
+  if (!isFullBuild && allSymbols.size <= ctx.config.build.smallFilesThreshold && !isTempDir) {
     closeDbPairDeferred(pair);
   } else {
     closeDbPair(pair);

package/src/domain/graph/builder/stages/insert-nodes.ts

@@ -159,23 +159,26 @@ function tryNativeInsert(ctx: PipelineContext): boolean {
   }
   const fileHashes = buildFileHashes(allSymbols, precomputedData, metadataUpdates, rootDir);
 
-  // WAL guard: same suspendJsDb/resumeJsDb pattern used by feature modules
-  // (ast, cfg, complexity, dataflow). Checkpoint JS side before native write,
-  // then checkpoint native side after, so neither library reads WAL frames
-  // written by the other (#696, #709, #715, #717).
+  // In native-first mode (single rusqlite connection), no WAL dance is needed.
+  // In dual-connection mode, checkpoint JS side before native write, then
+  // checkpoint native side after (#696, #709, #715, #717).
   let result: boolean;
-  try {
-    if (ctx.db) {
-      ctx.db.pragma('wal_checkpoint(TRUNCATE)');
-    }
+  if (ctx.nativeFirstProxy) {
     result = ctx.nativeDb!.bulkInsertNodes(batches, fileHashes, removed);
-  } finally {
+  } else {
     try {
-      ctx.nativeDb?.exec('PRAGMA wal_checkpoint(TRUNCATE)');
-    } catch (e) {
-      debug(
-        `tryNativeInsert: WAL checkpoint failed (nativeDb may already be closed): ${toErrorMessage(e)}`,
-      );
+      if (ctx.db) {
+        ctx.db.pragma('wal_checkpoint(TRUNCATE)');
+      }
+      result = ctx.nativeDb!.bulkInsertNodes(batches, fileHashes, removed);
+    } finally {
+      try {
+        ctx.nativeDb?.exec('PRAGMA wal_checkpoint(TRUNCATE)');
+      } catch (e) {
+        debug(
+          `tryNativeInsert: WAL checkpoint failed (nativeDb may already be closed): ${toErrorMessage(e)}`,
+        );
+      }
     }
   }
   return result;

package/src/domain/graph/builder/stages/resolve-imports.ts

@@ -34,15 +34,14 @@ function buildReexportMap(ctx: PipelineContext): void {
 
 /**
  * Find barrel files related to changed files for scoped re-parsing.
- * For small incremental builds (<=5 files), only barrels that re-export from
+ * For small incremental builds (<=smallFilesThreshold files), only barrels that re-export from
  * or are imported by the changed files. For larger changes, all barrels.
  */
 function findBarrelCandidates(ctx: PipelineContext): Array<{ file: string }> {
   const { db, fileSymbols, rootDir, aliases } = ctx;
   const changedRelPaths = new Set<string>(fileSymbols.keys());
 
-  const SMALL_CHANGE_THRESHOLD = 5;
-  if (changedRelPaths.size <= SMALL_CHANGE_THRESHOLD) {
+  if (changedRelPaths.size <= ctx.config.build.smallFilesThreshold) {
     const allBarrelFiles = new Set(
       (
         db