@optave/codegraph 3.4.1 → 3.6.0

package/src/domain/analysis/query-helpers.ts

@@ -0,0 +1,35 @@
+import { openReadonlyOrFail } from '../../db/index.js';
+import { loadConfig } from '../../infrastructure/config.js';
+import type { BetterSqlite3Database, CodegraphConfig } from '../../types.js';
+
+/**
+ * Open a readonly DB connection, run `fn`, and close the DB on completion.
+ * Eliminates the duplicated `openReadonlyOrFail` + `try/finally/db.close()` pattern
+ * that appears in every analysis query function.
+ */
+export function withReadonlyDb<T>(
+  customDbPath: string | undefined,
+  fn: (db: BetterSqlite3Database) => T,
+): T {
+  const db = openReadonlyOrFail(customDbPath);
+  try {
+    return fn(db);
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * Resolve common analysis options into a normalized form.
+ * Shared across fn-impact, context, dependencies, and exports modules.
+ */
+export function resolveAnalysisOpts(opts: { noTests?: boolean; config?: CodegraphConfig }): {
+  noTests: boolean;
+  config: CodegraphConfig;
+  displayOpts: Record<string, unknown>;
+} {
+  const noTests = opts.noTests || false;
+  const config = opts.config || loadConfig();
+  const displayOpts = config.display || {};
+  return { noTests, config, displayOpts };
+}

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

@@ -12,6 +12,7 @@ import type {
   ExtractorOutput,
   FileToParse,
   MetadataUpdate,
+  NativeDatabase,
   NodeRow,
   ParseChange,
   PathAliases,
@@ -31,6 +32,7 @@ export class PipelineContext {
   incremental!: boolean;
   forceFullRebuild: boolean = false;
   schemaVersion!: number;
+  nativeDb?: NativeDatabase;
 
   // ── File collection (set by collectFiles stage) ────────────────────
   allFiles!: string[];

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

@@ -47,6 +47,17 @@ export const BUILTIN_RECEIVERS: Set<string> = new Set([
   'require',
 ]);
 
+/** Check if a directory entry should be skipped (ignored dirs, dotfiles). */
+function shouldSkipEntry(entry: fs.Dirent, extraIgnore: Set<string> | null): boolean {
+  if (entry.name.startsWith('.') && entry.name !== '.') {
+    if (IGNORE_DIRS.has(entry.name)) return true;
+    if (entry.isDirectory()) return true;
+  }
+  if (IGNORE_DIRS.has(entry.name)) return true;
+  if (extraIgnore?.has(entry.name)) return true;
+  return false;
+}
+
 /**
  * Recursively collect all source files under `dir`.
  * When `directories` is a Set, also tracks which directories contain files.
@@ -100,12 +111,7 @@ export function collectFiles(
   }
 
   for (const entry of entries) {
-    if (entry.name.startsWith('.') && entry.name !== '.') {
-      if (IGNORE_DIRS.has(entry.name)) continue;
-      if (entry.isDirectory()) continue;
-    }
-    if (IGNORE_DIRS.has(entry.name)) continue;
-    if (extraIgnore?.has(entry.name)) continue;
+    if (shouldSkipEntry(entry, extraIgnore)) continue;
 
     const full = path.join(dir, entry.name);
     if (entry.isDirectory()) {

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

@@ -10,7 +10,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { bulkNodeIdsByFile } from '../../../db/index.js';
-import { warn } from '../../../infrastructure/logger.js';
+import { debug, warn } from '../../../infrastructure/logger.js';
 import { normalizePath } from '../../../shared/constants.js';
 import type {
   BetterSqlite3Database,
@@ -154,7 +154,8 @@ async function parseReverseDep(
   let code: string;
   try {
     code = readFileSafe(absPath);
-  } catch {
+  } catch (e: unknown) {
+    debug(`parseReverseDep: cannot read ${absPath}: ${e instanceof Error ? e.message : String(e)}`);
     return null;
   }
 

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

@@ -6,9 +6,10 @@
  */
 import path from 'node:path';
 import { performance } from 'node:perf_hooks';
-import { closeDb, getBuildMeta, initSchema, MIGRATIONS, openDb } from '../../../db/index.js';
+import { closeDbPair, getBuildMeta, initSchema, MIGRATIONS, openDb } from '../../../db/index.js';
 import { detectWorkspaces, loadConfig } from '../../../infrastructure/config.js';
 import { info, warn } from '../../../infrastructure/logger.js';
+import { loadNative } from '../../../infrastructure/native.js';
 import { CODEGRAPH_VERSION } from '../../../shared/version.js';
 import type { BuildGraphOpts, BuildResult } from '../../../types.js';
 import { getActiveEngine } from '../../parser.js';
@@ -33,6 +34,19 @@ function initializeEngine(ctx: PipelineContext): void {
     engine: ctx.opts.engine || 'auto',
     dataflow: ctx.opts.dataflow !== false,
     ast: ctx.opts.ast !== false,
+    nativeDb: ctx.nativeDb,
+    // WAL checkpoint callbacks for dual-connection WAL guard (#696).
+    // 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. Features
+    // return early on native success and never read native-written WAL data
+    // through the JS connection, so a post-write checkpoint is unnecessary.
+    suspendJsDb: ctx.nativeDb
+      ? () => {
+          ctx.db.pragma('wal_checkpoint(TRUNCATE)');
+        }
+      : undefined,
+    resumeJsDb: ctx.nativeDb ? () => {} : undefined,
   };
   const { name: engineName, version: engineVersion } = getActiveEngine(ctx.engineOpts);
   ctx.engineName = engineName as 'native' | 'wasm';
@@ -46,19 +60,25 @@ function checkEngineSchemaMismatch(ctx: PipelineContext): void {
   ctx.forceFullRebuild = false;
   if (!ctx.incremental) return;
 
-  const prevEngine = getBuildMeta(ctx.db, 'engine');
+  // Route metadata reads through NativeDatabase only when using the native engine,
+  // to avoid dual-SQLite WAL conflicts (rusqlite + better-sqlite3 on same file).
+  const useNativeDb = ctx.engineName === 'native' && !!ctx.nativeDb;
+  const meta = (key: string): string | null =>
+    useNativeDb ? ctx.nativeDb!.getBuildMeta(key) : getBuildMeta(ctx.db, key);
+
+  const prevEngine = meta('engine');
   if (prevEngine && prevEngine !== ctx.engineName) {
     info(`Engine changed (${prevEngine} → ${ctx.engineName}), promoting to full rebuild.`);
     ctx.forceFullRebuild = true;
   }
-  const prevSchema = getBuildMeta(ctx.db, 'schema_version');
+  const prevSchema = meta('schema_version');
   if (prevSchema && Number(prevSchema) !== ctx.schemaVersion) {
     info(
       `Schema version changed (${prevSchema} → ${ctx.schemaVersion}), promoting to full rebuild.`,
     );
     ctx.forceFullRebuild = true;
   }
-  const prevVersion = getBuildMeta(ctx.db, 'codegraph_version');
+  const prevVersion = meta('codegraph_version');
   if (prevVersion && prevVersion !== CODEGRAPH_VERSION) {
     info(
       `Codegraph version changed (${prevVersion} → ${CODEGRAPH_VERSION}), promoting to full rebuild.`,
@@ -91,7 +111,25 @@ function setupPipeline(ctx: PipelineContext): void {
   ctx.rootDir = path.resolve(ctx.rootDir);
   ctx.dbPath = path.join(ctx.rootDir, '.codegraph', 'graph.db');
   ctx.db = openDb(ctx.dbPath);
-  initSchema(ctx.db);
+
+  // 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.
+  const native = loadNative();
+  if (native?.NativeDatabase) {
+    try {
+      ctx.nativeDb = native.NativeDatabase.openReadWrite(ctx.dbPath);
+      ctx.nativeDb.initSchema();
+    } catch (err) {
+      warn(`NativeDatabase init failed, falling back to JS: ${(err as Error).message}`);
+      ctx.nativeDb = undefined;
+    }
+    // Always run JS initSchema so better-sqlite3 sees the schema —
+    // nativeDb is closed during pipeline stages and reopened for analyses.
+    initSchema(ctx.db);
+  } else {
+    initSchema(ctx.db);
+  }
 
   ctx.config = loadConfig(ctx.rootDir);
   ctx.incremental =
@@ -134,6 +172,26 @@ function formatTimingResult(ctx: PipelineContext): BuildResult {
 // ── Pipeline stages execution ───────────────────────────────────────────
 
 async function runPipelineStages(ctx: PipelineContext): Promise<void> {
+  // Prevent dual-connection WAL corruption during pipeline stages: when both
+  // better-sqlite3 (ctx.db) and rusqlite (ctx.nativeDb) are open to the same
+  // WAL-mode file, native writes corrupt the DB. Close nativeDb so stages
+  // use JS fallback paths. Reopened before runAnalyses for feature modules
+  // that use suspendJsDb/resumeJsDb WAL checkpoint pattern (#696).
+  const hadNativeDb = !!ctx.nativeDb;
+  if (ctx.db && ctx.nativeDb) {
+    try {
+      ctx.nativeDb.close();
+    } catch {
+      /* ignore close errors */
+    }
+    ctx.nativeDb = undefined;
+    // Also clear stale reference in engineOpts to prevent stages from
+    // calling methods on the closed NativeDatabase.
+    if (ctx.engineOpts?.nativeDb) {
+      ctx.engineOpts.nativeDb = undefined;
+    }
+  }
+
   await collectFiles(ctx);
   await detectChanges(ctx);
 
@@ -144,7 +202,39 @@ async function runPipelineStages(ctx: PipelineContext): Promise<void> {
   await resolveImports(ctx);
   await buildEdges(ctx);
   await buildStructure(ctx);
+
+  // Reopen nativeDb for feature modules (ast, cfg, complexity, dataflow)
+  // which use suspendJsDb/resumeJsDb WAL checkpoint before native writes.
+  if (hadNativeDb) {
+    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;
+        }
+      }
+    }
+  }
+
   await runAnalyses(ctx);
+
+  // Close nativeDb after analyses — finalize uses JS paths for setBuildMeta
+  // and closeDbPair handles cleanup. Avoids dual-connection during finalize.
+  if (ctx.nativeDb) {
+    try {
+      ctx.nativeDb.close();
+    } catch {
+      /* ignore close errors */
+    }
+    ctx.nativeDb = undefined;
+  }
+
   await finalize(ctx);
 }
 
@@ -168,7 +258,9 @@ export async function buildGraph(
     setupPipeline(ctx);
     await runPipelineStages(ctx);
   } catch (err) {
-    if (!ctx.earlyExit && ctx.db) closeDb(ctx.db);
+    if (!ctx.earlyExit && ctx.db) {
+      closeDbPair({ db: ctx.db, nativeDb: ctx.nativeDb });
+    }
     throw err;
   }
 

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

@@ -7,6 +7,7 @@
 import path from 'node:path';
 import { performance } from 'node:perf_hooks';
 import { getNodeId } from '../../../../db/index.js';
+import { debug } from '../../../../infrastructure/logger.js';
 import { loadNative } from '../../../../infrastructure/native.js';
 import type {
   BetterSqlite3Database,
@@ -21,6 +22,7 @@ import type {
 import { computeConfidence } from '../../resolve.js';
 import type { PipelineContext } from '../context.js';
 import { BUILTIN_RECEIVERS, batchInsertEdges } from '../helpers.js';
+
 import { getResolved, isBarrelFile, resolveBarrelExport } from './resolve-imports.js';
 
 // ── Local types ──────────────────────────────────────────────────────────
@@ -60,12 +62,6 @@ interface NativeEdge {
   dynamic: number;
 }
 
-/** TypeMap entry used in receiver supplement (normalized from native format). */
-interface NormalizedTypeEntry {
-  type: string;
-  confidence: number;
-}
-
 // ── Node lookup setup ───────────────────────────────────────────────────
 
 function makeGetNodeIdStmt(db: BetterSqlite3Database): NodeIdStmt {
@@ -209,14 +205,6 @@ function buildCallEdgesNative(
   for (const e of nativeEdges) {
     allEdgeRows.push([e.sourceId, e.targetId, e.kind, e.confidence, e.dynamic]);
   }
-
-  // Older native binaries (< 3.2.0) don't emit receiver or type-resolved method-call
-  // edges. Supplement them on the JS side if the native binary missed them.
-  // TODO: Remove once all published native binaries handle receivers (>= 3.2.0)
-  const hasReceiver = nativeEdges.some((e) => e.kind === 'receiver');
-  if (!hasReceiver) {
-    supplementReceiverEdges(ctx, nativeFiles, getNodeIdStmt, allEdgeRows);
-  }
 }
 
 function buildImportedNamesForNative(
@@ -241,58 +229,6 @@ function buildImportedNamesForNative(
   return importedNames;
 }
 
-// ── Receiver edge supplement for older native binaries ──────────────────
-
-function supplementReceiverEdges(
-  ctx: PipelineContext,
-  nativeFiles: NativeFileEntry[],
-  getNodeIdStmt: NodeIdStmt,
-  allEdgeRows: EdgeRowTuple[],
-): void {
-  const seenCallEdges = new Set<string>();
-  // Collect existing edges to avoid duplicates
-  for (const row of allEdgeRows) {
-    seenCallEdges.add(`${row[0]}|${row[1]}|${row[2]}`);
-  }
-
-  for (const nf of nativeFiles) {
-    const relPath = nf.file;
-    const typeMap = new Map<string, NormalizedTypeEntry>(
-      nf.typeMap.map((t) => [t.name, { type: t.typeName, confidence: t.confidence ?? 0.9 }]),
-    );
-    const fileNodeRow = { id: nf.fileNodeId };
-
-    for (const call of nf.calls) {
-      if (!call.receiver || BUILTIN_RECEIVERS.has(call.receiver)) continue;
-      if (call.receiver === 'this' || call.receiver === 'self' || call.receiver === 'super')
-        continue;
-
-      const caller = findCaller(call, nf.definitions, relPath, getNodeIdStmt, fileNodeRow);
-
-      // Receiver edge: caller → receiver type node
-      buildReceiverEdge(ctx, call, caller, relPath, seenCallEdges, allEdgeRows, typeMap);
-
-      // Type-resolved method call: caller → Type.method
-      const typeEntry = typeMap.get(call.receiver);
-      const typeName = typeEntry ? typeEntry.type : null;
-      if (typeName) {
-        const qualifiedName = `${typeName}.${call.name}`;
-        const targets = (ctx.nodesByName.get(qualifiedName) || []).filter(
-          (n) => n.kind === 'method',
-        );
-        for (const t of targets) {
-          const key = `${caller.id}|${t.id}|calls`;
-          if (t.id !== caller.id && !seenCallEdges.has(key)) {
-            seenCallEdges.add(key);
-            const confidence = computeConfidence(relPath, t.file, null);
-            allEdgeRows.push([caller.id, t.id, 'calls', confidence, call.dynamic ? 1 : 0]);
-          }
-        }
-      }
-    }
-  }
-}
-
 // ── Call edges (JS fallback) ────────────────────────────────────────────
 
 function buildCallEdgesJS(
@@ -494,7 +430,7 @@ function buildReceiverEdge(
   relPath: string,
   seenCallEdges: Set<string>,
   allEdgeRows: EdgeRowTuple[],
-  typeMap: Map<string, TypeMapEntry | NormalizedTypeEntry | string>,
+  typeMap: Map<string, TypeMapEntry | string>,
 ): void {
   const receiverKinds = new Set(['class', 'struct', 'interface', 'type', 'module']);
   const typeEntry = typeMap?.get(call.receiver!);
@@ -561,22 +497,94 @@ function buildClassHierarchyEdges(
 
 // ── Main entry point ────────────────────────────────────────────────────
 
+/**
+ * For small incremental builds (≤5 changed files on a large codebase), scope
+ * the node loading query to only files that are relevant: changed files +
+ * their import targets. Falls back to loading ALL nodes for full builds or
+ * larger incremental changes.
+ */
+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')`;
+
+  // Gate: only scope for small incremental on large codebases
+  if (!isFullBuild && fileSymbols.size <= 5) {
+    const existingFileCount = (
+      db.prepare("SELECT COUNT(*) as c FROM nodes WHERE kind = 'file'").get() as { c: number }
+    ).c;
+    if (existingFileCount > 20) {
+      // Collect relevant files: changed files + their import targets
+      const relevantFiles = new Set<string>(fileSymbols.keys());
+      if (batchResolved) {
+        for (const resolvedPath of batchResolved.values()) {
+          relevantFiles.add(resolvedPath);
+        }
+      }
+      // Also add barrel-only files
+      for (const barrelPath of ctx.barrelOnlyFiles) {
+        relevantFiles.add(barrelPath);
+      }
+
+      const placeholders = [...relevantFiles].map(() => '?').join(',');
+      const rows = db
+        .prepare(
+          `SELECT id, name, kind, file, line FROM nodes WHERE ${nodeKindFilter} AND file IN (${placeholders})`,
+        )
+        .all(...relevantFiles) as QueryNodeRow[];
+      return { rows, scoped: true };
+    }
+  }
+
+  const rows = db
+    .prepare(`SELECT id, name, kind, file, line FROM nodes WHERE ${nodeKindFilter}`)
+    .all() as QueryNodeRow[];
+  return { rows, scoped: false };
+}
+
+/**
+ * For scoped node loading, patch nodesByName.get with a lazy SQL fallback
+ * so global name-only lookups (resolveByMethodOrGlobal)
+ * can still find nodes outside the scoped set.
+ */
+function addLazyFallback(ctx: PipelineContext, scopedLoad: boolean): void {
+  if (!scopedLoad) return;
+  const { db } = ctx;
+  const fallbackStmt = db.prepare(
+    `SELECT id, name, kind, file, line FROM nodes WHERE name = ? AND kind != 'file'`,
+  );
+  const originalGet = ctx.nodesByName.get.bind(ctx.nodesByName);
+  ctx.nodesByName.get = (name: string) => {
+    const result = originalGet(name);
+    if (result !== undefined) return result;
+    const rows = fallbackStmt.all(name) as unknown as NodeRow[];
+    if (rows.length > 0) {
+      ctx.nodesByName.set(name, rows);
+      return rows;
+    }
+    return undefined;
+  };
+}
+
 export async function buildEdges(ctx: PipelineContext): Promise<void> {
   const { db, engineName } = ctx;
 
   const getNodeIdStmt = makeGetNodeIdStmt(db);
 
-  const allNodes = db
-    .prepare(
-      `SELECT id, name, kind, file, line FROM nodes WHERE kind IN ('function','method','class','interface','struct','type','module','enum','trait','record','constant')`,
-    )
-    .all() as QueryNodeRow[];
-  setupNodeLookups(ctx, allNodes);
+  const { rows: allNodesBefore, scoped: scopedLoad } = loadNodes(ctx);
+  setupNodeLookups(ctx, allNodesBefore);
+  addLazyFallback(ctx, scopedLoad);
 
   const t0 = performance.now();
-  const buildEdgesTx = db.transaction(() => {
-    // Delete stale outgoing edges for barrel-only files inside the transaction
-    // so that deletion and re-creation are atomic (no edge loss on mid-build crash).
+  const native = engineName === 'native' ? loadNative() : null;
+
+  // Phase 1: Compute edges inside a better-sqlite3 transaction.
+  // Barrel-edge deletion lives here so that the JS path (which also inserts
+  // edges in this transaction) keeps deletion + insertion atomic.
+  // When using the native rusqlite path, insertion happens in Phase 2 on a
+  // separate connection — a crash between Phase 1 and Phase 2 would leave
+  // barrel edges missing until the next incremental rebuild re-creates them.
+  const allEdgeRows: EdgeRowTuple[] = [];
+  const computeEdgesTx = db.transaction(() => {
     if (ctx.barrelOnlyFiles.size > 0) {
       const deleteOutgoingEdges = db.prepare(
         'DELETE FROM edges WHERE source_id IN (SELECT id FROM nodes WHERE file = ?)',
@@ -586,19 +594,44 @@ export async function buildEdges(ctx: PipelineContext): Promise<void> {
       }
     }
 
-    const allEdgeRows: EdgeRowTuple[] = [];
-
     buildImportEdges(ctx, getNodeIdStmt, allEdgeRows);
 
-    const native = engineName === 'native' ? loadNative() : null;
-    if (native?.buildCallEdges) {
-      buildCallEdgesNative(ctx, getNodeIdStmt, allEdgeRows, allNodes, native);
+    // Skip native call-edge path for small incremental builds (≤3 files):
+    // napi-rs marshaling overhead for allNodes exceeds computation savings.
+    const useNativeCallEdges =
+      native?.buildCallEdges && (ctx.isFullBuild || ctx.fileSymbols.size > 3);
+    if (useNativeCallEdges) {
+      buildCallEdgesNative(ctx, getNodeIdStmt, allEdgeRows, allNodesBefore, native!);
     } else {
       buildCallEdgesJS(ctx, getNodeIdStmt, allEdgeRows);
     }
 
-    batchInsertEdges(db, allEdgeRows);
+    // When using native edge insert, skip JS insert here — do it after tx commits.
+    // Otherwise insert edges within this transaction for atomicity.
+    const useNativeEdgeInsert = ctx.engineName === 'native' && !!ctx.nativeDb?.bulkInsertEdges;
+    if (!useNativeEdgeInsert) {
+      batchInsertEdges(db, allEdgeRows);
+    }
   });
-  buildEdgesTx();
+  computeEdgesTx();
+
+  // Phase 2: Native rusqlite bulk insert (outside better-sqlite3 transaction
+  // to avoid SQLITE_BUSY contention). Uses NativeDatabase persistent connection.
+  // Standalone napi functions were removed in 6.17.
+  if (ctx.engineName === 'native' && ctx.nativeDb?.bulkInsertEdges && allEdgeRows.length > 0) {
+    const nativeEdges = allEdgeRows.map((r) => ({
+      sourceId: r[0],
+      targetId: r[1],
+      kind: r[2],
+      confidence: r[3],
+      dynamic: r[4],
+    }));
+    const ok = ctx.nativeDb.bulkInsertEdges(nativeEdges);
+    if (!ok) {
+      debug('Native bulkInsertEdges failed — falling back to JS batchInsertEdges');
+      batchInsertEdges(ctx.db, allEdgeRows);
+    }
+  }
+
   ctx.timing.edgesMs = performance.now() - t0;
 }

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

@@ -39,8 +39,15 @@ export async function buildStructure(ctx: PipelineContext): Promise<void> {
   // loading ALL definitions from DB (~8ms) and recomputing ALL metrics (~15ms).
   // Gate: ≤5 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
-    ? (db.prepare("SELECT COUNT(*) as c FROM nodes WHERE kind = 'file'").get() as { c: number }).c
+    ? (
+        (useNativeReads
+          ? ctx.nativeDb!.queryGet("SELECT COUNT(*) as c FROM nodes WHERE kind = 'file'", [])
+          : db.prepare("SELECT COUNT(*) as c FROM nodes WHERE kind = 'file'").get()) as {
+          c: number;
+        }
+      ).c
     : 0;
   const useSmallIncrementalFastPath =
     !isFullBuild &&
@@ -86,13 +93,44 @@ export async function buildStructure(ctx: PipelineContext): Promise<void> {
   // Classify node roles (incremental: only reclassify changed files' nodes)
   const t1 = performance.now();
   try {
-    const { classifyNodeRoles } = (await import('../../../../features/structure.js')) as {
-      classifyNodeRoles: (
-        db: PipelineContext['db'],
-        changedFiles?: string[] | null,
-      ) => Record<string, number>;
-    };
-    const roleSummary = classifyNodeRoles(db, changedFileList);
+    let roleSummary: Record<string, number> | null = null;
+
+    // Use NativeDatabase persistent connection (Phase 6.15+).
+    // Standalone napi functions were removed in 6.17 — falls through to JS if nativeDb unavailable.
+    // Note: classifyRoles* both read (fan-in/fan-out) and write (UPDATE nodes SET role).
+    if (useNativeReads && ctx.nativeDb?.classifyRolesFull) {
+      const nativeResult =
+        changedFileList && changedFileList.length > 0
+          ? ctx.nativeDb.classifyRolesIncremental(changedFileList)
+          : ctx.nativeDb.classifyRolesFull();
+      if (nativeResult) {
+        roleSummary = {
+          entry: nativeResult.entry,
+          core: nativeResult.core,
+          utility: nativeResult.utility,
+          adapter: nativeResult.adapter,
+          dead: nativeResult.dead,
+          'dead-leaf': nativeResult.deadLeaf,
+          'dead-entry': nativeResult.deadEntry,
+          'dead-ffi': nativeResult.deadFfi,
+          'dead-unresolved': nativeResult.deadUnresolved,
+          'test-only': nativeResult.testOnly,
+          leaf: nativeResult.leaf,
+        };
+      }
+    }
+
+    // Fall back to JS path
+    if (!roleSummary) {
+      const { classifyNodeRoles } = (await import('../../../../features/structure.js')) as {
+        classifyNodeRoles: (
+          db: PipelineContext['db'],
+          changedFiles?: string[] | null,
+        ) => Record<string, number>;
+      };
+      roleSummary = classifyNodeRoles(ctx.db, changedFileList);
+    }
+
     debug(
       `Roles${changedFileList ? ` (incremental, ${changedFileList.length} files)` : ''}: ${Object.entries(
         roleSummary,