fix(native): enable bulkInsertNodes native path

crates/codegraph-core/src/insert_nodes.rs

@@ -6,44 +6,45 @@
 
 use std::collections::HashMap;
 
-use napi_derive::napi;
 use rusqlite::{params, Connection};
 use serde::{Deserialize, Serialize};
 
 // ── Input types (received from JS via napi) ─────────────────────────
 
-#[napi(object)]
+/// Child node of a definition (parameter, nested function, etc.).
+///
+/// Deserialized via serde (not napi object conversion) so that `null` visibility
+/// maps to `None` instead of crashing napi's `Option<String>` conversion (#709).
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct InsertNodesChild {
     pub name: String,
     pub kind: String,
     pub line: u32,
-    #[napi(js_name = "endLine")]
+    #[serde(default, rename = "endLine")]
     pub end_line: Option<u32>,
+    #[serde(default)]
     pub visibility: Option<String>,
 }
 
-#[napi(object)]
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct InsertNodesDefinition {
     pub name: String,
     pub kind: String,
     pub line: u32,
-    #[napi(js_name = "endLine")]
+    #[serde(default, rename = "endLine")]
     pub end_line: Option<u32>,
+    #[serde(default)]
     pub visibility: Option<String>,
     pub children: Vec<InsertNodesChild>,
 }
 
-#[napi(object)]
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct InsertNodesExport {
     pub name: String,
     pub kind: String,
     pub line: u32,
 }
 
-#[napi(object)]
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct InsertNodesBatch {
     pub file: String,

crates/codegraph-core/src/native_db.rs

@@ -736,13 +736,21 @@ impl NativeDatabase {
     /// Bulk-insert nodes, children, containment edges, exports, and file hashes.
     /// Reuses the persistent connection instead of opening a new one.
     /// Returns `true` on success, `false` on failure.
-    #[napi]
+    ///
+    /// Batches are received as `serde_json::Value` and deserialized via serde so
+    /// that `null` visibility values map to `None` instead of crashing napi's
+    /// `Option<String>` object conversion (#709).
+    #[napi(ts_args_type = "batches: InsertNodesBatch[], fileHashes: FileHashEntry[], removedFiles: string[]")]
     pub fn bulk_insert_nodes(
         &self,
-        batches: Vec<InsertNodesBatch>,
+        batches: serde_json::Value,
         file_hashes: Vec<FileHashEntry>,
         removed_files: Vec<String>,
     ) -> napi::Result<bool> {
+        let batches: Vec<InsertNodesBatch> = serde_json::from_value(batches)
+            .map_err(|e| {
+                napi::Error::from_reason(format!("bulk_insert_nodes: invalid batches: {e}"))
+            })?;
         let conn = self.conn()?;
         Ok(insert_nodes::do_insert_nodes(conn, &batches, &file_hashes, &removed_files)
             .inspect_err(|e| eprintln!("[NativeDatabase] bulk_insert_nodes failed: {e}"))

src/domain/graph/builder/pipeline.ts

@@ -223,7 +223,33 @@ async function runPipelineStages(ctx: PipelineContext): Promise<void> {
   if (ctx.earlyExit) return;
 
   await parseFiles(ctx);
+
+  // Temporarily reopen nativeDb for insertNodes — it uses the WAL checkpoint
+  // guard internally (same pattern as feature modules). Closed again before
+  // resolveImports/buildEdges which don't yet have the guard (#709).
+  if (hadNativeDb && ctx.engineName === 'native') {
+    const native = loadNative();
+    if (native?.NativeDatabase) {
+      try {
+        ctx.nativeDb = native.NativeDatabase.openReadWrite(ctx.dbPath);
+      } catch {
+        ctx.nativeDb = undefined;
+      }
+    }
+  }
+
   await insertNodes(ctx);
+
+  // Close nativeDb after insertNodes — remaining pipeline stages use JS paths.
+  if (ctx.nativeDb && ctx.db) {
+    try {
+      ctx.nativeDb.close();
+    } catch {
+      /* ignore close errors */
+    }
+    ctx.nativeDb = undefined;
+  }
+
   await resolveImports(ctx);
   await buildEdges(ctx);
   await buildStructure(ctx);

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

@@ -39,16 +39,17 @@ interface PrecomputedFileData {
 // ── Native fast-path ─────────────────────────────────────────────────
 
 function tryNativeInsert(ctx: PipelineContext): boolean {
-  // Disabled: bulkInsertNodes corrupts the DB when both the JS (better-sqlite3)
-  // and Rust (rusqlite) connections are open to the same WAL-mode file.
-  // The native path was never operational before — it always crashed on null
-  // visibility serialisation. See #696 for the dual-connection fix.
-  if (ctx.db) return false;
-
   // Use NativeDatabase persistent connection (Phase 6.15+).
   // Standalone napi functions were removed in 6.17 — falls through to JS if nativeDb unavailable.
   if (!ctx.nativeDb?.bulkInsertNodes) return false;
 
+  // WAL checkpoint: flush WAL to main DB file so the native (rusqlite) connection
+  // sees a clean slate. This is the same dual-connection guard used by feature
+  // modules (ast, cfg, complexity, dataflow). See #696, #709.
+  if (ctx.db) {
+    ctx.db.pragma('wal_checkpoint(TRUNCATE)');
+  }
+
   const { allSymbols, filesToParse, metadataUpdates, rootDir, removed } = ctx;
 
   // Marshal allSymbols → InsertNodesBatch[]