perf(native): fix incremental rebuild regression (#882) (#888)

* perf(native): fix incremental rebuild regression by lowering orchestrator version gate

The v3.9.1 native addon includes all incremental purge fixes from PR #865,
but the orchestrator version gate was raised to < 3.10.0 in PR #867 (because
the v3.9.0 prebuilt binaries were built before those fixes). This forced the
slower JS pipeline path for all v3.9.x addon versions, causing:

- No-op rebuild: 6ms → 15ms (+150%) — JS collectFiles + detectChanges slower
  than Rust orchestrator's equivalent
- 1-file rebuild: 527ms → 757ms (+44%) — JS pipeline adds nativeDb open/close
  cycles + JS-side resolve/edges instead of single Rust pass

Fix: lower the gate from < 3.10.0 to < 3.9.1, re-enabling the Rust
orchestrator for v3.9.1+ addon binaries.

Additionally, skip nativeDb open/close cycles in the JS pipeline fallback for
small incremental builds (≤5 files). The WAL checkpoint + connection churn
(~5-10ms) exceeds bulk-insert savings for a handful of files.

Closes #882

* refactor: extract smallFilesThreshold to DEFAULTS.build config (#888)

Replace hardcoded `<= 5` threshold across pipeline stages with
`config.build.smallFilesThreshold` from DEFAULTS, consolidating
five scattered magic numbers into one configurable constant.

* fix: use allSymbols.size instead of fileSymbols.size for smallIncremental guard

ctx.fileSymbols is an empty Map when the smallIncremental check runs
(populated later inside insertNodes). This caused every non-full build
to be treated as small incremental, skipping reopenNativeDb for all
incremental builds. Use ctx.allSymbols.size which parseFiles populates
before this check.

Author: carlos-alm

src/domain/graph/builder/pipeline.ts

@@ -234,7 +234,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;
@@ -636,10 +639,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 (ctx.nativeAvailable && 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');
   }
 
@@ -657,7 +663,8 @@ 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 (ctx.nativeAvailable) {
+  // 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;

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

@@ -712,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;

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) {

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);

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

src/infrastructure/config.ts

@@ -23,6 +23,7 @@ export const DEFAULTS = {
     incremental: true,
     dbPath: '.codegraph/graph.db',
     driftThreshold: 0.2,
+    smallFilesThreshold: 5,
   },
   query: {
     defaultDepth: 3,

src/types.ts

@@ -1085,6 +1085,7 @@ export interface CodegraphConfig {
     incremental: boolean;
     dbPath: string;
     driftThreshold: number;
+    smallFilesThreshold: number;
   };
 
   query: {