gitnexus 1.6.9 → 1.6.10-aptos.0

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

@@ -6,15 +6,17 @@ import { finished } from 'stream/promises';
 import path from 'path';
 import lbug from '@ladybugdb/core';
 import { closeQueryResults } from './query-result-utils.js';
+import { escapeCypherString } from './cypher-escape.js';
 import { withConnLock } from './conn-lock.js';
 import { isWalDriverActive } from './wal-driver-state.js';
 import { NODE_TABLES, REL_TABLE_NAME, SCHEMA_QUERIES, EMBEDDING_TABLE_NAME, CREATE_VECTOR_INDEX_QUERY, STALE_HASH_SENTINEL, } from './schema.js';
 import { streamAllCSVsToDisk } from './csv-generator.js';
 import { getNodeLabel as deriveNodeLabel } from './rel-pair-routing.js';
-import { extensionManager } from './extension-loader.js';
-import { classifyDeleteAllError, closeLbugConnection, isDbBusyError, isOpenRetryExhausted, isWalCorruptionError, openLbugConnection, toNativeSafePath, resolveNativeSafeStorageDir, WAL_RECOVERY_SUGGESTION, waitForWindowsHandleRelease, } from './lbug-config.js';
-import { finalizeLbugSidecarsAfterClose, inspectLbugSidecars, isMissingShadowSidecarError, isReadOnlyShadowReplayError, preflightLbugSidecars, quarantineWalForMissingShadow, renameFailureMessage, shadowSidecarRecoveryMessage, } from './sidecar-recovery.js';
-import { isVectorExtensionSupportedByPlatform } from '../platform/capabilities.js';
+import { EMBEDDABLE_LABELS } from '../embeddings/types.js';
+import { getNodeTableColumnNames } from './node-table-layout.js';
+import { extensionManager, resolveAnalyzeInstallPolicy, } from './extension-loader.js';
+import { classifyDeleteAllError, closeLbugConnection, HANDLE_RELEASE_PROBE_ATTEMPTS, HANDLE_RELEASE_PROBE_DELAY_MS, isDbBusyError, isOpenRetryExhausted, isWalCorruptionError, openLbugConnection, sleep, toNativeSafePath, resolveNativeSafeStorageDir, WAL_RECOVERY_SUGGESTION, waitForWindowsHandleRelease, } from './lbug-config.js';
+import { finalizeLbugSidecarsAfterClose, guardWalQuarantine, isMissingShadowSidecarError, isReadOnlyShadowReplayError, lbugLockRemediation, preflightLbugSidecars, quarantineWalForMissingShadow, renameFailureMessage, shadowSidecarRecoveryMessage, } from './sidecar-recovery.js';
 import { logger } from '../logger.js';
 /**
  * Split a relationship CSV into per-label-pair files on disk.
@@ -409,23 +411,14 @@ const queryAndDrain = async (targetConn, cypher) => {
 };
 const READ_ONLY_SHADOW_REPLAY_PROBE = 'MATCH (n) RETURN n LIMIT 1';
 /**
- * Reject the quarantine path when the orphan WAL is too large to safely
- * discard (>TINY_ORPHAN_WAL_BYTES). Mirrors the preflight policy at
- * sidecar-recovery.ts:153-160 ("warn, do not quarantine"). Symmetric across
- * read-only and writable recovery paths (PR #1747 review D2).
- *
- * Throws shadowSidecarRecoveryMessage immediately when the WAL is large,
- * preserving the uncheckpointed pages for explicit operator recovery.
- * Returns silently when the WAL is absent, tiny, or in any other state
- * where the existing recovery path is safe to proceed.
+ * 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) => {
-    const state = await inspectLbugSidecars(dbPath);
-    if (state.kind === 'orphan-wal') {
-        logger.warn(`GitNexus: refusing to quarantine large WAL (${state.walBytes} bytes) at ${dbPath}.wal during ${mode} recovery; ` +
-            'manual recovery required — run `gitnexus analyze --force <repo-path> --index-only`.');
-        throw new Error(shadowSidecarRecoveryMessage(dbPath, triggeringErr));
-    }
+    await guardWalQuarantine(dbPath, mode, triggeringErr, logger);
 };
 const reopenReadOnlyAfterMissingShadow = async (dbPath, err) => {
     await refuseLargeWalQuarantine(dbPath, 'read-only', err);
@@ -673,7 +666,8 @@ const doInitLbug = async (dbPath, readOnly = false) => {
                 const realPath = await fs.realpath(dbPath);
                 const parentDir = path.dirname(dbPath);
                 const realParent = await fs.realpath(parentDir);
-                if (!realPath.startsWith(realParent + path.sep) && realPath !== realParent) {
+                const safePrefix = realParent.endsWith(path.sep) ? realParent : realParent + path.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
@@ -1091,8 +1085,49 @@ const BACKTICK_TABLES = new Set([
 const escapeTableName = (table) => {
     return BACKTICK_TABLES.has(table) ? `\`${table}\`` : table;
 };
-/** Fallback: insert relationships one-by-one if COPY fails */
-const fallbackRelationshipInserts = async (validRelLines, validTables, getNodeLabel) => {
+/**
+ * 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 `'${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`.
+ */
+export const fallbackRelationshipInserts = async (validRelLines, validTables, getNodeLabel) => {
     if (!conn)
         return;
     const escapeLabel = (label) => {
@@ -1111,11 +1146,10 @@ const fallbackRelationshipInserts = async (validRelLines, validTables, getNodeLa
                 continue;
             const confidence = parseFloat(confidenceStr) || 1.0;
             const step = parseInt(stepStr) || 0;
-            const esc = (s) => s.replace(/'/g, "''").replace(/\\/g, '\\\\').replace(/\n/g, '\\n').replace(/\r/g, '\\r');
             await queryAndDrain(conn, `
-        MATCH (a:${escapeLabel(fromLabel)} {id: '${esc(fromId)}' }),
-              (b:${escapeLabel(toLabel)} {id: '${esc(toId)}' })
-        CREATE (a)-[:${REL_TABLE_NAME} {type: '${esc(relType)}', confidence: ${confidence}, reason: '${esc(reason)}', step: ${step}}]->(b)
+        MATCH (a:${escapeLabel(fromLabel)} {id: ${formatCypherValue(fromId)} }),
+              (b:${escapeLabel(toLabel)} {id: ${formatCypherValue(toId)} })
+        CREATE (a)-[:${REL_TABLE_NAME} {type: ${formatCypherValue(relType)}, confidence: ${confidence}, reason: ${formatCypherValue(reason)}, step: ${step}}]->(b)
       `);
         }
         catch {
@@ -1131,8 +1165,13 @@ const TABLES_WITH_EXPORTED = new Set([
     'Method',
     'CodeElement',
 ]);
+const copyColumns = (columns) => columns.join(', ');
 export const getCopyQuery = (table, filePath) => {
     const t = escapeTableName(table);
+    const layoutColumns = getNodeTableColumnNames(table);
+    if (layoutColumns) {
+        return `COPY ${t}(${copyColumns(layoutColumns)}) FROM "${filePath}" ${COPY_CSV_OPTS}`;
+    }
     if (table === 'File') {
         return `COPY ${t}(id, name, filePath, content) FROM "${filePath}" ${COPY_CSV_OPTS}`;
     }
@@ -1160,6 +1199,9 @@ export const getCopyQuery = (table, filePath) => {
         // `calleeIds` is its SOUND parallel (space-joined resolved callee ids, #2227).
         return `COPY ${t}(id, filePath, startLine, endLine, text, callees, calleeIds) FROM "${filePath}" ${COPY_CSV_OPTS}`;
     }
+    if (table === 'Class') {
+        return `COPY ${t}(id, name, filePath, startLine, endLine, isExported, content, description, frameworkAnnotations) FROM "${filePath}" ${COPY_CSV_OPTS}`;
+    }
     if (table === 'Method') {
         return `COPY ${t}(id, name, filePath, startLine, endLine, isExported, content, description, parameterCount, returnType) FROM "${filePath}" ${COPY_CSV_OPTS}`;
     }
@@ -1186,52 +1228,53 @@ export const insertNodeToLbug = async (label, properties, dbPath) => {
         throw new Error('LadybugDB not initialized. Provide dbPath or call initLbug first.');
     }
     try {
-        const escapeValue = (v) => {
-            if (v === null || v === undefined)
-                return 'NULL';
-            if (typeof v === 'number')
-                return String(v);
-            // Escape backslashes first (for Windows paths), then single quotes
-            return `'${String(v).replace(/\\/g, '\\\\').replace(/'/g, "''").replace(/\n/g, '\\n').replace(/\r/g, '\\r')}'`;
-        };
+        // 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: ${escapeValue(properties.id)}, name: ${escapeValue(properties.name)}, filePath: ${escapeValue(properties.filePath)}, content: ${escapeValue(properties.content || '')}})`;
+            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: ${escapeValue(properties.id)}, name: ${escapeValue(properties.name)}, filePath: ${escapeValue(properties.filePath)}})`;
+            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: ${escapeValue(properties.description)}`
+                ? `, description: ${formatCypherValue(properties.description)}`
                 : '';
-            query = `CREATE (n:Section {id: ${escapeValue(properties.id)}, name: ${escapeValue(properties.name)}, filePath: ${escapeValue(properties.filePath)}, startLine: ${properties.startLine || 0}, endLine: ${properties.endLine || 0}, level: ${properties.level || 1}, content: ${escapeValue(properties.content || '')}${descPart}})`;
+            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: ${escapeValue(properties.id)}, filePath: ${escapeValue(properties.filePath)}, startLine: ${properties.startLine || 0}, endLine: ${properties.endLine || 0}, text: ${escapeValue(properties.text || '')}, callees: ${escapeValue(properties.callees || '')}, calleeIds: ${escapeValue(properties.calleeIds || '')}})`;
+            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: ${escapeValue(properties.description)}`
+                ? `, description: ${formatCypherValue(properties.description)}`
                 : '';
-            query = `CREATE (n:${t} {id: ${escapeValue(properties.id)}, name: ${escapeValue(properties.name)}, filePath: ${escapeValue(properties.filePath)}, startLine: ${properties.startLine || 0}, endLine: ${properties.endLine || 0}, isExported: ${!!properties.isExported}, content: ${escapeValue(properties.content || '')}${descPart}})`;
+            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: ${escapeValue(properties.description)}`
+                ? `, description: ${formatCypherValue(properties.description)}`
                 : '';
-            query = `CREATE (n:${t} {id: ${escapeValue(properties.id)}, name: ${escapeValue(properties.name)}, filePath: ${escapeValue(properties.filePath)}, startLine: ${properties.startLine || 0}, endLine: ${properties.endLine || 0}, content: ${escapeValue(properties.content || '')}${descPart}, declaredType: ${escapeValue(properties.declaredType || '')}})`;
+            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: ${escapeValue(properties.description)}`
+                ? `, description: ${formatCypherValue(properties.description)}`
                 : '';
-            query = `CREATE (n:${t} {id: ${escapeValue(properties.id)}, name: ${escapeValue(properties.name)}, filePath: ${escapeValue(properties.filePath)}, startLine: ${properties.startLine || 0}, endLine: ${properties.endLine || 0}, content: ${escapeValue(properties.content || '')}${descPart}})`;
+            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) {
@@ -1266,14 +1309,10 @@ export const insertNodeToLbug = async (label, properties, dbPath) => {
 export const batchInsertNodesToLbug = async (nodes, dbPath) => {
     if (nodes.length === 0)
         return { inserted: 0, failed: 0 };
-    const escapeValue = (v) => {
-        if (v === null || v === undefined)
-            return 'NULL';
-        if (typeof v === 'number')
-            return String(v);
-        // Escape backslashes first (for Windows paths), then single quotes, then newlines
-        return `'${String(v).replace(/\\/g, '\\\\').replace(/'/g, "''").replace(/\n/g, '\\n').replace(/\r/g, '\\r')}'`;
-    };
+    // 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 openLbugConnection(lbug, dbPath);
     const tempConn = tempHandle.conn;
@@ -1286,39 +1325,45 @@ export const batchInsertNodesToLbug = async (nodes, dbPath) => {
                 // Use MERGE instead of CREATE for upsert behavior (handles duplicates gracefully)
                 const t = escapeTableName(label);
                 if (label === 'File') {
-                    query = `MERGE (n:File {id: ${escapeValue(properties.id)}}) SET n.name = ${escapeValue(properties.name)}, n.filePath = ${escapeValue(properties.filePath)}, n.content = ${escapeValue(properties.content || '')}`;
+                    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: ${escapeValue(properties.id)}}) SET n.name = ${escapeValue(properties.name)}, n.filePath = ${escapeValue(properties.filePath)}`;
+                    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 = ${escapeValue(properties.description)}`
+                        ? `, n.description = ${formatCypherValue(properties.description)}`
                         : '';
-                    query = `MERGE (n:Section {id: ${escapeValue(properties.id)}}) SET n.name = ${escapeValue(properties.name)}, n.filePath = ${escapeValue(properties.filePath)}, n.startLine = ${properties.startLine || 0}, n.endLine = ${properties.endLine || 0}, n.level = ${properties.level || 1}, n.content = ${escapeValue(properties.content || '')}${descPart}`;
+                    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: ${escapeValue(properties.id)}}) SET n.filePath = ${escapeValue(properties.filePath)}, n.startLine = ${properties.startLine || 0}, n.endLine = ${properties.endLine || 0}, n.text = ${escapeValue(properties.text || '')}, n.callees = ${escapeValue(properties.callees || '')}, n.calleeIds = ${escapeValue(properties.calleeIds || '')}`;
+                    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 = ${escapeValue(properties.description)}`
+                        ? `, n.description = ${formatCypherValue(properties.description)}`
                         : '';
-                    query = `MERGE (n:${t} {id: ${escapeValue(properties.id)}}) SET n.name = ${escapeValue(properties.name)}, n.filePath = ${escapeValue(properties.filePath)}, n.startLine = ${properties.startLine || 0}, n.endLine = ${properties.endLine || 0}, n.isExported = ${!!properties.isExported}, n.content = ${escapeValue(properties.content || '')}${descPart}`;
+                    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 = ${escapeValue(properties.description)}`
+                        ? `, n.description = ${formatCypherValue(properties.description)}`
                         : '';
-                    query = `MERGE (n:${t} {id: ${escapeValue(properties.id)}}) SET n.name = ${escapeValue(properties.name)}, n.filePath = ${escapeValue(properties.filePath)}, n.startLine = ${properties.startLine || 0}, n.endLine = ${properties.endLine || 0}, n.content = ${escapeValue(properties.content || '')}${descPart}, n.declaredType = ${escapeValue(properties.declaredType || '')}`;
+                    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 = ${escapeValue(properties.description)}`
+                        ? `, n.description = ${formatCypherValue(properties.description)}`
                         : '';
-                    query = `MERGE (n:${t} {id: ${escapeValue(properties.id)}}) SET n.name = ${escapeValue(properties.name)}, n.filePath = ${escapeValue(properties.filePath)}, n.startLine = ${properties.startLine || 0}, n.endLine = ${properties.endLine || 0}, n.content = ${escapeValue(properties.content || '')}${descPart}`;
+                    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++;
@@ -1749,7 +1794,142 @@ export const closeLbug = async () => {
     vectorIndexEnsured = false;
     ensuredFTSIndexes.clear();
 };
+/**
+ * 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
+ * `gitnexus 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.
+ */
+export 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 ` +
+                `${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, ${lbugLockRemediation('re-run the analyze')}.`);
+        this.name = 'LbugWipeError';
+        this.survivors = survivors;
+    }
+}
+/**
+ * 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.
+ */
+export const wipeLbugDbFiles = async (lbugPath) => {
+    const lockPath = `${lbugPath}.lock`;
+    const family = [lbugPath, `${lbugPath}.wal`, `${lbugPath}.shadow`, lockPath];
+    let survivors = [];
+    for (let attempt = 1; attempt <= HANDLE_RELEASE_PROBE_ATTEMPTS; attempt++) {
+        survivors = [];
+        for (const f of family) {
+            try {
+                await fs.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 fs.access(f).then(() => false, // still present
+            (err) => err?.code === 'ENOENT');
+            if (!gone)
+                survivors.push(f);
+        }
+        if (survivors.length === 0)
+            return;
+        if (attempt < HANDLE_RELEASE_PROBE_ATTEMPTS) {
+            await sleep(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.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);
+    }
+};
 export const isLbugReady = () => conn !== null && db !== null;
+/**
+ * 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 ${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
@@ -1772,7 +1952,34 @@ export const deleteNodesForFile = async (filePath, dbPath) => {
     }
     try {
         let deletedNodes = 0;
-        const escapedPath = filePath.replace(/'/g, "''");
+        const escapedPath = 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:${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.warn({ err }, `deleteNodesForFile: ${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 NODE_TABLES) {
@@ -1802,13 +2009,6 @@ export const deleteNodesForFile = async (filePath, dbPath) => {
                 // Some tables may not support this query, skip
             }
         }
-        // Also delete any embeddings for nodes in this file
-        try {
-            await queryAndDrain(targetConn, `MATCH (e:${EMBEDDING_TABLE_NAME}) WHERE e.nodeId STARTS WITH '${escapedPath}' DELETE e`);
-        }
-        catch {
-            // Embedding table may not exist or nodeId format may differ
-        }
         return { deletedNodes };
     }
     finally {
@@ -1817,6 +2017,91 @@ export const deleteNodesForFile = async (filePath, dbPath) => {
             await closeLbugConnection(tempHandle);
     }
 };
+/**
+ * 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).
+ */
+export const 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).
+ */
+export 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 += DELETE_FILES_CHUNK_SIZE) {
+        const chunk = filePaths.slice(i, i + DELETE_FILES_CHUNK_SIZE);
+        const listLiteral = `[${chunk.map((p) => `'${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:${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.warn({ err }, `deleteNodesForFiles: ${EMBEDDING_TABLE_NAME} table does not exist — ` +
+                    'skipping embedding-row deletes for this writeback.');
+            }
+        }
+        for (const tableName of 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 + DELETE_FILES_CHUNK_SIZE, filePaths.length), filePaths.length);
+    }
+};
 export const getEmbeddingTableName = () => EMBEDDING_TABLE_NAME;
 /**
  * Return the distinct repo-relative paths of files that import
@@ -1838,7 +2123,7 @@ export const queryImporters = async (targetFilePath) => {
     if (!c) {
         throw new Error('LadybugDB not initialized. Call initLbug first.');
     }
-    const escaped = targetFilePath.replace(/'/g, "''");
+    const escaped = escapeCypherString(targetFilePath);
     const cypher = `
     MATCH (a)-[r:${REL_TABLE_NAME}]->(b)
     WHERE r.type = 'IMPORTS' AND b.filePath = '${escaped}'
@@ -1870,6 +2155,70 @@ export const queryImporters = async (targetFilePath) => {
         }
     });
 };
+/**
+ * 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`).
+ */
+export 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 += DELETE_FILES_CHUNK_SIZE) {
+        // `i` only ever advances in whole chunk strides, so this is exact.
+        const chunkIndex = i / DELETE_FILES_CHUNK_SIZE;
+        const chunk = targetFilePaths.slice(i, i + DELETE_FILES_CHUNK_SIZE);
+        const listLiteral = `[${chunk.map((p) => `'${escapeCypherString(p)}'`).join(', ')}]`;
+        const cypher = `
+      MATCH (a)-[r:${REL_TABLE_NAME}]->(b)
+      WHERE r.type = 'IMPORTS' AND b.filePath IN ${listLiteral}
+      RETURN DISTINCT a.filePath AS importer
+    `;
+        await 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.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 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();
+};
 /**
  * Drop every Community and Process node (and their MEMBER_OF /
  * STEP_IN_PROCESS edges via DETACH DELETE). Used at the start of an
@@ -2052,16 +2401,16 @@ export const loadVectorExtension = async (targetConn, opts = {}) => {
     const useModuleState = targetConn === undefined;
     if (useModuleState && vectorExtensionLoaded)
         return true;
-    // INSTALL VECTOR crashes with SIGSEGV on Windows: the KuzuDB native extension
-    // installer has an unhandled error path on Windows that raises a fatal signal
-    // that JS try/catch cannot intercept. Skip loading — vector/embedding search
-    // is unavailable but all graph index queries still work. Do NOT set
-    // vectorExtensionLoaded here: the flag means "successfully loaded", and a
-    // subsequent call would otherwise short-circuit to `return true` at the top.
-    if (process.platform === 'win32')
-        return false;
-    if (!isVectorExtensionSupportedByPlatform())
-        return false;
+    // 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, exactly like FTS.
     const c = targetConn ?? conn;
     if (!c) {
         throw new Error('LadybugDB not initialized. Call initLbug first.');
@@ -2155,6 +2504,74 @@ export const createVectorIndex = async () => {
         throw e;
     }
 };
+/**
+ * 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 local `SHOW_INDEXES` 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. `SHOW_INDEXES` is
+ * readable WITHOUT the extension and reports `extension_loaded` per index, so
+ * no error-string sniffing is needed; it runs through the unprepared
+ * `conn.query()` path like every other `CALL` procedure here (#2114).
+ */
+export const ensureEmbeddingRowDmlSafe = async () => {
+    const targetConn = conn;
+    if (!targetConn) {
+        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.
+    let indexRows;
+    try {
+        indexRows = await withConnLock(async () => readQueryRows(await targetConn.query('CALL SHOW_INDEXES() RETURN *')));
+    }
+    catch (err) {
+        // Fall through to the load attempt: unable to prove the index is absent,
+        // so the extension is the only thing that can make DML safe.
+        logger.warn({ err }, `Could not read the index catalog to check for a ${EMBEDDING_TABLE_NAME} vector index; ` +
+            'falling back to loading the VECTOR extension.');
+    }
+    // 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 = indexRows === undefined ||
+        indexRows.some((row) => {
+            const table = row?.table_name ?? row?.[0];
+            if (table !== EMBEDDING_TABLE_NAME)
+                return false;
+            return (row?.index_type ?? row?.[2]) !== 'HASH';
+        });
+    if (!indexGatesDml)
+        return true;
+    return await loadVectorExtension(undefined, { policy: resolveAnalyzeInstallPolicy() });
+};
 /**
  * Lazy-create an FTS index, caching the fact in-process.
  *
@@ -2232,7 +2649,28 @@ export const queryFTS = async (tableName, indexName, query, limit = 20, conjunct
     }
 };
 /**
- * Drop an FTS index
+ * True for the two benign "nothing to drop" `DROP_FTS_INDEX` failures —
+ * both catalog/binder exceptions, LadybugDB's classes for "this name isn't
+ * bound to anything right now" (probe-verified end-to-end through
+ * `dropFTSIndex`'s real `conn.query()` path against @ladybugdb/core
+ * 0.18.x): the named index was never created (`Binder exception: Table <T>
+ * doesn't have an index with name <name>.`), or the FTS extension/function
+ * isn't registered at all (`Catalog exception: function DROP_FTS_INDEX is
+ * not defined...`). A real engine failure — e.g. the `Runtime exception:
+ * FTS index '<name>' is inconsistent: ...` class from #2589 — is a
+ * DIFFERENT exception class (an execution-time failure, not a catalog/bind
+ * lookup miss), so this returns false for it. Anchored to the START of the
+ * message (not a bare substring search): every probed LadybugDB error leads
+ * with its exception class, and anchoring means a future message that merely
+ * mentions "Binder exception" or "Catalog exception" further in in the body
+ * of an otherwise-genuine failure can't be misclassified as benign. Pure
+ * string logic so it is unit-testable without a native LadybugDB connection.
+ */
+export const isBenignDropFtsIndexError = (message) => message.startsWith('Binder exception:') || message.startsWith('Catalog exception:');
+/**
+ * Drop an FTS index. Tolerates only {@link isBenignDropFtsIndexError} —
+ * anything else rethrows instead of being silently masked, which previously
+ * let a corrupted index persist across analyze runs undetected.
  */
 export const dropFTSIndex = async (tableName, indexName) => {
     if (!conn) {
@@ -2241,8 +2679,11 @@ export const dropFTSIndex = async (tableName, indexName) => {
     try {
         await queryAndDrain(conn, `CALL DROP_FTS_INDEX('${tableName}', '${indexName}')`);
     }
-    catch {
-        // Index may not exist
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        if (!isBenignDropFtsIndexError(msg)) {
+            throw e;
+        }
     }
     finally {
         ensuredFTSIndexes.delete(ftsIndexKey(tableName, indexName));