gitnexus 1.6.10-rc.21 → 1.6.10-rc.211

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, 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';
@@ -26,12 +26,16 @@ 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 { 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
@@ -278,7 +350,8 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
     const skippedByLang = new Map();
     for (const f of scannedFiles) {
         const lang = getLanguageFromFilename(f.path);
-        if (lang && !isLanguageAvailable(lang)) {
+        const provider = lang === null ? undefined : getProvider(lang);
+        if (lang && provider?.parseStrategy !== 'standalone' && !isLanguageAvailable(lang)) {
             skippedByLang.set(lang, (skippedByLang.get(lang) || 0) + 1);
         }
     }
@@ -364,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;
@@ -675,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
@@ -777,6 +873,17 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
                 // Cache miss: dispatch to workers, capture the raw results, store
                 // them under the chunk hash for the next run.
                 chunkCacheMisses++;
+                if (durableParsedFileDir !== undefined && chunkHash !== null) {
+                    try {
+                        await prepareDurableParsedFileChunk(durableParsedFileDir, chunkHash);
+                    }
+                    catch (err) {
+                        // The durable store is an optimization — degrade like the restore
+                        // path does instead of failing the analyze. Workers recreate the
+                        // directory on write, so at worst the old generation lingers.
+                        logger.warn({ err, chunkHash: chunkHash.slice(0, 8) }, 'parsedfile-cache: could not reset durable chunk generation; continuing');
+                    }
+                }
                 const progressForChunk = (current, _total, filePath) => {
                     const globalCurrent = filesParsedSoFar + current;
                     // Parse phase covers 20-70 (M2). Deferred extraction handles 70-95.
@@ -1151,9 +1258,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';
@@ -13,4 +14,12 @@ import { type ProcessDetectionResult } from '../process-processor.js';
 export interface ProcessesOutput {
     processResult: ProcessDetectionResult;
 }
+/**
+ * Compute the dynamic max-processes budget from the symbol count.
+ *
+ * Scales proportionally (symbolCount / 10) with a floor of 20.
+ * Prior to #2198 this was capped at 300 via `Math.min(300, …)`,
+ * silently truncating process detection on large repositories.
+ */
+export declare function computeDynamicMaxProcesses(symbolCount: number): number;
 export declare const processesPhase: PipelinePhase<ProcessesOutput>;

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';
@@ -14,13 +15,31 @@ import { generateId } from '../../../lib/utils.js';
 import { routeNodeKey } from '../route-extractors/route-path.js';
 import { isDev } from '../utils/env.js';
 import { logger } from '../../logger.js';
+/**
+ * Compute the dynamic max-processes budget from the symbol count.
+ *
+ * Scales proportionally (symbolCount / 10) with a floor of 20.
+ * Prior to #2198 this was capped at 300 via `Math.min(300, …)`,
+ * silently truncating process detection on large repositories.
+ */
+export function computeDynamicMaxProcesses(symbolCount) {
+    return Math.max(20, Math.round(symbolCount / 10));
+}
 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');
@@ -37,7 +56,33 @@ export const processesPhase = {
             if (n.label !== 'File')
                 symbolCount++;
         });
-        const dynamicMaxProcesses = Math.max(20, Math.min(300, Math.round(symbolCount / 10)));
+        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({
@@ -46,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,
@@ -181,30 +201,56 @@ 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
+                const handlerSymbolId = 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',

package/dist/core/ingestion/pipeline-phases/spring-aop.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Phase: springAop
+ *
+ * Materializes statically visible Spring proxy/advice behavior after every
+ * language resolver has attached normalized metadata to the shared graph.
+ * The post-MRO export in this file propagates declarative behavior through
+ * METHOD_OVERRIDES/METHOD_IMPLEMENTS without changing @annotation semantics.
+ *
+ * @deps    scopeResolution
+ * @reads   Class/Method nodes, HAS_METHOD edges, shared Spring AOP metadata
+ * @writes  synthetic CodeElement nodes, DEFINES/DECLARES/ADVISED_BY edges
+ */
+import type { PipelinePhase } from './types.js';
+export declare const DEFAULT_SPRING_AOP_MAX_CANDIDATE_INSPECTIONS_PER_ADVICE = 100000;
+export declare const DEFAULT_SPRING_AOP_MAX_CANDIDATE_INSPECTIONS = 2000000;
+export declare const DEFAULT_SPRING_AOP_MAX_ADVISED_EDGES_PER_ADVICE = 25000;
+export declare const DEFAULT_SPRING_AOP_MAX_ADVISED_EDGES = 100000;
+export interface SpringAopOutput {
+    readonly advisedByEdges: number;
+    readonly evidenceNodes: number;
+    readonly unresolvedPointcuts: number;
+    readonly candidateInspections: number;
+    readonly truncatedAdvices: number;
+}
+export interface SpringAopInheritanceOutput {
+    readonly inheritedBehaviorEdges: number;
+}
+export declare const springAopPhase: PipelinePhase<SpringAopOutput>;
+/**
+ * Propagate behavior evidence across the inheritance decisions materialized by
+ * MRO. This is deliberately separate from pointcut matching: `@annotation`
+ * continues to mean an annotation declared directly on the callable.
+ */
+export declare const springAopInheritancePhase: PipelinePhase<SpringAopInheritanceOutput>;