gitnexus 1.6.11-rc.9 → 1.6.11

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

@@ -16,6 +16,7 @@ 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 { springDestinationsPhase } from './spring-destinations.js';
 export { springAutoConfigurationPhase, } from './spring-auto-configuration.js';
 export { springAopPhase, springAopInheritancePhase, } from './spring-aop.js';
 export { pruneLocalSymbolsPhase } from './prune-local-symbols.js';

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

@@ -2,7 +2,7 @@
  * Parse implementation — chunked parse + resolve loop.
  *
  * This is the core parsing engine of the ingestion pipeline. It reads
- * source files in byte-budget chunks (~20MB each), parses via the worker
+ * source files in stable hash-bucket packs (~2MB each by default), parses via the worker
  * pool (the sole parse path — there is no sequential fallback), and emits
  * route CALLS edges. Import,
  * call, and inheritance resolution are owned by the scope-resolution
@@ -19,6 +19,7 @@ import { type ExportedTypeMap } from '../call-processor.js';
 import { type MutableSemanticModel } from '../model/index.js';
 import { type PipelineProgress } from '../../../_shared/index.js';
 import type { ExtractedDecoratorRoute, ExtractedFetchCall, ExtractedORMQuery, ExtractedRoute, ExtractedToolDef, FetchWrapperDef } from '../workers/parse-worker.js';
+import type { ModuleConstants } from '../route-extractors/constant-resolver.js';
 import type { KnowledgeGraph } from '../../graph/types.js';
 import type { PipelineOptions } from '../pipeline.js';
 /** Projected main-thread heap need for the parse phase (#2649). */
@@ -96,11 +97,16 @@ export declare function runChunkedParseAndResolve(graph: KnowledgeGraph, scanned
     usedWorkerPool: boolean;
     /** Files dispatched to parser workers after parse-cache lookup. */
     reparsedFileCount: number;
+    /** Files restored from parse-cache chunks without parser-worker dispatch. */
+    parseCacheHitFileCount: number;
     /** Worker-produced ParsedFile artifacts aggregated across chunks.
      *  Threaded into scope-resolution as a re-extract cache so the warm-
      *  cache analyze run can skip the dominant `extractParsedFile` cost
      *  (otherwise ~58s on a 1000-file repo). */
     parsedFiles: import('../../../_shared/index.js').ParsedFile[];
+    /** Repo-wide harvested constants, already prepared per provider. See
+     *  `ParseOutput.moduleConstants` for why this leaves the parse phase. */
+    moduleConstants: ReadonlyMap<string, ModuleConstants>;
     scopeExtractionFailures: string[];
     /** Files excluded because their non-standalone language parser was unavailable. */
     unavailableScopeLanguageFiles: number;

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

@@ -2,7 +2,7 @@
  * Parse implementation — chunked parse + resolve loop.
  *
  * This is the core parsing engine of the ingestion pipeline. It reads
- * source files in byte-budget chunks (~20MB each), parses via the worker
+ * source files in stable hash-bucket packs (~2MB each by default), parses via the worker
  * pool (the sole parse path — there is no sequential fallback), and emits
  * route CALLS edges. Import,
  * call, and inheritance resolution are owned by the scope-resolution
@@ -16,8 +16,8 @@
  */
 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, loadParsedFilesForPaths, getDurableParsedFileDir, loadDurableParsedFileIndex, prepareDurableParsedFileChunk, restoreDurableParsedFileShard, } from '../../../storage/parsedfile-store.js';
+import { fileContentHash, computeChunkHash, loadParseCacheChunk, persistParseCacheChunk, PARSE_CACHE_VERSION, packParseCacheChunks, } from '../../../storage/parse-cache.js';
+import { clearParsedFileStore, persistParsedFileChunk, loadParsedFilesForPaths, getDurableParsedFileDir, loadDurableParsedFileIndex, prepareDurableParsedFileChunk, durableChunkHasShards, } from '../../../storage/parsedfile-store.js';
 import { DEFAULT_PDG_MAX_FUNCTION_LINES } from '../cfg/collect.js';
 import { processRoutesFromExtracted, resolveRouteHandlerSymbols, buildExportedTypeMapFromGraph, } from '../call-processor.js';
 import { createSemanticModel } from '../model/index.js';
@@ -30,7 +30,8 @@ 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 { resolveOperands } from '../route-extractors/python-const-resolver.js';
+import { prepareRouteConstantsByProvider } from '../language-provider.js';
 import { resolveInheritedSpringRoutes, } from '../route-extractors/spring-shared.js';
 import fs from 'node:fs';
 import { effectiveRamBytes, memoryAutopilotDisabled } from '../utils/effective-ram.js';
@@ -111,38 +112,18 @@ export function heapPressureRemedy(heapLimitBytes) {
     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.
+/** Max bytes of source content to load per parse cache pack.
  *
- * Memory bound for the worker pool dispatch + a granularity knob for
- * the parse cache. A single file change invalidates only its enclosing
- * chunk, so smaller budgets → finer-grained invalidation.
- *
- * Override via GITNEXUS_CHUNK_BYTE_BUDGET (bytes) — the default of 2MB
- * gives a useful invalidation floor (~1/N chunks on a multi-MB repo)
- * while keeping worker dispatch overhead under 5% on cold runs.
- */
-/**
- * Built-in chunk byte budget when neither `PipelineOptions.chunkByteBudget`
- * nor `GITNEXUS_CHUNK_BYTE_BUDGET` is set. Tuned to give a useful
- * cache-invalidation floor (~1/N chunks on a multi-MB repo) while keeping
- * worker dispatch overhead under 5% on cold runs. Resolution happens at
- * call time inside `runChunkedParseAndResolve` (U14 from PR #1693 review)
- * — previously this was a module-load IIFE, which froze the env value at
- * import time and meant per-call option threading silently no-op'd.
+ * Granularity knob for the parse cache: a single file change invalidates only
+ * its enclosing pack. Override via GITNEXUS_CHUNK_BYTE_BUDGET. Resolution
+ * happens at call time (U14 from PR #1693) — not at module load.
  */
 const DEFAULT_CHUNK_BYTE_BUDGET = 2 * 1024 * 1024;
 /**
- * Per-worker share of a chunk's byte budget when auto-scaling (#worker-idle).
- *
- * A chunk is a single `WorkerPool.dispatch` unit; the pool fans a chunk's files
- * into sub-batch jobs and assigns them to idle workers (`wakeIdleSlots`). When
- * the chunk budget (2 MB) was far below the 8 MB sub-batch cap, every chunk
- * produced exactly ONE job → ONE busy worker while the other N-1 sat idle. To
- * keep all workers fed, the auto chunk budget now scales as
- * `poolSize × CHUNK_BYTES_PER_WORKER`, so each dispatch carries enough work to
- * fan across the whole pool. Sequential / explicit-budget runs are unaffected.
+ * Byte unit for auto pool sizing (one worker per this much source). Same
+ * magnitude as the default cache pack, but not a membership input (#3088).
  */
-const CHUNK_BYTES_PER_WORKER = 2 * 1024 * 1024;
+const CHUNK_BYTES_PER_WORKER = DEFAULT_CHUNK_BYTE_BUDGET;
 /**
  * Target jobs-per-worker per dispatch. More jobs than workers gives the pool's
  * idle-slot assignment room to load-balance (a slow job doesn't strand a worker
@@ -151,16 +132,14 @@ const CHUNK_BYTES_PER_WORKER = 2 * 1024 * 1024;
 const TARGET_JOBS_PER_WORKER = 3;
 /** Floor for a derived sub-batch so jobs don't shrink to per-file IPC churn. */
 const MIN_SUB_BATCH_BYTES = 256 * 1024;
-function resolveChunkByteBudget(options, effectivePoolSize = 1) {
+function resolveChunkByteBudget(options) {
     const opt = options?.chunkByteBudget;
     if (typeof opt === 'number' && Number.isFinite(opt) && opt > 0)
         return opt;
     const env = Number(process.env.GITNEXUS_CHUNK_BYTE_BUDGET);
     if (Number.isFinite(env) && env > 0)
         return env;
-    // Auto: size each chunk so a dispatch can fan across the whole pool. A
-    // single-worker (tiny-repo) run keeps the original 2 MB invalidation floor.
-    return Math.max(DEFAULT_CHUNK_BYTE_BUDGET, effectivePoolSize * CHUNK_BYTES_PER_WORKER);
+    return DEFAULT_CHUNK_BYTE_BUDGET;
 }
 /**
  * Whole-repo, cross-file route extraction (main thread).
@@ -367,14 +346,6 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
         }
     }
     const unavailableScopeLanguageFiles = [...skippedByLang.values()].reduce((total, count) => total + count, 0);
-    // Sort parseableScanned alphabetically for stable chunk membership
-    // across runs (Finding 4). Without this, filesystem-scan order can
-    // shift between runs (notably on macOS APFS where directory entry
-    // order can change after modifications) — different files in the
-    // same chunk → different chunk hash → cache miss even when no file
-    // content changed. The cache also becomes platform-specific: a
-    // Linux-built cache misses on macOS for the same repo.
-    parseableScanned.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
     const totalParseable = parseableScanned.length;
     const totalBytes = parseableScanned.reduce((sum, f) => sum + f.size, 0);
     if (totalParseable === 0) {
@@ -416,24 +387,24 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
     // runs. Resolving in the function body restores per-call configurability
     // and matches the pattern used by resolveAutoPoolSize and the U1
     // parseChunkConcurrency resolver.
-    // Effective worker count, computed up-front so the chunk budget can scale to
-    // keep the whole pool busy (#worker-idle). The pool is ALWAYS used (sequential
-    // parsing was removed; the disabled channels threw above). Size it to the
-    // work: an explicit `--workers <N>` pins the size; otherwise the cores-based
-    // auto size is capped by the repo's worth of work (~one worker per
-    // CHUNK_BYTES_PER_WORKER of source) so a tiny repo spawns ~1 worker instead of
-    // a full pool, replacing the job the deleted small-repo threshold used to do.
-    // KTD-3 of the remove-sequential plan; the cap formula is intentionally coarse
-    // (tuning deferred).
+    // Effective worker count: explicit `--workers <N>` pins it; otherwise
+    // cores-based auto size is capped by source bytes / CHUNK_BYTES_PER_WORKER
+    // so a tiny repo does not spawn a full idle pool. Cache pack membership
+    // is independent of this number (#3088).
     const explicitPoolSize = options?.workerPoolSize;
     const workProportionalCap = Math.max(1, Math.ceil(totalBytes / CHUNK_BYTES_PER_WORKER));
     const effectivePoolSize = explicitPoolSize && explicitPoolSize > 0
         ? explicitPoolSize
         : Math.min(resolveAutoPoolSize(), workProportionalCap);
-    const chunkByteBudget = resolveChunkByteBudget(options, effectivePoolSize);
-    // Sub-batch size so each chunk fans into ~`TARGET_JOBS_PER_WORKER` jobs per
-    // worker, giving the pool's idle-slot assignment room to load-balance. An
-    // explicit `GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES` operator override wins.
+    // Cache packs: stable (language, hash(path) mod 128) buckets, then the
+    // per-call byte budget inside each bucket (#3088). Pool size is used only
+    // for worker count and sub-batch fan-out, not membership.
+    const chunkByteBudget = resolveChunkByteBudget(options);
+    // Sub-batch size so a 2 MiB pack fans into ~TARGET_JOBS_PER_WORKER jobs
+    // per worker, floored at MIN_SUB_BATCH_BYTES (256 KiB) so an 8-worker
+    // pool still gets ~8 jobs from one pack instead of one idle-heavy job
+    // (#worker-idle). Do not derive this from pool×2 MiB while dispatching a
+    // 2 MiB pack. An explicit GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES wins.
     const subBatchEnv = Number(process.env.GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES);
     const dispatchSubBatchMaxBytes = Number.isFinite(subBatchEnv) && subBatchEnv > 0
         ? subBatchEnv
@@ -451,20 +422,11 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
         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;
-    for (const file of parseableScanned) {
-        if (currentChunk.length > 0 && currentBytes + file.size > chunkByteBudget) {
-            chunks.push(currentChunk);
-            currentChunk = [];
-            currentBytes = 0;
-        }
-        currentChunk.push(file.path);
-        currentBytes += file.size;
-    }
-    if (currentChunk.length > 0)
-        chunks.push(currentChunk);
+    const chunks = packParseCacheChunks(parseableScanned.map((file) => ({
+        path: file.path,
+        size: file.size,
+        language: getLanguageFromFilename(file.path) ?? 'unknown',
+    })), chunkByteBudget);
     const numChunks = chunks.length;
     if (isDev) {
         const totalMB = parseableScanned.reduce((s, f) => s + f.size, 0) / (1024 * 1024);
@@ -586,15 +548,16 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
     // a sibling of the run-scoped store, NOT cleared per run. Workers write a
     // shard per chunk hash; on a warm parse-cache hit we restore the chunk's
     // shards into the run-scoped store so scope-resolution streams them without
-    // re-parsing. `durableHitKeys` is the prior run's index, version-gated by
-    // PARSE_CACHE_VERSION (a mismatch ⇒ empty ⇒ every chunk re-dispatches, which
-    // repopulates the durable store — never the main-thread extract fallback).
+    // re-parsing. `durableHitEntries` is the prior run's path-coverage index,
+    // version-gated by PARSE_CACHE_VERSION (a mismatch ⇒ empty ⇒ every chunk
+    // re-dispatches, which repopulates the durable store).
     const durableParsedFileDir = parsedFileStorePath !== undefined ? getDurableParsedFileDir(parsedFileStorePath) : undefined;
-    const durableHitKeys = durableParsedFileDir !== undefined
+    const durableHitEntries = durableParsedFileDir !== undefined
         ? await loadDurableParsedFileIndex(durableParsedFileDir, PARSE_CACHE_VERSION)
-        : new Set();
+        : new Map();
     let chunkCacheHits = 0;
     let chunkCacheMisses = 0;
+    let parseCacheHitFileCount = 0;
     let reparsedFileCount = 0;
     try {
         // U1 — bounded chunk concurrency (B1 from PR #1693 review): pre-fetch
@@ -646,7 +609,11 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
                 }
                 if (chunkWorkerData.parsedFiles?.length) {
                     if (parsedFileStorePath) {
-                        await persistParsedFileChunk(parsedFileStorePath, `chunk-${chunkIdx}`, chunkWorkerData.parsedFiles);
+                        const wrote = await persistParsedFileChunk(parsedFileStorePath, `chunk-${chunkIdx}`, chunkWorkerData.parsedFiles);
+                        if (!wrote) {
+                            for (const item of chunkWorkerData.parsedFiles)
+                                allParsedFiles.push(item);
+                        }
                     }
                     else {
                         for (const item of chunkWorkerData.parsedFiles)
@@ -833,7 +800,14 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
             // store was introduced, or a pruned/version-stale shard — fall through to
             // a worker re-dispatch to repopulate them. NEVER let scope-resolution
             // re-extract on the main thread (the #1983 OOM the durable store closes).
-            const durableHit = chunkHash !== null && durableParsedFileDir !== undefined && durableHitKeys.has(chunkHash);
+            const durableExpectedPaths = chunkHash === null ? undefined : durableHitEntries.get(chunkHash);
+            const durableHit = cachedRaw !== undefined &&
+                cachedRaw.length > 0 &&
+                chunkHash !== null &&
+                durableParsedFileDir !== undefined &&
+                parsedFileStorePath !== undefined &&
+                durableExpectedPaths !== undefined &&
+                (await durableChunkHasShards(parsedFileStorePath, chunkHash, durableExpectedPaths));
             if (cachedRaw && cachedRaw.length > 0 && (durableHit || parsedFileStorePath === undefined)) {
                 // Cache hit: replay cached worker output. Finalize any parked worker
                 // chunk FIRST so deferred aggregation stays in chunk order, then merge
@@ -843,6 +817,7 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
                     pendingWorkerChunk = null;
                 }
                 chunkCacheHits++;
+                parseCacheHitFileCount += chunkFiles.length;
                 const chunkWorkerData = mergeChunkResults(graph, symbolTable, cachedRaw, exportedTypeMap);
                 if (isDev) {
                     logger.info(`📦 parse-cache HIT: chunk ${chunkIdx + 1}/${numChunks} (${chunkFiles.length} files, ${chunkHash?.slice(0, 8) ?? 'unknown'})`);
@@ -863,16 +838,8 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
                         nodesCreated: graph.nodeCount,
                     },
                 });
-                // Restore the chunk's durable ParsedFile shards into the run-scoped
-                // store so scope-resolution finds full coverage with ZERO main-thread
-                // re-parse. A verbatim byte copy — byte-identical to a cold run.
-                if (durableHit && durableParsedFileDir && parsedFileStorePath && chunkHash) {
-                    const restored = await restoreDurableParsedFileShard(durableParsedFileDir, parsedFileStorePath, chunkHash);
-                    if (restored === 0) {
-                        logger.warn(`parsedfile-cache: durable shards missing for cached chunk ` +
-                            `${chunkHash.slice(0, 8)} — scope-resolution will re-extract these files`);
-                    }
-                }
+                // The durable gate already snapshotted warm `.v8` shards into the
+                // run-scoped store for scope resolution.
                 await applyChunkResults(chunkWorkerData, chunkIdx, chunkFiles, chunkStartMs);
             }
             else {
@@ -1053,11 +1020,27 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
     // carries `routePathExpr`/`routePathOperands` and an empty `routePath`; we fold
     // the operands against the repo-wide, file-path-keyed constant map. On failure
     // we DROP the route (KTD5 skip floor) rather than emit a phantom `POST /`.
+    //
+    // Built (and prepared) UNCONDITIONALLY when anything was harvested, because
+    // the map is also handed to downstream phases on `ParseOutput.moduleConstants`
+    // — `springDestinations` folds broker-address constants against exactly the
+    // same table. Preparation runs exactly once, here, on one map, before either
+    // consumer folds. Deferring it into each consumer instead would need
+    // `prepareRouteConstants` to be safe to call twice — it materializes deferred
+    // wildcard bindings IN PLACE — or would leave whichever consumer ran first
+    // folding against unprepared constants. Neither is worth the coupling; the
+    // cost here is one pass over the harvested constants of a repo that has some.
+    const repoConstants = new Map();
+    for (const { filePath, constants } of allModuleConstants) {
+        repoConstants.set(filePath, constants);
+    }
+    if (repoConstants.size > 0) {
+        // Let each language prepare only its own constants slice before folding.
+        // This is where deferred wildcard bindings can be materialized once per
+        // provider without naming a language in the shared parse phase.
+        prepareRouteConstantsByProvider(repoConstants, getProviderForFile);
+    }
     if (allDecoratorRoutes.some((dr) => dr.routePathExpr !== undefined)) {
-        const repoConstants = new Map();
-        for (const { filePath, constants } of allModuleConstants) {
-            repoConstants.set(filePath, constants);
-        }
         const resolvedRoutes = [];
         let skipped = 0;
         for (const dr of allDecoratorRoutes) {
@@ -1343,11 +1326,16 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
         // is intentionally measured at dispatch time rather than inferred from
         // the git/hash diff.
         reparsedFileCount,
+        parseCacheHitFileCount,
         // Per-file ParsedFile artifacts produced by workers' calls to
         // `extractParsedFile`. Consumed by scope-resolution as a re-extraction
         // cache: when the file's ParsedFile is here, scope-resolution skips its own
         // `extractParsedFile` call.
         parsedFiles: allParsedFiles,
+        // Repo-wide, file-path-keyed constants, already through each provider's
+        // `prepareRouteConstants` hook. Empty when no provider harvests constants
+        // for the languages in this repo.
+        moduleConstants: repoConstants,
         scopeExtractionFailures: [...scopeExtractionFailures].sort(),
         unavailableScopeLanguageFiles,
     };

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

@@ -20,6 +20,7 @@ import type { BindingAccumulator } from '../binding-accumulator.js';
 import type { ParsedFile } from '../../../_shared/index.js';
 import type { ExtractedFetchCall, ExtractedRoute, ExtractedDecoratorRoute, ExtractedToolDef, ExtractedORMQuery, FetchWrapperDef } from '../workers/parse-worker.js';
 import type { MutableSemanticModel } from '../model/index.js';
+import type { ModuleConstants } from '../route-extractors/constant-resolver.js';
 export interface ParseOutput {
     /**
      * Read-only snapshot of exported type bindings keyed by file path.
@@ -70,6 +71,22 @@ export interface ParseOutput {
      * costing ~58s on a 1000-file repo).
      */
     readonly parsedFiles: readonly ParsedFile[];
+    /**
+     * Repo-wide string constants harvested by the providers that declare
+     * `extractModuleConstants`, keyed by file path and already through each
+     * provider's `prepareRouteConstants` hook.
+     *
+     * Exposed so a later phase can fold a constant reference the same way the
+     * decorator-route pass does — `springDestinations` resolves a broker address
+     * written as `Topics.ORDERS` against this table. It is a snapshot: parse does
+     * not mutate it after returning, and consumers must not either, because the
+     * preparation that made it foldable has already run.
+     *
+     * Empty when no provider in this repo harvests constants. A downstream fold
+     * against an empty table simply fails to resolve, which is a recorded refusal
+     * rather than a wrong answer.
+     */
+    readonly moduleConstants: ReadonlyMap<string, ModuleConstants>;
     /** Files whose scope extraction failed while legacy parsing continued. */
     readonly scopeExtractionFailures: readonly string[];
     /** Files omitted because their non-standalone language parser was unavailable. */

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

@@ -4,7 +4,8 @@
  * Detects execution flows (processes) and creates Process nodes +
  * STEP_IN_PROCESS edges. Also links Route/Tool nodes to processes.
  *
- * @deps    communities, routes, tools, pruneLocalSymbols, structure, parse
+ * @deps    communities, routes, tools, springAutoConfiguration,
+ *          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)

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

@@ -4,7 +4,8 @@
  * Detects execution flows (processes) and creates Process nodes +
  * STEP_IN_PROCESS edges. Also links Route/Tool nodes to processes.
  *
- * @deps    communities, routes, tools, pruneLocalSymbols, structure, parse
+ * @deps    communities, routes, tools, springAutoConfiguration,
+ *          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)
@@ -39,7 +40,15 @@ export const processesPhase = {
     // 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', 'parse'],
+    deps: [
+        'communities',
+        'routes',
+        'tools',
+        'springAutoConfiguration',
+        'pruneLocalSymbols',
+        'structure',
+        'parse',
+    ],
     async execute(ctx, deps) {
         const { totalFiles } = getPhaseOutput(deps, 'structure');
         const { communityResult } = getPhaseOutput(deps, 'communities');
@@ -172,8 +181,34 @@ export const processesPhase = {
                 step: step.step,
             });
         });
+        // The static registry is finalized before Spring runtime enrichment. Merge
+        // runtime-confirmed Route nodes from the graph after the explicit
+        // springAutoConfiguration dependency has completed, so Actuator-only
+        // mappings participate in the same process-linking path.
+        const processRouteRegistry = new Map(routeRegistry);
+        ctx.graph.forEachNode((node) => {
+            if (node.label !== 'Route' ||
+                node.properties.runtimeSource !== 'spring-actuator' ||
+                node.properties.runtimeConfirmed !== true) {
+                return;
+            }
+            const url = typeof node.properties.name === 'string' ? node.properties.name : undefined;
+            const filePath = typeof node.properties.filePath === 'string' ? node.properties.filePath : undefined;
+            const method = typeof node.properties.method === 'string' ? node.properties.method : undefined;
+            if (url === undefined || filePath === undefined)
+                return;
+            const key = routeNodeKey(method, url);
+            if (!processRouteRegistry.has(key)) {
+                processRouteRegistry.set(key, {
+                    filePath,
+                    source: 'spring-actuator-runtime',
+                    url,
+                    ...(method === undefined ? {} : { method }),
+                });
+            }
+        });
         // Link Route and Tool nodes to Processes
-        if (routeRegistry.size > 0 || toolDefs.length > 0) {
+        if (processRouteRegistry.size > 0 || toolDefs.length > 0) {
             // Two-tier route lookup, mirroring the tool tables 10 lines below.
             // Routes whose handler resolved key by `handlerSymbolId` (read from
             // the Route node's graph properties — routes.ts stamps it there) and
@@ -188,7 +223,7 @@ export const processesPhase = {
             // routes phase stamps on the Route node was never consulted.
             const routesByHandlerId = new Map();
             const routesWithoutHandlerByFile = new Map();
-            for (const [, entry] of routeRegistry) {
+            for (const [, entry] of processRouteRegistry) {
                 // Push the Route node identity (`routeNodeKey`), not the bare URL, so the
                 // ENTRY_POINT_OF edge targets the same node id the routes phase created
                 // (#2289: a same-URL GET/POST pair is two distinct Route nodes).

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

@@ -265,28 +265,25 @@ export const routesPhase = {
         }
         let handlerContents;
         if (routeRegistry.size > 0) {
-            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
+            // Resolve once so content attribution, the route stamp, and the edge use
+            // the same live graph node. Pre-seeded routes never own handler symbols.
+            const routes = [...routeRegistry].map(([routeKey, entry]) => {
+                const id = preSeededKeys.has(routeKey) ? undefined : routeHandlerSymbols.get(routeKey);
+                const node = id ? ctx.graph.getNode(id) : undefined;
+                const handlerSymbol = id && node ? { id, node } : undefined;
+                const resolvedPath = entry.source === DATA_ROUTE_TABLE_SOURCE
+                    ? handlerSymbol?.node.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 handlerPath = typeof resolvedPath === 'string' ? resolvedPath : entry.filePath;
+                return { routeKey, entry, handlerSymbol, handlerPath };
+            });
+            handlerContents = await readFileContents(ctx.repoPath, routes.map(({ handlerPath }) => handlerPath));
+            for (const { routeKey, entry, handlerSymbol, handlerPath } of routes) {
                 const { source: routeSource, method: routeMethod, url } = entry;
-                const handlerPath = handlerPathFor(routeKey, entry);
                 const content = handlerContents.get(handlerPath);
-                // 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 handlerSymbolId = handlerSymbol?.id;
                 const analysisContent = entry.source === DATA_ROUTE_TABLE_SOURCE && content
-                    ? handlerSymbolContent(content, handlerSymbolId ? ctx.graph.getNode(handlerSymbolId) : undefined)
+                    ? handlerSymbolContent(content, handlerSymbol?.node)
                     : content;
                 const { responseKeys, errorKeys } = analysisContent
                     ? handlerPath.endsWith('.php')
@@ -318,6 +315,18 @@ export const routesPhase = {
                     confidence: 1.0,
                     reason: routeSource,
                 });
+                // Keep the file edge for existing extractor queries; add the live
+                // definition edge for explicit handler-level traversal.
+                if (handlerSymbolId) {
+                    ctx.graph.addRelationship({
+                        id: generateId('HANDLES_ROUTE', `${handlerSymbolId}->${routeNodeId}`),
+                        sourceId: handlerSymbolId,
+                        targetId: routeNodeId,
+                        type: 'HANDLES_ROUTE',
+                        confidence: 1.0,
+                        reason: routeSource,
+                    });
+                }
             }
             if (isDev) {
                 logger.info(`🗺️ Route registry: ${routeRegistry.size} routes${duplicateRoutes > 0 ? ` (${duplicateRoutes} duplicate URLs skipped)` : ''}`);

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

@@ -17,6 +17,9 @@ import type { PipelinePhase, PipelineContext, PhaseResult } from './types.js';
  *
  * @param phases  All phases to execute (order doesn't matter — sorted internally)
  * @param ctx     Shared pipeline context
+ * @param seed    Results of phases that already ran against this same context,
+ *                available to `phases` as dependencies (#3016 deferred derived
+ *                phases). Included in the returned map.
  * @returns       Map of phase name → PhaseResult (all completed phases)
  */
-export declare function runPipeline(phases: readonly PipelinePhase[], ctx: PipelineContext): Promise<ReadonlyMap<string, PhaseResult<unknown>>>;
+export declare function runPipeline(phases: readonly PipelinePhase[], ctx: PipelineContext, seed?: ReadonlyMap<string, PhaseResult<unknown>>): Promise<ReadonlyMap<string, PhaseResult<unknown>>>;

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

@@ -13,22 +13,30 @@
  */
 import { isDev } from '../utils/env.js';
 import { logger } from '../../logger.js';
-/**
- * Validate that the phases form a valid dependency graph (no cycles, all deps present).
- * Returns phases in topological execution order.
- */
-function topologicalSort(phases) {
-    const phaseMap = new Map();
+function assertUniquePhaseNames(phases) {
+    const seen = new Set();
     for (const phase of phases) {
-        if (phaseMap.has(phase.name)) {
+        if (seen.has(phase.name)) {
             throw new Error(`Duplicate phase name: '${phase.name}'`);
         }
-        phaseMap.set(phase.name, phase);
+        seen.add(phase.name);
     }
+}
+/**
+ * Validate that the phases form a valid dependency graph (no cycles, all deps present).
+ * Returns phases in topological execution order.
+ *
+ * `satisfied` names phases whose results are already available (a deferred
+ * follow-up run over the same context, #3016). Their edges are dropped rather
+ * than validated, because they are resolved by definition.
+ */
+function topologicalSort(phases, satisfied = new Set()) {
+    assertUniquePhaseNames(phases);
+    const phaseMap = new Map(phases.map((p) => [p.name, p]));
     // Validate all deps exist
     for (const phase of phases) {
         for (const dep of phase.deps) {
-            if (!phaseMap.has(dep)) {
+            if (!phaseMap.has(dep) && !satisfied.has(dep)) {
                 throw new Error(`Phase '${phase.name}' depends on '${dep}', which is not registered`);
             }
         }
@@ -37,8 +45,9 @@ function topologicalSort(phases) {
     const inDegree = new Map();
     const reverseDeps = new Map();
     for (const phase of phases) {
-        inDegree.set(phase.name, phase.deps.length);
-        for (const dep of phase.deps) {
+        const pendingDeps = phase.deps.filter((dep) => !satisfied.has(dep));
+        inDegree.set(phase.name, pendingDeps.length);
+        for (const dep of pendingDeps) {
             let rev = reverseDeps.get(dep);
             if (!rev) {
                 rev = [];
@@ -125,12 +134,23 @@ function findCyclePath(remaining, phaseMap) {
  *
  * @param phases  All phases to execute (order doesn't matter — sorted internally)
  * @param ctx     Shared pipeline context
+ * @param seed    Results of phases that already ran against this same context,
+ *                available to `phases` as dependencies (#3016 deferred derived
+ *                phases). Included in the returned map.
  * @returns       Map of phase name → PhaseResult (all completed phases)
  */
-export async function runPipeline(phases, ctx) {
+export async function runPipeline(phases, ctx, seed) {
+    // A seeded phase has already run against this context; re-running it would
+    // apply its graph writes a second time. "Already ran" is the whole meaning of
+    // the seed, so honour it here rather than making every caller pre-filter.
+    const satisfied = new Set(seed?.keys() ?? []);
     let sorted;
     try {
-        sorted = topologicalSort(phases);
+        // Duplicate names must be rejected on the caller-supplied list *before*
+        // seed-filtering. Filtering first would drop a seeded duplicate and let
+        // `topologicalSort` see a unique name (#3102).
+        assertUniquePhaseNames(phases);
+        sorted = topologicalSort(phases.filter((p) => !satisfied.has(p.name)), satisfied);
     }
     catch (err) {
         // Emit a terminal 'error' progress event for graph-validation failures
@@ -152,7 +172,7 @@ export async function runPipeline(phases, ctx) {
         }
         throw err;
     }
-    const results = new Map();
+    const results = new Map(seed);
     for (const phase of sorted) {
         const start = Date.now();
         if (isDev) {