gitnexus 1.6.9-rc.7 → 1.6.9-rc.8

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

@@ -574,6 +574,24 @@ function scanSpringProject(files) {
 export const JAVA_HTTP_PLUGIN = {
     name: 'java-http',
     language: Java,
+    // routeCoverage intentionally LEFT at the default 'partial' (#2138 Part 2).
+    // The graph provider set is a strict *subset* of this scan()'s provider set —
+    // ingestion does NOT emit a Route node for (1) array-form `@GetMapping({...})`,
+    // (2) interface-inherited Spring routes, or (3) the 2nd verb of a same-URL
+    // GET+POST pair (Route nodes are URL-keyed). Declaring 'complete' here would
+    // let the parse-skip drop those group-only providers. Java flips to 'complete'
+    // only once ingestion provider extraction matches this scan (a follow-up:
+    // array-form query branch + interface-inheritance emission + per-verb Route
+    // identity). `hasConsumerSignals` below is kept ready for that flip.
+    // Consumer signals this plugin's scan() can detect: RestTemplate / WebClient /
+    // OkHttp / Java-HttpClient / Apache-HttpClient call sites, OpenFeign
+    // (`@FeignClient` + `@RequestLine`) interfaces, and Spring 6 HTTP Interface
+    // `@(Get|...)Exchange` / `@HttpExchange`. A provider-covered file containing
+    // any of these must still be parsed so its consumer contracts are not dropped
+    // (ingestion emits no FETCHES for Java). Conservative by design.
+    hasConsumerSignals(content) {
+        return /\brestTemplate\b|\bwebClient\b|Request\.Builder|HttpRequest|HttpMethod\.|new\s+Http(Get|Post|Put|Delete|Patch)\b|@RequestLine|@FeignClient|Exchange/.test(content);
+    },
     scan(tree) {
         const out = [];
         // ─── Spring providers + OpenFeign consumers (one query pass) ────

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

@@ -104,6 +104,17 @@ function isHttpUrlLiteral(path) {
 export const PHP_HTTP_PLUGIN = {
     name: 'php-http',
     language: PHP.php_only,
+    // Laravel `Route::<verb>(...)` definitions are emitted as Route nodes by
+    // ingestion, so the graph is authoritative for PHP providers (#2138 Part 2).
+    routeCoverage: 'complete',
+    // Consumer signals scan() can detect: Laravel `Http::<verb>`, Guzzle client
+    // `->get/post/.../request(...)`, and `file_get_contents` of an HTTP URL. A
+    // provider-covered file with any of these must still be parsed (ingestion
+    // emits no FETCHES for PHP). Conservative — the `->verb(` shape over-matches
+    // ordinary method calls, which only costs a parse, never data.
+    hasConsumerSignals(content) {
+        return /Http::|file_get_contents|->\s*(get|post|put|delete|patch|request)\s*\(/i.test(content);
+    },
     scan(tree) {
         const out = [];
         for (const match of runCompiledPatterns(PHP_PATTERNS.laravelRoute, tree)) {

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

@@ -825,6 +825,20 @@ function joinPrefix(prefix, route) {
 export const PYTHON_HTTP_PLUGIN = {
     name: 'python-http',
     language: Python,
+    // routeCoverage intentionally LEFT at the default 'partial' (#2138 Part 2).
+    // It would be a no-op even if set to 'complete': FastAPI decorator routes set
+    // no handlerName (generic worker path) and Django sets methodName: null, so no
+    // Python file ever resolves a handlerSymbolId and none would be parse-skipped.
+    // Declaring 'complete' now is only a latent trap for the moment a follow-up
+    // gives FastAPI routes a handlerName. `hasConsumerSignals` is kept (and is a
+    // true superset of scan()'s consumer shapes) so the precondition already holds
+    // when Python is later flipped to 'complete'.
+    // Consumer signals scan() can detect: `requests.<verb>`/`requests.request`,
+    // `httpx` (sync/async client), the `uri=`/`url=` keyword/variable wrapper
+    // calls, plus aiohttp/urllib. Conservative — over-matching only costs a parse.
+    hasConsumerSignals(content) {
+        return /\brequests\s*\.|\bhttpx\b|\baiohttp\b|\burllib\b|\burlopen\b|\buri\s*=|\burl\s*=/.test(content);
+    },
     prepareRepo({ files, parser, readFile, parseSource }) {
         return buildPythonRepoContext(files, parser, readFile, parseSource);
     },

package/dist/core/group/extractors/http-patterns/types.d.ts

@@ -71,6 +71,43 @@ export interface HttpLanguagePlugin {
     name: string;
     /** tree-sitter grammar object (passed to the shared parser). */
     language: unknown;
+    /**
+     * Whether ingestion is known to emit a `Route` graph node for EVERY
+     * provider route in this language (Spring/FastAPI/Laravel annotations are
+     * extracted into Route nodes during parse). When `'complete'`, the
+     * orchestrator may skip the source-scan + tree-sitter parse for a file whose
+     * graph provider routes all resolved a handler symbol (#2138 Part 2) — the
+     * graph is authoritative, the scan would only re-discover the same routes.
+     *
+     * Defaults to `'partial'` (the safe assumption): the source scan always runs,
+     * so a language whose ingestion coverage is incomplete never loses routes.
+     * This is a deliberate, per-language trust assertion — set it only for
+     * languages whose route ingestion is provably complete.
+     */
+    routeCoverage?: 'complete' | 'partial';
+    /**
+     * Cheap, parse-free pre-check used by the parse-skip optimization (#2138
+     * Part 2). Given a file's raw source text, return `false` ONLY when the file
+     * provably contains no outbound-HTTP (consumer) call that this plugin's
+     * `scan()` would detect; return `true` on any doubt.
+     *
+     * Why it exists: `routeCoverage: 'complete'` asserts *provider* Route-node
+     * completeness only. A provider-covered file may ALSO be a consumer (e.g. a
+     * Spring `@RestController` that calls `restTemplate`/`webClient`, a Laravel
+     * controller using Guzzle, a FastAPI handler calling `requests`/`httpx`).
+     * Ingestion's `FETCHES` edges are JS/TS-only, so the graph cannot back up
+     * those server-side consumers — they come solely from the source scan. The
+     * orchestrator may therefore skip a provider-covered file's parse only when
+     * this returns `false`; otherwise the file is still scanned so its consumer
+     * contracts are not dropped.
+     *
+     * MUST be implemented by any plugin whose `scan()` can emit `'consumer'`
+     * detections AND that declares `routeCoverage: 'complete'`; otherwise that
+     * language's provider-covered files are never parse-skipped (safe, no win).
+     * The check is intentionally conservative — over-matching only costs a parse
+     * that could have been skipped; it never drops data.
+     */
+    hasConsumerSignals?(content: string): boolean;
     /**
      * Optional pre-pass: walk the relevant files in the repo and produce
      * an opaque context that `scan` can use to resolve cross-file facts.

package/dist/core/group/extractors/http-route-extractor.d.ts

@@ -23,7 +23,7 @@ import type { ExtractedContract, RepoHandle } from '../types.js';
  * `http-patterns/index.ts`: register a new `HttpLanguagePlugin` and
  * widen `HTTP_SCAN_GLOB` if needed.
  */
-export declare const HANDLES_ROUTE_QUERY = "\nMATCH (handlerFile:File)-[r:CodeRelation {type: 'HANDLES_ROUTE'}]->(route:Route)\nRETURN handlerFile.id AS fileId, handlerFile.filePath AS filePath,\n       route.name AS routePath, route.id AS routeId,\n       route.method AS routeMethod,\n       route.responseKeys AS responseKeys,\n       r.reason AS routeSource";
+export declare const HANDLES_ROUTE_QUERY = "\nMATCH (handlerFile:File)-[r:CodeRelation {type: 'HANDLES_ROUTE'}]->(route:Route)\nRETURN handlerFile.id AS fileId, handlerFile.filePath AS filePath,\n       route.name AS routePath, route.id AS routeId,\n       route.method AS routeMethod,\n       route.handlerSymbolId AS handlerSymbolId,\n       route.responseKeys AS responseKeys,\n       r.reason AS routeSource";
 /**
  * Canonicalize a provider-side HTTP path for contract-id generation:
  *   - strip query string

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

@@ -38,6 +38,7 @@ MATCH (handlerFile:File)-[r:CodeRelation {type: 'HANDLES_ROUTE'}]->(route:Route)
 RETURN handlerFile.id AS fileId, handlerFile.filePath AS filePath,
        route.name AS routePath, route.id AS routeId,
        route.method AS routeMethod,
+       route.handlerSymbolId AS handlerSymbolId,
        route.responseKeys AS responseKeys,
        r.reason AS routeSource`;
 const FETCHES_QUERY = `
@@ -248,13 +249,44 @@ export class HttpRouteExtractor {
             cachedDetections.clear();
         };
         const files = await getScannedFiles();
-        await collectProjectDetections(files);
-        const graphProviders = dbExecutor != null ? await this.extractProvidersGraph(dbExecutor, getDetections) : [];
-        // Source scan always runs to capture routes in languages/files not covered
-        // by graph edges; the glob and per-file parse results are cached above.
-        const providers = this.mergeGraphAndSourceContracts(graphProviders, await this.extractProvidersSourceScan(files, getDetections));
+        // Run the graph provider pass FIRST. After #2138 Part 2 it reads handler
+        // symbols from the graph (no source parse for resolved routes), so it can
+        // report which files are fully graph-covered BEFORE we decide what to
+        // parse. Files fully covered by a `routeCoverage: 'complete'` language are
+        // candidates to skip the source scan + tree-sitter parse — but only their
+        // *providers* are graph-authoritative; the consumer-safety gate below
+        // removes any candidate that still needs scanning for outbound calls.
+        const coveredFiles = new Set();
+        const graphProviders = dbExecutor != null
+            ? await this.extractProvidersGraph(dbExecutor, getDetections, coveredFiles)
+            : [];
+        // Consumer-safety gate (#2138 Part 2): `extractProvidersGraph` marks a file
+        // covered on *provider* grounds (all HANDLES_ROUTE rows resolved + a
+        // `routeCoverage: 'complete'` language). But a provider-covered file may also
+        // be a *consumer* (a controller that calls RestTemplate/WebClient/Guzzle/
+        // requests/...), and ingestion emits no FETCHES edges for those server-side
+        // languages — the graph can't back them up. So a covered file is only truly
+        // safe to skip (parse) when its plugin can PROVE, from a cheap parse-free
+        // text scan, that it holds no such consumer call. Anything else (a positive
+        // signal, no `hasConsumerSignals` hook, or an unreadable file) stays in the
+        // scan set so its consumer contracts are preserved.
+        for (const f of [...coveredFiles]) {
+            const plugin = getPluginForFile(f);
+            const content = readSafe(repoPath, f);
+            const provenNoConsumer = content != null && typeof plugin?.hasConsumerSignals === 'function'
+                ? plugin.hasConsumerSignals(content) === false
+                : false;
+            if (!provenNoConsumer)
+                coveredFiles.delete(f);
+        }
+        // Everything the graph did not fully cover still gets a full source scan
+        // (fail-open: partial-coverage languages, unresolved routes, and graph-less
+        // runs all land here).
+        const scanFiles = files.filter((f) => !coveredFiles.has(f));
+        await collectProjectDetections(scanFiles);
+        const providers = this.mergeGraphAndSourceContracts(graphProviders, await this.extractProvidersSourceScan(scanFiles, getDetections));
         const graphConsumers = dbExecutor != null ? await this.extractConsumersGraph(dbExecutor, getDetections) : [];
-        const consumers = this.mergeGraphAndSourceContracts(graphConsumers, await this.extractConsumersSourceScan(files, getDetections));
+        const consumers = this.mergeGraphAndSourceContracts(graphConsumers, await this.extractConsumersSourceScan(scanFiles, getDetections));
         return [...providers, ...consumers];
     }
     async scanFiles(repoPath) {
@@ -272,8 +304,13 @@ export class HttpRouteExtractor {
         });
     }
     // ─── Graph-assisted providers ──────────────────────────────────────
-    async extractProvidersGraph(db, getDetections) {
+    async extractProvidersGraph(db, getDetections, coveredFiles) {
         const out = [];
+        // Per-file coverage tracking (#2138 Part 2): a file is "fully graph-covered"
+        // when every one of its HANDLES_ROUTE rows resolved a handlerSymbolId AND its
+        // language plugin declares `routeCoverage: 'complete'`. Such files can skip
+        // the source scan + parse entirely — the graph is authoritative for them.
+        const fileAllResolved = new Map();
         let rows;
         try {
             rows = await db(HANDLES_ROUTE_QUERY);
@@ -298,66 +335,90 @@ export class HttpRouteExtractor {
                 .trim()
                 .toUpperCase();
             let method = (graphMethod || null) ?? methodFromRouteReason(routeSource);
-            // Look up handler name (and backfill method if missing) from the
-            // plugin's scan of the handler file. This replaces the old
-            // regex-based `inferMethodFromFileScan` and `pickJavaHandlerName`
-            // helpers — tree-sitter gives both pieces of information
-            // structurally. Always run the lookup: even when method is set by
-            // `methodFromRouteReason`, we still need the handler name.
-            const detections = filePath ? await getDetections(filePath) : [];
-            const providerDetections = detections.filter((d) => d.role === 'provider');
-            let handlerName = null;
-            const normalizedRoute = normalizeHttpPath(routePath);
-            // Candidates share the same normalized path. When multiple
-            // detections at the same path exist (e.g. GET + POST /api/orders
-            // in one router), a blind `.find()` silently returned the first
-            // verb — attaching the wrong handler and, when method was not
-            // already pinned by the route reason, the wrong method too.
-            // Disambiguate by method when we know it; refuse to guess when
-            // we don't.
-            const candidates = providerDetections.filter((d) => normalizeHttpPath(d.path) === normalizedRoute);
-            let match;
-            const ambiguousCandidates = !method && candidates.length > 1;
-            if (method) {
-                match = candidates.find((d) => d.method === method);
-            }
-            else if (candidates.length === 1) {
-                match = candidates[0];
-            }
-            // else: multiple candidates + unknown method → leave match
-            // undefined so handlerName stays null and skip symbol
-            // enrichment below, keeping the file-basename fallback instead
-            // of letting pickSymbolUid silently pick the first Function /
-            // Method in the file (which reintroduces the mis-attribution
-            // we were trying to avoid). Method stays at the conservative
-            // 'GET' default set below.
-            if (match) {
-                if (!method)
-                    method = match.method;
-                handlerName = match.name;
+            const handlerSymbolId = String(row.handlerSymbolId ?? '').trim();
+            const fileId = row.fileId ?? row[0];
+            // Track per-file resolution for the parse-skip coverage set: a file stays
+            // "all resolved" only while every one of its rows carries a handlerSymbolId.
+            if (filePath) {
+                const prev = fileAllResolved.get(filePath);
+                fileAllResolved.set(filePath, (prev ?? true) && handlerSymbolId.length > 0);
             }
-            if (!method)
-                method = 'GET';
-            const pathNorm = normalizeHttpPath(routePath);
-            const cid = contractIdFor(method, pathNorm);
+            const pathNormEarly = normalizeHttpPath(routePath);
             let symbolUid = '';
             let symbolName = path.basename(filePath) || 'handler';
             let symPath = filePath;
-            const fileId = row.fileId ?? row[0];
-            if (fileId && !ambiguousCandidates) {
-                try {
-                    const syms = await db(CONTAINS_QUERY, { fileId });
-                    if (syms.length > 0) {
-                        const picked = pickSymbolUid(syms, handlerName);
-                        symbolUid = picked.uid;
-                        symbolName = picked.name;
-                        symPath = picked.filePath || filePath;
+            if (handlerSymbolId) {
+                // Fast path (Part 2, #2138): the handler symbol was resolved during
+                // ingestion and persisted on the Route node, so we read it straight
+                // from the graph and SKIP the `getDetections()` source-scan/parse the
+                // legacy path needed just to recover the handler name. CONTAINS is a
+                // cheap graph query (no tree-sitter parse) used only to surface the
+                // handler's display name/path; the uid is authoritative regardless.
+                if (!method)
+                    method = 'GET';
+                symbolUid = handlerSymbolId;
+                if (fileId) {
+                    try {
+                        const syms = await db(CONTAINS_QUERY, { fileId });
+                        const hit = syms.find((s) => String(s.uid ?? s[0]) === handlerSymbolId);
+                        if (hit) {
+                            symbolName = String(hit.name ?? hit[1]) || symbolName;
+                            symPath = String(hit.filePath ?? hit[2]) || filePath;
+                        }
+                    }
+                    catch {
+                        /* keep the authoritative uid + basename fallback */
                     }
                 }
-                catch {
-                    /* ignore */
+            }
+            else {
+                // Legacy fallback (old index / unresolved handler): recover the handler
+                // name from the plugin's scan of the handler file (this parses source).
+                // Always run the lookup: even when method is set, we still need the name.
+                const detections = filePath ? await getDetections(filePath) : [];
+                const providerDetections = detections.filter((d) => d.role === 'provider');
+                let handlerName = null;
+                // Candidates share the same normalized path. When multiple detections at
+                // the same path exist (GET + POST /api/orders in one router), a blind
+                // `.find()` silently returned the first verb — attaching the wrong
+                // handler/method. Disambiguate by method when known; refuse to guess.
+                const candidates = providerDetections.filter((d) => normalizeHttpPath(d.path) === pathNormEarly);
+                let match;
+                const ambiguousCandidates = !method && candidates.length > 1;
+                if (method) {
+                    match = candidates.find((d) => d.method === method);
+                }
+                else if (candidates.length === 1) {
+                    match = candidates[0];
+                }
+                // else: multiple candidates + unknown method → leave match undefined so
+                // handlerName stays null and we skip symbol enrichment, keeping the
+                // file-basename fallback rather than letting pickSymbolUid pick the
+                // first Function/Method (which reintroduces mis-attribution).
+                if (match) {
+                    if (!method)
+                        method = match.method;
+                    handlerName = match.name;
+                }
+                if (!method)
+                    method = 'GET';
+                if (fileId && !ambiguousCandidates) {
+                    try {
+                        const syms = await db(CONTAINS_QUERY, { fileId });
+                        if (syms.length > 0) {
+                            const picked = pickSymbolUid(syms, handlerName);
+                            symbolUid = picked.uid;
+                            symbolName = picked.name;
+                            symPath = picked.filePath || filePath;
+                        }
+                    }
+                    catch {
+                        /* ignore */
+                    }
                 }
             }
+            const pathNorm = pathNormEarly;
+            const cid = contractIdFor(method, pathNorm);
             out.push({
                 contractId: cid,
                 type: 'http',
@@ -375,6 +436,17 @@ export class HttpRouteExtractor {
                 },
             });
         }
+        // Populate the parse-skip coverage set: files whose every provider route
+        // resolved a handler symbol AND whose language declares complete ingestion
+        // route coverage. Fail-open — any unresolved row or a 'partial' language
+        // leaves the file out, so it still gets a full source scan.
+        if (coveredFiles) {
+            for (const [fp, allResolved] of fileAllResolved) {
+                if (allResolved && getPluginForFile(fp)?.routeCoverage === 'complete') {
+                    coveredFiles.add(fp);
+                }
+            }
+        }
         return out;
     }
     // ─── Source-scan providers ─────────────────────────────────────────

package/dist/core/ingestion/call-processor.d.ts

@@ -17,6 +17,7 @@
 import { KnowledgeGraph } from '../graph/types.js';
 import type { SemanticModel, SymbolTableReader } from './model/index.js';
 import type { ExtractedRoute, ExtractedFetchCall } from './workers/parse-worker.js';
+import type { ExtractedDecoratorRoute } from './workers/parse-worker.js';
 /** Per-file resolved type bindings for exported symbols.
  *  Consumed by the cross-file re-resolution / enrichment pass. */
 export type ExportedTypeMap = Map<string, Map<string, string>>;
@@ -57,6 +58,31 @@ export declare function buildExportedTypeMapFromGraph(graph: KnowledgeGraph, sym
  * passes — acceptable for an edge whose target method could not be resolved.
  */
 export declare const processRoutesFromExtracted: (graph: KnowledgeGraph, extractedRoutes: ExtractedRoute[], model: SemanticModel, onProgress?: (current: number, total: number) => void) => Promise<void>;
+/**
+ * Resolve each route's handler to a real symbol UID, keyed by the normalized
+ * route URL (the same key the routes phase uses for the `Route` node). This is
+ * the Part 2 (#2138) groundwork that lets `HttpRouteExtractor.extractProvidersGraph`
+ * read the handler symbol from the graph instead of re-parsing source via
+ * `getDetections()`.
+ *
+ * Two route shapes, one resolution target — `(filePath, name) → nodeId`:
+ *   - Laravel framework routes (`ExtractedRoute`) carry `controllerName` +
+ *     `methodName`; resolve the controller (qualified-first) then the method in
+ *     the controller's own file (mirrors `processRoutesFromExtracted`).
+ *   - Decorator routes (`ExtractedDecoratorRoute`, e.g. Spring/FastAPI) carry
+ *     `handlerName` (the decorated method, captured at extraction); resolve it
+ *     directly in the route's own file.
+ *
+ * First-writer-wins per URL, matching the routes phase's dedup (it keeps the
+ * first route registered for a URL and counts the rest as duplicates). The first
+ * route to claim a URL reserves it **even when its handler is unresolvable**, so
+ * a later same-URL route can never stamp its handler onto the first route's Route
+ * node (the routes phase made that first route the node-winner). Routes whose
+ * handler cannot be *uniquely* resolved (no name, zero matches, or an ambiguous
+ * same-name match) carry no `handlerSymbolId`; the extractor then falls back to
+ * source scan for that route (fail-open, no regression, never a wrong handler).
+ */
+export declare function resolveRouteHandlerSymbols(model: SemanticModel, extractedRoutes: readonly ExtractedRoute[], decoratorRoutes: readonly ExtractedDecoratorRoute[]): Map<string, string>;
 /**
  * Extract property access keys from a consumer file's source code near fetch calls.
  *

package/dist/core/ingestion/call-processor.js

@@ -17,6 +17,7 @@
 import { generateId } from '../../lib/utils.js';
 import { yieldToEventLoop } from './utils/event-loop.js';
 import { normalizeFetchURL, routeMatches } from './route-extractors/nextjs.js';
+import { normalizeExtractedRoutePath } from './route-extractors/route-path.js';
 import { extractReturnTypeName } from './type-extractors/shared.js';
 const MAX_EXPORTS_PER_FILE = 500;
 const MAX_TYPE_NAME_LENGTH = 256;
@@ -213,6 +214,78 @@ export const processRoutesFromExtracted = async (graph, extractedRoutes, model,
     }
     onProgress?.(extractedRoutes.length, extractedRoutes.length);
 };
+/**
+ * Resolve each route's handler to a real symbol UID, keyed by the normalized
+ * route URL (the same key the routes phase uses for the `Route` node). This is
+ * the Part 2 (#2138) groundwork that lets `HttpRouteExtractor.extractProvidersGraph`
+ * read the handler symbol from the graph instead of re-parsing source via
+ * `getDetections()`.
+ *
+ * Two route shapes, one resolution target — `(filePath, name) → nodeId`:
+ *   - Laravel framework routes (`ExtractedRoute`) carry `controllerName` +
+ *     `methodName`; resolve the controller (qualified-first) then the method in
+ *     the controller's own file (mirrors `processRoutesFromExtracted`).
+ *   - Decorator routes (`ExtractedDecoratorRoute`, e.g. Spring/FastAPI) carry
+ *     `handlerName` (the decorated method, captured at extraction); resolve it
+ *     directly in the route's own file.
+ *
+ * First-writer-wins per URL, matching the routes phase's dedup (it keeps the
+ * first route registered for a URL and counts the rest as duplicates). The first
+ * route to claim a URL reserves it **even when its handler is unresolvable**, so
+ * a later same-URL route can never stamp its handler onto the first route's Route
+ * node (the routes phase made that first route the node-winner). Routes whose
+ * handler cannot be *uniquely* resolved (no name, zero matches, or an ambiguous
+ * same-name match) carry no `handlerSymbolId`; the extractor then falls back to
+ * source scan for that route (fail-open, no regression, never a wrong handler).
+ */
+export function resolveRouteHandlerSymbols(model, extractedRoutes, decoratorRoutes) {
+    const out = new Map();
+    // URLs already claimed by an earlier route (resolved or not). Mirrors the
+    // routes phase `addRoute` first-writer-wins so the handler we stamp always
+    // belongs to the route that actually won the Route node.
+    const claimed = new Set();
+    // Resolve a single same-file symbol by name, refusing to guess on ambiguity:
+    // exactly one match → its nodeId; zero or many → undefined (fail-open).
+    const uniqueSymbolId = (filePath, name) => {
+        const defs = model.symbols.lookupExactAll(filePath, name);
+        return defs.length === 1 ? defs[0]?.nodeId : undefined;
+    };
+    const claim = (routePath, prefix, symbolId) => {
+        if (!routePath)
+            return;
+        const url = normalizeExtractedRoutePath(routePath, prefix);
+        if (claimed.has(url))
+            return; // first-writer-wins: later same-URL routes can't override
+        claimed.add(url);
+        if (symbolId)
+            out.set(url, symbolId);
+    };
+    // Laravel framework routes — controller class + method name.
+    for (const route of extractedRoutes) {
+        let methodId;
+        if (route.controllerName && route.methodName) {
+            let controllerDef;
+            if (route.controllerQualifiedName) {
+                controllerDef = resolveControllerByQualifiedName(model, route.controllerQualifiedName);
+            }
+            if (!controllerDef) {
+                const controllerDefs = model.types.lookupClassByName(route.controllerName);
+                if (controllerDefs.length === 1)
+                    controllerDef = controllerDefs[0];
+            }
+            if (controllerDef)
+                methodId = uniqueSymbolId(controllerDef.filePath, route.methodName);
+        }
+        claim(route.routePath, route.prefix ?? null, methodId);
+    }
+    // Decorator routes (Spring / FastAPI / generic) — the decorated handler in
+    // the route's own file.
+    for (const dr of decoratorRoutes) {
+        const handlerId = dr.handlerName ? uniqueSymbolId(dr.filePath, dr.handlerName) : undefined;
+        claim(dr.routePath, dr.prefix ?? null, handlerId);
+    }
+    return out;
+}
 /** Common method names on response/data objects that are NOT property accesses */
 // Properties/methods to ignore when extracting consumer accessed keys from `data.X` patterns.
 // Avoids false positives from Fetch API, Array, Object, Promise, and DOM access on variables

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

@@ -66,6 +66,10 @@ export declare function runChunkedParseAndResolve(graph: KnowledgeGraph, scanned
     allToolDefs: ExtractedToolDef[];
     allORMQueries: ExtractedORMQuery[];
     bindingAccumulator: BindingAccumulator;
+    /** Route URL → resolved handler symbol UID (Part 2, #2138). Lets the routes
+     *  phase stamp `handlerSymbolId` on Route nodes so contract extraction can
+     *  read the handler from the graph instead of re-parsing source. */
+    routeHandlerSymbols: ReadonlyMap<string, string>;
     /** SemanticModel populated during parse — scope-resolution reads its
      *  TypeRegistry / MethodRegistry / SymbolTable indexes. */
     model: MutableSemanticModel;

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

@@ -19,7 +19,7 @@ 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 { DEFAULT_PDG_MAX_FUNCTION_LINES } from '../cfg/collect.js';
-import { processRoutesFromExtracted, buildExportedTypeMapFromGraph, } from '../call-processor.js';
+import { processRoutesFromExtracted, resolveRouteHandlerSymbols, buildExportedTypeMapFromGraph, } from '../call-processor.js';
 import { createSemanticModel } from '../model/index.js';
 import { getLanguageFromFilename, } from '../../../_shared/index.js';
 import { readFileContents } from '../filesystem-walker.js';
@@ -1048,6 +1048,9 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
         }
     }
     logHeapProbe('parse-impl-return', `exportedTypeMap=${exportedTypeMap.size} parsedFiles=${allParsedFiles.length} nodes=${graph.nodeCount}`);
+    // 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);
     return {
         exportedTypeMap,
         allFetchCalls,
@@ -1057,6 +1060,7 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
         allToolDefs,
         allORMQueries,
         bindingAccumulator,
+        routeHandlerSymbols,
         model,
         // Whether a worker pool was actually constructed for this run. False means
         // no pool was needed: a warm all-cache-hit run replays cached worker output

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

@@ -39,6 +39,9 @@ export interface ParseOutput {
     readonly allDecoratorRoutes: readonly ExtractedDecoratorRoute[];
     readonly allToolDefs: readonly ExtractedToolDef[];
     readonly allORMQueries: readonly ExtractedORMQuery[];
+    /** Route URL → resolved handler symbol UID (Part 2, #2138). Consumed by the
+     *  routes phase to stamp `handlerSymbolId` on Route nodes. */
+    readonly routeHandlerSymbols: ReadonlyMap<string, string>;
     bindingAccumulator: BindingAccumulator;
     /** SemanticModel populated during parse — scope-resolution reads its
      *  TypeRegistry / MethodRegistry / SymbolTable indexes. */

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

@@ -11,6 +11,7 @@
  * @output  routeRegistry, handlerContents
  */
 import type { PipelinePhase } from './types.js';
+import { normalizeExtractedRoutePath } from '../route-extractors/route-path.js';
 export interface RouteEntry {
     filePath: string;
     source: string;
@@ -34,6 +35,6 @@ export interface TemplateFetchCall {
 }
 export declare const isTemplateRouteCandidate: (filePath: string) => boolean;
 export declare function extractTemplateStaticFetchCalls(filePath: string, content: string, namedRouteUrls?: ReadonlyMap<string, string>): TemplateFetchCall[];
-export declare function normalizeExtractedRoutePath(routePath: string, prefix: string | null): string;
+export { normalizeExtractedRoutePath };
 export declare function normalizeRouteMethod(raw: string | null | undefined): string | undefined;
 export declare const routesPhase: PipelinePhase<RoutesOutput>;

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

@@ -18,6 +18,7 @@ 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 { normalizeExtractedRoutePath } from '../route-extractors/route-path.js';
 import { generateId } from '../../../lib/utils.js';
 import { readFileContents } from '../filesystem-walker.js';
 import { isDev } from '../utils/env.js';
@@ -88,15 +89,11 @@ export function extractTemplateStaticFetchCalls(filePath, content, namedRouteUrl
     }
     return calls;
 }
-export function normalizeExtractedRoutePath(routePath, prefix) {
-    const pathPart = routePath.trim().replace(/^\/+/, '').replace(/\/+$/g, '');
-    const prefixPart = prefix?.trim().replace(/^\/+/, '').replace(/\/+$/g, '');
-    const joined = prefixPart ? `/${prefixPart}${pathPart ? `/${pathPart}` : ''}` : `/${pathPart}`;
-    return joined.replace(/\/+/g, '/') || '/';
-}
 function escapeRegex(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
+// Re-exported for existing consumers/tests that import it from the routes phase.
+export { normalizeExtractedRoutePath };
 /**
  * Canonicalize a route's HTTP verb for persistence on the Route node.
  * Returns an upper-cased standard method, or `undefined` when the value
@@ -132,7 +129,7 @@ export const routesPhase = {
     name: 'routes',
     deps: ['parse'],
     async execute(ctx, deps) {
-        const { allPaths, allFetchCalls: parseFetchCalls, allFetchWrapperDefs, allExtractedRoutes, allDecoratorRoutes, } = getPhaseOutput(deps, 'parse');
+        const { allPaths, allFetchCalls: parseFetchCalls, allFetchWrapperDefs, allExtractedRoutes, allDecoratorRoutes, routeHandlerSymbols, } = getPhaseOutput(deps, 'parse');
         // Local copy — routes phase must not mutate upstream ParseOutput
         const allFetchCalls = [...parseFetchCalls];
         const routeRegistry = new Map();
@@ -226,6 +223,7 @@ export const routesPhase = {
                 const mwResult = content ? extractMiddlewareChain(content) : undefined;
                 const middleware = mwResult?.chain;
                 const routeNodeId = generateId('Route', routeURL);
+                const handlerSymbolId = routeHandlerSymbols.get(routeURL);
                 ctx.graph.addNode({
                     id: routeNodeId,
                     label: 'Route',
@@ -233,6 +231,7 @@ export const routesPhase = {
                         name: routeURL,
                         filePath: handlerPath,
                         ...(routeMethod ? { method: routeMethod } : {}),
+                        ...(handlerSymbolId ? { handlerSymbolId } : {}),
                         ...(responseKeys ? { responseKeys } : {}),
                         ...(errorKeys ? { errorKeys } : {}),
                         ...(middleware && middleware.length > 0 ? { middleware } : {}),

package/dist/core/ingestion/route-extractors/route-path.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared route-path normalization.
+ *
+ * Extracted from the routes phase so both the routes phase (which creates the
+ * `Route` graph node, keyed by the normalized URL) and the parse phase (which
+ * resolves each route's handler symbol and needs the SAME key to associate the
+ * resolved id back to the route) can compute an identical route URL without a
+ * phase-to-phase import cycle. Pure string logic, no dependencies.
+ */
+/**
+ * Join a route's path with its (optional) prefix into a normalized,
+ * leading-slash URL used as the Route node identity. Collapses duplicate
+ * slashes and strips trailing ones; an empty result degrades to `/`.
+ */
+export declare function normalizeExtractedRoutePath(routePath: string, prefix: string | null): string;

package/dist/core/ingestion/route-extractors/route-path.js

@@ -0,0 +1,20 @@
+/**
+ * Shared route-path normalization.
+ *
+ * Extracted from the routes phase so both the routes phase (which creates the
+ * `Route` graph node, keyed by the normalized URL) and the parse phase (which
+ * resolves each route's handler symbol and needs the SAME key to associate the
+ * resolved id back to the route) can compute an identical route URL without a
+ * phase-to-phase import cycle. Pure string logic, no dependencies.
+ */
+/**
+ * Join a route's path with its (optional) prefix into a normalized,
+ * leading-slash URL used as the Route node identity. Collapses duplicate
+ * slashes and strips trailing ones; an empty result degrades to `/`.
+ */
+export function normalizeExtractedRoutePath(routePath, prefix) {
+    const pathPart = routePath.trim().replace(/^\/+/, '').replace(/\/+$/g, '');
+    const prefixPart = prefix?.trim().replace(/^\/+/, '').replace(/\/+$/g, '');
+    const joined = prefixPart ? `/${prefixPart}${pathPart ? `/${pathPart}` : ''}` : `/${pathPart}`;
+    return joined.replace(/\/+/g, '/') || '/';
+}

package/dist/core/ingestion/route-extractors/spring.js

@@ -123,6 +123,9 @@ export function extractSpringRoutes(tree, filePath, lineOffset = 0) {
             continue;
         const enclosingClass = findEnclosingClass(node);
         const classPrefix = enclosingClass ? (prefixByClassId.get(enclosingClass.id) ?? '') : '';
+        // `node` is the annotated `method_declaration`; its name field is the
+        // handler method name (resolved to a symbol UID later by the routes phase).
+        const handlerName = node.childForFieldName('name')?.text;
         routes.push({
             filePath,
             routePath,
@@ -130,6 +133,7 @@ export function extractSpringRoutes(tree, filePath, lineOffset = 0) {
             decoratorName: ann,
             lineNumber: annNode.startPosition.row + lineOffset,
             ...(classPrefix ? { prefix: classPrefix } : {}),
+            ...(handlerName ? { handlerName } : {}),
         });
     }
     return routes;

package/dist/core/ingestion/workers/parse-worker.d.ts

@@ -119,6 +119,16 @@ export interface ExtractedDecoratorRoute {
      * absent ⇒ no prefix applies.
      */
     prefix?: string | null;
+    /**
+     * Name of the handler the route decorator sits on (the decorated
+     * method/function — e.g. `create` for `@PostMapping("/orders") Order create()`).
+     * Captured at extraction where the decorated definition node is in hand, so
+     * the routes phase can resolve it to a real handler symbol UID via the
+     * SemanticModel (same `(filePath, name) → nodeId` lookup Laravel routes use).
+     * Absent when the extractor could not identify the decorated definition;
+     * resolution then falls back (the Route node simply carries no handlerSymbolId).
+     */
+    handlerName?: string;
 }
 export interface ExtractedToolDef {
     filePath: string;

package/dist/core/lbug/csv-generator.js

@@ -304,7 +304,7 @@ export const streamAllCSVsToDisk = async (graph, repoPath, csvDir, onNodePhaseCo
         // Section nodes have an extra 'level' column
         const sectionWriter = new BufferedCSVWriter(path.join(csvDir, 'section.csv'), 'id,name,filePath,startLine,endLine,level,content,description');
         // Route nodes for API endpoint mapping
-        const routeWriter = new BufferedCSVWriter(path.join(csvDir, 'route.csv'), 'id,name,filePath,responseKeys,errorKeys,middleware,method');
+        const routeWriter = new BufferedCSVWriter(path.join(csvDir, 'route.csv'), 'id,name,filePath,responseKeys,errorKeys,middleware,method,handlerSymbolId');
         // Tool nodes for MCP tool definitions
         const toolWriter = new BufferedCSVWriter(path.join(csvDir, 'tool.csv'), 'id,name,filePath,description');
         // BasicBlock nodes — taint/PDG substrate (issue #2080). No `name` column;
@@ -452,6 +452,7 @@ export const streamAllCSVsToDisk = async (graph, repoPath, csvDir, onNodePhaseCo
                         escapeCSVField(errorKeysStr),
                         escapeCSVField(middlewareStr),
                         escapeCSVField(String(node.properties.method ?? '')),
+                        escapeCSVField(String(node.properties.handlerSymbolId ?? '')),
                     ].join(','));
                     break;
                 }

package/dist/core/lbug/lbug-adapter.js

@@ -1149,7 +1149,7 @@ export const getCopyQuery = (table, filePath) => {
         return `COPY ${t}(id, name, filePath, startLine, endLine, level, content, description) FROM "${filePath}" ${COPY_CSV_OPTS}`;
     }
     if (table === 'Route') {
-        return `COPY ${t}(id, name, filePath, responseKeys, errorKeys, middleware, method) FROM "${filePath}" ${COPY_CSV_OPTS}`;
+        return `COPY ${t}(id, name, filePath, responseKeys, errorKeys, middleware, method, handlerSymbolId) FROM "${filePath}" ${COPY_CSV_OPTS}`;
     }
     if (table === 'Tool') {
         return `COPY ${t}(id, name, filePath, description) FROM "${filePath}" ${COPY_CSV_OPTS}`;

package/dist/core/lbug/schema.d.ts

@@ -39,7 +39,7 @@ export declare const ANNOTATION_SCHEMA: string;
 export declare const CONSTRUCTOR_SCHEMA: string;
 export declare const TEMPLATE_SCHEMA: string;
 export declare const MODULE_SCHEMA: string;
-export declare const ROUTE_SCHEMA = "\nCREATE NODE TABLE Route (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  responseKeys STRING[],\n  errorKeys STRING[],\n  middleware STRING[],\n  method STRING,\n  PRIMARY KEY (id)\n)";
+export declare const ROUTE_SCHEMA = "\nCREATE NODE TABLE Route (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  responseKeys STRING[],\n  errorKeys STRING[],\n  middleware STRING[],\n  method STRING,\n  handlerSymbolId STRING,\n  PRIMARY KEY (id)\n)";
 export declare const TOOL_SCHEMA = "\nCREATE NODE TABLE Tool (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  description STRING,\n  PRIMARY KEY (id)\n)";
 export declare const SECTION_SCHEMA = "\nCREATE NODE TABLE Section (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  level INT64,\n  content STRING,\n  description STRING,\n  PRIMARY KEY (id)\n)";
 export declare const BASICBLOCK_SCHEMA = "\nCREATE NODE TABLE BasicBlock (\n  id STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  text STRING,\n  callees STRING,\n  calleeIds STRING,\n  PRIMARY KEY (id)\n)";

package/dist/core/lbug/schema.js

@@ -178,6 +178,7 @@ CREATE NODE TABLE Route (
   errorKeys STRING[],
   middleware STRING[],
   method STRING,
+  handlerSymbolId STRING,
   PRIMARY KEY (id)
 )`;
 // MCP tool definitions

package/dist/storage/parse-cache.js

@@ -52,7 +52,7 @@ import { fileURLToPath } from 'url';
 // the main thread (the #1983 OOM). Because the two stores share this version,
 // any future change to the `ParsedFile` serialization shape MUST bump
 // SCHEMA_BUMP so both invalidate in lockstep.
-const SCHEMA_BUMP = 6; // #2082 M2: cfgSideChannel gained bindings + per-block statement facts
+const SCHEMA_BUMP = 7; // #2138 Part 2: ExtractedDecoratorRoute gained `handlerName` (route handler symbol resolution)
 const GITNEXUS_PKG_VERSION = (() => {
     try {
         // package.json sits at gitnexus/package.json — two levels up from

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.9-rc.7",
+  "version": "1.6.9-rc.8",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",