gitnexus 1.6.11-rc.13 → 1.6.11-rc.15

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/parse-impl.js

@@ -17,7 +17,7 @@
 import { BindingAccumulator, enrichExportedTypeMap, } from '../binding-accumulator.js';
 import { mergeChunkResults, dispatchChunkParse } from '../parsing-processor.js';
 import { fileContentHash, computeChunkHash, loadParseCacheChunk, persistParseCacheChunk, PARSE_CACHE_VERSION, packParseCacheChunks, } from '../../../storage/parse-cache.js';
-import { clearParsedFileStore, persistParsedFileChunk, loadParsedFilesForPaths, getDurableParsedFileDir, loadDurableParsedFileIndex, prepareDurableParsedFileChunk, restoreDurableParsedFileShard, } from '../../../storage/parsedfile-store.js';
+import { clearParsedFileStore, persistParsedFileChunk, loadParsedFilesForPaths, getDurableParsedFileDir, loadDurableParsedFileIndex, prepareDurableParsedFileChunk, durableChunkHasShards, } from '../../../storage/parsedfile-store.js';
 import { DEFAULT_PDG_MAX_FUNCTION_LINES } from '../cfg/collect.js';
 import { processRoutesFromExtracted, resolveRouteHandlerSymbols, buildExportedTypeMapFromGraph, } from '../call-processor.js';
 import { createSemanticModel } from '../model/index.js';
@@ -547,13 +547,13 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
     // a sibling of the run-scoped store, NOT cleared per run. Workers write a
     // shard per chunk hash; on a warm parse-cache hit we restore the chunk's
     // shards into the run-scoped store so scope-resolution streams them without
-    // re-parsing. `durableHitKeys` is the prior run's index, version-gated by
-    // PARSE_CACHE_VERSION (a mismatch ⇒ empty ⇒ every chunk re-dispatches, which
-    // repopulates the durable store — never the main-thread extract fallback).
+    // re-parsing. `durableHitEntries` is the prior run's path-coverage index,
+    // version-gated by PARSE_CACHE_VERSION (a mismatch ⇒ empty ⇒ every chunk
+    // re-dispatches, which repopulates the durable store).
     const durableParsedFileDir = parsedFileStorePath !== undefined ? getDurableParsedFileDir(parsedFileStorePath) : undefined;
-    const durableHitKeys = durableParsedFileDir !== undefined
+    const durableHitEntries = durableParsedFileDir !== undefined
         ? await loadDurableParsedFileIndex(durableParsedFileDir, PARSE_CACHE_VERSION)
-        : new Set();
+        : new Map();
     let chunkCacheHits = 0;
     let chunkCacheMisses = 0;
     let reparsedFileCount = 0;
@@ -607,7 +607,11 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
                 }
                 if (chunkWorkerData.parsedFiles?.length) {
                     if (parsedFileStorePath) {
-                        await persistParsedFileChunk(parsedFileStorePath, `chunk-${chunkIdx}`, chunkWorkerData.parsedFiles);
+                        const wrote = await persistParsedFileChunk(parsedFileStorePath, `chunk-${chunkIdx}`, chunkWorkerData.parsedFiles);
+                        if (!wrote) {
+                            for (const item of chunkWorkerData.parsedFiles)
+                                allParsedFiles.push(item);
+                        }
                     }
                     else {
                         for (const item of chunkWorkerData.parsedFiles)
@@ -794,7 +798,14 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
             // store was introduced, or a pruned/version-stale shard — fall through to
             // a worker re-dispatch to repopulate them. NEVER let scope-resolution
             // re-extract on the main thread (the #1983 OOM the durable store closes).
-            const durableHit = chunkHash !== null && durableParsedFileDir !== undefined && durableHitKeys.has(chunkHash);
+            const durableExpectedPaths = chunkHash === null ? undefined : durableHitEntries.get(chunkHash);
+            const durableHit = cachedRaw !== undefined &&
+                cachedRaw.length > 0 &&
+                chunkHash !== null &&
+                durableParsedFileDir !== undefined &&
+                parsedFileStorePath !== undefined &&
+                durableExpectedPaths !== undefined &&
+                (await durableChunkHasShards(parsedFileStorePath, chunkHash, durableExpectedPaths));
             if (cachedRaw && cachedRaw.length > 0 && (durableHit || parsedFileStorePath === undefined)) {
                 // Cache hit: replay cached worker output. Finalize any parked worker
                 // chunk FIRST so deferred aggregation stays in chunk order, then merge
@@ -824,16 +835,8 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
                         nodesCreated: graph.nodeCount,
                     },
                 });
-                // Restore the chunk's durable ParsedFile shards into the run-scoped
-                // store so scope-resolution finds full coverage with ZERO main-thread
-                // re-parse. A verbatim byte copy — byte-identical to a cold run.
-                if (durableHit && durableParsedFileDir && parsedFileStorePath && chunkHash) {
-                    const restored = await restoreDurableParsedFileShard(durableParsedFileDir, parsedFileStorePath, chunkHash);
-                    if (restored === 0) {
-                        logger.warn(`parsedfile-cache: durable shards missing for cached chunk ` +
-                            `${chunkHash.slice(0, 8)} — scope-resolution will re-extract these files`);
-                    }
-                }
+                // The durable gate already snapshotted warm `.v8` shards into the
+                // run-scoped store for scope resolution.
                 await applyChunkResults(chunkWorkerData, chunkIdx, chunkFiles, chunkStartMs);
             }
             else {

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/ingestion/workers/parse-worker.js

@@ -2469,8 +2469,10 @@ parentPort.on('message', (msg) => {
                     persistDurableParsedFileShardSync(DURABLE_PARSED_FILE_STORAGE_PATH, msg.chunkHash, threadId, seq, accumulated.parsedFiles);
                 }
                 if (PARSED_FILE_STORE_STORAGE_PATH) {
-                    persistParsedFileShardSync(PARSED_FILE_STORE_STORAGE_PATH, `w${threadId}-${seq}`, accumulated.parsedFiles);
-                    accumulated.parsedFiles = [];
+                    const wrote = persistParsedFileShardSync(PARSED_FILE_STORE_STORAGE_PATH, `w${threadId}-${seq}`, accumulated.parsedFiles);
+                    if (wrote) {
+                        accumulated.parsedFiles = [];
+                    }
                 }
             }
             postResultCloneSafe(accumulated);

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