gitnexus 1.6.5-rc.2 → 1.6.5-rc.21

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

@@ -5,6 +5,7 @@ import { generateId } from '../../lib/utils.js';
 import { getLanguageFromFilename, SupportedLanguages } from '../../_shared/index.js';
 import { extractVueScript, isVueSetupTopLevel } from './vue-sfc-extractor.js';
 import { yieldToEventLoop } from './utils/event-loop.js';
+import { parseSourceSafe } from '../tree-sitter/safe-parse.js';
 import { isVerboseIngestionEnabled } from './utils/verbose.js';
 import { getDefinitionNodeFromCaptures, findEnclosingClassInfo, getLabelFromCaptures, CLASS_CONTAINER_TYPES, } from './utils/ast-helpers.js';
 import { detectFrameworkFromAST } from './framework-detection.js';
@@ -15,35 +16,18 @@ import { getTreeSitterBufferSize, getTreeSitterContentByteLength, TREE_SITTER_MA
 // ============================================================================
 // Worker-based parallel parsing
 // ============================================================================
-const processParsingWithWorkers = async (graph, files, symbolTable, astCache, workerPool, onFileProgress) => {
-    // Filter to parseable files only
-    const parseableFiles = [];
-    for (const file of files) {
-        const lang = getLanguageFromFilename(file.path);
-        if (lang)
-            parseableFiles.push({ path: file.path, content: file.content });
-    }
-    if (parseableFiles.length === 0)
-        return {
-            imports: [],
-            calls: [],
-            assignments: [],
-            heritage: [],
-            routes: [],
-            fetchCalls: [],
-            decoratorRoutes: [],
-            toolDefs: [],
-            ormQueries: [],
-            constructorBindings: [],
-            fileScopeBindings: [],
-            parsedFiles: [],
-        };
-    const total = files.length;
-    // Dispatch to worker pool — pool handles splitting into chunks and sub-batching
-    const chunkResults = await workerPool.dispatch(parseableFiles, (filesProcessed) => {
-        onFileProgress?.(Math.min(filesProcessed, total), total, 'Parsing...');
-    });
-    // Merge results from all workers into graph and symbol table
+/**
+ * Merge a list of `ParseWorkerResult`s into the running graph + symbol
+ * table state and produce the chunk-aggregated `WorkerExtractedData`.
+ *
+ * Extracted from `processParsingWithWorkers` so the same merge logic can
+ * be applied to both freshly-parsed worker output AND cached worker
+ * output replayed during incremental analyze. Idempotent on the
+ * accumulator fields (push-only); idempotent on graph if the caller
+ * starts from a clean graph (otherwise duplicate `addNode` calls are
+ * silently no-op'd by `KnowledgeGraph`).
+ */
+export const mergeChunkResults = (graph, symbolTable, chunkResults) => {
     const allImports = [];
     const allCalls = [];
     const allAssignments = [];
@@ -102,14 +86,70 @@ const processParsingWithWorkers = async (graph, files, symbolTable, astCache, wo
         if (result.fileScopeBindings)
             for (const item of result.fileScopeBindings)
                 fileScopeBindingsByFile.push(item);
-        // RFC #909 Ring 2: aggregate per-file scope artifacts. Tolerant of
-        // workers that don't emit the field yet (older worker builds or
-        // partial rollouts), since the additive contract means undefined =
-        // "this worker produced no ParsedFiles for this chunk".
         if (result.parsedFiles)
             for (const item of result.parsedFiles)
                 allParsedFiles.push(item);
     }
+    return {
+        imports: allImports,
+        calls: allCalls,
+        assignments: allAssignments,
+        heritage: allHeritage,
+        routes: allRoutes,
+        fetchCalls: allFetchCalls,
+        decoratorRoutes: allDecoratorRoutes,
+        toolDefs: allToolDefs,
+        ormQueries: allORMQueries,
+        constructorBindings: allConstructorBindings,
+        fileScopeBindings: fileScopeBindingsByFile,
+        parsedFiles: allParsedFiles,
+    };
+};
+const processParsingWithWorkers = async (graph, files, symbolTable, astCache, workerPool, onFileProgress, 
+/**
+ * When provided, populated with the raw worker results before merging.
+ * Used by the incremental-indexing parse cache to capture the per-chunk
+ * worker output for caching across runs. The mutation happens in-place
+ * so the caller (parse-impl) can keep a reference. See
+ * `gitnexus/src/storage/parse-cache.ts`.
+ */
+outRawResults) => {
+    // Filter to parseable files only
+    const parseableFiles = [];
+    for (const file of files) {
+        const lang = getLanguageFromFilename(file.path);
+        if (lang)
+            parseableFiles.push({ path: file.path, content: file.content });
+    }
+    if (parseableFiles.length === 0)
+        return {
+            imports: [],
+            calls: [],
+            assignments: [],
+            heritage: [],
+            routes: [],
+            fetchCalls: [],
+            decoratorRoutes: [],
+            toolDefs: [],
+            ormQueries: [],
+            constructorBindings: [],
+            fileScopeBindings: [],
+            parsedFiles: [],
+        };
+    const total = files.length;
+    // Dispatch to worker pool — pool handles splitting into chunks and sub-batching
+    const chunkResults = await workerPool.dispatch(parseableFiles, (filesProcessed) => {
+        onFileProgress?.(Math.min(filesProcessed, total), total, 'Parsing...');
+    });
+    // Capture the raw chunk results for the incremental parse cache before
+    // merging — the cache stores the unmerged worker output so a future run
+    // can re-merge them into a fresh graph state.
+    if (outRawResults) {
+        for (const r of chunkResults)
+            outRawResults.push(r);
+    }
+    // Merge results from all workers into graph and symbol table.
+    const merged = mergeChunkResults(graph, symbolTable, chunkResults);
     // Merge and log skipped languages from workers
     const skippedLanguages = new Map();
     for (const result of chunkResults) {
@@ -125,20 +165,7 @@ const processParsingWithWorkers = async (graph, files, symbolTable, astCache, wo
     }
     // Final progress
     onFileProgress?.(total, total, 'done');
-    return {
-        imports: allImports,
-        calls: allCalls,
-        assignments: allAssignments,
-        heritage: allHeritage,
-        routes: allRoutes,
-        fetchCalls: allFetchCalls,
-        decoratorRoutes: allDecoratorRoutes,
-        toolDefs: allToolDefs,
-        ormQueries: allORMQueries,
-        constructorBindings: allConstructorBindings,
-        fileScopeBindings: fileScopeBindingsByFile,
-        parsedFiles: allParsedFiles,
-    };
+    return merged;
 };
 // ============================================================================
 // Sequential fallback (original implementation)
@@ -274,7 +301,7 @@ const processParsingSequential = async (graph, files, symbolTable, astCache, sco
         }
         let tree;
         try {
-            tree = parser.parse(parseContent, undefined, {
+            tree = parseSourceSafe(parser, parseContent, undefined, {
                 bufferSize: getTreeSitterBufferSize(parseContent),
             });
         }
@@ -561,7 +588,15 @@ export const processParsing = async (graph, files, symbolTable, astCache,
  * Worker-mode parses skip — Trees can't cross MessageChannels.
  * Pass `undefined` if no consumer needs cross-phase access.
  */
-scopeTreeCache, onFileProgress, workerPool) => {
+scopeTreeCache, onFileProgress, workerPool, 
+/**
+ * Optional out-parameter for the incremental parse cache. When
+ * provided AND the worker-pool path runs successfully, populated
+ * with the raw `ParseWorkerResult[]` from the workers (pre-merge).
+ * Stays empty for the sequential fallback path (no per-chunk
+ * artifact to cache there). See `gitnexus/src/storage/parse-cache.ts`.
+ */
+outRawResults) => {
     let lastProgress = 0;
     const reportProgress = onFileProgress
         ? (current, total, detail) => {
@@ -578,7 +613,7 @@ scopeTreeCache, onFileProgress, workerPool) => {
             logger.warn(`[scope-resolution prof] worker pool engaged for ${files.length} files — cross-phase tree cache will be empty; scope-resolution re-parses.`);
         }
         try {
-            return await processParsingWithWorkers(graph, files, symbolTable, astCache, workerPool, reportProgress);
+            return await processParsingWithWorkers(graph, files, symbolTable, astCache, workerPool, reportProgress, outRawResults);
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);

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

@@ -54,5 +54,10 @@ export declare function runChunkedParseAndResolve(graph: KnowledgeGraph, scanned
      *  source. See plan
      *  docs/plans/2026-04-20-002-perf-parse-heritage-mro-plan.md (Unit 4). */
     scopeTreeCache: ASTCache;
+    /** 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[];
 }>;
 export {};

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

@@ -12,7 +12,8 @@
  * @module
  */
 import { BindingAccumulator, enrichExportedTypeMap, } from '../binding-accumulator.js';
-import { processParsing } from '../parsing-processor.js';
+import { processParsing, mergeChunkResults } from '../parsing-processor.js';
+import { fileContentHash, computeChunkHash } from '../../../storage/parse-cache.js';
 import { processImports, processImportsFromExtracted, buildImportResolutionContext, } from '../import-processor.js';
 import { EMPTY_INDEX } from '../import-resolvers/utils.js';
 import { processCalls, processCallsFromExtracted, processAssignmentsFromExtracted, processRoutesFromExtracted, seedCrossFileReceiverTypes, buildExportedTypeMapFromGraph, } from '../call-processor.js';
@@ -33,8 +34,22 @@ import { synthesizeWildcardImportBindings, needsSynthesis } from './wildcard-syn
 import { extractORMQueriesInline } from './orm-extraction.js';
 import { logger } from '../../logger.js';
 // ── Constants ──────────────────────────────────────────────────────────────
-/** Max bytes of source content to load per parse chunk. */
-const CHUNK_BYTE_BUDGET = 20 * 1024 * 1024; // 20MB
+/** Max bytes of source content to load per parse chunk.
+ *
+ * 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.
+ */
+const CHUNK_BYTE_BUDGET = (() => {
+    const env = Number(process.env.GITNEXUS_CHUNK_BYTE_BUDGET);
+    if (Number.isFinite(env) && env > 0)
+        return env;
+    return 2 * 1024 * 1024;
+})();
 /**
  * Chunked parse + resolve loop.
  *
@@ -64,6 +79,14 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
     for (const [lang, count] of skippedByLang) {
         logger.warn(`Skipping ${count} ${lang} file(s) — ${lang} parser not available (native binding may not have built). Try: npm rebuild tree-sitter-${lang}`);
     }
+    // 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;
     if (totalParseable === 0) {
         onProgress({
@@ -164,6 +187,19 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
     const deferredWorkerHeritage = [];
     const deferredConstructorBindings = [];
     const deferredAssignments = [];
+    // Aggregated per-file ParsedFile artifacts produced by workers' calls
+    // to `extractParsedFile`. Threaded through to the scope-resolution
+    // phase so it can SKIP its own re-extraction on cache hits — this is
+    // the second-half of the parse-cache speedup since scope-resolution's
+    // re-parse otherwise dominates the warm-cache wall-clock time.
+    const allParsedFiles = [];
+    // Incremental parse cache (Option B): chunk-level content-addressed.
+    // When the chunk's (filePath, content-hash) signature matches a prior
+    // run's, replay the cached ParseWorkerResult[] instead of dispatching
+    // to workers. See gitnexus/src/storage/parse-cache.ts.
+    const parseCache = options?.parseCache;
+    let chunkCacheHits = 0;
+    let chunkCacheMisses = 0;
     try {
         for (let chunkIdx = 0; chunkIdx < numChunks; chunkIdx++) {
             const chunkPaths = chunks[chunkIdx];
@@ -171,21 +207,76 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
             const chunkFiles = chunkPaths
                 .filter((p) => chunkContents.has(p))
                 .map((p) => ({ path: p, content: chunkContents.get(p) }));
-            const chunkWorkerData = await processParsing(graph, chunkFiles, symbolTable, astCache, scopeTreeCache, (current, _total, filePath) => {
-                const globalCurrent = filesParsedSoFar + current;
-                const parsingProgress = 20 + (globalCurrent / totalParseable) * 62;
+            // Compute the chunk's content-hash signature (if cache available).
+            let chunkHash = null;
+            if (parseCache) {
+                const entries = chunkFiles.map((f) => ({
+                    filePath: f.path,
+                    contentHash: fileContentHash(f.content),
+                }));
+                chunkHash = computeChunkHash(entries);
+            }
+            let chunkWorkerData;
+            const cachedRaw = chunkHash ? parseCache.entries.get(chunkHash) : undefined;
+            // Track every chunk hash we touched so the orchestrator can
+            // prune stale entries (chunks whose composition no longer
+            // corresponds to a live chunk in the current scan) before saving.
+            if (parseCache && chunkHash)
+                parseCache.usedKeys.add(chunkHash);
+            if (cachedRaw && cachedRaw.length > 0) {
+                // Cache hit: replay the cached worker output through the same
+                // merge logic the live worker path uses.
+                chunkCacheHits++;
+                chunkWorkerData = mergeChunkResults(graph, symbolTable, cachedRaw);
+                if (isDev) {
+                    logger.info(`📦 parse-cache HIT: chunk ${chunkIdx + 1}/${numChunks} (${chunkFiles.length} files, ${chunkHash.slice(0, 8)})`);
+                }
+                // Progress update so UI advances even on a cache hit.
+                const cachedFiles = chunkFiles.length;
                 onProgress({
                     phase: 'parsing',
-                    percent: Math.round(parsingProgress),
-                    message: `Parsing chunk ${chunkIdx + 1}/${numChunks}...`,
-                    detail: filePath,
+                    percent: Math.round(20 + ((filesParsedSoFar + cachedFiles) / totalParseable) * 62),
+                    message: `Parsing chunk ${chunkIdx + 1}/${numChunks} (cache)...`,
                     stats: {
-                        filesProcessed: globalCurrent,
+                        filesProcessed: filesParsedSoFar + cachedFiles,
                         totalFiles: totalParseable,
                         nodesCreated: graph.nodeCount,
                     },
                 });
-            }, workerPool);
+            }
+            else {
+                // Cache miss: dispatch to workers, capture the raw results, store
+                // them under the chunk hash for the next run.
+                chunkCacheMisses++;
+                const rawResults = [];
+                chunkWorkerData = await processParsing(graph, chunkFiles, symbolTable, astCache, scopeTreeCache, (current, _total, filePath) => {
+                    const globalCurrent = filesParsedSoFar + current;
+                    const parsingProgress = 20 + (globalCurrent / totalParseable) * 62;
+                    onProgress({
+                        phase: 'parsing',
+                        percent: Math.round(parsingProgress),
+                        message: `Parsing chunk ${chunkIdx + 1}/${numChunks}...`,
+                        detail: filePath,
+                        stats: {
+                            filesProcessed: globalCurrent,
+                            totalFiles: totalParseable,
+                            nodesCreated: graph.nodeCount,
+                        },
+                    });
+                }, workerPool, 
+                // Capture raw results only when we have a cache to write to —
+                // otherwise we'd retain extra arrays for nothing.
+                parseCache && chunkHash ? rawResults : undefined);
+                // Persist the raw results for this chunk hash. Sequential path
+                // doesn't populate rawResults (it writes directly to graph), so
+                // small repos without worker pool simply don't cache. That's fine.
+                if (parseCache && chunkHash && rawResults.length > 0) {
+                    parseCache.entries.set(chunkHash, rawResults);
+                    if (isDev) {
+                        logger.info(`📦 parse-cache MISS+store: chunk ${chunkIdx + 1}/${numChunks} (${chunkFiles.length} files, ${chunkHash.slice(0, 8)})`);
+                    }
+                }
+            }
             const chunkBasePercent = 20 + (filesParsedSoFar / totalParseable) * 62;
             if (chunkWorkerData) {
                 await processImportsFromExtracted(graph, allPathObjects, chunkWorkerData.imports, ctx, (current, total) => {
@@ -217,6 +308,13 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
                     deferredWorkerHeritage.push(item);
                 for (const item of chunkWorkerData.constructorBindings)
                     deferredConstructorBindings.push(item);
+                // Aggregate worker-produced ParsedFile artifacts so scope-
+                // resolution can use them as a re-extraction cache (skips its
+                // own tree-sitter re-parse on warm runs).
+                if (chunkWorkerData.parsedFiles?.length) {
+                    for (const item of chunkWorkerData.parsedFiles)
+                        allParsedFiles.push(item);
+                }
                 if (chunkWorkerData.assignments?.length) {
                     for (const item of chunkWorkerData.assignments)
                         deferredAssignments.push(item);
@@ -297,6 +395,9 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
             filesParsedSoFar += chunkFiles.length;
             astCache.clear();
         }
+        if (isDev && parseCache && (chunkCacheHits > 0 || chunkCacheMisses > 0)) {
+            logger.info(`📦 parse-cache summary: ${chunkCacheHits} chunk hit(s), ${chunkCacheMisses} miss(es) across ${numChunks} chunk(s)`);
+        }
         const fullWorkerHeritageMap = deferredWorkerHeritage.length > 0
             ? buildHeritageMap(deferredWorkerHeritage, ctx, getHeritageStrategyForLanguage)
             : undefined;
@@ -455,5 +556,12 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
         // chunk-local `astCache` above is intentionally NOT exposed
         // because parse-impl clears it between chunks.
         scopeTreeCache,
+        // Per-file ParsedFile artifacts produced by workers' calls to
+        // `extractParsedFile`. Empty when only the sequential path ran
+        // (sequential doesn't go through the worker, and extracts ParsedFile
+        // inline rather than emitting it). 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,
     };
 }

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

@@ -17,6 +17,7 @@
  */
 import type { PipelinePhase } from './types.js';
 import type { BindingAccumulator } from '../binding-accumulator.js';
+import type { ParsedFile } from '../../../_shared/index.js';
 import type { ExtractedFetchCall, ExtractedRoute, ExtractedDecoratorRoute, ExtractedToolDef, ExtractedORMQuery } from '../workers/parse-worker.js';
 import type { createResolutionContext } from '../model/resolution-context.js';
 import type { ASTCache } from '../ast-cache.js';
@@ -70,5 +71,18 @@ export interface ParseOutput {
      * `scopeTreeCache.clear()` after its extract loop finishes.
      */
     readonly scopeTreeCache: ASTCache;
+    /**
+     * Per-file `ParsedFile` artifacts produced by workers' calls to
+     * `extractParsedFile`. Threaded through to `scopeResolutionPhase`
+     * as a re-extraction cache: when a file's ParsedFile is present here,
+     * scope-resolution can skip its own `extractParsedFile` (which would
+     * otherwise re-parse the file with tree-sitter on the main thread,
+     * costing ~58s on a 1000-file repo).
+     *
+     * Empty for files that went through the sequential parse fallback —
+     * sequential doesn't emit ParsedFile artifacts; scope-resolution
+     * falls back to a fresh extract for those.
+     */
+    readonly parsedFiles: readonly ParsedFile[];
 }
 export declare const parsePhase: PipelinePhase<ParseOutput>;

package/dist/core/ingestion/pipeline.d.ts

@@ -32,5 +32,18 @@ export interface PipelineOptions {
         minFiles?: number;
         minBytes?: number;
     };
+    /**
+     * Incremental-indexing parse cache. When provided:
+     *   - The parse phase looks up each chunk's content hash in
+     *     `parseCache.entries`. On hit, it replays the cached
+     *     `ParseWorkerResult[]` instead of dispatching to workers.
+     *   - On miss, it runs the workers as today and stores the new
+     *     results in `parseCache.entries` keyed by chunk hash.
+     * The caller (`run-analyze.ts`) is responsible for loading the cache
+     * before the pipeline runs and persisting it after. Cache survives
+     * `--force` because keys are content-addressed.
+     * See `gitnexus/src/storage/parse-cache.ts`.
+     */
+    parseCache?: import('../../storage/parse-cache.js').ParseCache;
 }
 export declare const runPipelineFromRepo: (repoPath: string, onProgress: (progress: PipelineProgress) => void, options?: PipelineOptions) => Promise<PipelineResult>;

package/dist/core/ingestion/registry-primary-flag.js

@@ -69,6 +69,8 @@ export const MIGRATED_LANGUAGES = new Set([
     SupportedLanguages.CSharp,
     SupportedLanguages.TypeScript,
     SupportedLanguages.Go,
+    SupportedLanguages.C,
+    SupportedLanguages.PHP,
 ]);
 /**
  * Return the env-var name that controls a given language's registry-

package/dist/core/ingestion/scope-resolution/contract/scope-resolver.d.ts

@@ -342,6 +342,21 @@ export interface ScopeResolver {
      * inheritance).
      */
     buildMro(graph: KnowledgeGraph, parsedFiles: readonly ParsedFile[], nodeLookup: GraphNodeLookup): Map<string, string[]>;
+    /**
+     * Optional parallel MRO that EXCLUDES mixin-like augmentation (e.g., PHP
+     * traits). Returns the inheritance-only ancestor chain — the same kind
+     * of map as `buildMro` but built only from inheritance edges (EXTENDS).
+     *
+     * Used by the shared super-branch dispatch in `receiver-bound-calls`
+     * so that `parent::method()` walks the inheritance chain only, not the
+     * trait-augmented one. PHP semantics: `parent::` explicitly bypasses
+     * traits, even when a composed trait shadows a same-named parent method.
+     *
+     * Languages without mixin-like semantics leave this undefined — callers
+     * fall back to `buildMro`/`mroFor`, which for those languages is already
+     * the inheritance chain.
+     */
+    readonly buildExtendsOnlyMro?: (graph: KnowledgeGraph, parsedFiles: readonly ParsedFile[], nodeLookup: GraphNodeLookup) => Map<string, string[]>;
     /**
      * Mutate `parsed.localDefs[i].ownerId` to point at the structural
      * owner. Python's rule: methods (Function defs whose parent scope
@@ -414,6 +429,36 @@ export interface ScopeResolver {
      * but is too loose as a default for strict module systems.
      */
     readonly allowGlobalFreeCallFallback?: boolean;
+    /**
+     * Optional predicate to identify definitions with file-local linkage
+     * (e.g. C `static` functions). When provided, `pickUniqueGlobalCallable`
+     * excludes defs where `isFileLocalDef(def) === true` and the def lives
+     * in a different file from the caller. This prevents the global free-call
+     * fallback from creating CALLS edges to file-local symbols that are
+     * logically invisible from the caller's translation unit.
+     *
+     * Languages without file-local linkage semantics leave this undefined.
+     */
+    readonly isFileLocalDef?: (def: SymbolDefinition) => boolean;
+    /**
+     * Optional predicate to gate free-call fallback emission by caller-side
+     * visibility. When provided, `pickUniqueGlobalCallable` rejects candidates
+     * the caller cannot legally reach — e.g., a PHP function in a different
+     * namespace with no `use function` import, which PHP runtime would treat
+     * as `Call to undefined function`. Returning `false` blocks the candidate;
+     * returning `true` allows it; undefined-default keeps current behavior
+     * (no visibility filtering, equivalent to "all candidates visible").
+     *
+     * The hook receives the caller's `ParsedFile` (so it can consult
+     * `parsedImports`, `moduleScope`, etc.) and the candidate `SymbolDefinition`.
+     * The predicate must be pure: same inputs → same answer.
+     *
+     * Languages without namespace-scoped function resolution leave this undefined.
+     */
+    readonly isCallableVisibleFromCaller?: (ctx: {
+        readonly callerParsed: ParsedFile;
+        readonly candidate: SymbolDefinition;
+    }) => boolean;
     /**
      * Optional post-finalize hook to inject cross-file bindings that
      * aren't modeled via explicit imports. Runs after
@@ -490,4 +535,24 @@ export interface ScopeResolver {
             get(filePath: string): unknown;
         };
     }) => void;
+    /**
+     * Optional post-resolution pass: emit CALLS edges for member-call sites
+     * whose receiver cannot be typed by the scope chain (no `TypeRef`).
+     * Dynamically-typed languages with untyped/`mixed`/`Any` parameters use
+     * this hook to recover the call edge via workspace-wide method-name
+     * lookup, mirroring what their legacy resolvers did.
+     *
+     * Runs AFTER `emitReceiverBoundCalls` and BEFORE `emitFreeCallFallback`.
+     * Implementations MUST:
+     *   - Skip sites already in `handledSites` (Invariant I2).
+     *   - Add resolved site keys to `handledSites` before returning.
+     *   - Stay narrow: a unique workspace-wide match is the safe baseline.
+     *     Multi-candidate fallbacks should narrow by arity / argument types
+     *     before emitting to keep false-positive rate bounded.
+     *
+     * Returns the number of edges emitted (for telemetry).
+     *
+     * Default: undefined (no unresolved-receiver fallback).
+     */
+    readonly emitUnresolvedReceiverEdges?: (graph: KnowledgeGraph, scopes: ScopeResolutionIndexes, parsedFiles: readonly ParsedFile[], nodeLookup: GraphNodeLookup, handledSites: Set<string>, model: SemanticModel) => number;
 }

package/dist/core/ingestion/scope-resolution/graph-bridge/method-dispatch.d.ts

@@ -16,4 +16,4 @@
  * can extend the return shape without breaking existing consumers.
  */
 import type { MethodDispatchIndex } from '../../../../_shared/index.js';
-export declare function buildPopulatedMethodDispatch(mroByDefId: ReadonlyMap<string, readonly string[]>): MethodDispatchIndex;
+export declare function buildPopulatedMethodDispatch(mroByDefId: ReadonlyMap<string, readonly string[]>, extendsOnlyMroByDefId?: ReadonlyMap<string, readonly string[]>): MethodDispatchIndex;

package/dist/core/ingestion/scope-resolution/graph-bridge/method-dispatch.js

@@ -16,8 +16,8 @@
  * can extend the return shape without breaking existing consumers.
  */
 const EMPTY_DEFS = Object.freeze([]);
-export function buildPopulatedMethodDispatch(mroByDefId) {
-    return {
+export function buildPopulatedMethodDispatch(mroByDefId, extendsOnlyMroByDefId) {
+    const base = {
         mroByOwnerDefId: mroByDefId,
         implsByInterfaceDefId: new Map(),
         mroFor(ownerDefId) {
@@ -27,4 +27,14 @@ export function buildPopulatedMethodDispatch(mroByDefId) {
             return EMPTY_DEFS;
         },
     };
+    if (extendsOnlyMroByDefId !== undefined) {
+        return {
+            ...base,
+            extendsOnlyMroByOwnerDefId: extendsOnlyMroByDefId,
+            extendsOnlyMroFor(ownerDefId) {
+                return extendsOnlyMroByDefId.get(ownerDefId) ?? EMPTY_DEFS;
+            },
+        };
+    }
+    return base;
 }

package/dist/core/ingestion/scope-resolution/graph-bridge/node-lookup.js

@@ -105,6 +105,11 @@ export function isLinkableLabel(label) {
         label === 'Interface' ||
         label === 'Struct' ||
         label === 'Enum' ||
+        // Trait nodes are linkable so MRO builders can bridge PHP/Rust trait
+        // defs between scope-resolution DefIds and the graph's node ids.
+        // IMPLEMENTS edges from classes to traits are otherwise invisible to
+        // the scope-resolution MRO pass.
+        label === 'Trait' ||
         // Variable / Property are linkable too — receiver-bound write/read
         // ACCESSES edges target field nodes (e.g. `user.name = "x"` →
         // ACCESSES edge to User's `name` Variable/Property node).

package/dist/core/ingestion/scope-resolution/passes/free-call-fallback.d.ts

@@ -16,7 +16,7 @@
  * Generic; promoted from `languages/python/scope-resolver.ts` per the scope-resolution
  * generalization plan.
  */
-import type { ParsedFile, Reference, ScopeId } from '../../../../_shared/index.js';
+import type { ParsedFile, Reference, ScopeId, SymbolDefinition } from '../../../../_shared/index.js';
 import type { KnowledgeGraph } from '../../../graph/types.js';
 import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js';
 import type { SemanticModel } from '../../model/semantic-model.js';
@@ -26,4 +26,28 @@ export declare function emitFreeCallFallback(graph: KnowledgeGraph, scopes: Scop
     readonly bySourceScope: ReadonlyMap<ScopeId, readonly Reference[]>;
 }, handledSites: Set<string>, model: SemanticModel, workspaceIndex: WorkspaceResolutionIndex, options?: {
     readonly allowGlobalFallback?: boolean;
+    readonly isFileLocalDef?: (def: SymbolDefinition) => boolean;
+    readonly isCallableVisibleFromCaller?: (ctx: {
+        readonly callerParsed: ParsedFile;
+        readonly candidate: SymbolDefinition;
+    }) => boolean;
 }): number;
+/** Walk up from the call-site scope to the enclosing class scope,
+ *  pick a method member by name with overload narrowing on arity +
+ *  argument types. Returns undefined if there's no enclosing class,
+ *  no matching method, OR narrowing leaves multiple compatible
+ *  candidates — in the multi-candidate case, picking
+ *  `candidates[0]` would emit a high-confidence CALLS edge whose
+ *  target depends on registration order rather than a defensible
+ *  resolution. Mirrors `pickUniqueGlobalCallable`'s uniqueness check
+ *  in the same file (Codex PR #1497 review, finding 2).
+ *
+ *  Exported for unit testing — language-agnostic logic, exercised
+ *  via synthetic stubs in `pick-implicit-this-overload.test.ts`. The
+ *  production call site is `applyFreeCallFallback` immediately above. */
+export declare function pickImplicitThisOverload(site: {
+    readonly inScope: ScopeId;
+    readonly name: string;
+    readonly arity?: number;
+    readonly argumentTypes?: readonly string[];
+}, scopes: ScopeResolutionIndexes, workspaceIndex: WorkspaceResolutionIndex, model: SemanticModel): SymbolDefinition | undefined;