"""
Helpers behind the multi-graph precompile: the capture of a callable into one
artifact holding every frame Dynamo produces while the caller's calls run --
the entry frame, the ``torch_dynamo_resume_in_*`` continuations graph breaks
create, and the recompiled variants of each -- stored through CompilePackage
(``torch/_dynamo/package.py``), a low-level component not meant to be used
directly. It is not ``torch.compiler.precompile``, the ahead-of-time capture
API this repository already has (``torch/_precompile.py``), which does not call
into this module; nor ``torch._dynamo.config.caching_precompile``, which caches
``torch.compile`` artifacts transparently without an explicit capture and, when
set, wraps every guard filter, this module's included (see
``default_guard_filter_fn``).

``default_guard_filter_fn`` is the guard filter a capture's serialized guards
are written under. The rest of this module, added by the following commits of
this stack, is the guard tooling that reports what that filter dropped and the
configuration a capture runs under. The filter lives here, with that tooling,
rather than beside the serializer's pre-check in ``guards.py``: it is the
capture's policy over that pre-check, not part of it. Everything here is
internal; the filter alone is unprefixed because the capture session passes it
as the default a caller may name. ``PrecompileSession`` at the end of the module
is the multi-graph capture itself.
"""

from __future__ import annotations

import contextlib
import functools
import hashlib
import importlib.machinery
import os
import re
import site
import sys
import sysconfig
import types
from typing import TYPE_CHECKING

import torch
import torch._functorch.config as functorch_config
from torch._guards import ChainedSource
from torch.compiler._precompile_types import GuardFact as _GuardFact, PrecompileSummary
from torch.utils._config_module import ConfigModule

from .aot_compile import _BUILTINS_DICT_PREFIX, _IMPORT_ALIAS_PREFIX
from .convert_frame import ConvertFrame
from .exc import PackageError
from .guards import CheckFunctionManager, strip_local_scope
from .package import CompilePackage
from .source import (
    AttrSource,
    DictGetItemSource,
    GetItemSource,
    GlobalSource,
    LocalSource,
)


if TYPE_CHECKING:
    import traceback
    from collections.abc import Callable, Iterable, Iterator, Mapping, Sequence
    from typing import Any, NoReturn

    from torch._guards import Source

    from .convert_frame import ConvertFrameReturn
    from .hooks import Hooks
    from .package import _BackendId, _DynamoCacheEntry
    from .repro.after_dynamo import WrapBackendDebug
    from .types import CacheEntry, DynamoFrameType, GuardFilterEntry
    from .variables.builder import FrameStateSizeEntry


# Built once: config.patch() allocates a class and a ContextVar each time it is
# called, and this runs on every frame Dynamo compiles for a package.
_ALLOW_EMPTY_GRAPHS = torch._dynamo.config._make_closure_patcher(
    allow_empty_graphs=True
)


@contextlib.contextmanager
def _capture_config() -> Iterator[None]:
    """The compiler configuration a multi-graph capture's calls run under.

    Backends serialize into the artifact (``bundled_autograd_cache``) rather
    than the process-local inductor cache. The backward lowers eagerly:
    AOTAutograd otherwise defers it to the first ``.backward()``, and a graph
    compiled with grad enabled whose backward was never lowered is never saved,
    so a capture that never makes one -- a training step, or an inference call
    made outside ``torch.no_grad()`` -- would record no backend at all. Such an
    inference call therefore compiles a backward too, and a backward the
    backend cannot compile fails the capture; capturing under
    ``torch.no_grad()`` avoids both.
    ``allow_empty_graphs`` keeps an empty graph as a compiled frame so its
    guards reach the artifact; it also extends the lifetime of objects the frame
    holds -- with it on, a weakref callback on a value the frame captured does
    not fire when the caller drops its reference (test/dynamo/test_repros.py
    ReproTests.test_weakref_callback).

    Every scope patches and restores for itself: ``config.patch`` is re-entrant
    and per-thread, so nested scopes unwind in order and a worker thread sees
    only its own.
    """
    if torch.compiler.config.force_disable_caches:
        raise PackageError(
            "Cannot precompile with torch.compiler.config.force_disable_caches=True: "
            "compiled backends reach the artifact through the AOTAutograd cache, "
            "which that setting turns off, so the capture would record no graphs"
        )
    functorch_patch = {
        "bundled_autograd_cache": True,
        "force_non_lazy_backward_lowering": True,
        # AOTAutogradCache refuses to KEY a graph it cannot address soundly -- a
        # graph calling anything outside its allowlist -- and a refusal means it
        # never saves, so the bundled artifact precompile needs is never
        # recorded and the capture ends with nothing to serialize. That gate
        # asks whether the key tells this graph's behaviour apart from
        # another's, which a precompile artifact does not depend on: it is
        # addressed by backend id and pinned to one torch build, so fall back to
        # a nonce key rather than declining, as torch._dynamo.aot_compile and
        # aot_compile_joint_with_descriptors already do.
        "bypass_autograd_cache_key": True,
    }
    # AOTAutogradCache honours strict_precompile when it loads but not when it
    # saves: a bundled entry that fails to pickle is dropped with a warning and
    # the capture is short one backend, so raise where the pickle fails instead.
    if torch._dynamo.config.strict_precompile:
        functorch_patch["strict_autograd_cache"] = True
    with (
        functorch_config.patch(functorch_patch),
        torch._dynamo.config.patch(allow_empty_graphs=True),
    ):
        yield


class _AllowEmptyGraphsConvertFrame(ConvertFrame):
    """The package's frame converter, compiling its frames with allow_empty_graphs.

    An uncovered no-op branch must become a guarded variant rather than Dynamo's
    ordinary eager-only SkipFrame: a skip applies to the code object, so one
    fallback call permanently skips that frame and no later call can capture
    its other variants. Applied here as well as in _capture_config so the
    package's frames get it -- with the object-lifetime side effect noted there
    -- whenever this converter compiles them, including recompiles of a loaded
    artifact outside any capture-config scope. Beneath CatchErrorsWrapper
    rather than replacing it: frames its skipfile checks reject never pay the
    patch, and this frame stays out of the user stack dynamo_start reports.
    A frame under DistributedDataParallel with optimize_ddp="ddp_optimizer" is
    refused by name when a package is attached; _clone_with_backend below, the
    hook CatchErrorsWrapper calls only for that frame, says why. Without a
    package the DDP clone keeps this subclass, so the flag survives it.
    """

    @property
    def _clone_with_backend(self) -> Callable[[WrapBackendDebug], ConvertFrame]:
        # CatchErrorsWrapper asks for this clone only for a frame under an
        # active DDP module in ddp_optimizer mode (the default, optimize_ddp=True);
        # the other optimize_ddp modes never reach it. DDPOptimizer compiles the
        # graph one bucket at a time and no bucket carries the backend id the
        # package records, so the artifact could never be completed; the base
        # clone would drop the package silently instead. The wrapper probes the
        # attribute with hasattr before calling it, and hasattr swallows only
        # AttributeError, so a getter that raised would raise PackageError out of
        # the probe itself; raising from the returned callable puts the error at
        # the call the wrapper actually makes. A package-less converter is what
        # the tests build, and what a capture session may build before it
        # attaches a package; its clone keeps the subclass, hooks and limit. The
        # stance path (eval_frame._create_wrapped_callback, behind set_stance)
        # rebuilds a plain ConvertFrame with no package and is outside a capture
        # session's contract.
        if self._inner_convert._package is None:
            return lambda backend: type(self)(
                backend, self._hooks, recompile_limit=self._recompile_limit
            )

        def refuse(backend: WrapBackendDebug) -> NoReturn:
            raise PackageError(
                "Cannot precompile a DistributedDataParallel forward with "
                f"torch._dynamo.config.optimize_ddp={torch._dynamo.config.optimize_ddp!r}: "
                "DDPOptimizer compiles the graph one bucket at a time and no bucket "
                "records a backend under the id the package saves. Set "
                'torch._dynamo.config.optimize_ddp="no_optimization" to precompile '
                "a DDP forward (this disables DDPOptimizer's comm/compute overlap); "
                'the "python_reducer" and "python_reducer_without_compiled_forward" '
                "modes bypass DDPOptimizer as well"
            )

        return refuse

    def __call__(
        self,
        frame: DynamoFrameType,
        cache_entry: CacheEntry | None,
        hooks: Hooks,
        frame_state: dict[str, int | FrameStateSizeEntry],
        skip: int = 0,
    ) -> ConvertFrameReturn:
        revert = _ALLOW_EMPTY_GRAPHS()
        try:
            return super().__call__(
                frame, cache_entry, hooks, frame_state, skip=skip + 1
            )
        finally:
            revert()


def default_guard_filter_fn(guard_entries: Sequence[GuardFilterEntry]) -> list[bool]:
    """
    Drop every guard ``CheckFunctionManager.serialize_guards`` would refuse for
    its type or a derived type, and keep everything else.

    The refused types are ``UNSUPPORTED_SERIALIZATION_GUARD_TYPES``: the
    identity guards ID_MATCH, FUNCTION_MATCH, MODULE_MATCH, NN_MODULE,
    CLASS_MATCH and CLOSURE_MATCH (a function by its ``__code__`` id), plus
    DICT_VERSION and WEAKREF_ALIVE. Dropping one gives up on noticing that the
    guarded object was rebound, mutated or collected: rebind a global function
    between capture and load and the artifact serves the graph traced against
    the old one, with no error
    (``test_default_guard_filter_through_serialize_guards``). Every dropped
    slot is reported in ``PrecompileSummary.dropped_guards``, once however many
    variants dropped it.

    The criterion is the pre-check's own: a guard is dropped if its type is
    refused or a derived type is (a CONSTANT_MATCH on a code object runs
    through ID_MATCH), and TYPE_MATCH and BUILTIN_MATCH are kept whatever they
    derive, as the pre-check accepts them before it looks at derived types.
    That keeps BUILTIN_MATCH, an ``id_match_unchecked`` deriving ID_MATCH that
    the loaded artifact still checks against the loading process's builtins.

    A DICT_VERSION derived by a DICT_KEYS_MATCH is ignored. That compensates
    for a ``CheckFunctionManager`` artifact, not a property of the serializer:
    a filter sees the derived types of the pre-filter build, which runs with
    ``save_guards=False`` and so promotes the DICT_KEYS_MATCH on
    ``torch.utils._pytree.SUPPORTED_NODES`` to DICT_VERSION, while the save
    build keeps the DICT_KEYS_MATCH the pre-check accepts
    (``test_default_guard_filter_keeps_the_pytree_registry_keys_match``). A
    ``guards.py`` fix giving both builds one verdict would delete the two
    lines below. A DICT_KEYS_MATCH deriving another refused type, and any other
    type deriving DICT_VERSION, are dropped. Neither this keep nor the
    accepted-by-type branch holds under
    ``torch._dynamo.config.caching_precompile``: its wrapper around every guard
    filter trips over the same artifact and drops, with a warning, any guard
    of type ID_MATCH, CLOSURE_MATCH, WEAKREF_ALIVE or DICT_VERSION or deriving
    ID_MATCH or DICT_VERSION.

    Passing this filter does not mean the artifact serializes: the pre-check
    also refuses a kept TYPE_MATCH on a local-scope type, which cannot be
    pickled by name. The filter keeps such a guard on purpose, so serialization
    fails loudly; dropping the TYPE_MATCH on an ``nn.Module`` of a local class
    would ship an artifact that serves a module of any class whose guarded
    attributes match
    (``test_default_guard_filter_keeps_local_type_guards_for_a_loud_refusal``).
    """
    unsupported = CheckFunctionManager.UNSUPPORTED_SERIALIZATION_GUARD_TYPES
    keep = []
    for g in guard_entries:
        derived = g.derived_guard_types
        if g.guard_type == "DICT_KEYS_MATCH":
            derived = tuple(d for d in derived if d != "DICT_VERSION")
        keep.append(
            # The pre-check's accepted-by-type pair, a literal in serialize_guards,
            # in test_aot_compile.py's keep_builtin_guards and in
            # test_precompile_package.py's _pre_check_accepts too; a type added
            # to one is not seen by the others.
            g.guard_type in ("TYPE_MATCH", "BUILTIN_MATCH")
            or (
                g.guard_type not in unsupported
                and not any(d in unsupported for d in derived)
            )
        )
    return keep


def _owning_module(value: object) -> str | None:
    if isinstance(value, types.ModuleType):
        return value.__name__
    owner = getattr(value, "__module__", None)
    return owner if isinstance(owner, str) else None


def _source_root(source: Source) -> Source:
    return source.get_base() if isinstance(source, ChainedSource) else source


# The list of Dynamo-generated resume functions every generated resume function
# takes as its first parameter (resume_execution.py and
# comprehension_graph_break.py mint the name; codegen_call_resume in
# symbolic_convert.py builds the list). Its entries are generated code, not a
# slot any config chooses, so an identity guard lost on one cannot diverge.
# Only the list and an entry read straight off it are covered: a resume
# function's closure cells carry the resumed frame's cell variables, so a guard
# Dynamo mints past an entry (type(__nested_resume_fns[0].__closure__[0]
# .cell_contents).__call__ for a callable an inner def captured) is the user's
# and is judged like any other value. Its sibling __nested_frame_values is NOT
# here: it carries the live stack and locals of the frames nested INSIDE the
# one resuming, which pops the last entry off it for the callee it resumes, so
# a guard rooted there is judged like the value it stands for.
_DYNAMO_SYNTHESIZED = ("__nested_resume_fns",)


def _is_dynamo_synthesized(source: Source) -> bool:
    if isinstance(source, GetItemSource) and isinstance(source.index, int):
        source = source.base
    return isinstance(source, LocalSource) and source.local_name in _DYNAMO_SYNTHESIZED


def _norm(path: str) -> str:
    """
    realpath then normcase. A relative path resolves against the process cwd,
    so a recorded ``__file__`` is gated with isabs before it gets here and every
    root candidate comes through ``_norm_absolute``; this module's own
    ``__file__`` is taken as read because it is always the path finder's
    spelling, absolute since bpo-43105 (3.10+): the finder that keeps a relative
    one, zipimport, cannot load torch (torch._C is an extension module), and a
    frozen torch has no ``__file__`` at all. os is different: frozen since 3.11,
    its ``__file__`` is spelled from sys._stdlib_dir, relative under a relative
    home until site.abs_paths() re-anchors it at startup, which -S skips.
    """
    return os.path.normcase(os.path.realpath(path))


def _norm_absolute(paths: Iterable[object]) -> set[str]:
    """
    The ``_norm`` of every absolute str among ``paths``; anything else is
    dropped rather than resolved. The interpreter's own metadata can be
    relative: a venv whose pyvenv.cfg ``home`` is relative or a relative
    PYTHONHOME leaves sys.base_prefix, sys._stdlib_dir and every sysconfig
    path relative (os.__file__ alone is re-anchored, by site.abs_paths()),
    a relative PYTHONUSERBASE the user site. Resolved, such a root would sit
    wherever the process cwd was at the first call and stay cached there,
    so a writer and a reader on one interpreter could classify differently.
    """
    return {_norm(p) for p in paths if isinstance(p, str) and os.path.isabs(p)}


@functools.cache
def _stdlib_roots() -> tuple[str, ...]:
    """
    Where this interpreter's own library lives, sorted, so the first root a path
    lies under is the outermost (``_classify_file`` reads it that way). os is
    unquestionably stdlib, so its directory is the direct evidence and the only
    one that stays right when the stdlib is a zip, where that root is the whole
    archive and a third party bundled into it is waived with the stdlib;
    sysconfig and sys._stdlib_dir cover a build where os is frozen with no
    __file__ (``_classify_file`` skips the stdlib arm under ``sys.frozen``, so
    an app bundle does not use them). An install root can nest inside one of
    these (see ``_install_roots``), so a path under both is third party: an
    install root wins over a stdlib root.
    """
    roots: list[object] = []
    os_file = getattr(os, "__file__", None)
    if isinstance(os_file, str) and os.path.isabs(os_file):
        # The directory the file resolves into, not the one it was imported
        # from: in a venv over a symlink-farm prefix (a Nix, Guix or Spack
        # profile) os.py is a per-file link into the store, sysconfig and
        # sys._stdlib_dir already name the farm, and every consumer normalizes
        # the file it asks about.
        roots.append(os.path.dirname(_norm(os_file)))
    roots.append(getattr(sys, "_stdlib_dir", None))  # 3.11+
    paths = sysconfig.get_paths()
    roots += [paths["stdlib"], paths["platstdlib"]]
    if sys.platform == "win32":
        # The stdlib's C extensions live beside Lib, not under it.
        roots.append(os.path.join(sys.base_prefix, "DLLs"))
    return tuple(sorted(_norm_absolute(roots)))


@functools.cache
def _install_roots() -> tuple[str, ...]:
    """
    Where a third party lands. This is the load-bearing exclusion: purelib is
    NESTED inside stdlib in a conda layout and inside platstdlib in a venv (on
    a --with-platlibdir=lib64 build it is platlib that nests, purelib living
    under lib instead), so without it every pip-installed package is under a
    stdlib root.
    """
    paths = sysconfig.get_paths()
    roots: list[object] = [paths["purelib"], paths["platlib"]]
    for name in ("getsitepackages", "getusersitepackages"):
        try:
            got = getattr(site, name)()
            roots += [got] if isinstance(got, str) else list(got)
        except Exception:
            continue  # an old-virtualenv site.py lacks it, or it cannot answer
    # On Windows getsitepackages() lists the bare prefix, which the whole stdlib
    # sits under; a directory a stdlib root lies strictly under is not an
    # install root. A candidate that IS a stdlib root stays one, on purpose:
    # dropping it would leave a third party installed into the stdlib directory
    # itself under no install root and waived with the stdlib, while keeping it
    # only reads the stdlib as third party.
    stdlib = _stdlib_roots()
    normed = _norm_absolute(roots)
    above = {r for r in normed for s in stdlib if s.startswith(r + os.sep)}
    return tuple(sorted(normed - above))


@functools.cache
def _torch_roots() -> tuple[str, ...]:
    """
    Every directory torch's own submodules come from. An editable build splits
    them -- torch/__init__.py out of the source tree, _C.so and version.py out
    of site-packages -- and torch.__path__ is exactly that set. The gate rules
    out a substituted sys.modules['torch'] only: its __path__ is ignored unless
    the torch package directory this file sits under (two levels up, past
    _dynamo) is among the entries, and then every absolute entry is adopted,
    one a third party appended to the real torch's included; a relative entry
    is dropped (``_norm_absolute``). That directory has two spellings, both of
    them roots: resolved as a directory, and two levels up from where this file
    resolves. They differ in a per-file symlink farm (see ``_stdlib_roots``),
    where torch.__path__ names the farm and every consumer asks about a file
    that resolves into the store. The second is taken only while the file still
    resolves to <root>/_dynamo/<file>: a link that flattens the depth would make
    an ancestor of unrelated code a torch root, and then the resolved file lies
    under no root rather than under too wide a one.
    """
    own_file = globals().get("__file__")
    if not own_file:
        return ()  # frozen torch: no directory to anchor to
    own_dir = os.path.dirname(own_file)
    own = os.path.dirname(own_dir)
    roots = {_norm(own)}
    resolved = _norm(own_file)
    tail = os.path.join(os.path.basename(own_dir), os.path.basename(own_file))
    if resolved.endswith(os.sep + os.path.normcase(tail)):
        roots.add(os.path.dirname(os.path.dirname(resolved)))
    search = getattr(sys.modules.get("torch"), "__path__", None) or ()
    listed = _norm_absolute(search)
    if roots & listed:
        roots |= listed
    return tuple(sorted(roots))


def _within(path: str, roots: tuple[str, ...]) -> bool:
    """Prefix test over ``_norm``-ed paths; the caller normalizes both sides."""
    return any(path == r or path.startswith(r + os.sep) for r in roots)


# Belt and braces for an install directory none of the roots name: whichever
# layout put it there, a pip target still ends in one of these. Matched below
# the stdlib root a file was found under, not on the whole path, so a stdlib
# that itself sits under a site-packages directory keeps its waiver.
_INSTALL_DIR_NAMES = frozenset({"site-packages", "dist-packages"})


@functools.cache
def _classify_file(file: str, stdlib: bool) -> bool | None:
    """
    Shipped here (True), shipped elsewhere (False), or no evidence (None), for
    one ``__file__`` judged against the torch roots (``stdlib=False``) or the
    stdlib roots minus the install roots (``stdlib=True``). None is a path that
    cannot be resolved, or any path asked about for the stdlib in a frozen app;
    past those gates the torch arm never answers None: with no torch root (a
    frozen torch) every path is elsewhere, and ``_is_library_module`` waives
    torch names before asking. Cached on the (file, flag) pair rather than on a
    module name: everything else this reads, the roots and ``sys.frozen``, is
    fixed once the process is running, so the answer for a path never changes,
    while the module a name resolves to can (a test that patches either clears
    the cache on both sides of the patch).
    """
    # Before 3.13 ntpath.isabs accepts a driveless \Lib\x.py (its LEGACY BUG
    # comment), which realpath then resolves against the current drive.
    driveless = sys.platform == "win32" and not os.path.splitdrive(file)[0]
    if driveless or not os.path.isabs(file):
        # Resolving it would be against a cwd that is not the one it was
        # recorded under, so it is evidence in neither direction.
        return None
    if "\x00" in file:
        # No file has one. posixpath.realpath raises ValueError on it from lstat;
        # from gh-106242 on, ntpath.realpath swallows that and returns the path
        # unresolved, whose prefix _within would then match.
        return None
    path = _norm(file)
    if not stdlib:
        # Not gated on sys.frozen: the torch root is torch's own package
        # directory, taken from where this file sits, so in a bundle nothing
        # outside torch lies under it, whereas the stdlib root below is the
        # bundle root itself.
        return _within(path, _torch_roots())
    if getattr(sys, "frozen", False):
        # A frozen app bundles the stdlib and every third party under one root
        # with no site-packages component between them, and PyInstaller names
        # that root in sys._stdlib_dir and in the __file__ it gives the
        # CPython-frozen modules (its _fixup_frozen_stdlib), so every bundled
        # file would lie under a stdlib root: no path there says which of the
        # two a file is. _located's loader arm still waives what the interpreter
        # binary itself carries. Truthiness, as multiprocessing.spawn reads it:
        # PyInstaller and cx_Freeze set the flag to True, py2exe to a string
        # ("console_exe", "windows_exe" or "dll").
        return None
    if _within(path, _install_roots()):
        return False
    # The roots are sorted, so the first match is the outermost and the part
    # below it the longest: the strictest reading of _INSTALL_DIR_NAMES. Case
    # folded because normcase is the identity on posix, and a macOS filesystem
    # is case-insensitive.
    for root in _stdlib_roots():
        if _within(path, (root,)):
            below = path[len(root) + 1 :].lower().split(os.sep)
            return _INSTALL_DIR_NAMES.isdisjoint(below)
    return False


def _located(module: object, name: str, stdlib: bool) -> bool | None:
    """
    Shipped here (True), shipped elsewhere (False), or neither (None), for a
    sys.modules entry, which need not be a module. None covers no ``__file__``
    and no known loader, a ``__file__`` that ``_classify_file`` cannot place
    (relative, non-string, NUL, or any stdlib path in a frozen app) with no
    known loader, and a read below that raised; ``_is_library_module`` refuses
    None for a top-level name and keeps the package's waiver for an inner one,
    so an unplaceable inner ``__file__`` counts as no evidence there. A
    ``__file__`` that ``_classify_file`` can place decides, and only then is
    the loader read: with importlib on disk, importlib/__init__.py gives
    importlib._bootstrap a
    stdlib ``__file__`` next to a FrozenImporter whose table knows it only as
    _frozen_importlib (with importlib frozen too it has no ``__file__``, and
    the loader arm answers False under the dotted name: a lost waiver, not a
    wrong drop). The built-in and frozen arms answer on the caller's ``name``
    alone, not the module's ``__name__``, under either ``stdlib``: both importers
    precede the path finder, so no sys.path entry can shadow such a module,
    and its code is fixed by the interpreter binary, which is what either
    waiver needs. The ``stdlib=False`` case is an embedding that registers
    torch._C through PyImport_AppendInittab while torch's Python files stay on
    disk, so ``_torch_roots`` is non-empty and ``_is_library_module`` does not
    waive torch on its name.
    """
    # The module dict rather than getattr: a class attribute says nothing about
    # where the module came from (torch.ops is a ModuleType subclass carrying
    # the class's relative "_ops.py" as its __file__), and on an entry whose
    # dict is missing one of these dunders getattr would fall through to a PEP
    # 562 module __getattr__, user code a lint must not run (a raise is caught
    # below, its side effects are not). And object's read of the dict, not the
    # module's: importlib.util.LazyLoader leaves a _LazyModule whose
    # __getattribute__ executes the module body on ANY attribute read, __dict__
    # included, while its dict already carries the seeded __file__, __spec__ and
    # __loader__. That read defeats a __getattr__ or a __getattribute__
    # override, not a __dict__ descriptor defined on the type. sys.modules can
    # hold any object, so such a descriptor, and spec.loader on a hand-rolled
    # spec, are user code, and are caught, as is the AttributeError object
    # itself raises for a slotted entry with no __dict__ at all. The try also
    # spans _classify_file and the loader arms, so a raise out of the
    # classifier's own gates or out of FrozenImporter.find_spec (ImportError on
    # an excluded or invalid frozen table entry) lands here as None rather than
    # escaping a lint.
    try:
        attrs = object.__getattribute__(module, "__dict__")
        file = attrs.get("__file__")
        # Only a str is classifiable: a bytes or PathLike __file__ would pass
        # isabs and raise from the NUL check instead.
        if isinstance(file, str):
            verdict = _classify_file(file, stdlib)
            if verdict is not None:
                return verdict
        # The loader rather than spec.origin: both importers' find_spec pass
        # origin=cls._ORIGIN to spec_from_loader, so the two never disagree,
        # and the class is the stronger signal. A __loader__ in the dict skips
        # the spec's loader, the only user-code half of this; compared with None
        # rather than for truth, so no __bool__ of user code runs. A hand-made
        # ModuleType has the None its __init__ seeds and falls through (an
        # imported module's dict carries spec.loader instead, copied in by
        # _init_module_attrs).
        loader = attrs.get("__loader__")
        if loader is None:
            loader = getattr(attrs.get("__spec__"), "loader", None)
        # Both arms compare by identity: under == a __loader__ whose __eq__
        # answers true for anything would take the waiver.
        if loader is importlib.machinery.BuiltinImporter:
            # Statically linked, and BuiltinImporter precedes PathFinder on
            # sys.meta_path, so on import no file on sys.path is reachable
            # under this name; a spec assigned straight into sys.modules is
            # taken at its word. The inittab is keyed on the full dotted name.
            return name in sys.builtin_module_names
        if loader is importlib.machinery.FrozenImporter:
            # frozen also precedes the path finder
            return importlib.machinery.FrozenImporter.find_spec(name) is not None
    except Exception:
        return None
    return None  # namespace package, or exec'd in memory with no loader


def _is_library_module(module_name: str | None) -> bool:
    """
    Owned by torch or the stdlib, so config on the serving machine does not
    choose between implementations. NB this trusts the OWNER, not the binding:
    a third party that monkeypatches ``F.gelu`` at import time still diverges,
    and that is called out in ``_is_risky_drop``'s KNOWN GAP.

    sys.stdlib_module_names is a list of NAMES, and a waiver keyed on a name is
    a collision away from being wrong: graphlib, queue, code and distutils are
    all stdlib names a third party can and does supply. Worse, the name can be
    right and the code still not be the stdlib's -- in a default setuptools
    install ``import distutils`` gets site-packages/setuptools/_distutils, and
    SETUPTOOLS_USE_DISTUTILS picks which one, which is exactly the
    config-chooses-the-implementation shape this lint exists to catch. So the
    module has to RESOLVE to code shipped with the interpreter: located under a
    stdlib root and not under an install root (purelib nests inside stdlib in
    conda and inside platstdlib in a venv, so the exclusion is what does the
    work), or with no file at all because it is built in or frozen, which the
    path finder cannot shadow. That is required of the TOP-LEVEL name: not
    imported, or without location evidence (a namespace package has none), it
    is untrusted. An imported inner name only has to not be located ELSEWHERE:
    the package it was found in is already located, and a real submodule can
    carry no evidence of its own: pyexpat.errors, which pyexpat's C init
    registers with neither ``__file__`` nor ``__spec__``, and torch.ops, a
    ModuleType subclass whose ``__file__`` is a class attribute the module dict
    never sees. The torch arm alone has an escape hatch: a frozen torch gives
    ``_torch_roots`` no directory to anchor to, and then every torch name is
    waived on its name, with no location evidence at all.
    """
    if module_name is None:
        return False
    top = module_name.partition(".")[0]
    if top == "torch":
        if not _torch_roots():
            return True
        stdlib = False
    elif top in sys.stdlib_module_names:
        stdlib = True
    else:
        return False
    root = sys.modules.get(top)
    if root is None or _located(root, top, stdlib) is not True:
        return False
    parts = module_name.split(".")
    for i in range(2, len(parts) + 1):
        name = ".".join(parts[:i])
        module = sys.modules.get(name)
        # Unimported or unlocatable, an inner name has nothing to check, and
        # the package it would have to be found in has already been located.
        if module is not None and _located(module, name, stdlib) is False:
            return False
    return True


def _defined_where_read(
    value: object, global_name: str, user_stack: traceback.StackSummary | None
) -> bool:
    """
    Whether ``global_name`` is a def or class statement of that name living in
    the file that read it.

    ``global_name`` is the read's ``GlobalSource.global_name``; the
    ``GuardFilterEntry.name`` spelling keeps its ``G[...]`` wrapper and is not
    it. The reading file is the OUTERMOST frame of the guard's ``user_stack``:
    a bare GlobalSource denotes the root frame's globals (an inlined frame with
    other globals reads through an ``__import_`` alias or an
    ``___unnamed_scope`` dict entry instead), while the stack is stamped at
    first use, so its innermost frame can be a helper inlined from another
    file. A def bound under its own name in the reading file is the one binding
    the inlined-source checksum of that file covers. ``from impl_a import op``
    takes only a conditional import in the reader, which no checksum sees, and
    ``act = _impl_a if cfg.fast else _impl_b`` is a slot however close to home
    the def is; so are ``op = Ops.op`` and a def returned by a factory, which is
    why the name compared is ``__qualname__``, backed by the code object's own
    name: functools.wraps copies ``__qualname__`` onto a wrapper but cannot
    forge its ``co_qualname``, so a same-file ``wraps`` decorator a flag turns
    on is a slot in both arms (before 3.11 only ``co_name`` exists, so a
    wrapper def named after what it wraps slips through there). Only a plain
    function or a class is judged; a bound method or any other proxy that
    forwards ``__qualname__`` and ``__code__`` is refused before an attribute
    is read, which also keeps a proxy that answers reads by raising, such as
    ``torch.classes.<ns>``, out of the value slot. The file is read off the
    code object, not off ``__module__``: functools.wraps copies ``__module__``
    along with ``__name__`` and ``__qualname__``, so ``op = torch.compile(op)``
    behind a flag claims the reader's module while its code lives in
    eval_frame.py. The object does not tell that shape from an unconditional
    cross-file decorator, so ``@torch.no_grad()`` on a same-file def is not
    waived either.
    A class has no code object, and its ``__module__`` is no better: namedtuple
    and ``type()`` stamp it from the calling frame (make_dataclass does from
    3.12) under a BARE ``__qualname__`` (a def or class statement inside the
    factory would carry ``factory.<locals>.``), so a ``namedtuple("Point", ...)``
    called in the reader looks exactly like a class statement -- the frame
    stamped is the caller's, so the collision needs a factory called from the
    reading file, a cross-file ``lib.make_point()`` coming back stamped ``lib``.
    Its methods can tell: a class statement compiles its defs in its own file
    under its own ``__qualname__`` prefix, so a class is waived when at least one
    function in its own ``__dict__``, stored under key ``k`` with
    ``__qualname__`` ``Cls.k``
    (a staticmethod or classmethod is unwrapped through ``__func__`` and a
    property through ``fget``, by type rather than by ``getattr``, which a proxy
    attribute such as ``torch.classes.<ns>`` answers by raising; a
    cached_property keeps its function under ``.func`` and does not count), was
    compiled in the reading file. A function attached afterwards keeps its bare
    qualname, and one attached through functools.wraps keeps its code object's
    own name, so an imported class the reader extends (``Point.extra =
    _extra``) or patches (``Point.norm = wraps(Point.norm)(_norm)``) and a
    factory fed same-file methods (``type(name, bases, {"area": _area})``,
    ``make_dataclass(..., namespace=...)``) are refused, and ``class Marker:
    pass`` fails closed. So does a class statement whose only functions are
    generated: a fields-only ``@dataclass``'s and a ``NamedTuple``'s are defs
    of a factory (dataclasses' ``__create_fn__``, ``namedtuple``), so their
    code objects' own qualname carries the factory's ``<locals>.`` prefix (on
    3.10, where only ``co_name`` exists, the ``<string>`` or stdlib file they
    compile in refuses them instead), and an ``Enum``'s arrive in the subclass
    ``__dict__`` under ``Enum.`` qualnames the key rule refuses; so a plain
    config dataclass read as a global is reported. The one function the
    compiler itself puts in a class ``__dict__``, the PEP 649 annotate function
    3.14 stores for an annotated class body, compiles in the reading file, but
    under key ``__annotate_func__`` with ``__qualname__`` ``Cls.__annotate__``,
    so the key rule refuses it and the verdict is the same on every version;
    both annotate keys are skipped outright as well, against a version that
    stores it under its own name. Nothing else without a code object is
    waived, because a C-implemented wrapper such as functools.lru_cache claims
    the reader's module the same way. A ``co_filename`` is not always a path:
    an exec records ``<string>``, a REPL ``<stdin>``, and ``_norm`` would
    resolve either against the cwd, so a def exec'd under ``<string>`` and read
    from an exec-generated frame would collide with it and be waived (on 3.10 a
    fields-only dataclass too, whose ``__init__`` compiles in ``<string>``
    under a ``co_name`` that cannot tell it from a class statement's def). Only
    absolute filenames on both sides compare; anything else fails closed. What this
    cannot see is a same-name fork inside the reading file -- ``try: from x
    import impl as op`` / ``except ImportError: def op``, or a class statement
    under the same ``if`` -- which binds a different def per machine under one
    checksum; that is the conditional-bind KNOWN GAP recorded in
    ``_is_risky_drop``.
    """
    if not user_stack or not isinstance(value, (type, types.FunctionType)):
        return False
    if value.__qualname__ != global_name:
        return False

    # functools.wraps copies __qualname__ but not the code object's own name:
    # co_qualname from 3.11, before that co_name, its last component only.
    def compiled_as(fn: types.FunctionType, qualname: str) -> bool:
        if sys.version_info >= (3, 11):
            return fn.__code__.co_qualname == qualname
        return fn.__code__.co_name == qualname.rpartition(".")[2]

    if isinstance(value, type):
        # 3.14 stores the PEP 649 annotate function under __annotate_func__
        # with qualname Cls.__annotate__, which the key rule refuses; the skip
        # covers a version that stores it under its own name.
        skip = ("__annotate__", "__annotate_func__")
        files: list[str] = []
        for key, attr in vars(value).items():
            if isinstance(attr, (staticmethod, classmethod)):
                attr = attr.__func__
            elif isinstance(attr, property):
                attr = attr.fget
            if not isinstance(attr, types.FunctionType) or key in skip:
                continue
            qualname = f"{global_name}.{key}"
            if attr.__qualname__ == qualname and compiled_as(attr, qualname):
                files.append(attr.__code__.co_filename)
    else:
        files = [value.__code__.co_filename] if compiled_as(value, global_name) else []
    read = user_stack[0].filename
    if not os.path.isabs(read):
        return False
    try:
        here = _norm(read)
        return any(os.path.isabs(f) and _norm(f) == here for f in files)
    except ValueError:  # an embedded NUL, which posixpath.realpath lets through
        return False


def _dynamo_alias_module(global_name: str) -> types.ModuleType | None:
    """
    The module behind an ``__import_a_dot_b`` alias, mirroring the ordinary
    branch of import_source; a torch_package module is aliased without the
    prefix and comes back None here, which fails closed.

    The OutputGraph's import_sources table is authoritative, but a guard entry
    does not carry it; unmangling collides only for a module whose name
    contains ``_dot_`` (``pkg.sub_dot_mod`` is aliased as
    ``__import_pkg_dot_sub_dot_mod``, which comes back as ``pkg.sub.mod`` when
    that module is loaded too), and that collision fails open (the callers judge
    the module returned).
    """
    if not global_name.startswith(_IMPORT_ALIAS_PREFIX):
        return None
    tail = global_name[len(_IMPORT_ALIAS_PREFIX) :]
    return sys.modules.get(tail.replace("_dot_", "."))


def _module_namespaces(
    entries: Sequence[GuardFilterEntry],
) -> dict[str, types.ModuleType]:
    """
    Sources holding a module whose binding config cannot repoint, mapped to the
    module itself. Dynamo guards every module it walks through, so the path
    down to ``F.gelu`` is guarded module by module, which is what lets an
    attribute read be recognised as coming off a namespace rather than off an
    object a config could have swapped. The module comes back with the name
    because whether a read off a namespace is safe depends on which module it
    is -- see ``_is_risky_drop``.

    TRUSTED is the load-bearing half and is deliberately narrow. A module is
    that if torch or the stdlib owns it, if it is bound under its own name --
    ``import mypkg``, and the ``__import_x`` alias Dynamo installs to reach an
    inlined function's own globals -- or if it is an attribute of a trusted
    module under a name that module already owns: its own ``__name__`` (a plain
    ``import own_sub`` inside the parent) or the parent's plus the attribute
    (``from . import sub``, and ``import mypkg.layers``, which Dynamo guards as
    ``G['mypkg'].layers``). An ALIASED user module is none of those:
    ``if flag: import impl_b as impl`` picks what ``impl.op`` resolves to per
    machine, and so does the same alias spelled ``from . import impl_b as
    impl`` in a package __init__. Inheriting the parent's trust without
    checking the name is what let that shape through before.

    Library ownership is trusted under ANY binding, ``import torch.nn.functional
    as F`` included; the price, taken deliberately because flagging ``F`` would
    flag every model, is that an alias config picks between two torch modules
    is waived too (see ``_is_risky_drop``'s KNOWN GAP). A config module is the
    one namespace whose bindings config chooses by definition, so it is never
    trusted, whoever owns it and however it is reached (a recovered
    ``__import_x`` alias included). Keys are source names, and the consumer
    looks a read's ``source.base.name`` up exactly, never by prefix.
    """
    modules = {
        e.orig_guard.originating_source.name: (e.orig_guard.originating_source, e.value)
        for e in entries
        if isinstance(e.value, types.ModuleType)
        and isinstance(_source_root(e.orig_guard.originating_source), GlobalSource)
    }
    # Dynamo guards the attributes it reads off an import alias but never the
    # bare alias, so a real model produces G['__import_torch'].Tensor with no
    # module-valued entry for G['__import_torch'] to anchor it. The alias name
    # encodes its module, so recover it rather than treating torch.Tensor as a
    # config-swappable slot.
    for e in entries:
        root = _source_root(e.orig_guard.originating_source)
        if isinstance(root, GlobalSource) and root.name not in modules:
            aliased = _dynamo_alias_module(root.global_name)
            if aliased is not None:
                modules[root.name] = (root, aliased)
    trusted: dict[str, bool] = {}

    def is_trusted(name: str) -> bool:
        if name in trusted:
            return trusted[name]
        found = modules.get(name)
        ok = False
        if found is not None:
            source, module = found
            if isinstance(module, ConfigModule):
                ok = False
            elif _is_library_module(module.__name__):
                ok = True
            elif isinstance(source, GlobalSource):
                ok = (
                    source.global_name == module.__name__
                    or _dynamo_alias_module(source.global_name) is module
                )
            elif isinstance(source, AttrSource):
                outer = modules.get(source.base.name)
                ok = (
                    outer is not None
                    and is_trusted(source.base.name)
                    and module.__name__
                    in (source.member, f"{outer[1].__name__}.{source.member}")
                )
        trusted[name] = ok
        return ok

    return {name: module for name, (_, module) in modules.items() if is_trusted(name)}


def _reads_a_builtin(source: Source, value: object) -> bool:
    """
    ``len`` or ``sorted`` reached the ordinary way, through the builtins dict
    Dynamo installs to resolve them. That dict is the frame's live
    ``builtins.__dict__``, not a table of the real builtins, so a shim's
    ``builtins.py2_sum = sum`` is a binding under it that another machine's
    shim can point elsewhere; only a builtin ``builtins`` itself owns, read
    under its own name, is waived (``IOError`` and ``EnvironmentError``,
    CPython's aliases of ``OSError``, fail closed), and only one CPython built:
    functools.wraps copies ``__module__`` and ``__name__`` onto ``builtins.sum =
    wraps(sum)(logged_sum)``, a Python function whose CLOSURE_MATCH is dropped,
    and a class statement exec'd with the builtins namespace as its globals (or
    handed ``__module__ = "builtins"``) claims the module outright, so the value
    must be a builtin function or a static type as well, one carrying
    ``Py_TPFLAGS_IMMUTABLETYPE``, which a class statement or a ``type()`` call
    does not carry. The flag is read through ``type``'s own descriptor, so a
    metaclass can neither shadow it nor make the read raise, and a static
    type's ``__module__`` is derived from its C name; a builtin function's
    ``__module__`` is a writable member, though, so ``builtins.getcwd =
    os.getcwd`` plus ``os.getcwd.__module__ = "builtins"`` is waived -- evidence
    rather than proof on that branch, which an advisory lint over a
    dropped-guard set does not defend against. Every callable in
    ``builtins.__dict__`` is one of the two kinds apart from the
    ``_sitebuiltins`` objects, instances of neither, and beside the aliases
    (``WindowsError`` is a third on Windows) three of them fail closed:
    ``open``, the one builtin function ``builtins`` does not own (its
    ``__module__`` is ``_io``, ``io`` before 3.12, so a dropped guard on one of
    the most mainstream builtins here is reported), and the heap types
    ``ExceptionGroup`` (3.11+) and ``__loader__``, the latter refused under a
    name that is not its own as well. The exposure is
    narrow either way: a registered builtin is id-matched into a BUILTIN_MATCH
    the serializer keeps, so only a deregistered, polyfilled one (``sum``,
    ``enumerate``, ``all``, ``any``) or a shim reaches the dropped set this
    lint examines.

    A builtin parked in a slot -- ``self.act = abs``, straight out of an
    ACT2FN-style table -- is a slot like any other, so this deliberately keys
    on where the read comes FROM rather than on who owns the value.
    """
    return (
        isinstance(source, DictGetItemSource)
        and isinstance(source.base, GlobalSource)
        and source.base.global_name.startswith(_BUILTINS_DICT_PREFIX)
        and (
            isinstance(value, types.BuiltinFunctionType)
            # Py_TPFLAGS_IMMUTABLETYPE: a static type CPython built, not a
            # class statement or type() call, whose __module__ is writable. Read
            # through type's descriptor, past any metaclass shadowing __flags__.
            or (
                isinstance(value, type)
                and bool(vars(type)["__flags__"].__get__(value) & (1 << 8))
            )
        )
        and _owning_module(value) == "builtins"
        and getattr(value, "__name__", None) == source.index
    )


def _is_risky_drop(
    entry: GuardFilterEntry, namespaces: dict[str, types.ModuleType]
) -> bool:
    """
    Whether losing this identity guard can plausibly change results.

    Intersect the binding SITE with who owns the value; either test alone is
    wrong. Site alone: ``self.act = getattr(F, cfg.activation)`` and
    ``self.act = cfg.act_fn`` are the same swappable slot, so calling the first
    benign because ``F.gelu`` is torch-owned waves through the exact divergence
    this check exists for -- capture gelu, serve silu, get the gelu graph and no
    error. Ownership alone: ``if flag: import impl_b as impl`` then ``impl.op``
    is a read off a module namespace exactly like ``F.gelu``, and the module is
    user code an env var chose; so is ``self.act = abs``, where the value is a
    builtin nothing can repoint but the attribute holding it is a slot. The site
    survives the name stripping that makes source spelling useless -- a guard on
    ``self.act`` arrives as ``'self.act'`` -- because the structured source is
    still on the guard.

    For a capture-here / serve-there deployment the concern is not in-process
    rebinding but DIVERGENCE: the serving machine runs the same source but picks
    a different object because config, a flag, or an env var differs. Three
    bindings are waived -- a builtin read the ordinary way (see
    ``_reads_a_builtin``), a read off a TRUSTED namespace (see
    ``_module_namespaces``) that torch or the stdlib owns or that owns a def
    statement of that name, and a global bound to a def of that same name when
    torch or the stdlib owns the def or it lives in the file doing the reading.
    Both def-name tests compare ``__qualname__``, as ``_defined_where_read``
    does, so a def lifted off a class or returned by a factory is a slot. The
    rest are slots whose occupant config chooses: instance attributes, closure
    cells, aliased imports, cross-module ``from x import op``, registry
    lookups.

    Trusting a namespace is not trusting everything read off it. ``F.gelu`` is
    waived because torch owns torch.nn.functional and there is only one of it;
    ``own_helpers.call`` is waived because own_helpers owns a def of that same
    name, subject to the gap below. ``mypkg.op`` re-exported from
    ``mypkg.impl_b``, ``dispatch.op``, ``own_helpers.act`` bound to some other
    def, ``own_helpers.op`` bound to a staticmethod lifted off a class, and
    ``mypkg.impl.op`` where ``mypkg/__init__`` did ``from . import impl_b as
    impl`` are not waived: the import or assignment that chose the
    implementation lives in a file the inlined-source checksum never sees, so
    capture and serve can disagree with every other rail passing.
    ``test_risky_drop_decision_table`` in test_precompile_package.py pins these
    shapes and every other one found so far.

    KNOWN GAP, and it is a wrong-answer one. EVERY waiver above judges the
    object capture happened to bind, not the statement that bound it, so any
    name bound CONDITIONALLY is waived whenever the branch taken on the capture
    machine is one of the waived shapes. This is not specific to the def-name
    arm and it is not limited to the file being read:

    - def-name arm. ``if HAVE_FAST: from fastops import gelu`` / ``else: from
      torch.nn.functional import gelu``, captured without the flag, drops
      ``G['gelu']`` and reports nothing; a serving machine that has fastops
      runs torch's gelu instead, with no error. A def the reading file itself
      redefines under an ``if`` is the same shape.
    - namespace-owns-the-value arm. A module that binds a name under an ``if``
      and is read as a namespace by an ordinary ``import mod`` elsewhere is
      also waived, because at capture time the module really does own whichever
      def the branch produced. The reading file binds nothing conditionally,
      so it looks covered and is not.
    - library-namespace arm, and this one needs no conditional at all. The
      waiver trusts the owner, not the binding, so a third party that rebinds a
      torch or stdlib attribute -- ``F.gelu = _fast_gelu`` executed at import
      by a package that happens to be installed on the serving host -- is
      waived even though the model itself reads ``F.gelu`` unconditionally.
      ``functools.wraps(F.gelu)(user_fn)`` reaches the same waiver by a
      different route, since it copies ``__name__`` and ``__module__`` off the
      torch function it wraps. So does an alias config picks between two torch
      modules: ``F`` bound to torch.nn.functional or torch._refs.nn.functional
      is trusted either way, and ``F.gelu`` names a different function.

    An ``allow_in_graph`` function passes too, and Dynamo traces it opaquely so
    the inlined-source checksum never covers it either. Nothing at capture time
    distinguishes a conditional bind from an unconditional one -- only the
    resulting object is visible -- so this is a limit of the approach rather
    than a missing check. ``dropped_guards`` is the authoritative list; this
    predicate is a lint over it, not a proof of safety.
    """
    source = entry.orig_guard.originating_source
    value = entry.value
    stack = entry.orig_guard.user_stack
    if _is_dynamo_synthesized(source):
        return False
    if source.name in namespaces:
        return False
    if _reads_a_builtin(source, value):
        return False
    if not entry.has_value:
        return True  # nothing to judge ownership by
    if isinstance(source, AttrSource):
        namespace = namespaces.get(source.base.name)
        if namespace is not None:
            return not (
                _is_library_module(namespace.__name__)
                or (
                    _owning_module(value) == namespace.__name__
                    and getattr(value, "__qualname__", None) == source.member
                )
            )
    if (
        isinstance(source, GlobalSource)
        and getattr(value, "__name__", None) == source.global_name
    ):
        return not (
            _is_library_module(_owning_module(value))
            or _defined_where_read(value, source.global_name, stack)
        )
    return True


# The guards that pin a Python value by equality. CONSTANT_MATCH is the front
# door: it delegates a bool to BOOL_MATCH, None to NONE_MATCH, a code object to
# ID_MATCH and everything else -- ints included -- to EQUALS_MATCH, and it is
# the only guard method that derives into another one of these, so a slot's
# top-level guard type is enough here. CONSTANT_SUBCLASS_MATCH pins the base
# value of an int/float/str subclass argument; the two iterator guards pin an
# iterator argument's exact position. Length and key-set guards
# (SEQUENCE_LENGTH, TUPLE_ITERATOR_LEN, MAPPING_KEYS_CHECK) pin a container's
# structure rather than a value and are deliberately not counted; the set keys
# on guard type alone, so an EQUALS_MATCH installed on a container argument
# itself (a dict_keys or a frozenset of torch ops, variables/builder.py) IS
# counted, its contents being the value the artifact then serves only for.
_VALUE_EQUALITY_GUARD_TYPES = frozenset(
    {
        "CONSTANT_MATCH",
        "CONSTANT_SUBCLASS_MATCH",
        "COUNT_ITERATOR_MATCH",
        "EQUALS_MATCH",
        "RANGE_ITERATOR_MATCH",
    }
)


def _pins_a_value(guard_type: str, name: str) -> bool:
    """
    Whether this kept guard makes the artifact serve only the value it saw.

    Two things have to line up, and keying on either one alone is wrong.

    The guard has to be a value-equality one. TENSOR_MATCH, SHAPE_ENV and the
    global-state guards are what every capture has and they generalize fine --
    a TENSOR that crosses a graph break gets TENSOR_MATCH on a ``___stackN``
    source and is emphatically not a pin.

    And the source has to be a BARE name -- a plain local of some traced frame,
    or the ``___stackN`` Dynamo gives a value crossing a graph break. Anything
    dotted or subscripted (``self.eps``, ``model._modules['ln'].eps``,
    ``G['CFG'].width``) is reached THROUGH an argument rather than being one,
    which is where model config lives: every LayerNorm and Dropout contributes
    a CONSTANT_MATCH there, so counting those would flag every model and make
    the field noise. The EMPTY source of a guard checked against no source
    (``GuardFact.source`` for SHAPE_ENV, GLOBAL_STATE) is not a name either.

    KNOWN GAP: a constant inside a container argument is guarded on a
    subscripted source (``dims[0]`` for ``x.sum(dim=[0])``) and is not counted.
    ``kept_guards`` is the authoritative list; this is a lint over it.
    """
    return (
        bool(name)
        and guard_type in _VALUE_EQUALITY_GUARD_TYPES
        and not any(c in name for c in ".[")
    )


# Object addresses differ every run, so they are scrubbed from rendered guard
# facts. Keep these anchored to the call shapes that carry addresses: a bare
# \b\d{9,}\b also eats a user constant (a dict key, a slice bound), so two
# variants guarding different values render the same fact and invent an
# invariant neither holds.
_OBJ_ID = re.compile(r"(?<=, )\d+(?=\), type=)")
_SAVED_HOOK_IDS = re.compile(r"(?<=top_saved_tensors_hooks ids == )\(\d+(?:, \d+)*\)")
# Dynamo appends a per-process counter to the builtins dict it installs, so the
# same guard reads __builtins_dict___6 in one compilation and ___8 in the next.
# Of the globals Dynamo mints, only the three families in
# aot_compile._MINTED_GLOBAL_PREFIXES can root a serializable guard: this one and
# the two install_global_by_id shapes the pattern below covers. __compiled_fn_*
# and __resume_at_* are codegen-only LOAD_GLOBAL targets, never guard subjects.
_DYNAMO_COUNTER = re.compile(re.escape(_BUILTINS_DICT_PREFIX) + r"_\d+")
# OutputGraph.install_global_by_id names a global "<prefix>_<id(value)>_c<n>",
# so a guard reading one carries BOTH an address and a compile counter inside
# an identifier, where neither pattern above can see it. Real models reach this
# -- transformers' Qwen2 installs three -- and the report then differs run to
# run, which is exactly what the "commit and diff" contract rules out. The
# prefix can be empty (torch itself is installed as "_<id>_c<n>"), so the digit
# width is the anchor: it is what keeps a user identifier such as w_1_c2 intact.
_DYNAMO_GLOBAL_BY_ID = re.compile(r"_\d{9,}_c\d+\b")


def _normalize(text: str) -> str:
    text = _SAVED_HOOK_IDS.sub("(<ids>)", text)
    text = _DYNAMO_GLOBAL_BY_ID.sub("_<id>_c<n>", _OBJ_ID.sub("<id>", text))
    return _DYNAMO_COUNTER.sub(_BUILTINS_DICT_PREFIX + "_<n>", text)


def _render_code(code_list: Sequence[str] | None) -> tuple[str, ...]:
    return tuple(_normalize(part) for part in (code_list or ()))


def _hash_text(text: str) -> str:
    return hashlib.sha256(text.encode()).hexdigest()[:12]


# Guards whose check IS object identity, directly or through a derived guard,
# which is the same test default_guard_filter_fn drops on.
_IDENTITY_GUARD_TYPES = frozenset(
    CheckFunctionManager.UNSUPPORTED_SERIALIZATION_GUARD_TYPES
)


# Ellipsis and NotImplemented repr by name, so they are as stable as a literal.
_STABLE_CONST_TYPES = (
    str,
    int,
    float,
    complex,
    bytes,
    bool,
    type(None),
    type(Ellipsis),
    type(NotImplemented),
)


def _stable_consts(consts: tuple[object, ...]) -> tuple[object, ...]:
    """
    co_consts reduced to the part that reprs the same in every process.

    A nested code object reprs with its ADDRESS, so it cannot go into a digest
    that ends up in a file meant to be committed and diffed. Containers are
    filtered recursively rather than dropped whole: two lambdas differing only
    in a tuple or frozenset constant -- ``x * (1, 2)`` against ``x * (1, 3)`` --
    are genuinely different variants, and dropping the container is what let
    them collide. A const of any other type keeps its SLOT as a type marker:
    ``x[..., 0]`` and ``x[0, ...]`` fold to one const tuple at the same index,
    so with the slot dropped they would collide the same way.
    """
    out: list[object] = []
    for c in consts:
        if isinstance(c, _STABLE_CONST_TYPES):
            out.append(c)
        elif isinstance(c, types.CodeType):
            # A nested code object reprs with its ADDRESS, so it cannot go in
            # verbatim -- but dropping it merges two lambdas that differ only in
            # a comprehension or an inner lambda, which is this same bug one
            # level down. Recurse into its own fingerprint instead.
            out.append(_code_fingerprint(c))
        elif isinstance(c, tuple):
            out.append(_stable_consts(c))
        elif isinstance(c, frozenset):
            # Sorted by repr so the digest does not inherit set iteration order.
            out.append(tuple(sorted(_stable_consts(tuple(c)), key=repr)))
        else:
            out.append(f"<{type(c).__name__}>")
    return tuple(out)


def _code_fingerprint(code: types.CodeType) -> str:
    """
    Name a code object by its body, for callables a definition site cannot tell
    apart -- an ACT2FN table written on one source line makes every lambda in it
    agree on file AND lineno.

    Everything hashed is derived from the source, so the digest is identical in
    another process. It is NOT stable across Python versions, since co_code is
    version-specific bytecode: a committed invariants file churns wholesale on
    an interpreter upgrade even with unchanged source.
    """
    return _hash_text(
        repr(
            (
                code.co_code,
                code.co_names,
                code.co_varnames,
                # LOAD_DEREF addresses a cell by INDEX, so two closures that
                # capture different variables have identical co_code and are
                # told apart only by the names they close over.
                code.co_freevars,
                code.co_cellvars,
                _stable_consts(code.co_consts),
            )
        )
    )


def _object_identity(value: object) -> str:
    """
    A stable stand-in for the id ``_normalize`` stripped.

    A qualname alone does not separate the case this exists for: an ACT2FN-style
    table whose entries are all ``<lambda>`` in one module, where two variants
    holding different entries would render identically and the CLOSURE_MATCH
    that split them would be reported as an invariant of both. So a callable is
    also named by where it is DEFINED (basename, so no checkout path) and by a
    digest of its body, both source-derived and so stable across processes.

    The discriminating part goes FIRST: truncation bounds this string, and a
    transformers lambda nested in a long module path exceeds the limit on the
    qualname alone, so a digest appended at the end would be cut off exactly on
    the names that need it most.

    Only the code object is named, not the data bound to it. Two closures from
    one factory (``make(2)`` and ``make(3)``), two functions differing only in
    ``__defaults__``, bound methods of two instances, and every
    ``functools.partial`` render the same, as do two instances of one class.
    """
    if isinstance(value, types.ModuleType):
        return f"is module {value.__name__}"
    name = getattr(value, "__qualname__", None) or getattr(value, "__name__", None)
    if isinstance(name, str):
        code = getattr(value, "__code__", None)
        where = ""
        if isinstance(code, types.CodeType):
            filename = os.path.basename(code.co_filename or "?")
            where = f"@{filename}:{code.co_firstlineno}#{_code_fingerprint(code)} "
        return _normalize(f"is {where}{_owning_module(value) or '?'}.{name}")[:160]
    return f"is a {type(value).__module__}.{type(value).__qualname__}"[:160]


# Guard types that pin an input's shape, value or kind. An invariance policy
# never drops one, and the report compares them across variants.
_SHAPE_BEARING_GUARD_TYPES = frozenset(
    {
        "BOOL_MATCH",
        "CONSTANT_MATCH",
        "CONSTANT_SUBCLASS_MATCH",
        "COUNT_ITERATOR_MATCH",
        "COW_TENSOR_MATCH",
        "DICT_CONTAINS",
        "DICT_KEYS_MATCH",
        "DICT_NOT_CONTAINS",
        "DUPLICATE_INPUT",
        "EMPTY_NN_MODULE_HOOKS_DICT",
        "EQUALS_MATCH",
        "FAKE_SCRIPT_TYPE_MATCH",
        "HASATTR",
        "LIST_REVERSEITERATOR_LEN",
        "MAPPING_KEYS_CHECK",
        "NONE_MATCH",
        "NOT_NONE_MATCH",
        "NOT_PRESENT_IN_GENERIC_DICT",
        "RANGE_ITERATOR_MATCH",
        "SEQUENCE_LENGTH",
        "SET_CONTAINS",
        "SET_NOT_CONTAINS",
        "TENSOR_MATCH",
        "TUPLE_ITERATOR_LEN",
        "TYPE_MATCH",
    }
)


# Guard types on ambient or process state that the guard leaf checks for itself
# and nothing in this module fingerprints. Never dropped, never compared.
_UNMODELLED_GUARD_TYPES = frozenset(
    {
        "AUTOGRAD_SAVED_TENSORS_HOOKS",
        "CURRENT_STREAM_MATCH",
        "DEFAULT_DEVICE",
        "DISPATCH_KEY_SET_MATCH",
        "DTENSOR_SPEC_MATCH",
        "DUAL_LEVEL",
        "FSDP_TRAINING_STATE",
        "FUNCTORCH_STACK_MATCH",
        "GLOBAL_STATE",
        "OPAQUE_OBJ_GUARD_FN_MATCH",
        "SHAPE_ENV",
        "TENSOR_SUBCLASS_METADATA_MATCH",
        "TORCH_FUNCTION_STATE",
    }
)


# Guard types whose GuardBuilder method is `pass`: the guard is a marker, and
# the check it names is made by GLOBAL_STATE's leaf. Nothing about them is
# serialized or dropped, so they never appear in a dropped-guard report --
# listing GRAD_MODE as "a precondition nothing checks" would be false, since
# GlobalStateGuard checks it on every call. Their facts ARE compared, from the
# same process state GlobalStateGuard snapshots (see _value_fingerprint).
_NOOP_GUARD_TYPES = frozenset({"DETERMINISTIC_ALGORITHMS", "GRAD_MODE"})


def _is_noop_guard_type(guard_type: str) -> bool:
    # EMPTY_NN_MODULE_HOOKS_DICT is classified shape-bearing for the config
    # where it emits a check; under skip_nnmodule_hook_guards, the default,
    # GuardBuilder emits nothing for it, so a report must not call it a
    # precondition.
    return guard_type in _NOOP_GUARD_TYPES or (
        guard_type == "EMPTY_NN_MODULE_HOOKS_DICT"
        and torch._dynamo.config.skip_nnmodule_hook_guards
    )


# The ONLY guard types the invariance policy may drop, and only when proven
# invariant across every captured variant: the identity guards the default
# filter drops anyway as unserializable, plus BUILTIN_MATCH, an identity match
# on a builtin that the default filter keeps. The four sets are a total,
# disjoint classification of GuardBuilder's guard methods, pinned by
# test_guard_policy_classification_is_total: a guard type in none of them --
# any type added to GuardBuilder after this list -- is KEPT unconditionally
# until someone classifies it, so a new value-pinning guard can never become
# silently droppable. Guards installed outside GuardBuilder (the root manager's
# DuplicateInputs and StorageOverlap exprs, the dimension-marking lambda) never
# reach the guard filter and are outside the policy as well.
_INVARIANT_DROPPABLE_GUARD_TYPES = _IDENTITY_GUARD_TYPES | frozenset({"BUILTIN_MATCH"})


def _saved_hooks_fingerprint() -> str:
    """
    Name the installed saved-tensors hooks the way the guard compares them.

    The guard stores ``tuple(map(id, hooks))`` when both hooks are fx
    GraphModules and ``None`` otherwise, so plain-Python hooks, and no hooks at
    all, are one value to it and must be one value here, or the report shows a
    'varies' line for a guard that passes either way. Inlineable hooks are
    named by their rendered graph rather than by address, since an id cannot
    go in a committed, diffable file. KNOWN TRADEOFF: two distinct GraphModules
    with identical code read as one hook set here while the guard tells them
    apart, so the report may call that guard invariant when it is not.
    """
    try:
        from torch._functorch._aot_autograd.utils import (
            saved_tensors_hooks_are_inlineable,
            top_saved_tensors_hooks,
        )

        hooks = top_saved_tensors_hooks()
        if not saved_tensors_hooks_are_inlineable(hooks):
            return "hooks=None"
        return "hooks=(" + ", ".join(_hash_text(hook.code) for hook in hooks) + ")"
    except Exception:
        # Distinct from the "" that means "the rendered code already names the
        # check": a failed read must not merge two variants.
        return "hooks=<unreadable>"


def _value_fingerprint(entry: GuardFilterEntry) -> str:
    """
    What the guard checks, when the rendered code does not say.

    TENSOR_MATCH is the case that matters: its code_list carries only the
    _dynamo_*_indices hasattr checks, while everything it really compares lives
    in the C++ leaf. Without those two specializations of one frame look
    identical and wrongly land in the intersection, so this mirrors TensorCheck
    -- python type and the full dispatch key set included, since a Parameter
    against a Tensor, a conjugated view against a plain one, or an
    inference-mode tensor against a no_grad one, splits a compilation exactly
    as dtype does. KNOWN GAP: that leaf checks nothing for a dim the compile
    made dynamic, so under ``dynamic=True`` the concrete shape here is narrower
    than the guard and a shape-generic TENSOR_MATCH is reported as varying
    rather than invariant.

    An identity guard needs one too, because ``_normalize`` strips the id its
    code renders: without a name for the object, two variants holding different
    callables at one source collapse into one fact and are reported as an
    invariant neither of them holds.

    Every other guard takes its value from its own rendered code, which names
    it, so fingerprinting it again SPLITS identical guards: TYPE_MATCH on an
    unspecialized int checks only that the int is an int, and stamping 1 on one
    variant and 2 on the next demotes a real invariant into two identical
    'varies' lines. So every branch dispatches on the guard type, never on the
    value's: the NOT_NONE_MATCH Dynamo installs on an optimizer's .grad, or a
    TYPE_MATCH on a tensor attribute, holds a tensor whose shape and dtype it
    never checks.
    """
    if entry.guard_type == "AUTOGRAD_SAVED_TENSORS_HOOKS":
        # Its code renders tuple(map(id, hooks)), which _normalize has to erase
        # or the file churns -- but erasing it alone would merge two variants
        # that differ ONLY in their hooks and report the guard that split them
        # as an invariant. Put back a discriminator derived from what the hooks
        # ARE rather than where they live, which is both stable across
        # processes and still telling.
        return _saved_hooks_fingerprint()
    if entry.guard_type == "GRAD_MODE":
        # Global-state guards carry no name, code or value, so two variants of
        # one frame that differ only in grad mode render identically and land
        # in the intersection. The filter runs in the traced frame's own state.
        return f"grad_enabled={torch.is_grad_enabled()}"
    if entry.guard_type == "DETERMINISTIC_ALGORITHMS":
        # Same as GRAD_MODE: the two fields GlobalStateGuard snapshots for it.
        warn_only = torch.is_deterministic_algorithms_warn_only_enabled()
        return f"deterministic={torch.are_deterministic_algorithms_enabled()}, warn_only={warn_only}"
    if not entry.has_value:
        return ""
    value = entry.value
    if entry.guard_type == "TENSOR_MATCH" and isinstance(value, torch.Tensor):
        # Render exactly what TensorCheck stores (notably the TLS-adjusted
        # dispatch key set, not the tensor's own) rather than reconstructing it.
        # The fact's source already names the tensor, so no name goes in.
        from .guards import convert_to_concrete_values, get_tensor_guard_code_part

        try:
            return get_tensor_guard_code_part(
                value,
                "<value>",
                convert_to_concrete_values(value.size()),
                convert_to_concrete_values(value.stride()),
                type(value),
                torch._C._dispatch_keys(value),
            )
        except Exception:
            # A subclass whose __torch_function__ refuses attribute reads got
            # here; type() is the one read that cannot raise.
            return f"type={type(value).__name__}, <unrenderable>"
    if entry.guard_type in _IDENTITY_GUARD_TYPES or any(
        d in _IDENTITY_GUARD_TYPES for d in entry.derived_guard_types
    ):
        return _object_identity(value)
    return ""


def _fact_order(fact: _GuardFact) -> tuple[str, str, str, str]:
    # value is part of the key: once the boilerplate code parts are filtered a
    # TENSOR_MATCH renders no code, so two shape specializations would otherwise
    # tie and sort unstably, making the file differ run to run.
    return (fact.source, fact.guard_type, " ".join(fact.code), fact.value)


def _wont_generalize(
    kept: set[tuple[str, str]],
    guard_sets: Mapping[tuple[str, str, int], Sequence[frozenset[_GuardFact]]],
) -> tuple[str, ...]:
    """Sources no captured variant will serve a new value for.

    A source pinned in ONE variant is not pinned for the artifact: the union of
    kept guards says "some graph equality-matched this", while what the warning
    claims is "no graph will take anything else". A frame whose other variant
    guards the same source generically -- the ordinary shape once two examples
    are captured -- serves the new value fine, and warning about it tells the
    caller to enumerate values that already work.

    Cancellation is per frame, like every comparison in this module: a bare
    name means nothing across frames, and ``___stack0`` names whatever crossed
    the break in EVERY resume frame -- a tensor in one, an ``.item()`` int in
    the next -- so a generic mention elsewhere must not erase a real pin here.
    ``GuardFact.source`` and a kept slot's name share one spelling, the
    ``GuardFilterEntry.name`` with local scope stripped (``L['x']`` -> ``x``).
    A fact whose guard the filter dropped (``enforced`` False) checks nothing,
    so its variant counts as serving the source generically, not as pinning it;
    the drop itself is what ``dropped_guards`` reports, so the case changes
    fields rather than disappearing. A variant's OWN companion guards on a
    source it pins (the SEQUENCE_LENGTH beside a dict_keys EQUALS_MATCH) are
    not a generic mention, hence the ``- here`` below.

    KNOWN GAP: "reached it without pinning it" is read as "serves other
    values", and an unspecialized int breaks that: its variant carries only a
    TYPE_MATCH on the name, and if the trace then specializes the symbol the
    ``L['scale'] == 3`` check is a SHAPE_ENV fact with an EMPTY source, so the
    variant looks generic and cancels a sibling's pin that nothing serves.
    """
    pinned = {n for t, n in kept if _pins_a_value(t, n)}
    if not pinned:
        return ()
    # A source survives if SOME frame pins it and never serves it generically;
    # a frame that does both cancels only its own pin, not another frame's.
    survivors: set[str] = set()
    for variants in guard_sets.values():
        pins: set[str] = set()
        generic: set[str] = set()
        for facts in variants:
            here = {
                f.source
                for f in facts
                if f.enforced and _pins_a_value(f.guard_type, f.source)
            }
            pins |= here
            # A variant that reached the source without pinning it is the
            # graph that serves other values.
            generic |= {f.source for f in facts} - here
        survivors |= pins - generic
    return tuple(sorted(pinned & survivors))


def _varying_guard_slots(
    guard_sets: Mapping[tuple[str, str, int], Sequence[frozenset[_GuardFact]]],
) -> frozenset[tuple[str, str]]:
    """The guard slots that actually discriminate between captured variants.

    A slot is ``(guard_type, source)``, the source as ``GuardFact.source``
    spells it: the ``GuardFilterEntry.name`` with local scope stripped
    (``L['x']`` -> ``x``). It varies when two variants of one frame
    recorded DIFFERENT facts for it, and also when it is present in some
    variants and absent in others -- a guard only one variant carries is what
    tells that variant apart, and comparing values alone would call it
    invariant and drop it. That present-in-some case is the majority of what is
    kept, not an edge. A fact is its rendered code and value; ``enforced`` says
    whether the serialized copy keeps the guard, not what it checks, so two
    variants that differ only there agree. One variant can hold several facts
    on one slot (a ``HASATTR`` per attribute name, all on the parent source),
    so what is compared across variants is each variant's SET of facts for the
    slot, never one fact against another inside a variant.

    Everything else held identically in every variant, which is what licenses a
    caller to leave it out of the serialized copy.
    """
    varying: set[tuple[str, str]] = set()
    for variants in guard_sets.values():
        seen: dict[tuple[str, str], list[frozenset[tuple[tuple[str, ...], str]]]] = {}
        for facts in variants:
            rendered: dict[tuple[str, str], set[tuple[tuple[str, ...], str]]] = {}
            for f in facts:
                slot = (f.guard_type, f.source)
                rendered.setdefault(slot, set()).add((f.code, f.value))
            for slot, facts_here in rendered.items():
                seen.setdefault(slot, []).append(frozenset(facts_here))
        for slot, per_variant in seen.items():
            if len(per_variant) != len(variants) or len(set(per_variant)) > 1:
                varying.add(slot)
    return frozenset(varying)


def _summarize(
    entry: _DynamoCacheEntry,
    *,
    dropped: set[tuple[str, str]],
    kept: set[tuple[str, str]],
    policy_dropped: set[tuple[str, str]],
    risky: set[tuple[str, str]],
    truncated: frozenset[str],
    capture_errors: Sequence[str],
    guard_sets: Mapping[tuple[str, str, int], Sequence[frozenset[_GuardFact]]],
    dropped_code: Mapping[tuple[str, str], str],
) -> PrecompileSummary:
    """Assemble the report. ``dropped_code`` maps a dropped slot to the one
    rendering the report carries for it, the caller's pick among the variants
    that dropped it; a slot without one gets no ``dropped_guard_code`` entry.

    ``bypassed`` and ``uncovered_frames`` are read off the entry, one bare
    ``co_name`` per frame, so a repeated name is two frames and both lists are
    subsets of ``frames`` by construction. Uncovered is the coverage gap: the
    frame entered Dynamo (``has_compile_id``) and holds no guarded code, and was
    not bypassed. ``install()`` ``skip_code()``s a superset, every entry that is
    not bypassed and has no guarded codes whether or not it entered Dynamo, so a
    generated-but-never-executed resume entry is skipped there and is not a gap
    here. ``backend_graphs`` counts the backend ids of the entries that are not
    bypassed, the ones ``install()`` loads: a save-time bypass
    (``PrecompileCacheEntry.from_cache_entry``, backend artifact missing) marks
    the entry and leaves its ids in place. ``truncated`` comes from the compile
    path, which sees a frame hit the limit once and records it as ``co_name
    (filename:firstlineno)``, so that set cannot merge two frames.
    """
    return PrecompileSummary(
        frames=len(entry.codes),
        resume_functions=sum(1 for c in entry.codes if c.install_to_global),
        guarded_codes=sum(len(c.guarded_codes) for c in entry.codes),
        backend_graphs=len(
            {b for c in entry.codes if not c.bypassed for b in c.backend_ids}
        ),
        bypassed=tuple(c.python_code.co_name for c in entry.codes if c.bypassed),
        truncated=tuple(sorted(truncated)),
        uncovered_frames=tuple(
            c.python_code.co_name
            for c in entry.codes
            if c.has_compile_id and not c.guarded_codes and not c.bypassed
        ),
        wont_generalize=_wont_generalize(kept, guard_sets),
        dropped_guards=tuple(sorted(dropped)),
        dropped_guard_code=tuple(
            (gtype, name, dropped_code[(gtype, name)])
            for gtype, name in sorted(dropped | policy_dropped)
            if (gtype, name) in dropped_code
        ),
        kept_guards=tuple(sorted(kept)),
        risky_dropped_guards=tuple(sorted(risky)),
        policy_dropped_guards=tuple(sorted(policy_dropped)),
        capture_errors=tuple(capture_errors),
    )


class PrecompileSession:
    """A caller-driven multi-graph capture in progress.

    Enter it to get the callable to exercise, call that with real inputs inside
    the block, and :meth:`summary` reports what the calls covered. The calls run
    under ``_capture_config``, so every backend graph reaches the artifact as a
    bundled AOTAutograd entry, and under the package's guard filter, which this
    session wraps to record what it kept and dropped for the
    :class:`PrecompileSummary`. Rendering the artifact is the next commit's.
    """

    def __init__(
        self,
        fn: Callable[..., object],
        *,
        backend: str = "inductor",
        guard_filter_fn: Callable[[Sequence[GuardFilterEntry]], Sequence[bool]]
        | None = None,
        recompile_limit: int = 256,
        dynamic: bool | None = None,
    ) -> None:
        self._fn = fn
        self._backend = backend
        self._recompile_limit = recompile_limit
        self._dynamic = dynamic
        self._custom_guard_filter = guard_filter_fn is not None
        self._dropped_guards: set[tuple[str, str]] = set()
        self._kept_guards: set[tuple[str, str]] = set()
        self._risky_dropped_guards: set[tuple[str, str]] = set()
        self._dropped_guard_code: dict[tuple[str, str], str] = {}
        # (co_name, co_filename, co_firstlineno) -> one fact set per compilation
        self._guard_sets: dict[tuple[str, str, int], list[frozenset[_GuardFact]]] = {}
        self._capture_errors: list[str] = []
        self._backend_artifacts: dict[_BackendId, Any] = {}
        self._package = CompilePackage(fn)
        self._guard_filter_fn = self._recording_filter(
            default_guard_filter_fn if guard_filter_fn is None else guard_filter_fn
        )
        self._compiled: Callable[..., object] | None = None
        self._entered = False
        self._finished = False

    def _recording_filter(
        self,
        inner: Callable[[Sequence[GuardFilterEntry]], Sequence[bool]],
    ) -> Callable[[Sequence[GuardFilterEntry]], Sequence[bool]]:
        """Record what the filter kept and dropped, per compilation, for the summary.

        A dropped guard does not fail at serving time; it silently widens what a
        graph is reused for, so the set has to be inspectable. One filter call is
        one compilation, and the package knows which frame is being compiled.
        """

        def filter_fn(entries: Sequence[GuardFilterEntry]) -> Sequence[bool]:
            decisions = list(inner(entries))
            # A drop the default filter would not have made is risky by
            # construction: nothing here can say what the caller gave up.
            default_kept = (
                default_guard_filter_fn(entries)
                if self._custom_guard_filter
                else decisions
            )
            namespaces = _module_namespaces(entries)
            global_state_kept = any(
                keep and e.guard_type == "GLOBAL_STATE"
                for keep, e in zip(decisions, entries)
            )
            facts: set[_GuardFact] = set()
            for keep, by_default, entry in zip(decisions, default_kept, entries):
                # One spelling for every slot and fact, so the dropped, risky and
                # kept sets and the per-variant facts compare as equals.
                slot = (entry.guard_type, _normalize(strip_local_scope(entry.name)))
                # A no-op type's check, where it has one, is GLOBAL_STATE's leaf.
                enforced = keep or (
                    _is_noop_guard_type(entry.guard_type) and global_state_kept
                )
                if enforced:
                    self._kept_guards.add(slot)
                else:
                    self._dropped_guards.add(slot)
                    rendered = " ; ".join(_render_code(entry.code_parts))
                    if rendered:
                        self._dropped_guard_code.setdefault(slot, rendered)
                    if by_default or _is_risky_drop(entry, namespaces):
                        self._risky_dropped_guards.add(slot)
                if entry.guard_type in _UNMODELLED_GUARD_TYPES:
                    # Never compared, so never claimed to hold or to vary.
                    continue
                facts.add(
                    _GuardFact(
                        guard_type=entry.guard_type,
                        source=slot[1],
                        code=_render_code(entry.code_parts),
                        value=_value_fingerprint(entry),
                        enforced=enforced,
                    )
                )
            current = self._package.current_entry
            if current is not None:
                code = current.python_code
                key = (code.co_name, code.co_filename, code.co_firstlineno)
            else:
                key = ("<unknown>", "<unknown>", 0)
            self._guard_sets.setdefault(key, []).append(frozenset(facts))
            return decisions

        return filter_fn

    def __enter__(self) -> Callable[..., object]:
        if self._entered:
            raise PackageError(
                "PrecompileSession cannot be re-entered; start a new capture."
            )
        self._entered = True
        # Its own cache region: a function captured (or compiled) earlier in
        # this process would otherwise serve its existing cache entries, and
        # this package would record nothing.
        self._compiled = torch._dynamo.optimize(
            self._backend,
            package=self._package,
            guard_filter_fn=self._guard_filter_fn,
            dynamic=self._dynamic,
            recompile_limit=self._recompile_limit,
            isolate_recompiles=True,
        )(self._fn)
        return self._call

    def _call(self, *args: object, **kwargs: object) -> object:
        if self._compiled is None or self._finished:
            raise PackageError("PrecompileSession is not active")
        # The compiler configuration is per call, not per block: user code
        # between calls (optimizer.step, data loading, save()) runs in the
        # ambient configuration. The ambient accumulated limit is raised so the
        # explicit per-frame limit is the effective one.
        limit = max(
            self._recompile_limit, torch._dynamo.config.accumulated_recompile_limit
        )
        try:
            with (
                _capture_config(),
                torch._dynamo.config.patch(accumulated_recompile_limit=limit),
            ):
                return self._compiled(*args, **kwargs)
        except Exception as e:
            message = f"{type(e).__name__}: {e}"
            if message not in self._capture_errors:
                self._capture_errors.append(message)
            raise
        finally:
            self._take_backend_artifacts()

    def __exit__(self, *exc: object) -> None:
        self._finished = True
        self._compiled = None

    def _take_backend_artifacts(self) -> None:
        """Move this capture's backend artifacts out of the process-global list.

        The AOTAutograd cache records a bundled entry under each graph's backend
        id as the graph compiles; taking them after every call keeps another
        capture's ``PrecompileContext.clear()`` between calls from losing them.
        """
        from torch._dynamo.precompile_context import PrecompileContext

        for backend_id in self._package.cache_entry().backend_ids:
            if backend_id not in self._backend_artifacts:
                artifact = PrecompileContext.take_artifact(backend_id)
                if artifact is not None:
                    self._backend_artifacts[backend_id] = artifact

    def summary(self) -> PrecompileSummary:
        """Coverage and guard information for everything captured so far."""
        # A dropped slot is risky when the SAME source held DIFFERENT values
        # across a frame's variants: a dropped guard that told the variants
        # apart cannot pick between them at serve time. Merely being absent
        # from one variant (a MODULE_MATCH a branch does not touch) is not.
        risky = set(self._risky_dropped_guards)
        for variants in self._guard_sets.values():
            values: dict[tuple[str, str], set[str]] = {}
            for facts in variants:
                for f in facts:
                    if not f.enforced:
                        values.setdefault((f.guard_type, f.source), set()).add(f.value)
            risky |= {slot for slot, seen in values.items() if len(seen) > 1}
        return _summarize(
            self._package.cache_entry(),
            dropped=self._dropped_guards,
            kept=self._kept_guards,
            policy_dropped=set(),
            risky=risky,
            truncated=frozenset(),
            capture_errors=self._capture_errors,
            guard_sets=self._guard_sets,
            dropped_code=self._dropped_guard_code,
        )


def precompile_capture(
    fn: Callable[..., object],
    *,
    backend: str = "inductor",
    guard_filter_fn: Callable[[Sequence[GuardFilterEntry]], Sequence[bool]]
    | None = None,
    recompile_limit: int = 256,
    dynamic: bool | None = None,
) -> PrecompileSession:
    """Begin capturing ``fn`` into a multi-graph artifact.

    ``recompile_limit`` defaults well above Dynamo's usual 8 because a precompile
    deliberately wants one compiled variant per condition, whereas the normal
    limit exists to catch runaway recompilation. Runtime guards remain intact
    during capture: ``guard_filter_fn`` applies only to the serialized guard
    state, so every call observes the same recompilation behavior as ordinary
    ``torch.compile``.
    """
    if isinstance(fn, functools.partial):
        raise PackageError(
            "precompile cannot capture a partial. Pass the underlying function "
            "and give its bound arguments as call arguments."
        )
    if isinstance(fn, torch.nn.Module):
        # Dynamo compiles the module through its own wrapper frame, whose graphs
        # close over the module; a standalone artifact cannot rebuild that.
        raise PackageError(
            "precompile cannot capture an nn.Module directly: capture the function "
            "that CALLS the model, e.g. a module-level 'def step(model, x): return "
            "model(x)', calling cap(model, x)."
        )
    if isinstance(fn, types.MethodType):
        # The artifact rebuilds fn from its code object, which takes the
        # receiver as its first argument: served, it would not take fn's calls.
        raise PackageError(
            "precompile cannot capture a bound method: capture a module-level "
            "function that takes the receiver as an argument, e.g. 'def step(model, "
            "x): return model(x)', calling cap(model, x)."
        )
    return PrecompileSession(
        fn,
        backend=backend,
        guard_filter_fn=guard_filter_fn,
        recompile_limit=recompile_limit,
        dynamic=dynamic,
    )
