gitnexus 1.6.9 → 1.6.10-aptos.0

package/dist/core/run-analyze.js

@@ -10,14 +10,23 @@
  */
 import path from 'path';
 import fs from 'fs/promises';
-import { execFileSync } from 'child_process';
+import { retryRename } from '../storage/fs-atomic.js';
 import { runPipelineFromRepo } from './ingestion/pipeline.js';
+import { isMoveCompilerInputPath, moveCompilerRequiresFullRebuild, persistedMoveGraphRequiresCompiler, shouldProvisionMoveFlowBeforeFastPath, } from './move/constants.js';
+import { createMoveIngestPhase } from './move/move-ingest.js';
+import { repoHasMove } from './move/discovery.js';
+import { getMoveFlowReleaseSelection } from './move/install.js';
+import { ensureMoveFlowRuntime } from './move/provision.js';
 import { resetDegradedParseCounter } from './tree-sitter/safe-parse.js';
-import { initLbug, loadGraphToLbug, getLbugStats, executeQuery, executeWithReusedStatement, closeLbug, closeLbugBeforeExit, loadCachedEmbeddings, deleteNodesForFile, deleteAllCommunitiesAndProcesses, deleteAllInterprocTaintPaths, deleteAllCallSummaries, deleteAllInjects, queryImporters, loadFTSExtension, } from './lbug/lbug-adapter.js';
-import { createSearchFTSIndexes, initialiseSearchFTSStemmer, verifySearchFTSIndexes, } from './search/fts-indexes.js';
+import { initLbug, loadGraphToLbug, getLbugStats, executeQuery, executeWithReusedStatement, closeLbug, closeLbugBeforeExit, loadCachedEmbeddings, deleteNodesForFiles, ensureEmbeddingRowDmlSafe, deleteAllCommunitiesAndProcesses, deleteAllInterprocTaintPaths, deleteAllCallSummaries, deleteAllInjects, queryImportersBatch, loadFTSExtension, wipeLbugDbFiles, LbugWipeError, DELETE_FILES_CHUNK_SIZE, } from './lbug/lbug-adapter.js';
+import { estimateBufferPool, setBufferPoolSizeHint } from './lbug/lbug-config.js';
+import { escapeCypherString } from './lbug/cypher-escape.js';
+import { buildSearchIndexesOrDegrade, createSearchFTSIndexes, dropSearchFTSIndexes, initialiseSearchFTSStemmer, verifySearchFTSIndexes, } from './search/fts-indexes.js';
 import { cjkSegmentationModeMismatch, getSearchFTSCjkSegmentation, initialiseSearchFTSCjkSegmentation, } from './search/cjk-segmentation.js';
-import { resolveAnalyzeInstallPolicy } from './lbug/extension-loader.js';
-import { startWalCheckpointDriver, } from './lbug/wal-checkpoint-driver.js';
+import { getExtensionCapabilities, resolveAnalyzeInstallPolicy } from './lbug/extension-loader.js';
+import { diagnoseExtensionLoad } from './lbug/extension-load-error.js';
+import { startWalCheckpointDriver, checkpointOnce, } from './lbug/wal-checkpoint-driver.js';
+import { quarantineSidecarsForDirtyRecovery, inspectLbugSidecars, } from './lbug/sidecar-recovery.js';
 import { getStoragePaths, resolveBranchPlacement, saveMeta, loadMeta, ensureGitNexusIgnored, registerRepo, adoptFlatBranchLabel, isReadOnlyFilesystemError, isRepoRegistered, cleanupOldKuzuFiles, reconcileMetadataFiles, isMissingFilesystemError, INDEX_METADATA_FILE, INCREMENTAL_SCHEMA_VERSION, } from '../storage/repo-manager.js';
 import { DEFAULT_PDG_MAX_FUNCTION_LINES } from './ingestion/cfg/collect.js';
 import { DEFAULT_MAX_CFG_EDGES_PER_FUNCTION, DEFAULT_PDG_MAX_REACHING_DEF_EDGES_PER_FUNCTION, DEFAULT_PDG_MAX_CDG_EDGES_PER_FUNCTION, } from './ingestion/cfg/emit.js';
@@ -29,19 +38,61 @@ import { parseTruthyEnv, parsePositiveIntEnv } from './ingestion/utils/env.js';
 import { computeFileHashes, diffFileHashes } from '../storage/file-hash.js';
 import { extractChangedSubgraph, computeEffectiveWriteSet, } from './incremental/subgraph-extract.js';
 import { shadowCandidatesFor } from './incremental/shadow-candidates.js';
+import { shouldEscalateIncrementalWrite } from './incremental/escalation-gate.js';
 import { loadParseCache, saveParseCache, pruneCache, PARSE_CACHE_VERSION, } from '../storage/parse-cache.js';
 import { getDurableParsedFileDir, pruneAndSaveDurableParsedFileStore, } from '../storage/parsedfile-store.js';
-import { getCurrentCommit, getCurrentBranch, getRemoteUrl, hasGitDir, getInferredRepoName, resolveRepoIdentityRoot, } from '../storage/git.js';
+import { getCurrentCommit, getCurrentBranch, getRemoteUrl, hasGitDir, getInferredRepoName, isWorkingTreeDirty, resolveRepoIdentityRoot, } from '../storage/git.js';
 import { generateAIContextFiles } from '../cli/ai-context.js';
 import { sanitizeDetectedBranch } from '../cli/analyze-config.js';
 import { EMBEDDING_TABLE_NAME } from './lbug/schema.js';
 import { STALE_HASH_SENTINEL } from './lbug/schema.js';
+import { isSpringBeanCandidateSourceFile } from './ingestion/frameworks/spring/bean-catalog.js';
+import { SPRING_BEAN_INVENTORY_FEATURE } from './ingestion/frameworks/spring/analysis-features.js';
+import { SPRING_CONFIG_BINDINGS_FEATURE } from './ingestion/languages/java/analysis-features.js';
+import { CLASS_FRAMEWORK_ANNOTATIONS_FEATURE, findAnalysisFeatureMismatches, resolveAnalysisFeatureVersions, } from './analysis-features.js';
+import { analyzerRunnerIdentitiesEqual, finalizeAnalyzerRunnerIdentity, resolveAnalyzerRunnerIdentity, } from './analyzer-identity.js';
+const ANALYSIS_FEATURES = [
+    CLASS_FRAMEWORK_ANNOTATIONS_FEATURE,
+    SPRING_BEAN_INVENTORY_FEATURE,
+    SPRING_CONFIG_BINDINGS_FEATURE,
+];
+function stringList(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === 'string')
+        : [];
+}
+function collectFrameworkAnnotationDriftFiles(graph, persistedRows) {
+    const persistedById = new Map();
+    for (const row of persistedRows) {
+        if (typeof row.id === 'string') {
+            persistedById.set(row.id, stringList(row.frameworkAnnotations));
+        }
+    }
+    const driftFiles = new Set();
+    graph.forEachNode((node) => {
+        if (node.label !== 'Class')
+            return;
+        const current = stringList(node.properties.frameworkAnnotations);
+        const persisted = persistedById.get(node.id) ?? [];
+        if (current.length !== persisted.length ||
+            current.some((annotation, index) => annotation !== persisted[index])) {
+            const filePath = node.properties.filePath;
+            if (typeof filePath === 'string')
+                driftFiles.add(filePath);
+        }
+    });
+    return driftFiles;
+}
 /**
  * Logged when the optional FTS extension cannot be loaded or installed during
  * a full analyze. Kept as a named constant so the env-var/command guidance
  * stays in one place (mirrors the VECTOR message in embedding-pipeline.ts).
  */
-const FTS_UNAVAILABLE_MESSAGE = 'FTS extension unavailable; skipping search-index creation. ' +
+// Class-neutral lead, reused for the missing-dependency degrade path (#2383 F2):
+// its remedy already explains that reinstalling will NOT help, so appending the
+// generic "install with network access" tail below would contradict it.
+const FTS_UNAVAILABLE_LEAD = 'FTS extension unavailable; skipping search-index creation.';
+const FTS_UNAVAILABLE_MESSAGE = `${FTS_UNAVAILABLE_LEAD} ` +
     'Full-text/BM25 search will be disabled until the LadybugDB FTS extension is ' +
     'installed once with network access (GITNEXUS_LBUG_EXTENSION_INSTALL=auto) or ' +
     'pre-installed for offline use. Run `gitnexus doctor` for details.';
@@ -251,7 +302,7 @@ export const pdgModeMismatch = (recorded, options) => {
     }
     return false;
 };
-export async function runFullAnalysis(repoPath, options, callbacks) {
+export async function runFullAnalysis(repoPath, options, callbacks, runnerIdentityAtBootstrap) {
     const log = (msg) => callbacks.onLog?.(msg);
     const progress = (phase, percent, message) => callbacks.onProgress(phase, percent, message);
     // Resolve + validate operator-provided FTS config once, before the expensive
@@ -270,6 +321,10 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
     // (parse-cache, parsedfile-store) and the kuzu-migration cleanup live there
     // and are shared across branches (#2106 KTD7).
     const { storagePath } = getStoragePaths(repoPath);
+    // Start each analyze with a clean buffer-pool hint: any pre-pipeline DB open
+    // (e.g. the embeddings-cache open) falls back to the default until the hint is
+    // set from the built graph below, so a prior run's size can't leak in.
+    setBufferPoolSizeHint(undefined);
     // Clean up stale KuzuDB files from before the LadybugDB migration.
     const kuzuResult = await cleanupOldKuzuFiles(storagePath);
     if (kuzuResult.found && kuzuResult.needsReindex) {
@@ -328,6 +383,18 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             throw new Error('Cannot repair FTS indexes because this repository has not been analyzed yet. ' +
                 'Run `gitnexus analyze` first to create the initial index, then retry `--repair-fts`.');
         }
+        if (existingMeta.incrementalInProgress) {
+            // #2409 / tri-review 4669518496 (R6): a dirty flag means the previous
+            // run died mid-writeback — the graph may be half-written and its WAL
+            // possibly poisoned. This branch returns early, so the dirty-recovery
+            // sidecar quarantine below would never run: repairing FTS now would
+            // open the DB and replay that WAL pre-quarantine, and even a
+            // survivable open would certify FTS over a half-written graph.
+            throw new Error('Cannot repair FTS indexes: the index is mid-incremental-recovery ' +
+                '(a previous analyze run did not complete cleanly). ' +
+                'Run `gitnexus analyze` first — it recovers the index automatically — ' +
+                'then retry `--repair-fts`.');
+        }
         let lbugStat;
         try {
             lbugStat = await fs.lstat(lbugPath);
@@ -365,9 +432,23 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
                 policy: resolveAnalyzeInstallPolicy(),
             });
             if (!repairFtsAvailable) {
-                throw new Error('Cannot repair FTS indexes: the LadybugDB FTS extension is unavailable ' +
-                    '(not pre-installed and could not be installed on this machine). ' +
-                    'Run `gitnexus doctor` to install it, then retry `--repair-fts`.');
+                // Surface the load-side reason (#2374): "not pre-installed" was wrong
+                // and doctor never installed anything, so the old message trapped
+                // users in a query → repair-fts → doctor loop with no way out.
+                const rawFtsReason = getExtensionCapabilities().find((c) => c.name === 'fts')?.reason;
+                const ftsReason = rawFtsReason?.replace(/\.$/, '');
+                // A missing runtime dependency (Windows error 126, #2374) is not healed
+                // by re-installing — the file is already present. Route that class to the
+                // classified remedy (install VC++ redist / OpenSSL) instead of the old
+                // "retry the network install" text that trapped the user in a loop.
+                const { kind, remedy } = diagnoseExtensionLoad(rawFtsReason);
+                const remedyTail = kind === 'missing_dependency'
+                    ? ` ${remedy}`
+                    : '. Retry with network access and GITNEXUS_LBUG_EXTENSION_INSTALL=auto to install it, ' +
+                        'or pre-install the extension file; run `gitnexus doctor` for live FTS status.';
+                throw new Error('Cannot repair FTS indexes: the LadybugDB FTS extension failed to load' +
+                    (ftsReason ? ` — ${ftsReason}` : '') +
+                    remedyTail);
             }
             progress('fts', 85, 'Repairing search indexes...');
             await createSearchFTSIndexes({
@@ -400,20 +481,114 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             await closeLbug().catch(() => { });
         }
     }
+    // Resolve once per real analysis run so every successful metadata write
+    // carries one coherent receipt. The FTS-only repair path above intentionally
+    // returns without restamping: it does not regenerate the graph represented by
+    // RepoMeta and therefore must not claim a new analyzer identity.
+    const runnerIdentity = runnerIdentityAtBootstrap ?? resolveAnalyzerRunnerIdentity(import.meta.url);
+    if (!analyzerRunnerIdentitiesEqual(runnerIdentity, runnerIdentity)) {
+        throw new Error('Analyzer bootstrap supplied a malformed runner identity receipt');
+    }
+    let resumeEmbeddingCheckpoint = false;
+    let pendingEmbeddingNodeIds = new Set();
+    let embeddingIdentityForRun;
+    if (existingMeta?.embeddingCheckpoint) {
+        if (options.dropEmbeddings) {
+            log('Discarding the interrupted embedding checkpoint (--drop-embeddings).');
+            options = { ...options, force: true };
+        }
+        else {
+            const { resolveEmbeddingIdentity } = await import('./embeddings/embedding-identity.js');
+            embeddingIdentityForRun = resolveEmbeddingIdentity();
+            const checkpoint = existingMeta.embeddingCheckpoint;
+            if (checkpoint.provider !== embeddingIdentityForRun.provider) {
+                throw new Error('Cannot resume embedding checkpoint: the embedding provider configuration differs. ' +
+                    'Restore the matching endpoint configuration or pass --drop-embeddings to rebuild without it.');
+            }
+            if (checkpoint.model !== embeddingIdentityForRun.model ||
+                checkpoint.dimensions !== embeddingIdentityForRun.dimensions) {
+                throw new Error(`Cannot resume embedding checkpoint: it uses ${checkpoint.model} at ` +
+                    `${checkpoint.dimensions} dimensions, but this run resolves ` +
+                    `${embeddingIdentityForRun.model} at ${embeddingIdentityForRun.dimensions}. ` +
+                    'Restore the matching embedding configuration or pass --drop-embeddings to rebuild without it.');
+            }
+            resumeEmbeddingCheckpoint = true;
+            pendingEmbeddingNodeIds = new Set(checkpoint.pendingNodeIds ?? []);
+            log(`Previous analyze ended at an embedding checkpoint ` +
+                `(${checkpoint.nodesProcessed}/${checkpoint.totalNodes} nodes); resuming from persisted hashes` +
+                `${pendingEmbeddingNodeIds.size > 0 ? ` and regenerating ${pendingEmbeddingNodeIds.size} pending node(s)` : ''}.`);
+        }
+    }
     // ── Crash recovery: dirty flag forces full rebuild ────────────────
     // If the previous incremental run set incrementalInProgress and didn't
     // clear it, the on-disk index may be in a half-state. Cheapest path
     // back to a known-good index is to wipe + rebuild from scratch.
     if (existingMeta?.incrementalInProgress) {
+        const dirty = existingMeta.incrementalInProgress;
+        const dirtyDetails = typeof dirty === 'object'
+            ? [
+                dirty.phase ? `phase=${dirty.phase}` : undefined,
+                `toWrite=${dirty.toWriteCount}`,
+                dirty.importerExpansion !== undefined
+                    ? `importerExpansion=${dirty.importerExpansion}`
+                    : undefined,
+                dirty.effectiveWriteCount !== undefined
+                    ? `effectiveWrite=${dirty.effectiveWriteCount}`
+                    : undefined,
+                dirty.deleteCount !== undefined ? `deleteCount=${dirty.deleteCount}` : undefined,
+                // Only stamped when > 0 (tri-review 4669518496 P2-5): its
+                // presence means the crashed run's importer expansion was
+                // already degraded — the write set may have been under-expanded
+                // before the crash.
+                dirty.droppedImporterChunks !== undefined
+                    ? `droppedImporterChunks=${dirty.droppedImporterChunks}`
+                    : undefined,
+            ]
+                .filter(Boolean)
+                .join(', ')
+            : 'legacy dirty flag';
         log(
         // "analyze run", not "incremental run" — since #2099 F1 the flag is a
         // generic dirty marker written by BOTH writeback branches.
         'Previous analyze run did not complete cleanly (incrementalInProgress flag set); ' +
+            `last dirty state: ${dirtyDetails}; ` +
             'forcing full rebuild to restore a known-good index.');
         options = { ...options, force: true };
         // Reload meta after clearing the flag in-memory; we still want fileHashes
         // for the post-rebuild meta carry-over, but force=true ensures the
         // rebuild path executes.
+        //
+        // #2409 defect 2: the crashed writeback's WAL can be poisoned — replaying
+        // it kills the process natively, and the first DB open of this recovery
+        // run (the embedding-cache preservation open below) happens BEFORE the
+        // rebuild wipe that would discard it. Park the WAL/shadow sidecars aside
+        // now, while nothing is open, so every open in this run is replay-free.
+        // The rebuild wipes the DB regardless, so no committed data is at stake.
+        const { removed, failed } = await quarantineSidecarsForDirtyRecovery(lbugPath, log);
+        if (removed.length > 0) {
+            log(`Dirty-state recovery discarded ${removed.map((p) => path.basename(p)).join(', ')} ` +
+                'from the interrupted run (the file could not be moved aside, so its bytes were ' +
+                'removed — post-mortem forensics lost). Recovery proceeds with full embedding ' +
+                'preservation.');
+        }
+        if (failed.length > 0) {
+            // FIX 1 (this shipping review, replacing the tri-review 4669518496
+            // P2-3 drop-shape design): under a persistent lock the old drop-shape
+            // run derived its embedding mode as "drop", ran the WHOLE pipeline,
+            // and then died at the rebuild wipe on the very same handle — wasting
+            // minutes and zeroing embeddings on the way. A possibly-poisoned
+            // sidecar still sits next to the DB (any pre-wipe open would replay it
+            // and die), so failing here, in seconds, with the same actionable
+            // typed error the wipe would eventually throw is strictly better —
+            // and the CLI's LbugWipeError handler already renders it
+            // (recoveryHint 'lbug-wipe-failed'). The message is self-contained
+            // (headline + paths + lock guidance) because serve forwards only
+            // err.message over worker IPC.
+            throw new LbugWipeError(failed, {
+                headline: "Cannot start dirty-state recovery — the interrupted run's LadybugDB sidecars " +
+                    'could neither be moved aside nor removed:',
+            });
+        }
     }
     // ── pdg-mode flip forces full writeback (#2099 F1) ─────────────────
     // The incremental writeback persists only changed-file nodes, so a pdg
@@ -457,6 +632,36 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             `forcing a full rebuild so persisted rows match the current schema.`);
         options = { ...options, force: true };
     }
+    // ── independently-versioned analysis capabilities ────────────────
+    // `schemaVersion` is reserved for graph-wide incremental invariants. Some
+    // persisted semantics apply only to repositories containing relevant source
+    // files, so they carry exact feature versions instead. This guard must also
+    // run before alreadyUpToDate: current main and this PR both use schema v8,
+    // while pre-PR v8 indexes lack the Class frameworkAnnotations column and
+    // Java/Kotlin Bean evidence.
+    const persistedFilePaths = Object.keys(existingMeta?.fileHashes ?? {});
+    const expectedPersistedAnalysisFeatures = resolveAnalysisFeatureVersions(ANALYSIS_FEATURES, persistedFilePaths);
+    const persistedAnalysisFeatureMismatches = existingMeta
+        ? findAnalysisFeatureMismatches(existingMeta.analysisFeatures, expectedPersistedAnalysisFeatures)
+        : [];
+    let analysisFeatureMismatchLogged = false;
+    if (existingMeta && persistedAnalysisFeatureMismatches.length > 0) {
+        log(`analysis capabilities changed (${persistedAnalysisFeatureMismatches.join(', ')}); ` +
+            `forcing a full rebuild so persisted feature evidence is complete.`);
+        options = { ...options, force: true };
+        analysisFeatureMismatchLogged = true;
+    }
+    // Analyzer provenance is part of freshness, not merely diagnostics. A
+    // same-commit fast path must not preserve metadata produced by an older,
+    // malformed, or dependency/native-different runner. Force a real rebuild so
+    // the graph and its schema-v4 receipt are finalized atomically together.
+    if (existingMeta && !analyzerRunnerIdentitiesEqual(existingMeta.runnerIdentity, runnerIdentity)) {
+        const stampedRunnerSchema = existingMeta.runnerIdentity?.schemaVersion;
+        log(`analyzer runner identity changed (stamped schema ${String(stampedRunnerSchema ?? 'missing')}, ` +
+            `this build uses schema ${runnerIdentity.schemaVersion}); forcing a full rebuild so the ` +
+            'index provenance matches the analyzer and dependency/native runtime that produced it.');
+        options = { ...options, force: true };
+    }
     if (existingMeta &&
         cjkSegmentationModeMismatch(existingMeta.cjkSegmentation, getSearchFTSCjkSegmentation())) {
         log(`CJK segmentation mode changed (index built with '${existingMeta.cjkSegmentation ?? 'none'}', ` +
@@ -464,8 +669,39 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             `text and query-time segmentation stay in sync.`);
         options = { ...options, force: true };
     }
+    // Resolve local runtimes before the same-commit fast path. Managed
+    // provisioning is needed for a degraded/legacy graph and whenever the
+    // configured dynamic release differs from the one that built the index.
+    const hasMovePackages = await repoHasMove(repoPath);
+    const desiredMoveFlowRelease = hasMovePackages ? await getMoveFlowReleaseSelection() : undefined;
+    const persistedMoveCompilerRequired = persistedMoveGraphRequiresCompiler(existingMeta?.moveIngestAvailable, existingMeta?.fileHashes);
+    const provisionBeforeFastPath = shouldProvisionMoveFlowBeforeFastPath(hasMovePackages, persistedMoveCompilerRequired, existingMeta?.moveCompilerIdentity, existingMeta?.moveFlowReleaseSelection, desiredMoveFlowRelease);
+    let moveFlow = hasMovePackages
+        ? await ensureMoveFlowRuntime({
+            onLog: log,
+            install: provisionBeforeFastPath,
+        })
+        : null;
+    let moveCompilerRebuildApplied = false;
+    const applyMoveCompilerRebuildPolicy = () => {
+        if (!existingMeta ||
+            !moveCompilerRequiresFullRebuild(hasMovePackages, moveFlow?.identity, existingMeta.moveIngestAvailable, existingMeta.moveCompilerIdentity)) {
+            return;
+        }
+        if (!moveCompilerRebuildApplied) {
+            log(existingMeta.moveIngestAvailable === true
+                ? 'Move compiler changed; forcing a full rebuild so persisted facts match it.'
+                : 'Move compiler became available; forcing a full rebuild to backfill Move symbols.');
+        }
+        moveCompilerRebuildApplied = true;
+        options = { ...options, force: true };
+    };
+    applyMoveCompilerRebuildPolicy();
     // ── Early-return: already up to date ──────────────────────────────
-    if (existingMeta && !options.force && existingMeta.lastCommit === currentCommit) {
+    if (existingMeta &&
+        !existingMeta.embeddingCheckpoint &&
+        !options.force &&
+        existingMeta.lastCommit === currentCommit) {
         // Non-git folders have currentCommit = '' — always rebuild since we can't detect changes
         if (currentCommit !== '') {
             // For git repos, even if HEAD matches lastCommit, the working tree
@@ -480,33 +716,7 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             // Counting them as dirty would perpetually defeat the up-to-date
             // fast path because the previous analyze just wrote them
             // (regression vs PR #1233 behavior).
-            const dirty = (() => {
-                try {
-                    const out = execFileSync('git', [
-                        'status',
-                        '--porcelain',
-                        '--',
-                        '.',
-                        ':(exclude).gitnexus',
-                        ':(exclude).gitnexus/**',
-                        ':(exclude).claude',
-                        ':(exclude).claude/**',
-                        ':(exclude).cursor',
-                        ':(exclude).cursor/**',
-                        ':(exclude)AGENTS.md',
-                        ':(exclude)CLAUDE.md',
-                    ], {
-                        cwd: repoPath,
-                        stdio: ['ignore', 'pipe', 'ignore'],
-                        windowsHide: true,
-                        encoding: 'utf8',
-                    });
-                    return out.trim().length > 0;
-                }
-                catch {
-                    return true; // conservative on git failure
-                }
-            })();
+            const dirty = isWorkingTreeDirty(repoPath);
             // Registration wrinkle around the fast path (#2264). A prior
             // `analyze --name X` that hit a name collision writes meta.json (meta-save
             // runs before registerRepo) then fails before registering, leaving the
@@ -554,6 +764,7 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
                     }
                 }
                 await ensureGitNexusIgnored(repoPath);
+                await moveFlow?.client.shutdown();
                 return {
                     // `resolveRepoIdentityRoot` collapses worktree roots to the
                     // canonical repo basename (#1259) but leaves arbitrary subdirs
@@ -569,6 +780,19 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             }
         }
     }
+    // From this point onward analysis may write or derive graph data. Never run
+    // that plan without the compiler that produced an existing Move graph: a
+    // partial rebuild would silently erase Move rows or degrade global clusters.
+    if (hasMovePackages && !moveFlow) {
+        moveFlow = await ensureMoveFlowRuntime({ onLog: log });
+        if (persistedMoveCompilerRequired && !moveFlow) {
+            throw new Error('move-flow is unavailable; the existing Move graph was left unchanged. ' +
+                'Restore move-flow or set MOVE_FLOW, then retry analysis.');
+        }
+    }
+    const moveFlowClient = moveFlow?.client ?? null;
+    const moveIngestAvailable = hasMovePackages ? moveFlow !== null : undefined;
+    applyMoveCompilerRebuildPolicy();
     // ── Cache embeddings from existing index before rebuild ────────────
     // Four modes:
     //   --embeddings              -> load cache, restore, then generate any new ones
@@ -587,7 +811,9 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
     let cachedEmbeddingNodeIds = new Set();
     let cachedEmbeddings = [];
     const existingEmbeddingCount = existingMeta?.stats?.embeddings ?? 0;
-    const { forceRegenerateEmbeddings, preserveExistingEmbeddings, shouldGenerateEmbeddings, shouldLoadCache, } = _deriveEmbeddingMode(options, existingEmbeddingCount);
+    const { forceRegenerateEmbeddings, preserveExistingEmbeddings, shouldGenerateEmbeddings: derivedShouldGenerateEmbeddings, shouldLoadCache: derivedShouldLoadCache, } = _deriveEmbeddingMode(options, existingEmbeddingCount);
+    const shouldGenerateEmbeddings = derivedShouldGenerateEmbeddings || resumeEmbeddingCheckpoint;
+    const shouldLoadCache = derivedShouldLoadCache || resumeEmbeddingCheckpoint;
     if (options.dropEmbeddings && existingEmbeddingCount > 0) {
         log(`Dropping ${existingEmbeddingCount} existing embeddings (--drop-embeddings). ` +
             `Re-run with --embeddings to regenerate.`);
@@ -610,6 +836,12 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
     // silently dropping embeddings on a mispredicted run. The re-insert
     // step gates itself on the actual `isIncremental` value to avoid
     // PK-conflicts when the incremental writeback path keeps the rows.
+    //
+    // This is the FIRST DB open of the run — the one #2409 defect 2 is about.
+    // On a dirty-recovery run it happens only after the sidecar quarantine
+    // moved (or removed) the crashed run's WAL/shadow; when neither was
+    // possible the dirty block above already threw a LbugWipeError, so this
+    // open is replay-free by construction (FIX 1 of this shipping review).
     if (shouldLoadCache && existingMeta) {
         try {
             progress('embeddings', 0, 'Caching embeddings...');
@@ -643,35 +875,44 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
     // in-place (cache hits leave entries unchanged; misses add new ones).
     const parseCache = await loadParseCache(storagePath);
     // ── Phase 1: Full Pipeline (0–60%) ────────────────────────────────
-    const pipelineResult = await runPipelineFromRepo(repoPath, (p) => {
-        const phaseLabel = PHASE_LABELS[p.phase] || p.phase;
-        const scaled = Math.round(p.percent * 0.6);
-        const message = p.detail
-            ? `${p.message || phaseLabel} (${p.detail})`
-            : p.message || phaseLabel;
-        progress(p.phase, scaled, message);
-    }, {
-        parseCache,
-        workerPoolSize: options.workerPoolSize,
-        // CFG/PDG opt-in (#2081 M1). PipelineOptions.pdg fans out to the worker
-        // build gate (workerData.pdg) and the scope-resolution emit gate.
-        pdg: options.pdg === true,
-        pdgMaxFunctionLines: options.pdgMaxFunctionLines,
-        pdgMaxEdgesPerFunction: options.pdgMaxEdgesPerFunction,
-        pdgMaxReachingDefEdgesPerFunction: options.pdgMaxReachingDefEdgesPerFunction,
-        pdgMaxCdgEdgesPerFunction: options.pdgMaxCdgEdgesPerFunction,
-        pdgMaxTaintFindingsPerFunction: options.pdgMaxTaintFindingsPerFunction,
-        pdgMaxTaintHops: options.pdgMaxTaintHops,
-        pdgMaxInterprocFindings: options.pdgMaxInterprocFindings,
-        pdgMaxInterprocHops: options.pdgMaxInterprocHops,
-        pdgMaxInterprocEdges: options.pdgMaxInterprocEdges,
-        // Streaming/chunked PDG emit (#2202) — gated to full-rebuild runs
-        // (force === true) so the incremental writeback never reads back an
-        // offloaded BasicBlock layer. Memory-only; byte-identical output.
-        streamPdgEmit: resolveStreamPdgEmit(options),
-        pdgEmitChunkSize: resolvePdgEmitChunkSize(options),
-        fetchWrappers: options.fetchWrappers,
-    });
+    // `finally` guarantees the spawned move-flow child is released even if the
+    // pipeline throws — important for long-running hosts (MCP daemon, eval-server).
+    let pipelineResult;
+    try {
+        pipelineResult = await runPipelineFromRepo(repoPath, (p) => {
+            const phaseLabel = PHASE_LABELS[p.phase] || p.phase;
+            const scaled = Math.round(p.percent * 0.6);
+            const message = p.detail
+                ? `${p.message || phaseLabel} (${p.detail})`
+                : p.message || phaseLabel;
+            progress(p.phase, scaled, message);
+        }, {
+            parseCache,
+            workerPoolSize: options.workerPoolSize,
+            standaloneIngestPhase: createMoveIngestPhase(moveFlowClient),
+            // CFG/PDG opt-in (#2081 M1). PipelineOptions.pdg fans out to the worker
+            // build gate (workerData.pdg) and the scope-resolution emit gate.
+            pdg: options.pdg === true,
+            pdgMaxFunctionLines: options.pdgMaxFunctionLines,
+            pdgMaxEdgesPerFunction: options.pdgMaxEdgesPerFunction,
+            pdgMaxReachingDefEdgesPerFunction: options.pdgMaxReachingDefEdgesPerFunction,
+            pdgMaxCdgEdgesPerFunction: options.pdgMaxCdgEdgesPerFunction,
+            pdgMaxTaintFindingsPerFunction: options.pdgMaxTaintFindingsPerFunction,
+            pdgMaxTaintHops: options.pdgMaxTaintHops,
+            pdgMaxInterprocFindings: options.pdgMaxInterprocFindings,
+            pdgMaxInterprocHops: options.pdgMaxInterprocHops,
+            pdgMaxInterprocEdges: options.pdgMaxInterprocEdges,
+            // Streaming/chunked PDG emit (#2202) — gated to full-rebuild runs
+            // (force === true) so the incremental writeback never reads back an
+            // offloaded BasicBlock layer. Memory-only; byte-identical output.
+            streamPdgEmit: resolveStreamPdgEmit(options),
+            pdgEmitChunkSize: resolvePdgEmitChunkSize(options),
+            fetchWrappers: options.fetchWrappers,
+        });
+    }
+    finally {
+        await moveFlowClient?.shutdown();
+    }
     // ── Phase 2: LadybugDB (60–85%) ──────────────────────────────────
     progress('lbug', 60, 'Loading into LadybugDB...');
     // Compute current per-file content hashes from the pipeline's File nodes.
@@ -686,22 +927,88 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
         }
     });
     const newFileHashes = await computeFileHashes(repoPath, allFilePaths);
+    const currentAnalysisFeatures = resolveAnalysisFeatureVersions(ANALYSIS_FEATURES, allFilePaths);
+    const currentAnalysisFeatureMismatches = existingMeta
+        ? findAnalysisFeatureMismatches(existingMeta.analysisFeatures, currentAnalysisFeatures)
+        : [];
+    if (existingMeta &&
+        currentAnalysisFeatureMismatches.length > 0 &&
+        !analysisFeatureMismatchLogged) {
+        // Covers a repository gaining or losing its first applicable source file:
+        // the persisted file list cannot predict that transition before the
+        // pipeline, but an incremental top-up would leave unchanged rows incomplete.
+        log(`analysis capabilities changed (${currentAnalysisFeatureMismatches.join(', ')}); ` +
+            `forcing a full rebuild so persisted feature evidence is complete.`);
+        options = { ...options, force: true };
+    }
     // Decide incremental vs full at THIS point (post-pipeline, pre-DB).
     // All eligibility conditions are checked here against the actual
     // pipeline output — no separate pre-pipeline prediction to desync from
     // (Bugbot review on PR #1479: a prediction that flipped post-pipeline
     // could skip the embedding cache load and then take the full-rebuild
     // path, silently losing embeddings).
-    const isIncremental = !options.force &&
+    const incrementalCandidate = !options.force &&
         !!existingMeta &&
         existingMeta.schemaVersion === INCREMENTAL_SCHEMA_VERSION &&
+        currentAnalysisFeatureMismatches.length === 0 &&
         !!existingMeta.fileHashes &&
         Object.keys(existingMeta.fileHashes).length > 0 &&
         repoHasGit &&
         allFilePaths.length > 0;
-    const hashDiff = isIncremental
+    const candidateHashDiff = incrementalCandidate
         ? diffFileHashes(newFileHashes, existingMeta.fileHashes)
         : undefined;
+    const moveCompilerInputsChanged = candidateHashDiff !== undefined &&
+        [...candidateHashDiff.changed, ...candidateHashDiff.added, ...candidateHashDiff.deleted].some(isMoveCompilerInputPath);
+    const isIncremental = incrementalCandidate && !moveCompilerInputsChanged;
+    const hashDiff = isIncremental ? candidateHashDiff : undefined;
+    if (incrementalCandidate && moveCompilerInputsChanged) {
+        log('Move compiler inputs changed; using a full rebuild for package-wide consistency.');
+    }
+    // #2 atomic index publish: on a full rebuild, build the fresh DB at a temp
+    // path and swap it over the live index in one rename at the very end, so a
+    // concurrent MCP reader opening mid-build only ever sees the previous
+    // complete index (never a wiped/half-built file) and a crash leaves the old
+    // index intact. The whole build flows through the singleton connection, so
+    // only initLbug/wipeLbugDbFiles below take the temp target.
+    //
+    // POSIX only: the common CLI/serve-worker analyze paths skip the native close
+    // (closeLbugBeforeExit, #2264) and leave the build handle open at swap time.
+    // POSIX renames an open file cleanly; a same-process open handle blocks the
+    // rename on Windows. Windows keeps the current in-place behavior
+    // (buildPath === lbugPath, no swap) until that is resolved (see §12/follow-up).
+    const isFullRebuild = !(isIncremental && hashDiff);
+    // Where the swap is allowed:
+    //  - POSIX renames an open file, so the usual skip-native-close (#2264) is
+    //    fine and the swap always applies.
+    //  - Windows can swap only when a real close is safe to release the build
+    //    handle before the rename — i.e. NOT a --pdg run (the #2264 destructor
+    //    crash). Unverified on Windows CI; falls back to in-place otherwise.
+    const posixSwap = process.platform !== 'win32';
+    // #2614 Windows: the forced real-close before the rename re-bets that #2264 is
+    // --pdg-only, which is unproven (the CLI/worker skip the native close
+    // UNCONDITIONALLY) and unverifiable without a Windows runner. Keep it opt-in
+    // (GITNEXUS_ATOMIC_WINDOWS_SWAP=1) so the default Windows analyze stays on the
+    // proven in-place path; enable it only to test the Windows swap.
+    const windowsSwapOk = process.platform === 'win32' &&
+        options.pdg !== true &&
+        process.env.GITNEXUS_ATOMIC_WINDOWS_SWAP === '1';
+    // Incremental atomicity copies the whole index into the temp before mutating
+    // it, which negates incremental's speed premise — so it is opt-in
+    // (GITNEXUS_ATOMIC_INCREMENTAL=1) pending a benchmark. Full rebuilds always
+    // swap where the platform allows.
+    const wantAtomicIncremental = isIncremental && !!hashDiff && process.env.GITNEXUS_ATOMIC_INCREMENTAL === '1';
+    // #2614 F3: the copy-then-swap stages ONLY the main lbug file, so a live index
+    // carrying an orphan .wal/.shadow (a silently-failed prior checkpoint) would
+    // be copied incompletely and lose that delta. Only take the atomic path when
+    // the live index is a consolidated single file; otherwise fall back to the
+    // in-place writeback, which the next open replays correctly.
+    const atomicIncremental = wantAtomicIncremental && (await inspectLbugSidecars(lbugPath)).kind === 'clean';
+    if (wantAtomicIncremental && !atomicIncremental) {
+        log('atomic-incremental: live index carries orphan sidecars — using in-place writeback');
+    }
+    const useAtomicSwap = (isFullRebuild || atomicIncremental) && (posixSwap || windowsSwapOk);
+    const buildPath = useAtomicSwap ? `${lbugPath}.new` : lbugPath;
     if (isIncremental && hashDiff) {
         log(`Incremental: changed=${hashDiff.changed.length}, ` +
             `added=${hashDiff.added.length}, ` +
@@ -709,13 +1016,25 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             `(skipping wipe + ${allFilePaths.length - hashDiff.toWrite.length} unchanged file rows preserved)`);
         // Set the dirty flag BEFORE any destructive DB mutation. Cleared on
         // success at the meta-save step. Scoped to this branch's meta.json.
+        const now = Date.now();
         await saveMeta(metaDir, {
             ...existingMeta,
             incrementalInProgress: {
-                startedAt: Date.now(),
+                startedAt: now,
+                updatedAt: now,
+                phase: 'pre-write',
                 toWriteCount: hashDiff.toWrite.length,
+                directWriteCount: hashDiff.toWrite.length,
             },
         });
+        if (atomicIncremental) {
+            // Stage the live index into the temp so the in-place delete/writeback
+            // below mutates the COPY, and the end-of-run swap publishes it atomically.
+            // Clear any stale temp first (a crashed run), then copy the (consolidated,
+            // single-file) live index. Whole-file copy — hence opt-in.
+            await wipeLbugDbFiles(buildPath);
+            await fs.copyFile(lbugPath, buildPath);
+        }
     }
     else {
         // Full rebuild path: wipe DB files first.
@@ -727,23 +1046,42 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
         // pdg flip, certify zombie/missing BasicBlock rows indefinitely).
         // toWriteCount: 0 is the full-path sentinel (no incremental write set).
         if (existingMeta) {
+            const now = Date.now();
             await saveMeta(metaDir, {
                 ...existingMeta,
-                incrementalInProgress: { startedAt: Date.now(), toWriteCount: 0 },
+                incrementalInProgress: {
+                    startedAt: now,
+                    updatedAt: now,
+                    phase: 'full-rebuild',
+                    toWriteCount: 0,
+                },
             });
         }
         await closeLbug();
-        const lbugFiles = [lbugPath, `${lbugPath}.wal`, `${lbugPath}.lock`];
-        for (const f of lbugFiles) {
-            try {
-                await fs.rm(f, { recursive: true, force: true });
-            }
-            catch {
-                /* swallow */
-            }
-        }
+        // Shared loud wipe (#2409 + tri-review 4669518496 P2-4). The 4-file
+        // family list — `.shadow` included, because a checkpoint-in-flight crash
+        // leaves a shadow sidecar that is replay poison next to a freshly created
+        // DB file — lives in wipeLbugDbFiles so this site and the escalation
+        // valve below can never drift. Failures now throw a typed LbugWipeError
+        // (ENOENT-verified removal) instead of silently letting initLbug reopen
+        // a still-populated DB this run believes it wiped.
+        //
+        // With the atomic swap (POSIX), this wipes the TEMP build target
+        // (`buildPath` = `<lbugPath>.new`, clearing any stragglers from a crashed
+        // run) and leaves the live index untouched until the end-of-run swap. On
+        // Windows buildPath === lbugPath, so this is the original in-place wipe.
+        await wipeLbugDbFiles(buildPath);
     }
-    await initLbug(lbugPath);
+    // Size the buffer pool to the graph just built by the pipeline (a page cache
+    // over the on-disk index, which scales with node/edge count) instead of the
+    // fixed 2 GiB default, whose eager commit dominates large-repo analyze. The
+    // size is clamped to [COPY-safety floor, default], so it only ever shrinks
+    // the pool; env override / no-hint paths are unchanged. See
+    // resolveBufferManagerSize / estimateBufferPool.
+    setBufferPoolSizeHint(estimateBufferPool(pipelineResult.graph.nodeCount + pipelineResult.graph.relationshipCount));
+    // Full rebuild (POSIX) builds into the temp `buildPath`; incremental and
+    // Windows use `buildPath === lbugPath` in place.
+    await initLbug(buildPath);
     // Manual WAL checkpoint driver (#1741): periodically drain the WAL
     // from JS so the un-retriable native auto-checkpoint almost never
     // has work left to do. Failures of the manual CHECKPOINT are absorbed
@@ -752,12 +1090,31 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
     // Opt-out via `GITNEXUS_WAL_MANUAL_CHECKPOINT=0` (the driver itself
     // returns a no-op handle when disabled). Analyze-only: MCP and serve
     // paths continue to rely on the close-time CHECKPOINT in `safeClose`.
-    const walCheckpointDriver = startWalCheckpointDriver();
+    // `let`: the incremental branch's escalation valve (#2409) stops this driver
+    // around its close→wipe→reopen strategy switch and starts a fresh one.
+    let walCheckpointDriver = startWalCheckpointDriver();
     try {
         // All work after initLbug is wrapped in try/finally to ensure closeLbug()
         // is called even if an error occurs — the module-level singleton DB handle
         // must be released to avoid blocking subsequent invocations.
         let lbugMsgCount = 0;
+        // #2409 escalation valve outcome, hoisted above the incremental branch so
+        // the vector-index recreation seam in Phase 4 below can tell "surgical
+        // incremental" (DB files survived — the HNSW index with them) apart from
+        // "escalated full write" (DB wiped, index destroyed) — tri-review
+        // 4669518496 P1.
+        let escalatedFullWrite = false;
+        // Phase 3.5's restore scope (FIX 3 of this shipping review): on the
+        // SURGICAL write plan this is the exact file set whose rows
+        // deleteNodesForFiles just removed — only THOSE files' cached embedding
+        // rows need re-inserting (everything else still sits in the DB, and
+        // re-inserting it would PK-conflict). `null` means the DB was wiped
+        // (full rebuild or escalated write): the embedding table is fresh and
+        // every cached row must come back. Deriving this in memory replaces the
+        // old whole-table `RETURN e.id` pre-read, which rescanned data this
+        // process already holds and — worse — ran a read against the DB between
+        // writeback and finalize for no recovery benefit.
+        let deletedFilePathsForRestore = null;
         if (isIncremental && hashDiff) {
             // ── Incremental DB writeback ───────────────────────────────────
             // 0. Expand the writable set with transitive importers of
@@ -782,21 +1139,50 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             //    self-acknowledged as best-effort; `--force` remains the
             //    escape hatch documented in GUARDRAILS.md.
             //
-            //    `queryImporters` reads `IMPORTS` from the pre-pipeline DB
+            //    `queryImportersBatch` reads `IMPORTS` from the pre-pipeline DB
             //    state, so the result is "files that USED TO import the
             //    target" — exactly the set whose previously-stored edges may
             //    no longer match what cross-file resolution produces this run.
             const MAX_IMPORTER_BFS_DEPTH = 4;
+            // Escalation thresholds (#2409) live with shouldEscalateIncrementalWrite
+            // in incremental/escalation-gate.ts (pure predicate, boundary-tested).
             const writableFiles = new Set(hashDiff.toWrite);
             const directlyChangedCount = writableFiles.size;
-            // Shadow-seed: for ADDED files, queryImporters returns 0 (the new
+            const dirtyStartedAt = existingMeta.incrementalInProgress?.startedAt ?? Date.now();
+            // Dropped-chunk observability (tri-review 4669518496 P2-5): counts
+            // importer-BFS chunks whose IMPORTS query failed across ALL depths
+            // (degrade-don't-fail — the expansion shrinks instead of the run
+            // dying). Stamped into the #2410 crash diagnostics by
+            // saveIncrementalDirtyState ITSELF (FIX 6 of this shipping review),
+            // not by per-call-site spreads: the closure rebuilds its object from
+            // scratch on every call, so a count riding along at only some sites
+            // meant any newly added save site would silently erase it — exactly
+            // the phases where #2409-class crashes happen. >0-only semantics
+            // unchanged: unconditional zero-stamping would churn every
+            // strict-equality consumer of the diagnostics shape.
+            let droppedImporterChunks = 0;
+            const saveIncrementalDirtyState = async (phase, extra = {}) => {
+                await saveMeta(metaDir, {
+                    ...existingMeta,
+                    incrementalInProgress: {
+                        startedAt: dirtyStartedAt,
+                        updatedAt: Date.now(),
+                        phase,
+                        toWriteCount: writableFiles.size,
+                        directWriteCount: directlyChangedCount,
+                        ...(droppedImporterChunks > 0 ? { droppedImporterChunks } : {}),
+                        ...extra,
+                    },
+                });
+            };
+            // Shadow-seed: for ADDED files, the importer query returns 0 (the new
             // file has no IMPORTS rows in the pre-pipeline DB yet). But pre-
             // existing unchanged files may have IMPORTS edges whose module-
             // resolution claim the newcomer can steal under standard JS/TS
             // resolution (Bugbot review on PR #1479). For each added file we
             // derive the shadow candidates and, if the candidate was a known
             // file in the prior meta, seed it into the BFS frontier so its
-            // importers — surfaced via queryImporters — get their CALLS edges
+            // importers — surfaced via the importer BFS — get their CALLS edges
             // re-resolved against the new file. See shadow-candidates.ts for
             // the full pattern catalogue.
             const priorFileSet = new Set(existingMeta?.fileHashes ? Object.keys(existingMeta.fileHashes) : []);
@@ -809,28 +1195,33 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
                 }
             }
             {
+                // Batched per depth level (#2409): one IN-list query per ~200-path
+                // chunk instead of one query per frontier file — a ~700-file frontier
+                // used to cost ~700 sequential lock-taking round-trips (~5.6s). The
+                // closure is identical: importers already in writableFiles are not
+                // re-frontiered, exactly like the per-file loop's membership check.
                 let frontier = [...hashDiff.toWrite, ...hashDiff.deleted, ...shadowSeed];
                 for (let depth = 0; depth < MAX_IMPORTER_BFS_DEPTH && frontier.length > 0; depth++) {
+                    const importers = await queryImportersBatch(frontier, {
+                        onChunkFailure: () => {
+                            droppedImporterChunks += 1;
+                        },
+                    });
                     const nextFrontier = [];
-                    for (const f of frontier) {
-                        try {
-                            const importers = await queryImporters(f);
-                            for (const i of importers) {
-                                if (!writableFiles.has(i)) {
-                                    writableFiles.add(i);
-                                    nextFrontier.push(i);
-                                }
-                            }
-                        }
-                        catch {
-                            /* per-file importer query failure → skip; correctness degrades on
-                               that branch, but DB stays writable. */
+                    for (const i of importers) {
+                        if (!writableFiles.has(i)) {
+                            writableFiles.add(i);
+                            nextFrontier.push(i);
                         }
                     }
                     frontier = nextFrontier;
                 }
             }
             const importerExpansion = writableFiles.size - directlyChangedCount;
+            await saveIncrementalDirtyState('importer-bfs', {
+                importerExpansion,
+                shadowSeedCount: shadowSeed.length,
+            });
             if (importerExpansion > 0) {
                 log(`Incremental: +${importerExpansion} importer(s) added to writable set ` +
                     `(BFS depth ≤ ${MAX_IMPORTER_BFS_DEPTH}` +
@@ -848,69 +1239,221 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             //          cross-file CALLS edges that the pre-run DB couldn't
             //          predict, e.g. a barrel re-export shifting `foo` from
             //          B to D).
-            //    The composed set is the input to BOTH deleteNodesForFile
+            //    The composed set is the input to BOTH deleteNodesForFiles
             //    and extractChangedSubgraph — asymmetry between the two would
             //    leave stale rows or PK-conflict at COPY time.
             const effectiveWriteSet = computeEffectiveWriteSet(pipelineResult.graph, writableFiles);
+            // `frameworkAnnotations` is derived from cross-file JVM visibility, so
+            // an unchanged Class row can change when a same-package declaration is
+            // added or removed without producing an IMPORTS edge. Compare the fresh
+            // graph against the pre-write DB and rewrite only files whose persisted
+            // value drifted. Add them after edge-boundary expansion: relationships
+            // touching these files are already included by extractChangedSubgraph,
+            // while pulling every unchanged neighbor would add no correctness.
+            // Only supported Spring Bean source changes can alter this property;
+            // avoid materializing every persisted Class row for unrelated language
+            // updates. Check deleted paths too so removing/renaming a Java shadowing
+            // declaration still refreshes unchanged Spring candidates.
+            const beanSourceChanged = hashDiff.toWrite.some(isSpringBeanCandidateSourceFile) ||
+                hashDiff.deleted.some(isSpringBeanCandidateSourceFile);
+            if (beanSourceChanged) {
+                const persistedFrameworkAnnotations = (await executeQuery('MATCH (c:Class) ' + 'RETURN c.id AS id, c.frameworkAnnotations AS frameworkAnnotations'));
+                const frameworkAnnotationDriftFiles = collectFrameworkAnnotationDriftFiles(pipelineResult.graph, persistedFrameworkAnnotations);
+                for (const filePath of frameworkAnnotationDriftFiles)
+                    effectiveWriteSet.add(filePath);
+                if (frameworkAnnotationDriftFiles.size > 0) {
+                    log(`Incremental: +${frameworkAnnotationDriftFiles.size} file(s) added for ` +
+                        'framework annotation property drift');
+                }
+            }
             // Deduped: deleted entries may already appear via importer-BFS
-            // expansion (queryImporters can return a now-deleted path), which
-            // would otherwise call deleteNodesForFile twice for the same file
-            // (Bugbot LOW finding on PR #1479).
+            // expansion (the importer BFS can return a now-deleted path), which
+            // would otherwise hand deleteNodesForFiles the same path twice in one
+            // batch (Bugbot LOW finding on PR #1479).
             const filesToDelete = [...new Set([...effectiveWriteSet, ...hashDiff.deleted])];
-            for (let i = 0; i < filesToDelete.length; i++) {
-                const f = filesToDelete[i];
-                try {
-                    await deleteNodesForFile(f);
-                }
-                catch {
-                    /* file may not have rows (e.g. an unparseable file) — fine */
-                }
-                if (i % 20 === 0) {
-                    progress('lbug', 62, `Removing rows for changed files (${i}/${filesToDelete.length})...`);
+            await saveIncrementalDirtyState('effective-write-set', {
+                importerExpansion,
+                shadowSeedCount: shadowSeed.length,
+                effectiveWriteCount: effectiveWriteSet.size,
+                deleteCount: filesToDelete.length,
+            });
+            // Escalation valve (#2409): when the effective write set covers most of
+            // the repo, per-file surgery is strictly worse than the proven
+            // wipe-and-bulk-COPY plan — the same data volume lands either way, but
+            // the surgical plan pays per-table deletes plus COPY-into-non-empty
+            // tables, and at this size it measured SLOWER than a full DB load. The
+            // pipeline already produced the FULL graph (it always does), so only the
+            // DB write plan changes here; fileHashes/meta bookkeeping is identical.
+            // Thresholds + the AND-gate live in incremental/escalation-gate.ts.
+            const writeFraction = effectiveWriteSet.size / Math.max(1, allFilePaths.length);
+            // VECTOR gate (#2623) — load the extension BEFORE a single embedding row
+            // is touched. `deleteNodesForFiles` below opens with the CodeEmbedding
+            // join-delete, and LadybugDB refuses all DML on a table carrying its HNSW
+            // index unless VECTOR is loaded on this connection; nothing else on this
+            // path loads it until Phase 4, so every incremental run over a DB that
+            // already built `code_embedding_idx` died here. Same seam the FTS drop
+            // occupies at the head of this branch (#2589): index lifecycle first,
+            // then rows. UNCONDITIONAL — not gated on `shouldGenerateEmbeddings` —
+            // because a DB carrying the index from an earlier `--embeddings` run hits
+            // the identical wall on a plain incremental run.
+            //
+            // When VECTOR genuinely cannot load, the table is immutable (the index
+            // cannot be dropped without the extension either), so surgery is
+            // impossible: fall through to the escalation valve's wipe-and-COPY plan,
+            // which rebuilds the DB files outright and needs no embedding-row DML.
+            const embeddingRowDmlSafe = await ensureEmbeddingRowDmlSafe();
+            if (!embeddingRowDmlSafe && cachedEmbeddings.length === 0) {
+                // The escalation below WIPES the DB files, and Phase 3.5 restores
+                // embedding rows from `cachedEmbeddings` — which is only populated when
+                // `deriveEmbeddingMode` saw `meta.stats.embeddings > 0`. A DB whose meta
+                // under-reports its embeddings (meta restored from an older run, or a
+                // count that never got stamped) would therefore have every vector
+                // silently destroyed by a rebuild it did not ask for. Read them now,
+                // while the DB is still intact — a plain MATCH, which needs no VECTOR
+                // extension. Rows whose owning node is gone are dropped by Phase 3.5's
+                // live-graph filter, exactly as on any other wiped path.
+                const rescued = await loadCachedEmbeddings();
+                if (rescued.embeddings.length > 0) {
+                    cachedEmbeddings = rescued.embeddings;
+                    cachedEmbeddingNodeIds = rescued.embeddingNodeIds;
+                    log(`Preserving ${rescued.embeddings.length} embedding row(s) across the forced rebuild ` +
+                        `(the index metadata did not account for them).`);
                 }
             }
-            // 2. Drop graph-wide nodes (Community, Process). They'll be re-inserted
-            //    from the fresh pipeline output below. Required for the
-            //    "Leiden runs on the FULL graph" correctness invariant.
-            await deleteAllCommunitiesAndProcesses();
-            // 2a. Drop INJECTS edges (DI collection injection, #2200) — their
-            //     validity is a whole-program property (a third-file change to the
-            //     interface or an implementer 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). UNCONDITIONAL, next to the
-            //     Communities delete — NOT inside the `options.pdg` block below: the
-            //     di phase runs on every persisting analyze (same !skipGraphPhases
-            //     regime as communities/processes) while the graph-wide re-include
-            //     is unconditional, so a pdg-gated delete would append without
-            //     deleting on every non-pdg incremental run (N runs = N copies of
-            //     every INJECTS row; CodeRelation has no PK and no read-side dedup).
-            await deleteAllInjects();
-            // 2b. Drop interprocedural TAINT_PATH edges (#2084 M4 U6) when pdg is on
-            //     — their validity is a whole-program property (an A→C flow can be
-            //     invalidated by a change to an intermediate function on a third
-            //     file), so endpoint-writability extraction can't refresh them.
-            //     extractChangedSubgraph re-includes all of them from the fresh
-            //     graph (isGraphWideRelType), mirroring Community/Process.
-            if (options.pdg === true) {
-                await deleteAllInterprocTaintPaths();
-                // 2c. Drop CALL_SUMMARY edges (PDG FU-C) on an incremental `--pdg`
-                //     writeback. They are re-included from the FULL fresh graph
-                //     (isGraphWideRelType) and the callSummaries phase recomputes every
-                //     summary each run, so delete-all-then-rebuild keeps an unchanged
-                //     function's summary from being lost — same contract as TAINT_PATH.
-                await deleteAllCallSummaries();
+            if (!embeddingRowDmlSafe ||
+                shouldEscalateIncrementalWrite(filesToDelete.length, effectiveWriteSet.size, allFilePaths.length)) {
+                escalatedFullWrite = true;
+                log(!embeddingRowDmlSafe
+                    ? `Incremental: the ${EMBEDDING_TABLE_NAME} vector index exists but the VECTOR ` +
+                        `extension could not be loaded, so embedding rows cannot be rewritten in place — ` +
+                        `switching to a full DB write (wipe + bulk COPY) for this run. Semantic search ` +
+                        `falls back to exact scan until VECTOR is available; run \`gitnexus doctor\` for ` +
+                        `live extension status, or set GITNEXUS_LBUG_EXTENSION_INSTALL=auto to allow one ` +
+                        `bounded install attempt.`
+                    : `Incremental: effective write set covers ${effectiveWriteSet.size}/${allFilePaths.length} ` +
+                        // Display clamp only (predicate unchanged): BFS-found deleted
+                        // importers can push the numerator past the CURRENT file list, so
+                        // the raw fraction can exceed 1 — see the population-mismatch note
+                        // on shouldEscalateIncrementalWrite (tri-review 4669518496).
+                        `files (${Math.min(100, Math.round(writeFraction * 100))}%) — switching to a full DB write ` +
+                        `(wipe + bulk COPY) for this run; file-level incremental bookkeeping is unaffected.`);
+                // toWriteCount: 0 is the established full-path dirty-flag sentinel;
+                // the real counters ride along for crash diagnostics.
+                await saveIncrementalDirtyState('escalated-full-write', {
+                    toWriteCount: 0,
+                    importerExpansion,
+                    shadowSeedCount: shadowSeed.length,
+                    effectiveWriteCount: effectiveWriteSet.size,
+                    deleteCount: filesToDelete.length,
+                });
+                // Strategy switch: stop the checkpoint driver around the close so its
+                // in-flight CHECKPOINT can't race the reopen, drop the DB files
+                // (sidecars included), and bulk-load the full graph into a fresh DB —
+                // byte-for-byte the full-rebuild write plan. The wipe is the shared
+                // ENOENT-verified helper (#2409 + tri-review 4669518496 P2-4): a
+                // surviving family member throws a typed LbugWipeError here instead
+                // of letting the reopen below resurrect the rows this run just chose
+                // to replace wholesale.
+                await walCheckpointDriver.stop();
+                await closeLbug();
+                await wipeLbugDbFiles(buildPath);
+                await initLbug(buildPath);
+                walCheckpointDriver = startWalCheckpointDriver();
+                await loadGraphToLbug(pipelineResult.graph, pipelineResult.repoPath, storagePath, (msg) => {
+                    lbugMsgCount++;
+                    const pct = Math.min(84, 65 + Math.round((lbugMsgCount / (lbugMsgCount + 10)) * 19));
+                    progress('lbug', pct, msg);
+                });
             }
-            // 3. Extract the changed subgraph from the FULL ctx.graph and write
-            //    only that. Unchanged-file rows in the DB stay untouched. Pass
-            //    the SAME effectiveWriteSet so the subgraph and the deletes
-            //    cover identical files (asymmetry would silently corrupt).
-            const subgraph = extractChangedSubgraph(pipelineResult.graph, effectiveWriteSet);
-            await loadGraphToLbug(subgraph, pipelineResult.repoPath, storagePath, (msg) => {
-                lbugMsgCount++;
-                const pct = Math.min(84, 65 + Math.round((lbugMsgCount / (lbugMsgCount + 10)) * 19));
-                progress('lbug', pct, msg);
-            });
+            else {
+                // 1a. Drop every FTS index before touching a single row (#2589).
+                //     `deleteNodesForFiles` below DETACH DELETEs rows out of tables
+                //     that otherwise still carry the FTS index built at the end of
+                //     the PREVIOUS analyze run — Phase 3 doesn't drop+rebuild it
+                //     until well after this delete completes. LadybugDB's FTS
+                //     extension is not proven to survive DML against an indexed
+                //     table (its own docs never demonstrate it), and that ordering
+                //     is exactly what produced "FTS index 'file_fts' is
+                //     inconsistent: term is missing during delete". Dropping first
+                //     removes the hazard outright; Phase 3's createSearchFTSIndexes
+                //     rebuilds every index from the final row set regardless, so
+                //     this is a no-op on its own drop step there.
+                await dropSearchFTSIndexes();
+                // 1b. Remove the write set's existing rows — batched (#2409): one
+                //     DETACH DELETE per table per 200-file chunk. The former per-file
+                //     loop issued a count + delete per table per FILE — ~13k
+                //     single-row write transactions on a ~700-file write set — which
+                //     made this phase slower than a full rebuild and is the WAL-append
+                //     storm behind the native mid-writeback deaths in #2409. Errors
+                //     are NOT swallowed anymore: a zero-match file is a no-op by
+                //     construction, so anything thrown is a real engine failure that
+                //     must surface instead of silently skipping (that silent skip was
+                //     how #2409 hid its root cause).
+                progress('lbug', 62, `Removing rows for changed files (0/${filesToDelete.length})...`);
+                await deleteNodesForFiles(filesToDelete, {
+                    onChunk: (done, total) => progress('lbug', 62, `Removing rows for changed files (${done}/${total})...`),
+                });
+                // Surgical path: Phase 3.5 restores exactly these files' embedding
+                // rows (FIX 3). Sound because deleteNodesForFiles propagates errors
+                // — reaching this line means every listed file's rows are gone
+                // deterministically — and this process holds the exclusive DB lock,
+                // so no concurrent writer can disturb the derivation.
+                deletedFilePathsForRestore = new Set(filesToDelete);
+                // 2. Drop graph-wide nodes (Community, Process). They'll be re-inserted
+                //    from the fresh pipeline output below. Required for the
+                //    "Leiden runs on the FULL graph" correctness invariant.
+                await deleteAllCommunitiesAndProcesses();
+                // 2a. Drop INJECTS edges (DI collection injection, #2200) — their
+                //     validity is a whole-program property (a third-file change to the
+                //     interface or an implementer 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). UNCONDITIONAL, next to the
+                //     Communities delete — NOT inside the `options.pdg` block below: the
+                //     di phase runs on every persisting analyze (same !skipGraphPhases
+                //     regime as communities/processes) while the graph-wide re-include
+                //     is unconditional, so a pdg-gated delete would append without
+                //     deleting on every non-pdg incremental run (N runs = N copies of
+                //     every INJECTS row; CodeRelation has no PK and no read-side dedup).
+                await deleteAllInjects();
+                // 2b. Drop interprocedural TAINT_PATH edges (#2084 M4 U6) when pdg is on
+                //     — their validity is a whole-program property (an A→C flow can be
+                //     invalidated by a change to an intermediate function on a third
+                //     file), so endpoint-writability extraction can't refresh them.
+                //     extractChangedSubgraph re-includes all of them from the fresh
+                //     graph (isGraphWideRelType), mirroring Community/Process.
+                if (options.pdg === true) {
+                    await deleteAllInterprocTaintPaths();
+                    // 2c. Drop CALL_SUMMARY edges (PDG FU-C) on an incremental `--pdg`
+                    //     writeback. They are re-included from the FULL fresh graph
+                    //     (isGraphWideRelType) and the callSummaries phase recomputes every
+                    //     summary each run, so delete-all-then-rebuild keeps an unchanged
+                    //     function's summary from being lost — same contract as TAINT_PATH.
+                    await deleteAllCallSummaries();
+                }
+                // 3. Extract the changed subgraph from the FULL ctx.graph and write
+                //    only that. Unchanged-file rows in the DB stay untouched. Pass
+                //    the SAME effectiveWriteSet so the subgraph and the deletes
+                //    cover identical files (asymmetry would silently corrupt).
+                const subgraph = extractChangedSubgraph(pipelineResult.graph, effectiveWriteSet);
+                await saveIncrementalDirtyState('load-graph', {
+                    importerExpansion,
+                    shadowSeedCount: shadowSeed.length,
+                    effectiveWriteCount: effectiveWriteSet.size,
+                    deleteCount: filesToDelete.length,
+                });
+                await loadGraphToLbug(subgraph, pipelineResult.repoPath, storagePath, (msg) => {
+                    lbugMsgCount++;
+                    const pct = Math.min(84, 65 + Math.round((lbugMsgCount / (lbugMsgCount + 10)) * 19));
+                    progress('lbug', pct, msg);
+                });
+            }
+            // Boundary drain (#2409): checkpoint at the end of the incremental
+            // writeback so the WAL it accumulated never lingers into the FTS and
+            // embedding phases — a later crash leaves only post-checkpoint WAL for
+            // the next open to replay. Near-instant when the periodic driver has
+            // kept up; rides the driver's bounded retry via runCheckpointWithRetry.
+            await checkpointOnce();
         }
         else {
             // ── Full rebuild ───────────────────────────────────────────────
@@ -939,8 +1482,17 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
         const ftsAvailable = await loadFTSExtension(undefined, {
             policy: resolveAnalyzeInstallPolicy(),
         });
+        // Tracks whether search indexes actually ended up usable this run — starts
+        // as ftsAvailable (extension loaded) but flips to false below when the
+        // build/verify step itself fails, so capabilities.fts.status / ftsSkipped
+        // stay honest even though that failure no longer aborts the whole analyze.
+        let ftsReady = ftsAvailable;
         if (ftsAvailable) {
-            await createSearchFTSIndexes({
+            // Degrade rather than throw: createSearchFTSIndexes re-tokenizes every
+            // stored row on every run, so a native tokenizer error on a single
+            // pre-existing row (#2544/#2546) must not discard this run's otherwise-
+            // successful graph/embeddings work — only keyword search degrades.
+            const ftsResult = await buildSearchIndexesOrDegrade(executeQuery, {
                 onIndexStart: options.verbose
                     ? (table, indexName) => log(`FTS: creating ${table}.${indexName}`)
                     : undefined,
@@ -948,31 +1500,61 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
                     ? (table, indexName) => log(`FTS: ready ${table}.${indexName}`)
                     : undefined,
             });
-            const missingIndexNames = await verifySearchFTSIndexes(executeQuery);
-            if (missingIndexNames.length > 0) {
-                throw new Error(`FTS verification failed - missing indexes after analyze: ${missingIndexNames.join(', ')}. ` +
-                    'Check FTS extension availability, then retry `gitnexus analyze --force` for a full rebuild.');
+            if (ftsResult.ok) {
+                progress('fts', 90, 'Search indexes ready');
+            }
+            else {
+                ftsReady = false;
+                log(`FTS index build failed (${ftsResult.error}) — keyword search degraded this run. ` +
+                    'Graph and embeddings analysis completed successfully. Run `gitnexus analyze --repair-fts` to retry.');
+                progress('fts', 90, 'Search indexes skipped (build failed)');
             }
-            progress('fts', 90, 'Search indexes ready');
         }
         else {
-            log(FTS_UNAVAILABLE_MESSAGE);
+            // For a missing runtime dependency (#2374) the file is present, so the
+            // generic "install it with network access" tail in FTS_UNAVAILABLE_MESSAGE
+            // contradicts the remedy's own "reinstalling will NOT help" (#2383 F2). Lead
+            // with the class-neutral sentence and append only the classified remedy.
+            const ftsReason = getExtensionCapabilities().find((c) => c.name === 'fts')?.reason;
+            const { kind, remedy } = diagnoseExtensionLoad(ftsReason);
+            log(kind === 'missing_dependency'
+                ? `${FTS_UNAVAILABLE_LEAD} ${remedy}`
+                : FTS_UNAVAILABLE_MESSAGE);
             progress('fts', 90, 'Search indexes skipped (FTS unavailable)');
         }
         // ── Phase 3.5: Re-insert cached embeddings ────────────────────────
         // Runs on BOTH the full-rebuild path and the incremental path:
-        //   - Full rebuild: DB was wiped, every cached row needs to come back.
-        //   - Incremental:  changed-file rows were just deleted by
-        //                   deleteNodesForFile (which cascades to their
-        //                   embedding rows) — so their cached vectors need
-        //                   to come back too. Unchanged-file rows still
-        //                   exist; re-inserting their cached vectors would
-        //                   PK-conflict, but the per-batch try/catch below
-        //                   silently ignores those (matches the existing
-        //                   "some may fail if node was removed, that's
-        //                   fine" semantics). Bugbot review on PR #1479
-        //                   flagged that gating this on `!isIncremental`
-        //                   silently lost changed-file embeddings.
+        //   - Full rebuild / escalated write: DB was wiped, every cached row
+        //     needs to come back.
+        //   - Incremental (surgical): changed/deleted files' rows were just
+        //     deleted by deleteNodesForFiles (a REAL delete since tri-review
+        //     4669518496 P2-1 — it joins embedding rows through their owning
+        //     nodes), so changed-file vectors need to come back; unchanged-file
+        //     rows still exist. Bugbot review on PR #1479 flagged that gating
+        //     this on `!isIncremental` silently lost changed-file embeddings.
+        //
+        // Restore discipline (tri-review 4669518496 / KTD10, restore scope
+        // derived in memory since FIX 3 of this shipping review) — filtered and
+        // conflict-free, replacing the old insert-everything-and-swallow shape:
+        //   1. Live-graph filter: rows whose nodeId no longer exists in the
+        //      freshly-built FULL graph are dropped. The cache was read BEFORE
+        //      the pipeline ran, so it still carries deleted files' rows —
+        //      re-inserting them resurrected orphans (wholesale onto the wiped
+        //      paths' empty table) now that the delete above is real.
+        //   2. Restore-scope filter, derived WITHOUT touching the DB (the old
+        //      shape pre-read every surviving embedding id back out of the
+        //      table it had just written): on a wiped path
+        //      (`deletedFilePathsForRestore === null`) the table is fresh, so
+        //      every live row comes back; on the surgical path only rows whose
+        //      owning node's filePath is in the just-join-deleted set are
+        //      inserted — everything else still sits in the DB and would
+        //      PK-conflict. The derivation is sound because deleteNodesForFiles
+        //      propagates errors (a completed writeback means a deterministic
+        //      delete outcome) and this process holds the exclusive DB lock (no
+        //      concurrent writer).
+        // The per-batch try/catch stays as a last-resort guard only — it no
+        // longer fires on the happy path.
+        let restoredEmbeddingCount = 0;
         if (cachedEmbeddings.length > 0) {
             const cachedDims = cachedEmbeddings[0].embedding.length;
             const { EMBEDDING_DIMS } = await import('./lbug/schema.js');
@@ -983,16 +1565,65 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
                 cachedEmbeddingNodeIds = new Set();
             }
             else {
-                progress('embeddings', 88, `Restoring ${cachedEmbeddings.length} cached embeddings...`);
                 const { batchInsertEmbeddings: batchInsert } = await import('./embeddings/embedding-pipeline.js');
+                // (1) Live-graph filter — the FULL pipeline graph (always produced),
+                // NOT the incremental subgraph, or unchanged files' rows would be
+                // dropped from the restore set.
+                const liveEmbeddings = cachedEmbeddings.filter((e) => pipelineResult.graph.getNode(e.nodeId) !== undefined);
+                // (2) Restore-scope filter (see the discipline note above).
+                const rowsToRestore = deletedFilePathsForRestore === null
+                    ? liveEmbeddings
+                    : liveEmbeddings.filter((e) => {
+                        const filePath = pipelineResult.graph.getNode(e.nodeId)?.properties?.filePath;
+                        return typeof filePath === 'string' && deletedFilePathsForRestore.has(filePath);
+                    });
+                progress('embeddings', 88, `Restoring ${rowsToRestore.length} cached embeddings...`);
                 const EMBED_BATCH = 200;
-                for (let i = 0; i < cachedEmbeddings.length; i += EMBED_BATCH) {
-                    const batch = cachedEmbeddings.slice(i, i + EMBED_BATCH);
+                for (let i = 0; i < rowsToRestore.length; i += EMBED_BATCH) {
+                    const batch = rowsToRestore.slice(i, i + EMBED_BATCH);
                     try {
                         await batchInsert(executeWithReusedStatement, batch);
+                        restoredEmbeddingCount += batch.length;
                     }
                     catch {
-                        /* some may fail if node was removed, that's fine */
+                        /* last-resort guard — conflict-free by construction above */
+                    }
+                }
+                // Legacy-orphan sweep (FIX 3, finder B): the live-graph filter's
+                // REJECTS — cached rows whose owning node no longer exists — are the
+                // rows stranded by the era when the embedding delete was a no-op
+                // (tri-review 4669518496 P2-1; schema version stays 6), plus this
+                // run's just-deleted files' rows (already join-deleted above — the
+                // exact-id DELETE matches nothing for those, so including them is a
+                // harmless no-op rather than worth a fragile nodeId parse to
+                // exclude). On the SURGICAL path the true legacy orphans still sit
+                // in the DB and the node join can never reach them again (no owning
+                // node), so delete them by exact row id. On wiped paths the rejects
+                // were simply not restored — nothing to sweep. Legacy-tolerant: a
+                // sweep failure must never fail a completed writeback, so the whole
+                // sweep warns-and-continues.
+                if (deletedFilePathsForRestore !== null) {
+                    const orphanRowIds = cachedEmbeddings
+                        .filter((e) => pipelineResult.graph.getNode(e.nodeId) === undefined)
+                        .map((e) => `${e.nodeId}:${e.chunkIndex}`);
+                    if (orphanRowIds.length > 0) {
+                        try {
+                            for (let i = 0; i < orphanRowIds.length; i += DELETE_FILES_CHUNK_SIZE) {
+                                const chunk = orphanRowIds.slice(i, i + DELETE_FILES_CHUNK_SIZE);
+                                const listLiteral = `[${chunk
+                                    .map((id) => `'${escapeCypherString(id)}'`)
+                                    .join(', ')}]`;
+                                await executeQuery(`MATCH (e:${EMBEDDING_TABLE_NAME}) WHERE e.id IN ${listLiteral} DELETE e`);
+                            }
+                            log(`Swept ${orphanRowIds.length} cached embedding row(s) with no live owning ` +
+                                'node — legacy orphans stranded while the embedding delete was a no-op; ' +
+                                'ids already removed with their files match nothing.');
+                        }
+                        catch (err) {
+                            log(`Warning: could not sweep ${orphanRowIds.length} orphaned embedding ` +
+                                `row(s) (${err.message}); they are unreachable by search ` +
+                                'joins and will be retried next run.');
+                        }
                     }
                 }
             }
@@ -1002,7 +1633,7 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
         let embeddingSkipped = true;
         let semanticMode;
         if (shouldGenerateEmbeddings) {
-            const { skipForCap, capDisabled, nodeLimit } = deriveEmbeddingCap(stats.nodes, options.embeddingsNodeLimit);
+            const { skipForCap, capDisabled, nodeLimit } = deriveEmbeddingCap(stats.nodes, resumeEmbeddingCheckpoint ? 0 : options.embeddingsNodeLimit);
             if (!skipForCap) {
                 embeddingSkipped = false;
                 if (capDisabled && stats.nodes > DEFAULT_EMBEDDING_NODE_LIMIT) {
@@ -1019,11 +1650,50 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
                     `\`--embeddings <n>\` to set a custom cap.`);
             }
         }
+        // ── Vector-index recreation after a wipe-and-restore (tri-review
+        // 4669518496 P1 / KTD1) ────────────────────────────────────────────
+        // The full-rebuild and escalated-incremental write plans wipe the DB
+        // files — the HNSW index with them. Phase 3.5 brought the embedding ROWS
+        // back, but on a preserve-only run nothing recreates the index: semantic
+        // search silently loses its vector lane (>10k-embedding repos return
+        // empty under the exact-scan cap) while meta certified 'vector-index'.
+        // Recreate it here, where every gate input is settled:
+        //   - restoredEmbeddingCount > 0 — rows actually came back;
+        //   - dbWasWiped — surgical incremental runs keep their index (HNSW
+        //     self-maintains on insert/delete); only wiped DBs lost it;
+        //   - embeddingSkipped — evaluated AFTER the deriveEmbeddingCap decision
+        //     above, NOT `!shouldGenerateEmbeddings`: when Phase 4 really runs,
+        //     the pipeline builds the index itself after all inserts (firing this
+        //     seam first would swap its bulk build for per-row live HNSW
+        //     maintenance on the hottest flow), while a capped >50k-node repo has
+        //     shouldGenerateEmbeddings=true yet never runs the pipeline — exactly
+        //     the case a naive gate would leave index-less again.
+        // buildVectorIndex carries its own extension-policy gate and
+        // warn-on-failure; the boolean feeds semanticMode so the finalize stamp
+        // reflects the DB's ACTUAL state even when recreation fails (extension
+        // unavailable → 'exact-scan').
+        const dbWasWiped = !isIncremental || escalatedFullWrite;
+        if (restoredEmbeddingCount > 0 && dbWasWiped && embeddingSkipped) {
+            // Re-import at the seam rather than thread a mutable capture from
+            // Phase 3.5 (FIX 3 of this shipping review — the captured function was
+            // a fragile moving part): dynamic imports are memoized, and
+            // `restoredEmbeddingCount > 0` proves Phase 3.5 already loaded the
+            // module, so the lazy-embeddings convention (#2370) holds — no
+            // embeddings module loads unless a restore actually happened.
+            const { buildVectorIndex } = await import('./embeddings/embedding-pipeline.js');
+            const vectorIndexReady = await buildVectorIndex();
+            semanticMode = vectorIndexReady ? 'vector-index' : 'exact-scan';
+        }
         if (!embeddingSkipped) {
             const { isHttpMode } = await import('./embeddings/http-client.js');
             const httpMode = isHttpMode();
             progress('embeddings', 90, httpMode ? 'Connecting to embedding endpoint...' : 'Loading embedding model...');
             const { runEmbeddingPipeline } = await import('./embeddings/embedding-pipeline.js');
+            if (!embeddingIdentityForRun) {
+                const { resolveEmbeddingIdentity } = await import('./embeddings/embedding-identity.js');
+                embeddingIdentityForRun = resolveEmbeddingIdentity();
+            }
+            const embeddingIdentity = embeddingIdentityForRun;
             // Build a Map<nodeId, contentHash> from cached embeddings for incremental mode
             let existingEmbeddings;
             if (cachedEmbeddingNodeIds.size > 0) {
@@ -1032,6 +1702,43 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
                     existingEmbeddings.set(e.nodeId, e.contentHash ?? STALE_HASH_SENTINEL);
                 }
             }
+            const saveEmbeddingCheckpoint = async (checkpoint, pendingNodeIds, embeddings) => {
+                const fileHashes = {};
+                for (const [key, value] of newFileHashes)
+                    fileHashes[key] = value;
+                await saveMeta(metaDir, {
+                    ...(existingMeta ?? {}),
+                    repoPath,
+                    lastCommit: currentCommit,
+                    indexedAt: new Date().toISOString(),
+                    runnerIdentity,
+                    branch: branchLabel ?? existingMeta?.branch,
+                    remoteUrl: hasGitDir(repoPath) ? getRemoteUrl(repoPath) : undefined,
+                    stats: {
+                        files: pipelineResult.totalFileCount,
+                        nodes: stats.nodes,
+                        edges: stats.edges,
+                        communities: pipelineResult.communityResult?.stats.totalCommunities,
+                        processes: pipelineResult.processResult?.stats.totalProcesses,
+                        embeddings,
+                    },
+                    schemaVersion: hasGitDir(repoPath) ? INCREMENTAL_SCHEMA_VERSION : undefined,
+                    analysisFeatures: currentAnalysisFeatures,
+                    cjkSegmentation: getSearchFTSCjkSegmentation(),
+                    fileHashes: hasGitDir(repoPath) ? fileHashes : undefined,
+                    cacheKeys: [...parseCache.usedKeys],
+                    incrementalInProgress: undefined,
+                    embeddingCheckpoint: {
+                        at: new Date().toISOString(),
+                        ...checkpoint,
+                        model: embeddingIdentity.model,
+                        dimensions: embeddingIdentity.dimensions,
+                        provider: embeddingIdentity.provider,
+                        pendingNodeIds,
+                    },
+                    pdg: resolvePdgConfig(options),
+                });
+            };
             const embeddingResult = await runEmbeddingPipeline(executeQuery, executeWithReusedStatement, (p) => {
                 const scaled = 90 + Math.round((p.percent / 100) * 8);
                 const label = p.phase === 'loading-model'
@@ -1040,7 +1747,19 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
                         : 'Loading embedding model...'
                     : `Embedding ${p.nodesProcessed || 0}/${p.totalNodes || '?'}`;
                 progress('embeddings', scaled, label);
-            }, {}, cachedEmbeddingNodeIds.size > 0 ? cachedEmbeddingNodeIds : undefined, existingEmbeddings);
+            }, {}, cachedEmbeddingNodeIds.size > 0 ? cachedEmbeddingNodeIds : undefined, existingEmbeddings, {
+                forceReembedNodeIds: pendingEmbeddingNodeIds,
+                onCheckpointWindowStart: async ({ nodeIds, ...checkpoint }) => {
+                    await saveEmbeddingCheckpoint(checkpoint, nodeIds, existingMeta?.stats?.embeddings);
+                },
+                onCheckpoint: async (checkpoint) => {
+                    await checkpointOnce();
+                    const countResult = await executeQuery(`MATCH (e:${EMBEDDING_TABLE_NAME}) RETURN count(e) AS cnt`);
+                    const countRow = countResult?.[0];
+                    const embeddings = Number(countRow?.cnt ?? countRow?.[0] ?? 0);
+                    await saveEmbeddingCheckpoint(checkpoint, [], embeddings);
+                },
+            });
             if (embeddingResult.semanticMode === 'exact-scan') {
                 semanticMode = 'exact-scan';
                 log('Semantic embeddings were generated without a VECTOR index; ' +
@@ -1068,17 +1787,44 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
         }
         const { getRuntimeCapabilities } = await import('./platform/capabilities.js');
         const runtimeCapabilities = getRuntimeCapabilities();
+        // `semanticMode` is authoritative when set (Phase 4 reported what it
+        // built, or the wipe-and-restore seam above verified/recreated the index
+        // — tri-review 4669518496 P1). When unset, prefer the PREVIOUS run's
+        // persisted stamp over the platform capability (FIX 3, finder A): the
+        // unset case is exactly a run that neither wiped nor generated — e.g. a
+        // surgical incremental whose index survived in place — and such a run
+        // cannot change whether the HNSW index exists, so carrying the persisted
+        // observation forward is strictly more truthful than re-deriving from
+        // what the platform COULD do. Only the two positive observations carry
+        // ('vector-index'/'exact-scan'); 'unavailable'/absent falls through to
+        // the platform default rather than pinning a stale negative.
+        const persistedStatus = existingMeta?.capabilities?.vectorSearch.status;
+        const persistedSemanticMode = persistedStatus === 'vector-index' || persistedStatus === 'exact-scan'
+            ? persistedStatus
+            : undefined;
         const effectiveSemanticMode = semanticMode ??
+            persistedSemanticMode ??
             (runtimeCapabilities.semanticMode === 'vector-index' ? 'vector-index' : 'exact-scan');
         // Convert the post-run file-hash map to the on-disk Record<string,string>
         // shape consumed by RepoMeta.fileHashes.
         const newFileHashesRecord = {};
         for (const [k, v] of newFileHashes)
             newFileHashesRecord[k] = v;
+        // Incremental runs never rewrite Move facts (changed Move compiler inputs
+        // force a full rebuild), so when the compiler is transiently unavailable
+        // the previous record still describes the persisted facts. Stamping
+        // false/undefined here would force a needless full rebuild the moment the
+        // compiler returns.
+        const preserveMoveMeta = hasMovePackages && !moveFlow && isIncremental;
+        // Annotated so the capabilities stamp below is compile-checked against
+        // RepoMeta's status unions (tri-review 4669518496 P1/U3) — an unannotated
+        // literal widens the vectorSearch.status ternary to `string` and the
+        // honesty contract silently decays to "whatever interpolates".
         const meta = {
             repoPath,
             lastCommit: currentCommit,
             indexedAt: new Date().toISOString(),
+            runnerIdentity,
             // Branch identity this index represents (#2106). Recorded for the flat
             // slot too (so resolveBranchPlacement knows which branch owns it). When
             // the label is null (detached HEAD / non-git re-analyze) we PRESERVE an
@@ -1110,7 +1856,7 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
                 // meta.json / `gitnexus doctor` honest about degraded search.
                 fts: {
                     provider: 'ladybugdb-fts',
-                    status: ftsAvailable ? runtimeCapabilities.fts : 'unavailable',
+                    status: ftsReady ? runtimeCapabilities.fts : 'unavailable',
                 },
                 vectorSearch: {
                     provider: effectiveSemanticMode === 'vector-index' ? 'ladybugdb-vector' : 'exact-scan',
@@ -1124,17 +1870,30 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             // incrementalInProgress to undefined explicitly clears any prior
             // dirty flag (full and incremental success paths converge here).
             schemaVersion: hasGitDir(repoPath) ? INCREMENTAL_SCHEMA_VERSION : undefined,
+            analysisFeatures: currentAnalysisFeatures,
             // Always stamped with the live resolved mode (#2331/#2339) — unlike
             // `pdg` below, 'none' is a meaningful value to compare, not an
             // absence, so this is never conditionally omitted.
             cjkSegmentation: getSearchFTSCjkSegmentation(),
             fileHashes: hasGitDir(repoPath) ? newFileHashesRecord : undefined,
+            moveIngestAvailable: preserveMoveMeta
+                ? existingMeta?.moveIngestAvailable
+                : moveIngestAvailable,
+            moveCompilerIdentity: preserveMoveMeta
+                ? existingMeta?.moveCompilerIdentity
+                : moveFlow?.identity,
+            moveFlowReleaseSelection: preserveMoveMeta
+                ? existingMeta?.moveFlowReleaseSelection
+                : moveFlow?.identity.source === 'release'
+                    ? desiredMoveFlowRelease
+                    : undefined,
             // This branch's full live chunk-key set (#2106 R6). `usedKeys` is every
             // chunk hash touched in this scan — cache HITS included (see parse-impl
             // usedKeys.add) — so it's complete even on an incremental run. Persisted
             // so a sibling branch's prune can union it and not evict our shards.
             cacheKeys: [...parseCache.usedKeys],
             incrementalInProgress: undefined,
+            embeddingCheckpoint: undefined,
             // The effective pdg config this run's DB rows were built under
             // (#2099 F1). `undefined` on pdg-off runs — this meta is a fresh
             // literal (no spread of existingMeta), so omission is what CLEARS the
@@ -1142,7 +1901,18 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             // off==off and incremental eligibility is restored.
             pdg: resolvePdgConfig(options),
         };
-        await saveMeta(metaDir, meta);
+        // Re-resolve at the commit boundary. Long analyses can overlap an npm
+        // upgrade, rebuilt dist tree, or native dependency replacement; stamping
+        // the start-of-run receipt after such a mutation would falsely certify a
+        // graph produced by two analyzer identities. Stable-read validation lives
+        // inside the resolver, and a mismatch leaves the dirty flag intact so the
+        // next run takes the established full-recovery path.
+        meta.runnerIdentity = finalizeAnalyzerRunnerIdentity(import.meta.url, runnerIdentity);
+        // #2614 F1: the freshness stamp (saveMeta) is written AFTER the atomic swap
+        // below — never here — so a concurrent MCP reader can't observe
+        // meta.indexedAt = T_new while lbugPath still resolves to the pre-swap
+        // inode (which latched the reader on the stale index permanently). The meta
+        // object is fully computed at this point; only its write is deferred.
         // Persist the incremental parse cache for the next run. Wraps in
         // try/catch so a cache-write failure never breaks an otherwise
         // successful indexing run. Prune stale chunk-hash entries first so
@@ -1266,14 +2036,61 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
         // LadybugDB destructor double-free after --pdg writes — closeLbugBeforeExit
         // CHECKPOINTs for durability then leaves the handles for process exit to
         // reclaim (#2264). Long-lived callers close for real.
-        await (options.skipNativeCloseOnExit ? closeLbugBeforeExit() : closeLbug());
+        //
+        // On Windows a swap must release the build handle before the rename (a
+        // same-process open file can't be renamed), so it forces a real close —
+        // safe because windowsSwapOk excludes --pdg (the #2264 case). POSIX renames
+        // an open file, so it keeps the skip-native-close there.
+        const forceRealCloseForSwap = useAtomicSwap && process.platform === 'win32';
+        await (options.skipNativeCloseOnExit && !forceRealCloseForSwap
+            ? closeLbugBeforeExit()
+            : closeLbug());
+        // #2 atomic publish: the fresh index was built at buildPath (a full rebuild,
+        // or an opt-in atomic incremental that copied the live index in first). Swap
+        // it over the live lbugPath in one rename so an MCP reader that opened
+        // mid-build only ever saw the previous complete index — never a wiped/
+        // half-built file. The close above checkpoint-consolidated buildPath to a
+        // single file (no .wal), so the rename publishes a complete index; a reader
+        // holding the old inode keeps a consistent stale snapshot until the pool
+        // re-opens onto the new one (the pool staleness invalidation). Runs only on
+        // success — a thrown error skips this, leaving the live index intact and the
+        // temp build to be cleared by the next run's wipe.
+        // Only publish if the build actually produced a DB at buildPath. A
+        // degenerate run (empty repo, or a mocked pipeline that never opened the
+        // store) leaves nothing to swap — skip rather than throw ENOENT.
+        const builtDbExists = useAtomicSwap
+            ? await fs.stat(buildPath).then(() => true, () => false)
+            : false;
+        if (useAtomicSwap && builtDbExists) {
+            await retryRename(buildPath, lbugPath);
+            // Clear any sidecars orphaned beside the replaced file. A cleanly-closed
+            // prior index has none; a crashed one could, and it would be replay
+            // poison next to the freshly published index. Best-effort.
+            for (const suffix of ['.wal', '.shadow', '.wal.checkpoint']) {
+                await fs.rm(`${lbugPath}${suffix}`, { force: true }).catch(() => { });
+            }
+            // #2614 F4: if the final checkpoint silently failed, the build may still
+            // carry a residual .wal/.shadow under the temp name. MOVE it beside the
+            // published index (not orphan/delete it) so the next open replays the
+            // delta, rather than leaving it under a name LadybugDB never reconciles.
+            for (const suffix of ['.wal', '.shadow']) {
+                await fs.rename(`${buildPath}${suffix}`, `${lbugPath}${suffix}`).catch(() => { });
+            }
+        }
+        // #2614 F1: stamp the freshness metadata now that the index is published.
+        // When meta.indexedAt becomes visible, lbugPath already resolves to the new
+        // inode, so a reader reiniting on the stamp opens the fresh graph rather
+        // than latching on the old one. Leaving the dirty flag set across the swap
+        // is a crash-safety improvement: a failed swap leaves the previous index
+        // live and the next run recovers via the full-rebuild path.
+        await saveMeta(metaDir, meta);
         progress('done', 100, 'Done');
         return {
             repoName: projectName,
             repoPath,
             stats: meta.stats,
             pipelineResult,
-            ftsSkipped: !ftsAvailable,
+            ftsSkipped: !ftsReady,
             isPrimaryBranch: !placement.branch,
         };
     }