@optave/codegraph 3.4.0 → 3.4.1

package/src/domain/graph/builder/stages/detect-changes.ts

@@ -7,11 +7,10 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import type BetterSqlite3 from 'better-sqlite3';
 import { closeDb } from '../../../../db/index.js';
 import { debug, info } from '../../../../infrastructure/logger.js';
 import { normalizePath } from '../../../../shared/constants.js';
-import type { EngineOpts, ExtractorOutput } from '../../../../types.js';
+import type { BetterSqlite3Database, ExtractorOutput } from '../../../../types.js';
 import { parseFilesAuto } from '../../../parser.js';
 import { readJournal, writeJournalHeader } from '../../journal.js';
 import type { PipelineContext } from '../context.js';
@@ -56,7 +55,7 @@ interface NeedsHashItem {
 // ── Helpers ────────────────────────────────────────────────────────────
 
 function getChangedFiles(
-  db: BetterSqlite3.Database,
+  db: BetterSqlite3Database,
   allFiles: string[],
   rootDir: string,
 ): ChangeResult {
@@ -107,7 +106,7 @@ function detectRemovedFiles(
 }
 
 function tryJournalTier(
-  db: BetterSqlite3.Database,
+  db: BetterSqlite3Database,
   existing: Map<string, FileHashRow>,
   rootDir: string,
   removed: string[],
@@ -227,7 +226,7 @@ function mtimeAndHashTiers(
 async function runPendingAnalysis(ctx: PipelineContext): Promise<boolean> {
   const { db, opts, engineOpts, allFiles, rootDir } = ctx;
   const needsCfg =
-    (opts as Record<string, unknown>)['cfg'] !== false &&
+    (opts as Record<string, unknown>).cfg !== false &&
     (() => {
       try {
         return (
@@ -239,7 +238,7 @@ async function runPendingAnalysis(ctx: PipelineContext): Promise<boolean> {
       }
     })();
   const needsDataflow =
-    (opts as Record<string, unknown>)['dataflow'] !== false &&
+    (opts as Record<string, unknown>).dataflow !== false &&
     (() => {
       try {
         return (
@@ -255,7 +254,7 @@ async function runPendingAnalysis(ctx: PipelineContext): Promise<boolean> {
   info('No file changes. Running pending analysis pass...');
   const analysisOpts = {
     ...engineOpts,
-    dataflow: needsDataflow && (opts as Record<string, unknown>)['dataflow'] !== false,
+    dataflow: needsDataflow && (opts as Record<string, unknown>).dataflow !== false,
   };
   const analysisSymbols: Map<string, ExtractorOutput> = await parseFilesAuto(
     allFiles,
@@ -295,7 +294,7 @@ function healMetadata(ctx: PipelineContext): void {
 }
 
 function findReverseDependencies(
-  db: BetterSqlite3.Database,
+  db: BetterSqlite3Database,
   changedRelPaths: Set<string>,
   rootDir: string,
 ): Set<string> {
@@ -343,7 +342,7 @@ function purgeAndAddReverseDeps(
   }
 }
 
-function detectHasEmbeddings(db: BetterSqlite3.Database): boolean {
+function detectHasEmbeddings(db: BetterSqlite3Database): boolean {
   try {
     db.prepare('SELECT 1 FROM embeddings LIMIT 1').get();
     return true;
@@ -359,7 +358,7 @@ function handleScopedBuild(ctx: PipelineContext): void {
     (item) => item.relPath || normalizePath(path.relative(rootDir, item.file)),
   );
   let reverseDeps = new Set<string>();
-  if (!(opts as Record<string, unknown>)['noReverseDeps']) {
+  if (!(opts as Record<string, unknown>).noReverseDeps) {
     const changedRelPaths = new Set<string>([...changePaths, ...ctx.removed]);
     reverseDeps = findReverseDependencies(db, changedRelPaths, rootDir);
   }
@@ -386,7 +385,7 @@ function handleIncrementalBuild(ctx: PipelineContext): void {
   const { db, rootDir, opts } = ctx;
   ctx.hasEmbeddings = detectHasEmbeddings(db);
   let reverseDeps = new Set<string>();
-  if (!(opts as Record<string, unknown>)['noReverseDeps']) {
+  if (!(opts as Record<string, unknown>).noReverseDeps) {
     const changedRelPaths = new Set<string>();
     for (const item of ctx.parseChanges) {
       changedRelPaths.add(item.relPath || normalizePath(path.relative(rootDir, item.file)));
@@ -410,7 +409,7 @@ function handleIncrementalBuild(ctx: PipelineContext): void {
 
 export async function detectChanges(ctx: PipelineContext): Promise<void> {
   const { db, allFiles, rootDir, incremental, forceFullRebuild, opts } = ctx;
-  if ((opts as Record<string, unknown>)['scope']) {
+  if ((opts as Record<string, unknown>).scope) {
     handleScopedBuild(ctx);
     return;
   }

package/src/domain/graph/builder/stages/finalize.ts

@@ -3,21 +3,15 @@
  *
  * WASM cleanup, stats logging, drift detection, build metadata, registry, journal.
  */
-import fs from 'node:fs';
+import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { performance } from 'node:perf_hooks';
-import { closeDb, getBuildMeta, setBuildMeta } from '../../../../db/index.js';
+import { closeDb, closeDbDeferred, getBuildMeta, setBuildMeta } from '../../../../db/index.js';
 import { debug, info, warn } from '../../../../infrastructure/logger.js';
+import { CODEGRAPH_VERSION } from '../../../../shared/version.js';
 import { writeJournalHeader } from '../../journal.js';
 import type { PipelineContext } from '../context.js';
 
-const __builderDir = path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/i, '$1'));
-const CODEGRAPH_VERSION = (
-  JSON.parse(
-    fs.readFileSync(path.join(__builderDir, '..', '..', '..', '..', '..', 'package.json'), 'utf-8'),
-  ) as { version: string }
-).version;
-
 export async function finalize(ctx: PipelineContext): Promise<void> {
   const { db, allSymbols, rootDir, isFullBuild, hasEmbeddings, config, opts, schemaVersion } = ctx;
 
@@ -46,8 +40,9 @@ export async function finalize(ctx: PipelineContext): Promise<void> {
   info(`Graph built: ${nodeCount} nodes, ${actualEdgeCount} edges`);
   info(`Stored in ${ctx.dbPath}`);
 
-  // Incremental drift detection
-  if (!isFullBuild) {
+  // Incremental drift detection — skip for small incremental changes where
+  // count fluctuation is expected (reverse-dep edge churn).
+  if (!isFullBuild && allSymbols.size > 3) {
     const prevNodes = getBuildMeta(db, 'node_count');
     const prevEdges = getBuildMeta(db, 'edge_count');
     if (prevNodes && prevEdges) {
@@ -67,95 +62,121 @@ export async function finalize(ctx: PipelineContext): Promise<void> {
     }
   }
 
-  // Persist build metadata early so downstream checks (e.g. stale-embeddings)
-  // can read the *current* build's built_at rather than the previous one.
-  try {
-    setBuildMeta(db, {
-      engine: ctx.engineName,
-      engine_version: ctx.engineVersion || '',
-      codegraph_version: CODEGRAPH_VERSION,
-      schema_version: String(schemaVersion),
-      built_at: buildNow.toISOString(),
-      node_count: nodeCount,
-      edge_count: actualEdgeCount,
-    });
-  } catch (err) {
-    warn(`Failed to write build metadata: ${(err as Error).message}`);
+  // For small incremental builds, skip persisting build metadata — the
+  // engine/version/schema haven't changed (would have triggered a full rebuild),
+  // built_at is only used by stale-embeddings check (skipped for incremental),
+  // and counts are only used by drift detection (skipped for ≤3 files).
+  // This avoids a transaction commit + WAL fsync (~15-30ms).
+  if (isFullBuild || allSymbols.size > 5) {
+    try {
+      setBuildMeta(db, {
+        engine: ctx.engineName,
+        engine_version: ctx.engineVersion || '',
+        codegraph_version: CODEGRAPH_VERSION,
+        schema_version: String(schemaVersion),
+        built_at: buildNow.toISOString(),
+        node_count: nodeCount,
+        edge_count: actualEdgeCount,
+      });
+    } catch (err) {
+      warn(`Failed to write build metadata: ${(err as Error).message}`);
+    }
   }
 
-  // Orphaned embeddings warning
-  if (hasEmbeddings) {
+  // Skip expensive advisory queries for incremental builds — these are
+  // informational warnings that don't affect correctness and cost ~40-60ms.
+  if (!isFullBuild) {
+    debug(
+      'Finalize: skipping advisory queries (orphaned/stale embeddings, unused exports) for incremental build',
+    );
+  } else {
+    // Orphaned embeddings warning
+    if (hasEmbeddings) {
+      try {
+        const orphaned = (
+          db
+            .prepare(
+              'SELECT COUNT(*) as c FROM embeddings WHERE node_id NOT IN (SELECT id FROM nodes)',
+            )
+            .get() as { c: number }
+        ).c;
+        if (orphaned > 0) {
+          warn(
+            `${orphaned} embeddings are orphaned (nodes changed). Run "codegraph embed" to refresh.`,
+          );
+        }
+      } catch {
+        /* ignore - embeddings table may have been dropped */
+      }
+    }
+
+    // Stale embeddings warning (built before current graph rebuild)
+    if (hasEmbeddings) {
+      try {
+        const embedBuiltAt = (
+          db.prepare("SELECT value FROM embedding_meta WHERE key = 'built_at'").get() as
+            | { value: string }
+            | undefined
+        )?.value;
+        if (embedBuiltAt) {
+          const embedTime = new Date(embedBuiltAt).getTime();
+          if (!Number.isNaN(embedTime) && embedTime < buildNow.getTime()) {
+            warn(
+              'Embeddings were built before the last graph rebuild. Run "codegraph embed" to update.',
+            );
+          }
+        }
+      } catch {
+        /* ignore - embedding_meta table may not exist */
+      }
+    }
+
+    // Unused exports warning
     try {
-      const orphaned = (
+      const unusedCount = (
         db
           .prepare(
-            'SELECT COUNT(*) as c FROM embeddings WHERE node_id NOT IN (SELECT id FROM nodes)',
+            `SELECT COUNT(*) as c FROM nodes
+         WHERE exported = 1 AND kind != 'file'
+           AND id NOT IN (
+             SELECT DISTINCT e.target_id FROM edges e
+             JOIN nodes caller ON e.source_id = caller.id
+             JOIN nodes target ON e.target_id = target.id
+             WHERE e.kind = 'calls' AND caller.file != target.file
+           )`,
           )
           .get() as { c: number }
       ).c;
-      if (orphaned > 0) {
+      if (unusedCount > 0) {
         warn(
-          `${orphaned} embeddings are orphaned (nodes changed). Run "codegraph embed" to refresh.`,
+          `${unusedCount} exported symbol${unusedCount > 1 ? 's have' : ' has'} zero cross-file consumers. Run "codegraph exports <file> --unused" to inspect.`,
         );
       }
     } catch {
-      /* ignore - embeddings table may have been dropped */
+      /* exported column may not exist on older DBs */
     }
   }
 
-  // Stale embeddings warning (built before current graph rebuild)
-  if (hasEmbeddings) {
-    try {
-      const embedBuiltAt = (
-        db.prepare("SELECT value FROM embedding_meta WHERE key = 'built_at'").get() as
-          | { value: string }
-          | undefined
-      )?.value;
-      if (embedBuiltAt) {
-        const embedTime = new Date(embedBuiltAt).getTime();
-        if (!Number.isNaN(embedTime) && embedTime < buildNow.getTime()) {
-          warn(
-            'Embeddings were built before the last graph rebuild. Run "codegraph embed" to update.',
-          );
-        }
-      }
-    } catch {
-      /* ignore - embedding_meta table may not exist */
-    }
-  }
+  ctx.timing.finalizeMs = performance.now() - t0;
 
-  // Unused exports warning
-  try {
-    const unusedCount = (
-      db
-        .prepare(
-          `SELECT COUNT(*) as c FROM nodes
-       WHERE exported = 1 AND kind != 'file'
-         AND id NOT IN (
-           SELECT DISTINCT e.target_id FROM edges e
-           JOIN nodes caller ON e.source_id = caller.id
-           JOIN nodes target ON e.target_id = target.id
-           WHERE e.kind = 'calls' AND caller.file != target.file
-         )`,
-        )
-        .get() as { c: number }
-    ).c;
-    if (unusedCount > 0) {
-      warn(
-        `${unusedCount} exported symbol${unusedCount > 1 ? 's have' : ' has'} zero cross-file consumers. Run "codegraph exports <file> --unused" to inspect.`,
-      );
-    }
-  } catch {
-    /* exported column may not exist on older DBs */
+  // For small incremental builds, defer db.close() to the next event loop tick.
+  // The WAL checkpoint in db.close() costs ~250ms on Windows NTFS due to fsync.
+  // Deferring lets buildGraph() return immediately; the checkpoint runs after.
+  // Skip for temp directories (tests) — they rmSync immediately after build.
+  const isTempDir = path.resolve(rootDir).startsWith(path.resolve(tmpdir()));
+  if (!isFullBuild && allSymbols.size <= 5 && !isTempDir) {
+    closeDbDeferred(db);
+  } else {
+    closeDb(db);
   }
 
-  closeDb(db);
-
   // Write journal header after successful build
   writeJournalHeader(rootDir, Date.now());
 
-  // Auto-registration
-  if (!opts.skipRegistry) {
+  // Skip auto-registration for incremental builds — the repo was already
+  // registered during the initial full build. The dynamic import + file I/O
+  // costs ~100ms which dominates incremental finalize time.
+  if (!opts.skipRegistry && isFullBuild) {
     const { tmpdir } = await import('node:os');
     const tmpDir = path.resolve(tmpdir());
     const resolvedRoot = path.resolve(rootDir);
@@ -172,6 +193,4 @@ export async function finalize(ctx: PipelineContext): Promise<void> {
       }
     }
   }
-
-  ctx.timing.finalizeMs = performance.now() - t0;
 }

package/src/domain/graph/builder/stages/insert-nodes.ts

@@ -6,9 +6,13 @@
  */
 import path from 'node:path';
 import { performance } from 'node:perf_hooks';
-import type BetterSqlite3 from 'better-sqlite3';
 import { bulkNodeIdsByFile } from '../../../../db/index.js';
-import type { ExtractorOutput, MetadataUpdate } from '../../../../types.js';
+import type {
+  BetterSqlite3Database,
+  ExtractorOutput,
+  MetadataUpdate,
+  SqliteStatement,
+} from '../../../../types.js';
 import type { PipelineContext } from '../context.js';
 import {
   batchInsertEdges,
@@ -31,7 +35,7 @@ interface PrecomputedFileData {
 // ── Phase 1: Insert file nodes, definitions, exports ────────────────────
 
 function insertDefinitionsAndExports(
-  db: BetterSqlite3.Database,
+  db: BetterSqlite3Database,
   allSymbols: Map<string, ExtractorOutput>,
 ): void {
   const phase1Rows: unknown[][] = [];
@@ -63,7 +67,7 @@ function insertDefinitionsAndExports(
   // Mark exported symbols in batches (cache prepared statements by chunk size)
   if (exportKeys.length > 0) {
     const EXPORT_CHUNK = 500;
-    const exportStmtCache = new Map<number, BetterSqlite3.Statement>();
+    const exportStmtCache = new Map<number, SqliteStatement>();
     for (let i = 0; i < exportKeys.length; i += EXPORT_CHUNK) {
       const end = Math.min(i + EXPORT_CHUNK, exportKeys.length);
       const chunkSize = end - i;
@@ -89,7 +93,7 @@ function insertDefinitionsAndExports(
 // ── Phase 2+3: Insert children and containment edges (two nodeIdMap passes) ──
 
 function insertChildrenAndEdges(
-  db: BetterSqlite3.Database,
+  db: BetterSqlite3Database,
   allSymbols: Map<string, ExtractorOutput>,
 ): void {
   const childRows: unknown[][] = [];
@@ -164,12 +168,12 @@ function insertChildrenAndEdges(
 // ── Phase 4: Update file hashes ─────────────────────────────────────────
 
 function updateFileHashes(
-  _db: BetterSqlite3.Database,
+  _db: BetterSqlite3Database,
   allSymbols: Map<string, ExtractorOutput>,
   precomputedData: Map<string, PrecomputedFileData>,
   metadataUpdates: MetadataUpdate[],
   rootDir: string,
-  upsertHash: BetterSqlite3.Statement | null,
+  upsertHash: SqliteStatement | null,
 ): void {
   if (!upsertHash) return;
 
@@ -224,7 +228,7 @@ export async function insertNodes(ctx: PipelineContext): Promise<void> {
     if (item.relPath) precomputedData.set(item.relPath, item as PrecomputedFileData);
   }
 
-  let upsertHash: BetterSqlite3.Statement | null;
+  let upsertHash: SqliteStatement | null;
   try {
     upsertHash = db.prepare(
       'INSERT OR REPLACE INTO file_hashes (file, hash, mtime, size) VALUES (?, ?, ?, ?)',

package/src/domain/graph/builder/stages/resolve-imports.ts

@@ -41,18 +41,83 @@ export async function resolveImports(ctx: PipelineContext): Promise<void> {
 
   ctx.barrelOnlyFiles = new Set<string>();
   if (!isFullBuild) {
-    const barrelCandidates = db
-      .prepare(`SELECT DISTINCT n1.file FROM edges e
+    // Collect the set of changed file paths to scope barrel re-parsing.
+    const changedRelPaths = new Set<string>(fileSymbols.keys());
+
+    // For small incremental builds (≤5 files), only re-parse barrel files
+    // that are related to the changed files — either re-exporting from them
+    // or imported by them. For larger changes, re-parse all barrels.
+    let barrelCandidates: Array<{ file: string }>;
+    if (changedRelPaths.size <= 5) {
+      // All known barrel files (has at least one reexport edge)
+      const allBarrelFiles = new Set(
+        (
+          db
+            .prepare(
+              `SELECT DISTINCT n1.file FROM edges e
+               JOIN nodes n1 ON e.source_id = n1.id
+               WHERE e.kind = 'reexports' AND n1.kind = 'file'`,
+            )
+            .all() as Array<{ file: string }>
+        ).map((r) => r.file),
+      );
+
+      const barrels = new Set<string>();
+
+      // Find barrels imported by changed files using parsed import data
+      // (can't query DB edges — they were purged for the changed files).
+      for (const relPath of changedRelPaths) {
+        const symbols = fileSymbols.get(relPath);
+        if (!symbols) continue;
+        for (const imp of symbols.imports) {
+          const resolved = ctx.batchResolved?.get(`${path.join(rootDir, relPath)}|${imp.source}`);
+          const target =
+            resolved ??
+            resolveImportPath(path.join(rootDir, relPath), imp.source, rootDir, aliases);
+          if (allBarrelFiles.has(target)) barrels.add(target);
+        }
+      }
+
+      // Also find barrels that re-export from the changed files
+      const reexportSourceStmt = db.prepare(
+        `SELECT DISTINCT n1.file FROM edges e
          JOIN nodes n1 ON e.source_id = n1.id
-         WHERE e.kind = 'reexports' AND n1.kind = 'file'`)
-      .all() as Array<{ file: string }>;
+         JOIN nodes n2 ON e.target_id = n2.id
+         WHERE e.kind = 'reexports' AND n1.kind = 'file' AND n2.file = ?`,
+      );
+      for (const relPath of changedRelPaths) {
+        for (const row of reexportSourceStmt.all(relPath) as Array<{ file: string }>) {
+          barrels.add(row.file);
+        }
+      }
+      barrelCandidates = [...barrels].map((file) => ({ file }));
+    } else {
+      barrelCandidates = db
+        .prepare(
+          `SELECT DISTINCT n1.file FROM edges e
+           JOIN nodes n1 ON e.source_id = n1.id
+           WHERE e.kind = 'reexports' AND n1.kind = 'file'`,
+        )
+        .all() as Array<{ file: string }>;
+    }
+
+    // Batch-parse all barrel candidates at once instead of one-by-one
+    const barrelPaths: string[] = [];
     for (const { file: relPath } of barrelCandidates) {
-      if (fileSymbols.has(relPath)) continue;
-      const absPath = path.join(rootDir, relPath);
+      if (!fileSymbols.has(relPath)) {
+        barrelPaths.push(path.join(rootDir, relPath));
+      }
+    }
+
+    if (barrelPaths.length > 0) {
+      const deleteOutgoingEdges = db.prepare(
+        'DELETE FROM edges WHERE source_id IN (SELECT id FROM nodes WHERE file = ?)',
+      );
+
       try {
-        const symbols = await parseFilesAuto([absPath], rootDir, engineOpts);
-        const fileSym = symbols.get(relPath);
-        if (fileSym) {
+        const barrelSymbols = await parseFilesAuto(barrelPaths, rootDir, engineOpts);
+        for (const [relPath, fileSym] of barrelSymbols) {
+          deleteOutgoingEdges.run(relPath);
           fileSymbols.set(relPath, fileSym);
           ctx.barrelOnlyFiles.add(relPath);
           const reexports = fileSym.imports.filter((imp: Import) => imp.reexport);
@@ -60,7 +125,7 @@ export async function resolveImports(ctx: PipelineContext): Promise<void> {
             ctx.reexportMap.set(
               relPath,
               reexports.map((imp: Import) => ({
-                source: getResolved(ctx, absPath, imp.source),
+                source: getResolved(ctx, path.join(rootDir, relPath), imp.source),
                 names: imp.names,
                 wildcardReexport: imp.wildcardReexport || false,
               })),

package/src/domain/graph/cycles.ts

@@ -16,9 +16,9 @@ export function findCycles(
   const idToLabel = new Map<string, string>();
   for (const [id, attrs] of graph.nodes()) {
     if (fileLevel) {
-      idToLabel.set(id, attrs['file'] as string);
+      idToLabel.set(id, attrs.file as string);
     } else {
-      idToLabel.set(id, `${attrs['label']}|${attrs['file']}`);
+      idToLabel.set(id, `${attrs.label}|${attrs.file}`);
     }
   }
 

package/src/domain/graph/resolve.ts

@@ -1,13 +1,14 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { debug } from '../../infrastructure/logger.js';
 import { loadNative } from '../../infrastructure/native.js';
 import { normalizePath } from '../../shared/constants.js';
+import { toErrorMessage } from '../../shared/errors.js';
 import type { BareSpecifier, BatchResolvedMap, ImportBatchItem, PathAliases } from '../../types.js';
 
 // ── package.json exports resolution ─────────────────────────────────
 
 /** Cache: packageDir → parsed exports field (or null) */
-// biome-ignore lint/suspicious/noExplicitAny: package.json exports field has no fixed schema
 const _exportsCache: Map<string, any> = new Map();
 
 /**
@@ -55,7 +56,6 @@ function findPackageDir(packageName: string, rootDir: string): string | null {
  * Read and cache the exports field from a package's package.json.
  * Returns the exports value or null.
  */
-// biome-ignore lint/suspicious/noExplicitAny: package.json exports field has no fixed schema
 function getPackageExports(packageDir: string): any {
   if (_exportsCache.has(packageDir)) return _exportsCache.get(packageDir);
   try {
@@ -64,7 +64,8 @@ function getPackageExports(packageDir: string): any {
     const exports = pkg.exports ?? null;
     _exportsCache.set(packageDir, exports);
     return exports;
-  } catch {
+  } catch (e) {
+    debug(`readPackageExports: failed to read package.json in ${packageDir}: ${toErrorMessage(e)}`);
     _exportsCache.set(packageDir, null);
     return null;
   }
@@ -515,8 +516,10 @@ export function resolveImportPath(
       // unresolved ".." components (PathBuf::components().collect() doesn't
       // collapse parent refs). Apply the remap on the JS side as a fallback.
       return remapJsToTs(normalized, rootDir);
-    } catch {
-      // fall through to JS
+    } catch (e) {
+      debug(
+        `resolveImportPath: native resolution failed, falling back to JS: ${toErrorMessage(e)}`,
+      );
     }
   }
   return resolveImportPathJS(fromFile, importSource, rootDir, aliases);
@@ -535,8 +538,10 @@ export function computeConfidence(
   if (native) {
     try {
       return native.computeConfidence(callerFile, targetFile, importedFrom || null);
-    } catch {
-      // fall through to JS
+    } catch (e) {
+      debug(
+        `computeConfidence: native computation failed, falling back to JS: ${toErrorMessage(e)}`,
+      );
     }
   }
   return computeConfidenceJS(callerFile, targetFile, importedFrom);
@@ -575,7 +580,8 @@ export function resolveImportsBatch(
       map.set(`${r.fromFile}|${r.importSource}`, resolved);
     }
     return map;
-  } catch {
+  } catch (e) {
+    debug(`batchResolve: native batch resolution failed: ${toErrorMessage(e)}`);
     return null;
   }
 }

package/src/domain/graph/watcher.ts

@@ -24,9 +24,7 @@ export async function watchProject(rootDir: string, opts: { engine?: string } =
     throw new DbError('No graph.db found. Run `codegraph build` first.', { file: dbPath });
   }
 
-  const db = openDb(dbPath) as import('better-sqlite3').Database;
-  // Alias for functions expecting the project's BetterSqlite3Database interface
-  const typedDb = db as unknown as import('../../types.js').BetterSqlite3Database;
+  const db = openDb(dbPath);
   initSchema(db);
   const engineOpts: import('../../types.js').EngineOpts = {
     engine: (opts.engine || 'auto') as import('../../types.js').EngineMode,
@@ -51,7 +49,7 @@ export async function watchProject(rootDir: string, opts: { engine?: string } =
     ),
     getNodeId: {
       get: (name: string, kind: string, file: string, line: number) => {
-        const id = getNodeIdQuery(typedDb, name, kind, file, line);
+        const id = getNodeIdQuery(db, name, kind, file, line);
         return id != null ? { id } : undefined;
       },
     },