gitnexus 1.6.13-rc.45 → 1.6.13-rc.47

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

@@ -5,12 +5,13 @@
  *
  * Mirrors the legacy `buildMethodProps` conversion so scope-extracted
  * defs carry the same arity semantics as the parse-worker path:
- *   - `self` / `cls` are stripped (consumed by `extractPythonParameters`).
+ *   - A bound method's first positional receiver is stripped by class and
+ *     decorator context, independent of spelling; static/free functions keep it.
  *   - Defaulted params contribute to `optionalCount`, flipping
  *     `requiredParameterCount = total − optionalCount`.
- *   - Variadic (`*args` / `**kwargs`) collapses `parameterCount` to
- *     `undefined`, which `pythonArityCompatibility` then treats as
- *     `'unknown'` — keeping the candidate in the registry's lookup set.
+ *   - Variadic (`*args` / `**kwargs`) leaves both count-only bounds unknown:
+ *     parameter kinds are not retained, so a required keyword-only argument
+ *     cannot safely be treated as a positional minimum.
  *   - `parameterTypes` is populated only with real type text, matching
  *     legacy behavior.
  */

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

@@ -5,12 +5,13 @@
  *
  * Mirrors the legacy `buildMethodProps` conversion so scope-extracted
  * defs carry the same arity semantics as the parse-worker path:
- *   - `self` / `cls` are stripped (consumed by `extractPythonParameters`).
+ *   - A bound method's first positional receiver is stripped by class and
+ *     decorator context, independent of spelling; static/free functions keep it.
  *   - Defaulted params contribute to `optionalCount`, flipping
  *     `requiredParameterCount = total − optionalCount`.
- *   - Variadic (`*args` / `**kwargs`) collapses `parameterCount` to
- *     `undefined`, which `pythonArityCompatibility` then treats as
- *     `'unknown'` — keeping the candidate in the registry's lookup set.
+ *   - Variadic (`*args` / `**kwargs`) leaves both count-only bounds unknown:
+ *     parameter kinds are not retained, so a required keyword-only argument
+ *     cannot safely be treated as a positional minimum.
  *   - `parameterTypes` is populated only with real type text, matching
  *     legacy behavior.
  */

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

@@ -27,6 +27,7 @@ import { parseSourceSafe } from '../../../tree-sitter/safe-parse.js';
 import { pythonFunctionDefinitionLabel } from './simple-hooks.js';
 import { synthesizeCallableFlowCaptures } from '../../utils/callable-flow-captures.js';
 import { synthesizeReceiverChainCapture } from '../../utils/receiver-chain-captures.js';
+import { beginPythonSubtypeDispatchCapture, recordPythonSimplePositionalCall, recordPythonSubtypeMethodShape, } from './subtype-dispatch.js';
 const PYTHON_CALLABLE_CAPTURE_OPTIONS = {
     functionNodeTypes: new Set(['function_definition', 'lambda']),
     callNodeTypes: new Set(['call']),
@@ -58,6 +59,7 @@ const PYTHON_CALLABLE_CAPTURE_OPTIONS = {
     },
 };
 export function emitPythonScopeCaptures(sourceText, filePath, cachedTree, sourceMeta) {
+    beginPythonSubtypeDispatchCapture(filePath);
     let parseText = sourceText;
     let tree = cachedTree;
     let notebookSegments;
@@ -69,6 +71,9 @@ export function emitPythonScopeCaptures(sourceText, filePath, cachedTree, source
         tree = resolved.tree;
         notebookSegments = resolved.notebookSegments;
     }
+    const subtypeLineMapper = notebookSegments === undefined
+        ? undefined
+        : (line) => mapExtractLine(line - 1, notebookSegments) + 1;
     // Skip the parse when the caller (the scope-resolution orchestrator's
     // `treeCache`) already produced a Tree for this source — empty under
     // worker-pool runs, so cache miss = re-parse. The cachedTree parameter
@@ -116,6 +121,7 @@ export function emitPythonScopeCaptures(sourceText, filePath, cachedTree, source
         }
         if (Object.keys(grouped).length === 0)
             continue;
+        recordPythonSubtypeCallShape(grouped, nodeMap, filePath, subtypeLineMapper);
         if (grouped['@import.statement'] !== undefined) {
             // `@import.statement` is captured directly ON the `import_statement` /
             // `import_from_statement` node (query: `(import_statement) @import.statement`
@@ -183,6 +189,7 @@ export function emitPythonScopeCaptures(sourceText, filePath, cachedTree, source
                 if (pythonFunctionDefinitionLabel(fnNode, 'Function') === 'Method') {
                     delete grouped['@declaration.function'];
                     grouped['@declaration.method'] = { ...anchorCap, name: '@declaration.method' };
+                    recordPythonSubtypeMethodShape(filePath, fnNode, subtypeLineMapper);
                 }
                 const arity = computePythonArityMetadata(fnNode);
                 if (arity.parameterCount !== undefined) {
@@ -257,6 +264,31 @@ function remapCaptureMatch(match, segments) {
     }
     return next;
 }
+/**
+ * Record fixed positional argument counts only for Python's conservative
+ * missing-member subtype fallback. Ordinary reference arity stays unchanged:
+ * count-only metadata cannot model Python keyword binding or definition order.
+ */
+function recordPythonSubtypeCallShape(grouped, nodeMap, filePath, mapLine) {
+    const callTag = ['@reference.call.free', '@reference.call.member'].find((tag) => grouped[tag] !== undefined);
+    if (callTag === undefined)
+        return;
+    // Decorator references use the same call tags but are anchored on a
+    // `decorator`, not a `call`, so they intentionally retain their old shape.
+    const callNode = nodeMap[callTag];
+    if (callNode === undefined || callNode.type !== 'call')
+        return;
+    const argumentList = callNode.childForFieldName('arguments');
+    if (argumentList === null || argumentList.type !== 'argument_list')
+        return;
+    const args = argumentList.namedChildren.filter((child) => child !== null && child.type !== 'comment');
+    if (args.some((arg) => arg.type === 'list_splat' ||
+        arg.type === 'dictionary_splat' ||
+        arg.type === 'keyword_argument')) {
+        return;
+    }
+    recordPythonSimplePositionalCall(filePath, callNode, args.length, mapLine);
+}
 /**
  * Synthesize `@reference.inherits` captures from Python class superclass
  * lists so the registry-primary scope-resolution path emits EXTENDS edges

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

@@ -3,13 +3,27 @@
  * 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.
+ * defined in a class suite, including conditional suite branches" 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';
+export interface PythonBoundReceiver {
+    readonly kind: 'instance' | 'class';
+    readonly parameter: SyntaxNode;
+    readonly name: string;
+    readonly className: string;
+}
+/**
+ * Classify the parameter that Python's descriptor protocol binds implicitly.
+ * Class-suite control flow does not change descriptor ownership, while an
+ * intervening function does. Splat and keyword-only parameters cannot name
+ * the injected receiver directly and therefore fail closed.
+ */
+export declare function classifyPythonBoundReceiver(fnNode: SyntaxNode): PythonBoundReceiver | null;
 /**
  * Build a `@type-binding.self` (instance method) or `@type-binding.cls`
  * (`@classmethod`) match for `fnNode`, or `null` if `fnNode` is not a

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

@@ -3,7 +3,8 @@
  * 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.
+ * defined in a class suite, including conditional suite branches" 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.
@@ -43,75 +44,120 @@ function hasDecorator(fnNode, decoratorName) {
     }
     return false;
 }
-function firstNamedParameter(parameters) {
+function firstBoundReceiverParameter(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')
+        if (child.type === 'comment')
             continue;
-        return child;
+        // A positional-only separator follows at least one real positional
+        // parameter, so encountering it before a candidate is malformed input.
+        // A keyword-only separator, *args, or **kwargs means there is no variable
+        // that directly receives Python's descriptor-injected instance.
+        if (child.type === 'positional_separator' ||
+            child.type === 'keyword_separator' ||
+            child.type === 'list_splat_pattern' ||
+            child.type === 'dictionary_splat_pattern') {
+            return null;
+        }
+        return firstParameterName(child) === null ? null : 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;
+    // typed_parameter / default_parameter / typed_default_parameter must name a
+    // real positional variable. In particular, do not look through a typed
+    // list_splat_pattern or dictionary_splat_pattern for its nested identifier.
+    const named = param.childForFieldName('name') ?? param.firstNamedChild;
+    return named?.type === 'identifier' ? named.text : 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'`.
+ * Classify the parameter that Python's descriptor protocol binds implicitly.
+ * Class-suite control flow does not change descriptor ownership, while an
+ * intervening function does. Splat and keyword-only parameters cannot name
+ * the injected receiver directly and therefore fail closed.
  */
-export function synthesizeReceiverTypeBinding(fnNode) {
+export function classifyPythonBoundReceiver(fnNode) {
     const enclosingClass = findEnclosingClassDefinition(fnNode);
-    if (enclosingClass === null)
+    if (enclosingClass === null || hasDecorator(fnNode, 'staticmethod'))
         return null;
-    // Skip @staticmethod-decorated methods (no implicit receiver).
-    if (hasDecorator(fnNode, 'staticmethod'))
+    const functionName = fnNode.childForFieldName('name')?.text;
+    // Python applies these descriptor kinds implicitly even without decorators.
+    // __new__ is static-like (its class argument is explicit), while
+    // __init_subclass__ and __class_getitem__ receive the class implicitly.
+    if (functionName === '__new__')
         return null;
-    const isClassmethod = hasDecorator(fnNode, 'classmethod');
     const params = fnNode.childForFieldName('parameters');
     if (params === null)
         return null;
-    const first = firstNamedParameter(params);
-    if (first === null)
+    const parameter = firstBoundReceiverParameter(params);
+    if (parameter === null)
+        return null;
+    const name = firstParameterName(parameter);
+    const className = classDefinitionName(enclosingClass);
+    if (name === null || className === null)
+        return null;
+    return {
+        kind: hasDecorator(fnNode, 'classmethod') ||
+            functionName === '__init_subclass__' ||
+            functionName === '__class_getitem__'
+            ? 'class'
+            : 'instance',
+        parameter,
+        name,
+        className,
+    };
+}
+/**
+ * `__new__` is static-like for method dispatch, but Python supplies its class
+ * argument during construction rather than through descriptor binding. Keep
+ * that explicit parameter in arity metadata while still typing its local name.
+ */
+function classifyPythonExplicitNewReceiver(fnNode) {
+    if (fnNode.childForFieldName('name')?.text !== '__new__')
+        return null;
+    const enclosingClass = findEnclosingClassDefinition(fnNode);
+    const params = fnNode.childForFieldName('parameters');
+    if (enclosingClass === null || params === null)
+        return null;
+    const parameter = firstBoundReceiverParameter(params);
+    if (parameter === null)
         return null;
+    const name = firstParameterName(parameter);
     const className = classDefinitionName(enclosingClass);
-    if (className === null)
+    if (name === null || className === null)
         return null;
-    const firstName = firstParameterName(first);
-    if (firstName === null)
+    return { kind: 'class', parameter, name, className };
+}
+/**
+ * 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 receiver = classifyPythonBoundReceiver(fnNode) ?? classifyPythonExplicitNewReceiver(fnNode);
+    if (receiver === 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) {
+    // The capture tag records the descriptor kind; the variable may use any
+    // spelling.
+    if (receiver.kind === 'class') {
         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),
+            '@type-binding.cls': nodeToCapture('@type-binding.cls', receiver.parameter),
+            '@type-binding.name': syntheticCapture('@type-binding.name', receiver.parameter, receiver.name),
+            '@type-binding.type': syntheticCapture('@type-binding.type', receiver.parameter, receiver.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),
+        '@type-binding.self': nodeToCapture('@type-binding.self', receiver.parameter),
+        '@type-binding.name': syntheticCapture('@type-binding.name', receiver.parameter, receiver.name),
+        '@type-binding.type': syntheticCapture('@type-binding.type', receiver.parameter, receiver.className),
     };
 }
 /**

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

@@ -4,13 +4,27 @@
  *
  * 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`.
+ * resolver, C3 method resolution) 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';
+import type { ReferenceSite, SymbolDefinition, TypeRef } from '../../../../_shared/index.js';
+import type { ArityVerdict, ScopeResolver } from '../../scope-resolution/contract/scope-resolver.js';
+/**
+ * Python subtype dispatch is deliberately limited to instance receiver facts.
+ * Private names are class-mangled and cannot be matched by their source
+ * spelling across an eventual subtype. Argument-shape proof is candidate-level
+ * because it needs both the call-site and target-method capture facts.
+ */
+export declare function pythonMissingReceiverSubtypeDecision(typeRef: TypeRef, context: {
+    readonly receiverBindingIsStatic: boolean | undefined;
+    readonly memberName: string;
+    readonly callArity: number | undefined;
+}): boolean | 'suppress';
+/** Additive compatibility proof for Python's missing-member subtype candidates. */
+export declare function pythonMissingReceiverSubtypeCandidateCompatibility(callerFilePath: string, callsite: Pick<ReferenceSite, 'atRange'>, candidate: SymbolDefinition): ArityVerdict;
 declare const pythonScopeResolver: ScopeResolver;
 export { pythonScopeResolver };

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

@@ -4,7 +4,7 @@
  *
  * 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`.
+ * resolver, C3 method resolution) plug into `runScopeResolution`.
  *
  * Migration reference: when bringing up the next language
  * (TypeScript / Java / Kotlin / Ruby), copy this file's structure —
@@ -12,11 +12,40 @@
  * 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 { buildMro, c3LinearizeStrategy } from '../../scope-resolution/passes/mro.js';
 import { populateClassOwnedMembers } from '../../scope-resolution/scope/walkers.js';
 import { indexOnlyElementType } from '../../type-extractors/shared.js';
 import { pythonProvider } from '../python.js';
 import { isPythonImportedModule, pythonNamespaceReceiverPaths, pythonArityCompatibility, pythonMergeBindings, resolvePythonImportTarget, } from './index.js';
+import { applyPythonSubtypeDispatchSideChannel, pythonSubtypeCallPositionalCount, pythonSubtypePositionalCapacity, } from './subtype-dispatch.js';
+/**
+ * Python subtype dispatch is deliberately limited to instance receiver facts.
+ * Private names are class-mangled and cannot be matched by their source
+ * spelling across an eventual subtype. Argument-shape proof is candidate-level
+ * because it needs both the call-site and target-method capture facts.
+ */
+export function pythonMissingReceiverSubtypeDecision(typeRef, context) {
+    if (typeRef.source !== 'self' || context.receiverBindingIsStatic !== false)
+        return false;
+    const isPrivateName = context.memberName.startsWith('__') && !context.memberName.endsWith('__');
+    if (isPrivateName)
+        return 'suppress';
+    return true;
+}
+/** Additive compatibility proof for Python's missing-member subtype candidates. */
+export function pythonMissingReceiverSubtypeCandidateCompatibility(callerFilePath, callsite, candidate) {
+    const positionalCount = pythonSubtypeCallPositionalCount(callerFilePath, callsite.atRange);
+    if (positionalCount === undefined)
+        return 'unknown';
+    const capacity = pythonSubtypePositionalCapacity(candidate);
+    const minimum = candidate.requiredParameterCount;
+    const maximum = candidate.parameterCount;
+    if (capacity === undefined || minimum === undefined || maximum === undefined)
+        return 'unknown';
+    if (positionalCount < minimum || positionalCount > maximum)
+        return 'incompatible';
+    return positionalCount <= capacity ? 'compatible' : 'incompatible';
+}
 const pythonScopeResolver = {
     // A free call naming a class constructs it: `Service(db).do_work()` (#2708).
     constructionSyntax: { bare: true },
@@ -55,9 +84,21 @@ const pythonScopeResolver = {
     // 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),
+    buildMro: (graph, parsedFiles, nodeLookup) => buildMro(graph, parsedFiles, nodeLookup, c3LinearizeStrategy),
     populateOwners: (parsed) => populateClassOwnedMembers(parsed),
+    applyCaptureSideChannel: applyPythonSubtypeDispatchSideChannel,
     isSuperReceiver: (text) => /^super\s*\(/.test(text),
+    // A mixin may call a method supplied only by its eventual concrete class.
+    // Resolve the callable that DEFINED the binding, rather than the innermost
+    // caller, so a class receiver inherited by a closure cannot masquerade as
+    // instance dispatch. The helper also suppresses Python shapes whose exact
+    // target cannot be represented by the existing call-site facts.
+    resolveMissingReceiverMembersFromSubtypes: pythonMissingReceiverSubtypeDecision,
+    missingReceiverSubtypeCandidateCompatibility: (callsite, candidate, context) => pythonMissingReceiverSubtypeCandidateCompatibility(context.callerFilePath, callsite, candidate),
+    // Python permits both @staticmethod and @classmethod access through an
+    // instance. The graph's generic `isStatic` bit therefore does not mean
+    // "unreachable by instance dispatch" for this provider.
+    isStaticOnly: () => false,
     // Subscript route only — Python spells collection views as method calls
     // (`.values()`), which the compound resolver's call branch already handles.
     //

package/dist/core/ingestion/languages/python/subtype-dispatch.d.ts

@@ -0,0 +1,31 @@
+import type { ParsedFile, SymbolDefinition } from '../../../../_shared/index.js';
+import type { SyntaxNode } from '../../utils/ast-helpers.js';
+type CallShapeTuple = readonly [line: number, column: number, positionalCount: number];
+type CapacityTuple = readonly [line: number, column: number, capacity: number];
+type LineMapper = (line: number) => number;
+/**
+ * Python-private capture facts for conservative missing-member subtype dispatch.
+ * They stay opaque on `ParsedFile.captureSideChannel`; the public reference and
+ * definition schemas intentionally do not gain Python argument-binding fields.
+ */
+export interface PythonSubtypeDispatchSideChannel {
+    readonly kind: 'python-subtype-dispatch';
+    readonly simplePositionalCalls: readonly CallShapeTuple[];
+    readonly positionalCapacities: readonly CapacityTuple[];
+}
+/** Reset one file before a fresh capture or a worker snapshot restore. */
+export declare function beginPythonSubtypeDispatchCapture(filePath: string): void;
+/** Record calls whose arguments are all ordinary positional expressions. */
+export declare function recordPythonSimplePositionalCall(filePath: string, callNode: SyntaxNode, positionalCount: number, mapLine?: LineMapper): void;
+/** Record a method's exact fixed positional capacity when the AST proves it. */
+export declare function recordPythonSubtypeMethodShape(filePath: string, fnNode: SyntaxNode, mapLine?: LineMapper): void;
+/** Snapshot one worker file into structured-clone-safe plain data. */
+export declare function collectPythonSubtypeDispatchSideChannel(filePath: string): PythonSubtypeDispatchSideChannel | undefined;
+/** Restore worker/cache facts without reparsing source on the main thread. */
+export declare function applyPythonSubtypeDispatchSideChannel(parsed: ParsedFile): void;
+export declare function pythonSubtypeCallPositionalCount(filePath: string, range: {
+    readonly startLine: number;
+    readonly startCol: number;
+}): number | undefined;
+export declare function pythonSubtypePositionalCapacity(candidate: SymbolDefinition): number | undefined;
+export {};

package/dist/core/ingestion/languages/python/subtype-dispatch.js

@@ -0,0 +1,183 @@
+import { definitionIdPosition } from '../../scope-resolution/utils/definition-id.js';
+import { classifyPythonBoundReceiver } from './receiver-binding.js';
+const simplePositionalCallsByFile = new Map();
+const positionalCapacitiesByFile = new Map();
+const positionKey = (line, column) => `${line}:${column}`;
+const nodePosition = (node, mapLine) => {
+    const line = node.startPosition.row + 1;
+    return [mapLine?.(line) ?? line, node.startPosition.column];
+};
+/** Reset one file before a fresh capture or a worker snapshot restore. */
+export function beginPythonSubtypeDispatchCapture(filePath) {
+    simplePositionalCallsByFile.delete(filePath);
+    positionalCapacitiesByFile.delete(filePath);
+}
+/** Record calls whose arguments are all ordinary positional expressions. */
+export function recordPythonSimplePositionalCall(filePath, callNode, positionalCount, mapLine) {
+    const [line, column] = nodePosition(callNode, mapLine);
+    let sites = simplePositionalCallsByFile.get(filePath);
+    if (sites === undefined) {
+        sites = new Map();
+        simplePositionalCallsByFile.set(filePath, sites);
+    }
+    sites.set(positionKey(line, column), positionalCount);
+}
+function parameterBindingNode(parameter) {
+    if (parameter.type === 'typed_parameter' ||
+        parameter.type === 'default_parameter' ||
+        parameter.type === 'typed_default_parameter') {
+        return parameter.childForFieldName('name') ?? parameter.firstNamedChild ?? parameter;
+    }
+    return parameter;
+}
+function sameNodePosition(left, right) {
+    return (left.startPosition.row === right.startPosition.row &&
+        left.startPosition.column === right.startPosition.column &&
+        left.endPosition.row === right.endPosition.row &&
+        left.endPosition.column === right.endPosition.column);
+}
+/**
+ * Count parameters that can receive ordinary positional arguments after
+ * Python's descriptor-bound receiver is removed. `*args` and any required
+ * keyword-only parameter are deliberately unknown: this successor proves
+ * fixed positional calls only.
+ */
+function positionalCapacity(fnNode) {
+    const parameters = fnNode.childForFieldName('parameters');
+    if (parameters === null)
+        return undefined;
+    const receiver = classifyPythonBoundReceiver(fnNode)?.parameter;
+    let capacity = 0;
+    let keywordOnly = false;
+    for (const parameter of parameters.namedChildren) {
+        if (parameter === null || parameter.type === 'comment')
+            continue;
+        if (receiver !== undefined && sameNodePosition(parameter, receiver))
+            continue;
+        const binding = parameterBindingNode(parameter);
+        if (binding.type === 'positional_separator')
+            continue;
+        if (binding.type === 'keyword_separator') {
+            keywordOnly = true;
+            continue;
+        }
+        if (binding.type === 'dictionary_splat_pattern')
+            break;
+        if (binding.type === 'list_splat_pattern')
+            return undefined;
+        if (binding.type !== 'identifier' &&
+            parameter.type !== 'default_parameter' &&
+            parameter.type !== 'typed_parameter' &&
+            parameter.type !== 'typed_default_parameter') {
+            return undefined;
+        }
+        if (keywordOnly) {
+            if (parameter.type !== 'default_parameter' && parameter.type !== 'typed_default_parameter') {
+                return undefined;
+            }
+            continue;
+        }
+        capacity++;
+    }
+    return capacity;
+}
+/** Record a method's exact fixed positional capacity when the AST proves it. */
+export function recordPythonSubtypeMethodShape(filePath, fnNode, mapLine) {
+    const capacity = positionalCapacity(fnNode);
+    if (capacity === undefined)
+        return;
+    const [line, column] = nodePosition(fnNode, mapLine);
+    let capacities = positionalCapacitiesByFile.get(filePath);
+    if (capacities === undefined) {
+        capacities = new Map();
+        positionalCapacitiesByFile.set(filePath, capacities);
+    }
+    capacities.set(positionKey(line, column), capacity);
+}
+function parsePositionKey(key) {
+    const match = /^(\d+):(\d+)$/.exec(key);
+    if (match === null)
+        return undefined;
+    return [Number(match[1]), Number(match[2])];
+}
+/** Snapshot one worker file into structured-clone-safe plain data. */
+export function collectPythonSubtypeDispatchSideChannel(filePath) {
+    const callSites = [];
+    for (const [key, positionalCount] of simplePositionalCallsByFile.get(filePath) ?? []) {
+        const position = parsePositionKey(key);
+        if (position !== undefined)
+            callSites.push([position[0], position[1], positionalCount]);
+    }
+    const capacities = [];
+    for (const [key, capacity] of positionalCapacitiesByFile.get(filePath) ?? []) {
+        const position = parsePositionKey(key);
+        if (position !== undefined)
+            capacities.push([position[0], position[1], capacity]);
+    }
+    if (callSites.length === 0 && capacities.length === 0)
+        return undefined;
+    return {
+        kind: 'python-subtype-dispatch',
+        simplePositionalCalls: callSites,
+        positionalCapacities: capacities,
+    };
+}
+/** Restore worker/cache facts without reparsing source on the main thread. */
+export function applyPythonSubtypeDispatchSideChannel(parsed) {
+    beginPythonSubtypeDispatchCapture(parsed.filePath);
+    const data = parsed.captureSideChannel;
+    if (data === undefined ||
+        data === null ||
+        typeof data !== 'object' ||
+        data.kind !== 'python-subtype-dispatch' ||
+        !Array.isArray(data.simplePositionalCalls) ||
+        !Array.isArray(data.positionalCapacities)) {
+        return;
+    }
+    for (const position of data.simplePositionalCalls) {
+        if (!validCallShape(position))
+            continue;
+        let sites = simplePositionalCallsByFile.get(parsed.filePath);
+        if (sites === undefined) {
+            sites = new Map();
+            simplePositionalCallsByFile.set(parsed.filePath, sites);
+        }
+        sites.set(positionKey(position[0], position[1]), position[2]);
+    }
+    for (const entry of data.positionalCapacities) {
+        if (!validCapacity(entry))
+            continue;
+        let capacities = positionalCapacitiesByFile.get(parsed.filePath);
+        if (capacities === undefined) {
+            capacities = new Map();
+            positionalCapacitiesByFile.set(parsed.filePath, capacities);
+        }
+        capacities.set(positionKey(entry[0], entry[1]), entry[2]);
+    }
+}
+function validPosition(value) {
+    return (value.length === 2 &&
+        Number.isInteger(value[0]) &&
+        value[0] > 0 &&
+        Number.isInteger(value[1]) &&
+        value[1] >= 0);
+}
+function validCallShape(value) {
+    return validPosition(value.slice(0, 2)) && Number.isInteger(value[2]) && value[2] >= 0;
+}
+function validCapacity(value) {
+    return validPosition(value.slice(0, 2)) && Number.isInteger(value[2]) && value[2] >= 0;
+}
+export function pythonSubtypeCallPositionalCount(filePath, range) {
+    return simplePositionalCallsByFile
+        .get(filePath)
+        ?.get(positionKey(range.startLine, range.startCol));
+}
+export function pythonSubtypePositionalCapacity(candidate) {
+    const position = definitionIdPosition(candidate.nodeId, candidate.filePath);
+    if (position === undefined)
+        return undefined;
+    return positionalCapacitiesByFile
+        .get(candidate.filePath)
+        ?.get(positionKey(position.line, position.column));
+}

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

@@ -30,6 +30,8 @@ import { extractDjangoRoutes } from '../route-extractors/django.js';
 import { discoverDjangoRootUrls } from '../route-extractors/django-root-discovery.js';
 import { extractPythonModuleConstants } from '../route-extractors/python-const-resolver.js';
 import { pythonDecoratorRouteHandlerName } from '../route-extractors/python-decorator-handler.js';
+import { assertCloneable } from '../workers/clone-safety.js';
+import { collectPythonSubtypeDispatchSideChannel } from './python/subtype-dispatch.js';
 const BUILT_INS = new Set([
     'print',
     'len',
@@ -128,6 +130,7 @@ export const pythonProvider = defineLanguage({
     // full per-hook rationale and the canonical capture vocabulary in
     // ./python/query.ts (PYTHON_SCOPE_QUERY constant).
     emitScopeCaptures: emitPythonScopeCaptures,
+    collectCaptureSideChannel: (filePath) => assertCloneable(collectPythonSubtypeDispatchSideChannel(filePath)),
     cfgVisitor: createPythonCfgVisitor(),
     interpretImport: interpretPythonImport,
     interpretTypeBinding: interpretPythonTypeBinding,