cgraphx 2.0.2 → 2.0.6

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

@@ -0,0 +1,2703 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveGateRows = exports.readIndexCatalogSnapshot = exports.INDEX_CATALOG_UNREADABLE = exports.readIndexCatalogRows = exports.indexRowType = exports.indexRowTable = exports.createVectorIndex = exports.loadVectorExtension = exports.deleteSpringAutoConfigurationSyntheticClasses = exports.deleteSpringAutoConfigurationDeclarations = exports.deleteSpringAopEvidenceNodes = exports.deleteAllAdvisedBy = exports.deleteAllInjects = exports.deleteAllCallSummaries = exports.deleteAllInterprocTaintPaths = exports.deleteAllCommunitiesAndProcesses = exports.queryImportersBatch = exports.queryImporters = exports.getEmbeddingTableName = exports.deleteNodesForFiles = exports.DELETE_FILES_CHUNK_SIZE = exports.deleteNodesForFile = exports.isLbugReady = exports.wipeLbugDbFiles = exports.LbugWipeError = exports.closeLbug = exports.closeLbugBeforeExit = exports.safeClose = exports.tryFlushWAL = exports.flushWAL = exports.fetchExistingEmbeddingHashes = exports.loadCachedEmbeddings = exports.getLbugStats = exports.executeWithReusedStatement = exports.executePrepared = exports.streamQuery = exports.executeQuery = exports.batchInsertNodesToLbug = exports.insertNodeToLbug = exports.getCopyQuery = exports.fallbackRelationshipInserts = exports.COPY_CSV_OPTS = exports.loadGraphToLbug = exports.withLbugDb = exports.initLbug = exports._initLockPathForTest = exports.acquireInitLock = exports.isReadOnlyDbError = exports.getDatabase = exports.splitRelCsvByLabelPair = void 0;
+exports.ensureEmbeddingRowDmlSafe = void 0;
+const promises_1 = __importDefault(require("fs/promises"));
+const fs_1 = require("fs");
+const readline_1 = require("readline");
+const events_1 = require("events");
+const promises_2 = require("stream/promises");
+const path_1 = __importDefault(require("path"));
+const lbug = __importStar(require("@ladybugdb/core"));
+const query_result_utils_js_1 = require("./query-result-utils.js");
+const cypher_escape_js_1 = require("./cypher-escape.js");
+const conn_lock_js_1 = require("./conn-lock.js");
+const wal_driver_state_js_1 = require("./wal-driver-state.js");
+const schema_js_1 = require("./schema.js");
+// Analyze-only, but reached from backend startup via `pool-adapter.js`. #2802
+// proposed lazy-importing it; rejected — deferring here relocates the startup
+// cost to first query rather than removing it. The measured figures live in
+// #2802; they were environment-bound, this is not.
+const csv_generator_js_1 = require("./csv-generator.js");
+const rel_pair_routing_js_1 = require("./rel-pair-routing.js");
+// embeddings 子系统已删除——EMBEDDABLE_LABELS 在此局部定义以维持文件路径节点删除
+// 查询的标签匹配（增量写回已删，但全量重建的清表路径仍需枚举可嵌入标签）。
+const EMBEDDABLE_LABELS = [
+    'Function', 'Method', 'Constructor', 'Class', 'Interface', 'Struct',
+    'Enum', 'Trait', 'Impl', 'Macro',
+    'TypeAlias', 'TypeDef', 'Const', 'Property', 'Record', 'Union', 'Static', 'Variable',
+    // Kept in sync with DOC_BEARING_LABELS (ast-helpers.ts) so every doc-bearing
+    // label's leading-doc description remains semantically matchable (#2270).
+    'Namespace',
+];
+const extension_loader_js_1 = require("./extension-loader.js");
+const lbug_config_js_1 = require("./lbug-config.js");
+const sidecar_recovery_js_1 = require("./sidecar-recovery.js");
+const logger_js_1 = require("../logger.js");
+const auto_configuration_js_1 = require("../ingestion/frameworks/spring/auto-configuration.js");
+const aop_js_1 = require("../ingestion/frameworks/spring/aop.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
+ * backpressured streams have drained.
+ *
+ * @param csvPath       Path to the combined relationship CSV
+ * @param csvDir        Directory to write per-pair CSV files
+ * @param validTables   Set of valid node table names
+ * @param getNodeLabel  Function to extract the label from a node ID
+ * @param wsFactory     Optional WriteStream factory (defaults to fs.createWriteStream)
+ */
+const splitRelCsvByLabelPair = async (csvPath, csvDir, validTables, getNodeLabel, wsFactory = (p) => (0, fs_1.createWriteStream)(p, 'utf-8')) => {
+    let relHeader = '';
+    const relsByPairMeta = new Map();
+    const pairWriteStreams = new Map();
+    let skippedRels = 0;
+    let totalValidRels = 0;
+    const inputStream = (0, fs_1.createReadStream)(csvPath, 'utf-8');
+    const rl = (0, readline_1.createInterface)({ input: inputStream, crlfDelay: Infinity });
+    // If any pair WriteStream errors (disk full, EMFILE, etc.) or the input
+    // stream fails, we need to abort the pending `once(ws, 'drain')` await.
+    // An AbortController gives us one signal to cancel all pending waits
+    // without a custom state machine.
+    const abortOnError = new AbortController();
+    let streamError = null;
+    const markStreamError = (err) => {
+        streamError ??= err;
+        abortOnError.abort(err);
+    };
+    try {
+        // `for await (const line of rl)` replaces the old manual
+        // on('line')/pause()/resume()/waitingForDrain state machine: readline's
+        // async iterator naturally serializes line delivery with our awaits, so
+        // at most one ws can be in backpressure at a time and we just await its
+        // 'drain' event.
+        let isFirst = true;
+        for await (const line of rl) {
+            if (streamError)
+                throw streamError;
+            if (isFirst) {
+                relHeader = line;
+                isFirst = false;
+                continue;
+            }
+            if (!line.trim())
+                continue;
+            const match = line.match(/"([^"]*)","([^"]*)"/);
+            if (!match) {
+                skippedRels++;
+                continue;
+            }
+            const fromLabel = getNodeLabel(match[1]);
+            const toLabel = getNodeLabel(match[2]);
+            if (!validTables.has(fromLabel) || !validTables.has(toLabel)) {
+                skippedRels++;
+                continue;
+            }
+            const pairKey = `${fromLabel}|${toLabel}`;
+            let ws = pairWriteStreams.get(pairKey);
+            if (!ws) {
+                const pairCsvPath = path_1.default.join(csvDir, `rel_${fromLabel}_${toLabel}.csv`);
+                ws = wsFactory(pairCsvPath);
+                ws.on('error', markStreamError);
+                pairWriteStreams.set(pairKey, ws);
+                relsByPairMeta.set(pairKey, { csvPath: pairCsvPath, rows: 0 });
+                if (!ws.write(relHeader + '\n')) {
+                    await (0, events_1.once)(ws, 'drain', { signal: abortOnError.signal });
+                }
+            }
+            if (!ws.write(line + '\n')) {
+                await (0, events_1.once)(ws, 'drain', { signal: abortOnError.signal });
+            }
+            relsByPairMeta.get(pairKey).rows++;
+            totalValidRels++;
+        }
+        if (streamError)
+            throw streamError;
+    }
+    catch (err) {
+        // Tear down everything so no fd is left dangling. If the abort was caused
+        // by a stream error, rethrow that error (more actionable than AbortError).
+        for (const ws of pairWriteStreams.values())
+            ws.destroy();
+        inputStream.destroy();
+        throw streamError ?? err;
+    }
+    finally {
+        // Readline 'close' fires before the underlying fs.ReadStream releases its
+        // fd — on Windows that race caused ENOTEMPTY on the parent dir.
+        // stream/promises.finished is the stdlib "wait until this stream is fully
+        // closed" primitive and handles both success and error paths.
+        await (0, promises_2.finished)(inputStream).catch(() => { });
+    }
+    return { relHeader, relsByPairMeta, pairWriteStreams, skippedRels, totalValidRels };
+};
+exports.splitRelCsvByLabelPair = splitRelCsvByLabelPair;
+let db = null;
+let conn = null;
+// Serialize every operation on the shared singleton `conn`. LadybugDB's
+// Connection is single-writer and is NOT safe for concurrent query execution;
+// the periodic WAL-checkpoint driver overlapping a long `--pdg` COPY on this
+// connection corrupted native state (`double free or corruption`). Each
+// singleton-`conn` helper below runs its full query + drain inside withConnLock.
+// Invariant: a wrapped helper MUST NOT call another wrapped helper (re-entry
+// self-deadlocks); all current holders are leaf-level. `streamQuery` is
+// deliberately NOT wrapped — its per-row callback can re-enter the adapter and
+// it only runs on the read path where the checkpoint driver is inactive.
+// See conn-lock.ts for the full rationale.
+//
+// The gate that decides whether an op must take withConnLock: only operations on
+// the shared singleton `conn` serialize. Per-file / temp connections (distinct
+// native objects with no shared engine state) must NOT block on — or be blocked
+// by — the singleton's lock. Reads the live `conn` binding at call time (it's
+// reassigned only at open/close, never mid-load).
+const isSharedSingletonConn = (c) => c === conn;
+let currentDbPath = null;
+let currentDbReadOnly = false;
+let vectorExtensionLoaded = false;
+// In-process guard so a repeated createVectorIndex() within one connection
+// lifetime skips the DB round-trip. Reset wherever vectorExtensionLoaded
+// resets, so it can never stay true against a swapped or closed connection.
+let vectorIndexEnsured = false;
+/**
+ * Check if an error indicates a missing column or table (schema-level problem)
+ * rather than a transient/connection error. Used for legacy DB fallback logic.
+ */
+const isMissingColumnOrTableError = (msg) => msg.includes('does not exist') ||
+    // Kuzu-specific: "(table|column|property) ... not found" — narrow enough to avoid
+    // matching transient errors like "connection not found" or "key not found".
+    /(table|column|property).*not found/i.test(msg);
+/** Expose the current Database for pool adapter reuse in tests. */
+const getDatabase = () => db;
+exports.getDatabase = getDatabase;
+// Global session lock for operations that touch module-level lbug globals.
+// This guarantees no DB switch can happen while an operation is running.
+let sessionLock = Promise.resolve();
+/** Number of times to retry on a BUSY / lock-held error before giving up. */
+const DB_LOCK_RETRY_ATTEMPTS = 3;
+/** Base back-off in ms between BUSY retries (multiplied by attempt number). */
+const DB_LOCK_RETRY_DELAY_MS = 500;
+/**
+ * Return true when the error message indicates a write was attempted against
+ * a read-only LadybugDB connection. The read pool opens DBs read-only, so any
+ * path that calls a `CREATE_*` procedure there will surface this. Owners of
+ * the writable analyze path should ignore this error — index creation is owned
+ * by `cgraph analyze` and either already happened or will happen on the next run.
+ */
+const isReadOnlyDbError = (err) => {
+    // Walk the `cause` chain (bounded) so a wrapped read-only error — e.g. the
+    // pool adapter's `new Error('…read-only.', { cause: nativeReadOnlyErr })` —
+    // is still detected by callers that only see the wrapper (#2068 follow-up).
+    // The same strict regex is re-applied at each level, so a non-read-only
+    // chain stays false; the depth bound guards a cyclic `cause`.
+    let cur = err;
+    for (let depth = 0; depth < 5 && cur != null; depth++) {
+        const msg = cur instanceof Error ? cur.message : String(cur);
+        if (/read-only database/i.test(msg))
+            return true;
+        cur = cur instanceof Error ? cur.cause : undefined;
+    }
+    return false;
+};
+exports.isReadOnlyDbError = isReadOnlyDbError;
+const isMissingFileError = (err) => {
+    const errno = err;
+    return errno?.code === 'ENOENT';
+};
+const extractErrnoCode = (err) => {
+    const errno = err;
+    return errno?.code;
+};
+const MAX_LOGGED_ERROR_MESSAGE_LENGTH = 160;
+const summarizeError = (err) => (err instanceof Error ? err.message : String(err)).slice(0, MAX_LOGGED_ERROR_MESSAGE_LENGTH);
+// ---------------------------------------------------------------------------
+// Cross-process init lock
+//
+// Prevents a TOCTOU race in orphan sidecar cleanup: between checking that
+// the main DB file is missing and unlinking sidecars, another process could
+// create a fresh DB. The lock file (`${dbPath}.init.lock`) is created with
+// O_CREAT | O_EXCL (atomic create-or-fail) and contains the owning PID +
+// timestamp so stale locks from crashed processes can be reclaimed.
+// ---------------------------------------------------------------------------
+/** Maximum age (ms) before an init lock is considered stale. */
+const INIT_LOCK_STALE_MS = 30_000;
+/** Maximum attempts to acquire the init lock before giving up. */
+const INIT_LOCK_MAX_ATTEMPTS = 6;
+/** Delay between lock-acquisition retries (ms). */
+const INIT_LOCK_RETRY_DELAY_MS = 500;
+const initLockPath = (dbPath) => `${dbPath}.init.lock`;
+/**
+ * Returns true when the process identified by `pid` is still running.
+ * Uses `process.kill(pid, 0)` which sends signal 0 (a no-op probe) —
+ * it throws ESRCH when the process does not exist.
+ */
+const isProcessAlive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Try to break a stale lock whose owning process has exited.
+ * Returns `true` if the stale lock was removed (caller should retry acquire).
+ * Returns `false` if the lock is still valid (another live process owns it).
+ */
+const tryBreakStaleLock = async (lockPath) => {
+    try {
+        const content = await promises_1.default.readFile(lockPath, 'utf-8');
+        const parsed = JSON.parse(content);
+        // If the owning process is still alive AND the lock is not stale, don't break.
+        if (typeof parsed.pid === 'number' && isProcessAlive(parsed.pid)) {
+            // Even a live process's lock can be stale if it's been held too long
+            // (e.g. the process is hung). Check the timestamp.
+            if (typeof parsed.ts === 'number' && Date.now() - parsed.ts < INIT_LOCK_STALE_MS) {
+                return false;
+            }
+        }
+        // PID is gone or lock exceeded INIT_LOCK_STALE_MS — reclaim it.
+        await promises_1.default.unlink(lockPath);
+        logger_js_1.logger.warn(`GitNexus: removed stale init lock (pid=${parsed.pid ?? '?'}, age=${typeof parsed.ts === 'number' ? `${Date.now() - parsed.ts}ms` : '?'})`);
+        return true;
+    }
+    catch (err) {
+        // Lock file disappeared between our read and unlink, or is unreadable.
+        // Either way, let the caller retry the acquire.
+        if (isMissingFileError(err))
+            return true;
+        // Permission error or corrupt content — log and let caller retry.
+        const code = extractErrnoCode(err);
+        logger_js_1.logger.warn(`GitNexus: unable to inspect init lock (${code ?? 'UNKNOWN'}): ${summarizeError(err)}`);
+        return false;
+    }
+};
+/**
+ * Acquire a cross-process init lock for `dbPath`.
+ * Uses `O_CREAT | O_EXCL` for atomic create-or-fail semantics.
+ *
+ * Returns a release function that removes the lock file. The release
+ * function is idempotent and safe to call even if the lock was already
+ * cleaned up externally.
+ *
+ * Throws if the lock cannot be acquired after `INIT_LOCK_MAX_ATTEMPTS`.
+ */
+const acquireInitLock = async (dbPath) => {
+    const lockPath = initLockPath(dbPath);
+    const payload = JSON.stringify({ pid: process.pid, ts: Date.now() });
+    // Ensure the parent directory exists before creating the lock file.
+    // On a fresh repo the `.cgraphx/code/` directory may not exist yet, and
+    // fs.open with O_CREAT | O_EXCL would fail with ENOENT.
+    await promises_1.default.mkdir(path_1.default.dirname(lockPath), { recursive: true });
+    for (let attempt = 1; attempt <= INIT_LOCK_MAX_ATTEMPTS; attempt++) {
+        try {
+            const handle = await promises_1.default.open(lockPath, fs_1.constants.O_CREAT | fs_1.constants.O_EXCL | fs_1.constants.O_WRONLY);
+            await handle.writeFile(payload);
+            await handle.close();
+            // Return the idempotent release function
+            return async () => {
+                try {
+                    await promises_1.default.unlink(lockPath);
+                }
+                catch (err) {
+                    if (!isMissingFileError(err)) {
+                        const code = extractErrnoCode(err);
+                        logger_js_1.logger.warn(`GitNexus: failed to release init lock (${code ?? 'UNKNOWN'}): ${summarizeError(err)}`);
+                    }
+                }
+            };
+        }
+        catch (err) {
+            if (err?.code !== 'EEXIST') {
+                throw err; // Unexpected error — propagate immediately
+            }
+            // Lock file exists — check if it's stale
+            const broken = await tryBreakStaleLock(lockPath);
+            if (broken && attempt < INIT_LOCK_MAX_ATTEMPTS) {
+                continue; // Stale lock removed — retry immediately
+            }
+            if (attempt === INIT_LOCK_MAX_ATTEMPTS) {
+                throw new Error(`GitNexus: unable to acquire init lock after ${INIT_LOCK_MAX_ATTEMPTS} attempts — ` +
+                    `another gitnexus process may be initializing the same database (${lockPath})`);
+            }
+            // Live process holds the lock — wait and retry
+            await new Promise((resolve) => setTimeout(resolve, INIT_LOCK_RETRY_DELAY_MS));
+        }
+    }
+    // Unreachable — loop always throws or returns
+    throw new Error('GitNexus: init lock acquisition failed unexpectedly');
+};
+exports.acquireInitLock = acquireInitLock;
+/** Exported for testing — returns the lock file path for a given dbPath. */
+exports._initLockPathForTest = initLockPath;
+const runWithSessionLock = async (operation) => {
+    const previous = sessionLock;
+    let release = null;
+    sessionLock = new Promise((resolve) => {
+        release = resolve;
+    });
+    await previous;
+    try {
+        return await operation();
+    }
+    finally {
+        release?.();
+    }
+};
+const normalizeCopyPath = (filePath) => (0, lbug_config_js_1.toNativeSafePath)(filePath).replace(/\\/g, '/');
+// Single-result convenience wrapper over the shared best-effort closer
+// (drainQueryResult / readQueryRows close one cursor at a time).
+const closeQueryResult = async (result) => {
+    await (0, query_result_utils_js_1.closeQueryResults)(result);
+};
+const drainQueryResult = async (queryResult) => {
+    const results = Array.isArray(queryResult) ? queryResult : [queryResult];
+    let firstError;
+    let hasError = false;
+    for (const result of results) {
+        try {
+            await result.getAll();
+        }
+        catch (err) {
+            if (!hasError) {
+                firstError = err;
+                hasError = true;
+            }
+        }
+        finally {
+            await closeQueryResult(result);
+        }
+    }
+    if (hasError)
+        throw firstError;
+};
+const readQueryRows = async (queryResult) => {
+    const results = Array.isArray(queryResult) ? queryResult : [queryResult];
+    let rows = [];
+    let firstError;
+    let hasError = false;
+    for (let i = 0; i < results.length; i++) {
+        const result = results[i];
+        try {
+            const resultRows = await result.getAll();
+            if (i === 0)
+                rows = resultRows;
+        }
+        catch (err) {
+            if (!hasError) {
+                firstError = err;
+                hasError = true;
+            }
+        }
+        finally {
+            await closeQueryResult(result);
+        }
+    }
+    if (hasError)
+        throw firstError;
+    return rows;
+};
+const queryAndDrain = async (targetConn, cypher) => {
+    const run = async () => {
+        const queryResult = await targetConn.query(cypher);
+        await drainQueryResult(queryResult);
+    };
+    // Serialize only when this runs on the shared singleton connection (the bulk
+    // node/relationship COPY captures `writeConn = conn`); per-file / temp
+    // connections skip the lock — see isSharedSingletonConn.
+    return isSharedSingletonConn(targetConn) ? (0, conn_lock_js_1.withConnLock)(run) : run();
+};
+// determinism: probe — existence only. Every call site runs this through
+// `queryAndDrain`, which drains and discards the rows; the ONLY observable is
+// whether the read-only shadow replay throws, so no row identity is read.
+const READ_ONLY_SHADOW_REPLAY_PROBE = 'MATCH (n) RETURN n LIMIT 1';
+/**
+ * Serve-side entry to the shared WAL-quarantine safety gate. Refuses (throws)
+ * when the `.shadow` is present on disk or the orphan WAL is too large to
+ * safely discard; returns silently otherwise. The policy itself lives in
+ * `guardWalQuarantine` (sidecar-recovery.ts) so serve and the MCP pool share
+ * one source of truth (PR #1747 review D2; issue #2382 review, Finding B).
+ */
+const refuseLargeWalQuarantine = async (dbPath, mode, triggeringErr) => {
+    await (0, sidecar_recovery_js_1.guardWalQuarantine)(dbPath, mode, triggeringErr, logger_js_1.logger);
+};
+const reopenReadOnlyAfterMissingShadow = async (dbPath, err) => {
+    await refuseLargeWalQuarantine(dbPath, 'read-only', err);
+    try {
+        await (0, sidecar_recovery_js_1.quarantineWalForMissingShadow)(dbPath, {
+            logger: logger_js_1.logger,
+            level: 'warn',
+            reason: 'read-only recovery',
+        });
+    }
+    catch (renameErr) {
+        throw new Error((0, sidecar_recovery_js_1.renameFailureMessage)(dbPath, renameErr));
+    }
+    const reopened = await (0, lbug_config_js_1.openLbugConnection)(lbug, dbPath, { readOnly: true });
+    try {
+        await queryAndDrain(reopened.conn, READ_ONLY_SHADOW_REPLAY_PROBE);
+        return reopened;
+    }
+    catch (retryErr) {
+        await (0, lbug_config_js_1.closeLbugConnection)(reopened);
+        if ((0, sidecar_recovery_js_1.isMissingShadowSidecarError)(retryErr) || (0, sidecar_recovery_js_1.isReadOnlyShadowReplayError)(retryErr)) {
+            throw new Error((0, sidecar_recovery_js_1.shadowSidecarRecoveryMessage)(dbPath, retryErr));
+        }
+        throw retryErr;
+    }
+};
+const reopenWritableAfterMissingShadow = async (dbPath, err) => {
+    await refuseLargeWalQuarantine(dbPath, 'writable', err);
+    try {
+        await (0, sidecar_recovery_js_1.quarantineWalForMissingShadow)(dbPath, {
+            logger: logger_js_1.logger,
+            level: 'warn',
+            reason: 'writable recovery',
+        });
+    }
+    catch (renameErr) {
+        throw new Error((0, sidecar_recovery_js_1.renameFailureMessage)(dbPath, renameErr));
+    }
+    return await (0, lbug_config_js_1.openLbugConnection)(lbug, dbPath);
+};
+const ensureReadOnlyConnectionUsable = async (dbPath, handle) => {
+    let shadowReplayErr;
+    try {
+        await queryAndDrain(handle.conn, READ_ONLY_SHADOW_REPLAY_PROBE);
+        return handle;
+    }
+    catch (err) {
+        if ((0, sidecar_recovery_js_1.isMissingShadowSidecarError)(err)) {
+            await (0, lbug_config_js_1.closeLbugConnection)(handle);
+            return await reopenReadOnlyAfterMissingShadow(dbPath, err);
+        }
+        if (!(0, sidecar_recovery_js_1.isReadOnlyShadowReplayError)(err)) {
+            await (0, lbug_config_js_1.closeLbugConnection)(handle);
+            throw err;
+        }
+        shadowReplayErr = err;
+    }
+    await (0, lbug_config_js_1.closeLbugConnection)(handle);
+    let writable;
+    try {
+        writable = await (0, lbug_config_js_1.openLbugConnection)(lbug, dbPath);
+    }
+    catch (openErr) {
+        const code = extractErrnoCode(openErr);
+        if (code === 'EROFS' || code === 'EACCES' || code === 'EPERM') {
+            throw new Error((0, sidecar_recovery_js_1.shadowSidecarRecoveryMessage)(dbPath, shadowReplayErr) +
+                '\n  The workspace appears to be read-only — mount it read-write to perform shadow replay recovery,' +
+                ' or re-run `cgraph analyze` on a writable filesystem to rebuild the index.');
+        }
+        throw openErr;
+    }
+    let missingShadowError;
+    try {
+        await queryAndDrain(writable.conn, READ_ONLY_SHADOW_REPLAY_PROBE);
+    }
+    catch (err) {
+        if ((0, sidecar_recovery_js_1.isMissingShadowSidecarError)(err)) {
+            missingShadowError = err;
+        }
+        else {
+            throw err;
+        }
+    }
+    finally {
+        await (0, lbug_config_js_1.closeLbugConnection)(writable);
+    }
+    if (missingShadowError) {
+        return await reopenReadOnlyAfterMissingShadow(dbPath, missingShadowError);
+    }
+    const reopened = await (0, lbug_config_js_1.openLbugConnection)(lbug, dbPath, { readOnly: true });
+    try {
+        await queryAndDrain(reopened.conn, READ_ONLY_SHADOW_REPLAY_PROBE);
+        return reopened;
+    }
+    catch (err) {
+        await (0, lbug_config_js_1.closeLbugConnection)(reopened);
+        if ((0, sidecar_recovery_js_1.isMissingShadowSidecarError)(err)) {
+            throw new Error((0, sidecar_recovery_js_1.shadowSidecarRecoveryMessage)(dbPath, err));
+        }
+        throw err;
+    }
+};
+const resetOpenConnectionState = () => {
+    currentDbPath = null;
+    vectorExtensionLoaded = false;
+    vectorIndexEnsured = false;
+};
+const runSchemaCreationQueries = async (dbPath) => {
+    for (const schemaQuery of schema_js_1.SCHEMA_QUERIES) {
+        try {
+            await queryAndDrain(conn, schemaQuery);
+        }
+        catch (err) {
+            if ((0, sidecar_recovery_js_1.isMissingShadowSidecarError)(err)) {
+                return err;
+            }
+            const msg = err instanceof Error ? err.message : String(err);
+            // Suppression list:
+            //   - "already exists": expected idempotent re-create on existing DBs
+            //   - "could not set lock on file": LadybugDB v0.18.0 emits this on
+            //     Windows when CREATE NODE TABLE runs against a path that was
+            //     just opened (the WAL handle from a fresh Database briefly
+            //     contests the table's first-write lock). The table is created
+            //     anyway and any genuine cross-process lock contention surfaces
+            //     on the next operation via withLbugDb's retry. Logging it here
+            //     would just be noise in CI.
+            //
+            // WAL corruption: the first DDL write after DB open triggers WAL
+            // replay — if the WAL file was left in a corrupt state by an
+            // interrupted previous run, the native engine throws here. Rather
+            // than logging a WARN and continuing in a broken state, close the
+            // DB cleanly and surface an actionable error so the caller (serve,
+            // MCP, analyze) can exit with a clear recovery message.
+            if ((0, lbug_config_js_1.isWalCorruptionError)(err)) {
+                await (0, exports.safeClose)();
+                resetOpenConnectionState();
+                throw new Error(`LadybugDB WAL corruption detected at ${dbPath}. ${lbug_config_js_1.WAL_RECOVERY_SUGGESTION}\n` +
+                    `  Original error: ${msg.slice(0, 200)}`);
+            }
+            if (!msg.includes('already exists') && !(0, lbug_config_js_1.isDbBusyError)(err) && !(0, exports.isReadOnlyDbError)(err)) {
+                logger_js_1.logger.warn(`⚠️ Schema creation warning: ${msg.slice(0, 120)}`);
+            }
+        }
+    }
+    return null;
+};
+const initLbug = async (dbPath) => {
+    return runWithSessionLock(() => ensureLbugInitialized(dbPath));
+};
+exports.initLbug = initLbug;
+/**
+ * Execute multiple queries against one repo DB atomically.
+ * While the callback runs, no other request can switch the active DB.
+ *
+ * Automatically retries up to DB_LOCK_RETRY_ATTEMPTS times when the
+ * database is busy (e.g. `cgraph analyze` holds the write lock).
+ * Each retry waits DB_LOCK_RETRY_DELAY_MS * attempt milliseconds.
+ */
+const withLbugDb = async (dbPath, operation, options = {}) => {
+    let lastError;
+    const readOnly = options.readOnly === true;
+    for (let attempt = 1; attempt <= DB_LOCK_RETRY_ATTEMPTS; attempt++) {
+        try {
+            return await runWithSessionLock(async () => {
+                await ensureLbugInitialized(dbPath, readOnly);
+                return operation();
+            });
+        }
+        catch (err) {
+            lastError = err;
+            // Skip outer retry when the inner open-retry already exhausted: the
+            // ~1.5s open-time budget was just spent, repeating the full reset+
+            // reopen cycle would only add 4-5s of tail latency without changing
+            // the outcome (both layers consult the same isDbBusyError matcher).
+            if (!(0, lbug_config_js_1.isDbBusyError)(err) || (0, lbug_config_js_1.isOpenRetryExhausted)(err) || attempt === DB_LOCK_RETRY_ATTEMPTS) {
+                throw err;
+            }
+            // Close stale connection inside the session lock to prevent race conditions
+            // with concurrent operations that might acquire the lock between cleanup steps
+            await runWithSessionLock(async () => {
+                await (0, exports.safeClose)();
+                currentDbPath = null;
+                vectorExtensionLoaded = false;
+                vectorIndexEnsured = false;
+            });
+            // Sleep outside the lock — no need to block others while waiting
+            await new Promise((resolve) => setTimeout(resolve, DB_LOCK_RETRY_DELAY_MS * attempt));
+        }
+    }
+    // This line is unreachable — the loop either returns or throws inside,
+    // but TypeScript needs an explicit throw to satisfy the return type.
+    throw lastError;
+};
+exports.withLbugDb = withLbugDb;
+const ensureLbugInitialized = async (dbPath, readOnly = false) => {
+    if (conn && currentDbPath === dbPath && currentDbReadOnly === readOnly) {
+        return { db, conn };
+    }
+    await doInitLbug(dbPath, readOnly);
+    return { db, conn };
+};
+const doInitLbug = async (dbPath, readOnly = false) => {
+    // Different database requested — close the old one first
+    if (conn || db) {
+        await (0, exports.safeClose)();
+        currentDbPath = null;
+        vectorExtensionLoaded = false;
+        vectorIndexEnsured = false;
+    }
+    // ---------------------------------------------------------------------------
+    // Read-only fast path: skip all filesystem mutations (path cleanup, init
+    // lock, orphan sidecar removal, mkdir) so the open succeeds on read-only
+    // filesystems such as Docker `:ro` bind mounts. The init lock exists to
+    // prevent a TOCTOU race during DB *creation* — read-only opens never
+    // create databases and don't need the lock.
+    // ---------------------------------------------------------------------------
+    if (readOnly) {
+        await (0, sidecar_recovery_js_1.preflightLbugSidecars)(dbPath, {
+            mode: 'read-only',
+            logger: logger_js_1.logger,
+            allowQuarantine: false,
+        });
+        const opened = await (0, lbug_config_js_1.openLbugConnection)(lbug, dbPath, { readOnly: true });
+        const usable = await ensureReadOnlyConnectionUsable(dbPath, opened);
+        db = usable.db;
+        conn = usable.conn;
+        currentDbReadOnly = true;
+    }
+    else {
+        // LadybugDB stores the database as a single file (not a directory).
+        // If the path already exists, it must be a valid LadybugDB database file.
+        // Remove stale empty directories or files from older versions.
+        try {
+            const stat = await promises_1.default.lstat(dbPath);
+            if (stat.isSymbolicLink()) {
+                // Never follow symlinks — just remove the link itself
+                await promises_1.default.unlink(dbPath);
+            }
+            else if (stat.isDirectory()) {
+                // Verify path is within expected storage directory before deleting
+                const realPath = await promises_1.default.realpath(dbPath);
+                const parentDir = path_1.default.dirname(dbPath);
+                const realParent = await promises_1.default.realpath(parentDir);
+                const safePrefix = realParent.endsWith(path_1.default.sep) ? realParent : realParent + path_1.default.sep;
+                if (!realPath.startsWith(safePrefix) && realPath !== realParent) {
+                    throw new Error(`Refusing to delete ${dbPath}: resolved path ${realPath} is outside storage directory`);
+                }
+                // Old-style directory database or empty leftover - remove it
+                await promises_1.default.rm(dbPath, { recursive: true, force: true });
+            }
+            // If it's a file, assume it's an existing LadybugDB database - LadybugDB will open it
+        }
+        catch (err) {
+            if (!isMissingFileError(err)) {
+                throw err;
+            }
+            // Path doesn't exist, which is what LadybugDB wants for a new database
+        }
+        // -------------------------------------------------------------------------
+        // Cross-process critical section: acquire init lock, clean orphan sidecars,
+        // and open the database. The lock prevents a TOCTOU race where another
+        // process could create a fresh DB between our access() check and the
+        // unlink() of stale sidecars.
+        // -------------------------------------------------------------------------
+        const releaseInitLock = await (0, exports.acquireInitLock)(dbPath);
+        try {
+            // Reclaim missing-shadow WAL quarantines from a PRIOR crash (#2637).
+            // LadybugDB renames an unrecoverable WAL aside as
+            // `${dbPath}.wal.missing-shadow.<ts>-<rand>` (quarantineWalForMissingShadow)
+            // instead of deleting it. Once quarantined it is permanently detached from
+            // the live store and never reopened, so reclaiming it is safe regardless of
+            // whether the main DB file exists this run — unlike the orphan-sidecar
+            // cleanup below, this must NOT be gated on "main DB missing": a quarantine
+            // event and a healthy main DB are independent facts. Never let a reclaim
+            // failure (e.g. a transient EBUSY from an antivirus scan) block DB startup.
+            if (!(0, sidecar_recovery_js_1.sidecarPreflightDisabled)()) {
+                try {
+                    const reclaimed = await (0, sidecar_recovery_js_1.cleanQuarantinedMissingShadowWals)(dbPath);
+                    for (const file of reclaimed) {
+                        logger_js_1.logger.warn(`GitNexus: reclaimed quarantined WAL ${path_1.default.basename(file)} from a prior crash`);
+                    }
+                }
+                catch (err) {
+                    logger_js_1.logger.warn(`GitNexus: failed to reclaim missing-shadow WAL quarantines: ${summarizeError(err)}`);
+                }
+            }
+            // Crash-recovery cleanup: if the main DB file is missing, stale sidecars
+            // from an interrupted run can block fresh opens indefinitely.
+            try {
+                await promises_1.default.access(dbPath);
+            }
+            catch (err) {
+                if (isMissingFileError(err)) {
+                    // `.shadow` is documented by LadybugDB checkpointing and `.wal.checkpoint`
+                    // was observed in the #1618 crash loop that motivated this recovery path.
+                    const orphanSidecars = [`${dbPath}.shadow`, `${dbPath}.wal.checkpoint`];
+                    for (const sidecar of orphanSidecars) {
+                        try {
+                            await promises_1.default.unlink(sidecar);
+                            logger_js_1.logger.warn(`GitNexus: removed orphan sidecar ${path_1.default.basename(sidecar)} (no main DB file present)`);
+                        }
+                        catch (err) {
+                            if (isMissingFileError(err)) {
+                                continue;
+                            }
+                            const code = extractErrnoCode(err);
+                            logger_js_1.logger.warn(`GitNexus: failed to remove orphan sidecar ${path_1.default.basename(sidecar)} (${code ?? 'UNKNOWN'}) while main DB file is missing; LadybugDB open may still fail: ${summarizeError(err)}`);
+                        }
+                    }
+                }
+                else {
+                    const code = extractErrnoCode(err);
+                    logger_js_1.logger.warn(`GitNexus: unable to verify main DB file before orphan sidecar cleanup (${code ?? 'UNKNOWN'}); skipping cleanup: ${summarizeError(err)}`);
+                }
+            }
+            // Ensure parent directory exists
+            const parentDir = path_1.default.dirname(dbPath);
+            await promises_1.default.mkdir(parentDir, { recursive: true });
+            await (0, sidecar_recovery_js_1.preflightLbugSidecars)(dbPath, {
+                mode: 'write',
+                logger: logger_js_1.logger,
+                allowQuarantine: true,
+            });
+            const opened = await (0, lbug_config_js_1.openLbugConnection)(lbug, dbPath);
+            db = opened.db;
+            conn = opened.conn;
+            currentDbReadOnly = false;
+        }
+        finally {
+            await releaseInitLock();
+        }
+    }
+    if (!readOnly) {
+        const missingShadowError = await runSchemaCreationQueries(dbPath);
+        if (missingShadowError) {
+            await (0, exports.safeClose)();
+            resetOpenConnectionState();
+            const reopened = await reopenWritableAfterMissingShadow(dbPath, missingShadowError);
+            db = reopened.db;
+            conn = reopened.conn;
+            currentDbReadOnly = false;
+            const retryMissingShadowError = await runSchemaCreationQueries(dbPath);
+            if (retryMissingShadowError) {
+                await (0, exports.safeClose)();
+                resetOpenConnectionState();
+                throw new Error((0, sidecar_recovery_js_1.shadowSidecarRecoveryMessage)(dbPath, retryMissingShadowError));
+            }
+        }
+    }
+    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 = (0, exports.getCopyQuery)(table, normalizeCopyPath(csvPath));
+        await copyCsvWithRetry(targetConn, copyQuery, (retryErr) => {
+            const retryMsg = retryErr instanceof Error ? retryErr.message : String(retryErr);
+            // Pool exhaustion gets a remedy (#2631): the raw binder text gives the
+            // operator nothing to act on, and on non-4K-page hosts (Ascend aarch64,
+            // Apple Silicon) the pool bills up to pageSize/4KiB x faster than the
+            // sizing was calibrated for — name the knob and the mechanism.
+            const remedy = (0, lbug_config_js_1.bufferPoolExhaustionRemedy)(retryMsg);
+            throw new Error(`COPY failed for ${table}: ${retryMsg.slice(0, 200)}${remedy ? ` ${remedy}` : ''}`);
+        });
+    }
+};
+/**
+ * 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, or a relationship `COPY` failure —
+ * leaves a partially-loaded DB. The caller surfaces the error; recovery is a
+ * re-analyze (a full rebuild), not a partial retry. Callers must not
+ * assume the DB is either fully loaded or untouched after a rejection.
+ */
+const loadGraphToLbug = async (graph, repoPath, storagePath, onProgress, 
+/**
+ * Streamed structural-emit manifest (#2680). These pair keys are NOT disjoint
+ * from the whole-graph emit's: a streamed `CALLS` edge is `Function|Function`,
+ * exactly like the retained edges `streamAllCSVsToDisk` just wrote. So these
+ * files are APPENDED as additional COPY jobs for the same pair rather than
+ * merged into `relsByPair` (a Map, which holds one CSV per pair and would
+ * silently drop one of them).
+ */
+graphEmitManifest) => {
+    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.CGRAPH_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 = (0, lbug_config_js_1.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(schema_js_1.NODE_TABLES);
+    // 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) => {
+        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 (0, csv_generator_js_1.streamAllCSVsToDisk)(graph, repoPath, csvDir)
+            : await (0, csv_generator_js_1.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_js_1.logger.warn({ err: nodeCopyError }, '[lbug-load] node COPY also failed while relationship emit was failing');
+        }
+        throw emitErr;
+    }
+    const tCsv = mark();
+    // 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;
+    // One COPY job per CSV FILE, not per label pair. The whole-graph emit writes
+    // at most one file per pair, but the streamed structural manifest (#2680) can
+    // contribute a second file for a pair the whole-graph emit also wrote — both
+    // must load. `relsByPair` stays a one-file-per-pair Map so the PDG merge above
+    // and every other consumer are untouched.
+    const copyJobs = [];
+    for (const [pairKey, meta] of relsByPair) {
+        copyJobs.push({ pairKey, csvPath: meta.csvPath, rows: meta.rows });
+    }
+    if (graphEmitManifest) {
+        for (const [pairKey, meta] of graphEmitManifest.relsByPair) {
+            copyJobs.push({ pairKey, csvPath: meta.csvPath, rows: meta.rows });
+        }
+    }
+    const insertedRels = totalValidRels + (graphEmitManifest?.totalRows ?? 0);
+    const warnings = [];
+    let poolRemedyIssued = false;
+    if (insertedRels > 0) {
+        log(`Loading edges: ${insertedRels.toLocaleString()} across ${copyJobs.length} CSV files`);
+        let pairIdx = 0;
+        let failedPairEdges = 0;
+        const failedPairCsvPaths = new Set();
+        for (const { pairKey, csvPath: pairCsvPath, rows } of copyJobs) {
+            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 ${schema_js_1.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}/${copyJobs.length} files (${fromLabel} -> ${toLabel})`);
+            }
+            // Use the captured `writeConn` (not the module-level `conn`) for the rel
+            // COPY, matching the node COPY above — one captured reference for the whole
+            // bulk load (#2264 review P3). Same object during analyze (`conn` is only
+            // reassigned at open/close under the session lock, never mid-load), so the
+            // queryAndDrain `targetConn === conn` lock gate still engages.
+            await copyCsvWithRetry(writeConn, copyQuery, (retryErr) => {
+                const retryMsg = retryErr instanceof Error ? retryErr.message : String(retryErr);
+                warnings.push(`${fromLabel}->${toLabel} (${rows} edges): ${retryMsg.slice(0, 80)}`);
+                // One remedy per bulk load, not per pair (#2631): pool exhaustion
+                // repeats for every remaining pair once it starts. logger.warn, not
+                // just warnings.push — the returned warnings array has no consumer at
+                // any call site, so a push alone would leave the remedy invisible
+                // while the row-by-row fallback quietly degrades the load.
+                const remedy = poolRemedyIssued ? undefined : (0, lbug_config_js_1.bufferPoolExhaustionRemedy)(retryMsg);
+                if (remedy) {
+                    poolRemedyIssued = true;
+                    warnings.push(remedy);
+                    logger_js_1.logger.warn(remedy);
+                }
+                failedPairEdges += rows;
+                failedPairCsvPaths.add(pairCsvPath);
+            });
+            // Only delete if not in failedPairCsvPaths (needed for fallback)
+            if (!failedPairCsvPaths.has(pairCsvPath)) {
+                try {
+                    await promises_1.default.unlink(pairCsvPath);
+                }
+                catch { }
+            }
+        }
+        tCopyRels = mark();
+        if (failedPairCsvPaths.size > 0) {
+            log(`Inserting ${failedPairEdges} edges individually (missing schema pairs)`);
+            // Read failed pair files and merge for fallback inserts
+            const allLines = [relHeader];
+            for (const failedPath of failedPairCsvPaths) {
+                try {
+                    const content = await promises_1.default.readFile(failedPath, 'utf-8');
+                    const lines = content.split('\n');
+                    // Skip header line (first) and empty lines
+                    for (let i = 1; i < lines.length; i++) {
+                        if (lines[i].trim())
+                            allLines.push(lines[i]);
+                    }
+                }
+                catch { }
+                try {
+                    await promises_1.default.unlink(failedPath);
+                }
+                catch { }
+            }
+            if (allLines.length > 1) {
+                await (0, exports.fallbackRelationshipInserts)(allLines, validTables, rel_pair_routing_js_1.getNodeLabel);
+            }
+        }
+        tFallback = mark();
+    }
+    // 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 promises_1.default.unlink(csvPath);
+        }
+        catch { }
+    }
+    try {
+        const remaining = await promises_1.default.readdir(csvDir);
+        for (const f of remaining) {
+            try {
+                await promises_1.default.unlink(path_1.default.join(csvDir, f));
+            }
+            catch { }
+        }
+    }
+    catch { }
+    try {
+        await promises_1.default.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_js_1.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 };
+};
+exports.loadGraphToLbug = loadGraphToLbug;
+// 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.
+//
+// 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.
+exports.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([
+    'Struct',
+    'Enum',
+    'Macro',
+    'Typedef',
+    'Union',
+    'Namespace',
+    'Trait',
+    'Impl',
+    'TypeAlias',
+    'Const',
+    'Static',
+    'Property',
+    'Record',
+    'Delegate',
+    'Annotation',
+    'Constructor',
+    'Template',
+    'Module',
+]);
+const escapeTableName = (table) => {
+    return BACKTICK_TABLES.has(table) ? `\`${table}\`` : table;
+};
+/**
+ * Format one JS value as a Cypher literal for the adapter's string-built
+ * statements: NULL/undefined → `NULL`, numbers pass through unquoted,
+ * everything else becomes a single-quoted string literal escaped via
+ * {@link escapeCypherString} (backslashes first, then quotes).
+ *
+ * Replaces three per-function closures that used SQL-style `''` doubling —
+ * LadybugDB REJECTS doubling, so every value containing a quote made the
+ * whole statement a parser error, invisible wherever the call site swallowed
+ * per-row failures (#2409 escaping sweep, completed for tri-review
+ * 4669518496 P2-2). Those closures also rewrote literal `\n`/`\r` into
+ * two-character escape sequences; raw LF/CR are legal inside LadybugDB
+ * single-quoted literals (live-probed on @ladybugdb/core 0.18.0), so the
+ * replaces are gone and content now round-trips byte-identical.
+ */
+const formatCypherValue = (v) => {
+    if (v === null || v === undefined)
+        return 'NULL';
+    if (typeof v === 'number')
+        return String(v);
+    return `'${(0, cypher_escape_js_1.escapeCypherString)(String(v))}'`;
+};
+const formatCypherStringArray = (value) => {
+    const items = Array.isArray(value)
+        ? value.filter((item) => typeof item === 'string')
+        : [];
+    return `[${items.map(formatCypherValue).join(', ')}]`;
+};
+/**
+ * Fallback: insert relationships one-by-one if COPY fails.
+ *
+ * Exported for the quoted-id round-trip tests in
+ * `test/integration/lbug-core-adapter.test.ts` (the `DELETE_FILES_CHUNK_SIZE`
+ * exported-for-tests precedent); production callers stay in this module.
+ * Bails silently when the adapter singleton is closed.
+ *
+ * KNOWN PRE-EXISTING NARROWING (distinct from the `''` escaping bug, NOT
+ * fixed here): the row regex below matches CSV fields with `[^"]*`, so an id
+ * containing a double quote (CSV-escaped as `""`) never matches and the edge
+ * is skipped. Tracked as part of the quote-in-id divergence documented in
+ * `rel-pair-routing.ts`.
+ */
+const fallbackRelationshipInserts = async (validRelLines, validTables, getNodeLabel) => {
+    if (!conn)
+        return;
+    const escapeLabel = (label) => {
+        return BACKTICK_TABLES.has(label) ? `\`${label}\`` : label;
+    };
+    for (let i = 1; i < validRelLines.length; i++) {
+        const line = validRelLines[i];
+        try {
+            const match = line.match(/"([^"]*)","([^"]*)","([^"]*)",([0-9.]+),"([^"]*)",([0-9-]+)/);
+            if (!match)
+                continue;
+            const [, fromId, toId, relType, confidenceStr, reason, stepStr] = match;
+            const fromLabel = getNodeLabel(fromId);
+            const toLabel = getNodeLabel(toId);
+            if (!validTables.has(fromLabel) || !validTables.has(toLabel))
+                continue;
+            const confidence = parseFloat(confidenceStr) || 1.0;
+            const step = parseInt(stepStr) || 0;
+            await queryAndDrain(conn, `
+        MATCH (a:${escapeLabel(fromLabel)} {id: ${formatCypherValue(fromId)} }),
+              (b:${escapeLabel(toLabel)} {id: ${formatCypherValue(toId)} })
+        CREATE (a)-[:${schema_js_1.REL_TABLE_NAME} {type: ${formatCypherValue(relType)}, confidence: ${confidence}, reason: ${formatCypherValue(reason)}, step: ${step}}]->(b)
+      `);
+        }
+        catch {
+            // skip
+        }
+    }
+};
+exports.fallbackRelationshipInserts = fallbackRelationshipInserts;
+/** Tables with isExported column (TypeScript/JS-native types) */
+const TABLES_WITH_EXPORTED = new Set([
+    'Function',
+    'Class',
+    'Interface',
+    'Method',
+    'CodeElement',
+]);
+const getCopyQuery = (table, filePath) => {
+    const t = escapeTableName(table);
+    if (table === 'File') {
+        return `COPY ${t}(id, name, filePath, content) FROM "${filePath}" ${exports.COPY_CSV_OPTS}`;
+    }
+    if (table === 'Folder') {
+        return `COPY ${t}(id, name, filePath) FROM "${filePath}" ${exports.COPY_CSV_OPTS}`;
+    }
+    if (table === 'Community') {
+        return `COPY ${t}(id, label, heuristicLabel, keywords, description, enrichedBy, cohesion, symbolCount) FROM "${filePath}" ${exports.COPY_CSV_OPTS}`;
+    }
+    if (table === 'Process') {
+        return `COPY ${t}(id, label, heuristicLabel, processType, stepCount, communities, entryPointId, terminalId) FROM "${filePath}" ${exports.COPY_CSV_OPTS}`;
+    }
+    if (table === 'Section') {
+        return `COPY ${t}(id, name, filePath, startLine, endLine, level, content, description) FROM "${filePath}" ${exports.COPY_CSV_OPTS}`;
+    }
+    if (table === 'Route') {
+        return `COPY ${t}(id, name, filePath, responseKeys, errorKeys, middleware, method, handlerSymbolId) FROM "${filePath}" ${exports.COPY_CSV_OPTS}`;
+    }
+    if (table === 'Tool') {
+        return `COPY ${t}(id, name, filePath, description) FROM "${filePath}" ${exports.COPY_CSV_OPTS}`;
+    }
+    if (table === 'BasicBlock') {
+        // 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}" ${exports.COPY_CSV_OPTS}`;
+    }
+    if (table === 'Class') {
+        return `COPY ${t}(id, name, filePath, startLine, endLine, isExported, content, description, frameworkAnnotations) FROM "${filePath}" ${exports.COPY_CSV_OPTS}`;
+    }
+    if (table === 'Method') {
+        return `COPY ${t}(id, name, filePath, startLine, endLine, isExported, content, description, parameterCount, returnType) FROM "${filePath}" ${exports.COPY_CSV_OPTS}`;
+    }
+    if (table === 'Property') {
+        return `COPY ${t}(id, name, filePath, startLine, endLine, content, description, declaredType) FROM "${filePath}" ${exports.COPY_CSV_OPTS}`;
+    }
+    // TypeScript/JS code element tables have isExported; multi-language tables do not
+    if (TABLES_WITH_EXPORTED.has(table)) {
+        return `COPY ${t}(id, name, filePath, startLine, endLine, isExported, content, description) FROM "${filePath}" ${exports.COPY_CSV_OPTS}`;
+    }
+    // Multi-language tables (Struct, Impl, Trait, Macro, etc.)
+    return `COPY ${t}(id, name, filePath, startLine, endLine, content, description) FROM "${filePath}" ${exports.COPY_CSV_OPTS}`;
+};
+exports.getCopyQuery = getCopyQuery;
+/**
+ * Insert a single node to LadybugDB
+ * @param label - Node type (File, Function, Class, etc.)
+ * @param properties - Node properties
+ * @param dbPath - Path to LadybugDB database (optional if already initialized)
+ */
+const insertNodeToLbug = async (label, properties, dbPath) => {
+    // Use provided dbPath or fall back to module-level db
+    const targetDbPath = dbPath || (db ? undefined : null);
+    if (!targetDbPath && !db) {
+        throw new Error('LadybugDB not initialized. Provide dbPath or call initLbug first.');
+    }
+    try {
+        // Values go through the module-scope formatCypherValue — the old local
+        // closure used `''` doubling, which LadybugDB rejects (#2409 escaping
+        // sweep, tri-review 4669518496 P2-2).
+        // Build INSERT query based on node type
+        const t = escapeTableName(label);
+        let query;
+        if (label === 'File') {
+            query = `CREATE (n:File {id: ${formatCypherValue(properties.id)}, name: ${formatCypherValue(properties.name)}, filePath: ${formatCypherValue(properties.filePath)}, content: ${formatCypherValue(properties.content || '')}})`;
+        }
+        else if (label === 'Folder') {
+            query = `CREATE (n:Folder {id: ${formatCypherValue(properties.id)}, name: ${formatCypherValue(properties.name)}, filePath: ${formatCypherValue(properties.filePath)}})`;
+        }
+        else if (label === 'Section') {
+            const descPart = properties.description
+                ? `, description: ${formatCypherValue(properties.description)}`
+                : '';
+            query = `CREATE (n:Section {id: ${formatCypherValue(properties.id)}, name: ${formatCypherValue(properties.name)}, filePath: ${formatCypherValue(properties.filePath)}, startLine: ${properties.startLine || 0}, endLine: ${properties.endLine || 0}, level: ${properties.level || 1}, content: ${formatCypherValue(properties.content || '')}${descPart}})`;
+        }
+        else if (label === 'BasicBlock') {
+            // 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: ${formatCypherValue(properties.id)}, filePath: ${formatCypherValue(properties.filePath)}, startLine: ${properties.startLine || 0}, endLine: ${properties.endLine || 0}, text: ${formatCypherValue(properties.text || '')}, callees: ${formatCypherValue(properties.callees || '')}, calleeIds: ${formatCypherValue(properties.calleeIds || '')}})`;
+        }
+        else if (label === 'Class') {
+            const descPart = properties.description
+                ? `, description: ${formatCypherValue(properties.description)}`
+                : '';
+            query = `CREATE (n:Class {id: ${formatCypherValue(properties.id)}, name: ${formatCypherValue(properties.name)}, filePath: ${formatCypherValue(properties.filePath)}, startLine: ${properties.startLine || 0}, endLine: ${properties.endLine || 0}, isExported: ${!!properties.isExported}, content: ${formatCypherValue(properties.content || '')}${descPart}, frameworkAnnotations: ${formatCypherStringArray(properties.frameworkAnnotations)}})`;
+        }
+        else if (TABLES_WITH_EXPORTED.has(label)) {
+            const descPart = properties.description
+                ? `, description: ${formatCypherValue(properties.description)}`
+                : '';
+            query = `CREATE (n:${t} {id: ${formatCypherValue(properties.id)}, name: ${formatCypherValue(properties.name)}, filePath: ${formatCypherValue(properties.filePath)}, startLine: ${properties.startLine || 0}, endLine: ${properties.endLine || 0}, isExported: ${!!properties.isExported}, content: ${formatCypherValue(properties.content || '')}${descPart}})`;
+        }
+        else if (label === 'Property') {
+            const descPart = properties.description
+                ? `, description: ${formatCypherValue(properties.description)}`
+                : '';
+            query = `CREATE (n:${t} {id: ${formatCypherValue(properties.id)}, name: ${formatCypherValue(properties.name)}, filePath: ${formatCypherValue(properties.filePath)}, startLine: ${properties.startLine || 0}, endLine: ${properties.endLine || 0}, content: ${formatCypherValue(properties.content || '')}${descPart}, declaredType: ${formatCypherValue(properties.declaredType || '')}})`;
+        }
+        else {
+            // Multi-language tables (Struct, Impl, Trait, Macro, etc.) — no isExported
+            const descPart = properties.description
+                ? `, description: ${formatCypherValue(properties.description)}`
+                : '';
+            query = `CREATE (n:${t} {id: ${formatCypherValue(properties.id)}, name: ${formatCypherValue(properties.name)}, filePath: ${formatCypherValue(properties.filePath)}, startLine: ${properties.startLine || 0}, endLine: ${properties.endLine || 0}, content: ${formatCypherValue(properties.content || '')}${descPart}})`;
+        }
+        // Use per-query connection if dbPath provided (avoids lock conflicts)
+        if (targetDbPath) {
+            const tempHandle = await (0, lbug_config_js_1.openLbugConnection)(lbug, targetDbPath);
+            try {
+                await queryAndDrain(tempHandle.conn, query);
+                return true;
+            }
+            finally {
+                await (0, lbug_config_js_1.closeLbugConnection)(tempHandle);
+            }
+        }
+        else if (conn) {
+            // Use existing persistent connection (when called from analyze)
+            await queryAndDrain(conn, query);
+            return true;
+        }
+        return false;
+    }
+    catch (e) {
+        // Node may already exist or other error
+        logger_js_1.logger.error({ err: e.message }, `Failed to insert ${label} node:`);
+        return false;
+    }
+};
+exports.insertNodeToLbug = insertNodeToLbug;
+/**
+ * Batch insert multiple nodes to LadybugDB using a single connection
+ * @param nodes - Array of {label, properties} to insert
+ * @param dbPath - Path to LadybugDB database
+ * @returns Object with success count and error count
+ */
+const batchInsertNodesToLbug = async (nodes, dbPath) => {
+    if (nodes.length === 0)
+        return { inserted: 0, failed: 0 };
+    // Values go through the module-scope formatCypherValue — the old local
+    // closure used `''` doubling, which LadybugDB rejects; the per-node catch
+    // below counted every quoted value as a silent `failed` (#2409 escaping
+    // sweep, tri-review 4669518496 P2-2).
+    // Open a single connection for all inserts
+    const tempHandle = await (0, lbug_config_js_1.openLbugConnection)(lbug, dbPath);
+    const tempConn = tempHandle.conn;
+    let inserted = 0;
+    let failed = 0;
+    try {
+        for (const { label, properties } of nodes) {
+            try {
+                let query;
+                // Use MERGE instead of CREATE for upsert behavior (handles duplicates gracefully)
+                const t = escapeTableName(label);
+                if (label === 'File') {
+                    query = `MERGE (n:File {id: ${formatCypherValue(properties.id)}}) SET n.name = ${formatCypherValue(properties.name)}, n.filePath = ${formatCypherValue(properties.filePath)}, n.content = ${formatCypherValue(properties.content || '')}`;
+                }
+                else if (label === 'Folder') {
+                    query = `MERGE (n:Folder {id: ${formatCypherValue(properties.id)}}) SET n.name = ${formatCypherValue(properties.name)}, n.filePath = ${formatCypherValue(properties.filePath)}`;
+                }
+                else if (label === 'Section') {
+                    const descPart = properties.description
+                        ? `, n.description = ${formatCypherValue(properties.description)}`
+                        : '';
+                    query = `MERGE (n:Section {id: ${formatCypherValue(properties.id)}}) SET n.name = ${formatCypherValue(properties.name)}, n.filePath = ${formatCypherValue(properties.filePath)}, n.startLine = ${properties.startLine || 0}, n.endLine = ${properties.endLine || 0}, n.level = ${properties.level || 1}, n.content = ${formatCypherValue(properties.content || '')}${descPart}`;
+                }
+                else if (label === 'BasicBlock') {
+                    // 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: ${formatCypherValue(properties.id)}}) SET n.filePath = ${formatCypherValue(properties.filePath)}, n.startLine = ${properties.startLine || 0}, n.endLine = ${properties.endLine || 0}, n.text = ${formatCypherValue(properties.text || '')}, n.callees = ${formatCypherValue(properties.callees || '')}, n.calleeIds = ${formatCypherValue(properties.calleeIds || '')}`;
+                }
+                else if (label === 'Class') {
+                    const descPart = properties.description
+                        ? `, n.description = ${formatCypherValue(properties.description)}`
+                        : '';
+                    query = `MERGE (n:Class {id: ${formatCypherValue(properties.id)}}) SET n.name = ${formatCypherValue(properties.name)}, n.filePath = ${formatCypherValue(properties.filePath)}, n.startLine = ${properties.startLine || 0}, n.endLine = ${properties.endLine || 0}, n.isExported = ${!!properties.isExported}, n.content = ${formatCypherValue(properties.content || '')}${descPart}, n.frameworkAnnotations = ${formatCypherStringArray(properties.frameworkAnnotations)}`;
+                }
+                else if (TABLES_WITH_EXPORTED.has(label)) {
+                    const descPart = properties.description
+                        ? `, n.description = ${formatCypherValue(properties.description)}`
+                        : '';
+                    query = `MERGE (n:${t} {id: ${formatCypherValue(properties.id)}}) SET n.name = ${formatCypherValue(properties.name)}, n.filePath = ${formatCypherValue(properties.filePath)}, n.startLine = ${properties.startLine || 0}, n.endLine = ${properties.endLine || 0}, n.isExported = ${!!properties.isExported}, n.content = ${formatCypherValue(properties.content || '')}${descPart}`;
+                }
+                else if (label === 'Property') {
+                    const descPart = properties.description
+                        ? `, n.description = ${formatCypherValue(properties.description)}`
+                        : '';
+                    query = `MERGE (n:${t} {id: ${formatCypherValue(properties.id)}}) SET n.name = ${formatCypherValue(properties.name)}, n.filePath = ${formatCypherValue(properties.filePath)}, n.startLine = ${properties.startLine || 0}, n.endLine = ${properties.endLine || 0}, n.content = ${formatCypherValue(properties.content || '')}${descPart}, n.declaredType = ${formatCypherValue(properties.declaredType || '')}`;
+                }
+                else {
+                    const descPart = properties.description
+                        ? `, n.description = ${formatCypherValue(properties.description)}`
+                        : '';
+                    query = `MERGE (n:${t} {id: ${formatCypherValue(properties.id)}}) SET n.name = ${formatCypherValue(properties.name)}, n.filePath = ${formatCypherValue(properties.filePath)}, n.startLine = ${properties.startLine || 0}, n.endLine = ${properties.endLine || 0}, n.content = ${formatCypherValue(properties.content || '')}${descPart}`;
+                }
+                await queryAndDrain(tempConn, query);
+                inserted++;
+            }
+            catch (e) {
+                // Don't console.error here - it corrupts MCP JSON-RPC on stderr
+                failed++;
+            }
+        }
+    }
+    finally {
+        await (0, lbug_config_js_1.closeLbugConnection)(tempHandle);
+    }
+    return { inserted, failed };
+};
+exports.batchInsertNodesToLbug = batchInsertNodesToLbug;
+const executeQuery = async (cypher) => {
+    return await (0, exports.executePrepared)(cypher, {});
+};
+exports.executeQuery = executeQuery;
+const streamQuery = async (cypher, onRow) => {
+    if ((0, wal_driver_state_js_1.isWalDriverActive)()) {
+        // streamQuery reads rows on the singleton connection WITHOUT withConnLock; if
+        // the WAL-checkpoint driver is live, those reads could race a CHECKPOINT — the
+        // #2264 corruption window. Today the serve/read path never runs the driver
+        // (analyze runs in a forked worker), so this fails loud only if a future
+        // in-process analyze overlaps a stream. Run analysis in a worker, or stop the
+        // driver before streaming. See conn-lock.ts.
+        throw new Error('streamQuery cannot run while the WAL-checkpoint driver is active (it would ' +
+            'race a CHECKPOINT on the unlocked read connection — #2264).');
+    }
+    if (!conn) {
+        throw new Error('LadybugDB not initialized. Call initLbug first.');
+    }
+    const queryResult = await conn.query(cypher);
+    const results = Array.isArray(queryResult) ? queryResult : [queryResult];
+    const result = results[0];
+    let rowCount = 0;
+    let streamError;
+    try {
+        while (await result.hasNext()) {
+            const row = await result.getNext();
+            await onRow(row);
+            rowCount++;
+        }
+        return rowCount;
+    }
+    catch (err) {
+        streamError = err;
+        throw err;
+    }
+    finally {
+        try {
+            await drainQueryResult(results);
+        }
+        catch (err) {
+            if (streamError === undefined)
+                throw err;
+        }
+    }
+};
+exports.streamQuery = streamQuery;
+/**
+ * Execute a single parameterized query (prepare/execute pattern).
+ * Prevents Cypher injection by binding values as parameters.
+ */
+const executePrepared = async (cypher, params) => {
+    const c = conn;
+    if (!c) {
+        throw new Error('LadybugDB not initialized. Call initLbug first.');
+    }
+    return (0, conn_lock_js_1.withConnLock)(async () => {
+        const stmt = await c.prepare(cypher);
+        if (!stmt.isSuccess()) {
+            const errMsg = await stmt.getErrorMessage();
+            throw new Error(`Prepare failed: ${errMsg}`);
+        }
+        const queryResult = await c.execute(stmt, params);
+        return await readQueryRows(queryResult);
+    });
+};
+exports.executePrepared = executePrepared;
+const executeWithReusedStatement = async (cypher, paramsList) => {
+    const c = conn;
+    if (!c) {
+        throw new Error('LadybugDB not initialized. Call initLbug first.');
+    }
+    if (paramsList.length === 0)
+        return;
+    const SUB_BATCH_SIZE = 4;
+    for (let i = 0; i < paramsList.length; i += SUB_BATCH_SIZE) {
+        const subBatch = paramsList.slice(i, i + SUB_BATCH_SIZE);
+        // One critical section per sub-batch: the prepare + its executes run with
+        // exclusive access to the connection (so the WAL checkpoint driver cannot
+        // interleave a CHECKPOINT mid-batch), while the lock is released between
+        // sub-batches to let the driver checkpoint during a long writeback.
+        await (0, conn_lock_js_1.withConnLock)(async () => {
+            const stmt = await c.prepare(cypher);
+            if (!stmt.isSuccess()) {
+                const errMsg = await stmt.getErrorMessage();
+                throw new Error(`Prepare failed: ${errMsg}`);
+            }
+            try {
+                for (const params of subBatch) {
+                    await drainQueryResult(await c.execute(stmt, params));
+                }
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                const queryPreview = cypher.replace(/\s+/g, ' ').slice(0, 120);
+                throw new Error(`Batch execution failed for rows ${i + 1}-${i + subBatch.length}: ${msg} (${queryPreview})`);
+            }
+            // Note: LadybugDB PreparedStatement doesn't require explicit close()
+        });
+    }
+};
+exports.executeWithReusedStatement = executeWithReusedStatement;
+const getLbugStats = async () => {
+    const c = conn;
+    if (!c)
+        return { nodes: 0, edges: 0 };
+    // Called during analyze finalize while the WAL-checkpoint driver is still
+    // running; each count read takes the connection lock so it cannot execute
+    // concurrently with a driver CHECKPOINT. Per-query locking lets the driver
+    // checkpoint between table counts rather than waiting for the whole sweep.
+    let totalNodes = 0;
+    for (const tableName of schema_js_1.NODE_TABLES) {
+        try {
+            totalNodes += await (0, conn_lock_js_1.withConnLock)(async () => {
+                const queryResult = await c.query(`MATCH (n:${escapeTableName(tableName)}) RETURN count(n) AS cnt`);
+                const nodeRows = await readQueryRows(queryResult);
+                return nodeRows.length > 0 ? Number(nodeRows[0]?.cnt ?? nodeRows[0]?.[0] ?? 0) : 0;
+            });
+        }
+        catch {
+            // ignore
+        }
+    }
+    let totalEdges = 0;
+    try {
+        totalEdges = await (0, conn_lock_js_1.withConnLock)(async () => {
+            const queryResult = await c.query(`MATCH ()-[r:${schema_js_1.REL_TABLE_NAME}]->() RETURN count(r) AS cnt`);
+            const edgeRows = await readQueryRows(queryResult);
+            return edgeRows.length > 0 ? Number(edgeRows[0]?.cnt ?? edgeRows[0]?.[0] ?? 0) : 0;
+        });
+    }
+    catch {
+        // ignore
+    }
+    return { nodes: totalNodes, edges: totalEdges };
+};
+exports.getLbugStats = getLbugStats;
+/**
+ * embeddings 子系统已删除——恒返回空缓存。
+ */
+const loadCachedEmbeddings = async () => {
+    return { embeddingNodeIds: new Set(), embeddings: [] };
+};
+exports.loadCachedEmbeddings = loadCachedEmbeddings;
+/**
+ * Fetch existing embedding hashes from CodeEmbedding table for incremental embedding.
+ * Returns a Map<nodeId, contentHash> suitable for passing to `runEmbeddingPipeline`.
+ * Handles legacy DBs without the `contentHash` column (all rows treated as stale with empty hash).
+ * Returns undefined if the CodeEmbedding table does not exist.
+ *
+ * @param execQuery - Cypher query executor (typically pool-adapter's `executeQuery`)
+ */
+const fetchExistingEmbeddingHashes = async (execQuery) => {
+    try {
+        const rows = await execQuery(`MATCH (e:${schema_js_1.EMBEDDING_TABLE_NAME}) RETURN e.nodeId AS nodeId, e.chunkIndex AS chunkIndex, e.startLine AS startLine, e.endLine AS endLine, e.contentHash AS contentHash`);
+        if (!rows || rows.length === 0)
+            return undefined;
+        const map = new Map();
+        for (const r of rows) {
+            const nodeId = r.nodeId ?? r[0];
+            const chunkIndex = r.chunkIndex ?? r[1];
+            const startLine = r.startLine ?? r[2];
+            const endLine = r.endLine ?? r[3];
+            const hash = r.contentHash ?? r[4] ?? schema_js_1.STALE_HASH_SENTINEL;
+            if (nodeId) {
+                const hasChunkMetadata = chunkIndex !== undefined &&
+                    chunkIndex !== null &&
+                    startLine !== undefined &&
+                    startLine !== null &&
+                    endLine !== undefined &&
+                    endLine !== null;
+                // Empty/null contentHash or missing chunk metadata means legacy row — treat as stale.
+                map.set(nodeId, hasChunkMetadata && hash ? hash : schema_js_1.STALE_HASH_SENTINEL);
+            }
+        }
+        return map;
+    }
+    catch (err) {
+        const msg = err?.message ?? '';
+        if (isMissingColumnOrTableError(msg)) {
+            // Legacy rows missing chunk-aware columns — treat every row as stale.
+            try {
+                const rows = await execQuery(`MATCH (e:${schema_js_1.EMBEDDING_TABLE_NAME}) RETURN e.nodeId AS nodeId`);
+                if (!rows || rows.length === 0)
+                    return undefined;
+                const map = new Map();
+                for (const r of rows) {
+                    const nodeId = r.nodeId ?? r[0];
+                    if (nodeId)
+                        map.set(nodeId, schema_js_1.STALE_HASH_SENTINEL);
+                }
+                logger_js_1.logger.info(`[embed] ${map.size} nodes in legacy DB (missing chunk-aware columns) — all treated as stale`);
+                return map;
+            }
+            catch (fallbackErr) {
+                const fallbackMsg = fallbackErr?.message ?? '';
+                if (isMissingColumnOrTableError(fallbackMsg)) {
+                    logger_js_1.logger.info(`[embed] CodeEmbedding table not yet present — full embedding run (${fallbackMsg})`);
+                    return undefined;
+                }
+                throw fallbackErr;
+            }
+        }
+        throw err;
+    }
+};
+exports.fetchExistingEmbeddingHashes = fetchExistingEmbeddingHashes;
+/**
+ * Flush the WAL so all pending writes are visible to subsequent readers.
+ *
+ * Best-effort: swallows errors from older LadybugDB versions or schemaless
+ * databases that do not support the CHECKPOINT command.  A no-op when there
+ * is nothing pending, so safe (and cheap) to call unconditionally after any
+ * write path.
+ *
+ * Use this instead of safeClose when the connection must stay open
+ * (e.g. the /api/embed handler that keeps serving queries after flushing).
+ *
+ * @see safeClose — CHECKPOINT + connection/database close
+ */
+const flushWAL = async () => {
+    const c = conn;
+    if (!c)
+        return;
+    try {
+        await (0, conn_lock_js_1.withConnLock)(async () => {
+            const checkpointResult = await c.query('CHECKPOINT');
+            await drainQueryResult(checkpointResult);
+        });
+    }
+    catch (err) {
+        logger_js_1.logger.debug(`GitNexus: LadybugDB CHECKPOINT skipped/failed during WAL flush: ${summarizeError(err)}`);
+    }
+};
+exports.flushWAL = flushWAL;
+/**
+ * Issue a manual `CHECKPOINT` against the current connection and surface
+ * any engine error to the caller. Unlike {@link flushWAL}, this variant
+ * does NOT swallow Ladybug rename/remove IO failures — the manual
+ * checkpoint driver (`wal-checkpoint-driver.ts`) relies on the rejection
+ * to drive its bounded retry loop. Returns `false` when no connection is
+ * open (the caller treats this as a no-op success — there is no WAL to
+ * flush). Returns `true` after a successful CHECKPOINT + drain.
+ *
+ * The split from `flushWAL` is deliberate: every other CHECKPOINT site
+ * (server flush, safeClose) is best-effort and prefers a silent skip;
+ * the manual driver, by contrast, must observe failures to decide
+ * whether to retry.
+ */
+const tryFlushWAL = async () => {
+    const c = conn;
+    if (!c)
+        return false;
+    // Runs on the periodic WAL-checkpoint driver. The lock makes this CHECKPOINT
+    // wait for any in-flight COPY / writeback on the singleton connection instead
+    // of executing concurrently with it (the `analyze --pdg` heap-corruption bug).
+    await (0, conn_lock_js_1.withConnLock)(async () => {
+        const checkpointResult = await c.query('CHECKPOINT');
+        await drainQueryResult(checkpointResult);
+    });
+    return true;
+};
+exports.tryFlushWAL = tryFlushWAL;
+/**
+ * Flush the WAL and close the connection and database handles.
+ *
+ * Consolidates the CHECKPOINT + close pattern into a single function so
+ * callers never call conn.close() or db.close() directly (#1376).
+ * An ESLint no-restricted-syntax rule enforces this — see eslint.config.mjs.
+ *
+ * @see flushWAL — CHECKPOINT-only (connection stays open)
+ * @see closeLbug — safeClose + module state reset (full teardown)
+ */
+const safeClose = async () => {
+    await (0, exports.flushWAL)();
+    // Capture before close — currentDbPath stays set so the Windows post-close
+    // probe below knows which file to wait on.
+    const closingDbPath = currentDbPath;
+    if (conn) {
+        try {
+            // eslint-disable-next-line no-restricted-syntax -- sole authorised close site
+            await conn.close();
+        }
+        catch {
+            /* best-effort */
+        }
+        conn = null;
+    }
+    if (db) {
+        try {
+            // eslint-disable-next-line no-restricted-syntax -- sole authorised close site
+            await db.close();
+        }
+        catch {
+            /* best-effort */
+        }
+        db = null;
+    }
+    // Windows: libuv reports `db.close()` resolved before the kernel has
+    // released the file handle. A subsequent `new Database(samePath)` in
+    // the same process can race the release. The probe (lbug-config.ts)
+    // forces any residual lock to surface as EBUSY/EPERM/EACCES so the
+    // open-time retry absorbs the lag.
+    if (process.platform === 'win32' && closingDbPath) {
+        const released = await (0, lbug_config_js_1.waitForWindowsHandleRelease)(closingDbPath);
+        if (!released) {
+            // Probe exhausted with a lock code still in flight. The next
+            // openLbugConnection will absorb whatever residual lag remains, but
+            // a chronic warning helps operators spot AV interference (Windows
+            // Defender holding the file far past the 250ms budget).
+            logger_js_1.logger.warn({ dbPath: closingDbPath }, '⚠️ LadybugDB file handle still locked after close (Windows). If this repeats, check antivirus/Defender exclusions for the GitNexus storage directory.');
+        }
+    }
+    if (closingDbPath) {
+        await (0, sidecar_recovery_js_1.finalizeLbugSidecarsAfterClose)(closingDbPath, { logger: logger_js_1.logger });
+    }
+};
+exports.safeClose = safeClose;
+/**
+ * CHECKPOINT for durability, then DELIBERATELY skip the native connection/database
+ * teardown. The name encodes the contract — there is no boolean flag to misuse:
+ * call this ONLY from a path that guarantees a `process.exit` immediately after
+ * (the CLI analyze success/SIGINT paths and the forked worker).
+ *
+ * LadybugDB's ClientContext/Connection destructor can double-free after large
+ * --pdg writes (gdb: `double free or corruption` in ClientContext::~ClientContext
+ * via NodeConnection::Close), aborting the process AFTER a fully-written,
+ * checkpointed index. flushWAL already persisted the data; process exit reclaims
+ * the native handles. We leave the handles referenced and module state intact so a
+ * GC finalizer cannot run the same destructor before exit, and any post-analyze
+ * read reuses the live connection. Mirrors the pool adapter's fire-and-forget
+ * native teardown (pool-adapter.ts) and the ONNX native-cleanup philosophy.
+ * Workaround for a LadybugDB engine bug (to be reported upstream).
+ *
+ * SAFETY: only valid when a process.exit is guaranteed to follow. Long-lived
+ * callers (MCP server, tests) leave `skipNativeCloseOnExit` unset, so
+ * runFullAnalysis closes for real via {@link closeLbug} — never this.
+ */
+const closeLbugBeforeExit = async () => {
+    await (0, exports.flushWAL)();
+    // NOTE (#2264): unlike safeClose, this deliberately does NOT run
+    // finalizeLbugSidecarsAfterClose. That step inspects/quarantines orphan WAL +
+    // sidecar files and is designed to run AFTER the native close has released the
+    // WAL handle; running it here — with the connection still open — would risk a
+    // Windows file-lock on the in-use WAL for no benefit. The CHECKPOINT above
+    // already made the index durable, and the next run's preflightLbugSidecars
+    // reconciles any residual WAL on open. The deferred sidecar housekeeping is the
+    // accepted trade-off of skipping the native close to dodge the destructor
+    // double-free.
+};
+exports.closeLbugBeforeExit = closeLbugBeforeExit;
+const closeLbug = async () => {
+    await (0, exports.safeClose)();
+    currentDbPath = null;
+    vectorExtensionLoaded = false;
+    vectorIndexEnsured = false;
+};
+exports.closeLbug = closeLbug;
+/**
+ * Thrown by {@link wipeLbugDbFiles} when a data-bearing member of the
+ * LadybugDB file family is still present after the bounded
+ * remove-and-verify retries (#2409, tri-review 4669518496 P2-4), and by
+ * run-analyze's dirty-recovery block when the crashed run's sidecars can
+ * neither be parked nor removed (this shipping review, FIX 1 — same lock
+ * class, same remediation, and the CLI already renders this type).
+ *
+ * Classify by TYPE (`err instanceof LbugWipeError`) — the repo norm from
+ * #2385 — never by message text. The MESSAGE is nonetheless fully
+ * self-contained (headline + blocked paths + remediation) because
+ * `cgraph serve` forwards only `err.message` over worker IPC
+ * (analyze-worker-core.ts), so the serve surface has nothing but this
+ * string to show the user. The holder framing deliberately covers the
+ * own-process case (FIX 2, finder A): the blocking handle is often a
+ * lingering one from THIS process's just-closed DB or a transient AV scan
+ * — not necessarily another process — so an immediate re-run often
+ * succeeds.
+ */
+class LbugWipeError extends Error {
+    /** Paths still present (or unverifiable) after all retries. */
+    survivors;
+    constructor(survivors, options) {
+        super(`${options?.headline ??
+            `Failed to remove the LadybugDB index files — still present after ` +
+                `${lbug_config_js_1.HANDLE_RELEASE_PROBE_ATTEMPTS} attempts:`}\n` +
+            survivors.map((p) => `  - ${p}`).join('\n') +
+            `\nThe blocking handle may be another process, a lingering handle from this ` +
+            `process's just-closed database, or an antivirus scan — an immediate re-run ` +
+            `often succeeds. If it persists, ${(0, sidecar_recovery_js_1.lbugLockRemediation)('re-run the analyze')}.`);
+        this.name = 'LbugWipeError';
+        this.survivors = survivors;
+    }
+}
+exports.LbugWipeError = LbugWipeError;
+/**
+ * Remove the LadybugDB file family and VERIFY each member is really gone.
+ *
+ * Owns the canonical 4-file family list — `<lbugPath>`, `.wal`, `.shadow`,
+ * `.lock` — so run-analyze's two wipe sites (full rebuild + the #2409
+ * escalation valve) can never drift apart. `.shadow` is included because a
+ * checkpoint-in-flight crash leaves a shadow sidecar, and a stale shadow next
+ * to a freshly created DB file is replay poison on the next open (#2409).
+ *
+ * Verification contract (tri-review 4669518496 P2-4 — the old inline loops
+ * swallowed rm failures and let `initLbug` reopen a still-populated DB the
+ * run believed it wiped): after `fs.rm({ recursive, force })`, each path is
+ * probed and counts as GONE only when the probe rejects with **ENOENT**. A
+ * resolving probe, or a rejection in the EPERM/EBUSY/EACCES class (Windows
+ * delete-pending / handle-release lag — see HANDLE_RELEASE_LOCK_CODES in
+ * lbug-config.ts), or any other code means the path is not verifiably gone:
+ * it is retried on the shared handle-release budget
+ * (HANDLE_RELEASE_PROBE_ATTEMPTS × linear HANDLE_RELEASE_PROBE_DELAY_MS,
+ * lbug-config.ts — the previous private mirror constants were
+ * documentation-coupled copies) and then handled by CLASS (this shipping
+ * review, FIX 2):
+ *
+ *   - DATA-BEARING members (`<lbugPath>`, `.wal`, `.shadow`) — a survivor
+ *     means the reopen would resurrect rows this run believes wiped: throw
+ *     a typed {@link LbugWipeError}.
+ *   - `.lock` — contentless: `initLbug` recreates it, and a genuinely held
+ *     lock surfaces as initLbug's own lock-busy classification (a better
+ *     error than this one). A `.lock`-only survivor (an AV-held
+ *     delete-pending handle outlasting the budget previously failed a
+ *     perfectly sound rebuild) logs a warning and CONTINUES.
+ *
+ * Linux unlinked-but-open (name gone, holder keeps the old inode) probes
+ * ENOENT and is accepted by design — both production wipe sites run after a
+ * real `closeLbug()`.
+ *
+ * Deliberately OUT of this contract: `cleanupOldKuzuFiles`
+ * (repo-manager.ts) sweeps the LEGACY kuzu-era file family during storage
+ * migration — different family, best-effort by design; and
+ * `sweepStaleSidecars` (lbug-config.ts) is a test-fixture-gated open-retry
+ * fallback that must never delete production files. Neither wipes the live
+ * DB the run is about to recreate, so neither needs (or may share) the
+ * loud-failure contract here.
+ */
+const wipeLbugDbFiles = async (lbugPath) => {
+    const lockPath = `${lbugPath}.lock`;
+    const family = [lbugPath, `${lbugPath}.wal`, `${lbugPath}.shadow`, lockPath];
+    let survivors = [];
+    for (let attempt = 1; attempt <= lbug_config_js_1.HANDLE_RELEASE_PROBE_ATTEMPTS; attempt++) {
+        survivors = [];
+        for (const f of family) {
+            try {
+                await promises_1.default.rm(f, { recursive: true, force: true });
+            }
+            catch {
+                // `force: true` swallows ENOENT, so a rejection is a real failure —
+                // but the ENOENT-probe below stays authoritative either way (another
+                // process may have removed the path between the rm and the probe).
+            }
+            const gone = await promises_1.default.access(f).then(() => false, // still present
+            (err) => err?.code === 'ENOENT');
+            if (!gone)
+                survivors.push(f);
+        }
+        if (survivors.length === 0)
+            return;
+        if (attempt < lbug_config_js_1.HANDLE_RELEASE_PROBE_ATTEMPTS) {
+            await (0, lbug_config_js_1.sleep)(lbug_config_js_1.HANDLE_RELEASE_PROBE_DELAY_MS * attempt);
+        }
+    }
+    // Class split (FIX 2): the contentless `.lock` never fails the wipe.
+    const dataSurvivors = survivors.filter((f) => f !== lockPath);
+    if (survivors.includes(lockPath)) {
+        logger_js_1.logger.warn(`GitNexus: ${lockPath} is still present after the wipe retries — continuing: the ` +
+            'lock file is contentless and initLbug recreates it; a genuinely held lock will ' +
+            "surface as the reopen's own lock-busy error.");
+    }
+    if (dataSurvivors.length > 0) {
+        throw new LbugWipeError(dataSurvivors);
+    }
+};
+exports.wipeLbugDbFiles = wipeLbugDbFiles;
+const isLbugReady = () => conn !== null && db !== null;
+exports.isLbugReady = isLbugReady;
+/**
+ * Multi-label alternation over exactly the labels that can own embedding
+ * rows: EMBEDDABLE_LABELS plus File, which embedding-pipeline.ts embeds as
+ * the zero-symbol fallback for text-only repositories (#2454). Reserved
+ * keywords are backtick-escaped via {@link escapeTableName}. Probed on
+ * @ladybugdb/core 0.18.0 (this shipping review, FIX 4): the full multi-label
+ * alternation parses, executes, and deletes exactly the joined rows —
+ * replacing the unlabeled `MATCH (n)` that scanned EVERY node table per
+ * chunk (BasicBlock-dominated under `--pdg`) when only embeddable labels
+ * can match an embedding row. Including File is free for code repositories:
+ * they never hold File embedding rows, so the extra label joins nothing.
+ */
+const embeddableLabelMatch = () => ['File', ...EMBEDDABLE_LABELS].map((l) => escapeTableName(l)).join('|');
+// LADYBUGDB-CONTRACT: matches @ladybugdb/core ^0.18.0 native binder text,
+// probe-recorded: `Binder exception: Table CodeEmbedding does not exist.`
+// When bumping LadybugDB, re-validate — `git grep "LADYBUGDB-CONTRACT"`
+// enumerates every version-coupled spot.
+const isMissingEmbeddingTableError = (err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    return msg.includes(`Table ${schema_js_1.EMBEDDING_TABLE_NAME} does not exist`);
+};
+/**
+ * Delete all nodes (and their relationships) for a specific file from LadybugDB
+ * @param filePath - The file path to delete nodes for
+ * @param dbPath - Optional path to LadybugDB for per-query connection
+ * @returns Object with counts of deleted nodes
+ */
+const deleteNodesForFile = async (filePath, dbPath) => {
+    const usePerQuery = !!dbPath;
+    // Set up connection (either use existing or create per-query)
+    let tempHandle = null;
+    let tempConn = null;
+    let targetConn = conn;
+    if (usePerQuery) {
+        tempHandle = await (0, lbug_config_js_1.openLbugConnection)(lbug, dbPath);
+        tempConn = tempHandle.conn;
+        targetConn = tempConn;
+    }
+    else if (!conn) {
+        throw new Error('LadybugDB not initialized. Provide dbPath or call initLbug first.');
+    }
+    try {
+        let deletedNodes = 0;
+        const escapedPath = (0, cypher_escape_js_1.escapeCypherString)(filePath);
+        // Delete the file's embedding rows FIRST, while their owning nodes are
+        // still present: node ids are label-first — generateId = `${label}:${name}`
+        // (src/lib/utils.ts) with qualified names that embed the file path — so
+        // the old `e.nodeId STARTS WITH '<filePath>'` shape never matched a row
+        // (tri-review 4669518496 P2-1). Join through the nodes on exact id
+        // equality instead, scoped to the embeddable labels (FIX 4 — see
+        // embeddableLabelMatch); ordering is load-bearing — after the DETACH
+        // DELETE loop below the join would match nothing.
+        try {
+            await queryAndDrain(targetConn, `MATCH (n:${embeddableLabelMatch()}) WHERE n.filePath = '${escapedPath}' ` +
+                `MATCH (e:${schema_js_1.EMBEDDING_TABLE_NAME}) WHERE e.nodeId = n.id DELETE e`);
+        }
+        catch (err) {
+            // Deliberately legacy-permissive (pinned contract:
+            // lbug-conn-serialization U5 and lbug-core-adapter expect this variant
+            // to resolve `{deletedNodes: 0}` even on a bogus dbPath): the singular
+            // variant swallows per-statement failures wholesale — its per-table
+            // loop below does the same — so a partial rethrow here would be
+            // incoherent with the rest of the function. The STRICT
+            // rethrow-except-missing-table policy lives in deleteNodesForFiles,
+            // the #2409 incremental writeback path (FIX 4). The one case worth a
+            // diagnostic is the missing embedding table.
+            if (isMissingEmbeddingTableError(err)) {
+                logger_js_1.logger.warn({ err }, `deleteNodesForFile: ${schema_js_1.EMBEDDING_TABLE_NAME} table does not exist — ` +
+                    'skipping embedding-row deletes for this DB.');
+            }
+        }
+        // Delete nodes from each table that has filePath
+        // DETACH DELETE removes the node and all its relationships
+        for (const tableName of schema_js_1.NODE_TABLES) {
+            // Skip tables that don't have filePath (Community, Process)
+            if (tableName === 'Community' || tableName === 'Process')
+                continue;
+            try {
+                // First count how many we'll delete. On the singleton connection this
+                // count runs inside withConnLock (incremental --pdg writeback executes
+                // while the WAL driver is live); per-query/temp connections skip the
+                // lock, matching queryAndDrain's `targetConn === conn` gate — the sibling
+                // DETACH DELETE below already routes through it. (#2264)
+                const tn = escapeTableName(tableName);
+                const countCypher = `MATCH (n:${tn}) WHERE n.filePath = '${escapedPath}' RETURN count(n) AS cnt`;
+                const runCount = async () => readQueryRows(await targetConn.query(countCypher));
+                const rows = isSharedSingletonConn(targetConn)
+                    ? await (0, conn_lock_js_1.withConnLock)(runCount)
+                    : await runCount();
+                const count = Number(rows[0]?.cnt ?? rows[0]?.[0] ?? 0);
+                if (count > 0) {
+                    // Delete nodes (and implicitly their relationships via DETACH)
+                    await queryAndDrain(targetConn, `MATCH (n:${tn}) WHERE n.filePath = '${escapedPath}' DETACH DELETE n`);
+                    deletedNodes += count;
+                }
+            }
+            catch (e) {
+                // Some tables may not support this query, skip
+            }
+        }
+        return { deletedNodes };
+    }
+    finally {
+        // Close per-query connection if used
+        if (tempHandle)
+            await (0, lbug_config_js_1.closeLbugConnection)(tempHandle);
+    }
+};
+exports.deleteNodesForFile = deleteNodesForFile;
+/**
+ * Chunk size for {@link deleteNodesForFiles}. 200 paths keeps each
+ * statement ~13KB (well inside parser limits) while a ~700-file write set
+ * still collapses from ~13,000 statements to 124: 31 statements per chunk
+ * (1 CodeEmbedding join-delete + 30 filePath-bearing node tables — the
+ * 32-table NODE_TABLES roster minus Community/Process) × 4 chunks. The
+ * original "~40" claim under-counted the per-chunk statement fan-out
+ * (tri-review 4669518496 accuracy sweep).
+ */
+exports.DELETE_FILES_CHUNK_SIZE = 200;
+/**
+ * Batched variant of {@link deleteNodesForFile} for the incremental
+ * writeback (#2409). One `DETACH DELETE … WHERE n.filePath IN […]` per
+ * node table per chunk of paths, instead of a count + delete per table
+ * per FILE. The per-file loop issued ~13,000 single-row write
+ * transactions on a ~700-file write set — a WAL-append storm that made
+ * the incremental path slower than a full rebuild and is the write
+ * pattern behind the native mid-writeback deaths reported in #2409.
+ *
+ * NO general error swallowing: a zero-match chunk is a no-op success by
+ * construction (every node table except Community/Process has a filePath
+ * column), so anything thrown here is a real engine failure the caller
+ * must see — silently skipping was exactly how #2409 hid its root cause.
+ * The single tolerated exception (FIX 4) is the missing-embedding-table
+ * binder error on the embedding join-delete: a DB created without
+ * EMBEDDING_SCHEMA cannot own embedding rows, so skipping that one
+ * statement is sound, while failing would brick every incremental run on
+ * such a DB until `--force`. Statement count per chunk is unchanged by the
+ * multi-label join: 1 embedding join-delete + 30 node-table deletes = 31
+ * (the rejected per-label fallback shape would have been 19 + 30 = 49).
+ * Singleton-connection only: the analyze writeback owns the write lock,
+ * and `queryAndDrain` routes through `withConnLock` for it (the WAL
+ * checkpoint driver is live during this).
+ */
+const deleteNodesForFiles = async (filePaths, options = {}) => {
+    if (!conn) {
+        throw new Error('LadybugDB not initialized. Call initLbug first.');
+    }
+    const targetConn = conn;
+    let warnedMissingEmbeddingTable = false;
+    for (let i = 0; i < filePaths.length; i += exports.DELETE_FILES_CHUNK_SIZE) {
+        const chunk = filePaths.slice(i, i + exports.DELETE_FILES_CHUNK_SIZE);
+        const listLiteral = `[${chunk.map((p) => `'${(0, cypher_escape_js_1.escapeCypherString)(p)}'`).join(', ')}]`;
+        // Embedding rows key on their OWNING NODE's id: generateId builds
+        // label-first ids — `${label}:${name}` (src/lib/utils.ts) with qualified
+        // names that embed the file path (e.g. `Function:src/f.ts:fn0:1`) — so
+        // the previous bare-path `e.nodeId STARTS WITH '<filePath>'` OR-chain
+        // could never match anything (tri-review 4669518496 P2-1: the embedding
+        // delete was a no-op). Join through the nodes instead: one multi-label
+        // MATCH over exactly the embeddable labels (FIX 4, probe-proven on
+        // 0.18.0 — see embeddableLabelMatch; the old unlabeled `MATCH (n)`
+        // scanned every node table per chunk, BasicBlock-dominated under
+        // `--pdg`, when only embeddable labels can own rows), and
+        // `e.nodeId = n.id` equality is exact — no `File:a.ts` / `File:a.tsx`
+        // prefix collisions. ORDER IS LOAD-BEARING: this must run BEFORE the
+        // DETACH DELETE loop below — once the nodes are gone the join matches
+        // nothing (empirically verified against @ladybugdb/core 0.18.0).
+        try {
+            await queryAndDrain(targetConn, `MATCH (n:${embeddableLabelMatch()}) WHERE n.filePath IN ${listLiteral} ` +
+                `MATCH (e:${schema_js_1.EMBEDDING_TABLE_NAME}) WHERE e.nodeId = n.id DELETE e`);
+        }
+        catch (err) {
+            // Tolerate exactly the missing-embedding-table binder error: a
+            // build-variant DB without EMBEDDING_SCHEMA would otherwise brick
+            // every incremental run until `--force` (FIX 4). The no-swallow
+            // policy stays for every real failure — anything else rethrows.
+            if (!isMissingEmbeddingTableError(err))
+                throw err;
+            if (!warnedMissingEmbeddingTable) {
+                warnedMissingEmbeddingTable = true;
+                logger_js_1.logger.warn({ err }, `deleteNodesForFiles: ${schema_js_1.EMBEDDING_TABLE_NAME} table does not exist — ` +
+                    'skipping embedding-row deletes for this writeback.');
+            }
+        }
+        for (const tableName of schema_js_1.NODE_TABLES) {
+            // Community/Process are graph-wide (no filePath); the orchestrator
+            // drops them wholesale via deleteAllCommunitiesAndProcesses.
+            if (tableName === 'Community' || tableName === 'Process')
+                continue;
+            const tn = escapeTableName(tableName);
+            await queryAndDrain(targetConn, `MATCH (n:${tn}) WHERE n.filePath IN ${listLiteral} DETACH DELETE n`);
+        }
+        options.onChunk?.(Math.min(i + exports.DELETE_FILES_CHUNK_SIZE, filePaths.length), filePaths.length);
+    }
+};
+exports.deleteNodesForFiles = deleteNodesForFiles;
+const getEmbeddingTableName = () => schema_js_1.EMBEDDING_TABLE_NAME;
+exports.getEmbeddingTableName = getEmbeddingTableName;
+/**
+ * Return the distinct repo-relative paths of files that import
+ * `targetFilePath` according to the IMPORTS edges currently in the
+ * DB. Used by the incremental writeback path to expand the
+ * "files-to-rewrite" set so that files importing a changed file get
+ * their edges (which may have been refined by cross-file resolution)
+ * re-emitted, rather than left stale in the DB.
+ *
+ * The DB query reads the *previous* run's state — pre-pipeline, before
+ * any nodes are deleted — so the returned importers are "files that
+ * USED TO import the target". That's the right set to invalidate:
+ * those are the files whose edges in the DB might no longer match
+ * what cross-file resolution produces given the changed file's new
+ * exports.
+ */
+const queryImporters = async (targetFilePath) => {
+    const c = conn;
+    if (!c) {
+        throw new Error('LadybugDB not initialized. Call initLbug first.');
+    }
+    const escaped = (0, cypher_escape_js_1.escapeCypherString)(targetFilePath);
+    const cypher = `
+    MATCH (a)-[r:${schema_js_1.REL_TABLE_NAME}]->(b)
+    WHERE r.type = 'IMPORTS' AND b.filePath = '${escaped}'
+    RETURN DISTINCT a.filePath AS importer
+  `;
+    // Runs inside the connection lock: queryImporters is called in the importer-BFS
+    // loop during incremental --pdg writeback while the WAL driver is live, so an
+    // unlocked conn.query here could race a concurrent CHECKPOINT on the singleton.
+    return (0, conn_lock_js_1.withConnLock)(async () => {
+        let queryResult;
+        try {
+            queryResult = await c.query(cypher);
+            const result = Array.isArray(queryResult) ? queryResult[0] : queryResult;
+            const rows = await result.getAll();
+            const out = [];
+            for (const row of rows) {
+                const v = row.importer;
+                if (typeof v === 'string' && v.length > 0)
+                    out.push(v);
+            }
+            return out;
+        }
+        catch {
+            return [];
+        }
+        finally {
+            if (queryResult)
+                await (0, query_result_utils_js_1.closeQueryResults)(queryResult);
+        }
+    });
+};
+exports.queryImporters = queryImporters;
+/**
+ * Batched variant of {@link queryImporters} for the incremental importer
+ * BFS (#2409): distinct importers of ANY of the target paths, one query per
+ * chunk per BFS depth instead of one query per frontier FILE (a ~700-file
+ * frontier was ~700 sequential round-trips, each taking the connection lock
+ * against the live WAL checkpoint driver — ~5.6s of the writeback measured).
+ *
+ * Same contract as the singular form: reads the pre-pipeline DB state and
+ * swallows per-chunk query failures into a smaller result (correctness
+ * degrades on that branch — under-expansion means possibly-stale edges —
+ * but the DB stays writable and the writeback proceeds). Unlike the singular
+ * form the degradation is not silent (tri-review 4669518496 P2-5): every
+ * dropped chunk is logged and reported through `options.onChunkFailure`, so
+ * the orchestrator can count it into the #2410 crash diagnostics
+ * (`incrementalInProgress.droppedImporterChunks`).
+ */
+const queryImportersBatch = async (targetFilePaths, options = {}) => {
+    const c = conn;
+    if (!c) {
+        throw new Error('LadybugDB not initialized. Call initLbug first.');
+    }
+    const importers = new Set();
+    for (let i = 0; i < targetFilePaths.length; i += exports.DELETE_FILES_CHUNK_SIZE) {
+        // `i` only ever advances in whole chunk strides, so this is exact.
+        const chunkIndex = i / exports.DELETE_FILES_CHUNK_SIZE;
+        const chunk = targetFilePaths.slice(i, i + exports.DELETE_FILES_CHUNK_SIZE);
+        const listLiteral = `[${chunk.map((p) => `'${(0, cypher_escape_js_1.escapeCypherString)(p)}'`).join(', ')}]`;
+        const cypher = `
+      MATCH (a)-[r:${schema_js_1.REL_TABLE_NAME}]->(b)
+      WHERE r.type = 'IMPORTS' AND b.filePath IN ${listLiteral}
+      RETURN DISTINCT a.filePath AS importer
+    `;
+        await (0, conn_lock_js_1.withConnLock)(async () => {
+            let queryResult;
+            try {
+                queryResult = await c.query(cypher);
+                const result = Array.isArray(queryResult) ? queryResult[0] : queryResult;
+                const rows = await result.getAll();
+                for (const row of rows) {
+                    const v = row.importer;
+                    if (typeof v === 'string' && v.length > 0)
+                        importers.add(v);
+                }
+            }
+            catch (err) {
+                // Degrade-don't-fail, mirroring queryImporters — but LOUDLY
+                // (tri-review 4669518496 P2-5): a dropped chunk means every importer
+                // it would have surfaced keeps possibly-stale edges this run, and the
+                // old bare `catch {}` left no trace of that anywhere. pino idiom:
+                // `err` key — `error` serializes to `{}`.
+                logger_js_1.logger.warn({ err }, `Incremental importer BFS: dropped chunk ${chunkIndex} (${chunk.length} target path(s)) — ` +
+                    'importer expansion degrades for this run; affected importers may keep stale edges until the next full rebuild.');
+                options.onChunkFailure?.(chunkIndex, chunk.length, err);
+            }
+            finally {
+                if (queryResult)
+                    await (0, query_result_utils_js_1.closeQueryResults)(queryResult);
+            }
+        });
+    }
+    // Cypher without ORDER BY is unordered — sort so downstream chunking and
+    // logs are stable run-to-run (matches diffFileHashes' sorted outputs).
+    return [...importers].sort();
+};
+exports.queryImportersBatch = queryImportersBatch;
+/**
+ * Drop every Community and Process node (and their MEMBER_OF /
+ * STEP_IN_PROCESS edges via DETACH DELETE). Used at the start of an
+ * incremental run so the communities and processes phases regenerate
+ * them from scratch on the merged graph — required for the
+ * "Leiden runs on the FULL graph" correctness invariant.
+ */
+const deleteAllCommunitiesAndProcesses = async () => {
+    const c = conn;
+    if (!c) {
+        throw new Error('LadybugDB not initialized. Call initLbug first.');
+    }
+    // count + DETACH DELETE run inside the connection lock so they cannot execute
+    // concurrently with the WAL-checkpoint driver's CHECKPOINT on the singleton
+    // connection. This runs during incremental --pdg writeback while the driver is
+    // live; mirrors the wrapped deleteAllInterprocTaintPaths / deleteAllCallSummaries.
+    return (0, conn_lock_js_1.withConnLock)(async () => {
+        let nodesDeleted = 0;
+        for (const label of ['Community', 'Process']) {
+            let countResult;
+            try {
+                countResult = await c.query(`MATCH (n:${label}) RETURN count(n) 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 (0, query_result_utils_js_1.closeQueryResults)(await c.query(`MATCH (n:${label}) DETACH DELETE n`));
+                    nodesDeleted += count;
+                }
+            }
+            catch {
+                // Table may not exist yet on a freshly-initialized DB — fine.
+            }
+            finally {
+                if (countResult)
+                    await (0, query_result_utils_js_1.closeQueryResults)(countResult);
+            }
+        }
+        return { nodesDeleted };
+    });
+};
+exports.deleteAllCommunitiesAndProcesses = deleteAllCommunitiesAndProcesses;
+/**
+ * Shared mechanics for the delete-all-relationships-of-one-type family
+ * ({@link deleteAllInterprocTaintPaths}, {@link deleteAllCallSummaries},
+ * {@link deleteAllInjects}, {@link deleteSpringAutoConfigurationDeclarations}):
+ * count the matching CodeRelation rows, then DELETE them (relationship-level —
+ * these are edge types, not node labels, so endpoints are untouched).
+ *
+ * count + DELETE run as one critical section on the singleton connection so a
+ * concurrent WAL-checkpoint cannot corrupt native state mid-delete (#pdg).
+ *
+ * @param relType       the CodeRelation `type` value to delete (e.g. 'INJECTS')
+ * @param logTag        the `[tag]` prefix on the abort error message
+ * @param duplicateNoun what the abort message says would be duplicated
+ * @param exactReasons  optional reason allowlist for a shared relationship type
+ */
+const deleteAllRelationshipsOfType = async (relType, logTag, duplicateNoun, exactReasons) => {
+    const c = conn;
+    if (!c) {
+        throw new Error('LadybugDB not initialized. Call initLbug first.');
+    }
+    return (0, conn_lock_js_1.withConnLock)(async () => {
+        let edgesDeleted = 0;
+        let countResult;
+        const reasonFilter = exactReasons === undefined || exactReasons.length === 0
+            ? ''
+            : ` AND (${exactReasons
+                .map((reason) => `r.reason = '${(0, cypher_escape_js_1.escapeCypherString)(reason)}'`)
+                .join(' OR ')})`;
+        const predicate = `r.type = '${(0, cypher_escape_js_1.escapeCypherString)(relType)}'${reasonFilter}`;
+        try {
+            countResult = await c.query(`MATCH ()-[r:CodeRelation]->() WHERE ${predicate} 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 (0, query_result_utils_js_1.closeQueryResults)(await c.query(`MATCH ()-[r:CodeRelation]->() WHERE ${predicate} 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 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 rows. The benign-vs-rethrow branch is
+            // pure, extracted, and pinned by unit tests: `classifyDeleteAllError`
+            // (lbug-config.ts, test/unit/lbug-delete-all-error.test.ts).
+            const msg = err instanceof Error ? err.message : String(err);
+            if ((0, lbug_config_js_1.classifyDeleteAllError)(err) === 'benign-missing-table') {
+                if (countResult)
+                    await (0, query_result_utils_js_1.closeQueryResults)(countResult);
+                return { edgesDeleted };
+            }
+            if (countResult)
+                await (0, query_result_utils_js_1.closeQueryResults)(countResult);
+            throw new Error(`[${logTag}] failed to clear existing ${relType} edges before incremental ` +
+                `re-write (${msg}) — aborting to avoid ${duplicateNoun}; ` +
+                `the next run will full-rebuild`);
+        }
+        if (countResult)
+            await (0, query_result_utils_js_1.closeQueryResults)(countResult);
+        return { edgesDeleted };
+    });
+};
+/**
+ * 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.
+ */
+const deleteAllInterprocTaintPaths = async () => deleteAllRelationshipsOfType('TAINT_PATH', 'taint-interproc', 'duplicate cross-function findings');
+exports.deleteAllInterprocTaintPaths = deleteAllInterprocTaintPaths;
+/**
+ * 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.
+ */
+const deleteAllCallSummaries = async () => deleteAllRelationshipsOfType('CALL_SUMMARY', 'call-summary', 'duplicate summaries');
+exports.deleteAllCallSummaries = deleteAllCallSummaries;
+/**
+ * Drop every `INJECTS` relationship (DI collection injection, #2200). Used at
+ * the start of an incremental writeback — UNCONDITIONALLY, unlike the
+ * pdg-gated twins above, because the `di` phase runs on every persisting
+ * analyze — so the phase re-materialises them from scratch on the FULL
+ * recomputed graph.
+ *
+ * Mirrors {@link deleteAllInterprocTaintPaths}: INJECTS validity is a
+ * whole-program property (a change to the interface, or a new/removed
+ * implementer, on a THIRD file creates/invalidates edges between two
+ * untouched files), so endpoint-writability extraction can't refresh them.
+ * `extractChangedSubgraph` re-includes ALL of them from the fresh graph
+ * (`isGraphWideRelType`), so delete-all-then-rebuild is the sound move.
+ * Relationship-level (INJECTS is an edge type, not a node label), so a plain
+ * DELETE on the typed CodeRelation rows — endpoints are untouched.
+ */
+const deleteAllInjects = async () => deleteAllRelationshipsOfType('INJECTS', 'di', 'duplicate INJECTS edges');
+exports.deleteAllInjects = deleteAllInjects;
+/**
+ * Drop every Spring AOP `ADVISED_BY` relationship before incremental
+ * writeback. Pointcut/annotation resolution is whole-program: adding a type in
+ * a third file can shadow a wildcard annotation import or change a wildcard
+ * execution match between two otherwise unchanged endpoint files.
+ */
+const deleteAllAdvisedBy = async () => deleteAllRelationshipsOfType('ADVISED_BY', 'spring-aop', 'duplicate ADVISED_BY edges');
+exports.deleteAllAdvisedBy = deleteAllAdvisedBy;
+/** Drop all synthetic Spring AOP evidence nodes before incremental writeback. */
+const deleteSpringAopEvidenceNodes = async () => {
+    const c = conn;
+    if (!c) {
+        throw new Error('LadybugDB not initialized. Call initLbug first.');
+    }
+    return (0, conn_lock_js_1.withConnLock)(async () => {
+        let countResult;
+        const idPrefix = (0, cypher_escape_js_1.escapeCypherString)(aop_js_1.SPRING_AOP_EVIDENCE_ID_PREFIX);
+        const predicate = `n.id STARTS WITH '${idPrefix}'`;
+        try {
+            countResult = await c.query(`MATCH (n:CodeElement) WHERE ${predicate} RETURN count(n) 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 (0, query_result_utils_js_1.closeQueryResults)(await c.query(`MATCH (n:CodeElement) WHERE ${predicate} DETACH DELETE n`));
+            }
+            if (countResult)
+                await (0, query_result_utils_js_1.closeQueryResults)(countResult);
+            return { nodesDeleted: count };
+        }
+        catch (err) {
+            if (countResult)
+                await (0, query_result_utils_js_1.closeQueryResults)(countResult);
+            if ((0, lbug_config_js_1.classifyDeleteAllError)(err) === 'benign-missing-table') {
+                return { nodesDeleted: 0 };
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            throw new Error('[spring-aop] failed to clear synthetic evidence before incremental re-write ' +
+                `(${message}) — aborting to avoid stale advice metadata; the next run will full-rebuild`);
+        }
+    });
+};
+exports.deleteSpringAopEvidenceNodes = deleteSpringAopEvidenceNodes;
+/**
+ * Drop Spring-owned auto-configuration `DECLARES` relationships before
+ * incremental writeback. `DECLARES` is generic, so exact reason filtering is
+ * required: other metadata systems must retain their own declarations.
+ */
+const deleteSpringAutoConfigurationDeclarations = async () => deleteAllRelationshipsOfType('DECLARES', 'spring-auto-configuration', 'duplicate auto-configuration declarations', auto_configuration_js_1.SPRING_AUTO_CONFIGURATION_REASONS);
+exports.deleteSpringAutoConfigurationDeclarations = deleteSpringAutoConfigurationDeclarations;
+/**
+ * Drop synthetic source-unavailable auto-configuration Class nodes before
+ * incremental writeback. The fresh full graph re-emits every still-needed
+ * synthetic node; deleting first also removes placeholders that became stale
+ * when a real source class appeared.
+ */
+const deleteSpringAutoConfigurationSyntheticClasses = async () => {
+    const c = conn;
+    if (!c) {
+        throw new Error('LadybugDB not initialized. Call initLbug first.');
+    }
+    return (0, conn_lock_js_1.withConnLock)(async () => {
+        let countResult;
+        const idPrefix = (0, cypher_escape_js_1.escapeCypherString)(auto_configuration_js_1.SPRING_AUTO_CONFIGURATION_SYNTHETIC_ID_PREFIX);
+        const predicate = `n.id STARTS WITH '${idPrefix}'`;
+        try {
+            countResult = await c.query(`MATCH (n:Class) WHERE ${predicate} RETURN count(n) 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 (0, query_result_utils_js_1.closeQueryResults)(await c.query(`MATCH (n:Class) WHERE ${predicate} DETACH DELETE n`));
+            }
+            if (countResult)
+                await (0, query_result_utils_js_1.closeQueryResults)(countResult);
+            return { nodesDeleted: count };
+        }
+        catch (err) {
+            if (countResult)
+                await (0, query_result_utils_js_1.closeQueryResults)(countResult);
+            if ((0, lbug_config_js_1.classifyDeleteAllError)(err) === 'benign-missing-table') {
+                return { nodesDeleted: 0 };
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            throw new Error('[spring-auto-configuration] failed to clear synthetic Class nodes before ' +
+                `incremental re-write (${message}) — aborting to avoid stale placeholders; ` +
+                'the next run will full-rebuild');
+        }
+    });
+};
+exports.deleteSpringAutoConfigurationSyntheticClasses = deleteSpringAutoConfigurationSyntheticClasses;
+// ============================================================================
+// VECTOR Extension Functions
+// ============================================================================
+/**
+ * Load the VECTOR extension on the supplied connection (or the singleton
+ * writable connection when none is given). Returns false when VECTOR is
+ * unavailable so semantic search can fall back to exact scan.
+ */
+const loadVectorExtension = async (targetConn, opts = {}) => {
+    const useModuleState = targetConn === undefined;
+    if (useModuleState && vectorExtensionLoaded)
+        return true;
+    // No platform gate. Windows was hard-refused here for years on the strength
+    // of an early-era report that in-process INSTALL VECTOR could SIGSEGV
+    // (#1365) — but the extension server ships win_amd64 VECTOR artifacts for
+    // every 0.18.x extension version (probed live: v0.18.0 and v0.18.1 both
+    // serve a real PE32+ DLL; the pinned 0.18.2 core resolves its extension
+    // directory to 0.18.1, strace-verified), and INSTALL now runs in a spawned
+    // child process (installDuckDbExtensionOutOfProcess), so even a crashing
+    // installer kills only the child and degrades to `false` here. LOAD of a
+    // present extension file is an ordinary in-process load whose failures
+    // surface as catchable errors.
+    const c = targetConn ?? conn;
+    if (!c) {
+        throw new Error('LadybugDB not initialized. Call initLbug first.');
+    }
+    const loaded = await extension_loader_js_1.extensionManager.ensure((sql) => queryAndDrain(c, sql), 'VECTOR', 'VECTOR', opts);
+    if (loaded && useModuleState)
+        vectorExtensionLoaded = true;
+    return loaded;
+};
+exports.loadVectorExtension = loadVectorExtension;
+/**
+ * Create the HNSW vector index on the CodeEmbedding table.
+ *
+ * MUST run via `conn.query()` (here through `queryAndDrain`), NOT through the
+ * prepared `executeQuery`/`conn.prepare()` path: `CALL CREATE_VECTOR_INDEX(...)`
+ * compiles to multiple statements, which LadybugDB cannot prepare — it fails
+ * with "Connection Exception: We do not support prepare multiple statements."
+ * Routing index creation through `executeQuery` (prepared) is exactly what
+ * broke vector-index creation during `analyze` (#2114; the singleton
+ * `executeQuery` was switched to the prepared path in #1655).
+ *
+ * Returns `true` on success (or when the index already exists — idempotent so
+ * incremental re-runs don't spuriously downgrade to exact scan), `false` when
+ * the VECTOR extension is unavailable or the connection is read-only. Any other
+ * failure propagates so the caller can log it.
+ */
+const createVectorIndex = async () => {
+    if (!conn) {
+        throw new Error('LadybugDB not initialized. Call initLbug first.');
+    }
+    // Already built on this connection — skip the round-trip.
+    if (vectorIndexEnsured)
+        return true;
+    if (!(await (0, exports.loadVectorExtension)())) {
+        return false;
+    }
+    try {
+        await queryAndDrain(conn, schema_js_1.CREATE_VECTOR_INDEX_QUERY);
+        vectorIndexEnsured = true;
+        return true;
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        // Idempotent: a prior analyze already built the HNSW index.
+        if (msg.includes('already exists')) {
+            vectorIndexEnsured = true;
+            return true;
+        }
+        // Read-only DB (e.g. the MCP query pool): writable analyze owns creation.
+        if ((0, exports.isReadOnlyDbError)(e))
+            return false;
+        throw e;
+    }
+};
+exports.createVectorIndex = createVectorIndex;
+/**
+ * The field reads every index-catalog consumer needs, each hedging the
+ * named-record form against the positional one exactly once.
+ *
+ * They exist because the hedge used to be inlined at several call sites
+ * (#2841 review). Everything version-coupled about the row shape now lives in
+ * this one block.
+ */
+const indexRowTable = (row) => row?.table_name ?? row?.[0];
+exports.indexRowTable = indexRowTable;
+const indexRowType = (row) => row?.index_type ?? row?.[2];
+exports.indexRowType = indexRowType;
+/**
+ * Read the index catalog on the writable connection, or `undefined` when it
+ * cannot be read.
+ *
+ * `SHOW_INDEXES` is readable WITHOUT any extension loaded and reports
+ * `extension_loaded` per index, so the extension-gated-DML checks below settle
+ * the common "this DB carries no such index" case with one local read and no
+ * error-string sniffing. It runs through the unprepared `conn.query()` path
+ * like every other `CALL` procedure here (#2114).
+ *
+ * `undefined` means "could not prove anything" and every caller must treat it
+ * as fail-closed (assume an index may be present), never as "no indexes". All
+ * readers below honour that (#2841 review H3). To hand ONE read to several
+ * gates, use {@link readIndexCatalogSnapshot} — passing this `undefined` on
+ * cannot be distinguished from passing nothing at all.
+ */
+const readIndexCatalogRows = async () => {
+    const targetConn = conn;
+    if (!targetConn) {
+        throw new Error('LadybugDB not initialized. Call initLbug first.');
+    }
+    try {
+        return (await (0, conn_lock_js_1.withConnLock)(async () => readQueryRows(await targetConn.query('CALL SHOW_INDEXES() RETURN *'))));
+    }
+    catch (err) {
+        logger_js_1.logger.warn({ err }, 'Could not read the LadybugDB index catalog (CALL SHOW_INDEXES()); ' +
+            'extension-gated DML checks must assume an index may be present.');
+        return undefined;
+    }
+};
+exports.readIndexCatalogRows = readIndexCatalogRows;
+/**
+ * The failed half of an {@link IndexCatalogSnapshot}: the caller DID read the
+ * catalog and could not prove anything.
+ *
+ * It exists because `undefined` was overloaded (#2841 review §5.A). The gates
+ * below took `indexRows?: IndexCatalogRow[]`, so "my read failed" and "I passed
+ * you nothing" were the SAME value, and each gate's `?? (await
+ * readIndexCatalogRows())` silently re-read the catalog — turning the one shared
+ * read the call site documents into three round-trips and three identical
+ * warnings on the failure path, with the two gates free to decide from DIFFERENT
+ * snapshots. A distinct sentinel makes "read, unreadable" a value the parameter
+ * can carry, so a supplied snapshot is never re-read.
+ */
+exports.INDEX_CATALOG_UNREADABLE = Symbol('cgraph:index-catalog-unreadable');
+/**
+ * {@link readIndexCatalogRows} in snapshot form — what callers should read once
+ * and pass to EVERY extension-gated-DML gate in a run, so the "one shared
+ * `SHOW_INDEXES` read" invariant holds on the failure branch too (#2841 review
+ * §5.A). The `IndexCatalogRow[] | undefined` spelling stays available for
+ * callers that only want the rows.
+ */
+const readIndexCatalogSnapshot = async () => (await (0, exports.readIndexCatalogRows)()) ?? exports.INDEX_CATALOG_UNREADABLE;
+exports.readIndexCatalogSnapshot = readIndexCatalogSnapshot;
+/**
+ * Resolve a gate's optional `indexRows` argument into the rows it must judge,
+ * reading the catalog AT MOST ONCE and ONLY when the caller supplied nothing.
+ *
+ * The `??` is meaningful again (#2841 review §5.A): `undefined` in can now only
+ * mean "no snapshot supplied", because a caller whose own read failed passes
+ * {@link INDEX_CATALOG_UNREADABLE}, which is truthy and short-circuits it.
+ * `undefined` OUT keeps its documented meaning — "could not prove anything",
+ * which every caller of {@link readIndexCatalogRows} treats as fail-closed.
+ */
+const resolveGateRows = async (indexRows) => {
+    const snapshot = indexRows ?? (await (0, exports.readIndexCatalogSnapshot)());
+    return snapshot === exports.INDEX_CATALOG_UNREADABLE ? undefined : snapshot;
+};
+exports.resolveGateRows = resolveGateRows;
+/**
+ * Make DML against {@link EMBEDDING_TABLE_NAME} legal on the writable
+ * connection when it can be, and report whether it is.
+ *
+ * LadybugDB refuses EVERY mutation of a table carrying an HNSW index while
+ * the VECTOR extension is not loaded on that connection: `DELETE` fails with
+ * "Trying to delete from an index on table CodeEmbedding but its extension is
+ * not loaded", `CREATE` with the matching "insert into an index" variant,
+ * `DROP TABLE` is refused while the index references it, and `SET` — even on
+ * a NON-indexed property — segfaults the process outright. Probed against
+ * @ladybugdb/core 0.18.2 (the lockfile-pinned version) and 0.18.0 — every
+ * result identical on both (#2623).
+ *
+ * Dropping the index is NOT an available recovery: `CALL DROP_VECTOR_INDEX`
+ * is itself a VECTOR-extension function and resolves to "Catalog exception:
+ * function DROP_VECTOR_INDEX is not defined" in exactly the state it would
+ * need to rescue. Loading the extension is the only in-place repair, which is
+ * why this returns a verdict instead of attempting a fixup.
+ *
+ * `true` = embedding-row DML is safe: either VECTOR is now loaded, or the
+ * table carries no index to trip over. `false` = genuinely blocked (index
+ * present, extension unloadable); the analyze orchestrator answers that by
+ * escalating to the wipe-and-rebuild write plan instead of failing
+ * mid-writeback.
+ *
+ * Cheap by construction: one {@link readIndexCatalogRows} read settles the
+ * common "this repo never built an embedding index" case without touching the
+ * extension machinery at all, so a VECTOR-less machine is not charged a bounded
+ * INSTALL attempt on every incremental analyze. (That read's own mechanics and
+ * fail-closed contract are documented there, not re-explained here — #2841
+ * review §5.H.)
+ *
+ * @param indexRows An {@link IndexCatalogSnapshot} the caller already read, so
+ * one `SHOW_INDEXES` read can settle every gate in a run. FRESHNESS CONTRACT:
+ * the snapshot must have been taken on THIS connection with nothing in between
+ * that creates or drops an index — the gate's verdict is only as current as the
+ * rows it is handed. Pass {@link INDEX_CATALOG_UNREADABLE} (what
+ * {@link readIndexCatalogSnapshot} returns) when your own read failed; that
+ * fails closed here WITHOUT a second read. Omit the argument entirely to have
+ * the gate read the catalog itself.
+ */
+const ensureEmbeddingRowDmlSafe = async (indexRows) => {
+    // Unconditional precondition (#2841 review §5.B). This check used to run on
+    // every call; adding `indexRows` moved it inside `readIndexCatalogRows`, where
+    // a caller-supplied snapshot skips it — so a closed DB could be answered
+    // `true` where it previously threw. The verdict is only meaningful for the
+    // live writable connection, so assert that before looking at the argument.
+    if (!conn) {
+        throw new Error('LadybugDB not initialized. Call initLbug first.');
+    }
+    // Catalog FIRST. The overwhelmingly common case on a repo that never enabled
+    // embeddings is "no index at all", and that is provable with one local read
+    // — no extension needed. Loading first would make every incremental analyze
+    // on a VECTOR-less machine pay a bounded out-of-process INSTALL attempt (the
+    // `auto` policy) plus an "extension unavailable" warning, for a repo that
+    // can never hit this hazard.
+    const rows = await (0, exports.resolveGateRows)(indexRows);
+    // Any non-HASH index on the embedding table gates DML. Keyed on index TYPE,
+    // not name, so an index built under a different name still counts; the
+    // implicit primary-key HASH index is engine-internal and never gates.
+    const indexGatesDml = rows === undefined ||
+        rows.some((row) => {
+            if ((0, exports.indexRowTable)(row) !== schema_js_1.EMBEDDING_TABLE_NAME)
+                return false;
+            return (0, exports.indexRowType)(row) !== 'HASH';
+        });
+    if (!indexGatesDml)
+        return true;
+    return await (0, exports.loadVectorExtension)(undefined, { policy: (0, extension_loader_js_1.resolveAnalyzeInstallPolicy)() });
+};
+exports.ensureEmbeddingRowDmlSafe = ensureEmbeddingRowDmlSafe;