@optave/codegraph 3.9.6 → 3.11.0

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

@@ -7,7 +7,7 @@
 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 { acquireAdvisoryLock, closeDb, closeDbPair, getBuildMeta, initSchema, MIGRATIONS, openDb, purgeFilesData, 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';
@@ -15,16 +15,17 @@ import { semverCompare } from '../../../infrastructure/update-check.js';
 import { normalizePath } from '../../../shared/constants.js';
 import { toErrorMessage } from '../../../shared/errors.js';
 import { CODEGRAPH_VERSION } from '../../../shared/version.js';
-import { classifyNativeDrops, formatDropExtensionSummary, getActiveEngine, getInstalledWasmExtensions, parseFilesAuto, } from '../../parser.js';
+import { classifyNativeDrops, formatDropExtensionSummary, getActiveEngine, getInstalledWasmExtensions, NATIVE_SUPPORTED_EXTENSIONS, parseFilesWasmForBackfill, } from '../../parser.js';
+import { writeJournalHeader } from '../journal.js';
 import { setWorkspaces } from '../resolve.js';
 import { PipelineContext } from './context.js';
-import { batchInsertNodes, collectFiles as collectFilesUtil, loadPathAliases } from './helpers.js';
+import { batchInsertNodes, collectFiles as collectFilesUtil, fileHash, fileStat, loadPathAliases, readFileSafe, } 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
 import { collectFiles } from './stages/collect-files.js';
-import { detectChanges } from './stages/detect-changes.js';
+import { detectChanges, detectNoChanges } from './stages/detect-changes.js';
 import { finalize } from './stages/finalize.js';
 import { insertNodes } from './stages/insert-nodes.js';
 import { parseFiles } from './stages/parse-files.js';
@@ -42,9 +43,10 @@ function initializeEngine(ctx) {
         suspendJsDb: undefined,
         resumeJsDb: undefined,
     };
-    const { name: engineName, version: engineVersion } = getActiveEngine(ctx.engineOpts);
+    const { name: engineName, version: engineVersion, binaryVersion: nativeBinaryVersion, } = getActiveEngine(ctx.engineOpts);
     ctx.engineName = engineName;
     ctx.engineVersion = engineVersion;
+    ctx.nativeBinaryVersion = nativeBinaryVersion;
     info(`Using ${engineName} engine${engineVersion ? ` (v${engineVersion})` : ''}`);
 }
 function checkEngineSchemaMismatch(ctx) {
@@ -67,12 +69,14 @@ function checkEngineSchemaMismatch(ctx) {
         info(`Schema version changed (${prevSchema} → ${ctx.schemaVersion}), promoting to full rebuild.`);
         ctx.forceFullRebuild = true;
     }
-    // When the native engine is active, the Rust addon's version (ctx.engineVersion)
-    // is written into codegraph_version by setBuildMeta after a native orchestrator
-    // build. The check must compare against the same version, otherwise JS and Rust
-    // fight over which version to record — causing every incremental build to be
-    // promoted to a full rebuild when npm and crate versions diverge.
-    const effectiveVersion = ctx.engineName === 'native' && ctx.engineVersion ? ctx.engineVersion : CODEGRAPH_VERSION;
+    // When the native engine is active, the Rust orchestrator writes
+    // build_meta.codegraph_version = CARGO_PKG_VERSION (the binary's own value).
+    // Compare against the same value here so a CI hot-swap that leaves the
+    // platform package.json behind doesn't trigger a perpetual full-rebuild
+    // loop on every incremental (#1066).
+    const effectiveVersion = ctx.engineName === 'native' && ctx.nativeBinaryVersion
+        ? ctx.nativeBinaryVersion
+        : CODEGRAPH_VERSION;
     const prevVersion = meta('codegraph_version');
     if (prevVersion && prevVersion !== effectiveVersion) {
         info(`Codegraph version changed (${prevVersion} → ${effectiveVersion}), promoting to full rebuild.`);
@@ -113,7 +117,9 @@ function loadAliases(ctx) {
 }
 function setupPipeline(ctx) {
     ctx.rootDir = path.resolve(ctx.rootDir);
-    ctx.dbPath = path.join(ctx.rootDir, '.codegraph', 'graph.db');
+    ctx.dbPath = ctx.opts.dbPath
+        ? path.resolve(ctx.opts.dbPath)
+        : path.join(ctx.rootDir, '.codegraph', 'graph.db');
     // Detect whether native engine is available.
     const enginePref = ctx.opts.engine || 'auto';
     const native = enginePref !== 'wasm' ? loadNative() : null;
@@ -129,6 +135,16 @@ function setupPipeline(ctx) {
     ctx.db = openDb(ctx.dbPath);
     initSchema(ctx.db);
     ctx.config = loadConfig(ctx.rootDir);
+    // Merge caller-supplied excludes on top of the file-config excludes so
+    // programmatic callers (e.g. benchmark scripts) can extend exclusion
+    // without mutating .codegraphrc.json. Native orchestrator picks this up
+    // automatically — it reads exclude off the serialized ctx.config below.
+    if (ctx.opts.exclude?.length) {
+        ctx.config = {
+            ...ctx.config,
+            exclude: [...(ctx.config.exclude ?? []), ...ctx.opts.exclude],
+        };
+    }
     ctx.incremental =
         ctx.opts.incremental !== false && ctx.config.build && ctx.config.build.incremental !== false;
     initializeEngine(ctx);
@@ -508,6 +524,15 @@ async function tryNativeOrchestrator(ctx) {
     const result = JSON.parse(resultJson);
     if (result.earlyExit) {
         info('No changes detected');
+        // Even on no-op rebuilds, dropped-language files added since the last
+        // full build are still missing from `nodes`/`file_hashes` (#1083), and
+        // WASM-only files deleted from disk leave stale rows behind (#1073).
+        // The orchestrator's file_collector skipped them, so its earlyExit
+        // doesn't imply DB consistency. Run the gap repair before returning.
+        const gap = detectDroppedLanguageGap(ctx);
+        if (gap.missingAbs.length > 0 || gap.staleRel.length > 0) {
+            await backfillNativeDroppedFiles(ctx, gap);
+        }
         closeDbPair({ db: ctx.db, nativeDb: ctx.nativeDb });
         return 'early-exit';
     }
@@ -519,16 +544,24 @@ async function tryNativeOrchestrator(ctx) {
     }
     const p = result.phases;
     // Sync build_meta so JS-side version/engine checks work on next build.
-    // Use the Rust addon version as codegraph_version when the native
-    // orchestrator performed the build — the Rust side's check_version_mismatch
-    // compares this value against CARGO_PKG_VERSION.  Writing the JS
-    // CODEGRAPH_VERSION here would create a permanent mismatch whenever the
-    // npm package version diverges from the Rust crate version, forcing every
-    // subsequent native build to be a full rebuild (no incremental).
+    // Use the binary's CARGO_PKG_VERSION (ctx.nativeBinaryVersion), not the
+    // platform package.json version (ctx.engineVersion). The Rust side's
+    // check_version_mismatch compares against CARGO_PKG_VERSION; writing
+    // the package.json value would create a permanent mismatch whenever
+    // the binary and platform package.json diverge — e.g., CI hot-swap
+    // via ci-install-native.mjs (#1066) — forcing every subsequent build
+    // to be a full rebuild.
+    //
+    // When the native addon doesn't expose engineVersion() (older addon),
+    // fall back to CODEGRAPH_VERSION — same fallback used by both
+    // checkEngineSchemaMismatch (read path) and persistBuildMetadata
+    // (the JS-pipeline write path in finalize.ts). Using ctx.engineVersion
+    // here would re-introduce the asymmetry this PR fixes for that case.
+    const nativeVersionForMeta = ctx.nativeBinaryVersion || CODEGRAPH_VERSION;
     setBuildMeta(ctx.db, {
         engine: ctx.engineName,
-        engine_version: ctx.engineVersion || '',
-        codegraph_version: ctx.engineVersion || CODEGRAPH_VERSION,
+        engine_version: nativeVersionForMeta,
+        codegraph_version: nativeVersionForMeta,
         schema_version: String(ctx.schemaVersion),
         built_at: new Date().toISOString(),
     });
@@ -578,41 +611,153 @@ async function tryNativeOrchestrator(ctx) {
     // stale native binaries). WASM handles those — backfill via WASM so both
     // engines process the same file set (#967).
     //
-    // Only runs on full builds: incremental builds only touch changed files,
-    // which are parsed through parseFilesAuto (which has its own per-file
-    // backfill), so a full filesystem scan here would be wasted work.
-    if (result.isFullBuild) {
-        await backfillNativeDroppedFiles(ctx);
+    // Detect the gap once (fs walk + 2 DB queries, ~20–30ms) and use it for
+    // both gating and the backfill itself. On dirty incrementals/full builds
+    // the orchestrator signals trigger backfill, so the walk happens once
+    // (instead of redundantly inside backfill). On quiet incrementals we
+    // still pay the walk so we can detect brand-new files in dropped-language
+    // extensions — a gap that the orchestrator's `detect_removed_files`
+    // filter (#1070) leaves open (#1083, #1091). The pre-check is cheap
+    // because the expensive part (WASM re-parse of the missing set) is
+    // gated below.
+    const removedCount = result.removedCount ?? 0;
+    const changedCount = result.changedCount ?? 0;
+    const gap = detectDroppedLanguageGap(ctx);
+    if (result.isFullBuild ||
+        removedCount > 0 ||
+        changedCount > 0 ||
+        gap.missingAbs.length > 0 ||
+        gap.staleRel.length > 0) {
+        await backfillNativeDroppedFiles(ctx, gap);
     }
     closeDbPair({ db: ctx.db, nativeDb: ctx.nativeDb });
     return formatNativeTimingResult(p, structurePatchMs, analysisTiming);
 }
 /**
- * Backfill files that the native orchestrator silently dropped during parse.
- * Falls back to WASM + inserts file/symbol nodes so engine counts match (#967).
+ * Compute the WASM-only files present in the DB but missing from disk (#1073).
+ *
+ * Returns relative paths that:
+ *   - appear in `existingNodes` or `existingHashes` (in DB),
+ *   - are absent from `expected` (not on disk),
+ *   - have an extension installed for WASM, AND
+ *   - have an extension NOT covered by `nativeSupported` — Rust's
+ *     `purge_changed_files` handles deletion for natively-supported extensions
+ *     via its own `detect_removed_files`, so the caller must not double-purge.
+ *
+ * Extensions are lowercased before lookup to match the registry and Rust's
+ * `LanguageKind::from_extension` (which normalises case for the languages
+ * where both cases are conventional, e.g. R's `.r` / `.R`).
+ *
+ * DB paths are forced to forward slashes before comparison with `expected`
+ * (which is always normalised). The on-disk invariant is that DB rows are
+ * written with forward slashes, but a stale row written by older code on
+ * Windows could carry back-slashes — normalising here makes the comparison
+ * platform-safe and prevents false-positive purges of live rows. We replace
+ * `\\` explicitly (rather than calling `normalizePath`, which only touches
+ * `path.sep`) so the defence works when running on POSIX against a DB that
+ * was migrated from Windows.
+ *
+ * Exported for unit testing.
  */
-async function backfillNativeDroppedFiles(ctx) {
-    // Needs a real better-sqlite3 connection for INSERT.
-    if (ctx.nativeFirstProxy) {
-        closeNativeDb(ctx, 'pre-parity-backfill');
-        ctx.db = openDb(ctx.dbPath);
-        ctx.nativeFirstProxy = false;
+export function computeWasmOnlyStaleFiles(input) {
+    const { existingNodes, existingHashes, expected, installedExts, nativeSupported } = input;
+    const stale = [];
+    const seen = new Set();
+    const consider = (rawRel) => {
+        const rel = rawRel.replace(/\\/g, '/');
+        if (expected.has(rel) || seen.has(rel))
+            return;
+        const ext = path.extname(rel).toLowerCase();
+        if (nativeSupported.has(ext))
+            return;
+        if (!installedExts.has(ext))
+            return;
+        seen.add(rel);
+        // Push the ORIGINAL raw path (not the normalised form) so the eventual
+        // `DELETE FROM nodes WHERE file = ?` predicate in `purgeFilesData`
+        // matches the actual stored row. The dedup `seen` set keeps the
+        // normalised form so a file written once with `\` and once with `/`
+        // is still treated as one entry — but the value the SQL sees has to
+        // be byte-identical to what's on disk in the DB.
+        stale.push(rawRel);
+    };
+    for (const rel of existingNodes)
+        consider(rel);
+    for (const rel of existingHashes)
+        consider(rel);
+    return stale;
+}
+/**
+ * Group relative paths by their lowercased extension. Shape matches the bucket
+ * type that `formatDropExtensionSummary` consumes, so callers can render a
+ * log-friendly per-extension summary without going through `classifyNativeDrops`
+ * when the reason is already known (e.g. the stale-purge path where every path
+ * is guaranteed `unsupported-by-native`).
+ */
+function groupByExtension(relPaths) {
+    const buckets = new Map();
+    for (const rel of relPaths) {
+        const ext = path.extname(rel).toLowerCase();
+        let list = buckets.get(ext);
+        if (!list) {
+            list = [];
+            buckets.set(ext, list);
+        }
+        list.push(rel);
     }
+    return buckets;
+}
+/**
+ * Detect files the native orchestrator silently dropped.
+ *
+ * Walks the filesystem and compares against `nodes` + `file_hashes`. A file
+ * is "missing" if it's absent from EITHER table — both must be present for
+ * the fast-skip pre-flight (#1054) to work, and the two can diverge (e.g.
+ * legacy DBs where `nodes` was populated but `file_hashes` was not).
+ *
+ * Restricted to files with an installed WASM grammar; extensions in
+ * `LANGUAGE_REGISTRY` without a shipped grammar (e.g. groovy on minimal
+ * installs) can't be parsed by either engine, so they're not a native
+ * regression — excluding them keeps the warn count in
+ * `backfillNativeDroppedFiles` meaningful.
+ *
+ * Also detects WASM-only files deleted from disk (#1073). Rust's
+ * `detect_removed_files` filter (#1070) skips files outside its supported
+ * extensions, so deletions of WASM-only languages don't reach the native
+ * purge path; the rest of the backfill only inserts rows, so without this
+ * step stale `nodes`/`file_hashes` rows would linger across incremental
+ * rebuilds until the next full rebuild.
+ *
+ * Cheap (no DB handoff, no parsing): used both to gate the backfill call
+ * and as its working set. NativeDbProxy supports `.prepare().all()`, so
+ * this works whether `ctx.db` is a proxy or a real better-sqlite3
+ * connection — letting us skip the close-native / reopen-better-sqlite3
+ * cost when there's nothing to backfill.
+ */
+function detectDroppedLanguageGap(ctx) {
     const collected = collectFilesUtil(ctx.rootDir, [], ctx.config, new Set());
     const expected = new Set(collected.files.map((f) => normalizePath(path.relative(ctx.rootDir, f))));
-    const existingRows = ctx.db
+    const existingNodeRows = ctx.db
         .prepare("SELECT DISTINCT file FROM nodes WHERE kind = 'file'")
         .all();
-    const existing = new Set(existingRows.map((r) => r.file));
-    // Restrict backfill to files with an installed WASM grammar. Extensions in
-    // LANGUAGE_REGISTRY without a shipped grammar file (e.g. groovy, erlang on
-    // minimal installs) can't be parsed by either engine, so they're not a
-    // native regression — excluding them keeps the warn count meaningful.
+    const existingNodes = new Set(existingNodeRows.map((r) => r.file));
+    let existingHashes = new Set();
+    try {
+        const existingHashRows = ctx.db
+            .prepare('SELECT DISTINCT file FROM file_hashes')
+            .all();
+        existingHashes = new Set(existingHashRows.map((r) => r.file));
+    }
+    catch (e) {
+        // file_hashes table may not exist on legacy DBs; treat as fully missing
+        // so the backfill writes rows on the upsert path below.
+        debug(`detectDroppedLanguageGap: file_hashes read failed (table may not exist): ${toErrorMessage(e)}`);
+    }
     const installedExts = getInstalledWasmExtensions();
     const missingRel = [];
     const missingAbs = [];
     for (const rel of expected) {
-        if (existing.has(rel))
+        if (existingNodes.has(rel) && existingHashes.has(rel))
             continue;
         const ext = path.extname(rel).toLowerCase();
         if (!installedExts.has(ext))
@@ -620,6 +765,51 @@ async function backfillNativeDroppedFiles(ctx) {
         missingRel.push(rel);
         missingAbs.push(path.join(ctx.rootDir, rel));
     }
+    const staleRel = computeWasmOnlyStaleFiles({
+        existingNodes,
+        existingHashes,
+        expected,
+        installedExts,
+        nativeSupported: NATIVE_SUPPORTED_EXTENSIONS,
+    });
+    return { missingRel, missingAbs, staleRel };
+}
+/**
+ * Backfill files that the native orchestrator silently dropped during parse.
+ * Falls back to WASM + inserts file/symbol nodes so engine counts match (#967).
+ *
+ * Also purges stale rows for WASM-only files deleted from disk (#1073), which
+ * Rust's `detect_removed_files` filter (#1070) skips.
+ *
+ * Accepts a pre-computed `gap` from `detectDroppedLanguageGap` so the caller
+ * can use the same scan for both gating and the actual backfill — avoiding
+ * a redundant fs walk when the orchestrator's signals already triggered.
+ */
+async function backfillNativeDroppedFiles(ctx, gap) {
+    const { missingRel, missingAbs, staleRel } = gap;
+    if (missingAbs.length === 0 && staleRel.length === 0)
+        return;
+    // Now that we know there's work to do, hand off to better-sqlite3 (needed
+    // for the INSERT path below).
+    if (ctx.nativeFirstProxy) {
+        closeNativeDb(ctx, 'pre-parity-backfill');
+        ctx.db = openDb(ctx.dbPath);
+        ctx.nativeFirstProxy = false;
+    }
+    const dbConn = ctx.db;
+    // Purge WASM-only files that were deleted from disk (#1073). Rust's
+    // detect_removed_files skips them and the insert path below never visits
+    // them, so without this their rows would persist across rebuilds until the
+    // next full rebuild reset the DB.
+    if (staleRel.length > 0) {
+        // `computeWasmOnlyStaleFiles` guarantees every path here has an extension
+        // outside NATIVE_SUPPORTED_EXTENSIONS, so `classifyNativeDrops` would
+        // always bucket 100% into `unsupported-by-native`. Build the extension
+        // summary directly to avoid a redundant classification pass.
+        const staleByExt = groupByExtension(staleRel);
+        info(`Detected ${staleRel.length} deleted WASM-only file(s) the native orchestrator skipped; purging stale rows: ${formatDropExtensionSummary(staleByExt)}`);
+        purgeFilesData(dbConn, staleRel);
+    }
     if (missingAbs.length === 0)
         return;
     // Classify drops so users see per-extension reasons instead of just a count
@@ -633,7 +823,7 @@ async function backfillNativeDroppedFiles(ctx) {
     if (totals['native-extractor-failure'] > 0) {
         warn(`Native orchestrator dropped ${totals['native-extractor-failure']} file(s) in natively-supported languages — likely a Rust extractor bug. Backfilling via WASM: ${formatDropExtensionSummary(byReason['native-extractor-failure'])}`);
     }
-    const wasmResults = await parseFilesAuto(missingAbs, ctx.rootDir, { engine: 'wasm' });
+    const wasmResults = await parseFilesWasmForBackfill(missingAbs, ctx.rootDir);
     const rows = [];
     const exportKeys = [];
     for (const [relPath, symbols] of wasmResults) {
@@ -665,7 +855,7 @@ async function backfillNativeDroppedFiles(ctx) {
             exportKeys.push([exp.name, exp.kind, relPath, exp.line]);
         }
     }
-    const db = ctx.db;
+    const db = dbConn;
     batchInsertNodes(db, rows);
     // Mark exported symbols in batches — mirrors insertDefinitionsAndExports.
     if (exportKeys.length > 0) {
@@ -688,6 +878,67 @@ async function backfillNativeDroppedFiles(ctx) {
             updateStmt.run(...vals);
         }
     }
+    // Persist file_hashes rows for every backfilled file. The Rust orchestrator
+    // only hashes files it parsed itself, so without this step files in
+    // optional-language extensions (e.g. .clj when no Rust extractor exists)
+    // would be missing from `file_hashes` — permanently breaking the JS-side
+    // fast-skip pre-flight (#1054), which rejects on `collected file missing
+    // from file_hashes` and forces every no-op rebuild back through the full
+    // ~2s native pipeline (#1068).
+    //
+    // Iterates `missingRel` (every collected file the Rust orchestrator
+    // dropped), not `wasmResults`, so files that produced zero symbols still
+    // get a row.
+    try {
+        const upsertHash = db.prepare('INSERT OR REPLACE INTO file_hashes (file, hash, mtime, size) VALUES (?, ?, ?, ?)');
+        const writeHashes = db.transaction(() => {
+            for (let i = 0; i < missingRel.length; i++) {
+                const relPath = missingRel[i];
+                const absPath = missingAbs[i];
+                if (!relPath || !absPath)
+                    continue;
+                let code;
+                try {
+                    code = readFileSafe(absPath);
+                }
+                catch (e) {
+                    debug(`backfillNativeDroppedFiles: read failed for ${relPath}: ${toErrorMessage(e)}`);
+                    continue;
+                }
+                if (code === null)
+                    continue;
+                const stat = fileStat(absPath);
+                const mtime = stat ? stat.mtime : 0;
+                const size = stat ? stat.size : 0;
+                upsertHash.run(relPath, fileHash(code), mtime, size);
+            }
+        });
+        writeHashes();
+    }
+    catch (e) {
+        debug(`backfillNativeDroppedFiles: file_hashes write failed (table may not exist): ${toErrorMessage(e)}`);
+    }
+    // Free WASM parse trees from the inline backfill path (#1058).
+    // `parseFilesWasmInline` sets `symbols._tree` (a live web-tree-sitter Tree
+    // backed by WASM linear memory) on every result, but these symbols are
+    // consumed locally for DB row construction and never added to
+    // `ctx.allSymbols`, so the finalize-stage `releaseWasmTrees` sweep never
+    // sees them. Without this, trees leak WASM memory until process exit —
+    // bounded per run but cumulative across in-process integration tests.
+    // Mirrors the cleanup discipline established for #931.
+    for (const [, symbols] of wasmResults) {
+        const tree = symbols._tree;
+        if (tree && typeof tree.delete === 'function') {
+            try {
+                tree.delete();
+            }
+            catch {
+                /* ignore cleanup errors */
+            }
+        }
+        symbols._tree = undefined;
+        symbols._langId = undefined;
+    }
 }
 // ── Pipeline stages execution ───────────────────────────────────────────
 async function runPipelineStages(ctx) {
@@ -795,6 +1046,61 @@ export async function buildGraph(rootDir, opts = {}) {
     ctx.rootDir = rootDir;
     try {
         setupPipeline(ctx);
+        // ── JS-side fast-skip for native incremental (#1054) ──────────────
+        // The Rust orchestrator's internal early-exit fires reliably locally
+        // but not in CI, where every no-op rebuild was paying the full ~2s
+        // pipeline cost. A read-only mtime+size check here matches WASM's
+        // ~20ms early-exit and skips the orchestrator entirely when no
+        // source files have changed. Tier-2 hashing is left to the native
+        // side: any mismatch falls through and lets Rust's detect_changes
+        // remain the source of truth.
+        //
+        // Diagnostic logging gated by CODEGRAPH_FAST_SKIP_DIAG (#1066) — when
+        // any of the call-site guards short-circuit (forceFullRebuild,
+        // engineName, scope, etc.) we log the reason so the bench gate run
+        // produces observable output even if `detectNoChanges` is never
+        // entered.
+        const fastSkipDiag = process.env.CODEGRAPH_FAST_SKIP_DIAG === '1';
+        if (fastSkipDiag) {
+            const reasons = [];
+            if (!ctx.nativeAvailable)
+                reasons.push('nativeAvailable=false');
+            if (ctx.engineName !== 'native')
+                reasons.push(`engineName=${ctx.engineName}`);
+            if (!ctx.incremental)
+                reasons.push('incremental=false');
+            if (ctx.forceFullRebuild)
+                reasons.push('forceFullRebuild=true');
+            if (ctx.opts.scope)
+                reasons.push('scope=set');
+            if (reasons.length > 0) {
+                info(`[fast-skip] false: pre-flight gate skipped — ${reasons.join(', ')}`);
+            }
+        }
+        if (ctx.nativeAvailable &&
+            ctx.engineName === 'native' &&
+            ctx.incremental &&
+            !ctx.forceFullRebuild &&
+            !ctx.opts.scope) {
+            try {
+                await collectFiles(ctx);
+                if (detectNoChanges(ctx.db, ctx.allFiles, ctx.rootDir, ctx.opts)) {
+                    info('No changes detected. Graph is up to date.');
+                    writeJournalHeader(ctx.rootDir, Date.now());
+                    closeDb(ctx.db);
+                    return;
+                }
+            }
+            catch (err) {
+                // Pre-flight is best-effort — any failure falls through to the
+                // orchestrator, which performs its own complete detection.
+                // Reset ctx.allFiles so runPipelineStages re-collects under its own
+                // engine state if we ended up partially populated before throwing.
+                ctx.allFiles = undefined;
+                ctx.discoveredDirs = undefined;
+                debug(`native fast-skip pre-flight failed: ${toErrorMessage(err)}`);
+            }
+        }
         // ── Rust orchestrator fast path (#695) ────────────────────────────
         // When available, run the entire build pipeline in Rust with zero
         // napi crossings (eliminates WAL dual-connection dance). Falls back