gitnexus 1.6.8-rc.9 → 1.6.8

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

@@ -4,20 +4,28 @@ import { createInterface } from 'readline';
 import { once } from 'events';
 import { finished } from 'stream/promises';
 import path from 'path';
-import os from 'os';
-import crypto from 'crypto';
 import lbug from '@ladybugdb/core';
 import { closeQueryResults } from './query-result-utils.js';
 import { NODE_TABLES, REL_TABLE_NAME, SCHEMA_QUERIES, EMBEDDING_TABLE_NAME, CREATE_VECTOR_INDEX_QUERY, STALE_HASH_SENTINEL, } from './schema.js';
 import { streamAllCSVsToDisk } from './csv-generator.js';
+import { getNodeLabel as deriveNodeLabel } from './rel-pair-routing.js';
 import { extensionManager } from './extension-loader.js';
-import { closeLbugConnection, isDbBusyError, isOpenRetryExhausted, isWalCorruptionError, openLbugConnection, toNativeSafePath, WAL_RECOVERY_SUGGESTION, waitForWindowsHandleRelease, } from './lbug-config.js';
+import { closeLbugConnection, isDbBusyError, isOpenRetryExhausted, isWalCorruptionError, openLbugConnection, toNativeSafePath, resolveNativeSafeStorageDir, WAL_RECOVERY_SUGGESTION, waitForWindowsHandleRelease, } from './lbug-config.js';
 import { finalizeLbugSidecarsAfterClose, inspectLbugSidecars, isMissingShadowSidecarError, isReadOnlyShadowReplayError, preflightLbugSidecars, quarantineWalForMissingShadow, renameFailureMessage, shadowSidecarRecoveryMessage, } from './sidecar-recovery.js';
 import { isVectorExtensionSupportedByPlatform } from '../platform/capabilities.js';
 import { logger } from '../logger.js';
 /**
  * Split a relationship CSV into per-label-pair files on disk.
  *
+ * @internal RETAINED AS A DIFFERENTIAL ORACLE. As of #2203 U2, production emit
+ * routes relationships to per-pair files directly during the single pass (see
+ * RelPairRouter in `rel-pair-routing.ts`), so this function has NO production
+ * callers — it is kept ONLY so the byte-identity test in
+ * `test/integration/csv-pipeline.test.ts` ("direct per-pair emit matches the
+ * split oracle") can diff the direct-emit output against this proven path. Do
+ * NOT delete it as dead code without also removing that test and accepting the
+ * loss of the byte-identity guard (and likewise `test/unit/rel-csv-split.test.ts`).
+ *
  * Streams the CSV line-by-line, routing each relationship to a file named
  * `rel_{fromLabel}_{toLabel}.csv`. Handles backpressure correctly: only one
  * drain listener per stream at a time, and readline resumes only when ALL
@@ -732,91 +740,212 @@ const doInitLbug = async (dbPath, readOnly = false) => {
     currentDbPath = dbPath;
     return { db, conn };
 };
-export const loadGraphToLbug = async (graph, repoPath, storagePath, onProgress) => {
-    if (!conn) {
-        throw new Error('LadybugDB not initialized. Call initLbug first.');
-    }
-    const log = onProgress || (() => { });
-    let csvDir;
-    if (process.platform === 'win32' && /[^\x00-\x7F]/.test(storagePath)) {
-        const hash = crypto.createHash('sha256').update(storagePath).digest('hex').slice(0, 16);
-        csvDir = toNativeSafePath(path.join(os.tmpdir(), `gitnexus-csv-${hash}`));
+/**
+ * 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);
     }
-    else {
-        csvDir = path.join(storagePath, 'csv');
+    catch {
+        try {
+            const retryQuery = copyQuery.replace('auto_detect=false)', 'auto_detect=false, IGNORE_ERRORS=true)');
+            await queryAndDrain(targetConn, retryQuery);
+        }
+        catch (retryErr) {
+            onError(retryErr);
+        }
     }
-    log('Streaming CSVs to disk...');
-    const csvResult = await streamAllCSVsToDisk(graph, repoPath, csvDir);
-    const validTables = new Set(NODE_TABLES);
-    const getNodeLabel = (nodeId) => {
-        if (nodeId.startsWith('comm_'))
-            return 'Community';
-        if (nodeId.startsWith('proc_'))
-            return 'Process';
-        return nodeId.split(':')[0];
-    };
-    // 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
+};
+/**
+ * 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 nodeFiles) {
+    for (const [table, { csvPath, rows }] of nodeFileEntries) {
         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)}`);
+        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
+ * rebuild), the BasicBlock node CSV + per-pair PDG-edge CSVs it points at
+ * were already flushed to disk during the emit loop; they are merged into the
+ * COPY plan below so they load alongside the structural CSVs. When streaming
+ * was on the in-memory `graph` holds zero BasicBlocks, so `streamAllCSVsToDisk`
+ * emits none — the manifest is the sole source and there is no double-COPY.
+ */
+pdgEmitManifest) => {
+    if (!conn) {
+        throw new Error('LadybugDB not initialized. Call initLbug first.');
+    }
+    const log = onProgress || (() => { });
+    // ── #2203 persistence-path profiling ──────────────────────────────────
+    // Mirrors the PROF_SCOPE_RESOLUTION pattern (scope-resolution/pipeline/
+    // run.ts): zero-cost when off — process.hrtime.bigint() is only read under
+    // PROF_LBUG_LOAD=1, and the summary is logged behind the same gate. Fills
+    // 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');
+    // 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) {
+            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.`);
             }
+            nodeFilesMap.set(table, meta);
         }
-    }
-    // Bulk COPY relationships — split by FROM→TO label pair (LadybugDB requires it)
-    const { relHeader, relsByPairMeta, pairWriteStreams, skippedRels, totalValidRels } = await splitRelCsvByLabelPair(csvResult.relCsvPath, csvDir, validTables, getNodeLabel);
-    // Close all per-pair write streams before COPY. `stream/promises.finished`
-    // resolves on the stream's 'finish' event and rejects on 'error' — replaces
-    // a hand-rolled promisification with the stdlib primitive.
-    await Promise.all(Array.from(pairWriteStreams.values()).map(async (ws) => {
-        ws.end();
-        await finished(ws);
-    }));
+    };
+    // 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 ` +
+                    `"${pairKey}" — a PDG edge leaked into the in-memory graph during a streamed emit.`);
+            }
+            csvResult.relsByPair.set(pairKey, meta);
+            csvResult.totalValidRels += meta.rows;
+        }
+    }
+    // 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
+    // files during the emit pass (#2203 U2) — there is no monolithic relations.csv
+    // to re-read/re-split here; we COPY each pair file directly.
+    const { relsByPair, relHeader, skippedRels, totalValidRels } = csvResult;
+    let tCopyRels = tCopyNodes;
+    let tFallback = tCopyNodes;
     const insertedRels = totalValidRels;
     const warnings = [];
     if (insertedRels > 0) {
-        log(`Loading edges: ${insertedRels.toLocaleString()} across ${relsByPairMeta.size} types`);
+        log(`Loading edges: ${insertedRels.toLocaleString()} across ${relsByPair.size} types`);
         let pairIdx = 0;
         let failedPairEdges = 0;
         const failedPairCsvPaths = new Set();
-        for (const [pairKey, { csvPath: pairCsvPath, rows }] of relsByPairMeta) {
+        for (const [pairKey, { csvPath: pairCsvPath, rows }] of relsByPair) {
             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}/${relsByPairMeta.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);
-                }
+                log(`Loading edges: ${pairIdx}/${relsByPair.size} types (${fromLabel} -> ${toLabel})`);
             }
+            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 {
@@ -825,6 +954,7 @@ export const loadGraphToLbug = async (graph, repoPath, storagePath, onProgress)
                 catch { }
             }
         }
+        tCopyRels = mark();
         if (failedPairCsvPaths.size > 0) {
             log(`Inserting ${failedPairEdges} edges individually (missing schema pairs)`);
             // Read failed pair files and merge for fallback inserts
@@ -846,15 +976,13 @@ export const loadGraphToLbug = async (graph, repoPath, storagePath, onProgress)
                 catch { }
             }
             if (allLines.length > 1) {
-                await fallbackRelationshipInserts(allLines, validTables, getNodeLabel);
+                await fallbackRelationshipInserts(allLines, validTables, deriveNodeLabel);
             }
         }
+        tFallback = mark();
     }
-    // Cleanup all CSVs
-    try {
-        await fs.unlink(csvResult.relCsvPath);
-    }
-    catch { }
+    // Cleanup all CSVs (per-pair rel files are unlinked in the COPY loop above;
+    // the remaining sweep below catches node CSVs + any leftover pair files).
     for (const [, { csvPath }] of csvResult.nodeFiles) {
         try {
             await fs.unlink(csvPath);
@@ -875,13 +1003,39 @@ export const loadGraphToLbug = async (graph, repoPath, storagePath, onProgress)
         await fs.rmdir(csvDir);
     }
     catch { }
+    if (PROF) {
+        const tEnd = mark();
+        let totalNodeRows = 0;
+        for (const [, { rows }] of csvResult.nodeFiles)
+            totalNodeRows += rows;
+        // `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)`);
+    }
     return { success: true, insertedRels, skippedRels, warnings };
 };
 // LadybugDB default ESCAPE is '\' (backslash), but our CSV uses RFC 4180 escaping ("" for literal quotes).
 // 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([
@@ -947,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}`;
@@ -965,14 +1119,16 @@ const getCopyQuery = (table, filePath) => {
         return `COPY ${t}(id, name, filePath, startLine, endLine, level, content, description) FROM "${filePath}" ${COPY_CSV_OPTS}`;
     }
     if (table === 'Route') {
-        return `COPY ${t}(id, name, filePath, responseKeys, errorKeys, middleware) FROM "${filePath}" ${COPY_CSV_OPTS}`;
+        return `COPY ${t}(id, name, filePath, responseKeys, errorKeys, middleware, method) FROM "${filePath}" ${COPY_CSV_OPTS}`;
     }
     if (table === 'Tool') {
         return `COPY ${t}(id, name, filePath, description) FROM "${filePath}" ${COPY_CSV_OPTS}`;
     }
     if (table === 'BasicBlock') {
-        // Taint/PDG substrate (issue #2080) — no name column.
-        return `COPY ${t}(id, filePath, startLine, endLine, text) FROM "${filePath}" ${COPY_CSV_OPTS}`;
+        // Taint/PDG substrate (issue #2080) — no name column. `callees` is the
+        // statement-precise inter-procedural reach substrate (space-joined leaf names);
+        // `calleeIds` is its SOUND parallel (space-joined resolved callee ids, #2227).
+        return `COPY ${t}(id, filePath, startLine, endLine, text, callees, calleeIds) FROM "${filePath}" ${COPY_CSV_OPTS}`;
     }
     if (table === 'Method') {
         return `COPY ${t}(id, name, filePath, startLine, endLine, isExported, content, description, parameterCount, returnType) FROM "${filePath}" ${COPY_CSV_OPTS}`;
@@ -1024,8 +1180,9 @@ export const insertNodeToLbug = async (label, properties, dbPath) => {
             query = `CREATE (n:Section {id: ${escapeValue(properties.id)}, name: ${escapeValue(properties.name)}, filePath: ${escapeValue(properties.filePath)}, startLine: ${properties.startLine || 0}, endLine: ${properties.endLine || 0}, level: ${properties.level || 1}, content: ${escapeValue(properties.content || '')}${descPart}})`;
         }
         else if (label === 'BasicBlock') {
-            // Taint/PDG substrate (issue #2080) — no name column.
-            query = `CREATE (n:BasicBlock {id: ${escapeValue(properties.id)}, filePath: ${escapeValue(properties.filePath)}, startLine: ${properties.startLine || 0}, endLine: ${properties.endLine || 0}, text: ${escapeValue(properties.text || '')}})`;
+            // Taint/PDG substrate (issue #2080) — no name column. `calleeIds` (#2227)
+            // is the sound resolved-id parallel to the leaf-name `callees` set.
+            query = `CREATE (n:BasicBlock {id: ${escapeValue(properties.id)}, filePath: ${escapeValue(properties.filePath)}, startLine: ${properties.startLine || 0}, endLine: ${properties.endLine || 0}, text: ${escapeValue(properties.text || '')}, callees: ${escapeValue(properties.callees || '')}, calleeIds: ${escapeValue(properties.calleeIds || '')}})`;
         }
         else if (TABLES_WITH_EXPORTED.has(label)) {
             const descPart = properties.description
@@ -1111,8 +1268,9 @@ export const batchInsertNodesToLbug = async (nodes, dbPath) => {
                     query = `MERGE (n:Section {id: ${escapeValue(properties.id)}}) SET n.name = ${escapeValue(properties.name)}, n.filePath = ${escapeValue(properties.filePath)}, n.startLine = ${properties.startLine || 0}, n.endLine = ${properties.endLine || 0}, n.level = ${properties.level || 1}, n.content = ${escapeValue(properties.content || '')}${descPart}`;
                 }
                 else if (label === 'BasicBlock') {
-                    // Taint/PDG substrate (issue #2080) — no name column.
-                    query = `MERGE (n:BasicBlock {id: ${escapeValue(properties.id)}}) SET n.filePath = ${escapeValue(properties.filePath)}, n.startLine = ${properties.startLine || 0}, n.endLine = ${properties.endLine || 0}, n.text = ${escapeValue(properties.text || '')}`;
+                    // Taint/PDG substrate (issue #2080) — no name column. `calleeIds`
+                    // (#2227) is the sound resolved-id parallel to the `callees` set.
+                    query = `MERGE (n:BasicBlock {id: ${escapeValue(properties.id)}}) SET n.filePath = ${escapeValue(properties.filePath)}, n.startLine = ${properties.startLine || 0}, n.endLine = ${properties.endLine || 0}, n.text = ${escapeValue(properties.text || '')}, n.callees = ${escapeValue(properties.callees || '')}, n.calleeIds = ${escapeValue(properties.calleeIds || '')}`;
                 }
                 else if (TABLES_WITH_EXPORTED.has(label)) {
                     const descPart = properties.description
@@ -1629,6 +1787,110 @@ export const deleteAllCommunitiesAndProcesses = async () => {
     }
     return { nodesDeleted };
 };
+/**
+ * Drop every interprocedural `TAINT_PATH` relationship (#2084 M4 U6). Used at
+ * the start of an incremental `--pdg` writeback so the `taintSummaries` phase
+ * re-materialises them from scratch on the FULL recomputed graph.
+ *
+ * TAINT_PATH validity is a WHOLE-PROGRAM property (a flow A→C can be
+ * invalidated by a change to an INTERMEDIATE function whose file is neither A
+ * nor C). The endpoint-writability extract rule (`extractChangedSubgraph`)
+ * cannot see that — an A→C edge between two unchanged files would be skipped
+ * and a stale finding would survive. So, exactly like Community/Process, the
+ * sound move is delete-all-then-rebuild: cheap because TAINT_PATH is sparse
+ * (per-run capped), and the compute side already rebuilds every summary each
+ * run. Relationship-level (TAINT_PATH is an edge type, not a node label), so a
+ * plain DELETE on the typed CodeRelation rows — endpoints are untouched.
+ */
+export const deleteAllInterprocTaintPaths = async () => {
+    if (!conn) {
+        throw new Error('LadybugDB not initialized. Call initLbug first.');
+    }
+    let edgesDeleted = 0;
+    let countResult;
+    try {
+        countResult = await conn.query(`MATCH ()-[r:CodeRelation]->() WHERE r.type = 'TAINT_PATH' RETURN count(r) AS cnt`);
+        const result = Array.isArray(countResult) ? countResult[0] : countResult;
+        const rows = await result.getAll();
+        const count = Number(rows[0]?.cnt ?? rows[0]?.[0] ?? 0);
+        if (count > 0) {
+            await conn.query(`MATCH ()-[r:CodeRelation]->() WHERE r.type = 'TAINT_PATH' DELETE r`);
+            edgesDeleted = count;
+        }
+    }
+    catch (err) {
+        // A missing table on a freshly-initialized DB is the benign, expected case
+        // (the count query above is what throws) — stay silent. Any OTHER failure
+        // (lock, disk, native error) would leave stale TAINT_PATH rows that the
+        // subsequent re-extract then DUPLICATES (CodeRelation has no PK), so it
+        // must ABORT the writeback (#2084 review P2-5): re-throw so the caller's
+        // crash-recovery dirty flag forces a clean full rebuild on the next run,
+        // rather than silently writing duplicate cross-function findings.
+        const msg = err instanceof Error ? err.message : String(err);
+        if (/no table|not exist|not found|does not exist|Table .* does not exist/i.test(msg)) {
+            if (countResult)
+                await closeQueryResults(countResult);
+            return { edgesDeleted };
+        }
+        if (countResult)
+            await closeQueryResults(countResult);
+        throw new Error(`[taint-interproc] failed to clear existing TAINT_PATH edges before incremental ` +
+            `re-write (${msg}) — aborting to avoid duplicate cross-function findings; ` +
+            `the next run will full-rebuild`);
+    }
+    if (countResult)
+        await closeQueryResults(countResult);
+    return { edgesDeleted };
+};
+/**
+ * Drop every `CALL_SUMMARY` relationship (PDG FU-C, U-C3). Used at the start of
+ * an incremental `--pdg` writeback so the `callSummaries` phase re-materialises
+ * them from scratch on the FULL recomputed graph.
+ *
+ * Mirrors {@link deleteAllInterprocTaintPaths}: CALL_SUMMARY is a self-loop edge
+ * type (not a node label), so a plain DELETE on the typed CodeRelation rows
+ * leaves endpoints untouched. `extractChangedSubgraph` re-includes ALL of them
+ * from the fresh graph (`isGraphWideRelType`), so delete-all-then-rebuild keeps
+ * an unchanged function's summary from being lost.
+ */
+export const deleteAllCallSummaries = async () => {
+    if (!conn) {
+        throw new Error('LadybugDB not initialized. Call initLbug first.');
+    }
+    let edgesDeleted = 0;
+    let countResult;
+    try {
+        countResult = await conn.query(`MATCH ()-[r:CodeRelation]->() WHERE r.type = 'CALL_SUMMARY' RETURN count(r) AS cnt`);
+        const result = Array.isArray(countResult) ? countResult[0] : countResult;
+        const rows = await result.getAll();
+        const count = Number(rows[0]?.cnt ?? rows[0]?.[0] ?? 0);
+        if (count > 0) {
+            await conn.query(`MATCH ()-[r:CodeRelation]->() WHERE r.type = 'CALL_SUMMARY' DELETE r`);
+            edgesDeleted = count;
+        }
+    }
+    catch (err) {
+        // A missing table on a freshly-initialized DB is the benign, expected case
+        // (the count query is what throws) — stay silent. Any OTHER failure would
+        // leave stale rows that the re-extract then DUPLICATES (CodeRelation has no
+        // PK), so it must ABORT the writeback: re-throw so the caller's crash-
+        // recovery dirty flag forces a clean full rebuild on the next run.
+        const msg = err instanceof Error ? err.message : String(err);
+        if (/no table|not exist|not found|does not exist|Table .* does not exist/i.test(msg)) {
+            if (countResult)
+                await closeQueryResults(countResult);
+            return { edgesDeleted };
+        }
+        if (countResult)
+            await closeQueryResults(countResult);
+        throw new Error(`[call-summary] failed to clear existing CALL_SUMMARY edges before incremental ` +
+            `re-write (${msg}) — aborting to avoid duplicate summaries; ` +
+            `the next run will full-rebuild`);
+    }
+    if (countResult)
+        await closeQueryResults(countResult);
+    return { edgesDeleted };
+};
 // ============================================================================
 // Full-Text Search (FTS) Functions
 // ============================================================================

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

@@ -1,6 +1,25 @@
 import type lbug from '@ladybugdb/core';
 export declare function cleanupNativePathJunctions(): void;
 export declare function toNativeSafePath(p: string): string;
+/**
+ * Resolve the on-disk CSV staging dir for `<storagePath>/<subdir>`, applying the
+ * same ASCII-safe relocation `toNativeSafePath` enables: on Windows with a
+ * non-ASCII storage path, LadybugDB's bulk COPY cannot open files under that
+ * path, so the dir is relocated under `os.tmpdir()`. Shared by the structural
+ * `csv/` dir and the streaming `pdg-csv/` dir (#2202) so the two can never
+ * diverge on platform handling; the `gitnexus-<subdir>-` prefix keeps their tmp
+ * locations distinct and recognizable.
+ *
+ * The relocated dir is created with `fs.mkdtempSync` (a unique, mode-0700,
+ * guaranteed-not-pre-existing suffix) rather than a deterministic
+ * `gitnexus-<subdir>-<hash>` name. A predictable name in the world-readable OS
+ * temp dir is information-disclosure-prone and pre-plantable
+ * (CWE-377/378 / CodeQL `js/insecure-temporary-file`); mkdtemp's random suffix
+ * is the documented mitigation and is what reaches the streaming sink's
+ * `fs.openSync`. The non-Windows / ASCII path stays a pure `path.join` (no dir
+ * created) and is byte-identical to before.
+ */
+export declare function resolveNativeSafeStorageDir(storagePath: string, subdir: string): string;
 /**
  * Shared configuration for `@ladybugdb/core` `Database` construction.
  *

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

@@ -179,6 +179,35 @@ export function toNativeSafePath(p) {
         '(fsutil 8dot3name set 0).');
     return p;
 }
+/**
+ * Resolve the on-disk CSV staging dir for `<storagePath>/<subdir>`, applying the
+ * same ASCII-safe relocation `toNativeSafePath` enables: on Windows with a
+ * non-ASCII storage path, LadybugDB's bulk COPY cannot open files under that
+ * path, so the dir is relocated under `os.tmpdir()`. Shared by the structural
+ * `csv/` dir and the streaming `pdg-csv/` dir (#2202) so the two can never
+ * diverge on platform handling; the `gitnexus-<subdir>-` prefix keeps their tmp
+ * locations distinct and recognizable.
+ *
+ * The relocated dir is created with `fs.mkdtempSync` (a unique, mode-0700,
+ * guaranteed-not-pre-existing suffix) rather than a deterministic
+ * `gitnexus-<subdir>-<hash>` name. A predictable name in the world-readable OS
+ * temp dir is information-disclosure-prone and pre-plantable
+ * (CWE-377/378 / CodeQL `js/insecure-temporary-file`); mkdtemp's random suffix
+ * is the documented mitigation and is what reaches the streaming sink's
+ * `fs.openSync`. The non-Windows / ASCII path stays a pure `path.join` (no dir
+ * created) and is byte-identical to before.
+ */
+export function resolveNativeSafeStorageDir(storagePath, subdir) {
+    if (process.platform === 'win32' && NON_ASCII_RE.test(storagePath)) {
+        // 8.3-shorten the tmpdir base first (a non-ASCII Windows *profile* path can
+        // make os.tmpdir() itself non-ASCII), THEN mkdtemp so the returned path —
+        // the one that flows into fs.openSync — is provably mkdtemp-sourced (random,
+        // exclusive) and clears the insecure-temp-file dataflow.
+        const base = toNativeSafePath(os.tmpdir());
+        return fsSync.mkdtempSync(path.join(base, `gitnexus-${subdir}-`));
+    }
+    return path.join(storagePath, subdir);
+}
 /**
  * Shared configuration for `@ladybugdb/core` `Database` construction.
  *