gitnexus 1.6.3-rc.8 → 1.6.3

package/dist/core/ingestion/languages/python/query.js

@@ -0,0 +1,267 @@
+/**
+ * Tree-sitter query for Python scope captures (RFC §5.1).
+ *
+ * Exposes lazy `Parser` and `Query` singletons so callers don't
+ * pay tree-sitter init cost per file.
+ */
+import Parser from 'tree-sitter';
+import Python from 'tree-sitter-python';
+const PYTHON_SCOPE_QUERY = `
+;; Scopes
+(module) @scope.module
+(class_definition) @scope.class
+(function_definition) @scope.function
+
+;; Declarations
+(class_definition
+  name: (identifier) @declaration.name) @declaration.class
+
+(function_definition
+  name: (identifier) @declaration.name) @declaration.function
+
+(assignment
+  left: (identifier) @declaration.name) @declaration.variable
+
+;; Declarations: for-loop target — Python for-statements do NOT introduce
+;; a new scope, so the loop variable binds in the enclosing function/module
+;; scope. We emit it as a Variable declaration so Pass-2 attaches it.
+(for_statement
+  left: (identifier) @declaration.name) @declaration.variable
+
+;; Imports — single anchor per statement; interpretImport decomposes
+(import_statement) @import.statement
+(import_from_statement) @import.statement
+
+;; Type bindings (parameter annotations)
+(typed_parameter
+  (identifier) @type-binding.name
+  type: (type) @type-binding.type) @type-binding.parameter
+
+(typed_default_parameter
+  name: (identifier) @type-binding.name
+  type: (type) @type-binding.type) @type-binding.parameter
+
+;; Type bindings (constructor-inferred: \`u = User(...)\`)
+;; Listed BEFORE the annotation pattern so \`u: User = find()\` — which
+;; matches BOTH patterns — has the annotation (stronger source) win over
+;; the constructor-inferred guess via the scope-extractor's source-
+;; strength tie-break in pass4CollectTypeBindings.
+(assignment
+  left: (identifier) @type-binding.name
+  right: (call
+    function: (identifier) @type-binding.type)) @type-binding.constructor
+
+;; Qualified constructor (\`u = models.User(...)\`). Captures the
+;; attribute node as the type — its \`.text\` is the full dotted path
+;; (\`models.User\`), which \`resolveTypeRef\` resolves via
+;; \`QualifiedNameIndex\` Phase 2.
+(assignment
+  left: (identifier) @type-binding.name
+  right: (call
+    function: (attribute) @type-binding.type)) @type-binding.constructor
+
+;; Walrus operator: \`(u := User(...))\`. Python 3.8+ named expression.
+;; Shares the constructor-inferred shape so the binding lands in the
+;; enclosing function/module scope's typeBindings the same way a plain
+;; assignment would.
+(named_expression
+  name: (identifier) @type-binding.name
+  value: (call
+    function: (identifier) @type-binding.type)) @type-binding.constructor
+
+(named_expression
+  name: (identifier) @type-binding.name
+  value: (call
+    function: (attribute) @type-binding.type)) @type-binding.constructor
+
+;; Match-case as-pattern: \`case User() as u:\` → \`u: User\`. The
+;; class_pattern's dotted_name carries the type; the outer as_pattern's
+;; second child is the binding name.
+(as_pattern
+  (case_pattern
+    (class_pattern
+      (dotted_name) @type-binding.type))
+  (identifier) @type-binding.name) @type-binding.constructor
+
+;; Assignment chain: \`alias = user\` — the new name inherits the
+;; RHS-identifier's type. The pattern emits a TypeRef whose rawName is
+;; the RHS identifier's text; the scope-extractor's post-pass follows
+;; the chain so \`alias\` ends up pointing at whatever type \`user\` has.
+(assignment
+  left: (identifier) @type-binding.name
+  right: (identifier) @type-binding.type) @type-binding.alias
+
+;; For-loop iterable of an already-typed variable:
+;;   def f(users: list[User]):
+;;       for u in users:     # u: users (chained via post-pass)
+;;           u.save()
+;; The chain post-pass resolves \`users\` → its own type \`User\` via
+;; the generic-arg stripping in \`interpret.ts\`.
+(for_statement
+  left: (identifier) @type-binding.name
+  right: (identifier) @type-binding.type) @type-binding.alias
+
+;; For-loop iterable of a free-call result:
+;;   def get_users() -> list[User]: ...
+;;   for u in get_users():   # u: get_users → User via chain follow
+;;       u.save()
+;; Captures the call's function identifier as the rawName. With
+;; \`propagateImportedReturnTypes\`, this works cross-file too.
+(for_statement
+  left: (identifier) @type-binding.name
+  right: (call
+    function: (identifier) @type-binding.type)) @type-binding.alias
+
+;; for (i, u) in enumerate(X) — paren-tuple, bind last element to X's
+;; element type. \`enumerate(X)\` yields (int, X-element); the second
+;; pattern var takes X (which the chain-follow then unwraps to its
+;; element type via generic-strip in interpret.ts).
+(for_statement
+  left: (tuple_pattern
+    (identifier)
+    (identifier) @type-binding.name)
+  right: (call
+    function: (identifier) @_enum
+    arguments: (argument_list
+      (identifier) @type-binding.type))
+  (#eq? @_enum "enumerate")) @type-binding.alias
+
+;; for i, u in enumerate(X) — pattern_list (no parens) variant.
+(for_statement
+  left: (pattern_list
+    (identifier)
+    (identifier) @type-binding.name)
+  right: (call
+    function: (identifier) @_enum
+    arguments: (argument_list
+      (identifier) @type-binding.type))
+  (#eq? @_enum "enumerate")) @type-binding.alias
+
+;; for k, v in d.items() — bind v to d. The chain-follow unwraps d's
+;; dict[K, V] annotation to V via the dict-aware stripGeneric in
+;; interpret.ts. Covers both pattern_list and tuple_pattern shapes.
+(for_statement
+  left: (pattern_list
+    (identifier)
+    (identifier) @type-binding.name)
+  right: (call
+    function: (attribute
+      object: (identifier) @type-binding.type
+      attribute: (identifier) @_items))
+  (#eq? @_items "items")) @type-binding.alias
+
+(for_statement
+  left: (tuple_pattern
+    (identifier)
+    (identifier) @type-binding.name)
+  right: (call
+    function: (attribute
+      object: (identifier) @type-binding.type
+      attribute: (identifier) @_items))
+  (#eq? @_items "items")) @type-binding.alias
+
+;; for i, (k, v) in enumerate(d.items()) — nested tuple destructuring.
+;; Bind v (last id of the nested tuple) to d (the dict).
+(for_statement
+  left: (pattern_list
+    (identifier)
+    (tuple_pattern
+      (identifier)
+      (identifier) @type-binding.name))
+  right: (call
+    function: (identifier) @_enum
+    arguments: (argument_list
+      (call
+        function: (attribute
+          object: (identifier) @type-binding.type
+          attribute: (identifier) @_items))))
+  (#eq? @_enum "enumerate")
+  (#eq? @_items "items")) @type-binding.alias
+
+;; for i, k, v in enumerate(d.items()) — 3-var flat destructuring of
+;; the (i, (k,v)) tuple emitted by enumerate over items(). Bind v
+;; (last id) to d.
+(for_statement
+  left: (pattern_list
+    (identifier)
+    (identifier)
+    (identifier) @type-binding.name)
+  right: (call
+    function: (identifier) @_enum
+    arguments: (argument_list
+      (call
+        function: (attribute
+          object: (identifier) @type-binding.type
+          attribute: (identifier) @_items))))
+  (#eq? @_enum "enumerate")
+  (#eq? @_items "items")) @type-binding.alias
+
+;; for u in self.X — heuristic: bind u to X (the attribute name).
+;; The chain-follow then resolves X via the enclosing method's
+;; parameter typeBinding, supporting fixtures that reference
+;; \`self.X\` as a stand-in for a parameter X (matches legacy DAG
+;; behavior).
+(for_statement
+  left: (identifier) @type-binding.name
+  right: (attribute
+    object: (identifier) @_self
+    attribute: (identifier) @type-binding.type)
+  (#eq? @_self "self")) @type-binding.alias
+
+;; for v in d.values() — bind v to d (dict-strip yields value type).
+(for_statement
+  left: (identifier) @type-binding.name
+  right: (call
+    function: (attribute
+      object: (identifier) @type-binding.type
+      attribute: (identifier) @_values))
+  (#eq? @_values "values")) @type-binding.alias
+
+;; Type bindings (variable annotations: \`u: User\` / \`u: User = x\`)
+(assignment
+  left: (identifier) @type-binding.name
+  type: (type) @type-binding.type) @type-binding.annotation
+
+;; Return-type annotation: \`def get_user() -> User:\` binds the
+;; FUNCTION'S NAME to its return type in the enclosing scope. Combined
+;; with the constructor-inferred + chain-follow path, \`u = get_user()\`
+;; then resolves \`u: User\` cross-call. The Python provider hoists the
+;; binding via \`pythonBindingScopeFor\` to the function's parent scope
+;; so callers in module/class scope see it.
+(function_definition
+  name: (identifier) @type-binding.name
+  return_type: (type) @type-binding.type) @type-binding.return
+
+;; References — calls
+(call
+  function: (identifier) @reference.name) @reference.call.free
+
+(call
+  function: (attribute
+    object: (_) @reference.receiver
+    attribute: (identifier) @reference.name)) @reference.call.member
+
+;; References — attribute writes: \`obj.name = "x"\` emits a write
+;; ACCESSES edge from the enclosing function to the field on obj's
+;; class. The receiver-bound emit pass resolves obj → its class and
+;; \`name\` → the field def via the existing typeref-receiver path.
+(assignment
+  left: (attribute
+    object: (_) @reference.receiver
+    attribute: (identifier) @reference.name)) @reference.write.member
+`;
+let _parser = null;
+let _query = null;
+export function getPythonParser() {
+    if (_parser === null) {
+        _parser = new Parser();
+        _parser.setLanguage(Python);
+    }
+    return _parser;
+}
+export function getPythonScopeQuery() {
+    if (_query === null) {
+        _query = new Parser.Query(Python, PYTHON_SCOPE_QUERY);
+    }
+    return _query;
+}

package/dist/core/ingestion/languages/python/receiver-binding.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Synthesize `@type-binding.self` / `@type-binding.cls` captures for
+ * methods.
+ *
+ * Tree-sitter can't easily express "the first parameter of a function
+ * defined directly inside a class body" via a single static query.
+ * Doing this in code keeps the embedded scope query declarative and
+ * lets us encode the `@classmethod` / `@staticmethod` decorator
+ * awareness that Python's runtime depends on.
+ */
+import type { CaptureMatch } from '../../../../_shared/index.js';
+import { type SyntaxNode } from '../../utils/ast-helpers.js';
+/**
+ * Build a `@type-binding.self` (instance method) or `@type-binding.cls`
+ * (`@classmethod`) match for `fnNode`, or `null` if `fnNode` is not a
+ * method, is `@staticmethod`, or has no parameters.
+ *
+ * The caller is responsible for guaranteeing `fnNode.type ===
+ * 'function_definition'`.
+ */
+export declare function synthesizeReceiverTypeBinding(fnNode: SyntaxNode): CaptureMatch | null;

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

@@ -0,0 +1,116 @@
+/**
+ * Synthesize `@type-binding.self` / `@type-binding.cls` captures for
+ * methods.
+ *
+ * Tree-sitter can't easily express "the first parameter of a function
+ * defined directly inside a class body" via a single static query.
+ * Doing this in code keeps the embedded scope query declarative and
+ * lets us encode the `@classmethod` / `@staticmethod` decorator
+ * awareness that Python's runtime depends on.
+ */
+import { nodeToCapture, syntheticCapture } from '../../utils/ast-helpers.js';
+/** Walk up to the enclosing `class_definition`, ignoring the immediate
+ *  `decorated_definition` wrapper. Returns `null` when the function is
+ *  free, lambda-bodied, or nested inside another function. */
+function findEnclosingClassDefinition(node) {
+    let cur = node.parent;
+    while (cur !== null) {
+        if (cur.type === 'class_definition')
+            return cur;
+        if (cur.type === 'function_definition')
+            return null;
+        cur = cur.parent;
+    }
+    return null;
+}
+function classDefinitionName(classNode) {
+    return classNode.childForFieldName('name')?.text ?? null;
+}
+/** Does the function carry a `@<decoratorName>` decorator? Matches both
+ *  bare `@classmethod` and module-qualified `@functools.classmethod`. */
+function hasDecorator(fnNode, decoratorName) {
+    const parent = fnNode.parent;
+    if (parent === null || parent.type !== 'decorated_definition')
+        return false;
+    for (let i = 0; i < parent.namedChildCount; i++) {
+        const child = parent.namedChild(i);
+        if (child === null || child.type !== 'decorator')
+            continue;
+        const text = child.text.replace(/^@/, '').split('(')[0].trim();
+        const tail = text.split('.').pop();
+        if (tail === decoratorName)
+            return true;
+    }
+    return false;
+}
+function firstNamedParameter(parameters) {
+    for (let i = 0; i < parameters.namedChildCount; i++) {
+        const child = parameters.namedChild(i);
+        if (child === null)
+            continue;
+        // Skip `*` / `/` markers.
+        if (child.type === 'positional_separator' || child.type === 'keyword_separator')
+            continue;
+        return child;
+    }
+    return null;
+}
+function firstParameterName(param) {
+    if (param.type === 'identifier')
+        return param.text;
+    // typed_parameter / default_parameter / typed_default_parameter:
+    // first child holds the identifier / pattern.
+    const ident = param.childForFieldName('name') ?? findIdentifierChild(param);
+    return ident?.text ?? null;
+}
+function findIdentifierChild(node) {
+    for (let i = 0; i < node.namedChildCount; i++) {
+        const child = node.namedChild(i);
+        if (child !== null && child.type === 'identifier')
+            return child;
+    }
+    return null;
+}
+/**
+ * Build a `@type-binding.self` (instance method) or `@type-binding.cls`
+ * (`@classmethod`) match for `fnNode`, or `null` if `fnNode` is not a
+ * method, is `@staticmethod`, or has no parameters.
+ *
+ * The caller is responsible for guaranteeing `fnNode.type ===
+ * 'function_definition'`.
+ */
+export function synthesizeReceiverTypeBinding(fnNode) {
+    const enclosingClass = findEnclosingClassDefinition(fnNode);
+    if (enclosingClass === null)
+        return null;
+    // Skip @staticmethod-decorated methods (no implicit receiver).
+    if (hasDecorator(fnNode, 'staticmethod'))
+        return null;
+    const isClassmethod = hasDecorator(fnNode, 'classmethod');
+    const params = fnNode.childForFieldName('parameters');
+    if (params === null)
+        return null;
+    const first = firstNamedParameter(params);
+    if (first === null)
+        return null;
+    const className = classDefinitionName(enclosingClass);
+    if (className === null)
+        return null;
+    const firstName = firstParameterName(first);
+    if (firstName === null)
+        return null;
+    // Receiver convention: instance methods get `self`, classmethods get `cls`.
+    // We trust the AST literal name (Python convention is strict in practice).
+    if (isClassmethod) {
+        return {
+            '@type-binding.cls': nodeToCapture('@type-binding.cls', first),
+            '@type-binding.name': syntheticCapture('@type-binding.name', first, firstName),
+            '@type-binding.type': syntheticCapture('@type-binding.type', first, className),
+        };
+    }
+    return {
+        '@type-binding.self': nodeToCapture('@type-binding.self', first),
+        '@type-binding.name': syntheticCapture('@type-binding.name', first, firstName),
+        '@type-binding.type': syntheticCapture('@type-binding.type', first, className),
+    };
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Python `ScopeResolver` registered in `SCOPE_RESOLVERS` and consumed
+ * by the generic `runScopeResolution` orchestrator.
+ *
+ * The provider is a thin wiring object — Python's specific bits
+ * (super recognizer, LEGB merge precedence, Python's relative-import
+ * resolver, the simplified MRO walk) plug into `runScopeResolution`.
+ *
+ * Migration reference: when bringing up the next language
+ * (TypeScript / Java / Kotlin / Ruby), copy this file's structure —
+ * implement the 6 required `ScopeResolver` fields, optionally toggle
+ * the 2 booleans, and register in `scope-resolution/pipeline/registry.ts`.
+ */
+import type { ScopeResolver } from '../../scope-resolution/contract/scope-resolver.js';
+declare const pythonScopeResolver: ScopeResolver;
+export { pythonScopeResolver };

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

@@ -0,0 +1,53 @@
+/**
+ * Python `ScopeResolver` registered in `SCOPE_RESOLVERS` and consumed
+ * by the generic `runScopeResolution` orchestrator.
+ *
+ * The provider is a thin wiring object — Python's specific bits
+ * (super recognizer, LEGB merge precedence, Python's relative-import
+ * resolver, the simplified MRO walk) plug into `runScopeResolution`.
+ *
+ * Migration reference: when bringing up the next language
+ * (TypeScript / Java / Kotlin / Ruby), copy this file's structure —
+ * implement the 6 required `ScopeResolver` fields, optionally toggle
+ * the 2 booleans, and register in `scope-resolution/pipeline/registry.ts`.
+ */
+import { SupportedLanguages } from '../../../../_shared/index.js';
+import { buildMro, defaultLinearize } from '../../scope-resolution/passes/mro.js';
+import { populateClassOwnedMembers } from '../../scope-resolution/scope/walkers.js';
+import { pythonProvider } from '../python.js';
+import { pythonArityCompatibility, pythonMergeBindings, resolvePythonImportTarget, } from './index.js';
+const pythonScopeResolver = {
+    language: SupportedLanguages.Python,
+    languageProvider: pythonProvider,
+    importEdgeReason: 'python-scope: import',
+    resolveImportTarget: (targetRaw, fromFile, allFilePaths) => {
+        // Copy the orchestrator's `ReadonlySet` into a `Set` because the
+        // legacy Python resolver chain (`resolvePythonImportInternal` →
+        // `resolveAbsoluteFromFiles` / `hasRepoCandidate`) is typed to
+        // receive a mutable `Set<string>`. The copy is O(N) but called
+        // once per import — trivial compared to the parser work.
+        const ws = { fromFile, allFilePaths: new Set(allFilePaths) };
+        // `WorkspaceIndex` is an opaque `unknown` placeholder in the
+        // shared contract, so `ws` passes structurally without a cast.
+        return resolvePythonImportTarget({ kind: 'named', localName: '_', importedName: '_', targetRaw }, ws);
+    },
+    // Python LEGB precedence: local > import/namespace/reexport > wildcard.
+    // The per-scope id is unused by pythonMergeBindings (tier ordering
+    // is computed purely from BindingRef.origin), so we don't need to
+    // synthesize a Scope.
+    mergeBindings: (existing, incoming) => [...pythonMergeBindings([...existing, ...incoming])],
+    // Adapter: pythonArityCompatibility predates RegistryProviders and
+    // uses (def, callsite). ScopeResolver contract is (callsite, def).
+    // Wrapper kept to honor both contracts without altering the legacy
+    // shape that LanguageProvider.arityCompatibility consumes.
+    arityCompatibility: (callsite, def) => pythonArityCompatibility(def, callsite),
+    buildMro: (graph, parsedFiles, nodeLookup) => buildMro(graph, parsedFiles, nodeLookup, defaultLinearize),
+    populateOwners: (parsed) => populateClassOwnedMembers(parsed),
+    isSuperReceiver: (text) => /^super\s*\(/.test(text),
+    // Python is dynamically typed — field-fallback heuristic on, return-
+    // type propagation across imports on. Both default to true; listed
+    // explicitly here for documentation.
+    fieldFallbackOnMethodLookup: true,
+    propagatesReturnTypesAcrossImports: true,
+};
+export { pythonScopeResolver };

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

@@ -0,0 +1,23 @@
+/**
+ * Trivial / no-op-ish hooks for the Python provider. Kept together
+ * because each is a few lines and they share a common theme: they exist
+ * to make the provider's choice explicit (rather than relying on
+ * "absence == default") so reviewers don't have to re-derive the
+ * analysis.
+ */
+import type { CaptureMatch, ParsedImport, Scope, ScopeId, ScopeTree, TypeRef } from '../../../../_shared/index.js';
+/** Python has no block scope, so the central extractor's "innermost
+ *  enclosing scope" default is already correct: `for x in …` creates
+ *  `x` in the enclosing function/module scope (because we never emit a
+ *  `@scope.block` for the for-loop body), comprehension variables stay
+ *  in their expression context, etc. Returns `null` to delegate. */
+export declare function pythonBindingScopeFor(_decl: CaptureMatch, _innermost: Scope, _tree: ScopeTree): ScopeId | null;
+/** Function-local `from x import Y` should attach the binding to the
+ *  function scope, not the module. Class-body imports (rare but legal —
+ *  `class A: import x` makes `x` a class attribute) attach to the class.
+ *  Module-level imports delegate to the central default. */
+export declare function pythonImportOwningScope(_imp: ParsedImport, innermost: Scope, _tree: ScopeTree): ScopeId | null;
+/** Look up `self` or `cls` in the function scope's type bindings.
+ *  Returns `null` for free functions (no `self`/`cls`) and for
+ *  non-Function scopes. */
+export declare function pythonReceiverBinding(functionScope: Scope): TypeRef | null;

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

@@ -0,0 +1,35 @@
+/**
+ * Trivial / no-op-ish hooks for the Python provider. Kept together
+ * because each is a few lines and they share a common theme: they exist
+ * to make the provider's choice explicit (rather than relying on
+ * "absence == default") so reviewers don't have to re-derive the
+ * analysis.
+ */
+// ─── bindingScopeFor ──────────────────────────────────────────────────────
+/** Python has no block scope, so the central extractor's "innermost
+ *  enclosing scope" default is already correct: `for x in …` creates
+ *  `x` in the enclosing function/module scope (because we never emit a
+ *  `@scope.block` for the for-loop body), comprehension variables stay
+ *  in their expression context, etc. Returns `null` to delegate. */
+export function pythonBindingScopeFor(_decl, _innermost, _tree) {
+    return null;
+}
+// ─── importOwningScope ────────────────────────────────────────────────────
+/** Function-local `from x import Y` should attach the binding to the
+ *  function scope, not the module. Class-body imports (rare but legal —
+ *  `class A: import x` makes `x` a class attribute) attach to the class.
+ *  Module-level imports delegate to the central default. */
+export function pythonImportOwningScope(_imp, innermost, _tree) {
+    if (innermost.kind === 'Function' || innermost.kind === 'Class')
+        return innermost.id;
+    return null;
+}
+// ─── receiverBinding ──────────────────────────────────────────────────────
+/** Look up `self` or `cls` in the function scope's type bindings.
+ *  Returns `null` for free functions (no `self`/`cls`) and for
+ *  non-Function scopes. */
+export function pythonReceiverBinding(functionScope) {
+    if (functionScope.kind !== 'Function')
+        return null;
+    return functionScope.typeBindings.get('self') ?? functionScope.typeBindings.get('cls') ?? null;
+}

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

@@ -28,6 +28,7 @@ import { pythonVariableConfig } from '../variable-extractors/configs/python.js';
 import { createCallExtractor } from '../call-extractors/generic.js';
 import { pythonCallConfig } from '../call-extractors/configs/python.js';
 import { createHeritageExtractor } from '../heritage-extractors/generic.js';
+import { emitPythonScopeCaptures, interpretPythonImport, interpretPythonTypeBinding, pythonArityCompatibility, pythonBindingScopeFor, pythonImportOwningScope, pythonMergeBindings, pythonReceiverBinding, resolvePythonImportTarget, } from './python/index.js';
 const BUILT_INS = new Set([
     'print',
     'len',
@@ -74,4 +75,17 @@ export const pythonProvider = defineLanguage({
     classExtractor: createClassExtractor(pythonClassConfig),
     heritageExtractor: createHeritageExtractor(SupportedLanguages.Python),
     builtInNames: BUILT_INS,
+    // ── RFC #909 Ring 3: scope-based resolution hooks (RFC §5) ──────────
+    // Python is the first migration. See ./python/index.ts for the
+    // full per-hook rationale and the canonical capture vocabulary in
+    // ./python/query.ts (PYTHON_SCOPE_QUERY constant).
+    emitScopeCaptures: emitPythonScopeCaptures,
+    interpretImport: interpretPythonImport,
+    interpretTypeBinding: interpretPythonTypeBinding,
+    bindingScopeFor: pythonBindingScopeFor,
+    importOwningScope: pythonImportOwningScope,
+    mergeBindings: (_scope, bindings) => pythonMergeBindings(bindings),
+    receiverBinding: pythonReceiverBinding,
+    arityCompatibility: pythonArityCompatibility,
+    resolveImportTarget: resolvePythonImportTarget,
 });

package/dist/core/ingestion/model/method-registry.d.ts

@@ -37,6 +37,15 @@ export interface MethodRegistry {
      * allocation reachable from two indexes.
      */
     lookupMethodByName(name: string): readonly SymbolDefinition[];
+    /**
+     * Return every overload registered under `(ownerNodeId, methodName)`,
+     * unfiltered by arity or return type. This is the raw owner-scoped
+     * view — callers that need arity narrowing or unambiguous single-
+     * result semantics should use `lookupMethodByOwner` instead.
+     *
+     * Returns `[]` on miss so callers can iterate without null checks.
+     */
+    lookupAllByOwner(ownerNodeId: string, methodName: string): readonly SymbolDefinition[];
     /**
      * True iff at least one registered def has `type === 'Function'` — i.e.,
      * a Python/Rust/Kotlin class method emitted by the worker as

package/dist/core/ingestion/model/method-registry.js

@@ -88,6 +88,9 @@ export const createMethodRegistry = () => {
     const lookupMethodByName = (name) => {
         return methodsByName.get(name) ?? EMPTY;
     };
+    const lookupAllByOwner = (ownerNodeId, methodName) => {
+        return methodByOwner.get(`${ownerNodeId}\0${methodName}`) ?? EMPTY;
+    };
     const register = (ownerNodeId, methodName, def) => {
         const key = `${ownerNodeId}\0${methodName}`;
         const existing = methodByOwner.get(key);
@@ -121,6 +124,7 @@ export const createMethodRegistry = () => {
     return {
         lookupMethodByOwner,
         lookupMethodByName,
+        lookupAllByOwner,
         register,
         clear,
         get hasFunctionMethods() {

package/dist/core/ingestion/model/scope-resolution-indexes.d.ts

@@ -0,0 +1,59 @@
+/**
+ * `ScopeResolutionIndexes` — the bundle of materialized indexes produced
+ * by the finalize-orchestrator (RFC #909 Ring 2 PKG #921) and attached
+ * to `MutableSemanticModel`.
+ *
+ * Produced by `finalizeScopeModel(parsedFiles, hooks)` in
+ * `finalize-orchestrator.ts`. Consumed by the resolution phase (future
+ * tickets) where `Registry.lookup` / `resolveTypeRef` query this bundle
+ * to answer call-resolution questions without re-walking any AST.
+ *
+ * ## Lifecycle
+ *
+ *   1. Pipeline collects `ParsedFile[]` from the parsing-processor (#920).
+ *   2. Pipeline invokes `finalizeScopeModel(parsedFiles, hooks)` →
+ *      returns a `ScopeResolutionIndexes` (this interface).
+ *   3. Pipeline calls `model.attachScopeIndexes(indexes)` to stamp them
+ *      onto the `MutableSemanticModel`. This is a **one-shot write**;
+ *      subsequent calls throw. After attachment, the indexes are frozen
+ *      at the type level (everything is `readonly`) and at runtime via
+ *      `Object.freeze` on the bundle.
+ *   4. Resolution callers hold a `SemanticModel` reference and read
+ *      `model.scopes` to query.
+ *
+ * ## Content
+ *
+ *   - `scopeTree` / `moduleScopes` / `defs` / `qualifiedNames` — the
+ *     four Ring 2 SHARED indexes built over per-file artifacts.
+ *   - `methodDispatch` — MRO + implements materialized view (#914).
+ *   - `imports` — finalized `ImportEdge[]` per module scope (`parsedImports`
+ *     resolved through cross-file link + wildcard expansion).
+ *   - `bindings` — merged bindings per module scope (local + import +
+ *     wildcard + re-export), with the provider's precedence applied.
+ *   - `referenceSites` — union of every file's pre-resolution usage
+ *     facts. Consumed by the resolution phase (future) to emit
+ *     `Reference` records into `ReferenceIndex`.
+ *   - `stats` — coarse-grained counts from the shared finalize algorithm
+ *     (total files/edges, linked vs unresolved, SCC topology).
+ *
+ * `ReferenceIndex` is deliberately NOT here — it is populated in a later
+ * phase (RFC §3.2 Phase 4 / Ring 2 PKG #925) and owned separately.
+ */
+import type { BindingRef, DefIndex, FinalizedScc, FinalizeStats, ImportEdge, MethodDispatchIndex, ModuleScopeIndex, QualifiedNameIndex, ReferenceSite, ScopeId, ScopeTree } from '../../../_shared/index.js';
+export interface ScopeResolutionIndexes {
+    readonly scopeTree: ScopeTree;
+    readonly defs: DefIndex;
+    readonly qualifiedNames: QualifiedNameIndex;
+    readonly moduleScopes: ModuleScopeIndex;
+    readonly methodDispatch: MethodDispatchIndex;
+    /** Finalized `ImportEdge[]` per module scope. */
+    readonly imports: ReadonlyMap<ScopeId, readonly ImportEdge[]>;
+    /** Merged bindings (local + imports + wildcards) per module scope. */
+    readonly bindings: ReadonlyMap<ScopeId, ReadonlyMap<string, readonly BindingRef[]>>;
+    /** Pre-resolution usage facts; consumed by the resolution phase. */
+    readonly referenceSites: readonly ReferenceSite[];
+    /** SCC condensation of the file-level import graph — callers that want
+     *  parallel per-SCC processing in the resolution phase read this. */
+    readonly sccs: readonly FinalizedScc[];
+    readonly stats: FinalizeStats;
+}