gitnexus 1.6.10-rc.99 → 1.6.10

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

@@ -15,6 +15,8 @@ export { ormPhase, type ORMOutput } from './orm.js';
 export { crossFilePhase, type CrossFileOutput } from './cross-file.js';
 export { scopeResolutionPhase, type ScopeResolutionOutput, } from '../scope-resolution/pipeline/phase.js';
 export { springConfigPhase, type SpringConfigOutput } from './spring-config.js';
+export { springAutoConfigurationPhase, type SpringAutoConfigurationOutput, } from './spring-auto-configuration.js';
+export { springAopPhase, springAopInheritancePhase, type SpringAopOutput, type SpringAopInheritanceOutput, } from './spring-aop.js';
 export { pruneLocalSymbolsPhase, type PruneLocalSymbolsOutput } from './prune-local-symbols.js';
 export { taintSummariesPhase, type TaintSummariesOutput } from './taint-summaries.js';
 export { callSummariesPhase, type CallSummariesOutput } from './call-summaries.js';

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

@@ -16,6 +16,8 @@ export { ormPhase } from './orm.js';
 export { crossFilePhase } from './cross-file.js';
 export { scopeResolutionPhase, } from '../scope-resolution/pipeline/phase.js';
 export { springConfigPhase } from './spring-config.js';
+export { springAutoConfigurationPhase, } from './spring-auto-configuration.js';
+export { springAopPhase, springAopInheritancePhase, } from './spring-aop.js';
 export { pruneLocalSymbolsPhase } from './prune-local-symbols.js';
 export { taintSummariesPhase } from './taint-summaries.js';
 export { callSummariesPhase } from './call-summaries.js';

package/dist/core/ingestion/pipeline-phases/parse-impl.d.ts

@@ -21,6 +21,21 @@ import { type PipelineProgress } from '../../../_shared/index.js';
 import type { ExtractedDecoratorRoute, ExtractedFetchCall, ExtractedORMQuery, ExtractedRoute, ExtractedToolDef, FetchWrapperDef } from '../workers/parse-worker.js';
 import type { KnowledgeGraph } from '../../graph/types.js';
 import type { PipelineOptions } from '../pipeline.js';
+/** Projected main-thread heap need for the parse phase (#2649). */
+export declare function projectParseHeapNeedBytes(parseableFileCount: number): number;
+/** True when the mid-loop heap guard should abort the parse (#2649). */
+export declare function shouldAbortForHeapPressure(heapUsedBytes: number, heapLimitBytes: number): boolean;
+/**
+ * The ONE action a user should take when this repository doesn't fit the
+ * current heap (#2649). Users hitting memory limits are already frustrated —
+ * a menu of env knobs at that moment is noise. Branch on whether the machine
+ * itself has more memory to give: if this process's limit sits well below
+ * what the RAM-aware auto-sizer would grant (an inherited NODE_OPTIONS pin or
+ * explicit flag), the fix is to drop the pin — gitnexus sizes itself.
+ * Otherwise the machine is the ceiling and only scope or hardware helps.
+ * Escape hatches (GITNEXUS_MEMORY etc.) stay in the README env table.
+ */
+export declare function heapPressureRemedy(heapLimitBytes: number): string;
 type ScannedFile = {
     path: string;
     size: number;

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, } from '../../../storage/parse-cache.js';
-import { clearParsedFileStore, persistParsedFileChunk, getDurableParsedFileDir, loadDurableParsedFileIndex, prepareDurableParsedFileChunk, restoreDurableParsedFileShard, } from '../../../storage/parsedfile-store.js';
+import { clearParsedFileStore, persistParsedFileChunk, loadParsedFilesForPaths, getDurableParsedFileDir, loadDurableParsedFileIndex, prepareDurableParsedFileChunk, restoreDurableParsedFileShard, } 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';
@@ -25,13 +25,17 @@ import { getLanguageFromFilename, } from '../../../_shared/index.js';
 import { readFileContents } from '../filesystem-walker.js';
 import { isLanguageAvailable, isGrammarRuntimeSkipped, createParserForLanguage, } from '../../tree-sitter/parser-loader.js';
 import { parseSourceSafe } from '../../tree-sitter/safe-parse.js';
-import { getProvider, providers } from '../languages/index.js';
+import { getProvider, getProviderForFile, providers } from '../languages/index.js';
+import { SCOPE_RESOLVERS } from '../scope-resolution/pipeline/registry.js';
+import { DATA_ROUTE_TABLE_SOURCE } from '../route-extractors/data-route-table.js';
 import { createWorkerPool, workerPoolDisabledByEnv, resolveAutoPoolSize, WorkerPoolInitializationError, WorkerPoolDisabledError, } from '../workers/worker-pool.js';
 import { normalizeExtractedRoutePath } from '../route-extractors/route-path.js';
 import { resolveOperands, } from '../route-extractors/python-const-resolver.js';
 import { resolveInheritedSpringRoutes, } from '../route-extractors/spring-shared.js';
 import fs from 'node:fs';
+import { effectiveRamBytes, memoryAutopilotDisabled } from '../utils/effective-ram.js';
 import path from 'node:path';
+import v8 from 'node:v8';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { isDev } from '../utils/env.js';
 import { isVerboseIngestionEnabled } from '../utils/verbose.js';
@@ -39,6 +43,74 @@ import { endTimer, isDeferredResolutionProfileEnabled, logDeferredProfile, start
 import { isDebugHeapEnabled, logHeapProbe } from '../utils/heap-probe.js';
 import { logger } from '../../logger.js';
 // ── Constants ──────────────────────────────────────────────────────────────
+/**
+ * Heap-scale guardrail constants (#2649). Measured on a Linux-kernel analyze:
+ * ~75 graph nodes per PARSEABLE file (~5M nodes / ~65k parseable files;
+ * validated against heap probes at chunks 25/50/75 of 113 — the first
+ * calibration divided by total scanned files and under-projected by ~30%),
+ * main-thread heap per node. C-heavy corpus; other language mixes vary — these
+ * feed a WARNING and an emergency abort, never a hard admission gate, so
+ * estimate error only shifts when the operator hears about the problem, not
+ * whether analyze runs.
+ *
+ * RECALIBRATED for streamed structural emit (#2680), which is on by default for
+ * full rebuilds and holds relationships out of the JS heap. The original 2250
+ * was measured against the object-based graph; an A/B at 400k nodes / 1.08M
+ * edges put streaming at 1.40x smaller (819 MB -> 584 MB), so the corpus-
+ * calibrated figure is divided by that ratio: 2250 / 1.40 ~= 1600. Scaling the
+ * measured constant rather than substituting a synthetic one keeps #2649's
+ * kernel calibration intact and changes only the one thing that actually moved.
+ *
+ * If streaming is disabled (GITNEXUS_STREAM_GRAPH_EMIT=0, or any non-force run)
+ * this UNDER-projects by ~40%, so the preflight warning may stay quiet on a repo
+ * that then struggles. That is the safe direction to be wrong in: the abort
+ * below reads LIVE heap use, not this projection, so it still catches the real
+ * condition — only the early warning is affected.
+ */
+const PROJECTED_NODES_PER_FILE = 75;
+const PROJECTED_HEAP_BYTES_PER_NODE = 1600;
+/** Warn at scan end when the projection crosses this share of the heap limit. */
+const PREFLIGHT_WARN_FRACTION = 0.85;
+/**
+ * Abort the chunk loop when live heap use crosses this share of the limit.
+ * Above ~0.95 V8 enters the ineffective-mark-compact death spiral (2s+ GC
+ * pauses that also falsely idle-timeout healthy workers, #2649); 0.92 leaves
+ * one chunk's worth of headroom to fail with an actionable message instead.
+ * `GITNEXUS_MEMORY=off` declines the abort (proceed-at-own-risk).
+ */
+const HEAP_ABORT_FRACTION = 0.92;
+/** Projected main-thread heap need for the parse phase (#2649). */
+export function projectParseHeapNeedBytes(parseableFileCount) {
+    return parseableFileCount * PROJECTED_NODES_PER_FILE * PROJECTED_HEAP_BYTES_PER_NODE;
+}
+/** True when the mid-loop heap guard should abort the parse (#2649). */
+export function shouldAbortForHeapPressure(heapUsedBytes, heapLimitBytes) {
+    if (memoryAutopilotDisabled())
+        return false;
+    return heapUsedBytes > heapLimitBytes * HEAP_ABORT_FRACTION;
+}
+/**
+ * The ONE action a user should take when this repository doesn't fit the
+ * current heap (#2649). Users hitting memory limits are already frustrated —
+ * a menu of env knobs at that moment is noise. Branch on whether the machine
+ * itself has more memory to give: if this process's limit sits well below
+ * what the RAM-aware auto-sizer would grant (an inherited NODE_OPTIONS pin or
+ * explicit flag), the fix is to drop the pin — gitnexus sizes itself.
+ * Otherwise the machine is the ceiling and only scope or hardware helps.
+ * Escape hatches (GITNEXUS_MEMORY etc.) stay in the README env table.
+ */
+export function heapPressureRemedy(heapLimitBytes) {
+    // Effective RAM honors a real cgroup limit — raw os.totalmem() told users
+    // inside an 8GB-limited container on a 64GB host that "this machine has
+    // more memory available", an advice loop with no exit (#2649 review).
+    const autoCapBytes = effectiveRamBytes() * 0.75;
+    if (heapLimitBytes < autoCapBytes * 0.9) {
+        return (`This machine has more memory available: re-run without the --max-old-space-size ` +
+            `pin (NODE_OPTIONS or node flag) — gitnexus sizes its heap to the machine automatically.`);
+    }
+    return (`This machine is at its memory ceiling: exclude generated or vendored directories ` +
+        `via .gitnexusignore, or analyze on a machine with more memory.`);
+}
 /** Max bytes of source content to load per parse chunk.
  *
  * Memory bound for the worker pool dispatch + a granularity knob for
@@ -365,6 +437,19 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
     const dispatchSubBatchMaxBytes = Number.isFinite(subBatchEnv) && subBatchEnv > 0
         ? subBatchEnv
         : Math.max(MIN_SUB_BATCH_BYTES, Math.ceil(chunkByteBudget / (effectivePoolSize * TARGET_JOBS_PER_WORKER)));
+    // Heap-scale guardrails (#2649), measured on a Linux-kernel analyze
+    // (94,773 files): ~55 graph nodes per parseable file and ~2.2KB of
+    // main-thread heap per node, linear across 113 chunks (see
+    // docs/plans/2026-07-23-gitnexus-plan-large-repo-analyze-oom.md §2).
+    // Estimates, not contracts — used only to warn early (preflight) and to
+    // convert a certain multi-minute GC death spiral into an immediate
+    // actionable error (mid-loop guard).
+    const projectedHeapNeedBytes = projectParseHeapNeedBytes(parseableScanned.length);
+    const heapLimitBytes = v8.getHeapStatistics().heap_size_limit;
+    if (projectedHeapNeedBytes > heapLimitBytes * PREFLIGHT_WARN_FRACTION) {
+        logger.warn(`Large repository: analyzing ${parseableScanned.length} files needs roughly ${Math.round(projectedHeapNeedBytes / 1024 / 1024 / 1024)}GB of memory, ` +
+            `but Node is limited to ${Math.round(heapLimitBytes / 1024 / 1024 / 1024)}GB — analyze may stop early. ${heapPressureRemedy(heapLimitBytes)}`);
+    }
     const chunks = [];
     let currentChunk = [];
     let currentBytes = 0;
@@ -676,6 +761,16 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
             if (heapProbeEveryN > 0 && chunkIdx > 0 && chunkIdx % heapProbeEveryN === 0) {
                 logHeapProbe(`parse-chunk-${chunkIdx}`, `nodes=${graph.nodeCount} parsedFiles=${allParsedFiles.length}`);
             }
+            // #2649 mid-loop heap guard: fail actionably BEFORE V8 enters the
+            // ineffective-mark-compact death spiral (which also falsely times out
+            // healthy workers). The pool is torn down by this function's finally.
+            const heapUsedNow = process.memoryUsage().heapUsed;
+            const heapLimitNow = v8.getHeapStatistics().heap_size_limit;
+            if (shouldAbortForHeapPressure(heapUsedNow, heapLimitNow)) {
+                throw new Error(`Analyze stopped before running out of memory: ${Math.round(heapUsedNow / 1024 / 1024)}MB of the ` +
+                    `${Math.round(heapLimitNow / 1024 / 1024)}MB Node heap in use at parse chunk ${chunkIdx + 1}/${numChunks} (#2649). ` +
+                    heapPressureRemedy(heapLimitNow));
+            }
             const chunkPaths = chunks[chunkIdx];
             // Start wall-clock for the per-chunk throughput log emitted at end
             // of this iteration. The gate is computed once above; here we just
@@ -963,8 +1058,15 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
                 resolvedRoutes.push(dr);
                 continue;
             }
+            // Provider-driven fold (#2980): languages with qualified-ref semantics
+            // (Java `ApiPaths.X` / `com.example.ApiPaths.X`) fold through their
+            // provider hook; everything else uses the shared language-agnostic
+            // operand fold. No language names in the shared layer.
+            const fold = getProviderForFile(dr.filePath)?.foldRoutePathOperands;
             const value = dr.routePathOperands
-                ? resolveOperands(dr.filePath, dr.routePathOperands, repoConstants)
+                ? fold
+                    ? fold(dr.filePath, dr.routePathOperands, repoConstants)
+                    : resolveOperands(dr.filePath, dr.routePathOperands, repoConstants)
                 : null;
             if (value === null) {
                 skipped++;
@@ -1163,9 +1265,57 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
         }
     }
     logHeapProbe('parse-impl-return', `exportedTypeMap=${exportedTypeMap.size} parsedFiles=${allParsedFiles.length} nodes=${graph.nodeCount}`);
+    const routeFilePaths = new Set(allPaths);
+    const dataRouteFilePaths = new Set(allDecoratorRoutes
+        .filter((route) => route.source === DATA_ROUTE_TABLE_SOURCE)
+        .map((route) => route.filePath));
+    const routeResolutionConfigs = new Map();
+    for (const filePath of dataRouteFilePaths) {
+        const language = getLanguageFromFilename(filePath);
+        if (language === null || routeResolutionConfigs.has(language))
+            continue;
+        const resolver = SCOPE_RESOLVERS.get(language);
+        routeResolutionConfigs.set(language, resolver?.loadResolutionConfig === undefined
+            ? undefined
+            : await resolver.loadResolutionConfig(repoPath));
+    }
+    let routeResolutionFiles = allParsedFiles;
+    const resolveRouteImportTarget = (parsedImport, fromFile) => {
+        const language = getLanguageFromFilename(fromFile);
+        if (language === null)
+            return null;
+        const target = SCOPE_RESOLVERS.get(language)?.resolveImportTarget(parsedImport.targetRaw ?? '', fromFile, routeFilePaths, routeResolutionConfigs.get(language), { parsedFiles: routeResolutionFiles, parsedImport });
+        if (typeof target === 'string')
+            return target;
+        return target?.length === 1 ? target[0] : null;
+    };
+    if (parsedFileStorePath !== undefined && dataRouteFilePaths.size > 0) {
+        const byPath = await loadParsedFilesForPaths(parsedFileStorePath, dataRouteFilePaths);
+        for (const parsed of allParsedFiles) {
+            if (dataRouteFilePaths.has(parsed.filePath))
+                byPath.set(parsed.filePath, parsed);
+        }
+        routeResolutionFiles = [...byPath.values()];
+        const directTargets = new Set();
+        for (const parsed of routeResolutionFiles) {
+            for (const parsedImport of parsed.parsedImports) {
+                const target = resolveRouteImportTarget(parsedImport, parsed.filePath);
+                if (target !== null)
+                    directTargets.add(target);
+            }
+        }
+        const importedFiles = await loadParsedFilesForPaths(parsedFileStorePath, directTargets);
+        for (const parsed of importedFiles.values())
+            byPath.set(parsed.filePath, parsed);
+        routeResolutionFiles = [...byPath.values()];
+    }
     // Part 2 (#2138): resolve each route's handler to a real symbol UID now that
     // the model is fully populated and decorator-route prefixes are finalized.
-    const routeHandlerSymbols = resolveRouteHandlerSymbols(model, allExtractedRoutes, allDecoratorRoutes);
+    const routeHandlerSymbols = resolveRouteHandlerSymbols(model, allExtractedRoutes, allDecoratorRoutes, {
+        files: routeResolutionFiles,
+        resolveImportTarget: resolveRouteImportTarget,
+        isExportedSymbol: (nodeId) => graph.getNode(nodeId)?.properties.isExported === true,
+    });
     return {
         exportedTypeMap,
         allFetchCalls,

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

@@ -21,6 +21,11 @@ export const parsePhase = {
     name: 'parse',
     deps: ['structure', 'markdown', 'cobol'],
     async execute(ctx, deps) {
+        // Begin streamed structural emit (#2680), if enabled. Deliberately here and
+        // not at graph construction: the pre-parse phases are not all write-only —
+        // `mapCobolToGraph` scans CALLS edges and removes the unresolved ones — and
+        // nothing before parse produces bulk edge volume anyway.
+        ctx.graphEmit?.beginStreaming();
         const { scannedFiles, allPaths, allPathSet, totalFiles } = getPhaseOutput(deps, 'structure');
         const result = await runChunkedParseAndResolve(ctx.graph, scannedFiles, allPaths, totalFiles, ctx.repoPath, ctx.pipelineStart, ctx.onProgress, ctx.options);
         return {

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

@@ -4,8 +4,9 @@
  * Detects execution flows (processes) and creates Process nodes +
  * STEP_IN_PROCESS edges. Also links Route/Tool nodes to processes.
  *
- * @deps    communities, routes, tools, pruneLocalSymbols
- * @reads   graph (all nodes and relationships), communityResult, routeRegistry, toolDefs
+ * @deps    communities, routes, tools, pruneLocalSymbols, structure, parse
+ * @reads   graph (all nodes and relationships), communityResult, routeRegistry,
+ *          toolDefs, parse's allFetchCalls + allORMQueries (R3-6 sink sites)
  * @writes  graph (Process nodes, STEP_IN_PROCESS edges, ENTRY_POINT_OF edges)
  */
 import type { PipelinePhase } from './types.js';

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

@@ -4,8 +4,9 @@
  * Detects execution flows (processes) and creates Process nodes +
  * STEP_IN_PROCESS edges. Also links Route/Tool nodes to processes.
  *
- * @deps    communities, routes, tools, pruneLocalSymbols
- * @reads   graph (all nodes and relationships), communityResult, routeRegistry, toolDefs
+ * @deps    communities, routes, tools, pruneLocalSymbols, structure, parse
+ * @reads   graph (all nodes and relationships), communityResult, routeRegistry,
+ *          toolDefs, parse's allFetchCalls + allORMQueries (R3-6 sink sites)
  * @writes  graph (Process nodes, STEP_IN_PROCESS edges, ENTRY_POINT_OF edges)
  */
 import { getPhaseOutput } from './types.js';
@@ -26,11 +27,19 @@ export function computeDynamicMaxProcesses(symbolCount) {
 }
 export const processesPhase = {
     name: 'processes',
-    // `structure` supplies `totalFiles` (progress counter) without the spurious
-    // structural data dependency on `parse`. `pruneLocalSymbols` is declared
+    // `structure` supplies `totalFiles` (progress counter), which is why this
+    // phase historically avoided depending on `parse` at all — that dependency
+    // was spurious for a progress number.
+    //
+    // It is no longer spurious. R3-6 reads `allFetchCalls` / `allORMQueries` from
+    // the parse output to learn WHERE the program reaches outward, which is what
+    // lets a trace end at a sink instead of only at a leaf. That is a real data
+    // dependency, so it is declared rather than reached for implicitly — and the
+    // read below still fails open, so a pipeline without that output detects no
+    // sinks rather than failing the phase. `pruneLocalSymbols` is declared
     // explicitly so process extraction always reads the trimmed graph even if a
     // future option drops the intervening `mro`/`communities` phases.
-    deps: ['communities', 'routes', 'tools', 'pruneLocalSymbols', 'structure'],
+    deps: ['communities', 'routes', 'tools', 'pruneLocalSymbols', 'structure', 'parse'],
     async execute(ctx, deps) {
         const { totalFiles } = getPhaseOutput(deps, 'structure');
         const { communityResult } = getPhaseOutput(deps, 'communities');
@@ -48,6 +57,32 @@ export const processesPhase = {
                 symbolCount++;
         });
         const dynamicMaxProcesses = computeDynamicMaxProcesses(symbolCount);
+        // R3-6: where the program reaches outward. Already collected by the parse
+        // phase for FILE-level FETCHES/QUERIES edges; reused here at function
+        // granularity so a trace can end somewhere meaningful instead of only at a
+        // leaf. Absent (or an older parse output) simply yields no sinks and the
+        // previous behaviour.
+        //
+        // Typed as `ParseOutput` rather than a locally re-declared structural shape,
+        // the way every other parse consumer does it (cross-file.ts, orm.ts,
+        // routes.ts, tools.ts). `getPhaseOutput` is a raw `as T` cast, so a local
+        // shape does not check anything — it only severs the compile-time link, and
+        // renaming `allFetchCalls` on `ParseOutput` would then still compile here and
+        // silently detect zero sinks. The runtime `.filter` below is the actual
+        // guard, and it stays.
+        let parseOutput;
+        try {
+            parseOutput = getPhaseOutput(deps, 'parse');
+        }
+        catch {
+            // Fail open: no sinks, previous behaviour. A missing parse output is a
+            // pipeline-composition question, not a reason to lose every process.
+            parseOutput = undefined;
+        }
+        const outwardActionSites = [
+            ...(parseOutput?.allFetchCalls ?? []),
+            ...(parseOutput?.allORMQueries ?? []),
+        ].filter((s) => typeof s?.filePath === 'string' && typeof s?.lineNumber === 'number');
         const processResult = await processProcesses(ctx.graph, communityResult.memberships, (message, progress) => {
             const processProgress = 99 + progress * 0.01;
             ctx.onProgress({
@@ -56,10 +91,60 @@ export const processesPhase = {
                 message,
                 stats: { filesProcessed: totalFiles, totalFiles, nodesCreated: ctx.graph.nodeCount },
             });
-        }, { maxProcesses: dynamicMaxProcesses, minSteps: 3 });
+        }, { maxProcesses: dynamicMaxProcesses, minSteps: 3 }, outwardActionSites);
         if (isDev) {
             logger.info(`🔄 Process detection: ${processResult.stats.totalProcesses} processes found (${processResult.stats.crossCommunityCount} cross-community)`);
         }
+        // Not gated on `isDev`: this is the one line that tells a reader the process
+        // list is a SAMPLE. "823 flows" presented without it reads as the complete
+        // set, which is the confident-empty failure in its other direction — a
+        // confident-COMPLETE one.
+        //
+        // But it is only a `warn` when a ceiling removed WHOLE FLOWS from the
+        // report. That split is the one `ProcessTruncationStats` already documents —
+        // "unexplored entry points mean whole flows are missing, while a
+        // depth-capped trace means a flow is present but shorter than it really is"
+        // — and it is what keeps the line worth reading. Warning on every counter
+        // meant warning on every run: this phase overrides only `maxProcesses`, so
+        // at the shipped defaults (`maxBranching: 4`, `maxTraceDepth: 10`,
+        // per-entry trace budget 12) `calleesDropped` fires for any function with
+        // five callees, `tracesDepthCapped` for any chain deeper than ten, and
+        // `walksCutByBudget` for any entry point with twelve paths under it. All
+        // three are true of every non-trivial repository — and none of them removes
+        // an entry point or a completed flow from the list, they only bound how far
+        // an already-represented region was walked. A warning that always fires is a
+        // warning nobody reads, so those three go to `debug`.
+        //
+        // `entryPointCandidatesDropped` IS in the loud set even though it fires on
+        // any repository with more than 200 candidates, because it is the only
+        // ceiling that grows with the repository: `entryPointsUnexplored` and
+        // `processesDropped` can only fire while `maxProcesses` (symbols / 10) is
+        // small enough to bind, so gating on those two alone would go quiet on
+        // exactly the large repositories where 200 of several thousand entry points
+        // is the thinnest sample. The message leads with that ratio so the line
+        // carries a fact rather than an alarm.
+        //
+        // `stats.truncation` on the RESULT is untouched and still reports all six
+        // counters; this only decides which of them are loud.
+        const { truncation } = processResult.stats;
+        const entryPointCandidates = processResult.stats.entryPointsFound + truncation.entryPointCandidatesDropped;
+        const flowsMissing = truncation.entryPointCandidatesDropped > 0 ||
+            truncation.entryPointsUnexplored > 0 ||
+            truncation.processesDropped > 0;
+        const shape = `${truncation.entryPointCandidatesDropped} of ${entryPointCandidates} candidate entry point(s) never ranked in, ` +
+            `${truncation.entryPointsUnexplored} ranked entry point(s) never traced, ` +
+            `${truncation.processesDropped} deduplicated flow(s) dropped at maxProcesses, ` +
+            `${truncation.tracesDepthCapped} trace(s) cut at maxTraceDepth, ` +
+            `${truncation.calleesDropped} callee(s) skipped at maxBranching, ` +
+            `${truncation.walksCutByBudget} walk(s) cut by the per-entry trace budget.`;
+        if (flowsMissing) {
+            logger.warn({ truncation }, `[processes] ${processResult.stats.totalProcesses} flows reported, but whole flows are MISSING: ` +
+                `${shape} An absent flow does NOT mean the code path does not exist.`);
+        }
+        else if (truncation.truncated) {
+            logger.debug({ truncation }, `[processes] ${processResult.stats.totalProcesses} flows reported; every flow found is present, ` +
+                `but some are shorter than the code path they describe: ${shape}`);
+        }
         processResult.processes.forEach((proc) => {
             ctx.graph.addNode({
                 id: proc.id,

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

@@ -18,6 +18,8 @@ import { phpFileToRouteURL } from '../route-extractors/php.js';
 import { extractResponseShapes, extractPHPResponseShapes, } from '../route-extractors/response-shapes.js';
 import { extractMiddlewareChain, extractNextjsMiddlewareConfig, compileMatcher, compiledMatcherMatchesRoute, } from '../route-extractors/middleware.js';
 import { processNextjsFetchRoutes } from '../call-processor.js';
+import { reconcileDispatchGuardRoutes } from '../route-extractors/dispatch-guard.js';
+import { DATA_ROUTE_TABLE_SOURCE } from '../route-extractors/data-route-table.js';
 import { normalizeExtractedRoutePath, normalizeRouteMethod, routeNodeKey, } from '../route-extractors/route-path.js';
 import { generateId } from '../../../lib/utils.js';
 import { readFileContents } from '../filesystem-walker.js';
@@ -27,6 +29,24 @@ const EXPO_NAV_PATTERNS = [
     /router\.(push|replace|navigate)\(\s*['"`]([^'"`]+)['"`]/g,
     /<Link\s+[^>]*href=\s*['"`]([^'"`]+)['"`]/g,
 ];
+function handlerSymbolContent(content, handlerNode) {
+    if (handlerNode === undefined)
+        return undefined;
+    const startLine = handlerNode.properties.startLine;
+    const endLine = handlerNode.properties.endLine;
+    if (typeof startLine !== 'number' ||
+        typeof endLine !== 'number' ||
+        !Number.isInteger(startLine) ||
+        !Number.isInteger(endLine) ||
+        startLine < 0 ||
+        endLine < startLine) {
+        return undefined;
+    }
+    return content
+        .split(/\r?\n/)
+        .slice(startLine, endLine + 1)
+        .join('\n');
+}
 const TEMPLATE_URL_PATTERNS = [
     /\b(?:action|href)\s*=\s*["']([^"']+)["']/gi,
     /\burl\s*:\s*["']([^"']+)["'](?!\s*\+)/g,
@@ -100,6 +120,45 @@ export const routesPhase = {
         // Local copy — routes phase must not mutate upstream ParseOutput
         const allFetchCalls = [...parseFetchCalls];
         const routeRegistry = new Map();
+        /**
+         * Registry keys written straight from the file list below, never through
+         * `addRoute`. `resolveRouteHandlerSymbols` walks only `extractedRoutes` and
+         * `decoratorRoutes`, so it never sees these URLs and its `claimed` set never
+         * contains them — which means a handler stamped on one of these keys was
+         * resolved for a DIFFERENT route.
+         *
+         * That is reachable, and it fabricates rather than omits (#3049). A
+         * method-agnostic route (`@All`, a Django function view, a verb-less
+         * dispatch guard) keys by URL alone via `routeNodeKey`, so it collides with
+         * a file-convention route at the same URL. It claims the key unopposed in
+         * `claim()`, then loses first-writer-wins here in `addRoute` and is dropped
+         * as a duplicate — and without this guard the surviving file-convention node
+         * would read that handler and present another application's controller
+         * method as its own. `api_impact` is documented to be run BEFORE editing a
+         * route handler, so it would answer with a handler from the wrong app.
+         *
+         * Dropping the losing route is a separate and deliberate consequence of
+         * URL-only identity; this only stops the false attribution.
+         *
+         * Membership is recorded AT the pre-seeding `set`, mirroring `claim()` in
+         * call-processor.ts, which writes `claimed` and its result map together
+         * rather than re-deriving either by rescanning. Identifying pre-seeded
+         * entries by matching `entry.source` against a list of source strings would
+         * spell them a second time, away from the sites that produce them — and a
+         * fourth pre-seeded source added later would then reopen #3049 in silence.
+         * `addRoute` deliberately does NOT record here: its routes ARE
+         * handler-resolved, so suppressing them would widen the guard into a bug of
+         * its own.
+         *
+         * Each `add` below sits inside its own `!routeRegistry.has(key)` gate, as
+         * every `routeRegistry.set` in this phase does: the map is write-once per
+         * key, so a losing candidate cannot record a key it did not claim and no
+         * later writer can take a recorded key away. Key-membership is therefore
+         * equivalent to source-matching by construction — pre-seeded routes carry no
+         * verb and `routeNodeKey(undefined, url) === url` — which is why the
+         * two-candidates-one-URL case needs no fixture to settle it.
+         */
+        const preSeededKeys = new Set();
         // Detect Expo Router app/ roots vs Next.js app/ roots (monorepo-safe)
         const expoAppRoots = new Set();
         const nextjsAppRoots = new Set();
@@ -125,32 +184,34 @@ export const routesPhase = {
                     expoAppPaths.add(p);
             }
         }
+        // One writer for every pre-seeded route, so recording membership cannot be
+        // forgotten. Inlining `has` / `set` / `add` at each site made the invariant
+        // a convention three call sites had to remember — and a fourth source that
+        // forgot the `add` would reopen #3049 exactly as silently as the source-set
+        // it replaced. This is the shape `claim()` in call-processor.ts uses for the
+        // same reason: one helper writes the collection and its key set together.
+        const preSeed = (url, entry) => {
+            if (routeRegistry.has(url))
+                return false;
+            routeRegistry.set(url, { ...entry, url });
+            preSeededKeys.add(url);
+            return true;
+        };
         for (const p of allPaths) {
             if (expoAppPaths.has(p)) {
                 const expoURL = expoFileToRouteURL(p);
-                if (expoURL && !routeRegistry.has(expoURL)) {
-                    routeRegistry.set(expoURL, {
-                        filePath: p,
-                        source: 'expo-filesystem-route',
-                        url: expoURL,
-                    });
+                if (expoURL && preSeed(expoURL, { filePath: p, source: 'expo-filesystem-route' })) {
                     continue;
                 }
             }
             const nextjsURL = nextjsFileToRouteURL(p);
-            if (nextjsURL && !routeRegistry.has(nextjsURL)) {
-                routeRegistry.set(nextjsURL, {
-                    filePath: p,
-                    source: 'nextjs-filesystem-route',
-                    url: nextjsURL,
-                });
+            if (nextjsURL && preSeed(nextjsURL, { filePath: p, source: 'nextjs-filesystem-route' })) {
                 continue;
             }
             if (p.endsWith('.php')) {
                 const phpURL = phpFileToRouteURL(p);
-                if (phpURL && !routeRegistry.has(phpURL)) {
-                    routeRegistry.set(phpURL, { filePath: p, source: 'php-file-route', url: phpURL });
-                }
+                if (phpURL)
+                    preSeed(phpURL, { filePath: p, source: 'php-file-route' });
             }
         }
         let duplicateRoutes = 0;
@@ -181,30 +242,60 @@ export const routesPhase = {
                 namedRouteRegistry.set(route.routeName, routeUrl);
             }
         }
-        for (const dr of allDecoratorRoutes) {
+        // A dispatch-guard route observed WITHOUT a verb is dropped when the same
+        // URL is claimed WITH one anywhere in the repo — the split route-table
+        // idiom, which no single file can reconcile. Framework routes are untouched;
+        // their verb-less form is a declaration, not a weaker observation.
+        for (const dr of reconcileDispatchGuardRoutes(allDecoratorRoutes)) {
             const url = normalizeExtractedRoutePath(dr.routePath, dr.prefix ?? null);
+            const method = normalizeRouteMethod(dr.httpMethod);
+            const routeKey = routeNodeKey(method, url);
+            // A data-table entry is only a provider route once its static handler has
+            // been proven. Other route sources retain their historical fallback.
+            if (dr.source === DATA_ROUTE_TABLE_SOURCE && !routeHandlerSymbols.has(routeKey))
+                continue;
             addRoute(url, {
                 filePath: dr.filePath,
-                source: `decorator-${dr.decoratorName}`,
-                method: normalizeRouteMethod(dr.httpMethod),
+                // A route extracted from a file's own AST is usually a decorator; a
+                // dispatch guard is the same transport with different provenance, and
+                // says so (`ExtractedDecoratorRoute.source`).
+                source: dr.source ?? `decorator-${dr.decoratorName}`,
+                method,
             });
         }
         let handlerContents;
         if (routeRegistry.size > 0) {
-            const handlerPaths = [...routeRegistry.values()].map((e) => e.filePath);
+            const handlerPathFor = (routeKey, entry) => {
+                if (entry.source !== DATA_ROUTE_TABLE_SOURCE)
+                    return entry.filePath;
+                const handlerSymbolId = routeHandlerSymbols.get(routeKey);
+                const resolvedPath = handlerSymbolId
+                    ? ctx.graph.getNode(handlerSymbolId)?.properties.filePath
+                    : undefined;
+                return typeof resolvedPath === 'string' ? resolvedPath : entry.filePath;
+            };
+            const handlerPaths = [...routeRegistry].map(([key, entry]) => handlerPathFor(key, entry));
             handlerContents = await readFileContents(ctx.repoPath, handlerPaths);
             for (const [routeKey, entry] of routeRegistry) {
-                const { filePath: handlerPath, source: routeSource, method: routeMethod, url } = entry;
+                const { source: routeSource, method: routeMethod, url } = entry;
+                const handlerPath = handlerPathFor(routeKey, entry);
                 const content = handlerContents.get(handlerPath);
-                const { responseKeys, errorKeys } = content
+                // A pre-seeded route can never legitimately appear in
+                // `routeHandlerSymbols`, so a key that does is a route that LOST (#3049).
+                const handlerSymbolId = preSeededKeys.has(routeKey)
+                    ? undefined
+                    : routeHandlerSymbols.get(routeKey);
+                const analysisContent = entry.source === DATA_ROUTE_TABLE_SOURCE && content
+                    ? handlerSymbolContent(content, handlerSymbolId ? ctx.graph.getNode(handlerSymbolId) : undefined)
+                    : content;
+                const { responseKeys, errorKeys } = analysisContent
                     ? handlerPath.endsWith('.php')
-                        ? extractPHPResponseShapes(content)
-                        : extractResponseShapes(content)
+                        ? extractPHPResponseShapes(analysisContent)
+                        : extractResponseShapes(analysisContent)
                     : { responseKeys: undefined, errorKeys: undefined };
-                const mwResult = content ? extractMiddlewareChain(content) : undefined;
+                const mwResult = analysisContent ? extractMiddlewareChain(analysisContent) : undefined;
                 const middleware = mwResult?.chain;
                 const routeNodeId = generateId('Route', routeKey);
-                const handlerSymbolId = routeHandlerSymbols.get(routeKey);
                 ctx.graph.addNode({
                     id: routeNodeId,
                     label: 'Route',