gitnexus 1.6.8-rc.46 → 1.6.8-rc.47

package/dist/core/lbug/csv-generator.d.ts

@@ -55,5 +55,22 @@ export interface StreamedCSVResult {
  * Stream all CSV data directly to disk files.
  * Iterates graph nodes exactly ONCE — routes each node to the right writer.
  * File contents are lazy-read from disk with a generous LRU cache.
+ *
+ * `onNodePhaseComplete` (optional, #2203 parallelism leg): fired exactly once,
+ * right after every node CSV is fully flushed to disk and BEFORE the
+ * relationship pass starts writing any `rel_*.csv`. It receives the finished
+ * node-file manifest so the caller can begin `COPY`-ing nodes while this
+ * function keeps generating relationship CSVs (the only single-writer-safe
+ * overlap — node `COPY` ‖ relationship emit). It is intentionally NOT awaited:
+ * the relationship pass proceeds concurrently with whatever the caller
+ * schedules. A synchronous throw from the callback is allowed and propagates out
+ * of this function (rejecting the returned promise) — it is raised before the
+ * relationship pass begins, so no `rel_*.csv` is written; `loadGraphToLbug` uses
+ * this to surface its PDG-manifest collision guard. The callback must NOT, however,
+ * schedule un-awaited async work that can reject unobserved. Absent ⇒ today's
+ * behavior, byte-for-byte.
  */
-export declare const streamAllCSVsToDisk: (graph: KnowledgeGraph, repoPath: string, csvDir: string) => Promise<StreamedCSVResult>;
+export declare const streamAllCSVsToDisk: (graph: KnowledgeGraph, repoPath: string, csvDir: string, onNodePhaseComplete?: (nodeFiles: Map<NodeTableName, {
+    csvPath: string;
+    rows: number;
+}>) => void) => Promise<StreamedCSVResult>;

package/dist/core/lbug/csv-generator.js

@@ -33,6 +33,14 @@ const orderedNodes = (graph, sorted) => sorted ? [...graph.iterNodes()].sort(byG
 const orderedRelationships = (graph, sorted) => sorted ? [...graph.iterRelationships()].sort(byGraphId) : graph.iterRelationships();
 /** Flush buffered rows to disk every N rows */
 const FLUSH_EVERY = 500;
+/**
+ * Yield the event loop every N relationship rows during the emit pass (#2226 F4)
+ * so a concurrent node COPY (the overlap in loadGraphToLbug) and write-stream
+ * drain callbacks get scheduling time during long synchronous emit stretches.
+ * Scheduling-only — never changes row content or order (byte-identical). Tuning
+ * constant, not load-bearing.
+ */
+const REL_YIELD_EVERY = 5000;
 // ============================================================================
 // CSV ESCAPE UTILITIES
 // ============================================================================
@@ -239,8 +247,22 @@ export const buildBasicBlockRow = (node) => [
  * Stream all CSV data directly to disk files.
  * Iterates graph nodes exactly ONCE — routes each node to the right writer.
  * File contents are lazy-read from disk with a generous LRU cache.
+ *
+ * `onNodePhaseComplete` (optional, #2203 parallelism leg): fired exactly once,
+ * right after every node CSV is fully flushed to disk and BEFORE the
+ * relationship pass starts writing any `rel_*.csv`. It receives the finished
+ * node-file manifest so the caller can begin `COPY`-ing nodes while this
+ * function keeps generating relationship CSVs (the only single-writer-safe
+ * overlap — node `COPY` ‖ relationship emit). It is intentionally NOT awaited:
+ * the relationship pass proceeds concurrently with whatever the caller
+ * schedules. A synchronous throw from the callback is allowed and propagates out
+ * of this function (rejecting the returned promise) — it is raised before the
+ * relationship pass begins, so no `rel_*.csv` is written; `loadGraphToLbug` uses
+ * this to surface its PDG-manifest collision guard. The callback must NOT, however,
+ * schedule un-awaited async work that can reject unobserved. Absent ⇒ today's
+ * behavior, byte-for-byte.
  */
-export const streamAllCSVsToDisk = async (graph, repoPath, csvDir) => {
+export const streamAllCSVsToDisk = async (graph, repoPath, csvDir, onNodePhaseComplete) => {
     // Deterministic (id-sorted) node/relationship row order when enabled;
     // default off = today's graph-insertion order (byte-identical).
     const sortOutput = parseTruthyEnv(process.env.GITNEXUS_SORT_GRAPH_OUTPUT);
@@ -502,30 +524,11 @@ export const streamAllCSVsToDisk = async (graph, repoPath, csvDir) => {
             ...multiLangWriters.values(),
         ];
         await Promise.all(allWriters.map((w) => w.finish()));
-        // --- Stream relationships directly to per-FROM→TO-label-pair files ---
-        // (#2203 U2) Route every edge to its pair file in this single pass. The old
-        // monolithic relations.csv — and its line-by-line re-read + per-edge regex
-        // re-split in loadGraphToLbug — are gone, so the ~1M-edge set is written and
-        // read once instead of twice. The router applies the SAME label-derivation +
-        // validTables filter as the legacy splitRelCsvByLabelPair, so the per-pair
-        // files are byte-identical (asserted by the differential test).
-        const relRouter = new RelPairRouter(csvDir, REL_CSV_HEADER, new Set(NODE_TABLES));
-        try {
-            for (const rel of orderedRelationships(graph, sortOutput)) {
-                const pending = relRouter.route(rel.sourceId, rel.targetId, buildRelRow(rel));
-                if (pending)
-                    await pending;
-            }
-            await relRouter.close();
-        }
-        catch (err) {
-            relRouter.destroy();
-            // Rethrow the real stream error (EMFILE / disk-full) rather than the generic
-            // AbortError a pending drain-await rejects with — mirrors the retained
-            // splitRelCsvByLabelPair's `throw streamError ?? err`.
-            throw relRouter.lastError ?? err;
-        }
-        // Build result map — only include tables that have rows
+        // Build the node-file manifest now (all writers are flushed; `.rows` is
+        // final). Hoisted above the relationship pass so `onNodePhaseComplete` can
+        // hand the caller a complete node manifest to start COPY-ing while we keep
+        // generating relationship CSVs below (#2203 overlap). The same map is
+        // returned, so the result is unchanged when no callback is supplied.
         const nodeFiles = new Map();
         const tableMap = [
             ['File', fileWriter],
@@ -551,6 +554,38 @@ export const streamAllCSVsToDisk = async (graph, repoPath, csvDir) => {
                 });
             }
         }
+        // Node CSVs are on disk; relationship CSVs have not been touched yet. Hand
+        // the manifest to the caller (not awaited — the rel pass runs concurrently).
+        onNodePhaseComplete?.(nodeFiles);
+        // --- Stream relationships directly to per-FROM→TO-label-pair files ---
+        // (#2203 U2) Route every edge to its pair file in this single pass. The old
+        // monolithic relations.csv — and its line-by-line re-read + per-edge regex
+        // re-split in loadGraphToLbug — are gone, so the ~1M-edge set is written and
+        // read once instead of twice. The router applies the SAME label-derivation +
+        // validTables filter as the legacy splitRelCsvByLabelPair, so the per-pair
+        // files are byte-identical (asserted by the differential test).
+        const relRouter = new RelPairRouter(csvDir, REL_CSV_HEADER, new Set(NODE_TABLES));
+        try {
+            let emitted = 0;
+            for (const rel of orderedRelationships(graph, sortOutput)) {
+                const pending = relRouter.route(rel.sourceId, rel.targetId, buildRelRow(rel));
+                if (pending)
+                    await pending;
+                // Periodically hand the event loop back so the overlapped node COPY and
+                // write-stream drains run instead of starving behind this synchronous
+                // loop (#2226 F4). No effect on emitted bytes — pure scheduling.
+                if (++emitted % REL_YIELD_EVERY === 0)
+                    await new Promise((r) => setImmediate(r));
+            }
+            await relRouter.close();
+        }
+        catch (err) {
+            relRouter.destroy();
+            // Rethrow the real stream error (EMFILE / disk-full) rather than the generic
+            // AbortError a pending drain-await rejects with — mirrors the retained
+            // splitRelCsvByLabelPair's `throw streamError ?? err`.
+            throw relRouter.lastError ?? err;
+        }
         return {
             nodeFiles,
             relsByPair: relRouter.byPair,

package/dist/core/lbug/lbug-adapter.d.ts

@@ -1,5 +1,6 @@
 import lbug from '@ladybugdb/core';
 import { KnowledgeGraph } from '../graph/types.js';
+import { NodeTableName } from './schema.js';
 import type { PdgEmitManifest } from './pdg-emit-sink.js';
 import type { CachedEmbedding } from '../embeddings/types.js';
 import { type ExtensionEnsureOptions } from './extension-loader.js';
@@ -54,6 +55,18 @@ export declare const withLbugDb: <T>(dbPath: string, operation: () => Promise<T>
     readOnly?: boolean;
 }) => Promise<T>;
 export type LbugProgressCallback = (message: string) => void;
+/**
+ * Persist a KnowledgeGraph: stream CSVs, then bulk-COPY nodes (overlapped with
+ * relationship emit — see the body) and relationships.
+ *
+ * NOT TRANSACTIONAL (#2226). Each `COPY` commits independently and there is no
+ * surrounding transaction, so a failure partway through — a node `COPY` that
+ * throws at the FK barrier, a relationship `COPY` failure, or a `pdgEmitManifest`
+ * collision raised after node rows have already committed in the overlap path —
+ * leaves a partially-loaded DB. The caller surfaces the error; recovery is a
+ * `--force` re-analyze (a full rebuild), not a partial retry. Callers must not
+ * assume the DB is either fully loaded or untouched after a rejection.
+ */
 export declare const loadGraphToLbug: (graph: KnowledgeGraph, repoPath: string, storagePath: string, onProgress?: LbugProgressCallback, 
 /**
  * Streamed PDG-emit manifest (#2202). When present (streaming was on, full
@@ -69,6 +82,8 @@ pdgEmitManifest?: PdgEmitManifest) => Promise<{
     skippedRels: number;
     warnings: string[];
 }>;
+export declare const COPY_CSV_OPTS = "(HEADER=true, ESCAPE='\"', DELIM=',', QUOTE='\"', PARALLEL=false, auto_detect=false)";
+export declare const getCopyQuery: (table: NodeTableName, filePath: string) => string;
 /**
  * Insert a single node to LadybugDB
  * @param label - Node type (File, Function, Class, etc.)

package/dist/core/lbug/lbug-adapter.js

@@ -740,6 +740,60 @@ const doInitLbug = async (dbPath, readOnly = false) => {
     currentDbPath = dbPath;
     return { db, conn };
 };
+/**
+ * Run a COPY, retrying once with IGNORE_ERRORS=true (which skips row-level
+ * errors) on first failure. On a second failure, hand the RAW retry error to
+ * `onError` — each call site formats + slices its own message (#2226 F5: node
+ * COPY slices to 200 chars and throws; relationship COPY slices to 80 and warns,
+ * so the helper must not pre-format and lose that distinction). `onError` may
+ * throw to propagate the failure.
+ */
+const copyCsvWithRetry = async (targetConn, copyQuery, onError) => {
+    try {
+        await queryAndDrain(targetConn, copyQuery);
+    }
+    catch {
+        try {
+            const retryQuery = copyQuery.replace('auto_detect=false)', 'auto_detect=false, IGNORE_ERRORS=true)');
+            await queryAndDrain(targetConn, retryQuery);
+        }
+        catch (retryErr) {
+            onError(retryErr);
+        }
+    }
+};
+/**
+ * Bulk-COPY every node CSV sequentially on the single writable connection
+ * (LadybugDB allows one write txn at a time). Extracted from loadGraphToLbug so
+ * it can run either at the node-phase boundary — overlapping the relationship
+ * emit pass (#2203) — or after emit in the serial escape-hatch path. Each COPY
+ * keeps the IGNORE_ERRORS=true retry; a hard failure throws (no node rows ⇒ the
+ * relationship COPY would dangle on missing endpoints).
+ */
+const copyNodeCSVs = async (targetConn, nodeFileEntries, log, totalSteps) => {
+    let stepsDone = 0;
+    for (const [table, { csvPath, rows }] of nodeFileEntries) {
+        stepsDone++;
+        log(`Loading nodes ${stepsDone}/${totalSteps}: ${table} (${rows.toLocaleString()} rows)`);
+        const copyQuery = getCopyQuery(table, normalizeCopyPath(csvPath));
+        await copyCsvWithRetry(targetConn, copyQuery, (retryErr) => {
+            const retryMsg = retryErr instanceof Error ? retryErr.message : String(retryErr);
+            throw new Error(`COPY failed for ${table}: ${retryMsg.slice(0, 200)}`);
+        });
+    }
+};
+/**
+ * Persist a KnowledgeGraph: stream CSVs, then bulk-COPY nodes (overlapped with
+ * relationship emit — see the body) and relationships.
+ *
+ * NOT TRANSACTIONAL (#2226). Each `COPY` commits independently and there is no
+ * surrounding transaction, so a failure partway through — a node `COPY` that
+ * throws at the FK barrier, a relationship `COPY` failure, or a `pdgEmitManifest`
+ * collision raised after node rows have already committed in the overlap path —
+ * leaves a partially-loaded DB. The caller surfaces the error; recovery is a
+ * `--force` re-analyze (a full rebuild), not a partial retry. Callers must not
+ * assume the DB is either fully loaded or untouched after a rejection.
+ */
 export const loadGraphToLbug = async (graph, repoPath, storagePath, onProgress, 
 /**
  * Streamed PDG-emit manifest (#2202). When present (streaming was on, full
@@ -761,31 +815,87 @@ pdgEmitManifest) => {
     // the gap that the DB-persistence path is un-timed today (the analyze
     // "emit" number is the scope-resolution emit bucket, not this COPY path).
     const PROF = process.env.PROF_LBUG_LOAD === '1';
+    // Escape hatch / differential oracle (#2203): force the legacy strictly-serial
+    // load order (emit everything, THEN COPY nodes, THEN COPY rels) instead of the
+    // default node-COPY ‖ rel-emit overlap. Lets an operator revert the behavior at
+    // runtime, and lets a test load the same graph both ways and assert identical
+    // persisted content.
+    const SERIAL = process.env.GITNEXUS_SERIAL_LBUG_LOAD === '1';
     const mark = () => (PROF ? process.hrtime.bigint() : 0n);
     const span = (a, b) => (Number(b - a) / 1e6).toFixed(1);
     const tStart = mark();
     const csvDir = resolveNativeSafeStorageDir(storagePath, 'csv');
-    log('Streaming CSVs to disk...');
-    const csvResult = await streamAllCSVsToDisk(graph, repoPath, csvDir);
-    // Merge the streamed PDG-emit CSVs (#2202) into the COPY plan so the
-    // BasicBlock node table + per-pair PDG edges (CFG / REACHING_DEF / CDG /
-    // POST_DOMINATE / TAINTED / SANITIZES) load through the SAME node + per-pair
-    // COPY loops as the structural CSVs. The graph held zero BasicBlocks when
-    // streaming, so `streamAllCSVsToDisk` produced none of these — the manifest
-    // is the sole source and there is no double-COPY. Absent ⇒ no-op.
-    if (pdgEmitManifest) {
+    // The single writable connection (LadybugDB is single-writer). Captured as a
+    // const so the node-COPY closure has a non-null reference — TS cannot narrow
+    // the reassignable module-level `conn` across the callback boundary.
+    const writeConn = conn;
+    const validTables = new Set(NODE_TABLES);
+    // Merge the streamed PDG-emit node CSVs (#2202) into a node-file map. Collision
+    // guard: a BasicBlock in the in-memory graph during a streamed run is an
+    // invariant violation (streamAllCSVsToDisk would also emit basicblock.csv), so
+    // fail loudly rather than drop rows (#2202 review #3). Runs at the node-phase
+    // boundary so the manifest BasicBlock table COPYs with the structural CSVs.
+    const mergeManifestNodeFiles = (nodeFilesMap) => {
+        if (!pdgEmitManifest)
+            return;
         for (const [table, meta] of pdgEmitManifest.nodeFiles) {
-            // A collision means a BasicBlock leaked into the in-memory graph during a
-            // streamed run (streamAllCSVsToDisk then emitted a structural basicblock.csv).
-            // That is a streaming-invariant violation — fail loudly rather than
-            // silently overwrite one CSV with the other and drop its rows (#2202 review #3).
-            if (csvResult.nodeFiles.has(table)) {
+            if (nodeFilesMap.has(table)) {
                 throw new Error(`Streaming PDG manifest collides with a structural node CSV for "${table}" — ` +
                     `the in-memory graph should hold zero ${table} nodes when streaming. ` +
                     `A ${table} node leaked into the graph during a streamed emit.`);
             }
-            csvResult.nodeFiles.set(table, meta);
+            nodeFilesMap.set(table, meta);
         }
+    };
+    // Node COPY is the only DB write that can overlap relationship CSV emit: the
+    // rel pass writes new rel_*.csv files and never touches `conn`, while node COPY
+    // uses `conn` and never touches the rel files. We start node COPY at the
+    // node-phase boundary and let the rel pass run concurrently — the only
+    // single-writer-safe parallelism (#2203). The rel COPY still waits for node
+    // COPY (FK precondition), so the DB load order is unchanged.
+    let nodeCopyPromise;
+    let nodeCopyError;
+    const beginNodeCopy = (nodeFilesMap) => {
+        mergeManifestNodeFiles(nodeFilesMap);
+        const entries = [...nodeFilesMap.entries()];
+        // copyNodeCSVs logs node progress as step/total; it processes only node
+        // tables (the rel COPY has its own "Loading edges" progress line), so the
+        // denominator is the node-table count — not +1 reserving a rel step.
+        // .catch captures the failure so an overlapped (mid-emit) rejection cannot
+        // surface as an unhandled rejection; it is rethrown at the FK barrier below.
+        nodeCopyPromise = copyNodeCSVs(writeConn, entries, log, entries.length).catch((e) => {
+            nodeCopyError = e;
+        });
+    };
+    log('Streaming CSVs to disk...');
+    let csvResult;
+    try {
+        csvResult = SERIAL
+            ? await streamAllCSVsToDisk(graph, repoPath, csvDir)
+            : await streamAllCSVsToDisk(graph, repoPath, csvDir, beginNodeCopy);
+    }
+    catch (emitErr) {
+        // Relationship emit failed. In overlap mode a node COPY may be in flight —
+        // settle it (the .catch above means this never rejects) before rethrowing so
+        // it cannot leak as an unhandled rejection.
+        if (nodeCopyPromise)
+            await nodeCopyPromise;
+        // If node COPY ALSO failed, emitErr wins the throw — log the swallowed node
+        // error so a half-loaded DB isn't misattributed to the emit failure alone.
+        if (nodeCopyError) {
+            logger.warn({ err: nodeCopyError }, '[lbug-load] node COPY also failed while relationship emit was failing');
+        }
+        throw emitErr;
+    }
+    const tCsv = mark();
+    // Merge the streamed PDG-emit per-pair rel CSVs (#2202) into the COPY plan —
+    // collision-guarded. Done BEFORE node COPY so the serial escape hatch detects a
+    // manifest/structural pair collision before committing any node rows (legacy
+    // parity with the pre-overlap path), and the overlap path detects it as early
+    // as csvResult is available. When a manifest is present, streaming was on and
+    // the in-memory graph held zero BasicBlocks, so a structural collision means a
+    // streaming-invariant violation — fail loudly rather than load corrupt data.
+    if (pdgEmitManifest) {
         for (const [pairKey, meta] of pdgEmitManifest.relsByPair) {
             if (csvResult.relsByPair.has(pairKey)) {
                 throw new Error(`Streaming PDG manifest collides with a structural relationship CSV for pair ` +
@@ -795,30 +905,17 @@ pdgEmitManifest) => {
             csvResult.totalValidRels += meta.rows;
         }
     }
-    const tCsv = mark();
-    const validTables = new Set(NODE_TABLES);
-    // Bulk COPY all node CSVs (sequential — LadybugDB allows only one write txn at a time)
-    const nodeFiles = [...csvResult.nodeFiles.entries()];
-    const totalSteps = nodeFiles.length + 1; // +1 for relationships
-    let stepsDone = 0;
-    for (const [table, { csvPath, rows }] of nodeFiles) {
-        stepsDone++;
-        log(`Loading nodes ${stepsDone}/${totalSteps}: ${table} (${rows.toLocaleString()} rows)`);
-        const normalizedPath = normalizeCopyPath(csvPath);
-        const copyQuery = getCopyQuery(table, normalizedPath);
-        try {
-            await queryAndDrain(conn, copyQuery);
-        }
-        catch (err) {
-            try {
-                const retryQuery = copyQuery.replace('auto_detect=false)', 'auto_detect=false, IGNORE_ERRORS=true)');
-                await queryAndDrain(conn, retryQuery);
-            }
-            catch (retryErr) {
-                const retryMsg = retryErr instanceof Error ? retryErr.message : String(retryErr);
-                throw new Error(`COPY failed for ${table}: ${retryMsg.slice(0, 200)}`);
-            }
-        }
+    // Serial path: all CSVs are on disk and node COPY has not started — start it
+    // here so the barrier below blocks on it exactly as the legacy path did.
+    if (SERIAL)
+        beginNodeCopy(csvResult.nodeFiles);
+    // FK barrier: node rows must exist before the relationship COPY resolves their
+    // endpoints. In overlap mode most of node COPY was hidden behind rel emit, so
+    // this await is the *residual* node-COPY time (≈0 when fully overlapped).
+    if (nodeCopyPromise)
+        await nodeCopyPromise;
+    if (nodeCopyError) {
+        throw nodeCopyError instanceof Error ? nodeCopyError : new Error(String(nodeCopyError));
     }
     const tCopyNodes = mark();
     // Bulk COPY relationships. They were already routed to per-FROM→TO-label-pair
@@ -838,25 +935,17 @@ pdgEmitManifest) => {
             pairIdx++;
             const [fromLabel, toLabel] = pairKey.split('|');
             const normalizedPath = normalizeCopyPath(pairCsvPath);
+            // PARALLEL=false is load-bearing here too — see COPY_CSV_OPTS (#2203 / kuzudb/kuzu#5778).
             const copyQuery = `COPY ${REL_TABLE_NAME} FROM "${normalizedPath}" (from="${fromLabel}", to="${toLabel}", HEADER=true, ESCAPE='"', DELIM=',', QUOTE='"', PARALLEL=false, auto_detect=false)`;
             if (pairIdx % 5 === 0 || rows > 1000) {
                 log(`Loading edges: ${pairIdx}/${relsByPair.size} types (${fromLabel} -> ${toLabel})`);
             }
-            try {
-                await queryAndDrain(conn, copyQuery);
-            }
-            catch (err) {
-                try {
-                    const retryQuery = copyQuery.replace('auto_detect=false)', 'auto_detect=false, IGNORE_ERRORS=true)');
-                    await queryAndDrain(conn, retryQuery);
-                }
-                catch (retryErr) {
-                    const retryMsg = retryErr instanceof Error ? retryErr.message : String(retryErr);
-                    warnings.push(`${fromLabel}->${toLabel} (${rows} edges): ${retryMsg.slice(0, 80)}`);
-                    failedPairEdges += rows;
-                    failedPairCsvPaths.add(pairCsvPath);
-                }
-            }
+            await copyCsvWithRetry(conn, copyQuery, (retryErr) => {
+                const retryMsg = retryErr instanceof Error ? retryErr.message : String(retryErr);
+                warnings.push(`${fromLabel}->${toLabel} (${rows} edges): ${retryMsg.slice(0, 80)}`);
+                failedPairEdges += rows;
+                failedPairCsvPaths.add(pairCsvPath);
+            });
             // Only delete if not in failedPairCsvPaths (needed for fallback)
             if (!failedPairCsvPaths.has(pairCsvPath)) {
                 try {
@@ -919,7 +1008,12 @@ pdgEmitManifest) => {
         let totalNodeRows = 0;
         for (const [, { rows }] of csvResult.nodeFiles)
             totalNodeRows += rows;
-        logger.warn(`[lbug-load prof] csv-emit=${span(tStart, tCsv)}ms ` +
+        // `mode` records which load path ran. In overlap mode `csv-emit` is the wall
+        // to streamAllCSVsToDisk's return (node COPY overlapped part of it) and
+        // `copy-nodes` is the RESIDUAL node-COPY await after emit returned — it
+        // trends to 0 as the overlap hides node COPY behind relationship emit. In
+        // serial mode the buckets carry their legacy, disjoint meaning.
+        logger.warn(`[lbug-load prof] mode=${SERIAL ? 'serial' : 'overlap'} csv-emit=${span(tStart, tCsv)}ms ` +
             `copy-nodes=${span(tCsv, tCopyNodes)}ms copy-rels=${span(tCopyNodes, tCopyRels)}ms ` +
             `fallback=${span(tCopyRels, tFallback)}ms total=${span(tStart, tEnd)}ms ` +
             `(${totalNodeRows} nodes, ${insertedRels} rels)`);
@@ -930,7 +1024,18 @@ pdgEmitManifest) => {
 // Source code content is full of backslashes which confuse the auto-detection.
 // We MUST explicitly set ESCAPE='"' to use RFC 4180 escaping, and disable auto_detect to prevent
 // LadybugDB from overriding our settings based on sample rows.
-const COPY_CSV_OPTS = `(HEADER=true, ESCAPE='"', DELIM=',', QUOTE='"', PARALLEL=false, auto_detect=false)`;
+//
+// PARALLEL=false IS LOAD-BEARING FOR CORRECTNESS — DO NOT FLIP IT (#2203).
+// LadybugDB's parallel CSV reader (Kuzu-derived; default PARALLEL=true) splits the
+// file into byte ranges parsed concurrently, and CANNOT determine line boundaries
+// when a quoted field contains an embedded newline — it errors with "Quoted newlines
+// are not supported in parallel CSV reader. Please specify PARALLEL=FALSE", or worse,
+// mis-parses silently (upstream kuzudb/kuzu#5778, still open). Our `content`/`text`
+// columns hold source code, so quoted multiline fields are guaranteed. PARALLEL=false
+// is therefore required, not conservative. The multiline-quoted round-trip in
+// test/integration/copy-parallel-invariant.test.ts fails loudly if this is ever flipped.
+// Exported so that test asserts the invariant statically as well.
+export const COPY_CSV_OPTS = `(HEADER=true, ESCAPE='"', DELIM=',', QUOTE='"', PARALLEL=false, auto_detect=false)`;
 // Multi-language table names that were created with backticks in CODE_ELEMENT_BASE
 // and must always be referenced with backticks in queries
 const BACKTICK_TABLES = new Set([
@@ -996,7 +1101,7 @@ const TABLES_WITH_EXPORTED = new Set([
     'Method',
     'CodeElement',
 ]);
-const getCopyQuery = (table, filePath) => {
+export const getCopyQuery = (table, filePath) => {
     const t = escapeTableName(table);
     if (table === 'File') {
         return `COPY ${t}(id, name, filePath, content) FROM "${filePath}" ${COPY_CSV_OPTS}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.8-rc.46",
+  "version": "1.6.8-rc.47",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",