@optave/codegraph 3.9.6 → 3.11.0

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

@@ -9,11 +9,13 @@ import path from 'node:path';
 import { performance } from 'node:perf_hooks';
 import {
   acquireAdvisoryLock,
+  closeDb,
   closeDbPair,
   getBuildMeta,
   initSchema,
   MIGRATIONS,
   openDb,
+  purgeFilesData,
   releaseAdvisoryLock,
   setBuildMeta,
 } from '../../../db/index.js';
@@ -37,17 +39,26 @@ import {
   formatDropExtensionSummary,
   getActiveEngine,
   getInstalledWasmExtensions,
-  parseFilesAuto,
+  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';
@@ -67,9 +78,14 @@ function initializeEngine(ctx: PipelineContext): void {
     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 as 'native' | 'wasm';
   ctx.engineVersion = engineVersion;
+  ctx.nativeBinaryVersion = nativeBinaryVersion;
   info(`Using ${engineName} engine${engineVersion ? ` (v${engineVersion})` : ''}`);
 }
 
@@ -96,13 +112,15 @@ function checkEngineSchemaMismatch(ctx: PipelineContext): void {
     );
     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.
+  // 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.engineVersion ? ctx.engineVersion : CODEGRAPH_VERSION;
+    ctx.engineName === 'native' && ctx.nativeBinaryVersion
+      ? ctx.nativeBinaryVersion
+      : CODEGRAPH_VERSION;
   const prevVersion = meta('codegraph_version');
   if (prevVersion && prevVersion !== effectiveVersion) {
     info(
@@ -149,7 +167,9 @@ 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.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';
@@ -167,6 +187,16 @@ function setupPipeline(ctx: PipelineContext): void {
   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;
 
@@ -642,6 +672,15 @@ async function tryNativeOrchestrator(
 
   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';
   }
@@ -656,16 +695,24 @@ async function tryNativeOrchestrator(
   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(),
   });
@@ -729,53 +776,253 @@ async function tryNativeOrchestrator(
   // 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);
 }
 
+/** Files the native orchestrator silently dropped — the working set for backfill. */
+interface DroppedLanguageGap {
+  /** Relative paths (normalized) of files missing from `nodes` or `file_hashes`. */
+  missingRel: string[];
+  /** Absolute paths, aligned by index with `missingRel`. */
+  missingAbs: string[];
+  /**
+   * Relative paths of WASM-only files present in DB but absent from disk (#1073).
+   * Rust's `detect_removed_files` filter (#1070) skips these, so the JS-side
+   * backfill must purge them. Always disjoint from `missingRel`.
+   */
+  staleRel: string[];
+}
+
 /**
- * Backfill files that the native orchestrator silently dropped during parse.
- * Falls back to WASM + inserts file/symbol nodes so engine counts match (#967).
+ * Inputs to {@link computeWasmOnlyStaleFiles}. Sets are passed in so the helper
+ * is pure and unit-testable independently of `getInstalledWasmExtensions` and
+ * the `NATIVE_SUPPORTED_EXTENSIONS` global state.
  */
-async function backfillNativeDroppedFiles(ctx: PipelineContext): Promise<void> {
-  // 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 interface WasmOnlyStaleFilesInput {
+  /** Distinct `file` values from the `nodes` table. */
+  existingNodes: ReadonlySet<string>;
+  /** Distinct `file` values from the `file_hashes` table. */
+  existingHashes: ReadonlySet<string>;
+  /** Relative paths currently on disk (from `collectFilesUtil`). */
+  expected: ReadonlySet<string>;
+  /** Lowercased extensions whose WASM grammar is installed. */
+  installedExts: ReadonlySet<string>;
+  /** Extensions covered by the Rust addon — Rust owns deletion for these. */
+  nativeSupported: ReadonlySet<string>;
+}
+
+/**
+ * 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.
+ */
+export function computeWasmOnlyStaleFiles(input: WasmOnlyStaleFilesInput): string[] {
+  const { existingNodes, existingHashes, expected, installedExts, nativeSupported } = input;
+  const stale: string[] = [];
+  const seen = new Set<string>();
+  const consider = (rawRel: string): void => {
+    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: Iterable<string>): Map<string, string[]> {
+  const buckets = new Map<string, string[]>();
+  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: PipelineContext): DroppedLanguageGap {
   const collected = collectFilesUtil(ctx.rootDir, [], ctx.config, new Set<string>());
   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() as Array<{ file: string }>;
-  const existing = new Set(existingRows.map((r) => r.file));
+  const existingNodes = new Set(existingNodeRows.map((r) => r.file));
+
+  let existingHashes = new Set<string>();
+  try {
+    const existingHashRows = ctx.db
+      .prepare('SELECT DISTINCT file FROM file_hashes')
+      .all() as Array<{ file: string }>;
+    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)}`,
+    );
+  }
 
-  // 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 installedExts = getInstalledWasmExtensions();
   const missingRel: string[] = [];
   const missingAbs: string[] = [];
   for (const rel of expected) {
-    if (existing.has(rel)) continue;
+    if (existingNodes.has(rel) && existingHashes.has(rel)) continue;
     const ext = path.extname(rel).toLowerCase();
     if (!installedExts.has(ext)) continue;
     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: PipelineContext,
+  gap: DroppedLanguageGap,
+): Promise<void> {
+  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 as unknown as BetterSqlite3Database;
+
+  // 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
@@ -793,7 +1040,7 @@ async function backfillNativeDroppedFiles(ctx: PipelineContext): Promise<void> {
       `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: unknown[][] = [];
   const exportKeys: unknown[][] = [];
@@ -826,7 +1073,7 @@ async function backfillNativeDroppedFiles(ctx: PipelineContext): Promise<void> {
       exportKeys.push([exp.name, exp.kind, relPath, exp.line]);
     }
   }
-  const db = ctx.db as unknown as BetterSqlite3Database;
+  const db = dbConn;
   batchInsertNodes(db, rows);
 
   // Mark exported symbols in batches — mirrors insertDefinitionsAndExports.
@@ -853,6 +1100,68 @@ async function backfillNativeDroppedFiles(ctx: PipelineContext): Promise<void> {
       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: string | null;
+        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 as { _tree?: { delete?: () => void } })._tree;
+    if (tree && typeof tree.delete === 'function') {
+      try {
+        tree.delete();
+      } catch {
+        /* ignore cleanup errors */
+      }
+    }
+    (symbols as { _tree?: unknown; _langId?: unknown })._tree = undefined;
+    (symbols as { _tree?: unknown; _langId?: unknown })._langId = undefined;
+  }
 }
 
 // ── Pipeline stages execution ───────────────────────────────────────────
@@ -979,6 +1288,60 @@ export async function buildGraph(
   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: string[] = [];
+      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 as Record<string, unknown>).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 as Record<string, unknown>).scope
+    ) {
+      try {
+        await collectFiles(ctx);
+        if (
+          detectNoChanges(ctx.db, ctx.allFiles, ctx.rootDir, ctx.opts as Record<string, unknown>)
+        ) {
+          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 as unknown as string[];
+        ctx.discoveredDirs = undefined as unknown as Set<string>;
+        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

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

@@ -770,9 +770,11 @@ function reconnectReverseDepEdges(ctx: PipelineContext): void {
  * their import targets. Falls back to loading ALL nodes for full builds or
  * larger incremental changes.
  */
+const NODE_KIND_FILTER_SQL = `kind IN ('function','method','class','interface','struct','type','module','enum','trait','record','constant')`;
+
 function loadNodes(ctx: PipelineContext): { rows: QueryNodeRow[]; scoped: boolean } {
   const { db, fileSymbols, isFullBuild, batchResolved } = ctx;
-  const nodeKindFilter = `kind IN ('function','method','class','interface','struct','type','module','enum','trait','record','constant')`;
+  const nodeKindFilter = NODE_KIND_FILTER_SQL;
 
   // Gate: only scope for small incremental on large codebases
   if (!isFullBuild && fileSymbols.size <= ctx.config.build.smallFilesThreshold) {
@@ -816,8 +818,13 @@ function loadNodes(ctx: PipelineContext): { rows: QueryNodeRow[]; scoped: boolea
 function addLazyFallback(ctx: PipelineContext, scopedLoad: boolean): void {
   if (!scopedLoad) return;
   const { db } = ctx;
+  // Match the upfront kind filter exactly. Using `kind != 'file'` here lets
+  // parameters, properties, and other non-definition kinds leak into call
+  // resolution, producing bogus call edges like `parser.ts → <a parameter
+  // with the same name>` (#1174 follow-up). Calls only ever target the
+  // definition kinds, so the fallback's filter must agree with `loadNodes`.
   const fallbackStmt = db.prepare(
-    `SELECT id, name, kind, file, line FROM nodes WHERE name = ? AND kind != 'file'`,
+    `SELECT id, name, kind, file, line FROM nodes WHERE name = ? AND ${NODE_KIND_FILTER_SQL}`,
   );
   const originalGet = ctx.nodesByName.get.bind(ctx.nodesByName);
   ctx.nodesByName.get = (name: string) => {

package/src/domain/graph/builder/stages/collect-files.ts

@@ -100,6 +100,15 @@ function tryFastCollect(
 export async function collectFiles(ctx: PipelineContext): Promise<void> {
   const { rootDir, config, opts } = ctx;
 
+  // Skip when the JS-side fast-skip pre-flight (#1054) already populated the
+  // file list and changes were detected, causing fallthrough to the native
+  // orchestrator and then to runPipelineStages. Avoids redoing the filesystem
+  // walk on the non-skip path (~8ms on 473 files). On pre-flight failure the
+  // caller resets ctx.allFiles so this guard correctly falls through.
+  if (!opts.scope && ctx.allFiles?.length && ctx.discoveredDirs?.size) {
+    return;
+  }
+
   if (opts.scope) {
     // Scoped rebuild: rebuild only specified files.
     //