gitnexus 1.6.11-rc.2 → 1.6.11-rc.21

package/dist/core/run-analyze.js

@@ -12,6 +12,7 @@ import { detectGraphWriteCollapse } from './index-freshness.js';
 import { PDG_EDGE_TYPES } from './lbug/pdg-emit-sink.js';
 import path from 'path';
 import fs from 'fs/promises';
+import { constants as fsConstants } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { retryRename } from '../storage/fs-atomic.js';
 import { acquireIndexLock } from '../storage/index-lock.js';
@@ -20,11 +21,11 @@ import { logUnresolvedReceiverFiles, summarizeUnresolvedReceivers, } from './ing
 import { summarizeUndecidedSatisfaction } from './ingestion/scope-resolution/undecided-satisfaction.js';
 import { summarizeScopeExtractionFailures } from './ingestion/scope-resolution/scope-extraction-failures.js';
 import { resetDegradedParseCounter } from './tree-sitter/safe-parse.js';
-import { initLbug, loadGraphToLbug, getLbugStats, executeQuery, executeWithReusedStatement, closeLbug, closeLbugBeforeExit, loadCachedEmbeddings, deleteNodesForFiles, ensureEmbeddingRowDmlSafe, ensureFtsRowDmlSafe, readIndexCatalogSnapshot, INDEX_CATALOG_UNREADABLE, deleteAllCommunitiesAndProcesses, deleteAllInterprocTaintPaths, deleteAllCallSummaries, deleteAllInjects, deleteAllAdvisedBy, deleteSpringAopEvidenceNodes, deleteSpringAutoConfigurationDeclarations, deleteSpringAutoConfigurationSyntheticClasses, queryImportersBatch, loadFTSExtension, wipeLbugDbFiles, LbugWipeError, DELETE_FILES_CHUNK_SIZE, } from './lbug/lbug-adapter.js';
+import { initLbug, loadGraphToLbug, getLbugStats, executeQuery, executeWithReusedStatement, closeLbug, closeLbugBeforeExit, loadCachedEmbeddings, deleteNodesForFiles, nodeTablesWithRowsForFiles, snapshotDerivedRelsForFiles, restoreDerivedRels, ensureEmbeddingRowDmlSafe, ensureFtsRowDmlSafe, readIndexCatalogSnapshot, INDEX_CATALOG_UNREADABLE, deleteAllCommunitiesAndProcesses, deleteAllInterprocTaintPaths, deleteAllCallSummaries, deleteAllInjects, deleteAllAdvisedBy, deleteSpringAopEvidenceNodes, deleteSpringAutoConfigurationDeclarations, deleteSpringAutoConfigurationSyntheticClasses, queryImportersBatch, loadFTSExtension, wipeLbugDbFiles, LbugWipeError, DELETE_FILES_CHUNK_SIZE, } from './lbug/lbug-adapter.js';
 import { estimateBufferPool, setBufferPoolSizeHint, resolveNativeSafeStorageDir, } from './lbug/lbug-config.js';
 import { escapeCypherString } from './lbug/cypher-escape.js';
 import { chunk } from '../lib/utils.js';
-import { buildSearchIndexesOrDegrade, ftsFailureIsFatal, createSearchFTSIndexes, summarizeFtsIndexBuildFailures, dropSearchFTSIndexes, initialiseSearchFTSStemmer, verifySearchFTSIndexes, } from './search/fts-indexes.js';
+import { buildSearchIndexesOrDegrade, ftsFailureIsFatal, createSearchFTSIndexes, summarizeFtsIndexBuildFailures, dropSearchFTSIndexes, missingSearchFTSIndexTables, initialiseSearchFTSStemmer, verifySearchFTSIndexes, } from './search/fts-indexes.js';
 import { cjkSegmentationModeMismatch, getSearchFTSCjkSegmentation, initialiseSearchFTSCjkSegmentation, } from './search/cjk-segmentation.js';
 import { getExtensionCapability, getExtensionCapabilities, getFtsCapability, resolveAnalyzeInstallPolicy, } from './lbug/extension-loader.js';
 import { diagnoseExtensionLoad } from './lbug/extension-load-error.js';
@@ -42,9 +43,13 @@ 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 { ftsTablesAmong, incrementalFtsTablesFromGraph, nodeTablesForIncrementalDelete, shouldPreservePersistedDerivedGraph, } from './incremental/derived-writeback.js';
+import { NODE_TABLES } from './lbug/schema.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, isWorkingTreeDirty, resolveRepoIdentityRoot, } from '../storage/git.js';
+import { getCurrentCommit, getCurrentBranch, getRemoteUrl, hasGitDir, getInferredRepoName, isWorkingTreeDirty, listWorkingTreeDirtyPaths, resolveRepoIdentityRoot, } from '../storage/git.js';
+import { isGitNexusManagedPath } from '../storage/gitnexus-managed-paths.js';
+import { getMaxFileSizeBytes } from './ingestion/utils/max-file-size.js';
 import { generateAIContextFiles } from '../cli/ai-context.js';
 import { sanitizeDetectedBranch } from '../cli/analyze-config.js';
 import { EMBEDDING_TABLE_NAME, EMBEDDING_DIMS, STALE_HASH_SENTINEL, SCHEMA_FINGERPRINT, schemaFingerprintMismatch, isSchemaFingerprintShaped, embeddingDimsMismatch, } from './lbug/schema.js';
@@ -149,6 +154,17 @@ function collectSpringBeanDeclarationDriftFiles(graph, persistedRows) {
     }
     return driftFiles;
 }
+const liveIndexMutationRisks = new WeakSet();
+function recordLiveIndexMutationRisk(error) {
+    if ((typeof error === 'object' && error !== null) || typeof error === 'function') {
+        liveIndexMutationRisks.add(error);
+    }
+}
+/** Whether a failed analyze may already have changed the live DB. */
+export function analyzeFailureMayHaveMutatedLiveIndex(error) {
+    return (((typeof error === 'object' && error !== null) || typeof error === 'function') &&
+        liveIndexMutationRisks.has(error));
+}
 /**
  * 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
@@ -784,6 +800,13 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
             }
             progress('fts', 90, 'Search indexes ready');
             progress('done', 100, 'Done');
+            if (options.registryName) {
+                await registerRepo(repoPath, existingMeta, {
+                    name: options.registryName,
+                    allowDuplicateName: options.allowDuplicateName,
+                    branch: placement.branch,
+                });
+            }
             return {
                 repoName: options.registryName ??
                     getInferredRepoName(repoPath) ??
@@ -1118,6 +1141,29 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
             // later read on a host where it loads — which is a legitimate, common
             // state, and the invariant `analyzer-identity-cli.test.ts` pins.
             if (!dirty && !healUnregistered) {
+                if (options.registryName) {
+                    await registerRepo(repoPath, existingMeta, {
+                        name: options.registryName,
+                        allowDuplicateName: options.allowDuplicateName,
+                        branch: placement.branch,
+                    });
+                    if (!placement.branch) {
+                        try {
+                            await generateAIContextFiles(repoPath, storagePath, options.registryName, existingMeta.stats ?? {}, undefined, {
+                                skipAgentsMd: options.skipAgentsMd,
+                                skipSkills: options.skipSkills,
+                                noStats: options.noStats,
+                                defaultBranch: options.defaultBranch,
+                                // Fast path does not re-run PDG. Using `options.pdg` would
+                                // strip PDG bullets from AGENTS.md on a rename-only analyze.
+                                hasPdg: existingMeta.pdg != null,
+                            });
+                        }
+                        catch {
+                            /* best-effort — never fail the fast path over a context refresh */
+                        }
+                    }
+                }
                 // ── #2354: restamp the workspace label on a same-commit branch flip ──
                 // The flat slot follows the checked-out working tree; a branch switch
                 // at the SAME commit with a clean tree changes nothing the pipeline
@@ -1262,6 +1308,23 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
     // pipeline has already run by then; that run emits non-streamed, precisely as
     // `resolveStreamPdgEmit` — read fresh at the same point — behaves.)
     const streamGraphEmitActive = resolveStreamGraphEmit(options);
+    // #3016: hold back Leiden and flow extraction when the persisted metadata
+    // says this run is a candidate for a surgical incremental write, whose
+    // derived layer is reused rather than recomputed. Deliberately the same
+    // conditions as the `isIncremental` decision below MINUS the two that only
+    // the pipeline can answer (the analysis-feature re-check and a non-empty
+    // file list), so this is a superset: every run that turns out incremental
+    // had the phases skipped, and the runs that do not are caught by
+    // `runDeferredDerivedPhases` once the write plan is known. Excluded on the
+    // streaming path because that is a full rebuild by construction, and the
+    // deferred phases must not write into a finalized emit sink.
+    const skipDerivedGraphPhases = !streamGraphEmitActive &&
+        !options.force &&
+        !!existingMeta &&
+        !!existingMeta.fileHashes &&
+        Object.keys(existingMeta.fileHashes).length > 0 &&
+        repoHasGit &&
+        !schemaFingerprintMismatch(existingMeta.schemaFingerprint);
     // ── Phase 1: Full Pipeline (0–60%) ────────────────────────────────
     const pipelineResult = await runPipelineFromRepo(repoPath, (p) => {
         const phaseLabel = PHASE_LABELS[p.phase] || p.phase;
@@ -1301,6 +1364,7 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
             ? resolveNativeSafeStorageDir(storagePath, 'graph-csv')
             : undefined,
         fetchWrappers: options.fetchWrappers,
+        skipDerivedGraphPhases,
     });
     // ── Phase 2: LadybugDB (60–85%) ──────────────────────────────────
     progress('lbug', 60, 'Loading into LadybugDB...');
@@ -1350,6 +1414,26 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
     const hashDiff = isIncremental
         ? diffFileHashes(newFileHashes, existingMeta.fileHashes)
         : undefined;
+    // #3016: `skipDerivedGraphPhases` was decided BEFORE the pipeline, from the
+    // persisted metadata alone, so it can only ever be a bet that this run stays
+    // surgical. Settle the bet here, where `isIncremental` and the deletion set
+    // are both known, and pay it off by running the held-back phases whenever the
+    // write plan needs a freshly derived layer:
+    //   - not incremental      → full rebuild writes the whole graph, and a graph
+    //                            with no Community/Process nodes would publish an
+    //                            index with no communities and no flows;
+    //   - added/changed/deleted files → the persisted derived layer can miss new
+    //                            symbols, keep stale memberships, or reference
+    //                            removed ids. Only an empty file-hash diff is a
+    //                            proof that Leiden/flows still match.
+    const preserveDerivedLayer = skipDerivedGraphPhases &&
+        isIncremental &&
+        !!hashDiff &&
+        shouldPreservePersistedDerivedGraph(hashDiff);
+    if (skipDerivedGraphPhases && !preserveDerivedLayer) {
+        progress('communities', 58, 'Detecting code communities and flows...');
+        await pipelineResult.runDeferredDerivedPhases?.();
+    }
     // #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
@@ -1378,11 +1462,14 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
     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';
+    // Incremental atomicity stages the whole index before mutation. It remains
+    // opt-in for ordinary analyze runs; watch mode requests it for failure
+    // preservation. The copy requests a filesystem clone and records its actual
+    // duration, while Node falls back to a normal copy where reflinks are absent.
+    const wantAtomicIncremental = isIncremental &&
+        !!hashDiff &&
+        process.platform !== 'win32' &&
+        (options.atomicIncremental === true || 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
@@ -1399,6 +1486,10 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
     // valve. Nothing between here and there reads either binding except
     // `initLbug(buildPath)`, which the upgrade re-runs against the staging path.
     let useAtomicSwap = (isFullRebuild || atomicIncremental) && (posixSwap || windowsSwapOk);
+    // Set only at the first operation that can mutate the live graph store.
+    // Pre-write failures (config, lock, parsing, metadata, importer expansion)
+    // remain retryable even when this platform cannot use an atomic swap.
+    let liveIndexMutationStarted = false;
     // #2658: a per-run staging name (was the fixed `lbug.new`). Even under the
     // single-writer lock, a unique name means a crashed run's half-built staging
     // file can never be mistaken for — or clobber — a live run's; the lock's
@@ -1426,10 +1517,13 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
         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.
+            // Clear any stale temp first (a crashed run), then clone/copy the
+            // consolidated single-file live index.
             await wipeLbugDbFiles(buildPath);
-            await fs.copyFile(lbugPath, buildPath);
+            const copyStartedAt = Date.now();
+            await fs.copyFile(lbugPath, buildPath, fsConstants.COPYFILE_FICLONE);
+            log(`atomic-incremental: staged ${lbugPath} in ${Date.now() - copyStartedAt}ms ` +
+                '(copy-on-write requested; filesystem fallback is allowed)');
         }
     }
     else {
@@ -1466,7 +1560,16 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
         // (`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);
+        if (buildPath === lbugPath)
+            liveIndexMutationStarted = true;
+        try {
+            await wipeLbugDbFiles(buildPath);
+        }
+        catch (error) {
+            if (liveIndexMutationStarted)
+                recordLiveIndexMutationRisk(error);
+            throw error;
+        }
     }
     // 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
@@ -1483,7 +1586,14 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
         (pipelineResult.graphEmitManifest?.totalRows ?? 0)));
     // Full rebuild (POSIX) builds into the temp `buildPath`; incremental and
     // Windows use `buildPath === lbugPath` in place.
-    await initLbug(buildPath);
+    try {
+        await initLbug(buildPath);
+    }
+    catch (error) {
+        if (liveIndexMutationStarted)
+            recordLiveIndexMutationRisk(error);
+        throw error;
+    }
     // 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
@@ -1506,6 +1616,7 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
         // "escalated full write" (DB wiped, index destroyed) — tri-review
         // 4669518496 P1.
         let escalatedFullWrite = false;
+        let incrementalStats;
         // 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
@@ -1521,6 +1632,7 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
         // collapse check compares the whole in-memory graph against the whole DB,
         // which is only a like-for-like comparison on a full rebuild.
         let wroteChangedSubgraphOnly = false;
+        let incrementalFtsRebuildTables;
         if (isIncremental && hashDiff) {
             // ── Incremental DB writeback ───────────────────────────────────
             // 0. Expand the writable set with transitive importers of
@@ -1624,6 +1736,13 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
                 }
             }
             const importerExpansion = writableFiles.size - directlyChangedCount;
+            incrementalStats = {
+                changedFiles: hashDiff.changed.length + hashDiff.added.length + hashDiff.deleted.length,
+                reparsedFiles: pipelineResult.reparsedFileCount,
+                affectedDependents: importerExpansion,
+                deletedFiles: hashDiff.deleted.length,
+                writeMode: 'incremental',
+            };
             await saveIncrementalDirtyState('importer-bfs', {
                 importerExpansion,
                 shadowSeedCount: shadowSeed.length,
@@ -1776,6 +1895,14 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
             const sizeForcedRebuild = shouldEscalateIncrementalWrite(filesToDelete.length, effectiveWriteSet.size, allFilePaths.length);
             if (extensionForcedRebuild || sizeForcedRebuild) {
                 escalatedFullWrite = true;
+                // #3016: escalation converts this run into a wipe + full bulk COPY of
+                // the in-memory graph, so the derived layer the skip was betting on
+                // preserving has to exist in that graph after all. Same reasoning as
+                // the not-incremental branch above, just discovered later.
+                if (preserveDerivedLayer) {
+                    progress('communities', 63, 'Detecting code communities and flows...');
+                    await pipelineResult.runDeferredDerivedPhases?.();
+                }
                 // Every live cause is named, not just the first: a DB can carry BOTH a
                 // vector index and FTS indexes, and reporting one cause while the other
                 // is equally fatal is how #2841 stayed mis-diagnosed for so long. §5.D:
@@ -1946,6 +2073,8 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
                 }
                 await walCheckpointDriver.stop();
                 await closeLbug();
+                if (buildPath === lbugPath)
+                    liveIndexMutationStarted = true;
                 await wipeLbugDbFiles(buildPath);
                 await initLbug(buildPath);
                 walCheckpointDriver = startWalCheckpointDriver();
@@ -1972,7 +2101,55 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
                 // same connection, and nothing on this branch creates or drops an index
                 // in between — so re-reading would only weaken the one-read invariant
                 // the snapshot type exists to enforce.
-                await dropSearchFTSIndexes(indexCatalogRows);
+                if (buildPath === lbugPath)
+                    liveIndexMutationStarted = true;
+                // FTS narrowing is independent of Leiden/flow reuse: even when this
+                // run re-derives communities, Ladybug still cannot DML a live FTS
+                // index (#2589), so only the tables this write set touches should
+                // lose their index. The probe is a question about the DB rather than
+                // the fresh graph — a symbol the edit DELETED is in no fresh graph
+                // but is still a row that has to go.
+                const tablesWithRows = await nodeTablesWithRowsForFiles(filesToDelete, NODE_TABLES);
+                // Narrowing 1 — the FTS sweep, from "every configured index" to "the
+                // indexes this run must touch". Three sources, and dropping any one of
+                // them strands something:
+                //   - what the writeback DELETES (the probe above), because a symbol
+                //     the edit removed is in no fresh graph but is still a row;
+                //   - what it INSERTS (the fresh graph), because inserting under a live
+                //     FTS index is the same #2589 hazard as deleting under one;
+                //   - what is MISSING right now, because narrowing to the written
+                //     tables would otherwise leave keyword search degraded forever on
+                //     tables whose index a previous escalation dropped — the next full
+                //     rebuild would be the only thing that ever restored them.
+                // An unreadable catalog proves nothing about that third set, so it
+                // withdraws the narrowing entirely rather than guess.
+                const missingFts = await missingSearchFTSIndexTables(indexCatalogRows);
+                const touchedFts = missingFts
+                    ? new Set([
+                        ...ftsTablesAmong(tablesWithRows),
+                        ...incrementalFtsTablesFromGraph(pipelineResult.graph, new Set(filesToDelete)),
+                        ...missingFts,
+                    ])
+                    : undefined;
+                // Graph-wide Spring synthetic Class nodes are DETACH DELETEd on this
+                // branch even when Class is not in the write set
+                // (`deleteSpringAutoConfigurationSyntheticClasses`). Always include
+                // Class so class_fts is not live across that DML (#2589), including
+                // when the fresh graph no longer materializes the synthetics but the
+                // DB still holds them.
+                if (touchedFts) {
+                    touchedFts.add('Class');
+                }
+                incrementalFtsRebuildTables = touchedFts;
+                // MEMBER_OF / STEP_IN_PROCESS / ENTRY_POINT_OF edges hang off the nodes
+                // the DETACH DELETE below removes, so preserving the Community/Process
+                // nodes preserves only half the layer unless these are reattached after
+                // the subgraph write puts the member nodes back. Only the probed tables
+                // can own such an edge, so they are the only ones worth scanning.
+                const derivedSnapshot = preserveDerivedLayer
+                    ? await snapshotDerivedRelsForFiles(filesToDelete, [...tablesWithRows])
+                    : [];
+                await dropSearchFTSIndexes(indexCatalogRows, incrementalFtsRebuildTables);
                 // 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
@@ -1986,6 +2163,9 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
                 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})...`),
+                    nodeTables: incrementalFtsRebuildTables
+                        ? nodeTablesForIncrementalDelete(NODE_TABLES, incrementalFtsRebuildTables)
+                        : undefined,
                 });
                 // Surgical path: Phase 3.5 restores exactly these files' embedding
                 // rows (FIX 3). Sound because deleteNodesForFiles propagates errors
@@ -1993,10 +2173,12 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
                 // 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();
+                if (!preserveDerivedLayer) {
+                    // 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
@@ -2043,7 +2225,9 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
                 //    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);
+                const subgraph = extractChangedSubgraph(pipelineResult.graph, effectiveWriteSet, {
+                    includeDerivedGraphWide: !preserveDerivedLayer,
+                });
                 wroteChangedSubgraphOnly = true;
                 await saveIncrementalDirtyState('load-graph', {
                     importerExpansion,
@@ -2056,6 +2240,9 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
                     const pct = Math.min(84, 65 + Math.round((lbugMsgCount / (lbugMsgCount + 10)) * 19));
                     progress('lbug', pct, msg);
                 });
+                if (preserveDerivedLayer && derivedSnapshot.length > 0) {
+                    await restoreDerivedRels(derivedSnapshot);
+                }
             }
             // Boundary drain (#2409): checkpoint at the end of the incremental
             // writeback so the WAL it accumulated never lingers into the FTS and
@@ -2107,6 +2294,7 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
             // 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, {
+                tables: incrementalFtsRebuildTables,
                 onIndexStart: options.verbose
                     ? (table, indexName) => log(`FTS: creating ${table}.${indexName}`)
                     : undefined,
@@ -2751,8 +2939,9 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
                 files: pipelineResult.totalFileCount,
                 nodes: stats.nodes,
                 edges: stats.edges,
-                communities: pipelineResult.communityResult?.stats.totalCommunities,
-                processes: pipelineResult.processResult?.stats.totalProcesses,
+                communities: pipelineResult.communityResult?.stats.totalCommunities ??
+                    existingMeta?.stats?.communities,
+                processes: pipelineResult.processResult?.stats.totalProcesses ?? existingMeta?.stats?.processes,
                 embeddings: persistedEmbeddingCount,
             },
             capabilities: {
@@ -2828,6 +3017,12 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
             // absence has exactly one meaning — an index older than the field.
             embeddingDims: EMBEDDING_DIMS,
             fileHashes: hasGitDir(repoPath) ? newFileHashesRecord : undefined,
+            indexCoverage: hasGitDir(repoPath)
+                ? {
+                    maxFileSizeBytes: getMaxFileSizeBytes(),
+                    dirtyPaths: (listWorkingTreeDirtyPaths(repoPath) ?? Object.keys(newFileHashesRecord)).filter((rel) => newFileHashesRecord[rel] !== undefined && !isGitNexusManagedPath(rel)),
+                }
+                : 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
@@ -2956,9 +3151,10 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
                     files: pipelineResult.totalFileCount,
                     nodes: stats.nodes,
                     edges: stats.edges,
-                    communities: pipelineResult.communityResult?.stats.totalCommunities,
+                    communities: pipelineResult.communityResult?.stats.totalCommunities ??
+                        existingMeta?.stats?.communities,
                     clusters: aggregatedClusterCount,
-                    processes: pipelineResult.processResult?.stats.totalProcesses,
+                    processes: pipelineResult.processResult?.stats.totalProcesses ?? existingMeta?.stats?.processes,
                 }, undefined, {
                     skipAgentsMd: options.skipAgentsMd,
                     skipSkills: options.skipSkills,
@@ -3006,6 +3202,7 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
             : false;
         if (useAtomicSwap && builtDbExists) {
             await retryRename(buildPath, lbugPath);
+            liveIndexMutationStarted = true;
             // 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.
@@ -3037,6 +3234,12 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
             ftsSkipped: !ftsReady,
             ftsSkipReason: ftsReady ? undefined : ftsSkipReason,
             isPrimaryBranch: !placement.branch,
+            incrementalStats: incrementalStats
+                ? {
+                    ...incrementalStats,
+                    writeMode: escalatedFullWrite ? 'full' : 'incremental',
+                }
+                : undefined,
         };
     }
     catch (err) {
@@ -3079,6 +3282,11 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
                 /* swallow — orphan reclamation must never mask the real failure */
             }
         }
+        if (liveIndexMutationStarted) {
+            // Preserve the original error identity/prototype: callers distinguish
+            // IndexLockTimeoutError and other domain failures with `instanceof`.
+            recordLiveIndexMutationRisk(err);
+        }
         throw err;
     }
 }

package/dist/core/search/fts-indexes.d.ts

@@ -59,6 +59,12 @@ export declare const SUPPORTED_FTS_STEMMERS: ReadonlySet<string>;
 export interface CreateSearchFTSIndexesOptions {
     onIndexStart?: (table: string, indexName: string) => void;
     onIndexReady?: (table: string, indexName: string) => void;
+    /**
+     * When set, only these node-table names are dropped/rebuilt (#3016).
+     * Omit to rebuild every configured FTS index (full analyze / deleted-file
+     * incremental / `--repair-fts`).
+     */
+    tables?: ReadonlySet<string>;
 }
 /**
  * Resolve + validate `GITNEXUS_FTS_STEMMER` once, up front at analyze startup,
@@ -98,7 +104,19 @@ export declare function getSearchFTSStemmer(): string;
  * contract, and the same one-shared-`SHOW_INDEXES`-read purpose, as the gates in
  * `lbug-adapter.ts`. Omit it to have the sweep read the catalog itself.
  */
-export declare function dropSearchFTSIndexes(indexRows?: IndexCatalogSnapshot): Promise<void>;
+export declare function dropSearchFTSIndexes(indexRows?: IndexCatalogSnapshot, tables?: ReadonlySet<string>): Promise<void>;
+/**
+ * The configured FTS tables whose index the catalog proves is ABSENT right now.
+ *
+ * `undefined` means the catalog could not be read, which proves nothing — the
+ * same fail-closed reading the sweep above applies. Callers narrowing a rebuild
+ * to a subset of tables (#3016) must union this in, or must not narrow at all
+ * when it is `undefined`: a run that rebuilds only the tables it wrote leaves
+ * keyword search permanently degraded on every table whose index went missing
+ * earlier (a prior escalation drops all of them, and only the next full rebuild
+ * would ever put them back).
+ */
+export declare function missingSearchFTSIndexTables(indexRows?: IndexCatalogSnapshot): Promise<Set<string> | undefined>;
 /** One configured index that could not be (re)built, and why. */
 export interface FtsIndexBuildFailure {
     table: string;

package/dist/core/search/fts-indexes.js

@@ -172,7 +172,7 @@ export function getSearchFTSStemmer() {
  * contract, and the same one-shared-`SHOW_INDEXES`-read purpose, as the gates in
  * `lbug-adapter.ts`. Omit it to have the sweep read the catalog itself.
  */
-export async function dropSearchFTSIndexes(indexRows) {
+export async function dropSearchFTSIndexes(indexRows, tables) {
     // One catalog read for the whole sweep, decided PER CONFIGURED INDEX on
     // IDENTITY (#2841 cleanup review). `undefined` = the catalog could not be
     // read, which proves nothing — attempt every drop rather than skip a real one,
@@ -193,6 +193,8 @@ export async function dropSearchFTSIndexes(indexRows) {
     // whether the sweep ran or not.
     const rows = await resolveGateRows(indexRows);
     for (const { table, indexName } of FTS_INDEXES) {
+        if (tables && !tables.has(table))
+            continue;
         // Skip only what the catalog POSITIVELY proves absent. Without this, a
         // machine whose FTS extension cannot load, analyzing a DB that never carried
         // an FTS index, pays one failed `CALL DROP_FTS_INDEX` per configured table on
@@ -209,6 +211,29 @@ export async function dropSearchFTSIndexes(indexRows) {
         await dropFTSIndex(table, indexName);
     }
 }
+/**
+ * The configured FTS tables whose index the catalog proves is ABSENT right now.
+ *
+ * `undefined` means the catalog could not be read, which proves nothing — the
+ * same fail-closed reading the sweep above applies. Callers narrowing a rebuild
+ * to a subset of tables (#3016) must union this in, or must not narrow at all
+ * when it is `undefined`: a run that rebuilds only the tables it wrote leaves
+ * keyword search permanently degraded on every table whose index went missing
+ * earlier (a prior escalation drops all of them, and only the next full rebuild
+ * would ever put them back).
+ */
+export async function missingSearchFTSIndexTables(indexRows) {
+    const rows = await resolveGateRows(indexRows);
+    if (rows === undefined)
+        return undefined;
+    const missing = new Set();
+    for (const { table, indexName } of FTS_INDEXES) {
+        const present = rows.some((row) => indexRowTable(row) === table && indexRowName(row) === indexName);
+        if (!present)
+            missing.add(table);
+    }
+    return missing;
+}
 /**
  * Build every configured FTS index, and keep going when one of them fails
  * (#2889).
@@ -232,6 +257,8 @@ export async function createSearchFTSIndexes(options) {
     const stemmer = getSearchFTSStemmer();
     const failures = [];
     for (const { table, indexName, properties } of FTS_INDEXES) {
+        if (options?.tables && !options.tables.has(table))
+            continue;
         options?.onIndexStart?.(table, indexName);
         // Drop first so the live `properties` always win. `createFTSIndex` is
         // idempotent-by-name (skips when the index already exists), so without the

package/dist/core/wiki/generator.js

@@ -17,6 +17,7 @@ import { generateHTMLViewer } from './html-viewer.js';
 import { sanitizeMermaidMarkdown } from './mermaid-sanitizer.js';
 import { callLLM, estimateTokens, } from './llm-client.js';
 import { callCursorLLM, resolveCursorConfig } from './cursor-client.js';
+import { callGrokLLM, resolveGrokConfig } from './grok-client.js';
 import { callClaudeLLM, callCodexLLM, callOpenCodeLLM, resolveLocalCLIConfig, } from './local-cli-client.js';
 import { GROUPING_SYSTEM_PROMPT, GROUPING_USER_PROMPT, MODULE_SYSTEM_PROMPT, MODULE_USER_PROMPT, PARENT_SYSTEM_PROMPT, PARENT_USER_PROMPT, OVERVIEW_SYSTEM_PROMPT, OVERVIEW_USER_PROMPT, fillTemplate, formatFileListForGrouping, formatDirectoryTree, formatCallEdges, formatProcesses, } from './prompts.js';
 import { shouldIgnorePath } from '../../config/ignore-service.js';
@@ -123,6 +124,13 @@ export class WikiGenerator {
             });
             return callCursorLLM(prompt, cursorConfig, systemPrompt, options);
         }
+        if (this.llmConfig.provider === 'grok') {
+            const grokConfig = resolveGrokConfig({
+                model: this.llmConfig.model,
+                requestTimeoutMs: this.llmConfig.requestTimeoutMs,
+            });
+            return callGrokLLM(prompt, grokConfig, systemPrompt, options);
+        }
         if (this.llmConfig.provider === 'claude' ||
             this.llmConfig.provider === 'codex' ||
             this.llmConfig.provider === 'opencode') {

package/dist/core/wiki/grok-client.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Grok Build CLI client for wiki generation.
+ *
+ * Uses headless `grok --prompt-file` so large wiki prompts are not placed on
+ * argv or stdin (Grok does not read stdin as the prompt).
+ */
+import type { CallLLMOptions, LLMResponse } from './llm-client.js';
+export interface GrokConfig {
+    model?: string;
+    requestTimeoutMs?: number;
+}
+/** Returns `'grok'` when the CLI is on PATH, else null. Cached. */
+export declare function detectGrokCLI(): string | null;
+export declare function resolveGrokConfig(overrides?: Partial<GrokConfig>): GrokConfig;
+/**
+ * Call Grok Build in headless mode and return the assistant text.
+ *
+ * `--cwd` is an empty temp directory (not the repo) so project AGENTS.md
+ * files are not injected into wiki generation.
+ */
+export declare function callGrokLLM(prompt: string, config: GrokConfig, systemPrompt?: string, options?: CallLLMOptions): Promise<LLMResponse>;