ucn 4.2.3 → 5.0.2

package/languages/python.js

@@ -38,6 +38,68 @@ function extractReturnType(node) {
     return null;
 }
 
+const PY_FUNCTION_SCOPE_NODES = new Set([
+    'function_definition', 'async_function_definition', 'lambda',
+]);
+
+/**
+ * Concrete constructor calls returned by one Python function.
+ *
+ * This is deliberately data-only parser evidence. Query-time analysis still
+ * resolves each qualifier against the producer file before deciding whether
+ * the runtime class is project-owned or external. Recording the full
+ * qualifier is what makes aliases such as
+ * `Event = Union[asyncio.Event, trio.Event]` usable without treating the
+ * annotation's unresolved terminal name as type identity.
+ */
+function extractReturnedConstructors(node) {
+    const body = node.childForFieldName('body');
+    if (!body) return null;
+    const constructors = [];
+    let incomplete = false;
+    const unwrapValue = value => {
+        let current = value;
+        while (current && ['parenthesized_expression', 'await'].includes(current.type) &&
+            current.namedChildCount === 1) {
+            current = current.namedChild(0);
+        }
+        return current;
+    };
+    const stack = [body];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (current !== body && PY_FUNCTION_SCOPE_NODES.has(current.type)) continue;
+        if (current.type === 'class_definition') continue;
+        if (current.type === 'return_statement') {
+            const value = unwrapValue(current.namedChild(0));
+            if (value?.type !== 'call') {
+                incomplete = true;
+                continue;
+            }
+            const callable = value.childForFieldName('function');
+            let type, qualifier;
+            if (callable?.type === 'identifier') {
+                type = callable.text;
+            } else if (callable?.type === 'attribute') {
+                type = callable.childForFieldName('attribute')?.text;
+                qualifier = callable.childForFieldName('object')?.text;
+            }
+            if (!type || !/^[A-Z]/.test(type) || (qualifier && !/^[\w.]+$/.test(qualifier))) {
+                incomplete = true;
+                continue;
+            }
+            constructors.push({ type, ...(qualifier && { qualifier }) });
+            continue;
+        }
+        for (let i = current.namedChildCount - 1; i >= 0; i--) {
+            stack.push(current.namedChild(i));
+        }
+    }
+    if (incomplete || constructors.length === 0 ||
+        new Set(constructors.map(item => item.type)).size !== 1) return null;
+    return constructors;
+}
+
 /**
  * Find the actual def line (not decorator) for docstring extraction
  */
@@ -110,6 +172,7 @@ function _processFunction(node, functions, processedRanges, lines, code) {
             const endLine = node.endPosition.row + 1;
             const indent = getIndent(node, code);
             const returnType = extractReturnType(node);
+            const returnedConstructors = extractReturnedConstructors(node);
             const defLine = getDefLine(node);
             const docstring = extractPythonDocstring(lines, defLine);
 
@@ -135,6 +198,7 @@ function _processFunction(node, functions, processedRanges, lines, code) {
                 isAsync,
                 modifiers: isAsync ? ['async'] : [],
                 ...(returnType && { returnType }),
+                ...(returnedConstructors && { returnedConstructors }),
                 ...(paramTypes && { paramTypes }),
                 ...(docstring && { docstring }),
                 ...(decorators.length > 0 && { decorators }),
@@ -317,30 +381,64 @@ function extractDecorators(node) {
 
 
 /**
- * Type aliases (fix #251 — rule 7: TS/Rust/Go aliases are indexed, Python's
- * were invisible to typedef/find): PEP 695 `type X = int` and annotated
- * `X: TypeAlias = ...` assignments become 'type' symbols with aliasOf.
+ * Return the runtime/type-identity head of a Python alias expression.
+ * `typing.Dict[str, int]` and `dict[str, int]` both alias `dict`; a project
+ * generic such as `Page[T]` aliases `Page`. Unions deliberately have no
+ * single identity and therefore return null.
+ */
+const PY_ALIAS_RUNTIME_TYPES = new Map([
+    ['Dict', 'dict'], ['List', 'list'], ['Set', 'set'], ['Tuple', 'tuple'],
+    ['FrozenSet', 'frozenset'], ['Text', 'str'],
+]);
+
+function pythonAliasBase(node) {
+    let current = unwrapTypeNode(node);
+    while (current?.type === 'parenthesized_expression' &&
+        current.namedChildCount === 1) {
+        current = unwrapTypeNode(current.namedChild(0));
+    }
+    if (!current) return null;
+    if (current.type === 'binary_operator') return null;
+    if (current.type === 'subscript' || current.type === 'generic_type') {
+        const parts = genericTypeParts(current);
+        if (!parts?.base) return null;
+        return PY_ALIAS_RUNTIME_TYPES.get(parts.base) || parts.base;
+    }
+    const base = typeNameFromExpr(current);
+    return base ? (PY_ALIAS_RUNTIME_TYPES.get(base) || base) : null;
+}
+
+/**
+ * Python type aliases: PEP 695 `type X = int`, annotated
+ * `X: TypeAlias = ...`, and module-scope static aliases such as
+ * `Scope = typing.Dict[str, Any]` become `type` symbols. The last form is
+ * accepted only for conventional type-style names and generic type
+ * expressions, avoiding ordinary runtime assignments.
  */
 function _processTypeAlias(node, classes, processedRanges, lines) {
     let name;
-    let valueText;
+    let valueNode;
     if (node.type === 'type_alias_statement') {
         // grammar shape: type <left> = <right>
         const left = node.namedChild(0);
         const right = node.namedChild(1);
         if (!left) return false;
         name = left.text.replace(/\[.*\]$/, ''); // strip PEP 695 type params
-        valueText = right ? right.text : null;
+        valueNode = right || null;
     } else if (node.type === 'expression_statement') {
         const child = node.namedChild(0);
         if (!child || child.type !== 'assignment') return false;
         const typeNode = child.childForFieldName('type');
-        if (!typeNode || !/\bTypeAlias\b/.test(typeNode.text)) return false;
         const leftNode = child.childForFieldName('left');
         const rightNode = child.childForFieldName('right');
         if (!leftNode || leftNode.type !== 'identifier') return false;
+        const explicit = !!typeNode && /\bTypeAlias\b/.test(typeNode.text);
+        const implicit = !typeNode && node.parent?.type === 'module' &&
+            /^[A-Z][A-Za-z0-9_]*$/.test(leftNode.text) &&
+            ['subscript', 'generic_type'].includes(unwrapTypeNode(rightNode)?.type);
+        if (!explicit && !implicit) return false;
         name = leftNode.text;
-        valueText = rightNode ? rightNode.text : null;
+        valueNode = rightNode || null;
     } else {
         return false;
     }
@@ -349,6 +447,7 @@ function _processTypeAlias(node, classes, processedRanges, lines) {
     if (processedRanges.has(rangeKey)) return true;
     processedRanges.add(rangeKey);
     const { startLine, endLine } = nodeToLocation(node, lines);
+    const aliasOf = pythonAliasBase(valueNode);
     classes.push({
         name,
         type: 'type',
@@ -356,7 +455,7 @@ function _processTypeAlias(node, classes, processedRanges, lines) {
         endLine,
         methods: [],
         members: [],
-        ...(valueText && { aliasOf: valueText.trim() }),
+        ...(aliasOf && { aliasOf }),
     });
     return true;
 }
@@ -464,6 +563,7 @@ function extractClassMembers(classNode, code) {
 
                 const isAsync = funcNode.text.trimStart().startsWith('async ');
                 const returnType = extractReturnType(funcNode);
+                const returnedConstructors = extractReturnedConstructors(funcNode);
                 const defLine = getDefLine(funcNode);
                 const docstring = extractPythonDocstring(code, defLine);
                 // nameLine: where the name identifier lives (differs from startLine when decorated)
@@ -483,6 +583,7 @@ function extractClassMembers(classNode, code) {
                     // Match top-level Python functions: `async def` → ['async'] modifiers.
                     modifiers: isAsync ? ['async'] : [],
                     ...(returnType && { returnType }),
+                    ...(returnedConstructors && { returnedConstructors }),
                     ...(paramTypes && { paramTypes }),
                     ...(docstring && { docstring }),
                     ...(memberDecorators.length > 0 && { decorators: memberDecorators }),
@@ -585,6 +686,263 @@ function typeNameFromAnnotation(typeNode) {
     return typeNameFromExpr(inner);
 }
 
+function typeNamesFromAnnotation(typeNode) {
+    if (!typeNode) return [];
+    const inner = typeNode.namedChildCount > 0 ? typeNode.namedChild(0) : null;
+    const collect = node => {
+        if (!node) return [];
+        if (node.type === 'binary_operator' && node.text.includes('|')) {
+            return [...collect(node.namedChild(0)), ...collect(node.namedChild(1))];
+        }
+        if (node.type === 'identifier') return node.text === 'None' ? [] : [node.text];
+        if (node.type === 'none') return [];
+        if (node.type === 'attribute') {
+            const attr = node.childForFieldName('attribute');
+            return attr ? [attr.text] : [];
+        }
+        return [];
+    };
+    return [...new Set(collect(inner))];
+}
+
+function unwrapTypeNode(node) {
+    let current = node;
+    while (current?.type === 'type' && current.namedChildCount === 1) {
+        current = current.namedChild(0);
+    }
+    return current;
+}
+
+function genericTypeParts(node) {
+    const current = unwrapTypeNode(node);
+    if (!current || !['generic_type', 'subscript'].includes(current.type)) return null;
+    const baseNode = current.type === 'subscript'
+        ? (current.childForFieldName('value') || current.namedChild(0))
+        : current.namedChild(0);
+    const base = typeNameFromExpr(baseNode);
+    if (!base) return null;
+    let args;
+    if (current.type === 'subscript') {
+        args = [];
+        for (let i = 0; i < current.namedChildCount; i++) {
+            const child = current.namedChild(i);
+            if (child.id !== baseNode.id) args.push(unwrapTypeNode(child));
+        }
+    } else {
+        const params = current.namedChild(1);
+        args = [];
+        if (params) {
+            for (let i = 0; i < params.namedChildCount; i++) {
+                args.push(unwrapTypeNode(params.namedChild(i)));
+            }
+        }
+    }
+    return { base, args };
+}
+
+const PY_ITERABLE_ANNOTATIONS = new Set([
+    'list', 'set', 'tuple', 'Iterable', 'Iterator', 'Sequence',
+    'Collection', 'Generator', 'List', 'Set', 'Tuple',
+]);
+
+function iterableBindingTypes(typeNode) {
+    const outer = genericTypeParts(typeNode);
+    if (!outer || !PY_ITERABLE_ANNOTATIONS.has(outer.base) ||
+        outer.args.length === 0) return [];
+    const item = outer.args[0];
+    const tuple = genericTypeParts(item);
+    if (['tuple', 'Tuple'].includes(tuple?.base) && tuple.args.length > 0) {
+        return tuple.args.map(arg => typeNameFromExpr(unwrapTypeNode(arg)));
+    }
+    const typeName = typeNameFromExpr(unwrapTypeNode(item));
+    return typeName ? [typeName] : [];
+}
+
+function patternIdentifiers(node, out = []) {
+    if (!node) return out;
+    if (node.type === 'identifier') {
+        out.push(node.text);
+        return out;
+    }
+    for (let i = 0; i < node.namedChildCount; i++) {
+        patternIdentifiers(node.namedChild(i), out);
+    }
+    return out;
+}
+
+function enclosingPythonClassName(node) {
+    for (let current = node; current; current = current.parent) {
+        if (current.type === 'class_definition') {
+            return current.childForFieldName('name')?.text;
+        }
+    }
+    return null;
+}
+
+function explicitInstanceFieldContracts(tree, parser) {
+    const result = new Map();
+    const parseCommentType = comment => {
+        const text = comment?.text?.trim();
+        const prefix = '# type:';
+        if (!text?.startsWith(prefix)) return null;
+        const annotation = text.slice(prefix.length).trim();
+        if (!annotation) return null;
+        const annotationTree = parseTree(parser, `_value: ${annotation}`);
+        const statement = annotationTree.rootNode.namedChild(0);
+        const assignment = statement?.namedChild(0);
+        return assignment?.childForFieldName('type') || null;
+    };
+    traverseTreeCached(tree.rootNode, node => {
+        if (node.type !== 'expression_statement') return true;
+        const assignment = node.namedChild(0);
+        if (assignment?.type !== 'assignment') return true;
+        const left = assignment.childForFieldName('left');
+        if (left?.type !== 'attribute' ||
+            left.childForFieldName('object')?.text !== 'self') return true;
+        const field = left.childForFieldName('attribute')?.text;
+        const className = enclosingPythonClassName(node);
+        if (!field || !className) return true;
+        let typeNode = assignment.childForFieldName('type');
+        if (!typeNode) {
+            const parent = node.parent;
+            for (let i = 0; parent && i < parent.namedChildCount; i++) {
+                const sibling = parent.namedChild(i);
+                if (sibling.type === 'comment' &&
+                    sibling.startPosition.row === node.endPosition.row) {
+                    typeNode = parseCommentType(sibling);
+                    if (typeNode) break;
+                }
+            }
+        }
+        if (!typeNode) return true;
+        const type = typeNameFromAnnotation(typeNode);
+        const itemTypes = iterableBindingTypes(typeNode);
+        if (!type && itemTypes.length === 0) return true;
+        if (!result.has(className)) result.set(className, new Map());
+        result.get(className).set(field, {
+            ...(type && { type }),
+            ...(itemTypes.length > 0 && { itemTypes }),
+        });
+        return true;
+    });
+    return result;
+}
+
+function comprehensionReceiverType(
+    refNode, receiverName, iterableTypes, callableIterableTypes = new Map(),
+    instanceFieldContracts = new Map()) {
+    for (let current = refNode?.parent; current; current = current.parent) {
+        if (['generator_expression', 'list_comprehension',
+            'set_comprehension', 'dictionary_comprehension'].includes(current.type)) {
+            for (let i = 0; i < current.namedChildCount; i++) {
+                const clause = current.namedChild(i);
+                if (clause.type !== 'for_in_clause') continue;
+                const names = patternIdentifiers(clause.childForFieldName('left'));
+                const index = names.indexOf(receiverName);
+                const iterable = clause.childForFieldName('right');
+                const types = iterableTypesFromExpr(
+                    iterable, iterableTypes, callableIterableTypes,
+                    instanceFieldContracts, clause);
+                if (index >= 0 && types?.[index]) return types[index];
+            }
+        }
+        if (current.type === 'function_definition' ||
+            current.type === 'async_function_definition' ||
+            current.type === 'lambda') break;
+    }
+    return undefined;
+}
+
+function iterableTypesFromExpr(
+    node, iterableTypes, callableIterableTypes,
+    instanceFieldContracts = new Map(), contextNode = node) {
+    const current = unwrapTypeNode(node);
+    if (!current) return null;
+    if (current.type === 'identifier') return iterableTypes.get(current.text) || null;
+    if (current.type === 'call') {
+        const fn = current.childForFieldName('function');
+        if (fn?.type === 'identifier') return callableIterableTypes.get(fn.text) || null;
+    }
+    if (current.type === 'attribute' &&
+        current.childForFieldName('object')?.text === 'self') {
+        const field = current.childForFieldName('attribute')?.text;
+        const className = enclosingPythonClassName(contextNode);
+        return instanceFieldContracts.get(className)?.get(field)?.itemTypes || null;
+    }
+    return null;
+}
+
+function nodeContains(ancestor, node) {
+    return !!ancestor && !!node &&
+        node.startIndex >= ancestor.startIndex && node.endIndex <= ancestor.endIndex;
+}
+
+function isinstanceTypes(condition, receiverName) {
+    if (!condition || condition.type !== 'call') return [];
+    const fn = condition.childForFieldName('function');
+    const args = condition.childForFieldName('arguments');
+    if (fn?.type !== 'identifier' || fn.text !== 'isinstance' ||
+        !args || args.namedChildCount < 2) return [];
+    const value = args.namedChild(0);
+    const typeExpr = args.namedChild(1);
+    if (value?.type !== 'identifier' || value.text !== receiverName) return [];
+    const extract = node => {
+        if (!node) return [];
+        if (node.type === 'identifier') return [node.text];
+        if (node.type === 'attribute') {
+            const attr = node.childForFieldName('attribute');
+            return attr ? [attr.text] : [];
+        }
+        if (node.type === 'tuple') {
+            const out = [];
+            for (let i = 0; i < node.namedChildCount; i++) {
+                out.push(...extract(node.namedChild(i)));
+            }
+            return out;
+        }
+        return [];
+    };
+    return [...new Set(extract(typeExpr))];
+}
+
+function narrowedReceiverType(refNode, receiverName, declaredUnion) {
+    for (let current = refNode; current?.parent; current = current.parent) {
+        const parent = current.parent;
+        if (parent.type === 'if_statement') {
+            const condition = parent.childForFieldName('condition');
+            const positive = isinstanceTypes(condition, receiverName);
+            if (positive.length === 0) continue;
+            const consequence = parent.childForFieldName('consequence');
+            const alternative = parent.childForFieldName('alternative');
+            if (nodeContains(consequence, refNode) && positive.length === 1) {
+                return positive[0];
+            }
+            if (nodeContains(alternative, refNode) && declaredUnion?.length) {
+                const remaining = declaredUnion.filter(type => !positive.includes(type));
+                if (remaining.length === 1) return remaining[0];
+            }
+        }
+        if (parent.type === 'conditional_expression' &&
+            parent.namedChildCount >= 3) {
+            const consequence = parent.namedChild(0);
+            const condition = parent.namedChild(1);
+            const alternative = parent.namedChild(2);
+            const positive = isinstanceTypes(condition, receiverName);
+            if (nodeContains(consequence, refNode) && positive.length === 1) {
+                return positive[0];
+            }
+            if (nodeContains(alternative, refNode) && declaredUnion?.length) {
+                const remaining = declaredUnion.filter(type => !positive.includes(type));
+                if (remaining.length === 1) return remaining[0];
+            }
+        }
+        if (parent.type === 'function_definition' ||
+            parent.type === 'async_function_definition' ||
+            parent.type === 'lambda') break;
+    }
+    return undefined;
+}
+
 function typeNameFromExpr(node) {
     if (!node) return undefined;
     switch (node.type) {
@@ -595,6 +953,9 @@ function typeNameFromExpr(node) {
             const attr = node.childForFieldName('attribute');
             return attr?.text;
         }
+        case 'parenthesized_expression':
+            return node.namedChildCount === 1
+                ? typeNameFromExpr(node.namedChild(0)) : undefined;
         case 'binary_operator': {
             // PEP 604 union: X | None → X; unions of two real types are ambiguous
             const left = node.namedChild(0);
@@ -654,6 +1015,18 @@ function assignmentTargetOf(callNode) {
     return undefined;
 }
 
+function contextTargetOf(callNode) {
+    const pattern = callNode?.parent;
+    if (pattern?.type !== 'as_pattern' ||
+        pattern.namedChild(0)?.id !== callNode.id) return undefined;
+    const target = pattern.namedChild(pattern.namedChildCount - 1);
+    if (target?.type === 'as_pattern_target') {
+        const identifier = target.namedChild(0);
+        return identifier?.type === 'identifier' ? identifier.text : undefined;
+    }
+    return target?.type === 'identifier' ? target.text : undefined;
+}
+
 /**
  * Type identity hint from a constructor-call callee: ClassName(...) or
  * pkg.ClassName(...).  Preserve the qualifier: dropping `threading` from
@@ -677,14 +1050,161 @@ function constructorTypeInfo(funcNode) {
     return undefined;
 }
 
+function attributeReceiverPath(node) {
+    if (!node || node.type !== 'attribute') return null;
+    const fields = [];
+    let current = node;
+    while (current?.type === 'attribute') {
+        const attribute = current.childForFieldName('attribute');
+        if (!attribute) return null;
+        fields.unshift(attribute.text);
+        current = current.childForFieldName('object');
+    }
+    return current?.type === 'identifier' && fields.length > 0
+        ? { root: current.text, fields }
+        : null;
+}
+
+function iterableAttributeSource(node, localVarTypes) {
+    const current = unwrapTypeNode(node);
+    const path = attributeReceiverPath(current);
+    if (!path) return null;
+    return {
+        root: path.root,
+        fields: path.fields,
+        ...(localVarTypes.get(path.root) && {
+            rootType: localVarTypes.get(path.root),
+        }),
+    };
+}
+
+function literalStringValue(node) {
+    if (node?.type !== 'string') return null;
+    let value = '';
+    for (let i = 0; i < node.namedChildCount; i++) {
+        const child = node.namedChild(i);
+        if (child.type === 'interpolation') return null;
+        if (child.type === 'string_content') value += child.text;
+    }
+    return value;
+}
+
+/**
+ * Return the method name when a method call is dominated by a positive,
+ * receiver-exact capability check:
+ *
+ *     if hasattr(self._stream, "aread"):
+ *         await self._stream.aread(...)
+ *
+ * This is not type evidence—the runtime object may implement any matching
+ * contract—but it is useful provenance for the visible dispatch tier. Keep
+ * the recognizer deliberately narrow: a direct hasattr call or an AND term in
+ * the if/elif condition. OR and NOT do not guarantee the capability on entry.
+ */
+function receiverCapabilityGuard(callNode, receiverNode, methodName) {
+    if (!callNode || !receiverNode || !methodName) return undefined;
+    const receiverText = receiverNode.text;
+
+    const unwrap = node => {
+        let current = node;
+        while (current?.type === 'parenthesized_expression' &&
+            current.namedChildCount === 1) {
+            current = current.namedChild(0);
+        }
+        return current;
+    };
+
+    const matchesHasattr = node => {
+        const current = unwrap(node);
+        if (current?.type !== 'call') return false;
+        const fn = current.childForFieldName('function');
+        if (fn?.type !== 'identifier' || fn.text !== 'hasattr') return false;
+        const args = current.childForFieldName('arguments');
+        if (!args || args.namedChildCount < 2) return false;
+        return args.namedChild(0)?.text === receiverText &&
+            literalStringValue(args.namedChild(1)) === methodName;
+    };
+
+    const positivelyRequiresCapability = node => {
+        const current = unwrap(node);
+        if (matchesHasattr(current)) return true;
+        if (current?.type !== 'boolean_operator') return false;
+        let hasAnd = false;
+        for (let i = 0; i < current.childCount; i++) {
+            const child = current.child(i);
+            if (!child.isNamed && child.type === 'and') hasAnd = true;
+            if (!child.isNamed && child.type === 'or') return false;
+        }
+        return hasAnd && Array.from(
+            { length: current.namedChildCount },
+            (_, i) => current.namedChild(i)
+        ).some(positivelyRequiresCapability);
+    };
+
+    let child = callNode;
+    for (let current = callNode.parent; current; child = current, current = current.parent) {
+        if (current.type === 'function_definition' || current.type === 'lambda') break;
+        if (current.type !== 'if_statement' && current.type !== 'elif_clause') continue;
+        const consequence = current.childForFieldName('consequence');
+        if (!consequence || child.id !== consequence.id) continue;
+        const condition = current.childForFieldName('condition') || current.namedChild(0);
+        if (positivelyRequiresCapability(condition)) return methodName;
+    }
+    return undefined;
+}
+
+function pickleRoundTripSource(node) {
+    if (node?.type !== 'call') return null;
+    const loads = node.childForFieldName('function');
+    if (loads?.type !== 'attribute' ||
+        loads.childForFieldName('object')?.text !== 'pickle' ||
+        loads.childForFieldName('attribute')?.text !== 'loads') return null;
+    const loadsArgs = node.childForFieldName('arguments');
+    const dumped = loadsArgs?.namedChild(0);
+    if (dumped?.type !== 'call') return null;
+    const dumps = dumped.childForFieldName('function');
+    if (dumps?.type !== 'attribute' ||
+        dumps.childForFieldName('object')?.text !== 'pickle' ||
+        dumps.childForFieldName('attribute')?.text !== 'dumps') return null;
+    const value = dumped.childForFieldName('arguments')?.namedChild(0);
+    return value?.type === 'identifier' ? value.text : null;
+}
+
 function findCallsInCode(code, parser) {
     const tree = parseTree(parser, code);
     const calls = [];
+    const instanceFieldContracts = explicitInstanceFieldContracts(tree, parser);
+    // Same-file callable return contracts are a closed type source for loop
+    // bindings: `for item in parse_items()` can use
+    // `parse_items() -> list[Item]` without guessing about external code.
+    const callableIterableTypes = new Map();
+    traverseTreeCached(tree.rootNode, node => {
+        if (node.type !== 'function_definition') return true;
+        const name = node.childForFieldName('name')?.text;
+        const returnType = node.childForFieldName('return_type');
+        const itemTypes = iterableBindingTypes(returnType);
+        if (!name || itemTypes.length === 0) return true;
+        const previous = callableIterableTypes.get(name);
+        if (!previous) callableIterableTypes.set(name, itemTypes);
+        else if (previous.join('\0') !== itemTypes.join('\0')) {
+            // Overloads/redefinitions must agree before their result can type
+            // a receiver.
+            callableIterableTypes.delete(name);
+        }
+        return true;
+    });
     const functionStack = [];  // Stack of { name, startLine, endLine }
     const aliases = new Map();  // Track local aliases: aliasName -> originalName
     const nonCallableNames = new Set();  // Track names assigned non-callable values
     const localVarTypes = new Map();  // Track local variable types: varName -> typeName (for receiverType inference)
+    const declaredVarTypes = new Map(); // Compiler-checked annotations survive later assignments
     const localVarTypeQualifiers = new Map(); // varName -> imported module alias that owns the inferred type
+    const localVarUnionTypes = new Map(); // varName -> concrete PEP 604 alternatives
+    const localIterableTypes = new Map(); // iterable binding -> loop-variable types
+    const localIterationSources = new Map(); // loop variable -> declared iterable path + tuple index
+    const localDictValueTypes = new Map(); // local dict -> exact string-key value types
+    const localVarStdlibContracts = new Map(); // variable -> stdlib module proving its type flow
+    const assignmentRhsReceiverTypes = new Map(); // call-node id -> pre-assignment receiver type
     const constructedReceiverVars = new Set(); // exact constructor-result bindings
     const withBindingVars = new Set(); // names produced by a context-manager as-target
     // Member-access aliases (fix #218): `append = output.append` makes a later
@@ -698,7 +1218,13 @@ function findCallsInCode(code, parser) {
     const memberAliasesStack = [];  // function-scoped save/restore, like localVarTypes
     const moduleAliases = new Set();  // Names bound to MODULES (import httpx / import numpy as np)
     const localVarTypesStack = [];  // Stack for function-scoped save/restore of localVarTypes
+    const declaredVarTypesStack = [];
     const localVarTypeQualifiersStack = [];
+    const localVarUnionTypesStack = [];
+    const localIterableTypesStack = [];
+    const localIterationSourcesStack = [];
+    const localDictValueTypesStack = [];
+    const localVarStdlibContractsStack = [];
     const constructedReceiverVarsStack = [];
     const withBindingVarsStack = [];
 
@@ -779,9 +1305,11 @@ function findCallsInCode(code, parser) {
 
     // Helper to get current enclosing function
     const getCurrentEnclosingFunction = () => {
-        return functionStack.length > 0
-            ? { ...functionStack[functionStack.length - 1] }
-            : null;
+        if (functionStack.length === 0) return null;
+        return {
+            ...functionStack[functionStack.length - 1],
+            scopeChain: functionStack.map(scope => scope.startLine),
+        };
     };
 
     // fix #203: is a bare-identifier function REFERENCE shadowed by a local of
@@ -894,14 +1422,29 @@ function findCallsInCode(code, parser) {
             if (node.parent && node.parent.type === 'decorated_definition') {
                 startLine = node.parent.startPosition.row + 1;
             }
+            const returnParts = genericTypeParts(
+                node.childForFieldName('return_type'));
+            const generatorSendType =
+                ['Generator', 'AsyncGenerator'].includes(returnParts?.base) &&
+                returnParts.args.length > 1
+                    ? typeNameFromExpr(returnParts.args[1]) : undefined;
             functionStack.push({
                 name: extractFunctionName(node),
                 startLine,
-                endLine: node.endPosition.row + 1
+                endLine: node.endPosition.row + 1,
+                ...(generatorSendType && { generatorSendType }),
             });
             // Save localVarTypes so inner declarations don't leak to sibling functions
             localVarTypesStack.push(new Map(localVarTypes));
+            declaredVarTypesStack.push(new Map(declaredVarTypes));
             localVarTypeQualifiersStack.push(new Map(localVarTypeQualifiers));
+            localVarUnionTypesStack.push(new Map(localVarUnionTypes));
+            localIterableTypesStack.push(new Map(localIterableTypes));
+            localIterationSourcesStack.push(new Map(localIterationSources));
+            localDictValueTypesStack.push(new Map(
+                [...localDictValueTypes].map(([name, values]) =>
+                    [name, new Map(values)])));
+            localVarStdlibContractsStack.push(new Map(localVarStdlibContracts));
             constructedReceiverVarsStack.push(new Set(constructedReceiverVars));
             withBindingVarsStack.push(new Set(withBindingVars));
             memberAliasesStack.push(new Map(memberAliases));
@@ -910,12 +1453,59 @@ function findCallsInCode(code, parser) {
         // Track parameter type annotations: def foo(x: Foo) → x is Foo
         if (node.type === 'typed_parameter' || node.type === 'typed_default_parameter') {
             // typed_default_parameter has 'name' field; typed_parameter does not — use namedChild(0)
-            const nameNode = node.childForFieldName('name') || node.namedChild(0);
+            let nameNode = node.childForFieldName('name') || node.namedChild(0);
+            const parameterPattern = nameNode;
+            if (nameNode && ['dictionary_splat_pattern', 'list_splat_pattern']
+                .includes(nameNode.type)) {
+                nameNode = nameNode.namedChild(0);
+            }
             const typeNode = node.childForFieldName('type');
             if (nameNode?.type === 'identifier' && typeNode) {
                 const typeName = typeNameFromAnnotation(typeNode);
-                if (typeName && !['self', 'cls'].includes(nameNode.text)) {
-                    localVarTypes.set(nameNode.text, typeName);
+                const unionTypes = typeNamesFromAnnotation(typeNode);
+                const itemTypes = iterableBindingTypes(typeNode);
+                const receiverType = parameterPattern?.type === 'dictionary_splat_pattern'
+                    ? 'dict'
+                    : (parameterPattern?.type === 'list_splat_pattern' ? 'tuple' : typeName);
+                if (receiverType && !['self', 'cls'].includes(nameNode.text)) {
+                    localVarTypes.set(nameNode.text, receiverType);
+                    declaredVarTypes.set(nameNode.text, receiverType);
+                }
+                if (unionTypes.length > 1) localVarUnionTypes.set(nameNode.text, unionTypes);
+                else localVarUnionTypes.delete(nameNode.text);
+                if (itemTypes.length > 0) localIterableTypes.set(nameNode.text, itemTypes);
+                else localIterableTypes.delete(nameNode.text);
+            }
+        }
+
+        // Compiler-declared iterable element flow for ordinary for-loops.
+        // Tuple destructuring is positional: `for name, value in
+        // headers:`, where headers is list[tuple[bytes, bytes]], types both
+        // receivers as bytes. Comprehensions are handled at the call site
+        // because their result expression precedes the for-clause in the AST.
+        if (node.type === 'for_statement') {
+            const left = node.childForFieldName('left');
+            const right = node.childForFieldName('right');
+            const itemTypes = iterableTypesFromExpr(
+                right, localIterableTypes, callableIterableTypes,
+                instanceFieldContracts, node);
+            if (itemTypes?.length) {
+                const names = patternIdentifiers(left);
+                if (names.length === itemTypes.length) {
+                    for (let i = 0; i < names.length; i++) {
+                        if (itemTypes[i]) localVarTypes.set(names[i], itemTypes[i]);
+                    }
+                } else if (names.length === 1 && itemTypes.length === 1) {
+                    localVarTypes.set(names[0], itemTypes[0]);
+                }
+            } else {
+                const source = iterableAttributeSource(right, localVarTypes);
+                const names = patternIdentifiers(left);
+                for (let i = 0; source && i < names.length; i++) {
+                    localIterationSources.set(names[i], {
+                        ...source,
+                        index: i,
+                    });
                 }
             }
         }
@@ -944,6 +1534,13 @@ function findCallsInCode(code, parser) {
                         } else {
                             localVarTypeQualifiers.delete(targetId.text);
                         }
+                    } else if (ctx.childForFieldName('function')?.type === 'identifier' &&
+                        ctx.childForFieldName('function').text === 'open' &&
+                        !isShadowedByLocal(ctx.childForFieldName('function'), 'open')) {
+                        // Builtin open() is its own context value and always
+                        // yields an IO object. The exact text/binary subtype
+                        // is irrelevant for method-owner exclusion.
+                        localVarTypes.set(targetId.text, 'IO');
                     }
                 }
             }
@@ -954,13 +1551,29 @@ function findCallsInCode(code, parser) {
             const left = node.childForFieldName('left');
             const right = node.childForFieldName('right');
             if (left?.type === 'identifier') {
+                const previousType = localVarTypes.get(left.text);
+                if (previousType && right?.type === 'call') {
+                    const rightFunction = right.childForFieldName('function');
+                    if (rightFunction?.type === 'attribute' &&
+                        rightFunction.childForFieldName('object')?.type === 'identifier' &&
+                        rightFunction.childForFieldName('object').text === left.text) {
+                        assignmentRhsReceiverTypes.set(right.id, previousType);
+                    }
+                }
                 // Track type annotation: x: Foo = ... → x is Foo
                 const typeNode = node.childForFieldName('type');
                 if (typeNode) {
                     const typeName = typeNameFromAnnotation(typeNode);
+                    const unionTypes = typeNamesFromAnnotation(typeNode);
+                    const itemTypes = iterableBindingTypes(typeNode);
                     if (typeName) {
                         localVarTypes.set(left.text, typeName);
+                        declaredVarTypes.set(left.text, typeName);
                     }
+                    if (unionTypes.length > 1) localVarUnionTypes.set(left.text, unionTypes);
+                    else localVarUnionTypes.delete(left.text);
+                    if (itemTypes.length > 0) localIterableTypes.set(left.text, itemTypes);
+                    else localIterableTypes.delete(left.text);
                 }
                 memberAliases.delete(left.text); // any assignment rebinds the name
                 constructedReceiverVars.delete(left.text);
@@ -972,11 +1585,59 @@ function findCallsInCode(code, parser) {
                 if (!typeNode) {
                     localVarTypes.delete(left.text);
                     localVarTypeQualifiers.delete(left.text);
+                    localVarUnionTypes.delete(left.text);
+                    localIterableTypes.delete(left.text);
+                    localIterationSources.delete(left.text);
+                    localDictValueTypes.delete(left.text);
+                    localVarStdlibContracts.delete(left.text);
+                    // Python assignments remain constrained by a variable or
+                    // parameter annotation. Constructor/literal inference is
+                    // nearest-assignment only, but a declared contract is
+                    // valid for every subsequent assignment in type-correct
+                    // code (`boundary: bytes | None; boundary = make()`).
+                    const declaredType = declaredVarTypes.get(left.text);
+                    if (declaredType) localVarTypes.set(left.text, declaredType);
                 } else {
                     // An annotation is the authoritative type source; a
                     // previous constructor qualifier must not survive it.
                     localVarTypeQualifiers.delete(left.text);
                 }
+                // Preserve a declared collection contract through the common
+                // normalization idiom `x = {} if x is None else x`. The
+                // literal branch is a concrete implementation of the prior
+                // protocol; retaining that protocol is compiler-safe and
+                // keeps later method dispatch out of unrelated project
+                // classes.
+                if (!typeNode && previousType &&
+                    right?.type === 'conditional_expression') {
+                    const consequence = right.namedChild(0);
+                    const alternative = right.namedChild(2);
+                    const selfBranch = [consequence, alternative].find(
+                        branch => branch?.type === 'identifier' &&
+                            branch.text === left.text);
+                    const otherBranch = selfBranch === consequence
+                        ? alternative : consequence;
+                    const literalType = otherBranch
+                        ? PY_LITERAL_RECEIVER_TYPES[otherBranch.type] : null;
+                    const compatible = {
+                        Mapping: new Set(['dict']),
+                        MutableMapping: new Set(['dict']),
+                        Sequence: new Set(['list', 'tuple', 'str', 'bytes']),
+                        MutableSequence: new Set(['list']),
+                        Collection: new Set(['list', 'tuple', 'set', 'dict', 'str', 'bytes']),
+                        Iterable: new Set(['list', 'tuple', 'set', 'dict', 'str', 'bytes']),
+                    };
+                    if (selfBranch && literalType &&
+                        (previousType === literalType ||
+                            compatible[previousType]?.has(literalType))) {
+                        localVarTypes.set(left.text, previousType);
+                    }
+                }
+                if (!typeNode && right?.type === 'yield') {
+                    const sendType = functionStack[
+                        functionStack.length - 1]?.generatorSendType;
+                    if (sendType) localVarTypes.set(left.text, sendType);
+                }
                 // Literal assignment types the variable (fix #218):
                 // ansi_bytes = b"…" → bytes; out = [] → list. Compiler-true,
                 // same trust grade as literal receivers ({}.get() → dict).
@@ -985,6 +1646,29 @@ function findCallsInCode(code, parser) {
                     if (litType === 'str' && /^[rRuU]*[bB]/.test(right.text)) litType = 'bytes';
                     localVarTypes.set(left.text, litType);
                 }
+                if (right?.type === 'dictionary') {
+                    const valueTypes = new Map();
+                    for (let i = 0; i < right.namedChildCount; i++) {
+                        const pair = right.namedChild(i);
+                        if (pair.type !== 'pair') continue;
+                        const key = literalStringValue(pair.childForFieldName('key'));
+                        const value = pair.childForFieldName('value');
+                        const valueType = value?.type === 'identifier'
+                            ? localVarTypes.get(value.text)
+                            : PY_LITERAL_RECEIVER_TYPES[value?.type];
+                        if (key != null && valueType) valueTypes.set(key, valueType);
+                    }
+                    if (valueTypes.size > 0) {
+                        localDictValueTypes.set(left.text, valueTypes);
+                    }
+                }
+                const roundTripSource = pickleRoundTripSource(right);
+                const roundTripType = roundTripSource
+                    ? localVarTypes.get(roundTripSource) : null;
+                if (roundTripType && moduleAliases.has('pickle')) {
+                    localVarTypes.set(left.text, roundTripType);
+                    localVarStdlibContracts.set(left.text, 'pickle');
+                }
                 if (right?.type === 'identifier') {
                     aliases.set(left.text, right.text);
                 }
@@ -1068,7 +1752,8 @@ function findCallsInCode(code, parser) {
 
             const enclosingFunction = getCurrentEnclosingFunction();
             let uncertain = false;
-            const assignedTo = assignmentTargetOf(node);
+            const assignedContext = contextTargetOf(node);
+            const assignedTo = assignmentTargetOf(node) || assignedContext;
 
             // Call-site arg count (positional + keyword) for arity pruning.
             // *args/**kwargs splats make the count open-ended — flag them so
@@ -1108,6 +1793,7 @@ function findCallsInCode(code, parser) {
                         ...(recvType && { receiverType: recvType }),
                         ...(recvIsModule && { receiverIsModule: true }),
                         ...(assignedTo && { assignedTo }),
+                        ...(assignedContext && { assignedContext: true }),
                         argCount,
                         ...(argSpread && { argSpread: true }),
                         enclosingFunction,
@@ -1123,6 +1809,7 @@ function findCallsInCode(code, parser) {
                         line: node.startPosition.row + 1,
                         isMethod: false,
                         ...(assignedTo && { assignedTo }),
+                        ...(assignedContext && { assignedContext: true }),
                         argCount,
                         ...(argSpread && { argSpread: true }),
                         enclosingFunction,
@@ -1139,6 +1826,7 @@ function findCallsInCode(code, parser) {
                 if (attrNode) {
                     let receiver = objNode?.type === 'identifier' ? objNode.text : undefined;
                     let selfAttribute = undefined;
+                    const receiverPath = attributeReceiverPath(objNode);
                     // Chained receiver (fix #219): the receiver IS a call —
                     // fetch_data().json() — record the producer so findCallers
                     // can type the receiver from its declared return
@@ -1156,10 +1844,17 @@ function findCallsInCode(code, parser) {
                     }
                     {
                         let recvNode = objNode;
-                        if (recvNode?.type === 'parenthesized_expression' &&
-                            recvNode.namedChild(0)?.type === 'await') {
+                        while (recvNode?.type === 'parenthesized_expression' &&
+                            recvNode.namedChildCount === 1) {
+                            recvNode = recvNode.namedChild(0);
+                        }
+                        if (recvNode?.type === 'await') {
                             receiverCallAwaited = true;
-                            recvNode = recvNode.namedChild(0).namedChild(0);
+                            recvNode = recvNode.namedChild(0);
+                            while (recvNode?.type === 'parenthesized_expression' &&
+                                recvNode.namedChildCount === 1) {
+                                recvNode = recvNode.namedChild(0);
+                            }
                         }
                         if (recvNode?.type === 'call' && receiver !== 'super') {
                             const prodFunc = recvNode.childForFieldName('function');
@@ -1196,17 +1891,63 @@ function findCallsInCode(code, parser) {
 
                     // Literal receivers carry their builtin type: {}.get() can
                     // never be a project class method
+                    let subscriptReceiverType;
+                    if (objNode?.type === 'subscript') {
+                        const base = objNode.childForFieldName('value');
+                        const key = literalStringValue(
+                            objNode.childForFieldName('subscript'));
+                        if (base?.type === 'identifier' && key != null) {
+                            subscriptReceiverType =
+                                localDictValueTypes.get(base.text)?.get(key);
+                        }
+                    }
                     const receiverType = receiver
-                        ? localVarTypes.get(receiver)
-                        : (objNode ? PY_LITERAL_RECEIVER_TYPES[objNode.type] : undefined);
+                        ? (narrowedReceiverType(
+                            objNode, receiver, localVarUnionTypes.get(receiver)) ||
+                            comprehensionReceiverType(
+                                objNode, receiver, localIterableTypes,
+                                callableIterableTypes, instanceFieldContracts) ||
+                            localVarTypes.get(receiver))
+                            || assignmentRhsReceiverTypes.get(node.id)
+                        : (subscriptReceiverType ||
+                            (objNode ? PY_LITERAL_RECEIVER_TYPES[objNode.type] : undefined));
+                    let iterationSource = receiver
+                        ? localIterationSources.get(receiver) : null;
+                    if (receiver && !iterationSource) {
+                        for (let current = objNode?.parent; current; current = current.parent) {
+                            if (['generator_expression', 'list_comprehension',
+                                'set_comprehension', 'dictionary_comprehension']
+                                .includes(current.type)) {
+                                for (let i = 0; i < current.namedChildCount; i++) {
+                                    const clause = current.namedChild(i);
+                                    if (clause.type !== 'for_in_clause') continue;
+                                    const names = patternIdentifiers(
+                                        clause.childForFieldName('left'));
+                                    const index = names.indexOf(receiver);
+                                    if (index < 0) continue;
+                                    const source = iterableAttributeSource(
+                                        clause.childForFieldName('right'),
+                                        localVarTypes);
+                                    if (source) iterationSource = {
+                                        ...source, index,
+                                    };
+                                }
+                            }
+                            if (isFunctionNode(current)) break;
+                        }
+                    }
                     const receiverTypeQualifier = receiver
                         ? localVarTypeQualifiers.get(receiver)
                         : undefined;
+                    const receiverRootType = receiverPath
+                        ? localVarTypes.get(receiverPath.root) : undefined;
                     // Module receiver (httpx.get()) — unless locally shadowed
                     // by a typed instance binding
                     const receiverIsModule = !!receiver && moduleAliases.has(receiver) &&
                         !localVarTypes.has(receiver);
                     const firstArg = getFirstStringArg(node);
+                    const capabilityGuard = receiverCapabilityGuard(
+                        node, objNode, attrNode.text);
                     calls.push({
                         name: attrNode.text,
                         // Multi-line chains (obj.x()\n.y()) must report each
@@ -1216,18 +1957,40 @@ function findCallsInCode(code, parser) {
                         isMethod: true,
                         receiver,
                         ...(receiverType && { receiverType }),
+                        ...(receiver && localVarStdlibContracts.has(receiver) && {
+                            receiverTypeStdlibModule:
+                                localVarStdlibContracts.get(receiver),
+                        }),
                         ...(receiverTypeQualifier && { receiverTypeQualifier }),
                         ...(receiver && constructedReceiverVars.has(receiver) && { receiverConstructed: true }),
                         ...(receiver && withBindingVars.has(receiver) && { receiverWithBinding: true }),
                         ...(receiverIsModule && { receiverIsModule: true }),
                         ...(receiver && objNode?.type === 'identifier' &&
                             isShadowedByLocal(objNode, receiver) && { receiverLocalBinding: true }),
+                        ...(receiverPath && {
+                            receiverRoot: receiverPath.root,
+                            receiverField: receiverPath.fields[receiverPath.fields.length - 1],
+                            receiverFields: receiverPath.fields,
+                        }),
+                        ...(receiverRootType && { receiverRootType }),
+                        ...(iterationSource && {
+                            receiverIterationRoot: iterationSource.root,
+                            receiverIterationFields: iterationSource.fields,
+                            receiverIterationIndex: iterationSource.index,
+                            ...(iterationSource.rootType && {
+                                receiverIterationRootType: iterationSource.rootType,
+                            }),
+                        }),
                         ...(selfAttribute && { selfAttribute }),
                         ...(receiverCall && { receiverCall }),
                         ...(receiverCallIsMethod && { receiverCallIsMethod: true }),
                         ...(receiverCallAwaited && { receiverCallAwaited: true }),
                         ...(receiverCallLine && { receiverCallLine }),
+                        ...(capabilityGuard && {
+                            receiverCapabilityGuard: capabilityGuard,
+                        }),
                         ...(assignedTo && { assignedTo }),
+                        ...(assignedContext && { assignedContext: true }),
                         argCount,
                         ...(argSpread && { argSpread: true }),
                         enclosingFunction,
@@ -1299,11 +2062,47 @@ function findCallsInCode(code, parser) {
                     localVarTypes.clear();
                     for (const [k, v] of saved) localVarTypes.set(k, v);
                 }
+                const savedDeclared = declaredVarTypesStack.pop();
+                if (savedDeclared) {
+                    declaredVarTypes.clear();
+                    for (const [k, v] of savedDeclared) declaredVarTypes.set(k, v);
+                }
                 const savedQualifiers = localVarTypeQualifiersStack.pop();
                 if (savedQualifiers) {
                     localVarTypeQualifiers.clear();
                     for (const [k, v] of savedQualifiers) localVarTypeQualifiers.set(k, v);
                 }
+                const savedUnions = localVarUnionTypesStack.pop();
+                if (savedUnions) {
+                    localVarUnionTypes.clear();
+                    for (const [k, v] of savedUnions) localVarUnionTypes.set(k, v);
+                }
+                const savedIterables = localIterableTypesStack.pop();
+                if (savedIterables) {
+                    localIterableTypes.clear();
+                    for (const [k, v] of savedIterables) localIterableTypes.set(k, v);
+                }
+                const savedIterationSources = localIterationSourcesStack.pop();
+                if (savedIterationSources) {
+                    localIterationSources.clear();
+                    for (const [k, v] of savedIterationSources) {
+                        localIterationSources.set(k, v);
+                    }
+                }
+                const savedDictValueTypes = localDictValueTypesStack.pop();
+                if (savedDictValueTypes) {
+                    localDictValueTypes.clear();
+                    for (const [name, values] of savedDictValueTypes) {
+                        localDictValueTypes.set(name, values);
+                    }
+                }
+                const savedStdlibContracts = localVarStdlibContractsStack.pop();
+                if (savedStdlibContracts) {
+                    localVarStdlibContracts.clear();
+                    for (const [name, moduleName] of savedStdlibContracts) {
+                        localVarStdlibContracts.set(name, moduleName);
+                    }
+                }
                 const savedConstructed = constructedReceiverVarsStack.pop();
                 constructedReceiverVars.clear();
                 if (savedConstructed) for (const name of savedConstructed) constructedReceiverVars.add(name);
@@ -1471,6 +2270,33 @@ function findExportsInCode(code, parser) {
     const exports = [];
 
     traverseTreeCached(tree.rootNode, (node) => {
+        // PEP 484 explicit re-export idiom:
+        // `from .core import public_thing as public_thing`. The redundant
+        // alias is deliberate compiler/tooling evidence that the imported
+        // name belongs to this module's public surface even without __all__.
+        if (node.type === 'import_from_statement') {
+            let source = '';
+            for (let index = 0; index < node.namedChildCount; index++) {
+                const child = node.namedChild(index);
+                if (!source && (child.type === 'dotted_name' ||
+                    child.type === 'relative_import')) {
+                    source = child.text;
+                    continue;
+                }
+                if (child.type !== 'aliased_import') continue;
+                const imported = child.namedChild(0);
+                const alias = child.namedChild(1);
+                if (imported?.text && alias?.text === imported.text) {
+                    exports.push({
+                        name: alias.text,
+                        type: 're-export',
+                        source,
+                        line: node.startPosition.row + 1,
+                    });
+                }
+            }
+            return true;
+        }
         // Look for __all__ = [...]
         if (node.type === 'expression_statement') {
             const child = node.namedChild(0);
@@ -1634,9 +2460,10 @@ function findUsagesInCode(code, name, parser, tree) {
  * @param {object} parser - Tree-sitter parser instance
  * @returns {Map<string, Map<string, string>>} className -> (attrName -> typeName)
  */
-function findInstanceAttributeTypes(code, parser) {
+function findInstanceAttributeTypes(code, parser, options = {}) {
     const tree = parseTree(parser, code);
     const result = new Map(); // className -> Map(attrName -> typeName)
+    const explicitContracts = explicitInstanceFieldContracts(tree, parser);
 
     const PRIMITIVE_TYPES = new Set(['int', 'float', 'str', 'bool', 'bytes', 'list', 'dict', 'set', 'tuple', 'None', 'Any', 'object']);
 
@@ -1651,6 +2478,23 @@ function findInstanceAttributeTypes(code, parser) {
         if (!body) return false;
 
         const attrTypes = new Map();
+        for (const [field, contract] of explicitContracts.get(className) || []) {
+            if (contract.type) attrTypes.set(field, contract.type);
+        }
+        const methodReturns = new Map();
+        for (let i = 0; i < body.namedChildCount; i++) {
+            let member = body.namedChild(i);
+            if (member.type === 'decorated_definition') {
+                member = Array.from({ length: member.namedChildCount },
+                    (_, index) => member.namedChild(index))
+                    .find(child => child.type === 'function_definition') || member;
+            }
+            if (member.type !== 'function_definition') continue;
+            const methodName = member.childForFieldName('name')?.text;
+            const returnType = typeNameFromAnnotation(
+                member.childForFieldName('return_type'));
+            if (methodName && returnType) methodReturns.set(methodName, returnType);
+        }
 
         // Scan annotated class-level fields: name: Type [= ...]. Originally
         // @dataclass-only (fix #28); a BARE class-body annotation is the
@@ -1758,6 +2602,19 @@ function findInstanceAttributeTypes(code, parser) {
                 const typeName = extractConstructorName(rhs);
                 if (typeName) {
                     attrTypes.set(attrName, typeName);
+                } else if (rhs.type === 'call') {
+                    const fn = rhs.childForFieldName('function');
+                    if (fn?.type === 'attribute') {
+                        const moduleName = fn.childForFieldName('object')?.text;
+                        const functionName = fn.childForFieldName('attribute')?.text;
+                        const methodType = moduleName === 'self' && functionName
+                            ? methodReturns.get(functionName) : null;
+                        const builtinType = moduleName && functionName &&
+                            options.resolveBuiltinCallType?.(moduleName, functionName);
+                        if (methodType || builtinType) {
+                            attrTypes.set(attrName, methodType || builtinType);
+                        }
+                    }
                 } else if (rhs.type === 'identifier' && paramTypes.has(rhs.text)) {
                     // self.X = param where param has type annotation
                     attrTypes.set(attrName, paramTypes.get(rhs.text));
@@ -1767,6 +2624,63 @@ function findInstanceAttributeTypes(code, parser) {
             });
         }
 
+        // Stable external/runtime constructors assigned outside __init__ are
+        // still exact field evidence when every observed contract agrees.
+        // This covers lifecycle-owned fields such as
+        // `self.ready = asyncio.Event()` in serve(), without generalizing the
+        // old constructor-name heuristic to arbitrary methods. Unknown or
+        // conflicting assignments leave the field untyped.
+        const runtimeFieldTypes = new Map();
+        const invalidRuntimeFields = new Set();
+        for (let i = 0; i < body.namedChildCount; i++) {
+            let member = body.namedChild(i);
+            if (member.type === 'decorated_definition') {
+                member = Array.from({ length: member.namedChildCount },
+                    (_, index) => member.namedChild(index))
+                    .find(child => child.type === 'function_definition') || member;
+            }
+            if (member.type !== 'function_definition') continue;
+            const memberBody = member.childForFieldName('body');
+            if (!memberBody) continue;
+            traverseTree(memberBody, stmt => {
+                if (stmt.type !== 'expression_statement') return true;
+                const assignment = stmt.firstChild;
+                if (assignment?.type !== 'assignment') return true;
+                const left = assignment.childForFieldName('left');
+                const field = left?.type === 'attribute' &&
+                    left.childForFieldName('object')?.text === 'self'
+                    ? left.childForFieldName('attribute')?.text : null;
+                if (!field) return true;
+                const right = assignment.childForFieldName('right');
+                const callable = right?.type === 'call'
+                    ? right.childForFieldName('function') : null;
+                const moduleName = callable?.type === 'attribute'
+                    ? callable.childForFieldName('object')?.text : null;
+                const functionName = callable?.type === 'attribute'
+                    ? callable.childForFieldName('attribute')?.text : null;
+                const runtimeType = moduleName && functionName
+                    ? options.resolveBuiltinCallType?.(moduleName, functionName)
+                    : null;
+                if (!runtimeType) {
+                    // None is a harmless uninitialized state; any other
+                    // unknown write could replace the field with a project
+                    // value and therefore invalidates exclusion-grade flow.
+                    if (right?.type !== 'none') invalidRuntimeFields.add(field);
+                    return true;
+                }
+                if (!runtimeFieldTypes.has(field)) runtimeFieldTypes.set(field, new Set());
+                runtimeFieldTypes.get(field).add(runtimeType);
+                return true;
+            });
+        }
+        for (const [field, types] of runtimeFieldTypes) {
+            if (invalidRuntimeFields.has(field) || types.size !== 1) continue;
+            const type = [...types][0];
+            if (!attrTypes.has(field) || attrTypes.get(field) === type) {
+                attrTypes.set(field, type);
+            }
+        }
+
         if (attrTypes.size > 0) {
             result.set(className, attrTypes);
         }
@@ -1866,6 +2780,32 @@ function isEntryPoint(symbol) {
     return getEntryPointKind(symbol) !== null;
 }
 
+// Stable CPython/stdlib runtime contracts. These are intentionally small and
+// language-owned: callers must still prove that the import is external (not a
+// project module with the same name) before using them as exclusion evidence.
+const PY_BUILTIN_CALL_RETURNS = Object.freeze({
+    'asyncio.Event': 'AsyncEvent',
+    'base64.b64encode': 'bytes',
+    'base64.b64decode': 'bytes',
+    'json.dumps': 'str',
+    'os.urandom': 'bytes',
+    'urllib.request.getproxies': 'dict',
+    'zlib.compressobj': 'ZlibCompress',
+    'zlib.decompressobj': 'ZlibDecompress',
+});
+
+const PY_BUILTIN_FIELD_TYPES = Object.freeze({
+    'os.environ': 'dict',
+});
+
+function getBuiltinCallReturnType(moduleName, functionName) {
+    return PY_BUILTIN_CALL_RETURNS[`${moduleName}.${functionName}`] || null;
+}
+
+function getBuiltinFieldType(moduleName, fieldName) {
+    return PY_BUILTIN_FIELD_TYPES[`${moduleName}.${fieldName}`] || null;
+}
+
 module.exports = {
     findFunctions,
     findClasses,
@@ -1875,6 +2815,8 @@ module.exports = {
     findExportsInCode,
     findUsagesInCode,
     findInstanceAttributeTypes,
+    getBuiltinCallReturnType,
+    getBuiltinFieldType,
     isEntryPoint,
     getEntryPointKind,
     parse