From 64032216caf3fcd7c6d1c39083d9737568d065b6 Mon Sep 17 00:00:00 2001 From: HugoXK Date: Sat, 21 Nov 2026 05:40:36 +0000 Subject: [PATCH 1/4] test(typing): pin annotation names to module scope (#1203) Every module here defers annotation evaluation, so a name the module never binds at module scope costs nothing at import time and nothing in CI. The new test resolves the property statically: annotation names are read out of the AST (string annotations and nested subscripts included) and must be bound at module scope, where get_type_hints resolves them. Module scope only, by construction: a function-local import binds that function's locals, never the module globals. Two controls pin that -- one synthetic, one on async_evolve.py, whose function-local EvolvingArtifact import must not count -- and a TYPE_CHECKING import must count. Fails on main at e43e847a with the 24 rows this issue lists. --- tests/test_annotation_names.py | 306 +++++++++++++++++++++++++++++++++ 1 file changed, 306 insertions(+) create mode 100644 tests/test_annotation_names.py diff --git a/tests/test_annotation_names.py b/tests/test_annotation_names.py new file mode 100644 index 00000000..33c111ee --- /dev/null +++ b/tests/test_annotation_names.py @@ -0,0 +1,306 @@ +"""An annotation name must be bound at module scope in its own module. + +Every module here opens with ``from __future__ import annotations``, so an +annotation stays a string until a consumer resolves it. A name the module never +binds at module scope therefore costs nothing at import time, nothing in the +suite and nothing in CI -- and only the first resolver (``typing.get_type_hints``, +a schema generator, a type checker reading the source) sees the break. ``#1202`` +found one (``Tuple``), ``#1203`` lists the rest. + +The property pinned is static on purpose, and it is *module scope* only: names +that count are imports (``if TYPE_CHECKING:`` and ``try``/``except`` included -- +they run at module scope), module-level assignments, ``def``/``class`` and +builtins. Neither a function body nor an enclosing function's parameters bind an +annotation name, because ``get_type_hints`` resolves against the function's +``__globals__``; ``import random`` inside a method is invisible to it. A class +body's own bindings do count for that class's attributes, since +``get_type_hints`` resolves those against ``vars(cls)`` too. + +The test does **not** resolve annotations at runtime: that would demand real +imports of ``ParallelStrategy``, ``Invariant`` and ``VerifierBoost`` and +reintroduce the import cycles those strings exist to avoid. +""" + +from __future__ import annotations + +import ast +import builtins +import pathlib +import warnings + +PACKAGE = pathlib.Path(__file__).resolve().parents[1] / "agentdescent" +BUILTINS = set(dir(builtins)) +_SCOPES = (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef) + + +def _scope_imports(nodes: list[ast.stmt]) -> set[str]: + """Names imported while a statement list runs at module scope. + + Descends into the blocks that run there (``if``, ``try``, ``with``, + ``for``, ``while``) and stops at every new scope: an import inside a + function or class body binds that scope's locals, never the module. + """ + names: set[str] = set() + for node in nodes: + if isinstance(node, _SCOPES): + continue + if isinstance(node, ast.Import): + names |= {alias.asname or alias.name.split(".")[0] for alias in node.names} + elif isinstance(node, ast.ImportFrom): + names |= { + alias.asname or alias.name + for alias in node.names + if alias.name != "*" + } + elif isinstance(node, (ast.If, ast.While, ast.For, ast.AsyncFor, ast.With, ast.AsyncWith)): + names |= _scope_imports(node.body) + names |= _scope_imports(getattr(node, "orelse", [])) + elif isinstance(node, ast.Try): + names |= _scope_imports(node.body) + names |= _scope_imports(node.orelse) + names |= _scope_imports(node.finalbody) + for handler in node.handlers: + names |= _scope_imports(handler.body) + return names + + +def _target_names(node: ast.AST) -> set[str]: + if isinstance(node, ast.Name): + return {node.id} + if isinstance(node, (ast.Tuple, ast.List)): + return set().union(*(_target_names(elt) for elt in node.elts)) + if isinstance(node, ast.Starred): + return _target_names(node.value) + return set() + + +def _block_bindings(nodes: list[ast.stmt]) -> set[str]: + """Names this statement list binds at its own level, nested scopes excluded.""" + names: set[str] = set() + for node in nodes: + if isinstance(node, _SCOPES): + names.add(node.name) + elif isinstance(node, ast.Assign): + for target in node.targets: + names |= _target_names(target) + elif isinstance(node, (ast.AnnAssign, ast.AugAssign)): + names |= _target_names(node.target) + elif isinstance(node, (ast.For, ast.AsyncFor)): + names |= _target_names(node.target) + names |= _block_bindings(node.body) + names |= _block_bindings(node.orelse) + elif isinstance(node, (ast.With, ast.AsyncWith)): + for item in node.items: + if item.optional_vars is not None: + names |= _target_names(item.optional_vars) + names |= _block_bindings(node.body) + elif isinstance(node, (ast.If, ast.While)): + names |= _block_bindings(node.body) + names |= _block_bindings(node.orelse) + elif isinstance(node, ast.Try): + names |= _block_bindings(node.body) + names |= _block_bindings(node.orelse) + names |= _block_bindings(node.finalbody) + for handler in node.handlers: + if handler.name: + names.add(handler.name) + names |= _block_bindings(handler.body) + return names + + +def _annotation_names(node: ast.AST) -> set[str]: + """Names a (possibly string-shaped) annotation expression mentions.""" + if isinstance(node, ast.Name): + return {node.id} + if isinstance(node, ast.Attribute): + return _annotation_names(node.value) + if isinstance(node, ast.Subscript): + head = node.value + is_literal = (isinstance(head, ast.Name) and head.id == "Literal") or ( + isinstance(head, ast.Attribute) and head.attr == "Literal" + ) + names = _annotation_names(head) + elements = node.slice.elts if isinstance(node.slice, ast.Tuple) else [node.slice] + if is_literal: # ``Literal["a"]`` holds values, not type names + return names + for element in elements: + names |= _annotation_names(element) + return names + if isinstance(node, ast.Constant) and isinstance(node.value, str): + with warnings.catch_warnings(): # a forward ref may carry a regex "\w" + warnings.simplefilter("ignore") + try: + parsed = ast.parse(node.value, mode="eval") + except SyntaxError: + return set() + return _annotation_names(parsed.body) + if isinstance(node, ast.BinOp): + return _annotation_names(node.left) | _annotation_names(node.right) + if isinstance(node, (ast.Tuple, ast.List)): + return set().union(*(_annotation_names(elt) for elt in node.elts)) + if isinstance(node, ast.Starred): + return _annotation_names(node.value) + return set() + + +def _annotation_sites( + nodes: list[ast.stmt], + owner: str, + local: set[str], + sites: list[tuple[str, ast.AST, set[str]]], + in_function: bool = False, +) -> None: + """Collect ``(owner, annotation, bindings visible besides the module's)``. + + Only annotations something resolves against module globals are collected: a + signature, a class attribute, a module-level variable. A local variable's + annotation inside a function is skipped -- PEP 526 never evaluates it, and a + reader resolves it in that function's own scope, where a local import counts. + """ + for node in nodes: + if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)): + every = [*node.args.posonlyargs, *node.args.args, *node.args.kwonlyargs] + every += [arg for arg in (node.args.vararg, node.args.kwarg) if arg is not None] + for arg in every: + if arg.annotation is not None: + sites.append((node.name, arg.annotation, set())) + if node.returns is not None: + sites.append((node.name, node.returns, set())) + _annotation_sites(node.body, node.name, set(), sites, in_function=True) + elif isinstance(node, ast.ClassDef): + _annotation_sites(node.body, node.name, _block_bindings(node.body), sites, in_function) + elif isinstance(node, ast.AnnAssign): + if not in_function: + sites.append((owner, node.annotation, local)) + elif isinstance(node, (ast.If, ast.While, ast.For, ast.AsyncFor, ast.With, ast.AsyncWith)): + _annotation_sites(node.body, owner, local, sites, in_function) + _annotation_sites(getattr(node, "orelse", []), owner, local, sites, in_function) + elif isinstance(node, ast.Try): + _annotation_sites(node.body, owner, local, sites, in_function) + for handler in node.handlers: + _annotation_sites(handler.body, owner, local, sites, in_function) + _annotation_sites(node.orelse, owner, local, sites, in_function) + _annotation_sites(node.finalbody, owner, local, sites, in_function) + + +def _module_bindings(source: str) -> set[str]: + """Everything this module binds at module scope, builtins excluded.""" + with warnings.catch_warnings(): # a demo literal carries a regex "\w" + warnings.simplefilter("ignore") + tree = ast.parse(source) + return _scope_imports(tree.body) | _block_bindings(tree.body) + + +def _imports_in_functions(source: str) -> set[str]: + """Names the module imports only from inside a function body.""" + with warnings.catch_warnings(): + warnings.simplefilter("ignore") + tree = ast.parse(source) + found: set[str] = set() + for node in ast.walk(tree): + if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda)): + for inner in ast.walk(node): + if isinstance(inner, ast.ImportFrom): + found |= {alias.asname or alias.name for alias in inner.names} + elif isinstance(inner, ast.Import): + found |= {alias.asname or alias.name.split(".")[0] for alias in inner.names} + return found + + +def _type_checking_imports(source: str) -> set[str]: + """Names the module imports under a module-level ``if TYPE_CHECKING:``.""" + with warnings.catch_warnings(): + warnings.simplefilter("ignore") + tree = ast.parse(source) + found: set[str] = set() + for node in tree.body: + if not isinstance(node, ast.If): + continue + test = node.test + if not (isinstance(test, ast.Name) and test.id == "TYPE_CHECKING"): + continue + found |= _scope_imports(node.body) + return found + + +def _unbound_rows(source: str, module: str) -> dict[tuple[str, str], set[str]]: + """``(module, name)`` -> owners, for every annotation name the module misses.""" + with warnings.catch_warnings(): # a demo literal carries a regex "\w" + warnings.simplefilter("ignore") + tree = ast.parse(source) + module_bound = _module_bindings(source) | BUILTINS + sites: list[tuple[str, ast.AST, set[str]]] = [] + _annotation_sites(tree.body, "", set(), sites) + + rows: dict[tuple[str, str], set[str]] = {} + for owner, annotation, local in sites: + for name in _annotation_names(annotation): + if name in module_bound or name in local: + continue + rows.setdefault((module, name), set()).add(owner) + return rows + + +def _pairs(source: str, module: str) -> list[tuple[str, str]]: + rows = _unbound_rows(source, module) + return sorted( + (f"{module}:{owner}", name) for (module, name), owners in rows.items() for owner in owners + ) + + +def test_module_scope_binding_rule_has_not_drifted() -> None: + """The negative control: a function-local import binds nothing at module scope.""" + in_function = ( + "from __future__ import annotations\n" + "from typing import Optional\n" + "def go(extra: Optional['Hidden'] = None) -> None:\n" + " from .elsewhere import Hidden\n" + " return None\n" + ) + assert _pairs(in_function, "m.py") == [ + ("m.py:go", "Hidden"), + ], "a function-local import must not be credited" + + type_checking_only = ( + "from __future__ import annotations\n" + "from typing import TYPE_CHECKING, Optional\n" + "if TYPE_CHECKING:\n" + " from .elsewhere import Hidden\n" + "def go(extra: Optional['Hidden'] = None) -> None:\n" + " return None\n" + ) + assert _pairs(type_checking_only, "m.py") == [], "a TYPE_CHECKING import is module scope" + + +def _without_type_checking_blocks(source: str) -> str: + tree = ast.parse(source) + tree.body = [ + node + for node in tree.body + if not (isinstance(node, ast.If) and isinstance(node.test, ast.Name) and node.test.id == "TYPE_CHECKING") + ] + return ast.unparse(tree) + + +def test_the_real_modules_pin_the_same_rule() -> None: + """The rule against the real files it was written for, not just a snippet.""" + async_source = (PACKAGE / "async_evolve.py").read_text(encoding="utf-8") + stripped = _without_type_checking_blocks(async_source) + assert "EvolvingArtifact" in _imports_in_functions(stripped), "the file imports it in a function" + assert "EvolvingArtifact" not in _module_bindings(stripped), "that import must credit nothing" + + settings_source = (PACKAGE / "evolve_settings.py").read_text(encoding="utf-8") + assert "RoundInfo" in _type_checking_imports(settings_source), "the TYPE_CHECKING block names it" + assert "RoundInfo" in _module_bindings(settings_source), "TYPE_CHECKING is module scope" + assert "RoundInfo" not in _imports_in_functions(settings_source), "and it is not function-local" + + +def test_every_annotation_name_is_bound() -> None: + pairs: list[tuple[str, str]] = [] + for path in sorted(PACKAGE.rglob("*.py")): + module = path.relative_to(PACKAGE.parent).as_posix() + pairs += _pairs(path.read_text(encoding="utf-8"), module) + report = "\n".join(f" {owner} -> {name}" for owner, name in pairs) + assert not pairs, ( + f"annotation names nothing binds at module scope ({len(pairs)} sites):\n" + report + ) From 691b00fb27acda045df9d45cbd700fcc2d8d530c Mon Sep 17 00:00:00 2001 From: HugoXK Date: Sat, 21 Nov 2026 05:40:36 +0000 Subject: [PATCH 2/4] fix(typing): bind sixteen annotation names at module scope (#1203) Sixteen names over twenty-four annotated objects in twelve modules were never bound at module scope, so resolving any of those annotations raised NameError while the suite stayed green. Nothing here changes runtime behaviour: every module already defers annotation evaluation, and the cross-module names stay behind TYPE_CHECKING because the cycles are why those annotations are strings. Three typing lines gain a name (Union, Optional, Sequence), one existing TYPE_CHECKING block gains CallLimit, seven modules gain a TYPE_CHECKING block, and selection.py takes a plain module-level import random -- stdlib, no cycle. --- agentdescent/agent_society.py | 2 +- agentdescent/async_evolve.py | 6 +++++- agentdescent/audit/wiring.py | 5 ++++- agentdescent/budget.py | 5 ++++- agentdescent/evaluation.py | 2 +- agentdescent/evolution.py | 11 +++++++++-- agentdescent/evolve_settings.py | 2 +- agentdescent/evolvespec.py | 5 ++++- agentdescent/proofs.py | 5 ++++- agentdescent/scheduler.py | 2 +- agentdescent/selection.py | 1 + agentdescent/selfplay.py | 5 ++++- 12 files changed, 39 insertions(+), 12 deletions(-) diff --git a/agentdescent/agent_society.py b/agentdescent/agent_society.py index 318fe5e9..ec3d446f 100644 --- a/agentdescent/agent_society.py +++ b/agentdescent/agent_society.py @@ -19,7 +19,7 @@ import ast import statistics from dataclasses import dataclass, field -from typing import Any, Callable, Dict, List, Mapping, Optional, Sequence, Tuple +from typing import Any, Callable, Dict, List, Mapping, Optional, Sequence, Tuple, Union from .evolution import EvolutionResult, Task, evolve from .meta import MetaOutcome, slot_reflector diff --git a/agentdescent/async_evolve.py b/agentdescent/async_evolve.py index eff77bec..ed7db304 100644 --- a/agentdescent/async_evolve.py +++ b/agentdescent/async_evolve.py @@ -35,7 +35,7 @@ import time import warnings from concurrent.futures import ThreadPoolExecutor -from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple +from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple, TYPE_CHECKING from .advantage import GroupAdvantage from .agents import Usage @@ -59,6 +59,10 @@ from .pipeline import EarlyStop, FirstError, StallGuard, WorkerHealth, describe from .staleness import StaleAction, StalenessPolicy, get_policy +if TYPE_CHECKING: # annotations only: no runtime import, no cycle risk + from .evolve_settings import BudgetSettings, ObservabilitySettings, RuntimeSettings + from .evolution import EvolvingArtifact + def _async_allocator_context(diff, advantage, blast_radius: float = 0.2) -> Any: """Build an :class:`~agentdescent.allocator.AllocatorContext` at an async diff --git a/agentdescent/audit/wiring.py b/agentdescent/audit/wiring.py index e5641c17..a91a1657 100644 --- a/agentdescent/audit/wiring.py +++ b/agentdescent/audit/wiring.py @@ -37,7 +37,7 @@ import warnings from dataclasses import dataclass, field -from typing import Any, Callable, Dict, Iterable, Optional, Sequence, Union +from typing import Any, Callable, Dict, Iterable, Optional, Sequence, TYPE_CHECKING, Union from .calibrator import Calibrator, Rectification from .gate import RectifiedAcceptance, VerifierWatch @@ -46,6 +46,9 @@ from .store import AuditStore from .tap import AuditedReward, RenderTap +if TYPE_CHECKING: # annotations only: no runtime import, no cycle risk + from .boost import VerifierBoost + __all__ = ["Audit", "attach"] diff --git a/agentdescent/budget.py b/agentdescent/budget.py index 72e35a60..51a56f87 100644 --- a/agentdescent/budget.py +++ b/agentdescent/budget.py @@ -36,7 +36,10 @@ import math import threading from dataclasses import dataclass, field -from typing import Any, Callable, Optional +from typing import Any, Callable, Optional, TYPE_CHECKING + +if TYPE_CHECKING: # annotations only: no runtime import, no cycle risk + from .agents import Completion #: Where the fusion tournament stops being built: 75% of the budget spent. diff --git a/agentdescent/evaluation.py b/agentdescent/evaluation.py index 093ee8e0..7559591d 100644 --- a/agentdescent/evaluation.py +++ b/agentdescent/evaluation.py @@ -16,7 +16,7 @@ import math import random from dataclasses import dataclass, field -from typing import Any, Callable, Dict, List, Mapping, Sequence, Tuple +from typing import Any, Callable, Dict, List, Mapping, Optional, Sequence, Tuple __all__ = ["EvaluationReport", "EvaluationRow", "evaluate"] diff --git a/agentdescent/evolution.py b/agentdescent/evolution.py index 1a4cc459..e03cd690 100644 --- a/agentdescent/evolution.py +++ b/agentdescent/evolution.py @@ -38,8 +38,8 @@ import warnings from dataclasses import asdict, dataclass, field, replace as _replace from typing import ( - Any, Callable, Dict, List, Mapping, Optional, Protocol, Sequence, Tuple, - runtime_checkable, + TYPE_CHECKING, Any, Callable, Dict, List, Mapping, Optional, Protocol, + Sequence, Tuple, runtime_checkable, ) from .agents import Completion, Usage, claude @@ -62,6 +62,13 @@ from .staleness import StalenessPolicy from .budget import BudgetGovernor, BudgetStop, CallBudget +if TYPE_CHECKING: # annotations only: no runtime import, no cycle risk + from .budget import CallLimit + from .evolve_settings import BudgetSettings, ObservabilitySettings, RuntimeSettings + from .evolvable import VersionVector + from .parallel import ParallelStrategy + from .trajectory import TrajectoryStore + # --------------------------------------------------------------------------- # Task + actor diff --git a/agentdescent/evolve_settings.py b/agentdescent/evolve_settings.py index 55671760..9836707a 100644 --- a/agentdescent/evolve_settings.py +++ b/agentdescent/evolve_settings.py @@ -28,7 +28,7 @@ if TYPE_CHECKING: from .agents import Usage - from .budget import CallBudget + from .budget import CallBudget, CallLimit from .evolution import RoundInfo from .trajectory import TrajectoryStore diff --git a/agentdescent/evolvespec.py b/agentdescent/evolvespec.py index b36ab008..2aec1587 100644 --- a/agentdescent/evolvespec.py +++ b/agentdescent/evolvespec.py @@ -51,7 +51,7 @@ import os import shlex from dataclasses import dataclass, field, asdict, replace -from typing import Any, Callable, Dict, List, Mapping, Optional, Sequence, Tuple, Union +from typing import Any, Callable, Dict, List, Mapping, Optional, Sequence, Tuple, TYPE_CHECKING, Union from . import algorithms as _algorithms from .agents import Completion, Usage, WorkspaceAgent @@ -71,6 +71,9 @@ from .treestrategy import FileTree, tree_reflector from .workspec import DEFAULT_ALLOWED_PREFIXES, Ref, RefError +if TYPE_CHECKING: # annotations only: no runtime import, no cycle risk + from .budget import CallLimit + __all__ = [ "KINDS", "KIND_ROWS", diff --git a/agentdescent/proofs.py b/agentdescent/proofs.py index c09e0c20..969c14e5 100644 --- a/agentdescent/proofs.py +++ b/agentdescent/proofs.py @@ -38,7 +38,10 @@ import math import time from dataclasses import dataclass -from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple +from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple, TYPE_CHECKING + +if TYPE_CHECKING: # annotations only: no runtime import, no cycle risk + from .invariants import Invariant __all__ = [ "ProofInvariant", diff --git a/agentdescent/scheduler.py b/agentdescent/scheduler.py index 63e9494d..15d361bf 100644 --- a/agentdescent/scheduler.py +++ b/agentdescent/scheduler.py @@ -29,7 +29,7 @@ import threading from collections import defaultdict from dataclasses import dataclass, field -from typing import Any, Dict, List, Optional, Tuple +from typing import Any, Dict, List, Optional, Sequence, Tuple from .stats import difficulty_weight, ucb_score diff --git a/agentdescent/selection.py b/agentdescent/selection.py index ca3b078b..6f4d6139 100644 --- a/agentdescent/selection.py +++ b/agentdescent/selection.py @@ -54,6 +54,7 @@ from __future__ import annotations import math +import random from dataclasses import dataclass, field from typing import ( Dict, List, Mapping, Optional, Protocol, Sequence, Set, Tuple, diff --git a/agentdescent/selfplay.py b/agentdescent/selfplay.py index 3599f47f..c05ced17 100644 --- a/agentdescent/selfplay.py +++ b/agentdescent/selfplay.py @@ -43,13 +43,16 @@ import random from dataclasses import dataclass, field -from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple +from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple, TYPE_CHECKING from .evolution import ( EvolutionResult, Propose, Reward, Run, Strategy, Task, evolve, ) from .sampling import TaskSampler +if TYPE_CHECKING: # annotations only: no runtime import, no cycle risk + from .evolution import RoundInfo + __all__ = ["Challenger", "ChallengerConfig", "FrontierSampler", "curriculum_evolve"] From 15a9218c93f2aae612291bfd6cfd80cb29760629 Mon Sep 17 00:00:00 2001 From: AgentDescent Dev-1 Date: Sat, 21 Nov 2026 17:47:08 +0000 Subject: [PATCH 3/4] chore(typing): changelog fragment for #1203 --- changelog.d/1203-annotation-names.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 changelog.d/1203-annotation-names.md diff --git a/changelog.d/1203-annotation-names.md b/changelog.d/1203-annotation-names.md new file mode 100644 index 00000000..393c320c --- /dev/null +++ b/changelog.d/1203-annotation-names.md @@ -0,0 +1,5 @@ +Fixed +Sixteen annotation names `agentdescent` uses in its own annotations are now +imported at module scope, so `typing.get_type_hints()` on those objects no +longer raises `NameError`. Import-only change: no behaviour, signature or +generated API text changes (#1203). From e3d9475c47cca456e86d8d989b16b00cc8493808 Mon Sep 17 00:00:00 2001 From: AgentDescent Lead Date: Sat, 21 Nov 2026 18:19:12 +0000 Subject: [PATCH 4/4] docs(changelog): describe what #1203 binds statically, not a runtime fix --- changelog.d/1203-annotation-names.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/changelog.d/1203-annotation-names.md b/changelog.d/1203-annotation-names.md index 393c320c..00609090 100644 --- a/changelog.d/1203-annotation-names.md +++ b/changelog.d/1203-annotation-names.md @@ -1,5 +1,11 @@ Fixed -Sixteen annotation names `agentdescent` uses in its own annotations are now -imported at module scope, so `typing.get_type_hints()` on those objects no -longer raises `NameError`. Import-only change: no behaviour, signature or -generated API text changes (#1203). +Sixteen annotation names `agentdescent` uses in annotations that nothing bound at +module scope now resolve there: `Union`, `Optional` and `Sequence` join existing +`typing` imports, `selection.py` gets a plain `import random`, and twelve +cycle-prone cross-module names sit behind `if TYPE_CHECKING:` blocks (seven new, +one extended). Static readers -- a type checker, a schema generator, the new +`tests/test_annotation_names.py` sweep -- now resolve all 24 sites. Runtime +`typing.get_type_hints()` is unchanged for the twelve names kept behind +`if TYPE_CHECKING:` (that block does not execute), which is why the issue scopes +this as AST-level; no annotation text, signature or generated API text changes +(#1203).