gitnexus 1.6.10-rc.2 → 1.6.10-rc.21

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

@@ -1,6 +1,7 @@
 import Python from 'tree-sitter-python';
 import { compilePatterns, runCompiledPatterns, unquoteLiteral, } from '../tree-sitter-scanner.js';
 import { normalizeExtractedRoutePath } from '../../../ingestion/route-extractors/route-path.js';
+import { extractPythonModuleConstants, parseConstOperands, resolveOperands, } from '../../../ingestion/route-extractors/python-const-resolver.js';
 /**
  * Python HTTP plugin. Handles:
  *   - FastAPI `@app.get("/path")` provider decorators
@@ -67,6 +68,44 @@ const FASTAPI_ROUTER_PATTERNS = compilePatterns({
         },
     ],
 });
+// #2391: `@router.<verb>` / `@app.<verb>` whose first argument is a non-literal
+// path — a bare imported constant or a `+`-concatenation. The path is resolved
+// against the repo-wide constant map (parity with the ingestion side) and, on
+// failure, the route is skipped (no provider contract) exactly like ingestion.
+const FASTAPI_ROUTER_EXPR_PATTERNS = compilePatterns({
+    name: 'python-fastapi-router-expr',
+    language: Python,
+    patterns: [
+        {
+            meta: {},
+            query: `
+        (decorator
+          (call
+            function: (attribute
+              object: (identifier) @obj (#eq? @obj "router")
+              attribute: (identifier) @method (#match? @method "^(get|post|put|delete|patch)$"))
+            arguments: (argument_list . [(identifier) (binary_operator)] @path)))
+      `,
+        },
+    ],
+});
+const FASTAPI_APP_EXPR_PATTERNS = compilePatterns({
+    name: 'python-fastapi-app-expr',
+    language: Python,
+    patterns: [
+        {
+            meta: {},
+            query: `
+        (decorator
+          (call
+            function: (attribute
+              object: (identifier) @obj (#eq? @obj "app")
+              attribute: (identifier) @method (#match? @method "^(get|post|put|delete|patch)$"))
+            arguments: (argument_list . [(identifier) (binary_operator)] @path)))
+      `,
+        },
+    ],
+});
 // ─── Provider: Flask `app.add_url_rule('/path', view_func=handler)` ───
 // The imperative Flask route registration: unlike `@app.route` (whose handler
 // is the decorated function, same-file), `view_func` is frequently an IMPORTED
@@ -830,111 +869,153 @@ function recordPrefix(target, key, prefix) {
     set.add(prefix);
     target.set(key, set);
 }
+// Cheap cost-gate pre-filter: a `@router`/`@app.<verb>(` call whose first
+// argument is non-literal — either it STARTS with an identifier (a bare constant
+// or the head of `CONST + "/x"`), or it is a string-literal-LEADING concat
+// (`"/api" + SUFFIX`) detected by a `+` before the decorator's closing paren
+// (#2393). `[^)]*` spans the whole argument, including a Black-formatted concat
+// that wraps across lines, but stays bounded by the decorator's own `)`. Gating
+// the literal-leading case on the `+` (not merely a leading quote) keeps a plain
+// string route `@router.get("/x")` OFF the gate, so a literal-only repo pays no
+// parse pass. Deliberately loose — a false positive only costs a parse; a false
+// negative would silently drop the feature.
+const NONLITERAL_ROUTE_DECORATOR_RE = /@\s*(?:app|router)\s*\.\s*(?:get|post|put|delete|patch)\s*\(\s*(?:[A-Za-z_]|["'][^)]*\+)/;
 function buildPythonRepoContext(files, parser, readFile, parseSource) {
     const prefixesByLongKey = new Map();
     const prefixesByShortKey = new Map();
-    // Cross-file pre-pass: only `include_router` sites need it — they bind a
-    // prefix declared in one file to a router defined in another. Same-file
-    // `APIRouter(prefix=...)` is resolved in scan() from the file's own tree, so
-    // APIRouter-only files are left out here and never parsed twice.
+    // Single read pass (#2393): slurp every `.py` file's content ONCE. This used to
+    // be two passes — the include_router pre-pass below and the #2391 constant cost
+    // gate each re-read every `.py` file. The composed-route cost gate is computed
+    // in the same pass so a literal-only repo still does exactly one read and zero
+    // parses.
+    const pyContents = new Map();
+    let hasComposedRoute = false;
     for (const rel of files) {
         if (!rel.endsWith('.py'))
             continue;
         const src = readFile(rel);
         if (!src)
             continue;
-        if (!src.includes('include_router'))
+        pyContents.set(rel, src);
+        if (!hasComposedRoute && NONLITERAL_ROUTE_DECORATOR_RE.test(src))
+            hasComposedRoute = true;
+    }
+    // Single PARSE pass (#2391): parse each `.py` at most once and feed BOTH the
+    // include_router prefix pre-pass and the composed-constant map below. This used
+    // to be two loops, so an include_router file in a composed repo was parsed
+    // twice. A file that needs neither pass is not parsed at all (cost gates intact).
+    //
+    // Cross-file pre-pass: only `include_router` sites need it — they bind a prefix
+    // declared in one file to a router defined in another. Same-file
+    // `APIRouter(prefix=...)` is resolved in scan() from the file's own tree.
+    const constantsByFile = new Map();
+    for (const [rel, src] of pyContents) {
+        const needsRouter = src.includes('include_router');
+        if (!needsRouter && !hasComposedRoute)
             continue;
         parser.setLanguage(Python);
         const tree = parseSource(parser, src);
         if (!tree)
             continue;
-        const localNameToModule = new Map();
-        for (const m of runCompiledPatterns(FROM_IMPORT_ROUTER_PATTERNS, tree)) {
-            const moduleNode = m.captures.module;
-            const aliasNode = m.captures.alias;
-            const importedNode = m.captures.imported;
-            if (!moduleNode || !importedNode)
-                continue;
-            const localName = aliasNode?.text ?? importedNode.text;
-            const moduleShort = lastSegmentOfDotted(moduleNode.text);
-            if (!moduleShort)
-                continue;
-            const moduleLong = lastTwoSegmentsAsLongKey(moduleNode.text);
-            localNameToModule.set(localName, { moduleShort, moduleLong });
-        }
-        // Module-alias map: name imported from a multi-segment package →
-        // long key. Lets Shape A look up the precise file for `<name>.router`
-        // even when `<name>` collides with another package's basename.
-        const localNameToModuleAlias = new Map();
-        for (const m of runCompiledPatterns(FROM_IMPORT_MODULE_PATTERNS, tree)) {
-            const moduleNode = m.captures.module;
-            const importedNode = m.captures.imported;
-            const aliasNode = m.captures.alias;
-            if (!moduleNode || !importedNode)
-                continue;
-            // Skip the `router` shape — already handled by FROM_IMPORT_ROUTER_PATTERNS
-            // above and stored under its router-aware semantics.
-            if (importedNode.text === 'router')
-                continue;
-            const moduleLong = lastTwoSegmentsAsLongKey(`${moduleNode.text}.${importedNode.text}`);
-            if (!moduleLong)
-                continue;
-            const localName = aliasNode?.text ?? importedNode.text;
-            localNameToModuleAlias.set(localName, moduleLong);
-        }
-        // Shape A: `<host>.include_router(<module>.router, prefix='/x')`.
-        // The call site gives us only a short module name. We promote to a
-        // long key when the same file imports `<module>` via either
-        // `from <pkg> import <module>` (recorded in `localNameToModuleAlias`
-        // — the typical pattern) or, less commonly, a router-aware import
-        // statement. Only fall back to the basename short key when neither
-        // alias is available.
-        for (const m of runCompiledPatterns(INCLUDE_ROUTER_ATTR_PATTERNS, tree)) {
-            const modNode = m.captures.router_module;
-            const prefixNode = m.captures.prefix;
-            if (!modNode || !prefixNode)
-                continue;
-            const prefix = unquoteLiteral(prefixNode.text);
-            if (prefix === null)
-                continue;
-            const moduleShort = modNode.text;
-            const aliasLong = localNameToModuleAlias.get(moduleShort);
-            const sameFileImport = localNameToModule.get(moduleShort);
-            const longKey = aliasLong ?? sameFileImport?.moduleLong;
-            if (longKey) {
-                recordPrefix(prefixesByLongKey, longKey, prefix);
+        if (needsRouter) {
+            const localNameToModule = new Map();
+            for (const m of runCompiledPatterns(FROM_IMPORT_ROUTER_PATTERNS, tree)) {
+                const moduleNode = m.captures.module;
+                const aliasNode = m.captures.alias;
+                const importedNode = m.captures.imported;
+                if (!moduleNode || !importedNode)
+                    continue;
+                const localName = aliasNode?.text ?? importedNode.text;
+                const moduleShort = lastSegmentOfDotted(moduleNode.text);
+                if (!moduleShort)
+                    continue;
+                const moduleLong = lastTwoSegmentsAsLongKey(moduleNode.text);
+                localNameToModule.set(localName, { moduleShort, moduleLong });
             }
-            else {
-                recordPrefix(prefixesByShortKey, moduleShort, prefix);
+            // Module-alias map: name imported from a multi-segment package →
+            // long key. Lets Shape A look up the precise file for `<name>.router`
+            // even when `<name>` collides with another package's basename.
+            const localNameToModuleAlias = new Map();
+            for (const m of runCompiledPatterns(FROM_IMPORT_MODULE_PATTERNS, tree)) {
+                const moduleNode = m.captures.module;
+                const importedNode = m.captures.imported;
+                const aliasNode = m.captures.alias;
+                if (!moduleNode || !importedNode)
+                    continue;
+                // Skip the `router` shape — already handled by FROM_IMPORT_ROUTER_PATTERNS
+                // above and stored under its router-aware semantics.
+                if (importedNode.text === 'router')
+                    continue;
+                const moduleLong = lastTwoSegmentsAsLongKey(`${moduleNode.text}.${importedNode.text}`);
+                if (!moduleLong)
+                    continue;
+                const localName = aliasNode?.text ?? importedNode.text;
+                localNameToModuleAlias.set(localName, moduleLong);
             }
-        }
-        // Shape B: `<host>.include_router(my_router, prefix='/x')` — resolve
-        // `my_router` via the import map built above. Whenever the import
-        // statement supplied a multi-segment module path the long key is
-        // recorded, eliminating cross-package collisions.
-        for (const m of runCompiledPatterns(INCLUDE_ROUTER_NAME_PATTERNS, tree)) {
-            const nameNode = m.captures.router_name;
-            const prefixNode = m.captures.prefix;
-            if (!nameNode || !prefixNode)
-                continue;
-            const localImp = localNameToModule.get(nameNode.text);
-            if (!localImp)
-                continue;
-            const prefix = unquoteLiteral(prefixNode.text);
-            if (prefix === null)
-                continue;
-            if (localImp.moduleLong) {
-                recordPrefix(prefixesByLongKey, localImp.moduleLong, prefix);
+            // Shape A: `<host>.include_router(<module>.router, prefix='/x')`.
+            // The call site gives us only a short module name. We promote to a
+            // long key when the same file imports `<module>` via either
+            // `from <pkg> import <module>` (recorded in `localNameToModuleAlias`
+            // — the typical pattern) or, less commonly, a router-aware import
+            // statement. Only fall back to the basename short key when neither
+            // alias is available.
+            for (const m of runCompiledPatterns(INCLUDE_ROUTER_ATTR_PATTERNS, tree)) {
+                const modNode = m.captures.router_module;
+                const prefixNode = m.captures.prefix;
+                if (!modNode || !prefixNode)
+                    continue;
+                const prefix = unquoteLiteral(prefixNode.text);
+                if (prefix === null)
+                    continue;
+                const moduleShort = modNode.text;
+                const aliasLong = localNameToModuleAlias.get(moduleShort);
+                const sameFileImport = localNameToModule.get(moduleShort);
+                const longKey = aliasLong ?? sameFileImport?.moduleLong;
+                if (longKey) {
+                    recordPrefix(prefixesByLongKey, longKey, prefix);
+                }
+                else {
+                    recordPrefix(prefixesByShortKey, moduleShort, prefix);
+                }
             }
-            else {
-                recordPrefix(prefixesByShortKey, localImp.moduleShort, prefix);
+            // Shape B: `<host>.include_router(my_router, prefix='/x')` — resolve
+            // `my_router` via the import map built above. Whenever the import
+            // statement supplied a multi-segment module path the long key is
+            // recorded, eliminating cross-package collisions.
+            for (const m of runCompiledPatterns(INCLUDE_ROUTER_NAME_PATTERNS, tree)) {
+                const nameNode = m.captures.router_name;
+                const prefixNode = m.captures.prefix;
+                if (!nameNode || !prefixNode)
+                    continue;
+                const localImp = localNameToModule.get(nameNode.text);
+                if (!localImp)
+                    continue;
+                const prefix = unquoteLiteral(prefixNode.text);
+                if (prefix === null)
+                    continue;
+                if (localImp.moduleLong) {
+                    recordPrefix(prefixesByLongKey, localImp.moduleLong, prefix);
+                }
+                else {
+                    recordPrefix(prefixesByShortKey, localImp.moduleShort, prefix);
+                }
+            }
+        }
+        // #2391: build the repo-wide constant map for resolving non-literal decorator
+        // paths (KTD6 cost gate: only when `hasComposedRoute`). Parse EVERY `.py` so
+        // the resolvable set matches the ingestion aggregate (R4 parity) — a narrower
+        // set would return null where ingestion resolves.
+        if (hasComposedRoute) {
+            const mc = extractPythonModuleConstants(tree);
+            if (mc.literals.size > 0 || mc.exprs.size > 0 || mc.imports.size > 0) {
+                constantsByFile.set(rel, mc);
             }
         }
     }
     return {
         prefixesByLongKey,
         prefixesByShortKey,
+        constantsByFile,
     };
 }
 function joinPrefix(prefix, route) {
@@ -971,32 +1052,67 @@ export const PYTHON_HTTP_PLUGIN = {
         // statements, so an imperatively-registered handler (Flask `view_func`) that
         // is an imported (possibly aliased) symbol resolves to its real definition.
         const importMap = buildPythonImportMap(tree);
-        // Providers: FastAPI @app.<verb>("/path") — already absolute path.
-        for (const match of runCompiledPatterns(FASTAPI_APP_PATTERNS, tree)) {
-            const methodNode = match.captures.method;
-            const pathNode = match.captures.path;
-            if (!methodNode || !pathNode)
-                continue;
-            const httpMethod = FASTAPI_VERBS[methodNode.text];
-            if (!httpMethod)
-                continue;
-            const path = unquoteLiteral(pathNode.text);
-            if (path === null)
-                continue;
+        // #2391: fold a non-literal decorator argument (bare constant or
+        // `+`-concatenation) to its literal path against the repo constant map, or
+        // `null` → skip (the same floor the ingestion side applies, so provider
+        // contracts and graph Route nodes agree on both resolved and dropped routes).
+        const resolveExprArg = (argNode) => {
+            const cbf = ctx?.constantsByFile;
+            if (!cbf || !fileRel)
+                return null;
+            // Build an operand list and fold via `resolveOperands` — the SAME entry the
+            // ingestion side uses (parse-impl folds `routePathOperands`). Using the
+            // by-name `resolveConstant` here would enter `foldName` one depth shallower,
+            // so at the MAX_RESOLVE_DEPTH boundary the group would resolve a chain
+            // ingestion drops, breaking R4 parity (#2393).
+            const operands = argNode.type === 'identifier'
+                ? [{ kind: 'ref', name: argNode.text }]
+                : parseConstOperands(argNode);
+            return operands ? resolveOperands(fileRel, operands, cbf) : null;
+        };
+        const emitAppProvider = (httpMethod, pathVal, line) => {
             out.push({
                 role: 'provider',
                 framework: 'fastapi',
                 method: httpMethod,
-                path,
+                path: pathVal,
                 name: null,
                 // The decorated handler has no captured name → resolve by line-span
                 // containment. Best-effort fallback: FastAPI routes are graph-backed
                 // (ingestion decorator routes) and the function span starts at `def`
                 // (decorators excluded), so this lands the single-decorator case and
                 // degrades to file-level for multi-decorator stacks.
-                line: pathNode.startPosition.row + 1,
+                line,
                 confidence: 0.8,
             });
+        };
+        // Providers: FastAPI @app.<verb>("/path") — already absolute path.
+        for (const match of runCompiledPatterns(FASTAPI_APP_PATTERNS, tree)) {
+            const methodNode = match.captures.method;
+            const pathNode = match.captures.path;
+            if (!methodNode || !pathNode)
+                continue;
+            const httpMethod = FASTAPI_VERBS[methodNode.text];
+            if (!httpMethod)
+                continue;
+            const path = unquoteLiteral(pathNode.text);
+            if (path === null)
+                continue;
+            emitAppProvider(httpMethod, path, pathNode.startPosition.row + 1);
+        }
+        // Providers: FastAPI @app.<verb>(CONST | A + "/x") — resolved composed path.
+        for (const match of runCompiledPatterns(FASTAPI_APP_EXPR_PATTERNS, tree)) {
+            const methodNode = match.captures.method;
+            const pathNode = match.captures.path;
+            if (!methodNode || !pathNode)
+                continue;
+            const httpMethod = FASTAPI_VERBS[methodNode.text];
+            if (!httpMethod)
+                continue;
+            const resolved = resolveExprArg(pathNode);
+            if (resolved === null)
+                continue; // skip floor
+            emitAppProvider(httpMethod, resolved, pathNode.startPosition.row + 1);
         }
         // Django providers come from the graph Route nodes (includes composed by
         // the ingestion route extractor), not a per-file source scan — see the note
@@ -1020,17 +1136,11 @@ export const PYTHON_HTTP_PLUGIN = {
         // change is strictly additive vs. the prior @app-only behaviour;
         // when the same router is mounted under multiple prefixes we emit
         // one detection per prefix.
-        for (const match of runCompiledPatterns(FASTAPI_ROUTER_PATTERNS, tree)) {
-            const methodNode = match.captures.method;
-            const pathNode = match.captures.path;
-            if (!methodNode || !pathNode)
-                continue;
-            const httpMethod = FASTAPI_VERBS[methodNode.text];
-            if (!httpMethod)
-                continue;
-            const rawPath = unquoteLiteral(pathNode.text);
-            if (rawPath === null)
-                continue;
+        // Join a `@router.<verb>` path with the include_router / APIRouter prefix(es)
+        // that apply to this file and emit one provider detection per prefix. Shared
+        // by the literal and the #2391 non-literal (resolved) router loops so both
+        // stack prefixes identically.
+        const emitRouterProvider = (httpMethod, rawPath, line) => {
             // Long key first (precise, package-aware), short key as fallback.
             // Mirrors the ingestion-side resolution in parse-impl.ts so the
             // graph nodes and group contracts agree on which prefix applies.
@@ -1053,10 +1163,38 @@ export const PYTHON_HTTP_PLUGIN = {
                     path: p,
                     name: null,
                     // Best-effort containment fallback — see the @app provider note above.
-                    line: pathNode.startPosition.row + 1,
+                    line,
                     confidence: 0.8,
                 });
             }
+        };
+        for (const match of runCompiledPatterns(FASTAPI_ROUTER_PATTERNS, tree)) {
+            const methodNode = match.captures.method;
+            const pathNode = match.captures.path;
+            if (!methodNode || !pathNode)
+                continue;
+            const httpMethod = FASTAPI_VERBS[methodNode.text];
+            if (!httpMethod)
+                continue;
+            const rawPath = unquoteLiteral(pathNode.text);
+            if (rawPath === null)
+                continue;
+            emitRouterProvider(httpMethod, rawPath, pathNode.startPosition.row + 1);
+        }
+        // Providers: FastAPI @router.<verb>(CONST | A + "/x") — resolved composed path
+        // (#2391). Null resolution → skip, so provider/graph parity holds.
+        for (const match of runCompiledPatterns(FASTAPI_ROUTER_EXPR_PATTERNS, tree)) {
+            const methodNode = match.captures.method;
+            const pathNode = match.captures.path;
+            if (!methodNode || !pathNode)
+                continue;
+            const httpMethod = FASTAPI_VERBS[methodNode.text];
+            if (!httpMethod)
+                continue;
+            const resolved = resolveExprArg(pathNode);
+            if (resolved === null)
+                continue;
+            emitRouterProvider(httpMethod, resolved, pathNode.startPosition.row + 1);
         }
         // Providers: Flask `app.add_url_rule('/path', view_func=handler, methods=[…])`.
         // The handler is a `view_func` identifier, frequently an imported (possibly

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

@@ -7,6 +7,10 @@ import { logger } from '../../logger.js';
 // reserved-keyword labels `Macro` and `Union`, and LadybugDB's parser rejects
 // a disjunction that names a reserved keyword (#2325) — which the resolver's
 // try/catch then swallowed. `labels(n) IN` has no such collision.
+// This list overlaps `ingestion/utils/symbol-labels.ts` (SYMBOL_NODE_LABELS) but
+// is a deliberate SUBSET — it omits `Namespace`/`Variable`/`Module`. Unifying the
+// two would widen which nodes resolve as contract symbols and must update the
+// #2325 test, so they are intentionally kept separate for now.
 export const CUSTOM_CONTRACT_RESOLVE_QUERY = `MATCH (n)
    WHERE labels(n) IN ['Function','Method','Class','Interface','Struct','Enum','Trait','Constructor','TypeAlias','Impl','Macro','Union','Typedef','Property','Record','Delegate','Annotation','Template','Const','Static','CodeElement']
      AND n.name = $symbolName

package/dist/core/incremental/escalation-gate.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Escalation gate for the incremental DB writeback (#2409).
+ *
+ * When the effective write set covers most of the repo, per-file surgery is
+ * strictly worse than the proven wipe-and-bulk-COPY plan — the same data
+ * volume lands either way, but the surgical plan pays per-table deletes plus
+ * COPY-into-non-empty tables, and at that size it measured SLOWER than a full
+ * DB load. The orchestrator (`run-analyze.ts`) consults this predicate to
+ * decide which write plan to run; only the DB write plan changes on
+ * escalation — fileHashes/meta bookkeeping is identical.
+ *
+ * Extracted to a pure module (tri-review 4669518496) so the AND-gate's
+ * boundary corners are pinned by unit tests without multi-minute
+ * orchestration permutations — an `&&`→`||` mutation here can no longer
+ * survive CI.
+ */
+export declare const INCREMENTAL_MAX_WRITE_FRACTION = 0.5;
+export declare const INCREMENTAL_ESCALATION_MIN_FILES = 50;
+/**
+ * Should the incremental writeback escalate from per-file surgery to a full
+ * wipe-and-bulk-COPY write plan?
+ *
+ * @param deleteCount        Files whose rows will be DETACH-DELETEd
+ *                           (effective write set ∪ deleted files, deduped).
+ * @param effectiveWriteCount Size of the effective write set (toWrite ∪
+ *                           importer-BFS expansion ∪ boundary-crossing files).
+ * @param totalFiles         Current repo file count (denominator).
+ *
+ * POPULATION MISMATCH (tri-review 4669518496, documented not "fixed"): the
+ * numerator counts effective-write-set members, which include importer-BFS
+ * results read from the PRE-pipeline DB — those can be now-DELETED paths that
+ * the CURRENT file list (the denominator) no longer contains. The fraction is
+ * therefore not a true subset ratio and can exceed 1 on delete-heavy runs.
+ * That errs toward escalation, which is the safe direction (the full write
+ * plan is always correct); the valve's log line clamps the DISPLAYED
+ * percentage to 100 so operators aren't shown ">100% of the repo".
+ */
+export declare const shouldEscalateIncrementalWrite: (deleteCount: number, effectiveWriteCount: number, totalFiles: number) => boolean;

package/dist/core/incremental/escalation-gate.js

@@ -0,0 +1,48 @@
+/**
+ * Escalation gate for the incremental DB writeback (#2409).
+ *
+ * When the effective write set covers most of the repo, per-file surgery is
+ * strictly worse than the proven wipe-and-bulk-COPY plan — the same data
+ * volume lands either way, but the surgical plan pays per-table deletes plus
+ * COPY-into-non-empty tables, and at that size it measured SLOWER than a full
+ * DB load. The orchestrator (`run-analyze.ts`) consults this predicate to
+ * decide which write plan to run; only the DB write plan changes on
+ * escalation — fileHashes/meta bookkeeping is identical.
+ *
+ * Extracted to a pure module (tri-review 4669518496) so the AND-gate's
+ * boundary corners are pinned by unit tests without multi-minute
+ * orchestration permutations — an `&&`→`||` mutation here can no longer
+ * survive CI.
+ */
+// Escalation cap (#2409): above this fraction of the repo's files, the
+// surgical delete-and-COPY writeback is replaced by the full-rebuild write
+// plan (wipe + bulk COPY of the already-built graph). 0.5 is a coarse
+// crossover knob, not a tuned constant — lower it if surgical writebacks
+// above ~30% ever measure slower than the full COPY.
+export const INCREMENTAL_MAX_WRITE_FRACTION = 0.5;
+// …but only at a scale where the surgical plan's overhead is real. Tiny
+// repos hit huge fractions from a single edit (7 files → one touch can
+// pull in 5) while both write plans finish in well under a second there —
+// escalating would churn the DB files for nothing.
+export const INCREMENTAL_ESCALATION_MIN_FILES = 50;
+/**
+ * Should the incremental writeback escalate from per-file surgery to a full
+ * wipe-and-bulk-COPY write plan?
+ *
+ * @param deleteCount        Files whose rows will be DETACH-DELETEd
+ *                           (effective write set ∪ deleted files, deduped).
+ * @param effectiveWriteCount Size of the effective write set (toWrite ∪
+ *                           importer-BFS expansion ∪ boundary-crossing files).
+ * @param totalFiles         Current repo file count (denominator).
+ *
+ * POPULATION MISMATCH (tri-review 4669518496, documented not "fixed"): the
+ * numerator counts effective-write-set members, which include importer-BFS
+ * results read from the PRE-pipeline DB — those can be now-DELETED paths that
+ * the CURRENT file list (the denominator) no longer contains. The fraction is
+ * therefore not a true subset ratio and can exceed 1 on delete-heavy runs.
+ * That errs toward escalation, which is the safe direction (the full write
+ * plan is always correct); the valve's log line clamps the DISPLAYED
+ * percentage to 100 so operators aren't shown ">100% of the repo".
+ */
+export const shouldEscalateIncrementalWrite = (deleteCount, effectiveWriteCount, totalFiles) => deleteCount >= INCREMENTAL_ESCALATION_MIN_FILES &&
+    effectiveWriteCount / Math.max(1, totalFiles) > INCREMENTAL_MAX_WRITE_FRACTION;

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

@@ -2,9 +2,9 @@
  * 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
+ *   the importer BFS (queryImportersBatch) 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

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

@@ -2,9 +2,9 @@
  * 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
+ *   the importer BFS (queryImportersBatch) 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

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

@@ -22,7 +22,7 @@
  *
  * `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
+ * can be fed to both `deleteNodesForFiles` 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
@@ -57,7 +57,7 @@ export declare const extractChangedSubgraph: (fullGraph: KnowledgeGraph, toWrite
  * 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`
+ * orchestrator MUST feed the returned set to both `deleteNodesForFiles`
  * and `extractChangedSubgraph` — feeding the unexpanded set to either
  * one leaves stale rows or PK-conflicts at COPY time.
  */

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

@@ -22,7 +22,7 @@
  *
  * `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
+ * can be fed to both `deleteNodesForFiles` 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
@@ -118,7 +118,7 @@ export const extractChangedSubgraph = (fullGraph, toWriteSet) => {
  * 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`
+ * orchestrator MUST feed the returned set to both `deleteNodesForFiles`
  * and `extractChangedSubgraph` — feeding the unexpanded set to either
  * one leaves stale rows or PK-conflicts at COPY time.
  */