gitnexus 1.6.13-rc.44 → 1.6.13-rc.46

package/README.md

@@ -210,7 +210,7 @@ Note that the bundled Graphology path is no longer the slow option it once was:
 
 ## MCP Tools
 
-Your AI agent gets **17 tools** (15 per-repo + 2 group) automatically:
+Your AI agent gets **19 tools** (17 per-repo + 2 group) automatically:
 
 | Tool             | What It Does                                                                                                                                      |
 | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -229,10 +229,12 @@ Your AI agent gets **17 tools** (15 per-repo + 2 group) automatically:
 | `api_impact`     | Pre-change impact report for an API route handler                                                                                                 |
 | `explain`        | Explain persisted taint findings (source→sink flows, `--pdg` indexes)                                                                             |
 | `pdg_query`      | Query control/data dependence at statement level (`--pdg` indexes)                                                                                |
+| `read_file`      | Read a checkout file (optional 0-indexed slice; `maxLines` cap)                                                                                   |
+| `grep`           | Regex search of the working tree for indexed files (1-based hits; optional `caseSensitive` / `literal`)                                           |
 | `group_list`     | List configured repository groups                                                                                                                 |
 | `group_sync`     | Rebuild a group's Contract Registry and cross-repo links                                                                                          |
 
-> Read-only tools can omit `repo` when one repo is indexed, an MCP default is configured, or the GitNexus process cwd is inside a registered path without crossing into an unindexed nested Git checkout. Otherwise—and for mutating tools with multiple indexed repos and no MCP default—specify it explicitly: `query({search_query: "auth", repo: "my-app"})`. Per-repo tools also take an optional `branch` for indexes pinned with `gitnexus analyze --branch`; omitting it queries the workspace index, which follows your checked-out working tree. `explain` and `pdg_query` need an index built with `gitnexus analyze --pdg`.
+> Read-only tools can omit `repo` when one repo is indexed, an MCP default is configured, or the GitNexus process cwd is inside a registered path without crossing into an unindexed nested Git checkout. Otherwise—and for mutating tools with multiple indexed repos and no MCP default—specify it explicitly: `query({search_query: "auth", repo: "my-app"})`. Per-repo tools also take an optional `branch` for indexes pinned with `gitnexus analyze --branch`, except `read_file` and `grep`, which read the checkout and do not accept `branch`. Omitting `branch` queries the workspace index, which follows your checked-out working tree. `explain` and `pdg_query` need an index built with `gitnexus analyze --pdg`.
 
 ## MCP Resources
 

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 {};