gitnexus 1.6.11-rc.13 → 1.6.11-rc.14

package/dist/core/incremental/derived-writeback.d.ts

@@ -0,0 +1,36 @@
+import type { KnowledgeGraph } from '../graph/types.js';
+import type { FileHashDiff } from '../../storage/file-hash.js';
+/** The FTS-backed members of `tables`. */
+export declare const ftsTablesAmong: (tables: Iterable<string>) => Set<string>;
+/**
+ * Whether a surgical incremental write may reuse the persisted derived layer.
+ *
+ * Deletions disqualify it: the persisted Community/Process rows and their
+ * MEMBER_OF / STEP_IN_PROCESS edges can reference nodes that no longer exist
+ * after this run, and nothing short of re-deriving can tell which.
+ *
+ * Added or content-changed files also disqualify it: they can introduce,
+ * rename, or retarget symbols and CALLS edges that Leiden and flow extraction
+ * consume. File-deletion-only was too weak a proof that the derived graph is
+ * still valid.
+ */
+export declare const shouldPreservePersistedDerivedGraph: (diff: Pick<FileHashDiff, "deleted" | "added" | "changed">) => boolean;
+/**
+ * FTS-backed node tables that the fresh graph will WRITE rows into for
+ * `fileSet` — the inserting half of the DML.
+ *
+ * Callers must union this with a DB probe for the deleting half
+ * (`nodeTablesWithRowsForFiles`): a table whose last row in these files was
+ * just removed by the edit has nothing here, but still holds a stale row that
+ * the writeback must delete, and deleting it means taking its index down too.
+ */
+export declare const incrementalFtsTablesFromGraph: (graph: KnowledgeGraph, fileSet: ReadonlySet<string>) => Set<string>;
+/**
+ * The node tables an incremental DETACH DELETE should target, given the FTS
+ * tables this run is rebuilding.
+ *
+ * Every non-FTS table (Folder, CodeElement, …) deletes as before. An FTS-backed
+ * table only deletes when its index is being rebuilt anyway, because deleting
+ * from it otherwise would mean DML against a live FTS index (#2589).
+ */
+export declare const nodeTablesForIncrementalDelete: (allNodeTables: readonly string[], rebuildingFtsTables: ReadonlySet<string>) => string[];

package/dist/core/incremental/derived-writeback.js

@@ -0,0 +1,68 @@
+/**
+ * Incremental derived-layer writeback helpers (#3016).
+ *
+ * The derived layers — Leiden communities, execution flows, and the FTS
+ * indexes — are graph-wide, so every analyze run rebuilt all three in full no
+ * matter how small the diff. A surgical incremental write can instead:
+ *   - drop and rebuild only the FTS indexes whose tables hold rows in the
+ *     write set (LadybugDB still cannot DML a table with a live FTS index —
+ *     #2589 — so a table being written must still lose its index first);
+ *   - leave the untouched tables' rows alone, so their indexes stay live;
+ *   - reuse persisted Community/Process rows only when the file-hash diff is
+ *     empty (no added, changed, or deleted files). Any content change can
+ *     add, rename, or retarget symbols that Leiden and flow extraction
+ *     consume — a no-deletion edit is not a validity proof.
+ */
+import { FTS_INDEXES } from '../search/fts-schema.js';
+const FTS_TABLE_NAMES = new Set(FTS_INDEXES.map((i) => i.table));
+/** The FTS-backed members of `tables`. */
+export const ftsTablesAmong = (tables) => {
+    const out = new Set();
+    for (const table of tables) {
+        if (FTS_TABLE_NAMES.has(table))
+            out.add(table);
+    }
+    return out;
+};
+/**
+ * Whether a surgical incremental write may reuse the persisted derived layer.
+ *
+ * Deletions disqualify it: the persisted Community/Process rows and their
+ * MEMBER_OF / STEP_IN_PROCESS edges can reference nodes that no longer exist
+ * after this run, and nothing short of re-deriving can tell which.
+ *
+ * Added or content-changed files also disqualify it: they can introduce,
+ * rename, or retarget symbols and CALLS edges that Leiden and flow extraction
+ * consume. File-deletion-only was too weak a proof that the derived graph is
+ * still valid.
+ */
+export const shouldPreservePersistedDerivedGraph = (diff) => diff.deleted.length === 0 && diff.added.length === 0 && diff.changed.length === 0;
+/**
+ * FTS-backed node tables that the fresh graph will WRITE rows into for
+ * `fileSet` — the inserting half of the DML.
+ *
+ * Callers must union this with a DB probe for the deleting half
+ * (`nodeTablesWithRowsForFiles`): a table whose last row in these files was
+ * just removed by the edit has nothing here, but still holds a stale row that
+ * the writeback must delete, and deleting it means taking its index down too.
+ */
+export const incrementalFtsTablesFromGraph = (graph, fileSet) => {
+    const touched = new Set();
+    graph.forEachNode((n) => {
+        const filePath = n.properties?.filePath;
+        if (!filePath || !fileSet.has(filePath))
+            return;
+        if (FTS_TABLE_NAMES.has(n.label))
+            touched.add(n.label);
+    });
+    return touched;
+};
+/**
+ * The node tables an incremental DETACH DELETE should target, given the FTS
+ * tables this run is rebuilding.
+ *
+ * Every non-FTS table (Folder, CodeElement, …) deletes as before. An FTS-backed
+ * table only deletes when its index is being rebuilt anyway, because deleting
+ * from it otherwise would mean DML against a live FTS index (#2589).
+ */
+export const nodeTablesForIncrementalDelete = (allNodeTables, rebuildingFtsTables) => allNodeTables.filter((tableName) => !FTS_TABLE_NAMES.has(tableName) || rebuildingFtsTables.has(tableName));

package/dist/core/incremental/subgraph-extract.d.ts

@@ -6,9 +6,9 @@
  * replaced, produce a smaller KnowledgeGraph that contains:
  *
  *   - Every node whose `properties.filePath` is in `toWriteSet`.
- *   - Every graph-wide node (Community, Process, and Spring metadata
- *     placeholders) — these are regenerated each run and must be fully
- *     rewritten.
+ *   - Graph-wide Community/Process nodes unless `includeDerivedGraphWide`
+ *     is false (#3016 incremental preserve). Spring metadata placeholders
+ *     are always included.
  *   - Every relationship where AT LEAST ONE endpoint is in the writable
  *     set above. Relationships entirely between unchanged-file nodes
  *     are skipped — their rows are still in the DB and re-inserting
@@ -48,7 +48,9 @@
  * IMPORTS from the pre-pipeline DB) covers that case instead.
  */
 import type { KnowledgeGraph } from '../graph/types.js';
-export declare const extractChangedSubgraph: (fullGraph: KnowledgeGraph, toWriteSet: ReadonlySet<string>) => KnowledgeGraph;
+export declare const extractChangedSubgraph: (fullGraph: KnowledgeGraph, toWriteSet: ReadonlySet<string>, options?: {
+    includeDerivedGraphWide?: boolean;
+}) => KnowledgeGraph;
 /**
  * Public — derive the EFFECTIVE write-set: `toWriteSet` expanded by one
  * hop along every file-owned edge in the new graph that crosses the

package/dist/core/incremental/subgraph-extract.js

@@ -6,9 +6,9 @@
  * replaced, produce a smaller KnowledgeGraph that contains:
  *
  *   - Every node whose `properties.filePath` is in `toWriteSet`.
- *   - Every graph-wide node (Community, Process, and Spring metadata
- *     placeholders) — these are regenerated each run and must be fully
- *     rewritten.
+ *   - Graph-wide Community/Process nodes unless `includeDerivedGraphWide`
+ *     is false (#3016 incremental preserve). Spring metadata placeholders
+ *     are always included.
  *   - Every relationship where AT LEAST ONE endpoint is in the writable
  *     set above. Relationships entirely between unchanged-file nodes
  *     are skipped — their rows are still in the DB and re-inserting
@@ -108,12 +108,14 @@ const indexNodeFilePaths = (fullGraph) => {
     });
     return idx;
 };
-export const extractChangedSubgraph = (fullGraph, toWriteSet) => {
+export const extractChangedSubgraph = (fullGraph, toWriteSet, options) => {
     const sub = createKnowledgeGraph();
     const writableNodeIds = new Set();
+    const includeDerivedGraphWide = options?.includeDerivedGraphWide !== false;
     fullGraph.forEachNode((n) => {
         const filePath = n.properties?.filePath;
-        const include = (filePath && toWriteSet.has(filePath)) || isGraphWideNode(n);
+        const derivedWide = includeDerivedGraphWide || (n.label !== 'Community' && n.label !== 'Process');
+        const include = (filePath && toWriteSet.has(filePath)) || (isGraphWideNode(n) && derivedWide);
         if (include) {
             sub.addNode(n);
             writableNodeIds.add(n.id);

package/dist/core/ingestion/pipeline-phases/runner.d.ts

@@ -17,6 +17,9 @@ import type { PipelinePhase, PipelineContext, PhaseResult } from './types.js';
  *
  * @param phases  All phases to execute (order doesn't matter — sorted internally)
  * @param ctx     Shared pipeline context
+ * @param seed    Results of phases that already ran against this same context,
+ *                available to `phases` as dependencies (#3016 deferred derived
+ *                phases). Included in the returned map.
  * @returns       Map of phase name → PhaseResult (all completed phases)
  */
-export declare function runPipeline(phases: readonly PipelinePhase[], ctx: PipelineContext): Promise<ReadonlyMap<string, PhaseResult<unknown>>>;
+export declare function runPipeline(phases: readonly PipelinePhase[], ctx: PipelineContext, seed?: ReadonlyMap<string, PhaseResult<unknown>>): Promise<ReadonlyMap<string, PhaseResult<unknown>>>;

package/dist/core/ingestion/pipeline-phases/runner.js

@@ -13,22 +13,30 @@
  */
 import { isDev } from '../utils/env.js';
 import { logger } from '../../logger.js';
-/**
- * Validate that the phases form a valid dependency graph (no cycles, all deps present).
- * Returns phases in topological execution order.
- */
-function topologicalSort(phases) {
-    const phaseMap = new Map();
+function assertUniquePhaseNames(phases) {
+    const seen = new Set();
     for (const phase of phases) {
-        if (phaseMap.has(phase.name)) {
+        if (seen.has(phase.name)) {
             throw new Error(`Duplicate phase name: '${phase.name}'`);
         }
-        phaseMap.set(phase.name, phase);
+        seen.add(phase.name);
     }
+}
+/**
+ * Validate that the phases form a valid dependency graph (no cycles, all deps present).
+ * Returns phases in topological execution order.
+ *
+ * `satisfied` names phases whose results are already available (a deferred
+ * follow-up run over the same context, #3016). Their edges are dropped rather
+ * than validated, because they are resolved by definition.
+ */
+function topologicalSort(phases, satisfied = new Set()) {
+    assertUniquePhaseNames(phases);
+    const phaseMap = new Map(phases.map((p) => [p.name, p]));
     // Validate all deps exist
     for (const phase of phases) {
         for (const dep of phase.deps) {
-            if (!phaseMap.has(dep)) {
+            if (!phaseMap.has(dep) && !satisfied.has(dep)) {
                 throw new Error(`Phase '${phase.name}' depends on '${dep}', which is not registered`);
             }
         }
@@ -37,8 +45,9 @@ function topologicalSort(phases) {
     const inDegree = new Map();
     const reverseDeps = new Map();
     for (const phase of phases) {
-        inDegree.set(phase.name, phase.deps.length);
-        for (const dep of phase.deps) {
+        const pendingDeps = phase.deps.filter((dep) => !satisfied.has(dep));
+        inDegree.set(phase.name, pendingDeps.length);
+        for (const dep of pendingDeps) {
             let rev = reverseDeps.get(dep);
             if (!rev) {
                 rev = [];
@@ -125,12 +134,23 @@ function findCyclePath(remaining, phaseMap) {
  *
  * @param phases  All phases to execute (order doesn't matter — sorted internally)
  * @param ctx     Shared pipeline context
+ * @param seed    Results of phases that already ran against this same context,
+ *                available to `phases` as dependencies (#3016 deferred derived
+ *                phases). Included in the returned map.
  * @returns       Map of phase name → PhaseResult (all completed phases)
  */
-export async function runPipeline(phases, ctx) {
+export async function runPipeline(phases, ctx, seed) {
+    // A seeded phase has already run against this context; re-running it would
+    // apply its graph writes a second time. "Already ran" is the whole meaning of
+    // the seed, so honour it here rather than making every caller pre-filter.
+    const satisfied = new Set(seed?.keys() ?? []);
     let sorted;
     try {
-        sorted = topologicalSort(phases);
+        // Duplicate names must be rejected on the caller-supplied list *before*
+        // seed-filtering. Filtering first would drop a seeded duplicate and let
+        // `topologicalSort` see a unique name (#3102).
+        assertUniquePhaseNames(phases);
+        sorted = topologicalSort(phases.filter((p) => !satisfied.has(p.name)), satisfied);
     }
     catch (err) {
         // Emit a terminal 'error' progress event for graph-validation failures
@@ -152,7 +172,7 @@ export async function runPipeline(phases, ctx) {
         }
         throw err;
     }
-    const results = new Map();
+    const results = new Map(seed);
     for (const phase of sorted) {
         const start = Date.now();
         if (isDev) {

package/dist/core/ingestion/pipeline.d.ts

@@ -25,6 +25,12 @@ export interface PipelineOptions {
      * to retain those nodes under `skipGraphPhases`.
      */
     skipGraphPhases?: boolean;
+    /**
+     * Skip only Leiden community detection and process/flow extraction (#3016).
+     * MRO/DI still run. Used on warm incremental analyze so persisted
+     * Community/Process rows can be kept instead of wipe+rewrite.
+     */
+    skipDerivedGraphPhases?: boolean;
     /** Per-advice Spring AOP candidate inspection cap. `0` disables this cap. */
     springAopMaxCandidateInspectionsPerAdvice?: number;
     /** Aggregate Spring AOP candidate inspection cap for one analysis. `0` disables this cap. */

package/dist/core/ingestion/pipeline.js

@@ -61,8 +61,12 @@ export function buildPhaseList(options) {
         .register(mroPhase, { enabledWhen: (o) => !o.skipGraphPhases })
         .register(springAopInheritancePhase, { enabledWhen: (o) => !o.skipGraphPhases })
         .register(diPhase, { enabledWhen: (o) => !o.skipGraphPhases })
-        .register(communitiesPhase, { enabledWhen: (o) => !o.skipGraphPhases })
-        .register(processesPhase, { enabledWhen: (o) => !o.skipGraphPhases })
+        .register(communitiesPhase, {
+        enabledWhen: (o) => !o.skipGraphPhases && o.skipDerivedGraphPhases !== true,
+    })
+        .register(processesPhase, {
+        enabledWhen: (o) => !o.skipGraphPhases && o.skipDerivedGraphPhases !== true,
+    })
         // Normalize a missing options object once here so phase predicates above
         // take a required PipelineOptions and need no `?.` guard (#2080 review S1).
         .build(options ?? {}));
@@ -91,17 +95,18 @@ export const runPipelineFromRepo = async (repoPath, onProgress, options) => {
         graphEmitSink = new GraphEmitSink(graph, options.graphEmitCsvDir);
     }
     const phases = buildPhaseList(options);
+    const ctx = {
+        repoPath,
+        graph: graphEmitSink ?? graph,
+        onProgress,
+        options,
+        pipelineStart,
+        graphEmit: graphEmitSink,
+    };
     let graphEmitManifest;
     let results;
     try {
-        results = await runPipeline(phases, {
-            repoPath,
-            graph: graphEmitSink ?? graph,
-            onProgress,
-            options,
-            pipelineStart,
-            graphEmit: graphEmitSink,
-        });
+        results = await runPipeline(phases, ctx);
         graphEmitManifest = graphEmitSink?.finalize();
     }
     finally {
@@ -140,7 +145,7 @@ export const runPipelineFromRepo = async (repoPath, onProgress, options) => {
             nodesCreated: graph.nodeCount,
         },
     });
-    return {
+    const result = {
         // The RAW graph, deliberately — NOT `graphEmitSink`. Phases above received
         // the sink so their reads are complete, but `loadGraphToLbug` feeds this to
         // `streamAllCSVsToDisk`, and the sink's complete iterator would then emit
@@ -162,4 +167,30 @@ export const runPipelineFromRepo = async (repoPath, onProgress, options) => {
         pdgEmitManifest,
         propertyInference,
     };
+    // #3016: hand back a way to run the derived phases `skipDerivedGraphPhases`
+    // held back. Which phases those are is answered by re-asking the registry
+    // with only that flag cleared — the one form of the question that stays
+    // correct when a different predicate (`skipGraphPhases`) also disables them,
+    // since then they are absent for a reason a deferred run cannot fix and the
+    // filter yields nothing. The sink guard mirrors the `graph` note above: a
+    // streaming run is a full rebuild, which never sets the skip flag, so an
+    // active sink here means the two got combined by mistake — and deferred
+    // phases writing into a finalized sink would emit past its manifest.
+    const deferredDerivedPhases = options?.skipDerivedGraphPhases === true && graphEmitSink === undefined
+        ? buildPhaseList({ ...options, skipDerivedGraphPhases: false }).filter((p) => (p.name === 'communities' || p.name === 'processes') && !results.has(p.name))
+        : [];
+    if (deferredDerivedPhases.length > 0) {
+        result.runDeferredDerivedPhases = async () => {
+            const derived = await runPipeline(deferredDerivedPhases, ctx, results);
+            // Presence-checked for the same reason as the block above: a phase the
+            // registry filtered out is absent, and `getPhaseOutput` throws on absent.
+            if (derived.has('communities')) {
+                result.communityResult = getPhaseOutput(derived, 'communities').communityResult;
+            }
+            if (derived.has('processes')) {
+                result.processResult = getPhaseOutput(derived, 'processes').processResult;
+            }
+        };
+    }
+    return result;
 };

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

@@ -385,7 +385,66 @@ export declare const DELETE_FILES_CHUNK_SIZE = 200;
  */
 export declare const deleteNodesForFiles: (filePaths: readonly string[], options?: {
     onChunk?: (filesDone: number, filesTotal: number) => void;
+    /** When set, only these node tables are DETACH DELETEd (#3016). */
+    nodeTables?: readonly string[];
 }) => Promise<void>;
+/**
+ * Which of `candidateTables` currently hold at least one row for `filePaths`.
+ *
+ * The incremental writeback uses this to decide which FTS-backed tables it is
+ * about to DML (#3016). It has to be a question about the DB, not about the
+ * freshly built graph: an edit that DELETES the last Rust trait in a file
+ * leaves no Trait node in the new graph, but the old row is still in the index
+ * and still has to be deleted — and its FTS index still has to come down first.
+ */
+export declare const nodeTablesWithRowsForFiles: (filePaths: readonly string[], candidateTables: readonly string[]) => Promise<Set<string>>;
+/**
+ * One MEMBER_OF / STEP_IN_PROCESS edge, carrying everything needed to recreate
+ * it byte-for-byte: both endpoint labels (so the re-MATCH is label-scoped
+ * rather than a scan of every node) and every column of the relationship
+ * table, `step` included — process traces order by it (`ORDER BY r.step`), so
+ * an edge restored without it silently scrambles the flow it belongs to.
+ */
+export interface DerivedRelSnapshot {
+    sourceId: string;
+    sourceLabel: string;
+    targetId: string;
+    targetLabel: string;
+    type: string;
+    confidence: number;
+    reason: string;
+    step: number;
+}
+/**
+ * Capture the MEMBER_OF / STEP_IN_PROCESS / ENTRY_POINT_OF edges owned by `filePaths`, before a
+ * surgical incremental write DETACH DELETEs their file-side endpoints (#3016).
+ *
+ * Only meaningful on the write plan that keeps the persisted Community/Process
+ * nodes: those nodes survive the delete, but the edges tying this run's changed
+ * files to them do not, and the pipeline did not re-derive them.
+ *
+ * Both endpoints are matched by an EXPLICIT label — `sourceTables` on one side,
+ * the edge type's fixed target table on the other — so the labels come from the
+ * query rather than the rows. `labels(n)[0]` over an unlabelled match returns
+ * an empty string on this engine, which silently produced a snapshot that
+ * restored nothing.
+ *
+ * Read failures propagate. This runs against a warm index whose derived tables
+ * the caller has already established exist, so a failure here is a real fault —
+ * and swallowing it would drop the edges silently, which looks identical to a
+ * repo that genuinely has no communities.
+ */
+export declare const snapshotDerivedRelsForFiles: (filePaths: readonly string[], sourceTables: readonly string[]) => Promise<DerivedRelSnapshot[]>;
+/**
+ * Re-create the edges captured by `snapshotDerivedRelsForFiles`, after the
+ * incremental subgraph load has put their file-side endpoints back.
+ *
+ * Endpoints are matched by label + id, mirroring `fallbackRelationshipInserts`:
+ * an unlabelled `MATCH (a), (b)` is a cartesian product over the whole graph
+ * and does not finish on a real index. An endpoint the load did not restore
+ * simply matches nothing, so the edge is dropped rather than mis-attached.
+ */
+export declare const restoreDerivedRels: (rels: readonly DerivedRelSnapshot[]) => Promise<void>;
 export declare const getEmbeddingTableName: () => string;
 /**
  * Return the distinct repo-relative paths of files that import

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

@@ -2303,7 +2303,8 @@ export const deleteNodesForFiles = async (filePaths, options = {}) => {
                     'skipping embedding-row deletes for this writeback.');
             }
         }
-        for (const tableName of NODE_TABLES) {
+        const tables = options.nodeTables ?? NODE_TABLES;
+        for (const tableName of tables) {
             // Community/Process are graph-wide (no filePath); the orchestrator
             // drops them wholesale via deleteAllCommunitiesAndProcesses.
             if (tableName === 'Community' || tableName === 'Process')
@@ -2314,6 +2315,158 @@ export const deleteNodesForFiles = async (filePaths, options = {}) => {
         options.onChunk?.(Math.min((chunkIndex + 1) * DELETE_FILES_CHUNK_SIZE, filePaths.length), filePaths.length);
     }
 };
+/**
+ * Which of `candidateTables` currently hold at least one row for `filePaths`.
+ *
+ * The incremental writeback uses this to decide which FTS-backed tables it is
+ * about to DML (#3016). It has to be a question about the DB, not about the
+ * freshly built graph: an edit that DELETES the last Rust trait in a file
+ * leaves no Trait node in the new graph, but the old row is still in the index
+ * and still has to be deleted — and its FTS index still has to come down first.
+ */
+export const nodeTablesWithRowsForFiles = async (filePaths, candidateTables) => {
+    const c = conn;
+    if (!c) {
+        throw new Error('LadybugDB not initialized. Call initLbug first.');
+    }
+    const found = new Set();
+    return withConnLock(async () => {
+        for (const batch of chunk(filePaths, DELETE_FILES_CHUNK_SIZE)) {
+            const listLiteral = `[${batch.map((p) => formatCypherValue(p)).join(', ')}]`;
+            for (const tableName of candidateTables) {
+                // Graph-wide tables have no filePath column to filter on.
+                if (tableName === 'Community' || tableName === 'Process')
+                    continue;
+                if (found.has(tableName))
+                    continue;
+                // determinism: probe — asks only whether the table has any row for
+                // these files, so which row comes back cannot change the answer.
+                const queryResult = await c.query(`MATCH (n:${escapeTableName(tableName)}) WHERE n.filePath IN ${listLiteral} ` +
+                    `RETURN n.id LIMIT 1`);
+                try {
+                    const result = Array.isArray(queryResult) ? queryResult[0] : queryResult;
+                    if ((await result.getAll()).length > 0)
+                        found.add(tableName);
+                }
+                finally {
+                    await closeQueryResults(queryResult);
+                }
+            }
+        }
+        return found;
+    });
+};
+/**
+ * The graph-wide derived edges and the node table each one points at. Both are
+ * produced by the derived phases (Leiden, flow extraction) rather than by
+ * parsing, which is why an incremental run that skips those phases has to carry
+ * them across the writeback itself.
+ */
+const DERIVED_REL_KINDS = [
+    { type: 'MEMBER_OF', targetLabel: 'Community' },
+    { type: 'STEP_IN_PROCESS', targetLabel: 'Process' },
+    { type: 'ENTRY_POINT_OF', targetLabel: 'Process' },
+];
+/**
+ * Capture the MEMBER_OF / STEP_IN_PROCESS / ENTRY_POINT_OF edges owned by `filePaths`, before a
+ * surgical incremental write DETACH DELETEs their file-side endpoints (#3016).
+ *
+ * Only meaningful on the write plan that keeps the persisted Community/Process
+ * nodes: those nodes survive the delete, but the edges tying this run's changed
+ * files to them do not, and the pipeline did not re-derive them.
+ *
+ * Both endpoints are matched by an EXPLICIT label — `sourceTables` on one side,
+ * the edge type's fixed target table on the other — so the labels come from the
+ * query rather than the rows. `labels(n)[0]` over an unlabelled match returns
+ * an empty string on this engine, which silently produced a snapshot that
+ * restored nothing.
+ *
+ * Read failures propagate. This runs against a warm index whose derived tables
+ * the caller has already established exist, so a failure here is a real fault —
+ * and swallowing it would drop the edges silently, which looks identical to a
+ * repo that genuinely has no communities.
+ */
+export const snapshotDerivedRelsForFiles = async (filePaths, sourceTables) => {
+    const c = conn;
+    if (!c) {
+        throw new Error('LadybugDB not initialized. Call initLbug first.');
+    }
+    const out = [];
+    return withConnLock(async () => {
+        for (const batch of chunk(filePaths, DELETE_FILES_CHUNK_SIZE)) {
+            const listLiteral = `[${batch.map((p) => formatCypherValue(p)).join(', ')}]`;
+            for (const sourceLabel of sourceTables) {
+                if (sourceLabel === 'Community' || sourceLabel === 'Process')
+                    continue;
+                for (const { type, targetLabel } of DERIVED_REL_KINDS) {
+                    const queryResult = await c.query(`MATCH (n:${escapeTableName(sourceLabel)})-[r:${REL_TABLE_NAME}]->` +
+                        `(m:${escapeTableName(targetLabel)}) ` +
+                        `WHERE n.filePath IN ${listLiteral} AND r.type = ${formatCypherValue(type)} ` +
+                        `RETURN n.id AS sourceId, m.id AS targetId, ` +
+                        `r.confidence AS confidence, r.reason AS reason, r.step AS step`);
+                    try {
+                        const result = Array.isArray(queryResult) ? queryResult[0] : queryResult;
+                        for (const row of await result.getAll()) {
+                            const rec = row;
+                            if (typeof rec.sourceId !== 'string' || typeof rec.targetId !== 'string')
+                                continue;
+                            out.push({
+                                sourceId: rec.sourceId,
+                                sourceLabel,
+                                targetId: rec.targetId,
+                                targetLabel,
+                                type,
+                                confidence: typeof rec.confidence === 'number' ? rec.confidence : 1.0,
+                                reason: typeof rec.reason === 'string' ? rec.reason : '',
+                                step: typeof rec.step === 'number'
+                                    ? rec.step
+                                    : typeof rec.step === 'bigint'
+                                        ? Number(rec.step)
+                                        : 0,
+                            });
+                        }
+                    }
+                    finally {
+                        await closeQueryResults(queryResult);
+                    }
+                }
+            }
+        }
+        return out;
+    });
+};
+/**
+ * Re-create the edges captured by `snapshotDerivedRelsForFiles`, after the
+ * incremental subgraph load has put their file-side endpoints back.
+ *
+ * Endpoints are matched by label + id, mirroring `fallbackRelationshipInserts`:
+ * an unlabelled `MATCH (a), (b)` is a cartesian product over the whole graph
+ * and does not finish on a real index. An endpoint the load did not restore
+ * simply matches nothing, so the edge is dropped rather than mis-attached.
+ */
+export const restoreDerivedRels = async (rels) => {
+    const c = conn;
+    if (!c) {
+        throw new Error('LadybugDB not initialized. Call initLbug first.');
+    }
+    if (rels.length === 0)
+        return;
+    const escapeLabel = (label) => BACKTICK_TABLES.has(label) ? `\`${label}\`` : label;
+    // No outer `withConnLock`: `queryAndDrain` takes the lock per statement, and
+    // wrapping the loop as well trips the re-entry guard in conn-lock.ts. Same
+    // shape as `fallbackRelationshipInserts`, the other per-edge CREATE loop.
+    for (const rel of rels) {
+        if (!NODE_TABLES.includes(rel.sourceLabel))
+            continue;
+        if (!NODE_TABLES.includes(rel.targetLabel))
+            continue;
+        await queryAndDrain(c, `MATCH (a:${escapeLabel(rel.sourceLabel)} {id: ${formatCypherValue(rel.sourceId)}}), ` +
+            `(b:${escapeLabel(rel.targetLabel)} {id: ${formatCypherValue(rel.targetId)}}) ` +
+            `CREATE (a)-[:${REL_TABLE_NAME} {type: ${formatCypherValue(rel.type)}, ` +
+            `confidence: ${rel.confidence}, reason: ${formatCypherValue(rel.reason)}, ` +
+            `step: ${rel.step}}]->(b)`);
+    }
+};
 export const getEmbeddingTableName = () => EMBEDDING_TABLE_NAME;
 /**
  * Return the distinct repo-relative paths of files that import

package/dist/core/run-analyze.js

@@ -21,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';
@@ -43,6 +43,8 @@ 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, listWorkingTreeDirtyPaths, resolveRepoIdentityRoot, } from '../storage/git.js';
@@ -1306,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;
@@ -1345,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...');
@@ -1394,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
@@ -1592,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
@@ -1854,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:
@@ -2054,7 +2103,53 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
                 // the snapshot type exists to enforce.
                 if (buildPath === lbugPath)
                     liveIndexMutationStarted = true;
-                await dropSearchFTSIndexes(indexCatalogRows);
+                // 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
@@ -2068,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
@@ -2075,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
@@ -2125,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,
@@ -2138,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
@@ -2189,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,
@@ -2833,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: {
@@ -3044,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,

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/types/pipeline.d.ts

@@ -13,6 +13,18 @@ export interface PipelineResult {
     totalFileCount: number;
     communityResult?: CommunityDetectionResult;
     processResult?: ProcessDetectionResult;
+    /**
+     * Runs the community/process phases that `skipDerivedGraphPhases` held back
+     * (#3016), against the same graph and phase outputs the pipeline already
+     * produced, and populates `communityResult`/`processResult` on this object.
+     *
+     * Present ONLY when those phases were skipped for that reason, so a caller
+     * that optimistically skipped them can still get a byte-identical derived
+     * layer on the paths that turn out to need one (full rebuild, escalated
+     * write, or an incremental run with deleted files). Absent means the phases
+     * either already ran or were disabled for an unrelated reason.
+     */
+    runDeferredDerivedPhases?: () => Promise<void>;
     /**
      * Additive diagnostics for registry-primary resolution decisions that
      * deliberately suppress edge emission. Empty means no diagnostic was

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.11-rc.13",
+  "version": "1.6.11-rc.14",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",