@optave/codegraph 3.9.0 → 3.9.2

package/dist/domain/graph/builder/pipeline.js

@@ -4,9 +4,10 @@
  * 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 { closeDbPair, getBuildMeta, initSchema, MIGRATIONS, openDb, setBuildMeta, } from '../../../db/index.js';
+import { acquireAdvisoryLock, closeDbPair, getBuildMeta, initSchema, MIGRATIONS, openDb, releaseAdvisoryLock, setBuildMeta, } from '../../../db/index.js';
 import { detectWorkspaces, loadConfig } from '../../../infrastructure/config.js';
 import { debug, info, warn } from '../../../infrastructure/logger.js';
 import { loadNative } from '../../../infrastructure/native.js';
@@ -17,6 +18,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
@@ -33,28 +35,11 @@ function initializeEngine(ctx) {
         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;
@@ -67,10 +52,10 @@ function checkEngineSchemaMismatch(ctx) {
     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) => 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) => getBuildMeta(ctx.db, key);
     const prevEngine = meta('engine');
     if (prevEngine && prevEngine !== ctx.engineName) {
         info(`Engine changed (${prevEngine} → ${ctx.engineName}), promoting to full rebuild.`);
@@ -107,36 +92,46 @@ function loadAliases(ctx) {
 function setupPipeline(ctx) {
     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;
+            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);
     }
     ctx.config = loadConfig(ctx.rootDir);
@@ -227,14 +222,351 @@ function refreshJsDb(ctx) {
     }
     ctx.db = openDb(ctx.dbPath);
 }
+// ── Native orchestrator helpers ───────────────────────────────────────
+/** Determine whether the native orchestrator should be skipped. Returns a reason string, or null if it should run. */
+function shouldSkipNativeOrchestrator(ctx) {
+    if (process.env.CODEGRAPH_FORCE_JS_PIPELINE === '1')
+        return 'CODEGRAPH_FORCE_JS_PIPELINE=1';
+    if (ctx.forceFullRebuild)
+        return 'forceFullRebuild';
+    // 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;
+}
+/** Checkpoint WAL through rusqlite, close nativeDb, and reopen better-sqlite3.
+ *  Returns false if the DB reopen fails (caller should return partial result). */
+function handoffWalAfterNativeBuild(ctx) {
+    closeNativeDb(ctx, 'post-native-build');
+    try {
+        ctx.db.close();
+    }
+    catch (e) {
+        debug(`handoffWal JS db close failed: ${toErrorMessage(e)}`);
+    }
+    try {
+        ctx.db = openDb(ctx.dbPath);
+        return true;
+    }
+    catch (reopenErr) {
+        warn(`Failed to reopen DB after native build: ${reopenErr.message}`);
+        return false;
+    }
+}
+/**
+ * Reconstruct fileSymbols from the DB after a native orchestrator build.
+ * When `scopeFiles` is provided, only loads those files (for analysis-only).
+ * When omitted, loads all files (needed for structure rebuilds).
+ */
+function reconstructFileSymbolsFromDb(ctx, scopeFiles) {
+    let query = 'SELECT file, name, kind, line, end_line as endLine FROM nodes WHERE file IS NOT NULL';
+    const params = [];
+    if (scopeFiles && scopeFiles.length > 0) {
+        const placeholders = scopeFiles.map(() => '?').join(',');
+        query += ` AND file IN (${placeholders})`;
+        params.push(...scopeFiles);
+    }
+    query += ' ORDER BY file, line';
+    const rows = ctx.db.prepare(query).all(...params);
+    const fileSymbols = new Map();
+    for (const row of rows) {
+        let entry = fileSymbols.get(row.file);
+        if (!entry) {
+            entry = {
+                definitions: [],
+                calls: [],
+                imports: [],
+                classes: [],
+                exports: [],
+                typeMap: new Map(),
+            };
+            fileSymbols.set(row.file, entry);
+        }
+        entry.definitions.push({
+            name: row.name,
+            kind: row.kind,
+            line: row.line,
+            endLine: row.endLine ?? undefined,
+        });
+    }
+    // Populate import/export counts from DB edges so buildStructure
+    // computes correct import_count/export_count in node_metrics.
+    // The extractor arrays aren't persisted to the DB, so we derive
+    // counts from edge data instead (#804).
+    const importCountRows = ctx.db
+        .prepare(`SELECT n.file, COUNT(*) AS cnt
+       FROM edges e JOIN nodes n ON e.source_id = n.id
+       WHERE e.kind IN ('imports', 'imports-type', 'dynamic-imports')
+         AND n.file IS NOT NULL
+       GROUP BY n.file`)
+        .all();
+    for (const row of importCountRows) {
+        const entry = fileSymbols.get(row.file);
+        if (entry)
+            entry.imports = new Array(row.cnt);
+    }
+    const exportCountRows = ctx.db
+        .prepare(`SELECT n_tgt.file, COUNT(DISTINCT n_tgt.id) AS cnt
+       FROM edges e
+       JOIN nodes n_tgt ON e.target_id = n_tgt.id
+       JOIN nodes n_src ON e.source_id = n_src.id
+       WHERE e.kind IN ('imports', 'imports-type', 'reexports')
+         AND n_tgt.file IS NOT NULL
+         AND n_src.file != n_tgt.file
+       GROUP BY n_tgt.file`)
+        .all();
+    for (const row of exportCountRows) {
+        const entry = fileSymbols.get(row.file);
+        if (entry)
+            entry.exports = new Array(row.cnt);
+    }
+    return fileSymbols;
+}
+/**
+ * Run JS buildStructure() after native orchestrator to fill directory nodes + contains edges.
+ * For full builds, passes changedFiles=null (full rebuild).
+ * For incremental builds, passes the changed file list to scope the update.
+ */
+async function runPostNativeStructure(ctx, allFileSymbols, isFullBuild, changedFiles) {
+    const structureStart = performance.now();
+    try {
+        const directories = new Set();
+        for (const relPath of allFileSymbols.keys()) {
+            const parts = relPath.split('/');
+            for (let i = 1; i < parts.length; i++) {
+                directories.add(parts.slice(0, i).join('/'));
+            }
+        }
+        const lineCountMap = new Map();
+        const cachedLineCounts = ctx.db
+            .prepare(`SELECT n.name AS file, m.line_count
+         FROM node_metrics m JOIN nodes n ON m.node_id = n.id
+         WHERE n.kind = 'file'`)
+            .all();
+        for (const row of cachedLineCounts) {
+            lineCountMap.set(row.file, row.line_count);
+        }
+        // Full builds need null (rebuild everything). Incremental builds pass the
+        // changed file list so buildStructure only updates those files' metrics
+        // and contains edges — matching the JS pipeline's medium-incremental path.
+        const changedFilePaths = isFullBuild || !changedFiles?.length ? null : changedFiles;
+        const { buildStructure: buildStructureFn } = (await import('../../../features/structure.js'));
+        buildStructureFn(ctx.db, allFileSymbols, ctx.rootDir, lineCountMap, directories, changedFilePaths);
+        debug(`Structure phase completed after native orchestrator${changedFilePaths ? ` (${changedFilePaths.length} files)` : ' (full)'}`);
+    }
+    catch (err) {
+        warn(`Structure phase failed after native build: ${toErrorMessage(err)}`);
+    }
+    return performance.now() - structureStart;
+}
+/** Run AST/complexity/CFG/dataflow analysis after native orchestrator. */
+async function runPostNativeAnalysis(ctx, allFileSymbols, changedFiles) {
+    const timing = { astMs: 0, complexityMs: 0, cfgMs: 0, dataflowMs: 0 };
+    // Scope analysis fileSymbols to changed files only
+    let analysisFileSymbols;
+    if (changedFiles && changedFiles.length > 0) {
+        analysisFileSymbols = new Map();
+        for (const f of changedFiles) {
+            const entry = allFileSymbols.get(f);
+            if (entry)
+                analysisFileSymbols.set(f, entry);
+        }
+    }
+    else {
+        analysisFileSymbols = allFileSymbols;
+    }
+    // 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 {
+        const { runAnalyses: runAnalysesFn } = await import('../../../ast-analysis/engine.js');
+        const result = await runAnalysesFn(ctx.db, analysisFileSymbols, ctx.rootDir, ctx.opts, ctx.engineOpts);
+        timing.astMs = result.astMs ?? 0;
+        timing.complexityMs = result.complexityMs ?? 0;
+        timing.cfgMs = result.cfgMs ?? 0;
+        timing.dataflowMs = result.dataflowMs ?? 0;
+    }
+    catch (err) {
+        warn(`Analysis phases failed after native build: ${toErrorMessage(err)}`);
+    }
+    // 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 {
+            /* ignore checkpoint errors */
+        }
+        try {
+            ctx.nativeDb.close();
+        }
+        catch {
+            /* ignore close errors */
+        }
+        ctx.nativeDb = undefined;
+        if (ctx.engineOpts)
+            ctx.engineOpts.nativeDb = undefined;
+    }
+    return timing;
+}
+/** Format timing result from native orchestrator phases + JS post-processing. */
+function formatNativeTimingResult(p, structurePatchMs, analysisTiming) {
+    return {
+        phases: {
+            setupMs: +((p.setupMs ?? 0) + (p.collectMs ?? 0) + (p.detectMs ?? 0)).toFixed(1),
+            parseMs: +(p.parseMs ?? 0).toFixed(1),
+            insertMs: +(p.insertMs ?? 0).toFixed(1),
+            resolveMs: +(p.resolveMs ?? 0).toFixed(1),
+            edgesMs: +(p.edgesMs ?? 0).toFixed(1),
+            structureMs: +((p.structureMs ?? 0) + structurePatchMs).toFixed(1),
+            rolesMs: +(p.rolesMs ?? 0).toFixed(1),
+            astMs: +(analysisTiming.astMs ?? 0).toFixed(1),
+            complexityMs: +(analysisTiming.complexityMs ?? 0).toFixed(1),
+            cfgMs: +(analysisTiming.cfgMs ?? 0).toFixed(1),
+            dataflowMs: +(analysisTiming.dataflowMs ?? 0).toFixed(1),
+            finalizeMs: +(p.finalizeMs ?? 0).toFixed(1),
+        },
+    };
+}
+/** Try the native build orchestrator. Returns a BuildResult on success, undefined to fall through to JS pipeline. */
+async function tryNativeOrchestrator(ctx) {
+    const skipReason = shouldSkipNativeOrchestrator(ctx);
+    if (skipReason) {
+        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(ctx.rootDir, JSON.stringify(ctx.config), JSON.stringify(ctx.aliases), JSON.stringify(ctx.opts));
+    const result = JSON.parse(resultJson);
+    if (result.earlyExit) {
+        info('No changes detected');
+        closeDbPair({ db: ctx.db, nativeDb: ctx.nativeDb });
+        return 'early-exit';
+    }
+    // Log incremental status to match JS pipeline output
+    const changed = result.changedCount ?? 0;
+    const removed = result.removedCount ?? 0;
+    if (!result.isFullBuild && (changed > 0 || removed > 0)) {
+        info(`Incremental: ${changed} changed, ${removed} removed`);
+    }
+    const p = result.phases;
+    // Sync build_meta so JS-side version/engine checks work on next build.
+    setBuildMeta(ctx.db, {
+        engine: ctx.engineName,
+        engine_version: ctx.engineVersion || '',
+        codegraph_version: CODEGRAPH_VERSION,
+        schema_version: String(ctx.schemaVersion),
+        built_at: new Date().toISOString(),
+        node_count: String(result.nodeCount ?? 0),
+        edge_count: String(result.edgeCount ?? 0),
+    });
+    info(`Native build orchestrator completed: ${result.nodeCount ?? 0} nodes, ${result.edgeCount ?? 0} edges, ${result.fileCount ?? 0} files`);
+    // ── Post-native structure + analysis ──────────────────────────────
+    let analysisTiming = { astMs: 0, complexityMs: 0, cfgMs: 0, 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) {
+        // 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);
+        }
+        // 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);
+        if (needsStructure) {
+            structurePatchMs = await runPostNativeStructure(ctx, fileSymbols, !!result.isFullBuild, result.structureScope ?? result.changedFiles);
+        }
+        if (needsAnalysis) {
+            analysisTiming = await runPostNativeAnalysis(ctx, fileSymbols, result.changedFiles);
+        }
+    }
+    closeDbPair({ db: ctx.db, nativeDb: ctx.nativeDb });
+    return formatNativeTimingResult(p, structurePatchMs, analysisTiming);
+}
 // ── Pipeline stages execution ───────────────────────────────────────────
 async function runPipelineStages(ctx) {
-    // 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');
     }
@@ -243,10 +575,12 @@ async function runPipelineStages(ctx) {
     if (ctx.earlyExit)
         return;
     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');
     }
     await insertNodes(ctx);
@@ -260,13 +594,27 @@ async function runPipelineStages(ctx) {
     await buildStructure(ctx);
     // 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;
         }
     }
     await runAnalyses(ctx);
@@ -296,303 +644,16 @@ export async function buildGraph(rootDir, opts = {}) {
         // When available, run the entire build pipeline in Rust with zero
         // napi crossings (eliminates WAL dual-connection dance). Falls back
         // to the JS pipeline on failure or when native is unavailable.
-        //
-        // Native addon ≤3.8.0 has a path bug: file_symbols keys are absolute
-        // paths but known_files are relative, causing zero import/call edges.
-        // Native addon ≤3.8.1 has an incremental barrel bug: the Rust pipeline
-        // doesn't re-parse barrel files that are imported by changed files,
-        // causing missing barrel import edges and lost analysis data for
-        // reverse-dep files during incremental builds.
-        // Skip the orchestrator for affected versions (fixed in 3.9.0+).
-        const orchestratorBuggy = !!ctx.engineVersion && semverCompare(ctx.engineVersion, '3.8.1') <= 0;
-        const forceJs = process.env.CODEGRAPH_FORCE_JS_PIPELINE === '1' ||
-            ctx.forceFullRebuild ||
-            orchestratorBuggy ||
-            ctx.engineName !== 'native';
-        if (forceJs) {
-            const reason = process.env.CODEGRAPH_FORCE_JS_PIPELINE === '1'
-                ? 'CODEGRAPH_FORCE_JS_PIPELINE=1'
-                : ctx.forceFullRebuild
-                    ? 'forceFullRebuild'
-                    : orchestratorBuggy
-                        ? `buggy addon ${ctx.engineVersion}`
-                        : `engine=${ctx.engineName}`;
-            debug(`Skipping native orchestrator: ${reason}`);
+        try {
+            const nativeResult = await tryNativeOrchestrator(ctx);
+            if (nativeResult === 'early-exit')
+                return;
+            if (nativeResult)
+                return nativeResult;
         }
-        if (!forceJs && ctx.nativeDb?.buildGraph) {
-            try {
-                const resultJson = ctx.nativeDb.buildGraph(ctx.rootDir, JSON.stringify(ctx.config), JSON.stringify(ctx.aliases), JSON.stringify(opts));
-                const result = JSON.parse(resultJson);
-                if (result.earlyExit) {
-                    info('No changes detected');
-                    closeDbPair({ db: ctx.db, nativeDb: ctx.nativeDb });
-                    return;
-                }
-                // Log incremental status to match JS pipeline output
-                const changed = result.changedCount ?? 0;
-                const removed = result.removedCount ?? 0;
-                if (!result.isFullBuild && (changed > 0 || removed > 0)) {
-                    info(`Incremental: ${changed} changed, ${removed} removed`);
-                }
-                // Map Rust timing fields to the JS BuildResult format.
-                // Rust handles collect+detect+parse+insert+resolve+edges+structure+roles.
-                const p = result.phases;
-                // Sync build_meta so JS-side version/engine checks work on next build.
-                // Note: the Rust orchestrator also writes codegraph_version (using
-                // CARGO_PKG_VERSION). We intentionally overwrite it here with the npm
-                // package version so that the JS-side "version changed → full rebuild"
-                // detection (line ~97) compares against the authoritative JS version.
-                // The two versions are kept in lockstep by the release process.
-                setBuildMeta(ctx.db, {
-                    engine: ctx.engineName,
-                    engine_version: ctx.engineVersion || '',
-                    codegraph_version: CODEGRAPH_VERSION,
-                    schema_version: String(ctx.schemaVersion),
-                    built_at: new Date().toISOString(),
-                    node_count: String(result.nodeCount ?? 0),
-                    edge_count: String(result.edgeCount ?? 0),
-                });
-                info(`Native build orchestrator completed: ${result.nodeCount ?? 0} nodes, ${result.edgeCount ?? 0} edges, ${result.fileCount ?? 0} files`);
-                // ── Run structure + analysis phases after native orchestrator ──
-                // Structure (directory nodes, contains edges, metrics) is not fully
-                // ported to Rust — the native pipeline only handles the small
-                // incremental fast path (≤5 changed files). For full builds and
-                // larger incremental builds, run JS buildStructure() to fill the gap.
-                // Analysis phases (AST, complexity, CFG, dataflow) are also not yet
-                // ported; run via JS engine after reconstructing fileSymbols from DB.
-                let analysisTiming = { astMs: 0, complexityMs: 0, cfgMs: 0, dataflowMs: 0 };
-                let structurePatchMs = 0;
-                const needsAnalysis = opts.ast !== false ||
-                    opts.complexity !== false ||
-                    opts.cfg !== false ||
-                    opts.dataflow !== false;
-                // The native fast path only runs structure for small incremental
-                // builds: !isFullBuild && changedCount <= 5 && existingFileCount > 20.
-                // For all other cases (full builds, large incrementals), we must
-                // run JS buildStructure() to create directory nodes + contains edges (#804).
-                // Always run JS structure — the native fast-path has an additional
-                // existingFileCount > 20 guard that isn't reflected in the result JSON,
-                // so we can't reliably detect whether native actually ran structure.
-                const nativeHandledStructure = false;
-                const needsStructure = !nativeHandledStructure;
-                if (needsAnalysis || needsStructure) {
-                    // WAL handoff: checkpoint through rusqlite, close nativeDb,
-                    // reopen better-sqlite3 with a fresh page cache (#715, #736).
-                    try {
-                        ctx.nativeDb.exec('PRAGMA wal_checkpoint(TRUNCATE)');
-                    }
-                    catch {
-                        /* ignore checkpoint errors */
-                    }
-                    try {
-                        ctx.nativeDb.close();
-                    }
-                    catch {
-                        /* ignore close errors */
-                    }
-                    ctx.nativeDb = undefined;
-                    try {
-                        ctx.db.close();
-                    }
-                    catch {
-                        /* ignore close errors */
-                    }
-                    ctx.db = null; // avoid closeDbPair operating on a stale handle
-                    try {
-                        ctx.db = openDb(ctx.dbPath);
-                    }
-                    catch (reopenErr) {
-                        warn(`Failed to reopen DB after native build: ${reopenErr.message}`);
-                        // Native build succeeded but we can't run post-processing — return partial result
-                        return {
-                            phases: {
-                                setupMs: +((p.setupMs ?? 0) + (p.collectMs ?? 0) + (p.detectMs ?? 0)).toFixed(1),
-                                parseMs: +(p.parseMs ?? 0).toFixed(1),
-                                insertMs: +(p.insertMs ?? 0).toFixed(1),
-                                resolveMs: +(p.resolveMs ?? 0).toFixed(1),
-                                edgesMs: +(p.edgesMs ?? 0).toFixed(1),
-                                structureMs: +(p.structureMs ?? 0).toFixed(1),
-                                rolesMs: +(p.rolesMs ?? 0).toFixed(1),
-                                astMs: 0,
-                                complexityMs: 0,
-                                cfgMs: 0,
-                                dataflowMs: 0,
-                                finalizeMs: +(p.finalizeMs ?? 0).toFixed(1),
-                            },
-                        };
-                    }
-                    // Reconstruct fileSymbols from DB. For structure we need ALL files
-                    // (to build complete directory tree); for analysis we scope to
-                    // changed files only. Load all files, then scope analysis later.
-                    const allFileRows = ctx.db
-                        .prepare('SELECT file, name, kind, line, end_line as endLine FROM nodes WHERE file IS NOT NULL ORDER BY file, line')
-                        .all();
-                    const allFileSymbols = new Map();
-                    for (const row of allFileRows) {
-                        let entry = allFileSymbols.get(row.file);
-                        if (!entry) {
-                            entry = {
-                                definitions: [],
-                                calls: [],
-                                imports: [],
-                                classes: [],
-                                exports: [],
-                                typeMap: new Map(),
-                            };
-                            allFileSymbols.set(row.file, entry);
-                        }
-                        entry.definitions.push({
-                            name: row.name,
-                            kind: row.kind,
-                            line: row.line,
-                            endLine: row.endLine ?? undefined,
-                        });
-                    }
-                    // Populate import/export counts from DB edges so buildStructure
-                    // computes correct import_count/export_count in node_metrics.
-                    // The extractor arrays aren't persisted to the DB, so we derive
-                    // counts from edge data instead (#804).
-                    const importCountRows = ctx.db
-                        .prepare(`SELECT n.file, COUNT(*) AS cnt
-               FROM edges e JOIN nodes n ON e.source_id = n.id
-               WHERE e.kind IN ('imports', 'imports-type', 'dynamic-imports')
-                 AND n.file IS NOT NULL
-               GROUP BY n.file`)
-                        .all();
-                    for (const row of importCountRows) {
-                        const entry = allFileSymbols.get(row.file);
-                        if (entry)
-                            entry.imports = new Array(row.cnt);
-                    }
-                    // Export count: definitions in this file that are imported by other files
-                    const exportCountRows = ctx.db
-                        .prepare(`SELECT n_tgt.file, COUNT(DISTINCT n_tgt.id) AS cnt
-               FROM edges e
-               JOIN nodes n_tgt ON e.target_id = n_tgt.id
-               JOIN nodes n_src ON e.source_id = n_src.id
-               WHERE e.kind IN ('imports', 'imports-type', 'reexports')
-                 AND n_tgt.file IS NOT NULL
-                 AND n_src.file != n_tgt.file
-               GROUP BY n_tgt.file`)
-                        .all();
-                    for (const row of exportCountRows) {
-                        const entry = allFileSymbols.get(row.file);
-                        if (entry)
-                            entry.exports = new Array(row.cnt);
-                    }
-                    // ── Structure phase: directory nodes + contains edges (#804) ──
-                    if (needsStructure) {
-                        const structureStart = performance.now();
-                        try {
-                            // Derive directories from file paths
-                            const directories = new Set();
-                            for (const relPath of allFileSymbols.keys()) {
-                                const parts = relPath.split('/');
-                                for (let i = 1; i < parts.length; i++) {
-                                    directories.add(parts.slice(0, i).join('/'));
-                                }
-                            }
-                            // Build line count map from DB metrics or file content
-                            const lineCountMap = new Map();
-                            const cachedLineCounts = ctx.db
-                                .prepare(`SELECT n.name AS file, m.line_count
-                 FROM node_metrics m JOIN nodes n ON m.node_id = n.id
-                 WHERE n.kind = 'file'`)
-                                .all();
-                            for (const row of cachedLineCounts) {
-                                lineCountMap.set(row.file, row.line_count);
-                            }
-                            // Native ran no structure at all — always do a full rebuild so
-                            // every directory gets nodes + contains edges (#804).
-                            const changedFilePaths = null;
-                            const { buildStructure: buildStructureFn } = (await import('../../../features/structure.js'));
-                            buildStructureFn(ctx.db, allFileSymbols, ctx.rootDir, lineCountMap, directories, changedFilePaths);
-                            debug('Structure phase completed after native orchestrator');
-                        }
-                        catch (err) {
-                            warn(`Structure phase failed after native build: ${toErrorMessage(err)}`);
-                        }
-                        structurePatchMs = performance.now() - structureStart;
-                    }
-                    // ── Analysis phase ──
-                    if (needsAnalysis) {
-                        // Scope analysis fileSymbols to changed files only
-                        const changedFiles = result.changedFiles;
-                        let analysisFileSymbols;
-                        if (changedFiles && changedFiles.length > 0) {
-                            analysisFileSymbols = new Map();
-                            for (const f of changedFiles) {
-                                const entry = allFileSymbols.get(f);
-                                if (entry)
-                                    analysisFileSymbols.set(f, entry);
-                            }
-                        }
-                        else {
-                            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;
-                            }
-                        }
-                        try {
-                            const { runAnalyses: runAnalysesFn } = await import('../../../ast-analysis/engine.js');
-                            analysisTiming = await runAnalysesFn(ctx.db, analysisFileSymbols, ctx.rootDir, opts, ctx.engineOpts);
-                        }
-                        catch (err) {
-                            warn(`Analysis phases failed after native build: ${toErrorMessage(err)}`);
-                        }
-                        // Close nativeDb after analyses
-                        if (ctx.nativeDb) {
-                            try {
-                                ctx.nativeDb.exec('PRAGMA wal_checkpoint(TRUNCATE)');
-                            }
-                            catch {
-                                /* ignore checkpoint errors */
-                            }
-                            try {
-                                ctx.nativeDb.close();
-                            }
-                            catch {
-                                /* ignore close errors */
-                            }
-                            ctx.nativeDb = undefined;
-                            if (ctx.engineOpts)
-                                ctx.engineOpts.nativeDb = undefined;
-                        }
-                    }
-                }
-                closeDbPair({ db: ctx.db, nativeDb: ctx.nativeDb });
-                return {
-                    phases: {
-                        setupMs: +((p.setupMs ?? 0) + (p.collectMs ?? 0) + (p.detectMs ?? 0)).toFixed(1),
-                        parseMs: +(p.parseMs ?? 0).toFixed(1),
-                        insertMs: +(p.insertMs ?? 0).toFixed(1),
-                        resolveMs: +(p.resolveMs ?? 0).toFixed(1),
-                        edgesMs: +(p.edgesMs ?? 0).toFixed(1),
-                        structureMs: +((p.structureMs ?? 0) + structurePatchMs).toFixed(1),
-                        rolesMs: +(p.rolesMs ?? 0).toFixed(1),
-                        astMs: +(analysisTiming.astMs ?? 0).toFixed(1),
-                        complexityMs: +(analysisTiming.complexityMs ?? 0).toFixed(1),
-                        cfgMs: +(analysisTiming.cfgMs ?? 0).toFixed(1),
-                        dataflowMs: +(analysisTiming.dataflowMs ?? 0).toFixed(1),
-                        finalizeMs: +(p.finalizeMs ?? 0).toFixed(1),
-                    },
-                };
-            }
-            catch (err) {
-                warn(`Native build orchestrator failed, falling back to JS pipeline: ${toErrorMessage(err)}`);
-                // Fall through to JS pipeline
-            }
+        catch (err) {
+            warn(`Native build orchestrator failed, falling back to JS pipeline: ${toErrorMessage(err)}`);
+            // Fall through to JS pipeline
         }
         await runPipelineStages(ctx);
     }