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

package/dist/core/ingestion/languages/java/receiver-binding.js

@@ -0,0 +1,95 @@
+/**
+ * Synthesize `@type-binding.self` captures for Java instance methods —
+ * one for `this` (always on non-static methods inside a type
+ * declaration) and optionally one for `super` (only on class methods
+ * when the enclosing class has a `superclass`).
+ *
+ * Mirrors `languages/csharp/receiver-binding.ts` in structure.
+ */
+import { nodeToCapture, syntheticCapture } from '../../utils/ast-helpers.js';
+const TYPE_DECL_NODE_TYPES = new Set([
+    'class_declaration',
+    'interface_declaration',
+    'enum_declaration',
+    'record_declaration',
+]);
+const FUNCTION_NODE_TYPES = new Set(['method_declaration', 'constructor_declaration']);
+/** Walk up to the enclosing type declaration. */
+function findEnclosingTypeDeclaration(node) {
+    let cur = node.parent;
+    while (cur !== null) {
+        if (TYPE_DECL_NODE_TYPES.has(cur.type))
+            return cur;
+        cur = cur.parent;
+    }
+    return null;
+}
+function typeName(typeNode) {
+    return typeNode.childForFieldName('name')?.text ?? null;
+}
+/** First superclass text. tree-sitter-java uses a `superclass` field
+ *  containing a `superclass` node wrapping a `type_identifier`. */
+function firstSuperclassText(typeNode) {
+    const superclass = typeNode.childForFieldName('superclass');
+    if (superclass === null)
+        return null;
+    // The superclass node wraps the type_identifier
+    for (let i = 0; i < superclass.namedChildCount; i++) {
+        const child = superclass.namedChild(i);
+        if (child !== null && (child.type === 'type_identifier' || child.type === 'generic_type')) {
+            return child.text;
+        }
+    }
+    return null;
+}
+/** Check if a method has the `static` modifier. In tree-sitter-java,
+ *  modifiers are grouped under a `modifiers` named child with anonymous
+ *  keyword tokens. */
+function isStaticMethod(fnNode) {
+    for (let i = 0; i < fnNode.namedChildCount; i++) {
+        const child = fnNode.namedChild(i);
+        if (child !== null && child.type === 'modifiers') {
+            for (let j = 0; j < child.childCount; j++) {
+                const mod = child.child(j);
+                if (mod !== null && mod.text.trim() === 'static')
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+export function synthesizeJavaReceiverBinding(fnNode) {
+    if (!FUNCTION_NODE_TYPES.has(fnNode.type))
+        return [];
+    if (isStaticMethod(fnNode))
+        return [];
+    const enclosingType = findEnclosingTypeDeclaration(fnNode);
+    if (enclosingType === null)
+        return [];
+    const enclosingName = typeName(enclosingType);
+    if (enclosingName === null)
+        return [];
+    // Anchor to the method body so the synthesized captures are inside
+    // the function scope.
+    const anchorNode = fnNode.childForFieldName('body');
+    if (anchorNode === null)
+        return [];
+    const out = [];
+    out.push(buildReceiverMatch(anchorNode, 'this', enclosingName));
+    // `super` applies only to class/record methods with an explicit superclass.
+    if (enclosingType.type === 'class_declaration' || enclosingType.type === 'record_declaration') {
+        const superText = firstSuperclassText(enclosingType);
+        if (superText !== null) {
+            out.push(buildReceiverMatch(anchorNode, 'super', superText));
+        }
+    }
+    return out;
+}
+function buildReceiverMatch(anchorNode, name, typeText) {
+    const m = {
+        '@type-binding.self': nodeToCapture('@type-binding.self', anchorNode),
+        '@type-binding.name': syntheticCapture('@type-binding.name', anchorNode, name),
+        '@type-binding.type': syntheticCapture('@type-binding.type', anchorNode, typeText),
+    };
+    return m;
+}

package/dist/core/ingestion/languages/java/scope-resolver.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Java `ScopeResolver` registered in `SCOPE_RESOLVERS` and consumed by
+ * the generic `runScopeResolution` orchestrator (RFC #909 Ring 3).
+ *
+ * ## Registry-primary parity status
+ *
+ * Java is **not** in `MIGRATED_LANGUAGES` — the scope-resolution
+ * registry runs in shadow mode only.  Parity in forced registry mode
+ * (`REGISTRY_PRIMARY_JAVA=1`) is 143/172 (83%).  The 29 gaps fall into:
+ *
+ *   - switch pattern binding / sealed-class exhaustiveness
+ *   - Map.values() / entrySet() iteration type propagation
+ *   - assignment / method chain return-type propagation across files
+ *   - virtual dispatch / interface default methods
+ *
+ * These are the same category of advanced-resolution gaps seen in prior
+ * migrations (Python, C#, Go).  Parity is below the ≥99% flip threshold
+ * per RFC §6.4.
+ *
+ * **CI visibility:** Because Java is absent from `MIGRATED_LANGUAGES`,
+ * the parity CI workflow (`ci-scope-parity.yml`) does not run Java in
+ * either `REGISTRY_PRIMARY_JAVA=0` or `=1` mode.  Regressions in forced
+ * mode are only visible via manual `REGISTRY_PRIMARY_JAVA=1 npx vitest
+ * run java.test.ts`.  Before flipping Java to registry-primary, a
+ * non-required CI step should be added to run Java tests in forced mode
+ * and report parity as a dashboard input.
+ *
+ * **Parity baseline (29 failures):** The 29 gaps in forced registry mode
+ * are tracked in this PR (#1482) and this JSDoc.  If the gap count
+ * changes (up or down), update this baseline accordingly.
+ *
+ * ### Known flip-blockers (must fix before adding to MIGRATED_LANGUAGES)
+ *
+ *   - Varargs arity: fixed-prefix count is now preserved, but no
+ *     integration fixture exercises the 0-arg rejection path yet.
+ *   - Static import resolution: `import static X.Y.m` now correctly
+ *     resolves to `X/Y.java` (the class), not `X/Y/m.java` (the member).
+ *     Edge cases with nested classes may remain.
+ *   - Generic superclass receiver binding: `BaseModel<T>` now strips
+ *     to `BaseModel` via JVM type-erasure fallback in `stripGeneric`.
+ *   - Wildcard import (`import com.example.*`) file selection is
+ *     nondeterministic when multiple classes share a package directory.
+ *     May produce wrong-file edges in forced mode.
+ *   - Qualified generic type parameters in field/parameter annotations
+ *     (`com.example.BaseModel<T>`) — rare in practice but may miss
+ *     resolution when the full qualifier is present with generics.
+ */
+import type { ScopeResolver } from '../../scope-resolution/contract/scope-resolver.js';
+declare const javaScopeResolver: ScopeResolver;
+export { javaScopeResolver };

package/dist/core/ingestion/languages/java/scope-resolver.js

@@ -0,0 +1,74 @@
+/**
+ * Java `ScopeResolver` registered in `SCOPE_RESOLVERS` and consumed by
+ * the generic `runScopeResolution` orchestrator (RFC #909 Ring 3).
+ *
+ * ## Registry-primary parity status
+ *
+ * Java is **not** in `MIGRATED_LANGUAGES` — the scope-resolution
+ * registry runs in shadow mode only.  Parity in forced registry mode
+ * (`REGISTRY_PRIMARY_JAVA=1`) is 143/172 (83%).  The 29 gaps fall into:
+ *
+ *   - switch pattern binding / sealed-class exhaustiveness
+ *   - Map.values() / entrySet() iteration type propagation
+ *   - assignment / method chain return-type propagation across files
+ *   - virtual dispatch / interface default methods
+ *
+ * These are the same category of advanced-resolution gaps seen in prior
+ * migrations (Python, C#, Go).  Parity is below the ≥99% flip threshold
+ * per RFC §6.4.
+ *
+ * **CI visibility:** Because Java is absent from `MIGRATED_LANGUAGES`,
+ * the parity CI workflow (`ci-scope-parity.yml`) does not run Java in
+ * either `REGISTRY_PRIMARY_JAVA=0` or `=1` mode.  Regressions in forced
+ * mode are only visible via manual `REGISTRY_PRIMARY_JAVA=1 npx vitest
+ * run java.test.ts`.  Before flipping Java to registry-primary, a
+ * non-required CI step should be added to run Java tests in forced mode
+ * and report parity as a dashboard input.
+ *
+ * **Parity baseline (29 failures):** The 29 gaps in forced registry mode
+ * are tracked in this PR (#1482) and this JSDoc.  If the gap count
+ * changes (up or down), update this baseline accordingly.
+ *
+ * ### Known flip-blockers (must fix before adding to MIGRATED_LANGUAGES)
+ *
+ *   - Varargs arity: fixed-prefix count is now preserved, but no
+ *     integration fixture exercises the 0-arg rejection path yet.
+ *   - Static import resolution: `import static X.Y.m` now correctly
+ *     resolves to `X/Y.java` (the class), not `X/Y/m.java` (the member).
+ *     Edge cases with nested classes may remain.
+ *   - Generic superclass receiver binding: `BaseModel<T>` now strips
+ *     to `BaseModel` via JVM type-erasure fallback in `stripGeneric`.
+ *   - Wildcard import (`import com.example.*`) file selection is
+ *     nondeterministic when multiple classes share a package directory.
+ *     May produce wrong-file edges in forced mode.
+ *   - Qualified generic type parameters in field/parameter annotations
+ *     (`com.example.BaseModel<T>`) — rare in practice but may miss
+ *     resolution when the full qualifier is present with generics.
+ */
+import { SupportedLanguages } from '../../../../_shared/index.js';
+import { buildMro, defaultLinearize } from '../../scope-resolution/passes/mro.js';
+import { populateClassOwnedMembers } from '../../scope-resolution/scope/walkers.js';
+import { javaProvider } from '../java.js';
+import { javaArityCompatibility, javaMergeBindings, resolveJavaImportTarget, } from './index.js';
+const javaScopeResolver = {
+    language: SupportedLanguages.Java,
+    languageProvider: javaProvider,
+    importEdgeReason: 'java-scope: import',
+    resolveImportTarget: (targetRaw, fromFile, allFilePaths) => {
+        const ws = { fromFile, allFilePaths };
+        return resolveJavaImportTarget({ kind: 'named', localName: '_', importedName: '_', targetRaw }, ws);
+    },
+    mergeBindings: (existing, incoming) => [...javaMergeBindings([...existing, ...incoming])],
+    arityCompatibility: (callsite, def) => javaArityCompatibility(def, callsite),
+    buildMro: (graph, parsedFiles, nodeLookup) => buildMro(graph, parsedFiles, nodeLookup, defaultLinearize),
+    populateOwners: (parsed) => populateClassOwnedMembers(parsed),
+    isSuperReceiver: (text) => text.trim() === 'super',
+    // Java is statically typed — field-fallback heuristic stays off
+    fieldFallbackOnMethodLookup: false,
+    propagatesReturnTypesAcrossImports: true,
+    // Java doesn't collapse member calls
+    collapseMemberCallsByCallerTarget: false,
+    // Hoist return-type bindings to Module scope for cross-file propagation
+    hoistTypeBindingsToModule: true,
+};
+export { javaScopeResolver };

package/dist/core/ingestion/languages/java/simple-hooks.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Small hooks for the Java provider. Each is a few lines; they make
+ * the provider's choice explicit rather than relying on defaults.
+ */
+import type { CaptureMatch, ParsedImport, Scope, ScopeId, ScopeTree, TypeRef } from '../../../../_shared/index.js';
+/** Method return-type bindings hoist to Module scope so cross-file
+ *  `propagateImportedReturnTypes` and chain-follow can find them. */
+export declare function javaBindingScopeFor(decl: CaptureMatch, innermost: Scope, tree: ScopeTree): ScopeId | null;
+/** Java imports are always at compilation-unit (Module) level (JLS §7.5).
+ *  Return `null` unconditionally so the default Module scope is used. */
+export declare function javaImportOwningScope(_imp: ParsedImport, _innermost: Scope, _tree: ScopeTree): ScopeId | null;
+/** Look up `this` or `super` in the function scope's type bindings. */
+export declare function javaReceiverBinding(functionScope: Scope): TypeRef | null;

package/dist/core/ingestion/languages/java/simple-hooks.js

@@ -0,0 +1,34 @@
+/**
+ * Small hooks for the Java provider. Each is a few lines; they make
+ * the provider's choice explicit rather than relying on defaults.
+ */
+// ─── bindingScopeFor ──────────────────────────────────────────────────────
+/** Method return-type bindings hoist to Module scope so cross-file
+ *  `propagateImportedReturnTypes` and chain-follow can find them. */
+export function javaBindingScopeFor(decl, innermost, tree) {
+    if (decl['@type-binding.return'] !== undefined) {
+        let cur = innermost;
+        while (cur !== undefined && cur.kind !== 'Module') {
+            const parentId = cur.parent ?? null;
+            if (parentId === null)
+                break;
+            cur = tree.getScope(parentId);
+        }
+        if (cur !== undefined && cur.kind === 'Module')
+            return cur.id;
+    }
+    return null;
+}
+// ─── importOwningScope ────────────────────────────────────────────────────
+/** Java imports are always at compilation-unit (Module) level (JLS §7.5).
+ *  Return `null` unconditionally so the default Module scope is used. */
+export function javaImportOwningScope(_imp, _innermost, _tree) {
+    return null;
+}
+// ─── receiverBinding ──────────────────────────────────────────────────────
+/** Look up `this` or `super` in the function scope's type bindings. */
+export function javaReceiverBinding(functionScope) {
+    if (functionScope.kind !== 'Function')
+        return null;
+    return functionScope.typeBindings.get('this') ?? functionScope.typeBindings.get('super') ?? null;
+}

package/dist/core/ingestion/languages/java.js

@@ -25,6 +25,7 @@ import { javaMethodConfig } from '../method-extractors/configs/jvm.js';
 import { createVariableExtractor } from '../variable-extractors/generic.js';
 import { javaVariableConfig } from '../variable-extractors/configs/jvm.js';
 import { createHeritageExtractor } from '../heritage-extractors/generic.js';
+import { emitJavaScopeCaptures, interpretJavaImport, interpretJavaTypeBinding, javaBindingScopeFor, javaImportOwningScope, javaMergeBindings, javaReceiverBinding, javaArityCompatibility, resolveJavaImportTarget, } from './java/index.js';
 export const javaProvider = defineLanguage({
     id: SupportedLanguages.Java,
     extensions: ['.java'],
@@ -62,4 +63,14 @@ export const javaProvider = defineLanguage({
     variableExtractor: createVariableExtractor(javaVariableConfig),
     classExtractor: createClassExtractor(javaClassConfig),
     heritageExtractor: createHeritageExtractor(SupportedLanguages.Java),
+    // ── RFC #909 Ring 3: scope-based resolution hooks ──
+    emitScopeCaptures: emitJavaScopeCaptures,
+    interpretImport: interpretJavaImport,
+    interpretTypeBinding: interpretJavaTypeBinding,
+    bindingScopeFor: javaBindingScopeFor,
+    importOwningScope: javaImportOwningScope,
+    mergeBindings: (_scope, bindings) => javaMergeBindings(bindings),
+    receiverBinding: javaReceiverBinding,
+    arityCompatibility: javaArityCompatibility,
+    resolveImportTarget: resolveJavaImportTarget,
 });

package/dist/core/ingestion/languages/php/arity-metadata.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Extract PHP arity metadata from a method-like tree-sitter node —
+ * `method_declaration` or `function_definition`.
+ *
+ * Reuses `phpMethodConfig.extractParameters` so scope-extracted defs
+ * carry the same arity semantics as the legacy parse-worker path:
+ *   - `variadic_parameter` (`...$args`) collapses `parameterCount` to
+ *     `undefined`, which `phpArityCompatibility` then treats as
+ *     "max unknown" — the candidate stays eligible at `argCount >= required`.
+ *   - Defaulted parameters (`= expr`) contribute to `optionalCount`;
+ *     `requiredParameterCount = total − optionalCount − (variadic ? 1 : 0)`.
+ *     The variadic slot itself accepts zero args so it is subtracted from
+ *     the required count — `f(int $a, ...$rest)` requires exactly 1 arg,
+ *     not 2, and `f(...$rest)` requires 0.
+ *   - `property_promotion_parameter` (constructor-promoted) is counted
+ *     the same as `simple_parameter` since both consume an argument slot.
+ *   - `parameterTypes` collects declared type names; a literal `'...'`
+ *     marker is appended for variadic methods so `phpArityCompatibility`
+ *     can detect them without re-reading the AST.
+ */
+import type { SyntaxNode } from '../../utils/ast-helpers.js';
+interface PhpArityMetadata {
+    readonly parameterCount: number | undefined;
+    readonly requiredParameterCount: number | undefined;
+    readonly parameterTypes: readonly string[] | undefined;
+}
+export declare function computePhpArityMetadata(fnNode: SyntaxNode): PhpArityMetadata;
+export {};

package/dist/core/ingestion/languages/php/arity-metadata.js

@@ -0,0 +1,63 @@
+/**
+ * Extract PHP arity metadata from a method-like tree-sitter node —
+ * `method_declaration` or `function_definition`.
+ *
+ * Reuses `phpMethodConfig.extractParameters` so scope-extracted defs
+ * carry the same arity semantics as the legacy parse-worker path:
+ *   - `variadic_parameter` (`...$args`) collapses `parameterCount` to
+ *     `undefined`, which `phpArityCompatibility` then treats as
+ *     "max unknown" — the candidate stays eligible at `argCount >= required`.
+ *   - Defaulted parameters (`= expr`) contribute to `optionalCount`;
+ *     `requiredParameterCount = total − optionalCount − (variadic ? 1 : 0)`.
+ *     The variadic slot itself accepts zero args so it is subtracted from
+ *     the required count — `f(int $a, ...$rest)` requires exactly 1 arg,
+ *     not 2, and `f(...$rest)` requires 0.
+ *   - `property_promotion_parameter` (constructor-promoted) is counted
+ *     the same as `simple_parameter` since both consume an argument slot.
+ *   - `parameterTypes` collects declared type names; a literal `'...'`
+ *     marker is appended for variadic methods so `phpArityCompatibility`
+ *     can detect them without re-reading the AST.
+ */
+import { phpMethodConfig } from '../../method-extractors/configs/php.js';
+export function computePhpArityMetadata(fnNode) {
+    const params = phpMethodConfig.extractParameters?.(fnNode) ?? [];
+    let hasVariadic = false;
+    let optionalCount = 0;
+    const types = [];
+    for (const p of params) {
+        if (p.isVariadic) {
+            hasVariadic = true;
+        }
+        else if (p.isOptional) {
+            optionalCount++;
+        }
+        if (p.type !== null)
+            types.push(p.type);
+    }
+    // PHP variadic marker convention: append the literal '...' string to
+    // `parameterTypes`. This is intentionally DIFFERENT from C#, which uses
+    // the literal 'params' (its source-language keyword). The shared
+    // `narrowOverloadCandidates` pass in `scope-resolution/passes/overload-
+    // narrowing.ts` checks for the C# 'params' marker — that branch is
+    // dead code for PHP because PHP variadic methods set `parameterCount
+    // = undefined` (see line below), which skips the `max !== undefined`
+    // gate that hosts the 'params' check. PHP's actual variadic-aware
+    // arity logic lives in `phpArityCompatibility` (arity.ts) and now
+    // also in `phpEmitUnresolvedReceiverEdges` (scope-resolver.ts), both
+    // of which check `'...'`. Finding 9 of PR #1497 adversarial review.
+    if (hasVariadic)
+        types.push('...');
+    const total = params.length;
+    // Variadic methods accept any arg count ≥ required — leave `parameterCount`
+    // undefined so the registry treats max as unknown.
+    const parameterCount = hasVariadic ? undefined : total;
+    // The variadic slot itself accepts zero args; subtract it from the required
+    // count so PHP's ArgumentCountError-equivalent calls (too few args before
+    // the variadic) are correctly rejected by arity compatibility.
+    const requiredParameterCount = total - optionalCount - (hasVariadic ? 1 : 0);
+    return {
+        parameterCount,
+        requiredParameterCount,
+        parameterTypes: types.length > 0 ? types : undefined,
+    };
+}

package/dist/core/ingestion/languages/php/arity.d.ts

@@ -0,0 +1,25 @@
+/**
+ * PHP arity check, accommodating variadic (`...$args`) and default parameters.
+ *
+ * The `def` metadata synthesized by `arity-metadata.ts`:
+ *   - `parameterCount`         — total formal parameters; `undefined` when
+ *                                the method has a variadic `...$param`.
+ *   - `requiredParameterCount` — min required (excludes defaulted params
+ *                                and the variadic itself).
+ *   - `parameterTypes`         — declared type strings; contains the
+ *                                literal `'...'` when the method is variadic.
+ *
+ * Verdicts:
+ *   - `'compatible'`   — `required <= argCount <= max`, OR the def has
+ *                        variadic (any `argCount >= required`).
+ *   - `'incompatible'` — argCount below required, or above max with no variadic.
+ *   - `'unknown'`      — metadata absent / incomplete; named-args can satisfy
+ *                        any arity so we return unknown when we detect them.
+ *
+ * PHP supports named arguments (PHP 8.0+): `save(force: true)`. Named-arg
+ * call sites cannot be arity-checked statically without parsing arg names,
+ * so we return `'unknown'` when the callsite carries named args (signalled
+ * by a negative `arity` value per the shared Callsite contract).
+ */
+import type { Callsite, SymbolDefinition } from '../../../../_shared/index.js';
+export declare function phpArityCompatibility(def: SymbolDefinition, callsite: Callsite): 'compatible' | 'unknown' | 'incompatible';

package/dist/core/ingestion/languages/php/arity.js

@@ -0,0 +1,40 @@
+/**
+ * PHP arity check, accommodating variadic (`...$args`) and default parameters.
+ *
+ * The `def` metadata synthesized by `arity-metadata.ts`:
+ *   - `parameterCount`         — total formal parameters; `undefined` when
+ *                                the method has a variadic `...$param`.
+ *   - `requiredParameterCount` — min required (excludes defaulted params
+ *                                and the variadic itself).
+ *   - `parameterTypes`         — declared type strings; contains the
+ *                                literal `'...'` when the method is variadic.
+ *
+ * Verdicts:
+ *   - `'compatible'`   — `required <= argCount <= max`, OR the def has
+ *                        variadic (any `argCount >= required`).
+ *   - `'incompatible'` — argCount below required, or above max with no variadic.
+ *   - `'unknown'`      — metadata absent / incomplete; named-args can satisfy
+ *                        any arity so we return unknown when we detect them.
+ *
+ * PHP supports named arguments (PHP 8.0+): `save(force: true)`. Named-arg
+ * call sites cannot be arity-checked statically without parsing arg names,
+ * so we return `'unknown'` when the callsite carries named args (signalled
+ * by a negative `arity` value per the shared Callsite contract).
+ */
+export function phpArityCompatibility(def, callsite) {
+    const max = def.parameterCount;
+    const min = def.requiredParameterCount;
+    if (max === undefined && min === undefined)
+        return 'unknown';
+    const argCount = callsite.arity;
+    // Negative arity signals named-argument call sites — can't narrow statically.
+    if (!Number.isFinite(argCount) || argCount < 0)
+        return 'unknown';
+    const hasVarArgs = def.parameterTypes !== undefined &&
+        def.parameterTypes.some((t) => t === '...' || t.startsWith('...'));
+    if (min !== undefined && argCount < min)
+        return 'incompatible';
+    if (max !== undefined && argCount > max && !hasVarArgs)
+        return 'incompatible';
+    return 'compatible';
+}

package/dist/core/ingestion/languages/php/cache-stats.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Dev-mode counters for the cross-phase scope-captures parse cache
+ * (PHP mirror of `languages/csharp/cache-stats.ts`).
+ *
+ * Gated by `PROF_SCOPE_RESOLUTION=1`. Production builds fold every
+ * increment into dead code via the module-level `PROF` constant, so
+ * the hot path in `captures.ts` stays branch-free.
+ */
+export declare function recordCacheHit(): void;
+export declare function recordCacheMiss(): void;
+export declare function getPhpCaptureCacheStats(): {
+    hits: number;
+    misses: number;
+};
+export declare function resetPhpCaptureCacheStats(): void;

package/dist/core/ingestion/languages/php/cache-stats.js

@@ -0,0 +1,26 @@
+/**
+ * Dev-mode counters for the cross-phase scope-captures parse cache
+ * (PHP mirror of `languages/csharp/cache-stats.ts`).
+ *
+ * Gated by `PROF_SCOPE_RESOLUTION=1`. Production builds fold every
+ * increment into dead code via the module-level `PROF` constant, so
+ * the hot path in `captures.ts` stays branch-free.
+ */
+const PROF = process.env.PROF_SCOPE_RESOLUTION === '1';
+let CACHE_HITS = 0;
+let CACHE_MISSES = 0;
+export function recordCacheHit() {
+    if (PROF)
+        CACHE_HITS++;
+}
+export function recordCacheMiss() {
+    if (PROF)
+        CACHE_MISSES++;
+}
+export function getPhpCaptureCacheStats() {
+    return { hits: CACHE_HITS, misses: CACHE_MISSES };
+}
+export function resetPhpCaptureCacheStats() {
+    CACHE_HITS = 0;
+    CACHE_MISSES = 0;
+}

package/dist/core/ingestion/languages/php/captures.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `emitScopeCaptures` for PHP (RFC #909 Ring 3 LANG-php).
+ *
+ * Drives the PHP scope query against tree-sitter-php and groups raw
+ * matches into `CaptureMatch[]` for the central extractor. Layers two
+ * synthesized streams on top:
+ *
+ *   1. **Decomposed use declarations** — each `namespace_use_declaration`
+ *      is re-emitted with `@import.kind/source/name/alias` markers so
+ *      `interpretPhpImport` can recover the ParsedImport shape without
+ *      re-parsing raw text. Grouped uses fan out to one match per clause.
+ *
+ *   2. **Receiver-binding synthesis** — `$this` and `parent` type-bindings
+ *      are synthesized on every non-static method entry. PHP's grammar
+ *      does not express "implicit receiver of a non-static class method"
+ *      via a clean `.scm` pattern, so we walk up the AST in code.
+ *
+ *   3. **Arity metadata synthesis** — `@declaration.parameter-count` /
+ *      `@declaration.required-parameter-count` / `@declaration.parameter-types`
+ *      are synthesized on function-like declarations so the registry can
+ *      narrow overloads.
+ *
+ *   4. **PHPDoc synthesis** — @param and @return annotations in comment
+ *      nodes preceding method/function declarations are extracted and emitted
+ *      as `@type-binding.parameter` and `@type-binding.return` matches.
+ *
+ *   5. **Foreach loop synthesis** — `foreach ($users as $user)` emits
+ *      a `@type-binding.alias` match binding the loop variable to the
+ *      element type of the iterable (resolved from PHPDoc or scopeEnv).
+ *
+ * Pure given the input source text. No I/O, no globals consulted.
+ */
+import type { CaptureMatch } from '../../../../_shared/index.js';
+export declare function emitPhpScopeCaptures(sourceText: string, _filePath: string, cachedTree?: unknown): readonly CaptureMatch[];