@optave/codegraph 3.9.1 → 3.9.2

package/src/domain/graph/builder/native-db-proxy.ts

@@ -0,0 +1,98 @@
+/**
+ * NativeDbProxy — wraps a NativeDatabase (rusqlite via napi-rs) to satisfy the
+ * BetterSqlite3Database interface.  When the native addon is available, the
+ * build pipeline uses this proxy as `ctx.db` so that every stage operates on a
+ * single rusqlite connection — no dual-connection WAL corruption, no
+ * open/close/reopen dance.
+ *
+ * When native is unavailable, the pipeline falls back to real better-sqlite3.
+ */
+
+import type { BetterSqlite3Database, NativeDatabase, SqliteStatement } from '../../../types.js';
+
+/** Sanitize params for napi-rs: better-sqlite3 treats `undefined` as NULL,
+ *  but serde_json cannot represent `undefined`. Replace with `null`. */
+function sanitize(params: unknown[]): Array<string | number | null> {
+  return params.map((p) => (p === undefined ? null : p)) as Array<string | number | null>;
+}
+
+export class NativeDbProxy implements BetterSqlite3Database {
+  readonly #ndb: NativeDatabase;
+  /** Advisory lock path — set by the pipeline so closeDb() can release it. */
+  __lockPath?: string;
+
+  constructor(nativeDb: NativeDatabase) {
+    this.#ndb = nativeDb;
+  }
+
+  prepare<TRow = unknown>(sql: string): SqliteStatement<TRow> {
+    const ndb = this.#ndb;
+    const stmt: SqliteStatement<TRow> = {
+      all(...params: unknown[]): TRow[] {
+        return ndb.queryAll(sql, sanitize(params)) as TRow[];
+      },
+      get(...params: unknown[]): TRow | undefined {
+        return (ndb.queryGet(sql, sanitize(params)) ?? undefined) as TRow | undefined;
+      },
+      run(...params: unknown[]): { changes: number; lastInsertRowid: number | bigint } {
+        ndb.queryAll(sql, sanitize(params));
+        // Retrieve last_insert_rowid via SQLite scalar function so callers
+        // that depend on it (e.g. CFG block edge mapping) get correct values.
+        const row = ndb.queryGet('SELECT last_insert_rowid() AS rid', []) as { rid: number } | null;
+        return { changes: 0, lastInsertRowid: row?.rid ?? 0 };
+      },
+      iterate(): IterableIterator<TRow> {
+        throw new Error('iterate() is not supported via NativeDbProxy');
+      },
+      raw(): SqliteStatement<TRow> {
+        return stmt; // no-op — .raw() is not used in the build pipeline
+      },
+    };
+    return stmt;
+  }
+
+  exec(sql: string): this {
+    this.#ndb.exec(sql);
+    return this;
+  }
+
+  pragma(sql: string): unknown {
+    return this.#ndb.pragma(sql);
+  }
+
+  close(): void {
+    // No-op: the pipeline manages the NativeDatabase lifecycle directly.
+    // closeDbPair() calls nativeDb.close() separately.
+  }
+
+  get open(): boolean {
+    return this.#ndb.isOpen;
+  }
+
+  get name(): string {
+    return this.#ndb.dbPath;
+  }
+
+  transaction<F extends (...args: any[]) => any>(
+    fn: F,
+  ): (...args: F extends (...a: infer A) => unknown ? A : never) => ReturnType<F> {
+    const ndb = this.#ndb;
+    return ((...args: unknown[]) => {
+      // NOTE: nested transactions (savepoints) are not supported — ensure callers
+      // do not invoke a transaction() wrapper from within an existing transaction.
+      ndb.exec('BEGIN');
+      try {
+        const result = fn(...args);
+        ndb.exec('COMMIT');
+        return result;
+      } catch (e) {
+        try {
+          ndb.exec('ROLLBACK');
+        } catch {
+          // Ignore rollback errors — the original error is more important
+        }
+        throw e;
+      }
+    }) as any;
+  }
+}

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';
@@ -25,6 +28,7 @@ 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 +47,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 +65,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 +114,46 @@ 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;
+
+  // Native-first: use only rusqlite for the entire pipeline (no better-sqlite3).
+  // This eliminates the dual-connection WAL corruption problem and enables all
+  // native fast-paths (bulkInsertNodes, classifyRolesFull, etc.).
+  // Fallback: if native is unavailable or FORCE_JS is set, use better-sqlite3.
+  if (
+    ctx.nativeAvailable &&
+    native?.NativeDatabase &&
+    process.env.CODEGRAPH_FORCE_JS_PIPELINE !== '1'
+  ) {
     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);
   }
 
@@ -275,7 +272,10 @@ interface NativeOrchestratorResult {
 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;
@@ -472,16 +472,20 @@ async function runPostNativeAnalysis(
     analysisFileSymbols = allFileSymbols;
   }
 
-  // Reopen nativeDb for analysis features (suspend/resume WAL pattern).
-  const native = loadNative();
-  if (native?.NativeDatabase) {
-    try {
-      ctx.nativeDb = native.NativeDatabase.openReadWrite(ctx.dbPath);
-      if (ctx.engineOpts) ctx.engineOpts.nativeDb = ctx.nativeDb;
-    } catch {
-      ctx.nativeDb = undefined;
-      if (ctx.engineOpts) ctx.engineOpts.nativeDb = undefined;
+  // In native-first mode, nativeDb is already open — no reopen needed.
+  if (!ctx.nativeFirstProxy) {
+    const native = loadNative();
+    if (native?.NativeDatabase) {
+      try {
+        ctx.nativeDb = native.NativeDatabase.openReadWrite(ctx.dbPath);
+        if (ctx.engineOpts) ctx.engineOpts.nativeDb = ctx.nativeDb;
+      } catch {
+        ctx.nativeDb = undefined;
+        if (ctx.engineOpts) ctx.engineOpts.nativeDb = undefined;
+      }
     }
+  } else if (ctx.engineOpts) {
+    ctx.engineOpts.nativeDb = ctx.nativeDb;
   }
 
   try {
@@ -501,8 +505,8 @@ async function runPostNativeAnalysis(
     warn(`Analysis phases failed after native build: ${toErrorMessage(err)}`);
   }
 
-  // Close nativeDb after analyses
-  if (ctx.nativeDb) {
+  // Close nativeDb after analyses (skip in native-first — single connection stays open)
+  if (ctx.nativeDb && !ctx.nativeFirstProxy) {
     try {
       ctx.nativeDb.exec('PRAGMA wal_checkpoint(TRUNCATE)');
     } catch {
@@ -553,6 +557,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(
@@ -607,7 +633,8 @@ async function tryNativeOrchestrator(
   const needsStructure = !result.structureHandled;
 
   if (needsAnalysis || needsStructure) {
-    if (!handoffWalAfterNativeBuild(ctx)) {
+    // In native-first mode the proxy is already wired — no WAL handoff needed.
+    if (!ctx.nativeFirstProxy && !handoffWalAfterNativeBuild(ctx)) {
       // DB reopen failed — return partial result
       return formatNativeTimingResult(p, 0, analysisTiming);
     }
@@ -639,12 +666,35 @@ 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;
+  // ── Native-first mode ────────────────────────────────────────────────
+  // When ctx.nativeFirstProxy is true, ctx.db is a NativeDbProxy backed by
+  // the single rusqlite connection (ctx.nativeDb). No dual-connection WAL
+  // dance is needed — every stage uses the same connection transparently.
+  if (ctx.nativeFirstProxy) {
+    // Ensure engineOpts.nativeDb is set so stages can use dedicated native methods.
+    if (ctx.engineOpts) {
+      ctx.engineOpts.nativeDb = ctx.nativeDb;
+    }
+
+    await collectFiles(ctx);
+    await detectChanges(ctx);
+    if (ctx.earlyExit) return;
+    await parseFiles(ctx);
+    await insertNodes(ctx);
+    await resolveImports(ctx);
+    await buildEdges(ctx);
+    await buildStructure(ctx);
+    await runAnalyses(ctx);
+    await finalize(ctx);
+    return;
+  }
+
+  // ── Legacy dual-connection mode (WASM / fallback) ────────────────────
+  // 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');
   }
@@ -656,10 +706,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');
   }
 
@@ -677,13 +730,28 @@ 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) {
+  // Skip for small incremental builds — same rationale as insertNodes above.
+  if (ctx.nativeAvailable && !smallIncremental) {
     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;
     }
   }
 

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

package/src/domain/parser.ts

@@ -5,7 +5,7 @@ import type { Tree } from 'web-tree-sitter';
 import { Language, Parser, Query } from 'web-tree-sitter';
 import { debug, warn } from '../infrastructure/logger.js';
 import { getNative, getNativePackageVersion, loadNative } from '../infrastructure/native.js';
-import { toErrorMessage } from '../shared/errors.js';
+import { ParseError, toErrorMessage } from '../shared/errors.js';
 import type {
   EngineMode,
   ExtractorOutput,
@@ -188,7 +188,11 @@ async function doLoadLanguage(entry: LanguageRegistryEntry): Promise<void> {
       _queryCache.set(entry.id, new Query(lang, patterns.join('\n')));
     }
   } catch (e: unknown) {
-    if (entry.required) throw e;
+    if (entry.required)
+      throw new ParseError(`Required parser ${entry.id} failed to initialize`, {
+        file: entry.grammarFile,
+        cause: e as Error,
+      });
     warn(
       `${entry.id} parser failed to initialize: ${(e as Error).message}. ${entry.id} files will be skipped.`,
     );

package/src/domain/queries.ts

@@ -22,7 +22,7 @@ export {
   VALID_ROLES,
 } from '../shared/kinds.js';
 // ── Shared utilities ─────────────────────────────────────────────────────
-export { kindIcon, normalizeSymbol } from '../shared/normalize.js';
+export { kindIcon, normalizeSymbol, toSymbolRef } from '../shared/normalize.js';
 export { briefData } from './analysis/brief.js';
 export { contextData, explainData } from './analysis/context.js';
 export { fileDepsData, filePathData, fnDepsData, pathData } from './analysis/dependencies.js';