gitnexus 1.6.5-rc.2 → 1.6.5-rc.21

package/dist/core/group/extractors/grpc-extractor.js

@@ -3,6 +3,7 @@ import { glob } from 'glob';
 import Parser from 'tree-sitter';
 import { createIgnoreFilter } from '../../../config/ignore-service.js';
 import { readSafe } from './fs-utils.js';
+import { parseSourceSafe } from '../../tree-sitter/safe-parse.js';
 import { logger } from '../../logger.js';
 import { GRPC_SCAN_GLOB, getPluginForFile, hasProtoPlugin, } from './grpc-patterns/index.js';
 /**
@@ -352,7 +353,7 @@ export class GrpcExtractor {
             let detections = [];
             try {
                 parser.setLanguage(plugin.language);
-                const tree = parser.parse(content);
+                const tree = parseSourceSafe(parser, content);
                 detections = plugin.scan(tree);
             }
             catch {

package/dist/core/group/extractors/http-patterns/python.js

@@ -5,6 +5,7 @@ import { compilePatterns, runCompiledPatterns, unquoteLiteral, } from '../tree-s
  *   - FastAPI `@app.get("/path")` provider decorators
  *   - `requests.get/post/...("url")` consumer calls
  *   - Generic `requests.request("METHOD", "url")` consumer calls
+ *   - `httpx.AsyncClient` instances calling `.get/.post/...("url")`
  */
 const FASTAPI_VERBS = {
     get: 'GET',
@@ -65,11 +66,142 @@ const REQUESTS_GENERIC_PATTERNS = compilePatterns({
         },
     ],
 });
+// ─── Consumer: httpx.AsyncClient assignments ────────────────────────
+// NOTE: This targeted detector only tracks explicit `httpx.AsyncClient(...)`
+// construction. Direct imports (`from httpx import AsyncClient`) and module
+// aliases (`import httpx as hx`) and annotated assignments (`client: httpx.AsyncClient = ...`)
+// are intentionally left for a follow-up. Module-scope clients are only matched
+// at module scope; calls inside functions require a function/class-local tracked
+// client to avoid false positives from same-name local variables.
+const HTTPX_ASYNC_CLIENT_ASSIGN_PATTERNS = compilePatterns({
+    name: 'python-httpx-async-client-assign',
+    language: Python,
+    patterns: [
+        {
+            meta: {},
+            query: `
+        (assignment
+          left: (_) @client
+          right: (call
+            function: (attribute
+              object: (identifier) @module (#eq? @module "httpx")
+              attribute: (identifier) @client_class (#eq? @client_class "AsyncClient"))))
+      `,
+        },
+    ],
+});
+// ─── Consumer: async with httpx.AsyncClient() as client ──────────────
+const HTTPX_ASYNC_CLIENT_WITH_ALIAS_PATTERNS = compilePatterns({
+    name: 'python-httpx-async-client-with-alias',
+    language: Python,
+    patterns: [
+        {
+            meta: {},
+            query: `
+        (as_pattern
+          (call
+            function: (attribute
+              object: (identifier) @module (#eq? @module "httpx")
+              attribute: (identifier) @client_class (#eq? @client_class "AsyncClient")))
+          (as_pattern_target (identifier) @client))
+      `,
+        },
+    ],
+});
+function getScopeKey(node, preferClass = false) {
+    if (preferClass) {
+        let current = node;
+        while (current) {
+            if (current.type === 'class_definition') {
+                return `class:${current.startIndex}:${current.endIndex}`;
+            }
+            current = current.parent;
+        }
+    }
+    let current = node;
+    while (current) {
+        if (current.type === 'function_definition') {
+            return `function:${current.startIndex}:${current.endIndex}`;
+        }
+        current = current.parent;
+    }
+    return 'module';
+}
+function trackedClientScopeKey(clientNode) {
+    return getScopeKey(clientNode.parent, clientNode.text.includes('.'));
+}
+function callScopeKeys(clientNode) {
+    const keys = new Set();
+    const preferClass = clientNode.text.includes('.');
+    const nearestScope = getScopeKey(clientNode.parent, preferClass);
+    keys.add(nearestScope);
+    return [...keys];
+}
+function collectHttpxAsyncClients(tree) {
+    const clients = new Map();
+    const addClient = (clientNode) => {
+        if (!clientNode)
+            return;
+        const scopeKey = trackedClientScopeKey(clientNode);
+        const clientText = clientNode.text;
+        const scopes = clients.get(clientText) ?? new Set();
+        scopes.add(scopeKey);
+        clients.set(clientText, scopes);
+    };
+    for (const match of runCompiledPatterns(HTTPX_ASYNC_CLIENT_ASSIGN_PATTERNS, tree)) {
+        addClient(match.captures.client);
+    }
+    for (const match of runCompiledPatterns(HTTPX_ASYNC_CLIENT_WITH_ALIAS_PATTERNS, tree)) {
+        addClient(match.captures.client);
+    }
+    return clients;
+}
+function hasTrackedHttpxAsyncClient(clients, clientNode) {
+    const scopes = clients.get(clientNode.text);
+    if (!scopes)
+        return false;
+    return callScopeKeys(clientNode).some((scopeKey) => scopes.has(scopeKey));
+}
+// ─── Consumer: httpx AsyncClient .get/.post/...("url") ──────────────
+const HTTPX_ASYNC_CLIENT_VERB_PATTERNS = compilePatterns({
+    name: 'python-httpx-async-client-verb',
+    language: Python,
+    patterns: [
+        {
+            meta: {},
+            query: `
+        (call
+          function: (attribute
+            object: (_) @client
+            attribute: (identifier) @method (#match? @method "^(get|post|put|delete|patch)$"))
+          arguments: (argument_list . (string) @path))
+      `,
+        },
+    ],
+});
+// ─── Consumer: httpx AsyncClient .request("METHOD", "url") ─────────
+const HTTPX_ASYNC_CLIENT_GENERIC_PATTERNS = compilePatterns({
+    name: 'python-httpx-async-client-generic',
+    language: Python,
+    patterns: [
+        {
+            meta: {},
+            query: `
+        (call
+          function: (attribute
+            object: (_) @client
+            attribute: (identifier) @method (#eq? @method "request"))
+          arguments: (argument_list . (string) @http_method (string) @path))
+      `,
+        },
+    ],
+});
 export const PYTHON_HTTP_PLUGIN = {
     name: 'python-http',
     language: Python,
     scan(tree) {
         const out = [];
+        const httpxAsyncClients = collectHttpxAsyncClients(tree);
         // Providers: FastAPI
         for (const match of runCompiledPatterns(FASTAPI_PATTERNS, tree)) {
             const methodNode = match.captures.method;
@@ -128,6 +260,49 @@ export const PYTHON_HTTP_PLUGIN = {
                 confidence: 0.7,
             });
         }
+        // Consumers: httpx.AsyncClient.<verb>("url")
+        for (const match of runCompiledPatterns(HTTPX_ASYNC_CLIENT_VERB_PATTERNS, tree)) {
+            const clientNode = match.captures.client;
+            const methodNode = match.captures.method;
+            const pathNode = match.captures.path;
+            if (!clientNode || !methodNode || !pathNode)
+                continue;
+            if (!hasTrackedHttpxAsyncClient(httpxAsyncClients, clientNode))
+                continue;
+            const path = unquoteLiteral(pathNode.text);
+            if (path === null)
+                continue;
+            out.push({
+                role: 'consumer',
+                framework: 'python-httpx',
+                method: methodNode.text.toUpperCase(),
+                path,
+                name: null,
+                confidence: 0.7,
+            });
+        }
+        // Consumers: httpx.AsyncClient.request("METHOD", "url")
+        for (const match of runCompiledPatterns(HTTPX_ASYNC_CLIENT_GENERIC_PATTERNS, tree)) {
+            const clientNode = match.captures.client;
+            const methodNode = match.captures.http_method;
+            const pathNode = match.captures.path;
+            if (!clientNode || !methodNode || !pathNode)
+                continue;
+            if (!hasTrackedHttpxAsyncClient(httpxAsyncClients, clientNode))
+                continue;
+            const methodRaw = unquoteLiteral(methodNode.text);
+            const path = unquoteLiteral(pathNode.text);
+            if (methodRaw === null || path === null)
+                continue;
+            out.push({
+                role: 'consumer',
+                framework: 'python-httpx',
+                method: methodRaw.toUpperCase(),
+                path,
+                name: null,
+                confidence: 0.7,
+            });
+        }
         return out;
     },
 };

package/dist/core/group/extractors/http-route-extractor.js

@@ -3,6 +3,7 @@ import { glob } from 'glob';
 import Parser from 'tree-sitter';
 import { createIgnoreFilter } from '../../../config/ignore-service.js';
 import { readSafe } from './fs-utils.js';
+import { parseSourceSafe } from '../../tree-sitter/safe-parse.js';
 import { getPluginForFile, HTTP_SCAN_GLOB } from './http-patterns/index.js';
 /**
  * Language-agnostic orchestrator for HTTP route (provider + consumer)
@@ -154,7 +155,7 @@ export class HttpRouteExtractor {
             }
             try {
                 parser.setLanguage(plugin.language);
-                const tree = parser.parse(content);
+                const tree = parseSourceSafe(parser, content);
                 const detections = plugin.scan(tree);
                 cachedDetections.set(rel, detections);
                 return detections;

package/dist/core/group/extractors/include-extractor.js

@@ -8,6 +8,7 @@ import { readSafe } from './fs-utils.js';
 import { buildSuffixIndex } from '../../ingestion/import-resolvers/utils.js';
 import { createIgnoreFilter } from '../../../config/ignore-service.js';
 import { getMaxFileSizeBytes } from '../../ingestion/utils/max-file-size.js';
+import { parseSourceSafe } from '../../tree-sitter/safe-parse.js';
 import { logger } from '../../logger.js';
 /**
  * Cross-repo C/C++ `#include` dependency extractor.
@@ -457,7 +458,7 @@ export class IncludeExtractor {
             let extractionSource;
             try {
                 parser.setLanguage(lang);
-                const tree = parser.parse(content);
+                const tree = parseSourceSafe(parser, content);
                 let matches;
                 try {
                     matches = query.matches(tree.rootNode);

package/dist/core/group/extractors/thrift-extractor.js

@@ -1,6 +1,7 @@
 import { glob } from 'glob';
 import Parser from 'tree-sitter';
 import { readSafe } from './fs-utils.js';
+import { parseSourceSafe } from '../../tree-sitter/safe-parse.js';
 import { getPluginForFile, THRIFT_SCAN_GLOB, } from './thrift-patterns/index.js';
 function normalizeThriftPath(rel) {
     return rel.replace(/\\/g, '/');
@@ -228,7 +229,7 @@ export class ThriftExtractor {
             let detections = [];
             try {
                 parser.setLanguage(plugin.language);
-                const tree = parser.parse(content);
+                const tree = parseSourceSafe(parser, content);
                 detections = plugin.scan(tree);
             }
             catch {

package/dist/core/group/extractors/tree-sitter-scanner.js

@@ -1,4 +1,5 @@
 import Parser from 'tree-sitter';
+import { parseSourceSafe } from '../../tree-sitter/safe-parse.js';
 /**
  * Compile a LanguagePatterns bundle. Call this once per plugin, at
  * module load time, and export the result. Throws if any pattern
@@ -60,7 +61,7 @@ export function scanFile(parser, plugin, content) {
     let tree;
     try {
         parser.setLanguage(plugin.language);
-        tree = parser.parse(content);
+        tree = parseSourceSafe(parser, content);
     }
     catch {
         return [];

package/dist/core/incremental/shadow-candidates.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Shadow-candidate path derivation for incremental indexing.
+ *
+ * Background — Bugbot review on PR #1479:
+ *   queryImporters() on a NEWLY ADDED file returns 0 importers in the
+ *   pre-pipeline DB, because the new file's IMPORTS rows haven't been
+ *   written yet. But pre-existing files may have IMPORTS edges that
+ *   *resolved to a sibling path*, and the newcomer can now steal that
+ *   resolution under standard JS/TS module-resolution rules. Without
+ *   pulling those pre-existing files into the writable set, their
+ *   stale CALLS edges remain pointing at the OLD resolution target.
+ *
+ * Given an added file path, this helper enumerates the pre-existing
+ * file paths whose import-resolution claim the newcomer can steal.
+ * Caller filters the candidates against the prior-run `fileHashes`
+ * map so we only query importers of paths that actually existed.
+ *
+ * Shadow patterns covered (resolution-priority-aware):
+ *
+ *   (a) Same basename, different extension —
+ *       added `foo/bar.ts` shadows `foo/bar.{tsx,js,jsx,mjs,cjs,d.ts}`.
+ *   (b) Bare-file beats directory-style index —
+ *       added `foo/bar.ts` shadows `foo/bar/index.{ts,tsx,...}`.
+ *   (c) Directory-index beats bare-file —
+ *       added `foo/index.ts` shadows `foo.{ts,tsx,...}` (rare but real,
+ *       e.g. converting a single-file module into a directory module).
+ *
+ * Resolution-order priority is conservatively wide: we enumerate ALL
+ * common extensions because we don't know which the importer actually
+ * specified, and over-seeding is harmless (extra BFS work, but the
+ * subgraph extract still gates write-back by file membership).
+ *
+ * Cross-platform path separators: candidates are emitted with both `/`
+ * and `\` for shadow pattern (b), since the caller's prior fileHashes
+ * map may use either depending on the OS that wrote it.
+ */
+/**
+ * Enumerate pre-existing paths whose import-resolution `added` can steal.
+ *
+ * @param added — repo-relative path of a newly-added file
+ * @returns deduplicated list of candidate paths (NOT filtered against
+ *          any known-files set — caller does that)
+ */
+export declare const shadowCandidatesFor: (added: string) => string[];

package/dist/core/incremental/shadow-candidates.js

@@ -0,0 +1,74 @@
+/**
+ * Shadow-candidate path derivation for incremental indexing.
+ *
+ * Background — Bugbot review on PR #1479:
+ *   queryImporters() on a NEWLY ADDED file returns 0 importers in the
+ *   pre-pipeline DB, because the new file's IMPORTS rows haven't been
+ *   written yet. But pre-existing files may have IMPORTS edges that
+ *   *resolved to a sibling path*, and the newcomer can now steal that
+ *   resolution under standard JS/TS module-resolution rules. Without
+ *   pulling those pre-existing files into the writable set, their
+ *   stale CALLS edges remain pointing at the OLD resolution target.
+ *
+ * Given an added file path, this helper enumerates the pre-existing
+ * file paths whose import-resolution claim the newcomer can steal.
+ * Caller filters the candidates against the prior-run `fileHashes`
+ * map so we only query importers of paths that actually existed.
+ *
+ * Shadow patterns covered (resolution-priority-aware):
+ *
+ *   (a) Same basename, different extension —
+ *       added `foo/bar.ts` shadows `foo/bar.{tsx,js,jsx,mjs,cjs,d.ts}`.
+ *   (b) Bare-file beats directory-style index —
+ *       added `foo/bar.ts` shadows `foo/bar/index.{ts,tsx,...}`.
+ *   (c) Directory-index beats bare-file —
+ *       added `foo/index.ts` shadows `foo.{ts,tsx,...}` (rare but real,
+ *       e.g. converting a single-file module into a directory module).
+ *
+ * Resolution-order priority is conservatively wide: we enumerate ALL
+ * common extensions because we don't know which the importer actually
+ * specified, and over-seeding is harmless (extra BFS work, but the
+ * subgraph extract still gates write-back by file membership).
+ *
+ * Cross-platform path separators: candidates are emitted with both `/`
+ * and `\` for shadow pattern (b), since the caller's prior fileHashes
+ * map may use either depending on the OS that wrote it.
+ */
+const SHADOW_EXTS = ['.d.ts', '.tsx', '.ts', '.jsx', '.js', '.mjs', '.cjs'];
+/**
+ * Enumerate pre-existing paths whose import-resolution `added` can steal.
+ *
+ * @param added — repo-relative path of a newly-added file
+ * @returns deduplicated list of candidate paths (NOT filtered against
+ *          any known-files set — caller does that)
+ */
+export const shadowCandidatesFor = (added) => {
+    const ext = SHADOW_EXTS.find((e) => added.endsWith(e));
+    if (!ext)
+        return [];
+    const noExt = added.slice(0, -ext.length);
+    const out = new Set();
+    // (a) Same basename, different extension.
+    for (const alt of SHADOW_EXTS) {
+        if (alt !== ext)
+            out.add(noExt + alt);
+    }
+    // (b) Bare file beats sibling directory-style index.
+    for (const idx of SHADOW_EXTS) {
+        out.add(`${noExt}/index${idx}`);
+        out.add(`${noExt}\\index${idx}`);
+    }
+    // (c) New `foo/index.ext` shadows old `foo.ext`.
+    const idxSuffixSlash = '/index';
+    const idxSuffixBack = '\\index';
+    let dir = null;
+    if (noExt.endsWith(idxSuffixSlash))
+        dir = noExt.slice(0, -idxSuffixSlash.length);
+    else if (noExt.endsWith(idxSuffixBack))
+        dir = noExt.slice(0, -idxSuffixBack.length);
+    if (dir !== null) {
+        for (const alt of SHADOW_EXTS)
+            out.add(dir + alt);
+    }
+    return [...out];
+};

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

@@ -0,0 +1,64 @@
+/**
+ * Subgraph extraction for incremental DB writeback.
+ *
+ * Given the FULL ctx.graph produced by the pipeline (all files parsed,
+ * all phases run) and the set of file paths whose DB rows must be
+ * replaced, produce a smaller KnowledgeGraph that contains:
+ *
+ *   - Every node whose `properties.filePath` is in `toWriteSet`.
+ *   - Every graph-wide node (Community, Process) — these are regenerated
+ *     each run by the communities/processes phases and must be fully
+ *     rewritten.
+ *   - 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
+ *     them would PK-conflict at COPY time.
+ *
+ * The resulting subgraph is what gets passed to `loadGraphToLbug` after
+ * the orchestrator has deleted the corresponding DB rows. Hydrated
+ * unchanged-file rows are never touched in the DB.
+ *
+ * # Cross-file edge consistency (Finding 1)
+ *
+ * `extractChangedSubgraph` intentionally does NOT expand the set it is
+ * given — expansion is the orchestrator's job, so the SAME expanded set
+ * can be fed to both `deleteNodesForFile` and this function (asymmetry
+ * between the delete set and the write set silently corrupts the DB).
+ * `computeEffectiveWriteSet` below performs the boundary-crossing 1-hop
+ * walk; the orchestrator composes it with its importer-BFS expansion and
+ * passes the result here.
+ *
+ * Why the 1-hop walk is needed: consider a barrel re-export change —
+ * file C (a barrel) shifts `export { foo } from './b'` to
+ * `export { foo } from './d'`. After scope resolution, file A's CALLS
+ * edge to `foo` resolves to D instead of B, even though A's content is
+ * byte-for-byte identical:
+ *
+ *   - Old A→B edge survives in DB (neither A nor B is changed → not deleted)
+ *   - New A→D edge is missing (neither A nor D in writable set → skipped)
+ *
+ * Pulling the unchanged-side file of every writable-boundary-crossing
+ * edge into the write set fixes both halves: the orchestrator's
+ * `DETACH DELETE` cleans up the stale unchanged-side rows, and the new
+ * cross-file edges land because at least one endpoint is now writable.
+ *
+ * Limitation (documented): if a file X *stopped* importing from a
+ * changed file C, X has no edge to C in the new graph, so this 1-hop
+ * walk doesn't catch it. The orchestrator's importer-BFS (which reads
+ * 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;
+/**
+ * Public — derive the EFFECTIVE write-set: `toWriteSet` expanded by one
+ * hop along every edge in the new graph that crosses the writable
+ * boundary (one endpoint in a writable file, the other in an unchanged
+ * file). The unchanged-side file is pulled in so its stale rows are
+ * deleted + rewritten in lockstep with the changed side.
+ *
+ * Single pass over the edge list. Does NOT mutate `toWriteSet`. The
+ * orchestrator MUST feed the returned set to both `deleteNodesForFile`
+ * and `extractChangedSubgraph` — feeding the unexpanded set to either
+ * one leaves stale rows or PK-conflicts at COPY time.
+ */
+export declare const computeEffectiveWriteSet: (fullGraph: KnowledgeGraph, toWriteSet: ReadonlySet<string>) => Set<string>;

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

@@ -0,0 +1,111 @@
+/**
+ * Subgraph extraction for incremental DB writeback.
+ *
+ * Given the FULL ctx.graph produced by the pipeline (all files parsed,
+ * all phases run) and the set of file paths whose DB rows must be
+ * replaced, produce a smaller KnowledgeGraph that contains:
+ *
+ *   - Every node whose `properties.filePath` is in `toWriteSet`.
+ *   - Every graph-wide node (Community, Process) — these are regenerated
+ *     each run by the communities/processes phases and must be fully
+ *     rewritten.
+ *   - 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
+ *     them would PK-conflict at COPY time.
+ *
+ * The resulting subgraph is what gets passed to `loadGraphToLbug` after
+ * the orchestrator has deleted the corresponding DB rows. Hydrated
+ * unchanged-file rows are never touched in the DB.
+ *
+ * # Cross-file edge consistency (Finding 1)
+ *
+ * `extractChangedSubgraph` intentionally does NOT expand the set it is
+ * given — expansion is the orchestrator's job, so the SAME expanded set
+ * can be fed to both `deleteNodesForFile` and this function (asymmetry
+ * between the delete set and the write set silently corrupts the DB).
+ * `computeEffectiveWriteSet` below performs the boundary-crossing 1-hop
+ * walk; the orchestrator composes it with its importer-BFS expansion and
+ * passes the result here.
+ *
+ * Why the 1-hop walk is needed: consider a barrel re-export change —
+ * file C (a barrel) shifts `export { foo } from './b'` to
+ * `export { foo } from './d'`. After scope resolution, file A's CALLS
+ * edge to `foo` resolves to D instead of B, even though A's content is
+ * byte-for-byte identical:
+ *
+ *   - Old A→B edge survives in DB (neither A nor B is changed → not deleted)
+ *   - New A→D edge is missing (neither A nor D in writable set → skipped)
+ *
+ * Pulling the unchanged-side file of every writable-boundary-crossing
+ * edge into the write set fixes both halves: the orchestrator's
+ * `DETACH DELETE` cleans up the stale unchanged-side rows, and the new
+ * cross-file edges land because at least one endpoint is now writable.
+ *
+ * Limitation (documented): if a file X *stopped* importing from a
+ * changed file C, X has no edge to C in the new graph, so this 1-hop
+ * walk doesn't catch it. The orchestrator's importer-BFS (which reads
+ * IMPORTS from the pre-pipeline DB) covers that case instead.
+ */
+import { createKnowledgeGraph } from '../graph/graph.js';
+const isGraphWide = (label) => label === 'Community' || label === 'Process';
+/**
+ * Build a Map<nodeId, filePath> for every File-bound node in the graph.
+ * Graph-wide nodes (Community/Process) have no filePath and are filtered.
+ */
+const indexNodeFilePaths = (fullGraph) => {
+    const idx = new Map();
+    fullGraph.forEachNode((n) => {
+        const fp = n.properties?.filePath;
+        if (fp)
+            idx.set(n.id, fp);
+    });
+    return idx;
+};
+export const extractChangedSubgraph = (fullGraph, toWriteSet) => {
+    const sub = createKnowledgeGraph();
+    const writableNodeIds = new Set();
+    fullGraph.forEachNode((n) => {
+        const filePath = n.properties?.filePath;
+        const include = (filePath && toWriteSet.has(filePath)) || isGraphWide(n.label);
+        if (include) {
+            sub.addNode(n);
+            writableNodeIds.add(n.id);
+        }
+    });
+    fullGraph.forEachRelationship((r) => {
+        if (writableNodeIds.has(r.sourceId) || writableNodeIds.has(r.targetId)) {
+            sub.addRelationship(r);
+        }
+    });
+    return sub;
+};
+/**
+ * Public — derive the EFFECTIVE write-set: `toWriteSet` expanded by one
+ * hop along every edge in the new graph that crosses the writable
+ * boundary (one endpoint in a writable file, the other in an unchanged
+ * file). The unchanged-side file is pulled in so its stale rows are
+ * deleted + rewritten in lockstep with the changed side.
+ *
+ * Single pass over the edge list. Does NOT mutate `toWriteSet`. The
+ * orchestrator MUST feed the returned set to both `deleteNodesForFile`
+ * and `extractChangedSubgraph` — feeding the unexpanded set to either
+ * one leaves stale rows or PK-conflicts at COPY time.
+ */
+export const computeEffectiveWriteSet = (fullGraph, toWriteSet) => {
+    const nodeFilePaths = indexNodeFilePaths(fullGraph);
+    const expanded = new Set(toWriteSet);
+    fullGraph.forEachRelationship((r) => {
+        const sourcePath = nodeFilePaths.get(r.sourceId);
+        const targetPath = nodeFilePaths.get(r.targetId);
+        if (!sourcePath || !targetPath)
+            return; // skip edges to graph-wide nodes
+        const sourceWritable = toWriteSet.has(sourcePath);
+        const targetWritable = toWriteSet.has(targetPath);
+        if (sourceWritable && !targetWritable)
+            expanded.add(targetPath);
+        else if (targetWritable && !sourceWritable)
+            expanded.add(sourcePath);
+    });
+    return expanded;
+};