Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

145 KB
Raw Blame
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0

"""Pre-quantized transformer load, lazily imported; pickles use weights_only plus allowlist; bad
files return None so the caller falls back to dense quantise"""

from __future__ import annotations

import contextvars
import functools
import re as _re
import threading as _threading
from dataclasses import dataclass
from collections.abc import Sequence
from typing import Any, Optional

from .diffusion_nvfp4_flag import nvfp4_blocked

# torch.save dict layout tag; bump on an on-disk change so old/foreign artifacts are rejected
PREQUANT_FORMAT = "unsloth_prequant_transformer_state_dict_v1"

# v2 = rotated weights; old builds must refuse it (they would render wrong pixels).
# v2 MUST declare a rotation and v1 must NOT.
PREQUANT_FORMAT_ROTATED = "unsloth_prequant_transformer_state_dict_v2"

# Own tag, else an older build reads it as whole-model nvfp4. v3 MUST declare a policy, v1/v2 must NOT.
PREQUANT_FORMAT_POLICY = "unsloth_prequant_transformer_state_dict_v3"

PREQUANT_FORMATS = (PREQUANT_FORMAT, PREQUANT_FORMAT_ROTATED, PREQUANT_FORMAT_POLICY)

DEFAULT_PREQUANT_COMPONENT = "transformer"


def prequant_format_for(metadata: Any) -> str:
    """The format tag to stamp for ``metadata``; v2 and v3 share one tag slot, so declaring both is refused."""
    from .diffusion_convrot import declares_rotation
    from .diffusion_nvfp4_policy import declares_policy

    rotated = declares_rotation(metadata)
    policy = declares_policy(metadata)
    if rotated and policy:
        raise ValueError(
            "a pre-quant checkpoint cannot declare both an activation rotation and a per-layer "
            "nvfp4 policy: the format tag can only warn older builds about one of them"
        )
    if policy:
        return PREQUANT_FORMAT_POLICY
    return PREQUANT_FORMAT_ROTATED if rotated else PREQUANT_FORMAT


# Request-supplied paths load only inside an operator allowlist (weights_only either way).
ALLOW_LOCAL_PREQUANT_PATH_ENV = "UNSLOTH_ALLOW_LOCAL_PREQUANT_PATH"

# The constructors a pre-quant checkpoint's pickle may name, on top of what ``weights_only`` already permits
# (storages, dtypes, ``_rebuild_*``, ``OrderedDict``, ``torch.device``, ``_get_layout``). Surveyed across every hosted
# checkpoint Unsloth resolves (image + video, fp8 + int8, rotated and not) this is the complete set, so the load runs
# ``weights_only = True`` and a checkpoint naming anything else is refused before one opcode of it executes, hosted or
# local. Registered under the name the PICKLE records, which for a re-exported class is not the class's own
# ``__module__`` (``torchao.quantization.Float8Tensor`` really lives in
# ``...quantize_.workflows.float8.float8_tensor``), so both spellings are listed. Names a given torchao lacks are
# skipped rather than raised: the set spans every release ``install_python_stack`` pins or pinned (0.14 to 0.18) and an
# absent class could not have produced a loadable checkpoint here anyway. Adding a scheme means adding its
# constructors here; forgetting warns and falls back to dense-quantise, never a silent unpickle.
_PREQUANT_SAFE_GLOBALS: tuple[tuple[str, str], ...] = (
    # int8: AffineQuantizedTensor + its plain layout, wrapped for dynamic activation quant
    ("torchao.dtypes.affine_quantized_tensor", "AffineQuantizedTensor"),
    ("torchao.dtypes.uintx.plain_layout", "PlainAQTTensorImpl"),
    ("torchao.dtypes.utils", "PlainLayout"),
    ("torchao.quantization.linear_activation_quantized_tensor", "LinearActivationQuantizedTensor"),
    ("torchao.quantization.quant_api", "_int8_symm_per_token_reduced_range_quant"),
    ("torchao.quantization.quant_primitives", "ZeroPointDomain"),
    ("torchao.quantization.quant_primitives", "MappingType"),
    # fp8: the newer tensor subclass, its per-row granularity and its kernel/mm options.
    ("torchao.quantization", "Float8Tensor"),
    ("torchao.quantization.quantize_.workflows.float8.float8_tensor", "Float8Tensor"),
    (
        "torchao.quantization.quantize_.workflows.float8.float8_tensor",
        "QuantizeTensorToFloat8Kwargs",
    ),
    ("torchao.quantization.quantize_.common.kernel_preference", "KernelPreference"),
    ("torchao.quantization.granularity", "PerRow"),
    ("torchao.quantization.granularity", "PerTensor"),
    ("torchao.float8.inference", "Float8MMConfig"),
    # mxfp8: local bakes only; torchao registers it only on prototype import. nvfp4 is never unpickled.
    ("torchao.prototype.mx_formats.mx_tensor", "MXTensor"),
    ("torchao.prototype.mx_formats.mx_tensor", "QuantizeTensorToMXKwargs"),
    ("torchao.prototype.mx_formats.config", "ScaleCalculationMode"),
    # torch.save stamps TorchVersion; without it every torchao checkpoint is refused.
    ("torch.torch_version", "TorchVersion"),
)


def _prequant_safe_globals() -> list:
    """``(object, pickled name)`` pairs to register; names this torchao lacks are skipped."""
    import importlib

    pairs = []
    for module, name in _PREQUANT_SAFE_GLOBALS:
        try:
            obj = getattr(importlib.import_module(module), name)
        except Exception:  # noqa: BLE001 -- a name this release does not ship is not allowed
            continue
        pairs.append((obj, f"{module}.{name}"))
    return pairs


_SAFE_GLOBALS_LOCK = _threading.Lock()
_SAFE_GLOBALS_REGISTERED: Optional[bool] = None
# Filled in by the registration: which of the names above this install actually resolved.
_RESOLVED_SAFE_GLOBALS: set = set()

# Globals each scheme's checkpoints name, read via pickletools; unused names are not required.
_FP8_REQUIRED_GLOBALS: frozenset = frozenset(
    {
        "torchao.quantization.Float8Tensor",
        "torchao.quantization.quantize_.workflows.float8.float8_tensor."
        "QuantizeTensorToFloat8Kwargs",
        "torchao.quantization.quantize_.common.kernel_preference.KernelPreference",
        "torchao.quantization.granularity.PerRow",
        "torchao.float8.inference.Float8MMConfig",
        "torch.torch_version.TorchVersion",
    }
)

_SCHEME_REQUIRED_GLOBALS: dict = {
    "int8": frozenset(
        {
            "torchao.dtypes.affine_quantized_tensor.AffineQuantizedTensor",
            "torchao.dtypes.uintx.plain_layout.PlainAQTTensorImpl",
            "torchao.dtypes.utils.PlainLayout",
            "torchao.quantization.linear_activation_quantized_tensor."
            "LinearActivationQuantizedTensor",
            "torchao.quantization.quant_api._int8_symm_per_token_reduced_range_quant",
            "torchao.quantization.quant_primitives.ZeroPointDomain",
            "torch.torch_version.TorchVersion",
        }
    ),
    "fp8": _FP8_REQUIRED_GLOBALS,
    "mxfp8": frozenset(
        {
            "torchao.prototype.mx_formats.mx_tensor.MXTensor",
            "torchao.prototype.mx_formats.mx_tensor.QuantizeTensorToMXKwargs",
            "torchao.prototype.mx_formats.config.ScaleCalculationMode",
            "torchao.quantization.quantize_.common.kernel_preference.KernelPreference",
        }
    ),
}

# nvfp4 checkpoints are read from .safetensors only; a .pt / .pth one is never resolved, cached or unpickled.
NVFP4_SAFETENSORS_ONLY_MESSAGE = (
    "NVFP4 diffusion checkpoints are loaded from .safetensors only; {what} is a pickle "
    "(.pt / .pth) and is refused. Use the .safetensors NVFP4 checkpoint instead."
)


def _is_nvfp4_scheme(scheme: Any) -> bool:
    return str(scheme or "").strip().lower() == "nvfp4"


def nvfp4_pickle_name(scheme: Any, name: Optional[str]) -> bool:
    """True when ``name`` is a pickle container (.pt / .pth) for the nvfp4 scheme, which is never used."""
    return _is_nvfp4_scheme(scheme) and str(name or "").strip().lower().endswith(_PICKLE_SUFFIXES)


def without_nvfp4_pickles(scheme: Any, names: Sequence[str]) -> list:
    """``names`` minus the pickle containers when ``scheme`` is nvfp4; every other scheme is unchanged."""
    return [n for n in names if n and not nvfp4_pickle_name(scheme, n)]


def _tuple_safe_globals_supported() -> bool:
    """Checked by version: below torch 2.6, tuple pairs are accepted then break every weights_only load."""
    try:
        import torch
        parts = str(torch.__version__).split("+")[0].split(".")
        return (int(parts[0]), int(parts[1])) >= (2, 6)
    except Exception:  # noqa: BLE001 -- an unreadable version is not a supported one
        return False


def _register_prequant_safe_globals() -> bool:
    """Adds the allowlist once and never removes it (overlapping loads race a context-manager exit); also widens other weights_only loads in-process."""
    global _SAFE_GLOBALS_REGISTERED

    if _SAFE_GLOBALS_REGISTERED is not None:
        return _SAFE_GLOBALS_REGISTERED
    with _SAFE_GLOBALS_LOCK:
        if _SAFE_GLOBALS_REGISTERED is not None:
            return _SAFE_GLOBALS_REGISTERED
        ok = False
        try:
            from core._torchao_stub import is_stubbed

            import torch

            add = getattr(torch.serialization, "add_safe_globals", None)
            # A stubbed torchao (Windows ROCm) fabricates every class, so never register it.
            if add is not None and not is_stubbed("torchao") and _tuple_safe_globals_supported():
                pairs = _prequant_safe_globals()
                resolved = {name for _obj, name in pairs}
                # Resolving some globals is not enough: every artifact needs TorchVersion plus one torchao class.
                if "torch.torch_version.TorchVersion" in resolved and any(
                    name.startswith("torchao.") for name in resolved
                ):
                    add(pairs)
                    _RESOLVED_SAFE_GLOBALS.update(resolved)
                    # Calls _get_user_allowed_globals so unsupported forms fail here, not mid-load after planning.
                    try:
                        torch._weights_only_unpickler._get_user_allowed_globals()
                    except AttributeError:  # noqa: BLE001 -- private; absence is not a failure
                        pass
                    ok = True
        except Exception:  # noqa: BLE001 -- no allowlist means no restricted load, never a raise
            ok = False
        _SAFE_GLOBALS_REGISTERED = ok
        return ok


def restricted_prequant_load_supported(
    scheme: Optional[str] = None, filename: Optional[str] = None
) -> bool:
    """Per scheme (torchao retires int8 constructors before fp8); with a safetensors filename, answer for that file, which needs no allowlist
    but does need a torchao that can rebuild the scheme's subclass (0.16 cannot rebuild nvfp4 / mxfp8)."""
    from .prequant_safetensors import is_safetensors_checkpoint, safetensors_scheme_supported

    if is_safetensors_checkpoint(filename):
        return safetensors_scheme_supported(scheme)
    if _is_nvfp4_scheme(scheme):
        # Safetensors only: a pickle is never readable; the scheme-only question is the safetensors one.
        return filename is None and safetensors_scheme_supported(scheme)
    if not _register_prequant_safe_globals():
        return False
    key = (scheme or "").strip().lower()
    required = _SCHEME_REQUIRED_GLOBALS.get(key)
    if required is None or required <= _RESOLVED_SAFE_GLOBALS:
        return True
    if key == "int8":
        # torchao 0.18 deleted the v1 int8 classes every hosted INT8 pickle names; see prequant_legacy_int8.
        from .prequant_legacy_int8 import legacy_int8_decode_supported
        return legacy_int8_decode_supported()
    return False


def _torch_load_prequant(path: str, **kwargs: Any) -> Any:
    """Always weights_only=True: a pickle naming any global runs code; a torch that cannot take the allowlist is refused, never reopened unrestricted."""
    import torch

    if not _register_prequant_safe_globals():
        raise RuntimeError(
            "this torch cannot register the pre-quant constructor allowlist (needs "
            "torch.serialization.add_safe_globals with (object, name) support, i.e. >= 2.6), so "
            "a pre-quant checkpoint cannot be deserialized without allowing arbitrary pickle "
            "globals"
        )
    from .prequant_legacy_int8 import (
        legacy_int8_decode_supported,
        load_legacy_int8_pickle,
        names_legacy_int8_class,
        rebuild_stray_standins,
    )

    try:
        ckpt = torch.load(path, weights_only = True, **kwargs)
    except Exception as exc:  # noqa: BLE001 - only the deleted-int8-classes refusal is retried
        if names_legacy_int8_class(exc) and legacy_int8_decode_supported():
            return load_legacy_int8_pickle(path, **kwargs)
        raise
    return rebuild_stray_standins(ckpt)


def _load_prequant_checkpoint(
    path: str,
    *,
    scheme: Optional[str] = None,
    **kwargs: Any,
) -> Any:
    """Dispatches on extension, not content; nvfp4 (asked for or recorded) is refused unless safetensors."""
    from .prequant_safetensors import is_safetensors_checkpoint, load_prequant_safetensors

    if is_safetensors_checkpoint(path):
        ckpt = load_prequant_safetensors(path, mmap = bool(kwargs.get("mmap")))
    else:
        if _is_nvfp4_scheme(scheme):
            raise ValueError(NVFP4_SAFETENSORS_ONLY_MESSAGE.format(what = repr(str(path))))
        ckpt = _torch_load_prequant(path, **kwargs)
        meta = ckpt.get("metadata") if isinstance(ckpt, dict) else None
        if isinstance(meta, dict) and _is_nvfp4_scheme(meta.get("scheme")):
            raise ValueError(NVFP4_SAFETENSORS_ONLY_MESSAGE.format(what = repr(str(path))))
    _install_fp8_unit_scale_for(ckpt)
    return ckpt


def _int8_only(ckpt: Any) -> bool:
    """True if every quantized tensor is int8: the fp8 dispatcher's compile cache tag would miss the runtime entry."""
    try:
        state_dict = ckpt.get("state_dict") if isinstance(ckpt, dict) else None
        if not isinstance(state_dict, dict):
            return False
        quantized = [
            type(v).__name__
            for v in state_dict.values()
            if type(v).__name__ not in ("Tensor", "Parameter")
        ]
        return bool(quantized) and all(name.startswith("Int8") for name in quantized)
    except Exception:  # noqa: BLE001
        return False


def _install_fp8_unit_scale(fast_accum: Optional[bool] = None) -> None:
    try:
        from .diffusion_fp8_unit_scale import install
        install(fast_accum = fast_accum)
    except Exception:  # noqa: BLE001 - never block a load on a speed path
        pass


def _install_fp8_unit_scale_for(ckpt: Any) -> None:
    """Skip int8 checkpoints and ones baked at fast accumulate (the builder's default)."""
    meta = (ckpt.get("metadata") if isinstance(ckpt, dict) else None) or {}
    if str(meta.get("scheme") or "").lower() == "int8" or _int8_only(ckpt):
        return
    fast_accum = meta.get("fast_accum")
    _install_fp8_unit_scale(fast_accum = fast_accum if isinstance(fast_accum, bool) else None)


# 0 reads a pickle checkpoint headed for an accelerator into host memory instead of mapping it.
_PREQUANT_MMAP_ENV = "UNSLOTH_DIFFUSION_PREQUANT_MMAP"


def prequant_mmap_enabled(destination: Any, *, host_copy_follows: bool = False) -> bool:
    """Map only for a non-CPU destination: a host-placed module would keep the file open (Windows then cannot delete it).
    ``host_copy_follows``: host-placed but copied off before first render, so Linux maps (avoids a 20 GB copy)."""
    import os
    import sys

    raw = (os.environ.get(_PREQUANT_MMAP_ENV) or "").strip().lower()
    if raw in ("0", "false", "no", "off"):
        return False
    if host_copy_follows and sys.platform.startswith("linux"):
        return True
    dest = str(destination or "").strip().lower()
    return bool(dest) and not dest.startswith("cpu") and dest != "meta"


def _read_prequant_for(
    path: str,
    destination: Any,
    logger: Any = None,
    *,
    host_copy_follows: bool = False,
    scheme: Optional[str] = None,
) -> Any:
    """``_load_prequant_checkpoint`` mapped when enabled; anything the mapping cannot open is re-read in full."""
    if prequant_mmap_enabled(destination, host_copy_follows = host_copy_follows):
        try:
            return _load_prequant_checkpoint(path, scheme = scheme, map_location = "cpu", mmap = True)
        except Exception as exc:  # noqa: BLE001 - retried unmapped; the real error resurfaces there
            if logger is not None:
                logger.info(
                    "diffusion.prequant: mapped read failed (%s: %s); reading the checkpoint into memory",
                    type(exc).__name__,
                    str(exc).splitlines()[0][:200] if str(exc) else "",
                )
    return _load_prequant_checkpoint(path, scheme = scheme, map_location = "cpu")


_PREQUANT_TOGGLE_TOKENS = {"1", "true", "yes", "on", "0", "false", "no", "off"}


def _allowed_prequant_roots() -> list:
    """Operator-allowlisted directories whose pre-quant checkpoints may be unpickled.
    ``UNSLOTH_ALLOW_LOCAL_PREQUANT_PATH`` = one or more dirs (``os.pathsep``-separated). A bare
    truthy/falsey toggle is ignored: it must name a directory, so no "allow all" mode."""
    import os

    raw = (os.environ.get(ALLOW_LOCAL_PREQUANT_PATH_ENV) or "").strip()
    if not raw:
        return []
    roots = []
    for part in raw.split(os.pathsep):
        part = part.strip()
        if not part or part.lower() in _PREQUANT_TOGGLE_TOKENS:
            continue  # a bare on/off value is not a directory
        try:
            roots.append(os.path.realpath(os.path.expanduser(part)))
        except Exception:  # noqa: BLE001 - a bad entry is simply not allowlisted
            continue
    return roots


def _local_prequant_path_allowed(path: str) -> bool:
    """True only when ``path`` resolves inside an allowlisted directory. ``realpath`` first so a
    symlink cannot point an allowlisted name at a file outside the allowed roots."""
    import os

    # Studio's own pre-quant cache root only.
    try:
        from .diffusion_prequant_cache import path_in_cache
        if path_in_cache(path):
            return True
    except Exception:  # noqa: BLE001 - an unanswerable check falls back to the operator allowlist
        pass
    roots = _allowed_prequant_roots()
    if not roots:
        return False
    try:
        real = os.path.realpath(os.path.expanduser(path))
    except Exception:  # noqa: BLE001
        return False
    return any(real == r or real.startswith(r + os.sep) for r in roots)


def local_prequant_path_ready(path: str) -> bool:
    """True only if the path is allowlisted and present, so planning never drops dense for a refused
    file."""
    import os

    if not _local_prequant_path_allowed(path):
        return False
    return os.path.isfile(os.path.expanduser(path))


# Operator mirror <root>/<owner>/<repo>/<filename>, os.pathsep roots, checked before the Hub; names from family tables only; escaping paths ignored.
PREQUANT_MIRROR_ENV = "UNSLOTH_DIFFUSION_PREQUANT_MIRROR"


def prequant_mirror_path(
    repo_id: Optional[str],
    name: Optional[str],
    readable: Any = None,
) -> Optional[str]:
    """A safetensors twin wins over a pickle only if this install can open it, else the file is refused."""
    import os

    raw = (os.environ.get(PREQUANT_MIRROR_ENV) or "").strip()
    if not raw or not repo_id or not name:
        return None
    parts = [*str(repo_id).split("/"), *str(name).split("/")]
    if any(p in ("", ".", "..") or "\\" in p for p in parts):
        return None
    wanted = [parts]
    for suffix in (".pt", ".pth"):
        if parts[-1].endswith(suffix):
            sibling = parts[-1][: -len(suffix)] + ".safetensors"
            try:
                ok = readable is None or bool(readable(sibling))
            except Exception:  # noqa: BLE001 - an unanswerable question is a no
                ok = False
            if ok:
                wanted.insert(0, [*parts[:-1], sibling])
            break
    for root in raw.split(os.pathsep):
        root = root.strip()
        if not root:
            continue
        for rel in wanted:
            try:
                base = os.path.realpath(os.path.expanduser(root))
                candidate = os.path.realpath(os.path.join(base, *rel))
            except Exception:  # noqa: BLE001 - a bad root is simply not a mirror
                break
            if candidate.startswith(base.rstrip(os.sep) + os.sep) and os.path.isfile(candidate):
                return candidate
    return None


def _first_mirrored(repo_id: Optional[str], names: Sequence[str], readable: Any) -> Optional[str]:
    """The mirror's copy of the first of ``names`` it holds, checked for ALL names before any Hub call."""
    for name in names:
        hit = prequant_mirror_path(repo_id, name, readable)
        if hit is not None:
            return hit
    return None


# Set to 1 to always download the safetensors container even when its pickle twin is already cached.
PREFER_SAFETENSORS_ENV = "UNSLOTH_PREQUANT_PREFER_SAFETENSORS"

_PICKLE_SUFFIXES = (".pt", ".pth")
_logged_twin_choices: set = set()

# ``<stem>-ComfyUI.safetensors``: the twin of a hosted artifact both ComfyUI and Studio load; older builds never ask for it.
COMFY_PREQUANT_TAG = "-ComfyUI"
COMFY_PREQUANT_SUFFIX = COMFY_PREQUANT_TAG + ".safetensors"
# 0 drops the ComfyUI-format names from the chain (back to Studio's own containers only).
COMFY_PREQUANT_ENV = "UNSLOTH_DIFFUSION_PREQUANT_COMFY"
_ARTIFACT_SUFFIXES = (".safetensors",) + _PICKLE_SUFFIXES


def is_comfy_prequant_filename(name: Optional[str]) -> bool:
    """Whether ``name`` is the ComfyUI-format spelling of a hosted artifact."""
    return bool(name) and str(name).endswith(COMFY_PREQUANT_SUFFIX)


def _artifact_stem(name: Optional[str]) -> Optional[str]:
    """``<stem>`` of a hosted ``<stem>.safetensors`` / ``.pt`` / ``.pth`` / ``-ComfyUI.safetensors`` artifact;
    None for the legacy ``transformer_<scheme>.pt`` names, which have no ComfyUI twin."""
    if not name or "/" in str(name):
        return None
    name = str(name)
    if name.startswith("transformer_"):
        return None
    if name.endswith(COMFY_PREQUANT_SUFFIX):
        return name[: -len(COMFY_PREQUANT_SUFFIX)] or None
    for suffix in _ARTIFACT_SUFFIXES:
        if name.endswith(suffix):
            return name[: -len(suffix)] or None
    return None


def comfy_prequant_filename(name: Optional[str]) -> Optional[str]:
    """The ComfyUI-format twin of the hosted artifact ``name`` (``<stem>-ComfyUI.safetensors``), else None."""
    stem = _artifact_stem(name)
    if stem is None or is_comfy_prequant_filename(name):
        return None
    return stem + COMFY_PREQUANT_SUFFIX


def comfy_prequant_enabled() -> bool:
    import os
    return (os.environ.get(COMFY_PREQUANT_ENV) or "").strip().lower() not in (
        "0",
        "off",
        "false",
        "no",
    )


# Twins that hold Studio's weights bit for bit (int8) lead the chain. ComfyUI fp8 has one scale per tensor, a coarser
# second rounding of Studio's per-row fp8, so an fp8 twin trails Studio's own fp8 artifact.
COMFY_TWIN_LEADS = frozenset({"int8"})


def with_comfy_twins(names: Sequence[str], *, lead: bool = True) -> list:
    """Adds each name's ComfyUI-format twin; with lead the twin comes first, older names stay as
    fallback."""
    names = [n for n in names if n]
    out: list = []
    for index, name in enumerate(names):
        twin = comfy_prequant_filename(name)
        stem = _artifact_stem(name)
        if twin and twin not in names and twin not in out:
            if lead:
                out.append(twin)
            elif not any(_artifact_stem(n) == stem for n in names[index + 1 :]):
                out.extend(n for n in (name, twin) if n not in out)
                continue
        if name not in out:
            out.append(name)
    return out


def _hub_name_cached(
    repo_id: Optional[str], name: Optional[str], root: Optional[str]
) -> Optional[str]:
    """``repo_id/name``'s path in ONE Hub cache root (None = huggingface_hub's own), else None. Never raises."""
    if not repo_id or not name:
        return None
    try:
        import os

        from huggingface_hub import try_to_load_from_cache
    except Exception:  # noqa: BLE001 - no cache API to ask: treat as not cached
        return None
    try:
        hit = try_to_load_from_cache(repo_id, name, cache_dir = root)
    except Exception:  # noqa: BLE001 - a malformed cache entry is not a hit
        return None
    # a str is the cached path; a miss is None and a known-absent file is a sentinel object
    return hit if isinstance(hit, str) and os.path.isfile(hit) else None


def _twin_cache_roots(cache_dir: Optional[str]) -> tuple:
    """Every cache root a download could reuse: the caller's, the live setting, huggingface_hub's own."""
    roots: list = []
    live = None
    try:
        from utils.hf_cache_settings import active_hf_hub_cache
        live = active_hf_hub_cache()
    except Exception:  # noqa: BLE001 - outside the Studio backend there is no live setting
        live = None
    for root in (cache_dir, live, None):
        if root not in roots:
            roots.append(root)
    return tuple(roots)


def explain_container_choice(
    repo_id: Optional[str],
    chosen: Optional[str],
    candidates: Sequence[str],
    order: Sequence[str],
    readable: Any = None,
    logger: Any = None,
) -> Optional[str]:
    """Log once per file why a ``.pt`` was resolved although the chain names its safetensors twin
    (cached twin, twin not hosted yet, or safetensors unreadable here). Returns the reason. Never raises."""
    try:
        if not repo_id or not chosen or not chosen.lower().endswith(_PICKLE_SUFFIXES):
            return None
        stem = chosen[: chosen.rfind(".")]
        twin = stem + ".safetensors"
        if twin not in candidates:
            return None
        try:
            twin_ok = readable is None or bool(readable(twin))
        except Exception:  # noqa: BLE001
            twin_ok = False
        if not twin_ok:
            reason = "this install cannot read the .safetensors container"
        elif twin in order and chosen in order and order.index(chosen) < order.index(twin):
            return "cached"
        else:
            reason = "the repo does not host the .safetensors twin yet"
        key = (repo_id, chosen, reason)
        if key not in _logged_twin_choices:
            _logged_twin_choices.add(key)
            log = logger
            if log is None:
                import logging
                log = logging.getLogger(__name__)
            log.info(
                "diffusion.prequant_pickle: %s: using %s instead of %s because %s",
                repo_id,
                chosen,
                twin,
                reason,
            )
        return reason
    except Exception:  # noqa: BLE001 - a log line, never a failure
        return None


def prefer_cached_pickle_twins(
    repo_id: Optional[str],
    names: Sequence[str],
    *,
    readable: Any = None,
    cache_dir: Optional[str] = None,
    logger: Any = None,
    log: bool = True,
    roots: Optional[Sequence[Optional[str]]] = None,
) -> list:
    """Safetensors stays first, except a same-stem cached .pt/.pth whose sha256 matches the Hub's record moves ahead of
    its uncached safetensors twin (reused, not re-downloaded); the twin stays behind it as 404 fallback. An unverified
    cached pickle (offline, no LFS record, mismatch) keeps its place behind the twin. PREFER_SAFETENSORS_ENV disables."""
    import os

    out = [n for n in names if n]
    if not repo_id or len(out) < 2:
        return out
    try:
        # only the roots the caller's download will reuse, else it re-fetches the pickle it was promised
        roots = tuple(roots) if roots is not None else _twin_cache_roots(cache_dir)

        def _cached(name: str) -> bool:
            return any(_hub_name_cached(repo_id, name, root) is not None for root in roots)

        def _ok(name: str) -> bool:
            try:
                return readable is None or bool(readable(name))
            except Exception:  # noqa: BLE001 - an unanswerable question is a no
                return False

        def _verified(name: str) -> bool:
            from .cached_weight_sha import cached_copy_matches_hub

            if _LOCAL_FILES_ONLY.get():
                return False  # a load that may not reach the Hub cannot ask it for the hash
            token = _LOAD_HF_TOKEN.get()
            for root in roots:
                hit = _hub_name_cached(repo_id, name, root)
                if hit is not None and cached_copy_matches_hub(repo_id, name, hit, token = token):
                    return True
            return False

        prefer_safetensors = (os.environ.get(PREFER_SAFETENSORS_ENV) or "").strip().lower() in (
            "1",
            "true",
            "yes",
            "on",
        )

        def _reusable(name: str) -> bool:
            if not _ok(name) or not _cached(name):
                return False
            # same pickle trust rule as below
            if name.lower().endswith(_PICKLE_SUFFIXES):
                return not prefer_safetensors and _verified(name)
            return True

        # A cached container of an artifact beats an uncached one of the SAME artifact: never download a second copy.
        for comfy in [n for n in out if is_comfy_prequant_filename(n)]:
            stem = _artifact_stem(comfy)
            twins = [n for n in out if n != comfy and _artifact_stem(n) == stem]
            if not twins:
                continue
            hit = next((t for t in twins if _reusable(t)), None)
            if _cached(comfy):
                if hit is None and _ok(comfy) and out.index(comfy) > out.index(twins[0]):
                    out.remove(comfy)
                    out.insert(out.index(twins[0]), comfy)
                continue
            if hit is None:
                continue
            out.remove(comfy)
            out.insert(out.index(twins[-1]) + 1, comfy)
            key = (repo_id, hit, comfy)
            if log and key not in _logged_twin_choices:
                _logged_twin_choices.add(key)
                sink = logger
                if sink is None:
                    import logging
                    sink = logging.getLogger(__name__)
                sink.info(
                    "diffusion.prequant_cached_twin: %s: using the cached %s; its ComfyUI-format twin %s is "
                    "not downloaded",
                    repo_id,
                    hit,
                    comfy,
                )
        if prefer_safetensors:
            return out

        for st in [
            n
            for n in out
            if n.lower().endswith(".safetensors") and not is_comfy_prequant_filename(n)
        ]:
            stem = st[: -len(".safetensors")]
            twin = next(
                (
                    stem + suffix
                    for suffix in _PICKLE_SUFFIXES
                    if stem + suffix in out and _ok(stem + suffix) and _cached(stem + suffix)
                ),
                None,
            )
            # Only a cached pickle the Hub's sha256 vouches for is reused; unverified, safetensors stays first.
            if twin is None or _cached(st) or not _verified(twin):
                continue
            out.remove(twin)
            out.insert(out.index(st), twin)
            key = (repo_id, twin)
            if log and key not in _logged_twin_choices:
                _logged_twin_choices.add(key)
                sink = logger
                if sink is None:
                    import logging
                    sink = logging.getLogger(__name__)
                sink.info(
                    "diffusion.prequant_cached_pickle: %s: using the cached %s (sha256 matches the Hub); the "
                    "%s twin is not downloaded (set %s=1 to fetch it instead)",
                    repo_id,
                    twin,
                    st,
                    PREFER_SAFETENSORS_ENV,
                )
    except Exception:  # noqa: BLE001 - a preference, never a new failure
        return [n for n in names if n]
    return out


# 0 stops requesting the ``<stem>.safetensors`` twin ahead of a family-declared ``<stem>.pt`` (the older chain).
SAFETENSORS_TWINS_ENV = "UNSLOTH_PREQUANT_SAFETENSORS_TWINS"


def with_declared_safetensors_twins(
    names: Sequence[str],
    declared: Sequence[str],
    *,
    scheme: Optional[str] = None,
) -> list:
    """Put ``<stem>.safetensors`` before each declared root .pt / .pth (kept as 404 fallback); nvfp4 ignores the env."""
    import os

    out = [n for n in names if n]
    if not _is_nvfp4_scheme(scheme) and (
        os.environ.get(SAFETENSORS_TWINS_ENV) or ""
    ).strip().lower() in (
        "0",
        "false",
        "no",
        "off",
    ):
        return out
    wanted = {n for n in declared if n}
    ordered: list = []
    for name in out:
        if name in wanted and "/" not in name and name.lower().endswith(_PICKLE_SUFFIXES):
            twin = name[: name.rfind(".")] + ".safetensors"
            if twin not in ordered:
                ordered.append(twin)
        if name not in ordered:
            ordered.append(name)
    return ordered


_LOCAL_FILES_ONLY = contextvars.ContextVar("unsloth_prequant_local_files_only", default = False)
# The load's Hub token for probes lacking one in their signature (cache freshness of a gated base); outer token wins.
_LOAD_HF_TOKEN: contextvars.ContextVar = contextvars.ContextVar(
    "unsloth_prequant_hf_token", default = None
)


def scoped_local_files_only(fn: Any) -> Any:
    """Run ``fn`` with its ``local_files_only`` kwarg visible to every cache probe it reaches, so a
    load that may not download plans like an offline one. Nested calls keep an outer True."""

    @functools.wraps(fn)
    def _wrapper(*args: Any, **kwargs: Any) -> Any:
        token = _LOCAL_FILES_ONLY.set(
            bool(kwargs.get("local_files_only")) or _LOCAL_FILES_ONLY.get()
        )
        hf_token = _LOAD_HF_TOKEN.set(kwargs.get("hf_token") or _LOAD_HF_TOKEN.get())
        try:
            return fn(*args, **kwargs)
        finally:
            _LOAD_HF_TOKEN.reset(hf_token)
            _LOCAL_FILES_ONLY.reset(token)

    return _wrapper


def hub_offline() -> bool:
    """huggingface_hub's offline switch. Never raises."""
    try:
        from huggingface_hub import constants
        return bool(constants.HF_HUB_OFFLINE)
    except Exception:  # noqa: BLE001 - no hub library: nothing can be downloaded either
        return True


def hub_name_known_absent(
    repo_id: Optional[str],
    name: Optional[str],
    cache_dir: Optional[str] = None,
) -> bool:
    """True when a Hub cache root holds a ``.no_exist`` marker (a recorded 404) for ``name``. Never raises."""
    if not repo_id or not name:
        return False
    try:
        from huggingface_hub import try_to_load_from_cache
    except Exception:  # noqa: BLE001 - no cache API: nothing is known
        return False
    for root in _twin_cache_roots(cache_dir):
        try:
            hit = try_to_load_from_cache(repo_id, name, cache_dir = root)
        except Exception:  # noqa: BLE001 - a malformed cache entry says nothing
            continue
        # str = cached path, None = never asked, anything else = the .no_exist sentinel
        if hit is not None and not isinstance(hit, str):
            return True
    return False


def first_cached_as_resolved(
    repo_id: Optional[str],
    names: Sequence[str],
    *,
    is_cached: Any,
    online: Optional[bool] = None,
    cache_dir: Optional[str] = None,
) -> Optional[str]:
    """First cached name in resolver order; online, an uncached name ahead of it would block the load."""
    try:
        if online is None:
            online = not hub_offline() and not _LOCAL_FILES_ONLY.get()
        ahead: list = []
        for name in names:
            if not name:
                continue
            if not is_cached(name):
                ahead.append(name)
                continue
            if online:
                for other in ahead:
                    if not hub_name_known_absent(repo_id, other, cache_dir):
                        return None
            return name
    except Exception:  # noqa: BLE001 - a planning aid: unanswerable reads as not cached
        return None
    return None


@dataclass(frozen = True)
class PrequantSource:
    """Where a pre-quantized checkpoint lives. ``kind`` is "path" (a local file) or "repo" (Hub repo
    id in ``location`` + ``filename``; ``fallback_filenames`` are tried IN ORDER when the primary
    name is absent, covering the ``.pt`` container and repos still on the legacy
    transformer_<scheme>.pt)."""

    kind: str
    location: str
    filename: Optional[str] = None
    fallback_filenames: tuple[str, ...] = ()
    # Family-declared names are real; derived ones are guesses that may 404.
    declared_filenames: tuple[str, ...] = ()

    @property
    def fallback_filename(self) -> Optional[str]:
        """The first fallback. Kept because callers outside this module read it by name, and
        because it is what "the one other name to try" meant before the chain existed."""
        return self.fallback_filenames[0] if self.fallback_filenames else None

    @property
    def candidate_filenames(self) -> tuple[str, ...]:
        """Every name this source may resolve, best first. The single place that ordering lives, so
        the downloader, the cache probe and the planner cannot disagree about which file wins."""
        return tuple(n for n in (self.filename, *self.fallback_filenames) if n)


def candidate_filenames_of(source: Any) -> tuple[str, ...]:
    """Stand-ins without candidate_filenames fall back to the filename attributes instead of raising."""
    names = getattr(source, "candidate_filenames", None)
    if names is None:
        names = (
            getattr(source, "filename", None),
            getattr(source, "fallback_filename", None),
        )
    return tuple(n for n in names if n)


def prequant_filename(scheme: str) -> str:
    """The legacy checkpoint filename for ``scheme`` inside a Hub repo."""
    return f"transformer_{scheme}.pt"


def prequant_repo_filename(
    repo_id: str,
    scheme: str,
    suffix: str = ".pt",
    *,
    component: Optional[str] = None,
) -> str:
    """Derives the name from repo and scheme; suffix defaults to .pt, so existing callers are unchanged."""
    model = repo_id.rsplit("/", 1)[-1]
    for drop in ("-fp8", "-int8", "-nvfp4", "-mxfp8", "-quantized"):
        if model.lower().endswith(drop):
            model = model[: -len(drop)]
            break
    part = (component or "").strip()
    if part and part != DEFAULT_PREQUANT_COMPONENT:
        return f"{model}-{part}-{scheme.upper()}{suffix}"
    return f"{model}-{scheme.upper()}{suffix}"


def derived_prequant_filenames(
    repo_id: str,
    scheme: str,
    *,
    component: Optional[str] = None,
) -> tuple[str, ...]:
    """Safetensors name first, .pt behind; nvfp4 derives the safetensors name only."""
    if _is_nvfp4_scheme(scheme):
        return (prequant_repo_filename(repo_id, scheme, ".safetensors", component = component),)
    names = (
        prequant_repo_filename(repo_id, scheme, ".safetensors", component = component),
        prequant_repo_filename(repo_id, scheme, ".pt", component = component),
    )
    part = (component or "").strip()
    if part and part != DEFAULT_PREQUANT_COMPONENT:
        return names
    return names + (prequant_filename(scheme),)


def resolve_prequant_source(
    fam: Any,
    scheme: str,
    *,
    path_override: Optional[str] = None,
    base_repo: Optional[str] = None,
    task: Optional[str] = None,
) -> Optional[PrequantSource]:
    """Resolve where the checkpoint for ``(fam, scheme)`` comes from.

    Priority: an explicit local ``path_override``; then the family's hosted repo for ``scheme``
    (variant-specific when ``base_repo`` names a base with its own baked checkpoint); then None,
    meaning no pre-quant and the caller quantises dense. No torch; the only IO is the memoised local cache lookup
    (safetensors headers), reached only when nothing is hosted.

    ``task`` names the workflow / denoiser PARTITION the load is bringing up, for the families that
    host more than one under a single repo and scheme (MiniMax-H3's keyframe and reference
    denoisers). It only ever selects a more specific filename: unset, or set to a task the family
    declares nothing for, resolves exactly what it resolved before.

    Both names are repo-ROOT names. Every hosted prequant repo, image and video alike, keeps its
    checkpoints at the root, so there is no directory to prepend; a repo that nested them would 404
    on the primary AND on the fallback and the load would silently fall back to dense.
    """
    if nvfp4_blocked(scheme):
        return None
    override = (path_override or "").strip()
    if override:
        if nvfp4_pickle_name(scheme, override):
            # A local nvfp4 override is read from safetensors only; a pickle is never a source.
            return None
        return PrequantSource(kind = "path", location = override, filename = None)
    preferred = None
    agnostic = None
    try:
        from .diffusion_families import family_prequant_filename, family_prequant_repo

        repo_id = family_prequant_repo(fam, scheme, base_repo = base_repo)
        preferred = family_prequant_filename(fam, scheme, task = task)
        # Name resolved without a task, which decides whether a fallback is safe; skipped if no task.
        agnostic = family_prequant_filename(fam, scheme) if task else preferred
    except Exception:  # noqa: BLE001 - a bad family object must not break the load
        repo_id = None
    if repo_id:
        derived = derived_prequant_filenames(repo_id, scheme)
        # A family may name a second artifact; it becomes primary. Task-specific names get NO
        # fallback: another partition's denoiser would pass every check with the wrong weights.
        task_specific = preferred is not None and preferred != agnostic
        if task_specific:
            # Only the same artifact's safetensors twin goes ahead of it: same partition, same weights.
            names = without_nvfp4_pickles(
                scheme, with_declared_safetensors_twins((preferred,), (preferred,), scheme = scheme)
            )
            if not names:
                return None
            return PrequantSource(
                kind = "repo",
                location = repo_id,
                filename = names[0],
                fallback_filenames = tuple(names[1:]),
                declared_filenames = (names[0],) if _is_nvfp4_scheme(scheme) else (preferred,),
            )
        # Declared name first, then derived chain (safetensors ahead); dedup in order. Declared names are default-repo files; variant repos derive their own.
        variant_repo = _is_variant_prequant_repo(fam, repo_id)
        if variant_repo and preferred:
            declared = (prequant_repo_filename(repo_id, scheme, ".safetensors"),)
        else:
            declared = (preferred,) if preferred else ()
        if _is_nvfp4_scheme(scheme):
            # Every hosted nvfp4 repo stores exactly ``<Model>-NVFP4.safetensors``: a real name, not a guess.
            declared = tuple(without_nvfp4_pickles(scheme, declared)) or derived[:1]
        # rotated artifact (hosted) first, only in its own repo; the plain chain stays behind it (offline, older caches)
        from .diffusion_transformer_quant import (
            convrot_prequant_filename,
            convrot_prequant_repo,
            convrot_prequant_variant_repo,
            int8_convrot_enabled,
        )

        fam_name = getattr(fam, "name", None)
        rotated = convrot_prequant_filename(scheme, fam_name)
        rotated_repo = convrot_prequant_repo(scheme, fam_name)
        if (
            variant_repo
            and convrot_prequant_variant_repo(scheme, fam_name, repo_id)
            and int8_convrot_enabled(fam_name)
        ):
            # A variant repo listed as hosting its own rotated build, named like its derived chain.
            declared = (prequant_repo_filename(repo_id, scheme, "-ConvRot.safetensors"),) + declared
        elif (
            rotated
            and rotated_repo
            and str(repo_id).strip().lower() == rotated_repo.lower()
            and int8_convrot_enabled(fam_name)
        ):
            declared = (rotated,) + declared
        names: list[str] = []
        for name in declared + derived:
            if name and name not in names:
                names.append(name)
        from .diffusion_transformer_quant import convrot_drops_plain_hosted

        if rotated and convrot_drops_plain_hosted(scheme, fam_name):
            # Hosted plain int8 files are unrotated: rotated file or rotate at load.
            names = (
                [rotated] if str(repo_id).strip().lower() == str(rotated_repo or "").lower() else []
            )
            declared = tuple(names)
        names = with_declared_safetensors_twins(names, declared, scheme = scheme)
        if comfy_prequant_enabled() and _comfy_prequant_family(fam):
            names = with_comfy_twins(names, lead = scheme in COMFY_TWIN_LEADS)
        names = without_nvfp4_pickles(scheme, names)
        if names:
            return PrequantSource(
                kind = "repo",
                location = repo_id,
                filename = names[0],
                fallback_filenames = tuple(names[1:]),
                declared_filenames = declared,
            )
        if not (rotated and convrot_drops_plain_hosted(scheme, fam_name)):
            return None
    # Nothing hosted: try this machine's cache of an earlier build; task names the component (MoE transformer_2).
    try:
        from .diffusion_prequant_cache import lookup
        cached = lookup(
            fam,
            scheme,
            base_repo = base_repo,
            component = task if task in ("transformer_2",) else "transformer",
        )
    except Exception:  # noqa: BLE001 - a cache problem is a miss, never a failed load
        cached = None
    if cached and not nvfp4_pickle_name(scheme, cached):
        return PrequantSource(kind = "path", location = cached, filename = None)
    return None


def _is_variant_prequant_repo(fam: Any, repo_id: Optional[str]) -> bool:
    """Whether ``repo_id`` is one of ``fam``'s per-base variant repos and not one of its default repos."""
    key = str(repo_id or "").strip().lower()
    if not key:
        return False
    try:
        defaults = {str(r).strip().lower() for _s, r in getattr(fam, "prequant_repos", ()) or ()}
        variants = {
            str(e[2]).strip().lower()
            for e in getattr(fam, "prequant_variant_repos", ()) or ()
            if len(e) == 3
        }
    except Exception:  # noqa: BLE001 - a malformed table keeps the declared names, today's behaviour
        return False
    return key in variants and key not in defaults


def _comfy_prequant_family(fam: Any) -> bool:
    """Whether ``fam``'s hosted artifacts may resolve to a ComfyUI-format twin: the image families, whose
    denoiser loads through ``load_prequantized_transformer`` as one whole module."""
    try:
        from .diffusion_families import DiffusionFamily
        return isinstance(fam, DiffusionFamily)
    except Exception:  # noqa: BLE001 - no registry: keep the chain as it was
        return False


_LOCAL_PREQUANT_SCHEME: dict[tuple[str, int, int], Optional[str]] = {}


def local_prequant_scheme(path: str) -> Optional[str]:
    """Recorded scheme via the allowlisted load; a pickle recording nvfp4 reads as unknown."""
    import os

    try:
        real = os.path.expanduser(path)
        st = os.stat(real)
        # Nanoseconds: a same-size swap within one second would reuse the old scheme.
        key = (real, st.st_mtime_ns, int(st.st_size))
    except Exception:  # noqa: BLE001 -- unreadable is "unknown", handled by the caller
        return None
    if key in _LOCAL_PREQUANT_SCHEME:
        return _LOCAL_PREQUANT_SCHEME[key]
    from .prequant_safetensors import is_safetensors_checkpoint, read_prequant_header

    scheme: Optional[str] = None
    try:
        if is_safetensors_checkpoint(real):
            obj = read_prequant_header(real)
        else:
            obj = _torch_load_prequant(real, map_location = "meta", mmap = True)
        if isinstance(obj, dict) and obj.get("format") in PREQUANT_FORMATS:
            recorded = (obj.get("metadata") or {}).get("scheme")
            scheme = str(recorded) if recorded else None
        if nvfp4_pickle_name(scheme, real):
            scheme = None
    except Exception:  # noqa: BLE001 -- a checkpoint we cannot parse is "unknown", never a match
        scheme = None
    if scheme is None and is_safetensors_checkpoint(real):
        try:
            from .diffusion_comfy_quant import comfy_prequant_scheme, scan_comfy_quant
            scheme = comfy_prequant_scheme(scan_comfy_quant(real))
        except Exception:  # noqa: BLE001 -- unreadable is "unknown"
            scheme = None
    _LOCAL_PREQUANT_SCHEME[key] = scheme
    return scheme


def hosted_nvfp4_repo_ids() -> frozenset:
    """Lowercased repo ids any image/video family registers for nvfp4, read off the family tables."""
    from dataclasses import fields, is_dataclass

    from .diffusion_nvfp4_flag import is_nvfp4

    families: list = []
    for module in ("diffusion_families", "video_families"):
        try:
            mod = __import__(f"{__package__}.{module}", fromlist = ["_FAMILIES"])
            families.extend(getattr(mod, "_FAMILIES", ()) or ())
        except Exception:  # noqa: BLE001 - a table that fails to import names no repo
            continue
    repos = set()
    for fam in families:
        if not is_dataclass(fam):
            continue
        for field in fields(fam):
            value = getattr(fam, field.name, None)
            if not isinstance(value, tuple):
                continue
            for row in value:
                if not isinstance(row, tuple) or not row or not isinstance(row[-1], str):
                    continue
                if "/" in row[-1] and any(isinstance(x, str) and is_nvfp4(x) for x in row[:-1]):
                    repos.add(row[-1].strip().lower())
    return frozenset(repos)


# Root only: a diffusers pipeline keeps its weights in component folders.
_PREQUANT_PROBE_SUFFIXES = (".safetensors", ".pt", ".pth")
# nvfp4 is recorded only in safetensors headers; a pickle is never opened to ask.
_NVFP4_PROBE_SUFFIXES = (".safetensors",)
_PREQUANT_PROBE_LIMIT = 16


def _cached_snapshot_dirs(repo_id: str) -> list:
    """The local snapshot folders of Hub repo ``repo_id``, newest first. No network."""
    import os

    parts = repo_id.strip().strip("/").split("/")
    if len(parts) != 2 or not all(parts):
        return []
    roots = []
    try:
        from utils.hf_cache_settings import active_hf_hub_cache
        roots.append(active_hf_hub_cache())
    except Exception:  # noqa: BLE001
        pass
    try:
        from huggingface_hub import constants
        roots.append(constants.HF_HUB_CACHE)
    except Exception:  # noqa: BLE001
        pass
    found = []
    for root in dict.fromkeys(r for r in roots if r):
        snapshots = os.path.join(root, "models--" + "--".join(parts), "snapshots")
        try:
            entries = [os.path.join(snapshots, name) for name in os.listdir(snapshots)]
        except OSError:
            continue
        entries = [e for e in entries if os.path.isdir(e)]
        entries.sort(key = lambda e: os.path.getmtime(e), reverse = True)
        found.extend(entries)
    return found


def _artifacts_declare_nvfp4(folder: str) -> bool:
    """Whether a pre-quant artifact at the root of ``folder`` records ``scheme = nvfp4``."""
    import os

    from .diffusion_nvfp4_flag import is_nvfp4

    try:
        names = sorted(os.listdir(folder))
    except OSError:
        return False
    if "model_index.json" in names:
        return False
    probed = 0
    for name in names:
        if not name.lower().endswith(_NVFP4_PROBE_SUFFIXES):
            continue
        path = os.path.join(folder, name)
        if not os.path.isfile(path):
            continue
        if is_nvfp4(local_prequant_scheme(path)):
            return True
        probed += 1
        if probed >= _PREQUANT_PROBE_LIMIT:
            break
    return False


def declares_nvfp4_checkpoint(model_path: Optional[str]) -> bool:
    """Whether ``model_path`` is an NVFP4 prequant checkpoint: recorded metadata first, else registry or name. Never raises."""
    import os

    raw = str(model_path or "").strip()
    if not raw:
        return False
    try:
        local = os.path.expanduser(raw)
        if os.path.isfile(local):
            if not local.lower().endswith(_PREQUANT_PROBE_SUFFIXES):
                return False
            if local.lower().endswith(_PICKLE_SUFFIXES):
                # Never unpickled to ask: the name decides (an nvfp4 pickle is refused at load anyway).
                stem = os.path.splitext(os.path.basename(local))[0].lower()
                return stem.endswith(("-nvfp4", "_nvfp4"))
            from .diffusion_nvfp4_flag import is_nvfp4

            return is_nvfp4(local_prequant_scheme(local))
        if os.path.isdir(local):
            if _artifacts_declare_nvfp4(local):
                return True
        else:
            key = raw.strip("/").lower()
            if key in hosted_nvfp4_repo_ids():
                return True
            if any(_artifacts_declare_nvfp4(snap) for snap in _cached_snapshot_dirs(raw)):
                return True
    except Exception:  # noqa: BLE001 - a probe that fails is "not known to be NVFP4"
        pass
    return raw.rstrip("/\\").lower().endswith("-nvfp4")


# Legacy (read-only): hashes torchao internals, so v1 only matches the torchao generation that wrote it.
FINGERPRINT_ALGO = "md5-packed-v1"
# Stored under ``canonical_modules``, not ``modules``: older loaders would refuse it as a v1 mismatch.
CANONICAL_FINGERPRINT_ALGO = "md5-canonical-v2"
CANONICAL_FINGERPRINT_KEY = "canonical_modules"

# Payload attrs per torchao class NAME, hash order; unlisted reads "not covered", never "equal".
_FINGERPRINT_PAYLOAD: dict = {
    "NVFP4Tensor": ("qdata", "scale", "per_tensor_scale"),
    "Float8Tensor": ("qdata", "scale"),
    "Int8Tensor": (
        "qdata",
        "scale",
        "zero_point",
        "act_quant_scale",
        "act_quant_zero_point",
        "act_pre_scale",
    ),
    "MXTensor": ("qdata", "scale"),
    "LinearActivationQuantizedTensor": ("original_weight_tensor",),
    "AffineQuantizedTensor": ("tensor_impl",),
    "PlainAQTTensorImpl": ("int_data", "scale", "zero_point"),
}


def _packed_view(tensor: Any, torch: Any) -> Any:
    """``tensor``'s raw bytes as a zero-copy buffer (``view(torch.uint8)``), exact for dtypes numpy cannot represent."""
    t = tensor.detach().contiguous()
    if t.dim() == 0:
        t = t.reshape(1)
    if t.dtype is not torch.uint8:
        t = t.view(torch.uint8)
    return memoryview(t.cpu().numpy().reshape(-1))


def _packed_bytes(tensor: Any, torch: Any) -> bytes:
    """``tensor``'s raw bytes via ``view(torch.uint8)``, exact for dtypes numpy cannot represent."""
    return _packed_view(tensor, torch).tobytes()


def _hash_packed_payload(tensor: Any, digest: Any, torch: Any) -> bool:
    """Feed one weight's packed payload (with attribute names) into ``digest``; False when uncovered."""
    names = _FINGERPRINT_PAYLOAD.get(type(tensor).__name__)
    if names is None:
        return False
    hashed = False
    for name in names:
        value = getattr(tensor, name, None)
        if value is None:
            continue
        digest.update(name.encode("utf-8"))
        if type(value).__name__ in _FINGERPRINT_PAYLOAD:
            if not _hash_packed_payload(value, digest, torch):
                return False
            hashed = True
            continue
        digest.update(_packed_view(value, torch))
        hashed = True
    return hashed


def packed_weight_fingerprint(state_dict: Any, *, select: Any = None) -> dict:
    """md5 of every quantized weight's packed payload by fqn (``select`` narrows it); unknown ones go under ``skipped``."""
    import hashlib

    import torch

    def _digest(tensor: Any) -> Optional[str]:
        digest = hashlib.md5()
        if not _hash_packed_payload(tensor, digest, torch):
            return None
        return digest.hexdigest()

    modules, skipped = _digest_weights(state_dict, select, _digest)
    return {
        "algo": FINGERPRINT_ALGO,
        "count": len(modules),
        "modules": modules,
        "skipped": skipped,
    }


# torchao class name -> (role, attr); ("inner", attr) unwraps. Roles are version neutral (``q`` = int_data / qdata).
_CANONICAL_PARTS: dict = {
    "LinearActivationQuantizedTensor": (("inner", "original_weight_tensor"),),
    "AffineQuantizedTensor": (("inner", "tensor_impl"),),
    "PlainAQTTensorImpl": (("q", "int_data"), ("scale", "scale"), ("zero_point", "zero_point")),
    "Int8Tensor": (
        ("q", "qdata"),
        ("scale", "scale"),
        ("zero_point", "zero_point"),
        ("act_quant_scale", "act_quant_scale"),
        ("act_quant_zero_point", "act_quant_zero_point"),
        ("act_pre_scale", "act_pre_scale"),
    ),
    "Float8Tensor": (("q", "qdata"), ("scale", "scale")),
    "NVFP4Tensor": (("q", "qdata"), ("scale", "scale"), ("per_tensor_scale", "per_tensor_scale")),
    "MXTensor": (("q", "qdata"), ("scale", "scale")),
    "HostedInt8Parts": (("q", "qdata"), ("scale", "scale"), ("zero_point", "zero_point")),
}


class HostedInt8Parts:
    """An Int8Tensor's stored payload read as plain tensors (no torchao), fingerprinted like the Int8Tensor."""

    __slots__ = ("qdata", "scale", "zero_point")

    def __init__(
        self,
        qdata: Any,
        scale: Any,
        zero_point: Any = None,
    ):
        self.qdata = qdata
        self.scale = scale
        self.zero_point = zero_point


_CANONICAL_ROLE_ORDER = (
    "q",
    "scale",
    "zero_point",
    "per_tensor_scale",
    "act_quant_scale",
    "act_quant_zero_point",
    "act_pre_scale",
)
_ZERO_POINT_ROLES = ("zero_point", "act_quant_zero_point")


def _canonical_parts(tensor: Any, depth: int = 0) -> Optional[dict]:
    spec = _CANONICAL_PARTS.get(type(tensor).__name__)
    if spec is None or depth > 4:
        return None
    parts: dict = {}
    for role, attr in spec:
        value = getattr(tensor, attr, None)
        if value is None:
            continue
        if role == "inner":
            inner = _canonical_parts(value, depth + 1)
            if inner is None:
                return None
            parts.update(inner)
        else:
            parts[role] = value
    return parts if "q" in parts else None


def _all_zero(value: Any, torch: Any) -> bool:
    try:
        return not bool(torch.any(value.detach() != 0))
    except Exception:  # noqa: BLE001 - unknown: hash it
        return False


def _canonical_parts_of(role: str, value: Any, torch: Any) -> tuple:
    """(head, zero-copy payload) of ``_canonical_bytes``: hashing them in turn gives the same digest without the copies."""
    t = value.detach()
    if role == "q":
        head = f"q:{str(t.dtype).replace('torch.', '')}:{tuple(t.shape)}".encode("utf-8")
        return head, _packed_view(t, torch)
    t = t.reshape(-1)
    if role in _ZERO_POINT_ROLES:
        t = t.to(torch.int64)
    elif t.is_floating_point() and t.dtype is not torch.float64:
        t = t.to(torch.float32)
    head = f"{role}:{str(t.dtype).replace('torch.', '')}:{t.numel()}".encode("utf-8")
    return head, _packed_view(t, torch)


def _canonical_bytes(role: str, value: Any, torch: Any) -> bytes:
    """Version-stable bytes: ``q`` as stored; others flattened to float32 (exact for stored scales) / int64 zero point."""
    head, payload = _canonical_parts_of(role, value, torch)
    return head + payload.tobytes()


def canonical_weight_digest(tensor: Any) -> Optional[str]:
    """Version-neutral md5 of one quantized weight (None if unmodelled); an all-zero zero point equals none."""
    import hashlib

    import torch

    parts = _canonical_parts(tensor)
    if parts is None:
        return None
    digest = hashlib.md5()
    for role in _CANONICAL_ROLE_ORDER:
        value = parts.get(role)
        if value is None or (role in _ZERO_POINT_ROLES and _all_zero(value, torch)):
            continue
        head, payload = _canonical_parts_of(role, value, torch)
        digest.update(head)
        digest.update(payload)
    return digest.hexdigest()


# Weights hashed at once by the fingerprint check: md5 (over 2 KiB) and the torch casts release the GIL, so threads
# scale until memory bandwidth does. ``UNSLOTH_PREQUANT_FINGERPRINT_THREADS`` overrides (1 = serial).
FINGERPRINT_THREADS_ENV = "UNSLOTH_PREQUANT_FINGERPRINT_THREADS"
_FINGERPRINT_THREADS_DEFAULT = 8


def _fingerprint_threads() -> int:
    import os

    raw = str(os.environ.get(FINGERPRINT_THREADS_ENV, "")).strip()
    try:
        wanted = int(raw) if raw else _FINGERPRINT_THREADS_DEFAULT
    except ValueError:
        wanted = _FINGERPRINT_THREADS_DEFAULT
    return max(1, min(wanted, os.cpu_count() or 1))


def _digest_weights(state_dict: Any, select: Any, digest_of: Any) -> tuple:
    """({fqn: digest}, [uncovered fqns]) over the ``.weight`` entries ``select`` keeps, in state-dict order.

    ``digest_of`` returns None for an uncovered weight; a raise counts as uncovered. Runs on a thread pool."""
    items = state_dict.items() if hasattr(state_dict, "items") else ()
    picked = [
        (key, tensor)
        for key, tensor in items
        if (key == "weight" or str(key).endswith(".weight"))
        and (select is None or select(str(key)))
    ]

    def _one(tensor: Any) -> Optional[str]:
        try:
            return digest_of(tensor)
        except Exception:  # noqa: BLE001 -- an unreadable payload is uncovered, never a raise
            return None

    tensors = [tensor for _key, tensor in picked]
    threads = min(_fingerprint_threads(), len(picked))
    if threads > 1:
        from concurrent.futures import ThreadPoolExecutor
        with ThreadPoolExecutor(max_workers = threads, thread_name_prefix = "prequant-fp") as pool:
            values = list(pool.map(_one, tensors))
    else:
        values = [_one(tensor) for tensor in tensors]
    modules: dict = {}
    skipped: list = []
    for (key, _tensor), value in zip(picked, values):
        if value is None:
            skipped.append(key)
        else:
            modules[key] = value
    return modules, skipped


def canonical_weight_fingerprint(state_dict: Any, *, select: Any = None) -> dict:
    modules, skipped = _digest_weights(state_dict, select, canonical_weight_digest)
    return {
        "algo": CANONICAL_FINGERPRINT_ALGO,
        "count": len(modules),
        CANONICAL_FINGERPRINT_KEY: modules,
        "skipped": skipped,
    }


_V1_INT8_PREFIXES = (
    ("original_weight_tensor", "tensor_impl", "int_data"),  # torchao <= 0.17
    ("qdata",),  # torchao >= 0.18 Int8Tensor
)


def _v1_cross_generation_match(
    tensor: Any,
    recorded: str,
    hint: Optional[list] = None,
) -> bool:
    """Whether v1 digest ``recorded`` matches this int8 weight in any torchao generation's layout.

    Every variant hashes the full ``q`` and scale bytes, so changed values still fail. ``hint`` caches
    the last matching layout to try first."""
    import hashlib

    import torch

    parts = _canonical_parts(tensor)
    if parts is None or set(parts) - {"q", "scale", "zero_point"} or "scale" not in parts:
        return False
    q, scale = parts["q"], parts["scale"].detach()
    if q.dtype is not torch.int8 or q.dim() != 2:
        return False
    zp = parts.get("zero_point")
    if zp is not None and not _all_zero(zp, torch):
        return False
    n = q.shape[0]
    scales = {"stored": scale}
    for dtype in (torch.float32, torch.bfloat16):
        if scale.dtype is not dtype:
            cast = scale.to(dtype)
            if torch.equal(cast.to(scale.dtype), scale):
                scales[str(dtype)] = cast
    zero_points = {"none": None, "int8_zeros": torch.zeros(n, 1, dtype = torch.int8)}
    if zp is not None:
        zero_points["stored"] = zp
    layouts = [
        (p, sk, zk) for p in range(len(_V1_INT8_PREFIXES)) for sk in scales for zk in zero_points
    ]
    if hint and hint[0] in layouts:
        layouts.remove(hint[0])
        layouts.insert(0, hint[0])
    q_bytes = _packed_bytes(q, torch)
    bases: dict = {}
    for layout in layouts:
        prefix, sk, zk = layout
        if prefix not in bases:
            base = hashlib.md5()
            for name in _V1_INT8_PREFIXES[prefix]:
                base.update(name.encode("utf-8"))
            base.update(q_bytes)
            bases[prefix] = base
        digest = bases[prefix].copy()
        digest.update(b"scale")
        digest.update(_packed_bytes(scales[sk], torch))
        z = zero_points[zk]
        if z is not None:
            digest.update(b"zero_point")
            digest.update(_packed_bytes(z, torch))
        if digest.hexdigest() == recorded:
            if hint is not None:
                hint[:] = [layout]
            return True
    return False


FINGERPRINT_MODE_ENV = "UNSLOTH_PREQUANT_FINGERPRINT"
FINGERPRINT_MODES = ("full", "sample", "off")
FINGERPRINT_SAMPLE_RATE = 8


def _fingerprint_mode() -> str:
    """``full`` (default) / ``sample`` / ``off``. An unrecognised value reads as the default."""
    import os

    mode = (os.environ.get(FINGERPRINT_MODE_ENV) or "").strip().lower()
    return mode if mode in FINGERPRINT_MODES else "full"


def _fingerprint_sampled(fqn: str) -> bool:
    """Stable 1-in-8 by md5 of the name (``hash()`` is randomised per process)."""
    import hashlib
    return hashlib.md5(fqn.encode("utf-8")).digest()[0] % FINGERPRINT_SAMPLE_RATE == 0


def _verified_marker(path: Any, expected: dict) -> Optional[tuple]:
    """(marker file, identity) for a checkpoint whose full check passed before: same real file, size, mtime and
    recorded fingerprint. None when the file cannot be identified (then every load checks in full)."""
    import hashlib
    import json
    import os

    try:
        real = os.path.realpath(str(path))
        st = os.stat(real)
        from .diffusion_compile_cache import cache_root

        recorded = hashlib.md5(json.dumps(expected, sort_keys = True).encode("utf-8")).hexdigest()
        identity = {
            "path": real,
            "size": st.st_size,
            "mtime_ns": st.st_mtime_ns,
            "fingerprint": recorded,
        }
        name = hashlib.md5(real.encode("utf-8")).hexdigest() + ".json"
        return cache_root() / "prequant_verified" / name, identity
    except Exception:  # noqa: BLE001 -- unidentifiable: check in full
        return None


def _already_verified(marker: Optional[tuple]) -> bool:
    import json
    if marker is None:
        return False
    try:
        return json.loads(marker[0].read_text(encoding = "utf-8")) == marker[1]
    except Exception:  # noqa: BLE001 -- absent or unreadable marker: check in full
        return False


def _remember_verified(marker: Optional[tuple]) -> None:
    import json
    import os

    if marker is None:
        return
    try:
        marker[0].parent.mkdir(parents = True, exist_ok = True)
        tmp = marker[0].with_suffix(".tmp")
        tmp.write_text(json.dumps(marker[1], sort_keys = True), encoding = "utf-8")
        os.replace(tmp, marker[0])
    except Exception:  # noqa: BLE001 -- the next load just checks in full again
        pass


def _verify_packed_fingerprint(
    state_dict: Any,
    metadata: Any,
    *,
    logger: Any = None,
    path: Any = None,
) -> bool:
    """Mismatch drops to dense; missing or uncomputable block passes; clean results cached per file, keyed on size and mtime so changes recheck."""
    block = (metadata or {}).get("fingerprint")
    block = block if isinstance(block, dict) else {}
    canonical = bool(block.get(CANONICAL_FINGERPRINT_KEY))
    expected = block.get(CANONICAL_FINGERPRINT_KEY) if canonical else block.get("modules")
    if not expected or not isinstance(expected, dict):
        return True
    mode = _fingerprint_mode()
    marker = _verified_marker(path, expected) if path is not None and mode == "full" else None
    if _already_verified(marker):
        if logger is not None:
            logger.info(
                "diffusion.prequant: fingerprint verified on an earlier load of this unchanged file (%d weights)",
                len(expected),
            )
        return True
    if mode == "off":
        if logger is not None:
            logger.debug(
                "diffusion.prequant: fingerprint check disabled (%s=off)", FINGERPRINT_MODE_ENV
            )
        return True
    try:
        select = _fingerprint_sampled if mode == "sample" else None
        if canonical:
            actual = (
                canonical_weight_fingerprint(state_dict, select = select).get(
                    CANONICAL_FINGERPRINT_KEY
                )
                or {}
            )
        else:
            actual = packed_weight_fingerprint(state_dict, select = select).get("modules") or {}
    except Exception as exc:  # noqa: BLE001 -- an uncomputable fingerprint checks nothing
        _warn(logger, "fingerprint", exc)
        return True
    if not actual:
        _warn(
            logger,
            "fingerprint",
            RuntimeError(
                f"this build recognised none of the {len(expected)} quantized weights the "
                "checkpoint fingerprinted (a torchao payload rename?); loading it unverified"
            ),
        )
        return True
    checked = [k for k in expected if mode != "sample" or _fingerprint_sampled(k)]
    differing = sorted(k for k in checked if actual.get(k) != expected[k])
    reencoded = 0
    if differing and not canonical and hasattr(state_dict, "get"):
        still = []
        hint: list = []
        for key in differing:
            try:
                crossed = _v1_cross_generation_match(state_dict.get(key), expected[key], hint)
            except Exception:  # noqa: BLE001 -- not re-encodable: a real mismatch
                crossed = False
            if not crossed:
                still.append(key)
        reencoded = len(differing) - len(still)
        differing = still
    counted = mode != "sample" and len(actual) != len(expected)
    if not differing and not counted:
        if logger is not None:
            logger.info(
                "diffusion.prequant: fingerprint verified (%d of %d quantized weights, %s, %s%s)",
                len(checked),
                len(expected),
                mode,
                CANONICAL_FINGERPRINT_ALGO if canonical else FINGERPRINT_ALGO,
                f"; {reencoded} matched in another torchao generation's layout"
                if reencoded
                else "",
            )
        _remember_verified(marker)
        return True
    if logger is not None:
        logger.error(
            "diffusion.prequant: fingerprint MISMATCH (%d of %d checked weights differ, %d "
            "weights present vs %d recorded): %s. The checkpoint does not hold the bytes it was "
            "built with; falling back to the dense path",
            len(differing),
            len(checked),
            len(actual),
            len(expected),
            ", ".join(differing[:5]) or "counts only",
        )
    return False


HEADER_PROBE_ENV = "UNSLOTH_PREQUANT_HEADER_PROBE"
_HEADER_PROBE_TTL_S = 600.0
# Keyed by request values, so bounded: memo drops expired then LRU entries, the said-set its oldest.
_HEADER_PROBE_MAX = 256
_HEADER_PROBE_MEMO: dict = {}
_HEADER_PROBE_SAID: dict = {}
_HEADER_PROBE_LOCK = _threading.Lock()


def _memo_get(key: Any, now: float) -> Any:
    """The live memo entry for ``key`` (refreshed as most recent), or None; an expired one is dropped.
    Offline-cache verdicts (``key[0] == "local"``) never expire: the file under them cannot change
    without changing the key. Caller holds the lock."""
    hit = _HEADER_PROBE_MEMO.pop(key, None)
    if hit is None:
        return None
    if key[0] != "local" and now - hit[0] >= _HEADER_PROBE_TTL_S:
        return None
    _HEADER_PROBE_MEMO[key] = hit
    return hit


def _memo_put(key: Any, value: Any, now: float) -> None:
    """Insert ``key``, then trim expired entries and the oldest beyond ``_HEADER_PROBE_MAX``. Caller holds the lock."""
    _HEADER_PROBE_MEMO.pop(key, None)
    _HEADER_PROBE_MEMO[key] = value
    for old in [
        k
        for k, (at, _) in _HEADER_PROBE_MEMO.items()
        if k[0] != "local" and now - at >= _HEADER_PROBE_TTL_S
    ]:
        del _HEADER_PROBE_MEMO[old]
    while len(_HEADER_PROBE_MEMO) > _HEADER_PROBE_MAX:
        del _HEADER_PROBE_MEMO[next(iter(_HEADER_PROBE_MEMO))]


def _token_fingerprint(token: Optional[str]) -> str:
    """A short one-way tag for ``token`` (empty when none), so memo keys never hold the secret."""
    if not token:
        return ""
    import hashlib

    return hashlib.sha256(str(token).encode("utf-8", "replace")).hexdigest()[:16]


def _said_first(said: Any) -> bool:
    """Whether ``said`` is new (warn) rather than a repeat (info); remembers at most ``_HEADER_PROBE_MAX``.
    Caller holds the lock."""
    first = said not in _HEADER_PROBE_SAID
    _HEADER_PROBE_SAID.pop(said, None)
    _HEADER_PROBE_SAID[said] = True
    while len(_HEADER_PROBE_SAID) > _HEADER_PROBE_MAX:
        del _HEADER_PROBE_SAID[next(iter(_HEADER_PROBE_SAID))]
    return first


def _cached_snapshot_current(repo_id: str, local: str, token: Optional[str]) -> Optional[bool]:
    """Whether the Hub still serves the cached ``local`` snapshot of its file: True / False, or None when
    unanswerable (not a Hub-cache path, no network, no etag nor commit), which keeps the cached verdict.
    One HEAD, no range read. The blob name is the file's etag and the snapshot directory its commit, so
    either matching proves the cache is what ``hf_hub_download`` would open; an unrelated commit to the
    repo leaves the etag equal and costs no re-read."""
    import os

    parts = os.path.normpath(local).split(os.sep)
    if len(parts) < 3 or parts[-3] != "snapshots":
        return None
    commit, name = parts[-2], parts[-1]
    blob = os.path.basename(os.path.realpath(local))
    from .prequant_header_probe import hub_file_revision

    current = hub_file_revision(repo_id, name, token = token)
    if current is None or current == "missing":
        return None if current is None else False
    etag, hub_commit = current
    if (etag and etag == blob) or (hub_commit and hub_commit == commit):
        return True
    if etag or hub_commit:
        return False
    return None


class _CollectWarnings:
    def __init__(self) -> None:
        self.lines: list = []

    def warning(self, fmt: str, *args: Any) -> None:
        self.lines.append(fmt % args if args else fmt)

    def info(self, *args: Any, **kwargs: Any) -> None:
        pass

    debug = info


def _probe_logger(logger: Any) -> Any:
    if logger is not None:
        return logger
    try:
        from loggers import get_logger
        return get_logger(__name__)
    except Exception:  # noqa: BLE001 - no Studio logger: the stdlib one
        import logging
        return logging.getLogger(__name__)


def hosted_prequant_refusal(
    source: Any,
    scheme: str,
    *,
    base: Optional[str] = None,
    min_features: Optional[int] = None,
    fast_accum: Optional[bool] = None,
    component: Optional[str] = None,
    hf_token: Optional[str] = None,
    cache_dir: Optional[str] = None,
    local_files_only: bool = False,
    logger: Any = None,
) -> Optional[str]:
    """Refusal reason for a hosted safetensors source from its header alone; None when usable or
    unknown, or when the first existing candidate is a .pt (never opened here); never raises."""
    import os
    import time

    if (os.environ.get(HEADER_PROBE_ENV) or "").strip().lower() in ("0", "false", "no", "off"):
        return None
    if getattr(source, "kind", None) != "repo" or not scheme:
        return None
    saved_failure = getattr(_LAST_FAILURE, "text", None)
    try:
        names = [
            n
            for n in candidate_filenames_of(source)
            if restricted_prequant_load_supported(scheme, n)
        ]
        if not names:
            return None
        local = cached_checkpoint_path(source, cache_dir = cache_dir, names = names)
        # A ``scoped_local_files_only`` load is offline too: a cache miss must not become Hub requests.
        offline = bool(local_files_only or _LOCAL_FILES_ONLY.get() or hub_offline())
        if local is None and offline:
            return None
        request = (scheme, base or "", min_features, fast_accum, component or "")
        # Keyed by credentials: an anonymous 401 (unknown) must not stand in for the authenticated probe.
        auth = _token_fingerprint(hf_token)
        if local is not None:
            try:
                st = os.stat(local)
                # Offline the cached file is what loads; online it may have been re-uploaded, so revalidate.
                key = (
                    "local" if offline else "cached",
                    os.path.realpath(local),
                    st.st_size,
                    st.st_mtime_ns,
                    request,
                    "" if offline else auth,
                )
            except OSError:
                return None
        else:
            key = ("hub", source.location, tuple(names), request, auth)
        now = time.monotonic()
        with _HEADER_PROBE_LOCK:
            hit = _memo_get(key, now)
        if hit is not None:
            return hit[1]

        from .prequant_header_probe import read_hub_checkpoint_header, read_local_checkpoint_header

        header, name = None, None
        # False when the Hub could not answer (401/403, network): not memoised, so the next probe retries.
        answered = True
        hub_names = names
        from .prequant_safetensors import is_safetensors_checkpoint

        # Only a safetensors header is ever read, so a cached pickle is "unknown" and not worth a HEAD.
        if local is not None and not offline and is_safetensors_checkpoint(local):
            if _cached_snapshot_current(source.location, local, hf_token) is False:
                # Judge what the download would fetch; a name now 404ing falls through to the next one.
                cached_name = os.path.basename(local)
                at = names.index(cached_name) if cached_name in names else -1
                hub_names, local = (names[at:] if at >= 0 else [cached_name]), None
        if local is not None:
            header, name = read_local_checkpoint_header(local), os.path.basename(local)
        else:
            for candidate in hub_names:
                header, exists = read_hub_checkpoint_header(
                    source.location, candidate, token = hf_token
                )
                if exists is False:
                    continue
                answered = exists is not None
                name = candidate
                break
        reason = None
        if header is not None:
            collect = _CollectWarnings()
            try:
                if not isinstance(header["metadata"], dict):
                    raise ValueError("metadata is not a JSON object")
                ok = _validate_checkpoint(
                    {"format": header["format"], "metadata": header["metadata"]},
                    scheme,
                    base or "",
                    collect,
                    min_features = min_features,
                    fast_accum = fast_accum,
                    component = component,
                    metadata_only = True,
                )
            except Exception as exc:  # noqa: BLE001 - a PARSED header the loader cannot validate
                # The loader raises on it too, so this is a refusal, not "unknown".
                ok = False
                collect.lines.insert(
                    0, f"malformed checkpoint metadata ({type(exc).__name__}: {exc})"[:300]
                )
            if not ok:
                reason = (collect.lines[0] if collect.lines else "incompatible metadata").replace(
                    "diffusion.prequant: ", ""
                )
                said = (source.location, name, reason)
                with _HEADER_PROBE_LOCK:
                    first = _said_first(said)
                where = (
                    "cached file"
                    if local is not None
                    else f"{(header.get('size') or 0) / 1e9:.1f} GB file, not downloaded"
                )
                (_probe_logger(logger).warning if first else _probe_logger(logger).info)(
                    "diffusion.prequant: skipping hosted %s checkpoint %s/%s (%s; read %d header "
                    "bytes): %s; using the fallback path instead",
                    scheme,
                    source.location,
                    name,
                    where,
                    int(header.get("bytes_read") or 0),
                    reason,
                )
        with _HEADER_PROBE_LOCK:
            if answered:
                _memo_put(key, (now, reason), now)
        return reason
    except Exception:  # noqa: BLE001 - a probe that cannot answer leaves today's behaviour
        return None
    finally:
        _LAST_FAILURE.text = saved_failure


def _planning_min_features(min_features: Optional[int]) -> Optional[int]:
    if min_features is not None:
        return min_features
    try:
        from .diffusion_transformer_quant import DEFAULT_MIN_LINEAR_FEATURES
        return DEFAULT_MIN_LINEAR_FEATURES
    except Exception:  # noqa: BLE001 - no quant module: skip the check, as before
        return None


def usable_prequant_source(
    fam: Any,
    scheme: str,
    *,
    path_override: Optional[str] = None,
    base_repo: Optional[str] = None,
    local_files_only: bool = False,
    hf_token: Optional[str] = None,
    cache_dir: Optional[str] = None,
    min_features: Optional[int] = None,
) -> Optional[PrequantSource]:
    """``resolve_prequant_source``, but a local path counts only when the loader would accept it:
    inside the allowlist AND present on disk AND baked for THIS scheme. Otherwise resolves to None
    so memory planning falls back to dense-fit checks up front, instead of the loader refusing the
    path only after the resident pipeline was evicted and dense bf16 materialises under a plan that
    never budgeted for it (evict-then-OOM). Hosted-repo sources are unaffected.

    The scheme check matters most under ``auto``, which picks a scheme the user never named: an int8
    override must not read as an available fp8 pre-quant just because the file exists. A checkpoint
    whose scheme cannot be read is treated as not usable, matching every other unknown here, since
    the loader would reject it too.

    An install that cannot restrict the load has no usable source AT ALL, hosted included: the
    loader refuses every checkpoint there, and a plan that had already dropped the dense shards for
    one would find that out after the eviction. That question is asked of the RESOLVED names rather
    than of the scheme alone, because it has different answers for the two containers: a repo whose
    primary artifact is safetensors is usable on an install that could not open a pickle at all, and
    resolving first is what lets the source say so. Any one loadable name is enough, since the
    resolver tries them in order and the first that exists wins.

    ``local_files_only`` / ``hf_token`` / ``cache_dir`` are the load's own, handed to the hosted header
    probe so planning asks exactly what the loader will: an offline load makes no Hub request here
    either, and a gated repo is read with the caller's token. ``base_repo`` doubles as the base the
    probe checks ``base_model_id`` against, as ``load_prequantized_transformer`` does. ``min_features``
    defaults to ``DEFAULT_MIN_LINEAR_FEATURES``, the Linear filter every loader of these checkpoints
    enforces, so a header baked under another filter is refused here rather than after its download.
    """
    src = resolve_prequant_source(fam, scheme, path_override = path_override, base_repo = base_repo)
    if src is None:
        return None
    # getattr: planners pass lightweight stand-ins; a missing attribute must not cause a dense fallback.
    candidates = (
        [src.location]
        if getattr(src, "kind", None) == "path"
        else list(candidate_filenames_of(src))
    ) or [None]
    readable = [n for n in candidates if restricted_prequant_load_supported(scheme, n)]
    if not readable:
        return None
    # Guessed safetensors names need a declaration or a cache hit, else a .pt-only repo wastes 6 GB.
    from .prequant_safetensors import is_safetensors_checkpoint

    if src.kind == "repo" and all(is_safetensors_checkpoint(n) for n in readable):
        declared = set(getattr(src, "declared_filenames", ()) or ())
        # Cache probe uses only READABLE names: a cached legacy pickle proves nothing about safetensors.
        if (
            not any(n in declared for n in readable)
            and cached_checkpoint_path(src, cache_dir = cache_dir, names = readable, online = False)
            is None
        ):
            return None
    if src.kind == "path":
        if not local_prequant_path_ready(src.location):
            return None
        if local_prequant_scheme(src.location) != scheme:
            return None
        if not _comfy_prequant_family(fam):
            # only the image denoiser loader reads a ComfyUI-format file; anywhere else it would be refused at load
            try:
                from .diffusion_comfy_quant import scan_comfy_quant

                from os.path import expanduser
                if scan_comfy_quant(expanduser(src.location)) is not None:
                    return None
            except Exception:  # noqa: BLE001 -- unreadable: the scheme check above already decided
                pass
    # Refused metadata = no source, judged with the loader's base and fetch rules, so planning stages dense.
    if (
        src.kind == "repo"
        and hosted_prequant_refusal(
            src,
            scheme,
            base = base_repo,
            min_features = _planning_min_features(min_features),
            hf_token = hf_token,
            cache_dir = cache_dir,
            local_files_only = local_files_only,
        )
        is not None
    ):
        return None
    return src


def cached_checkpoint_path(
    source: Any,
    *,
    cache_dir: Optional[str] = None,
    names: Optional[Sequence[str]] = None,
    online: Optional[bool] = None,
) -> Optional[str]:
    """Searches both cache roots (live pin, then import-time constant) and every candidate name in preference order; an unopenable name is never a hit."""
    roots = (cache_dir, None) if cache_dir else (None,)
    wanted = set(names) if names is not None else None

    def _readable(name: str) -> bool:
        try:
            return bool(restricted_prequant_load_supported(None, name))
        except Exception:  # noqa: BLE001 - a pure lookup that never raises, as documented above
            return True

    candidates = [
        n
        for n in candidate_filenames_of(source)
        if (wanted is None or n in wanted) and _readable(n)
    ]
    location = getattr(source, "location", None)
    if getattr(source, "kind", None) == "repo":
        mirrored = _first_mirrored(location, candidates, _readable)
        if mirrored is not None:
            return mirrored
    hits: dict = {}

    def _hit(name: str) -> Optional[str]:
        if name not in hits:
            hits[name] = next(
                (
                    h
                    for h in (_cached_in_root(source, root, name) for root in roots)
                    if h is not None
                ),
                None,
            )
        return hits[name]

    ordered = prefer_cached_pickle_twins(
        location, candidates, readable = _readable, cache_dir = cache_dir, log = False
    )
    name = first_cached_as_resolved(
        location,
        ordered,
        is_cached = lambda n: _hit(n) is not None,
        online = online,
        cache_dir = cache_dir,
    )
    return _hit(name) if name else None


def _cached_in_root(
    source: Any,
    root: Optional[str],
    name: Optional[str] = None,
) -> Optional[str]:
    """One checkpoint name's path inside ONE cache root, or None. Defaults to the primary name; the
    resolver passes ``fallback_filename`` once the primary turns out to be absent. Never raises."""
    if source is None or getattr(source, "kind", None) != "repo":
        return None
    name = name or getattr(source, "filename", None)
    if not name:
        return None
    try:
        import os

        from huggingface_hub import try_to_load_from_cache
    except Exception:  # noqa: BLE001 - no cache API to ask: treat as not cached
        return None
    try:
        hit = try_to_load_from_cache(source.location, name, cache_dir = root)
    except Exception:  # noqa: BLE001 - a malformed cache entry is not a hit
        return None
    # a str is the cached path; a miss is None and a known-absent file is a sentinel object
    return hit if isinstance(hit, str) and os.path.isfile(hit) else None


def prequant_checkpoint_cached(
    source: Any,
    *,
    cache_dir: Optional[str] = None,
    online: Optional[bool] = None,
) -> bool:
    """True when ``source`` resolves from the cache, i.e. enabling prequant costs no download."""
    return cached_checkpoint_path(source, cache_dir = cache_dir, online = online) is not None


def _pin_kernel_preference(state_dict: Any, logger: Any = None) -> int:
    """Rewrites fp8 weights to plain-torch kernel: AUTO picks mslk, which lacks a fake impl; weights stay bit-identical, so checkpoint sha256 still holds."""
    try:
        from torchao.quantization.quantize_.common.kernel_preference import KernelPreference
    except Exception:  # noqa: BLE001 -- enum moved or absent: leave the checkpoint as saved
        return 0
    pinned = 0
    for t in state_dict.values():
        if getattr(t, "kernel_preference", None) not in (None, KernelPreference.TORCH):
            try:
                t.kernel_preference = KernelPreference.TORCH
                pinned += 1
            except Exception:  # noqa: BLE001 -- frozen subclass: nothing else to try
                pass
    if pinned and logger is not None:
        logger.info("diffusion.prequant: pinned %d weights to the plain-torch fp8 kernel", pinned)
    return pinned


def _reports_rejected_cache_entry(fn: Any) -> Any:
    """Report an unusable cache entry so the dense fallback build replaces it; a forced fp8 accumulate mismatch is
    the request's choice, not a fault, and leaves the entry alone."""

    @functools.wraps(fn)
    def wrapper(transformer_cls: Any, base: str, source: Any, *args: Any, **kwargs: Any) -> Any:
        out = fn(transformer_cls, base, source, *args, **kwargs)
        if out is None and getattr(source, "kind", None) == "path":
            try:
                if not hosted_fast_accum_conflict(
                    str(kwargs.get("scheme") or ""), kwargs.get("fast_accum")
                ):
                    from .diffusion_prequant_cache import note_rejected
                    note_rejected(source.location, kwargs.get("logger"))
            except Exception:  # noqa: BLE001 - bookkeeping never changes the load's outcome
                pass
        return out

    return wrapper


def _engage_nvfp4_backend(
    transformer: Any,
    metadata: Any,
    device: Any,
    *,
    family: Optional[str] = None,
    base: Optional[str] = None,
    logger: Any = None,
) -> int:
    """Moves the NVFP4 transformer to its backend; the flashinfer warning fires here, not in planning."""
    from .diffusion_nvfp4_linear import convert_nvfp4_backend
    from .diffusion_nvfp4_ops import select_nvfp4_backend

    converted = convert_nvfp4_backend(
        transformer, metadata, select_nvfp4_backend(device), logger = logger
    )
    if converted:
        try:
            from .diffusion_nvfp4_gate import warn_flashinfer_mismatch_once
            md = metadata if isinstance(metadata, dict) else {}
            # The checkpoint's own base first: ``base`` can be the ungated mirror the weights were fetched from.
            for base_repo in dict.fromkeys(b for b in (md.get("base_model_id"), base) if b):
                if warn_flashinfer_mismatch_once(
                    family or md.get("family"), base_repo, logger, backend_active = True
                ):
                    break
        except Exception:  # noqa: BLE001 -- a warning, never a load error
            pass
    return converted


@_reports_rejected_cache_entry
def load_prequantized_transformer(
    transformer_cls: Any,
    base: str,
    source: PrequantSource,
    *,
    device: str,
    dtype: Any,
    hf_token: Optional[str] = None,
    scheme: str,
    min_features: Optional[int] = None,
    fast_accum: Optional[bool] = None,
    cache_dir: Optional[str] = None,
    prepare_model: Optional[Any] = None,
    config_subfolder: str = "transformer",
    component: Optional[str] = None,
    local_files_only: bool = False,
    logger: Any = None,
    placement_device: Optional[str] = None,
    family: Optional[str] = None,
    into: Optional[Any] = None,
    host_copy_follows: bool = False,
) -> Optional[Any]:
    """Load the pre-quantized transformer described by ``source`` onto ``device``.

    ``into``: an already-built DENSE transformer to load the checkpoint into instead of a fresh ``from_config``
    skeleton (the pipeline-quant path, whose denoiser came with the pipeline). Its key set must equal the
    checkpoint's; it stays where its weights already are, and on a refusal before assignment it is left dense.

    ``family`` (the Studio family name) is what a ComfyUI-format artifact needs to pick the layers Studio's
    own ``scheme`` quantizes; Studio's own checkpoints record it themselves.

    ``placement_device`` (default ``device``) is where the module is materialised; ``device`` selects kernels.

    ``cache_dir`` is the live Hub cache root, as every other loader call pins it: unset, a fetch
    lands under huggingface_hub's import-time constant, so a mid-session cache change re-downloads
    into a root Unsloth no longer reads.

    ``component`` must match the checkpoint's (MoE experts share every other field); ``prepare_model``
    runs between ``from_config`` and ``load_state_dict``, the one window to reshape the skeleton. A
    declared activation rotation is installed unconditionally: a miss renders wrong pixels silently.

    Returns the placed transformer, or None on any problem (missing / mismatched / unreadable
    checkpoint, unsupported meta-init, or a rotation this build cannot apply exactly) so the caller
    falls back to dense-quantise. Best-effort: never raises for an unavailable artifact.
    """
    _LAST_FAILURE.text = None
    try:
        # Local request paths are arbitrary weights: always read weights_only, even when allowlisted.
        if source.kind == "path" and not _local_prequant_path_allowed(source.location):
            _warn(
                logger,
                f"{scheme}:path",
                RuntimeError(
                    "request-supplied local pre-quant path refused (loading arbitrary weights "
                    f"into the served model); set {ALLOW_LOCAL_PREQUANT_PATH_ENV} to an "
                    "allowlisted directory containing trusted checkpoints to permit it",
                ),
            )
            return None

        if source.kind == "repo":
            refusal = hosted_prequant_refusal(
                source,
                scheme,
                base = base,
                min_features = min_features,
                fast_accum = fast_accum,
                component = component,
                hf_token = hf_token,
                cache_dir = cache_dir,
                local_files_only = local_files_only,
                logger = logger,
            )
            if refusal is not None:
                _LAST_FAILURE.text = _ABS_PATH.sub("", f"ValueError: {refusal}")[:300]
                return None

        path = _resolve_checkpoint_path(
            source,
            hf_token,
            cache_dir,
            local_files_only = local_files_only,
            scheme = scheme,
            logger = logger,
        )
        if path is None:
            return None
        if source.kind == "path":
            # Verify the payload digest: the manifest size check misses same-size corruption.
            from .diffusion_prequant_cache import path_in_cache, verify_entry
            if path_in_cache(path) and not verify_entry(path, logger):
                _LAST_FAILURE.text = (
                    "ValueError: local pre-quant cache entry failed its payload digest"
                )
                return None

        # A ComfyUI-format file rebuilds into the same torchao weights as Studio's own checkpoint of this scheme.
        from .diffusion_comfy_quant import load_comfy_prequant, scan_comfy_quant

        comfy_scan = scan_comfy_quant(path)
        comfy_rotated = False
        if comfy_scan is not None:
            if into is not None:
                raise ValueError(
                    "a ComfyUI-format checkpoint cannot be loaded into an existing transformer"
                )
            if prepare_model is not None or (component and component != DEFAULT_PREQUANT_COMPONENT):
                raise ValueError(
                    "a ComfyUI-format checkpoint is only read as a whole denoiser, not as the "
                    f"{component or 'reshaped'} component"
                )
            transformer = load_comfy_prequant(
                transformer_cls,
                path,
                scheme = scheme,
                base = base,
                family = family,
                dtype = dtype,
                hf_token = hf_token,
                cache_dir = cache_dir,
                local_files_only = local_files_only,
                fast_accum = fast_accum,
                min_features = min_features,
                config_subfolder = config_subfolder,
                logger = logger,
            )
            # ComfyUI files never pass through _load_prequant_checkpoint, which installs this for Studio's own.
            from .diffusion_transformer_quant import _resolve_fast_accum

            _install_fp8_unit_scale(fast_accum = _resolve_fast_accum(fast_accum))
            from .diffusion_convrot import declares_rotation, is_rotated_linear, warm_rotation_cache

            comfy_rotated = any(is_rotated_linear(m) for m in transformer.modules())
            metadata = {
                "family": family,
                "torch_dtype": str(dtype).replace("torch.", ""),
                "comfy_format": True,
            }
        else:
            # Pickles load only under the ALLOWLIST, never free-running: a mutated file must fail,
            # not run.
            ckpt = _read_prequant_for(
                path,
                placement_device or device,
                logger,
                host_copy_follows = host_copy_follows,
                scheme = scheme,
            )
            if not _validate_checkpoint(
                ckpt,
                scheme,
                base,
                logger,
                min_features = min_features,
                fast_accum = fast_accum,
                component = component,
            ):
                return None
            state_dict = ckpt["state_dict"]
            # The only check reading what the artifact HOLDS: corruption after build passes the rest.
            if not _verify_packed_fingerprint(
                state_dict, ckpt.get("metadata") or {}, logger = logger, path = path
            ):
                return None
            _repair_legacy_checkpoint(ckpt, scheme, logger)
            _pin_kernel_preference(state_dict, logger)

            # Read from the root that supplied the checkpoint; a pinned root may be gone after a
            # cache change.
            config = (
                None
                if into is not None
                else _load_transformer_config(
                    transformer_cls,
                    base,
                    hf_token,
                    cache_dir,
                    path,
                    config_subfolder,
                    local_files_only = local_files_only,
                )
            )
            from accelerate import init_empty_weights

            metadata = ckpt.get("metadata") or {}
            if into is not None:
                transformer = into
                _load_into_dense(transformer, state_dict, prepare_model)
            else:
                with init_empty_weights():
                    transformer = transformer_cls.from_config(config)
                if prepare_model is not None:
                    prepare_model(transformer, metadata)
                _prepare_outlier_buffers(transformer, state_dict)
                transformer.load_state_dict(state_dict, strict = True, assign = True)
            if into is None and _has_meta_tensors(transformer):
                # Non-persistent buffers (built in __init__, absent from the state dict) stay on meta. Rebuild on CPU so
                # they hold real values, then re-assign the quantized weights; dense bf16 never reaches the GPU.
                transformer = transformer_cls.from_config(config)
                # The retry builds a new module, so prepare_model must run again or the state dict
                # mismatches.
                if prepare_model is not None:
                    prepare_model(transformer, metadata)
                _prepare_outlier_buffers(transformer, state_dict)
                transformer.load_state_dict(state_dict, strict = True, assign = True)

            # Online half of the rotation, applied here so no route skips it: after load_state_dict (meta retry rebuilds), before small-M padding reparents Linears.
            from .diffusion_convrot import (
                apply_activation_rotation,
                declares_rotation,
                warm_rotation_cache,
            )

            apply_activation_rotation(transformer, metadata, logger = logger)

            if scheme == "nvfp4":
                from .diffusion_nvfp4_act_quant import install_nvfp4_act_quant_patch

                # Layers left on torchao quantise activations through NVFP4Tensor.to_nvfp4 at run time.
                install_nvfp4_act_quant_patch(logger)
                _engage_nvfp4_backend(
                    transformer,
                    metadata,
                    device,
                    family = family,
                    base = base,
                    logger = logger,
                )
            # assign=True shares the tensors: a live reference doubles the peak on unified memory.
            del state_dict
            del ckpt

        from .diffusion_fast_load import fast_upload

        with fast_upload([transformer], placement_device or device, logger = logger):
            transformer = transformer.to(placement_device or device)
        if declares_rotation(metadata) or comfy_rotated:
            try:
                import torch

                on = next(iter(transformer.parameters()), None)
                dtype = getattr(
                    torch, str(metadata.get("torch_dtype") or "bfloat16"), torch.bfloat16
                )
                # a host-placed module still computes on ``device``
                warm_rotation_cache(
                    transformer,
                    on.device if on is not None and placement_device is None else device,
                    dtype,
                )
            except Exception:  # noqa: BLE001
                pass
        # Small-M padding, else quantised small-M linears raise in _int_mm. After load and .to().
        from .diffusion_transformer_quant import (
            apply_small_m_padding,
            apply_zero_row_guard,
            quantize_runtime_leftovers,
            quantize_streamed_weight_only,
        )

        # Must run before padding (it reparents Linears); a failure keeps the artifact, leftovers stay dense.
        try:
            quantize_runtime_leftovers(
                transformer,
                scheme,
                metadata.get("family") or family,
                metadata.get("exclude_name_tokens"),
                min_features = int(metadata.get("min_features") or min_features or 512),
                device = device,
                logger = logger,
            )
        except Exception as exc:  # noqa: BLE001 - optimisation only
            _warn(logger, f"{scheme}:runtime leftovers", exc)
        # Streamed scope only; a no-op on an artifact whose modulations are already weight-only. Never raises.
        quantize_streamed_weight_only(
            transformer,
            scheme,
            metadata.get("family") or family,
            min_features = int(metadata.get("min_features") or min_features or 512),
            device = device,
            logger = logger,
        )

        apply_small_m_padding(transformer, scheme, metadata.get("family"), logger = logger)
        apply_zero_row_guard(transformer, scheme, metadata.get("family"), logger = logger)
        # from_config starts in train mode; match from_pretrained's eval().
        try:
            transformer.eval()
        except Exception:  # noqa: BLE001 - eval() is best-effort
            pass
        if scheme == "nvfp4":
            try:
                from .diffusion_nvfp4_linear import nvfp4_prewarm
                nvfp4_prewarm(transformer, (1,), logger = logger)
            except Exception as exc:  # noqa: BLE001 - an untuned layer still runs
                _warn(logger, f"{scheme}:prewarm", exc)
        try:
            transformer._unsloth_runtime_quant = scheme
        except Exception:  # noqa: BLE001 - marker is best-effort
            pass
        try:
            # Records the file that really loaded, since the provenance label cannot tell primary from fallback.
            transformer._unsloth_prequant_path = path
        except Exception:  # noqa: BLE001 - marker is best-effort
            pass
        if logger is not None:
            logger.info(
                "diffusion.prequant: loaded %s checkpoint (%s) onto %s",
                scheme,
                source.kind,
                placement_device or device,
            )
        return transformer
    except PrequantIntoError:
        # Partly assigned: falling back would mix two builds.
        raise
    except Exception as exc:  # noqa: BLE001 - fall back to the dense-quantise path
        _warn(logger, f"{scheme}:{source.kind}", exc)
        return None


def _entry_not_found_errors() -> tuple:
    """LocalEntryNotFoundError subclasses EntryNotFoundError on both hub majors, so catch it first."""
    try:
        from huggingface_hub.errors import EntryNotFoundError
    except Exception:  # noqa: BLE001 - older/newer hub layouts

        class EntryNotFoundError(Exception):  # type: ignore[no-redef]
            pass

    try:
        from huggingface_hub.errors import LocalEntryNotFoundError
    except Exception:  # noqa: BLE001

        class LocalEntryNotFoundError(EntryNotFoundError):  # type: ignore[no-redef]
            pass

    return EntryNotFoundError, LocalEntryNotFoundError


def _download_checkpoint_name(
    source: PrequantSource,
    name: str,
    hf_token: Optional[str],
    cache_dir: Optional[str],
    *,
    propagate_missing: bool,
    local_files_only: bool = False,
) -> str:
    """A remote 404 must propagate while another name is still to try, or a stale other-root copy wins."""
    from huggingface_hub import hf_hub_download

    EntryNotFoundError, LocalEntryNotFoundError = _entry_not_found_errors()

    if cache_dir is not None and _cached_in_root(source, cache_dir, name) is None:
        elsewhere = _cached_in_root(source, None, name)
        if elsewhere is not None:
            try:
                return hf_hub_download(
                    repo_id = source.location,
                    filename = name,
                    token = hf_token,
                    cache_dir = None,
                    local_files_only = local_files_only,
                )
            except LocalEntryNotFoundError:  # offline with the copy right there: use it
                return elsewhere
            except EntryNotFoundError:
                if not propagate_missing:
                    return elsewhere
                raise
            except Exception:  # noqa: BLE001 - revalidation is a bonus, never a new failure
                return elsewhere
    return hf_hub_download(
        repo_id = source.location,
        filename = name,
        token = hf_token,
        cache_dir = cache_dir,
        local_files_only = local_files_only,
    )


def _resolve_checkpoint_path(
    source: PrequantSource,
    hf_token: Optional[str],
    cache_dir: Optional[str] = None,
    *,
    local_files_only: bool = False,
    scheme: Optional[str] = None,
    logger: Any = None,
) -> Optional[str]:
    """Same scheme filter as the plan, else a two-container repo fetches both; local-only must not fetch."""
    if source.kind == "path":
        import os

        if nvfp4_pickle_name(scheme, source.location):
            raise ValueError(
                NVFP4_SAFETENSORS_ONLY_MESSAGE.format(what = "the local pre-quant override")
            )
        # Expand ~ (the allowlist gate already did), else os.path.isfile sees a literal "~".
        expanded = os.path.expanduser(source.location)
        return expanded if os.path.isfile(expanded) else None
    if source.kind == "repo":
        EntryNotFoundError, LocalEntryNotFoundError = _entry_not_found_errors()
        # nvfp4 never falls back to a pickle name, whatever the source carries.
        names = without_nvfp4_pickles(scheme, candidate_filenames_of(source))
        all_names = list(names)
        if scheme is not None:
            readable = [n for n in names if restricted_prequant_load_supported(scheme, n)]
            if not readable and _is_nvfp4_scheme(scheme) and names:
                raise ValueError(
                    f"the hosted nvfp4 checkpoint ({source.location}) cannot be read here: "
                    f"{_unreadable_why(scheme)}"
                )
            # Empty filter means it should never have been offered; returning None would hide the refusal.
            names = readable or names
        if not names:
            return None
        # Mirror first for EVERY name: else a Hub copy of an earlier name is downloaded and the mirror never used.
        mirrored = _first_mirrored(
            source.location, names, lambda n: restricted_prequant_load_supported(scheme, n)
        )
        if mirrored is not None:
            return mirrored
        names = prefer_cached_pickle_twins(
            source.location,
            names,
            readable = lambda n: restricted_prequant_load_supported(scheme, n),
            cache_dir = cache_dir,
            logger = logger,
            roots = tuple(dict.fromkeys((cache_dir, None))),  # what _download_checkpoint_name reuses
        )
        for index, name in enumerate(names):
            last = index == len(names) - 1
            try:
                path = _download_checkpoint_name(
                    source,
                    name,
                    hf_token,
                    cache_dir,
                    # Only the last name may swallow its 404; earlier ones must propagate so the next is tried.
                    propagate_missing = not last,
                    local_files_only = local_files_only,
                )
                explain_container_choice(
                    source.location,
                    name,
                    all_names,
                    names,
                    readable = lambda n: restricted_prequant_load_supported(scheme, n),
                    logger = logger,
                )
                return path
            except LocalEntryNotFoundError:
                # Before its base class: online, this means the Hub is unreachable, not that the name
                # is absent. Offline, treat it as a 404.
                if not local_files_only or last:
                    cached = (
                        None
                        if last
                        else cached_checkpoint_path(
                            source, cache_dir = cache_dir, names = names[index + 1 :], online = False
                        )
                    )
                    if cached is None:
                        raise
                    return cached
            except EntryNotFoundError:
                if last:
                    raise
    return None


def _config_cache_roots(checkpoint_path: str, cache_dir: Optional[str]) -> tuple:
    """Checkpoint's own cache root first: the checkpoint lookup can answer from the import-time root."""
    if cache_dir is None:
        return (None,)
    import os

    try:
        # normcase: Windows path case differences would reverse the order below.
        root = os.path.normcase(os.path.realpath(cache_dir))
        real = os.path.normcase(os.path.realpath(checkpoint_path))
        under_live = real == root or real.startswith(root + os.sep)
    except Exception:  # noqa: BLE001 - an unresolvable path keeps today's order
        under_live = True
    return (cache_dir, None) if under_live else (None, cache_dir)


def _load_transformer_config(
    transformer_cls: Any,
    base: str,
    hf_token: Optional[str],
    cache_dir: Optional[str],
    checkpoint_path: str,
    subfolder: str = "transformer",
    *,
    local_files_only: bool = False,
) -> Any:
    """``transformer_cls.load_config`` against the checkpoint's cache root, then the other one. The
    config is a few KB, but it is still a Hub fetch, and a load that promised to reach nothing
    has to keep that promise for the small files too."""
    last: Optional[BaseException] = None
    for root in _config_cache_roots(checkpoint_path, cache_dir):
        try:
            from .diffusion_families import pinned_revision_kwargs
            return transformer_cls.load_config(
                base,
                subfolder = subfolder,
                token = hf_token,
                cache_dir = root,
                local_files_only = local_files_only,
                **pinned_revision_kwargs(base),
            )
        except Exception as exc:  # noqa: BLE001 - try the other root before giving up
            last = exc
    raise last  # type: ignore[misc]


# By NAME: re-exported under several paths, and this check must not import torchao.
_FLOAT8_TENSOR_CLASS = "Float8Tensor"


def _fp8_activation_floor_present(
    state_dict: Any,
    logger: Any,
    *,
    warn: bool = True,
) -> bool:
    """True unless the first Float8Tensor has no activation lower bound (by class: NVFP4Tensor lacks one too)."""
    from .diffusion_transformer_quant import TQ_FP8

    try:
        items = state_dict.items() if hasattr(state_dict, "items") else ()
        for name, tensor in items:
            if type(tensor).__name__ != _FLOAT8_TENSOR_CLASS:
                continue
            kwargs = getattr(tensor, "act_quant_kwargs", None)
            if kwargs is None:
                continue
            if getattr(kwargs, "hp_value_lb", None):
                return True
            if not warn:
                return False
            _warn(
                logger,
                TQ_FP8,
                ValueError(
                    f"fp8 checkpoint has no activation scale floor on {name!r} "
                    "(built before activation_value_lb); a zero activation row renders black. "
                    "Rebuild it"
                ),
            )
            return False
    except Exception:  # noqa: BLE001 -- an unreadable state dict is the other checks' problem
        return True
    return True


def _fp8_kwargs_missing_floor(tensor: Any) -> Optional[Any]:
    if type(tensor).__name__ != _FLOAT8_TENSOR_CLASS:
        return None
    kwargs = getattr(tensor, "act_quant_kwargs", None)
    if kwargs is None or getattr(kwargs, "hp_value_lb", None):
        return None
    return kwargs


def _fp8_activation_floor_restorable(state_dict: Any) -> bool:
    """torchao's fp8 weight quantiser ignores hp_value_lb, so only the activation floor differs."""
    try:
        items = state_dict.items() if hasattr(state_dict, "items") else ()
        for _name, tensor in items:
            kwargs = _fp8_kwargs_missing_floor(tensor)
            if kwargs is None:
                continue
            if (
                not hasattr(kwargs, "hp_value_lb")
                or getattr(kwargs, "hp_value_ub", None) is not None
            ):
                return False
    except Exception:  # noqa: BLE001 -- cannot prove it: keep refusing
        return False
    return True


def _restore_fp8_activation_floor(state_dict: Any, logger: Any = None) -> int:
    """Write the runtime activation floor into every unfloored Float8Tensor; returns how many.
    Fresh kwargs per tensor: a pickle may share one instance between tensors."""
    import copy
    import dataclasses

    from .diffusion_transformer_quant import FP8_ACTIVATION_VALUE_LB

    restored = 0
    for _name, tensor in list(state_dict.items()):
        kwargs = _fp8_kwargs_missing_floor(tensor)
        if kwargs is None:
            continue
        if dataclasses.is_dataclass(kwargs) and not isinstance(kwargs, type):
            fixed = dataclasses.replace(kwargs, hp_value_lb = FP8_ACTIVATION_VALUE_LB)
        else:
            fixed = copy.copy(kwargs)
            fixed.hp_value_lb = FP8_ACTIVATION_VALUE_LB
        tensor.act_quant_kwargs = fixed
        restored += 1
    if restored and logger is not None:
        logger.info(
            "diffusion.prequant: restored the fp8 activation scale floor (%g) on %d weights built "
            "before activation_value_lb",
            FP8_ACTIVATION_VALUE_LB,
            restored,
        )
    return restored


def _repair_legacy_checkpoint(
    ckpt: Any,
    scheme: str,
    logger: Any = None,
) -> None:
    from .diffusion_nvfp4_policy import declares_policy
    from .diffusion_transformer_quant import TQ_FP8
    if scheme == TQ_FP8 or declares_policy(ckpt.get("metadata") or {}):
        _restore_fp8_activation_floor(ckpt["state_dict"], logger)


def _validate_activation_rotation(ckpt_format: Any, meta: Any, scheme: str, logger: Any) -> bool:
    """Refuses rotations this build cannot apply exactly, since a mismatch renders wrong pixels silently."""
    from .diffusion_convrot import declares_rotation, rotation_metadata_error

    rotated = declares_rotation(meta)
    tagged = ckpt_format == PREQUANT_FORMAT_ROTATED
    if rotated != tagged:
        _warn(
            logger,
            scheme,
            ValueError(
                f"checkpoint format {ckpt_format!r} and its activation rotation disagree "
                f"(declares a rotation: {rotated}); a rotated checkpoint must be tagged "
                f"{PREQUANT_FORMAT_ROTATED!r} so older builds refuse it instead of running it "
                "unrotated"
            ),
        )
        return False
    problem = rotation_metadata_error(meta)
    if problem:
        _warn(logger, scheme, ValueError(problem))
        return False
    return True


def _validate_policy(ckpt_format: Any, meta: Any, scheme: str, logger: Any) -> bool:
    """Reject a checkpoint whose per-layer nvfp4 policy this build cannot reproduce EXACTLY."""
    from .diffusion_nvfp4_policy import (
        NVFP4_POLICY_KEY,
        declares_policy,
        policy_expected_counts,
        policy_metadata_error,
        resolve_policy,
    )
    from .diffusion_transformer_quant import TQ_NVFP4

    declared = declares_policy(meta)
    tagged = ckpt_format == PREQUANT_FORMAT_POLICY
    if declared != tagged:
        _warn(
            logger,
            scheme,
            ValueError(
                f"checkpoint format {ckpt_format!r} and its per-layer nvfp4 policy disagree "
                f"(declares a policy: {declared}); a policy checkpoint must be tagged "
                f"{PREQUANT_FORMAT_POLICY!r} so older builds refuse it instead of loading it as a "
                "whole-model artifact"
            ),
        )
        return False
    if not declared:
        return True
    problem = policy_metadata_error(meta)
    if problem:
        _warn(logger, scheme, ValueError(problem))
        return False
    block = meta.get(NVFP4_POLICY_KEY)
    if scheme != TQ_NVFP4:
        _warn(
            logger,
            scheme,
            ValueError(
                f"checkpoint declares the nvfp4 policy {block.get('policy_id')!r} but its scheme "
                f"is {scheme!r}"
            ),
        )
        return False
    policy = resolve_policy(meta.get("family"), meta.get("base_model_id"))
    if policy is None:
        _warn(
            logger,
            scheme,
            ValueError(
                f"checkpoint declares the nvfp4 policy {block.get('policy_id')!r} but this build "
                f"resolves none for family {meta.get('family')!r} on base "
                f"{meta.get('base_model_id')!r}"
            ),
        )
        return False
    declared_id = (block.get("policy_id"), int(block.get("policy_version")))
    expected_id = (policy.policy_id, int(policy.version))
    if declared_id != expected_id:
        _warn(
            logger,
            scheme,
            ValueError(
                f"checkpoint nvfp4 policy {declared_id!r} != the one this build resolves for "
                f"{meta.get('base_model_id')!r}, {expected_id!r}"
            ),
        )
        return False
    declared_counts = {str(key): int(value) for key, value in (block.get("counts") or {}).items()}
    expected_counts = policy_expected_counts(policy)
    if declared_counts != expected_counts:
        _warn(
            logger,
            scheme,
            ValueError(
                f"checkpoint nvfp4 policy {policy.policy_id!r} records {declared_counts!r}, this "
                f"build's table expects {expected_counts!r}"
            ),
        )
        return False
    return True


def hosted_fast_accum_conflict(scheme: str, fast_accum: Optional[bool]) -> bool:
    """A forced fp8 fast_accum differing from the baked auto value rejects every hosted fp8 checkpoint."""
    from .diffusion_transformer_quant import TQ_FP8, _resolve_fast_accum

    if fast_accum is None or scheme != TQ_FP8:
        return False
    return bool(fast_accum) != _resolve_fast_accum(None)


def _validate_checkpoint(
    ckpt: Any,
    scheme: str,
    base: str,
    logger: Any,
    min_features: Optional[int] = None,
    fast_accum: Optional[bool] = None,
    component: Optional[str] = None,
    metadata_only: bool = False,
) -> bool:
    """Reject a wrong format / scheme / base / filter / denoiser; absent ``min_features`` / ``fast_accum`` pass.
    ``metadata_only`` skips the checks that need tensors."""
    if not isinstance(ckpt, dict) or ckpt.get("format") not in PREQUANT_FORMATS:
        _warn(logger, scheme, ValueError("unrecognised pre-quant checkpoint format"))
        return False
    if "state_dict" not in ckpt and not metadata_only:
        _warn(logger, scheme, ValueError("pre-quant checkpoint has no state_dict"))
        return False
    meta = ckpt.get("metadata") or {}
    if not _validate_activation_rotation(ckpt.get("format"), meta, scheme, logger):
        return False
    if not _validate_policy(ckpt.get("format"), meta, scheme, logger):
        return False
    if meta.get("scheme") != scheme:
        _warn(logger, scheme, ValueError(f"checkpoint scheme {meta.get('scheme')!r} != {scheme!r}"))
        return False
    # fp8 requires per-row granularity; old checkpoints without it are re-quantised.
    from .diffusion_nvfp4_policy import declares_policy
    from .diffusion_transformer_quant import FP8_GRANULARITY, TQ_FP8

    holds_fp8 = scheme == TQ_FP8 or declares_policy(meta)
    if holds_fp8 and meta.get("fp8_granularity") != FP8_GRANULARITY:
        _warn(
            logger,
            scheme,
            ValueError(
                f"fp8 checkpoint granularity {meta.get('fp8_granularity')!r} != "
                f"{FP8_GRANULARITY!r} (stale per-tensor artifact); rebuild it"
            ),
        )
        return False
    # fp8 also REQUIRES the activation scale floor, and this is checked on the loaded TENSORS, not on metadata.
    # torchao's per-row activation quantiser divides by each row's amax, so a zero row (qwen's text stream emits them)
    # gives scale 0 and NaN qdata unless activation_value_lb floors it. That floor is serialised per tensor as
    # act_quant_kwargs.hp_value_lb, so an artifact built before the fix stays broken however it is loaded, and it
    # predates any metadata field we could stamp -- and "absent is accepted for back-compat", the convention every
    # check above follows, is exactly wrong here. Reading the tensors is fail-closed and needs no format bump.
    # Unless the floor is the only difference: it is not weight data, so ``_repair_legacy_checkpoint`` writes it in.
    if (
        holds_fp8
        and not metadata_only
        and not _fp8_activation_floor_present(ckpt.get("state_dict"), logger, warn = False)
    ):
        if not _fp8_activation_floor_restorable(ckpt.get("state_dict")):
            _fp8_activation_floor_present(ckpt.get("state_dict"), logger)
            return False
        if logger is not None:
            logger.info(
                "diffusion.prequant: fp8 checkpoint predates activation_value_lb; the runtime "
                "floor will be written into its weights"
            )
    ckpt_base = meta.get("base_model_id")
    if base:
        # Wrong-base keys can load strict=True, so refuse a checkpoint that omits base_model_id.
        if not ckpt_base:
            _warn(
                logger,
                scheme,
                ValueError(
                    f"checkpoint metadata missing base_model_id; refusing for base {base!r}"
                ),
            )
            return False
        if not _same_base_model(ckpt_base, base):
            _warn(logger, scheme, ValueError(f"checkpoint base {ckpt_base!r} != {base!r}"))
            return False
    if min_features is not None:
        ckpt_min = meta.get("min_features")
        if ckpt_min is not None and int(ckpt_min) != int(min_features):
            _warn(
                logger,
                scheme,
                ValueError(f"checkpoint min_features {ckpt_min!r} != runtime {min_features!r}"),
            )
            return False
    # Reject quantised layers the runtime now excludes; a stale baked set would crash the first
    # denoise.
    ckpt_excludes = meta.get("exclude_name_tokens")
    if ckpt_excludes is not None:
        from .diffusion_transformer_quant import exclude_tokens_for_scheme

        # Excludes depend on scheme and family; an artifact with older tokens is re-quantised, not loaded.
        expected = tuple(exclude_tokens_for_scheme(scheme, meta.get("family")))
        if not isinstance(ckpt_excludes, (list, tuple)) or not set(expected) <= set(ckpt_excludes):
            _warn(
                logger,
                scheme,
                ValueError(
                    "checkpoint built under an older exclusion list (missing "
                    f"{sorted(set(expected) - set(ckpt_excludes or ())) if isinstance(ckpt_excludes, (list, tuple)) else ckpt_excludes!r}"
                    f"): checkpoint exclude_name_tokens {ckpt_excludes!r} do not cover the runtime {expected!r}"
                ),
            )
            return False
    # Weight-only modulations are a streamed-build layout: refuse them where this runtime keeps them dense.
    ckpt_weight_only = meta.get("weight_only_name_tokens")
    if ckpt_weight_only:
        from .diffusion_transformer_quant import streamed_weight_only_tokens_for_scheme
        allowed = set(streamed_weight_only_tokens_for_scheme(scheme, meta.get("family")))
        if not isinstance(ckpt_weight_only, (list, tuple)) or not set(ckpt_weight_only) <= allowed:
            _warn(
                logger,
                scheme,
                ValueError(
                    f"checkpoint stores {ckpt_weight_only!r} weight-only; this load keeps them dense"
                ),
            )
            return False
    # Verify recorded require_bf16 so a _REQUIRE_BF16_SCHEMES change can't load old-filter checkpoints.
    ckpt_require_bf16 = meta.get("require_bf16")
    if ckpt_require_bf16 is not None:
        from .diffusion_transformer_quant import _REQUIRE_BF16_SCHEMES
        expected_require_bf16 = scheme in _REQUIRE_BF16_SCHEMES
        if bool(ckpt_require_bf16) != expected_require_bf16:
            _warn(
                logger,
                scheme,
                ValueError(
                    f"checkpoint require_bf16 {bool(ckpt_require_bf16)!r} != {expected_require_bf16!r}"
                ),
            )
            return False
    ckpt_divisible = meta.get("require_divisible")
    if ckpt_divisible is not None:
        from .diffusion_transformer_quant import divisible_for_scheme
        expected_divisible = divisible_for_scheme(scheme)
        if int(ckpt_divisible) != expected_divisible:
            _warn(
                logger,
                scheme,
                ValueError(
                    f"checkpoint require_divisible {ckpt_divisible!r} != {expected_divisible!r}"
                ),
            )
            return False
    elif logger is not None:
        logger.debug(
            "diffusion.prequant: checkpoint records no require_divisible (built before the "
            "field); accepting it for %s",
            scheme,
        )
    if component:
        ckpt_component = meta.get("component")
        if ckpt_component is not None and str(ckpt_component) != str(component):
            _warn(
                logger,
                scheme,
                ValueError(
                    f"checkpoint component {ckpt_component!r} != {component!r}; this is another "
                    "denoiser of the same family and would load clean and render wrong"
                ),
            )
            return False
        if ckpt_component is None and logger is not None:
            logger.debug(
                "diffusion.prequant: checkpoint records no component; accepting it for %r",
                component,
            )
    # fp8 fast-accum is baked into the saved kernels; only enforce when the caller forces it.
    if fast_accum is not None:
        ckpt_fa = meta.get("fast_accum")
        if ckpt_fa is not None and bool(ckpt_fa) != bool(fast_accum):
            _warn(
                logger,
                scheme,
                ValueError(f"checkpoint fast_accum {ckpt_fa!r} != requested {bool(fast_accum)!r}"),
            )
            return False
    return True


def _same_base_model(a: str, b: str) -> bool:
    """Both sides normalise via canonical_base, so a mirror id cannot force the multi-GB dense download."""
    from .diffusion_families import canonical_base

    a, b = canonical_base(a), canonical_base(b)

    def _tail(x: str) -> str:
        return x.replace("\\", "/").rstrip("/").split("/")[-1].lower()

    return a == b or _tail(a) == _tail(b)


def _unhook_from_manager(
    manager: Any,
    module: Any,
    *,
    logger: Any = None,
    what: str,
) -> bool:
    """Remove ``module`` from a ComponentsManager's offload rotation without moving it."""
    hooks = list(getattr(manager, "model_hooks", None) or ())
    target = next((hook for hook in hooks if getattr(hook, "model", None) is module), None)
    if target is None:
        return False
    try:
        target.remove()
        # Unlist it too, else another pre_forward can evict it to CPU with no hook to bring it back.
        for hook in hooks:
            others = getattr(getattr(hook, "hook", None), "other_hooks", None)
            if others:
                hook.hook.other_hooks = [item for item in others if item is not target]
        manager.model_hooks = [hook for hook in hooks if hook is not target]
        return True
    except Exception as exc:  # noqa: BLE001 -- the caller still places the module
        _warn(logger, what, exc)
        return False


def pin_prequantized_module(
    manager: Any,
    module: Any,
    device: Any,
    *,
    logger: Any = None,
    label: str = "pre-quantized denoiser",
) -> bool:
    """Keeps a torchao module resident, since auto-offload's mid-forward move breaks its storage
    aliasing."""
    pinned = _unhook_from_manager(manager, module, logger = logger, what = "pin:hook")
    module.to(device)
    if logger is not None:
        logger.info(
            "diffusion.prequant: %s pinned on %s (offload rotation: %s)",
            label,
            device,
            "removed" if pinned else "unchanged",
        )
    return pinned


def tensor_payload_bytes(tensor: Any) -> int:
    """Payload bytes; torchao subclasses report their logical bf16 size, so sum the inner tensors."""
    flatten = getattr(tensor, "__tensor_flatten__", None)
    if callable(flatten) and type(tensor).__name__ not in ("Tensor", "Parameter"):
        try:
            return sum(tensor_payload_bytes(getattr(tensor, name)) for name in flatten()[0])
        except Exception:  # noqa: BLE001 -- fall through to the logical size
            pass
    return int(tensor.numel()) * int(tensor.element_size())


def torchao_group_offload_supported() -> bool:
    """Whether group offloading swaps torchao internals (diffusers >= 0.40); older ones half-move via ``param.data``."""
    try:
        from diffusers.hooks import apply_group_offloading  # noqa: F401
        from diffusers.hooks import group_offloading as go
    except Exception:  # noqa: BLE001 -- no group offloading at all
        return False
    return callable(getattr(go, "_is_torchao_tensor", None)) and callable(
        getattr(go, "_swap_torchao_tensor", None)
    )


def _weights_pinnable(module: Any) -> bool:
    """Whether every weight class answers ``is_pinned`` (torchao <= 0.17's v1 int8 class raises)."""
    from itertools import chain

    seen: set = set()
    try:
        for tensor in chain(module.parameters(), module.buffers()):
            cls = type(tensor)
            if cls in seen:
                continue
            seen.add(cls)
            tensor.is_pinned()
    except Exception:  # noqa: BLE001 -- unimplemented for this subclass
        return False
    return True


def _evict_rotation_hook(manager: Any, device: Any) -> Any:
    """Pre-hook offloading rotating components on ``device``: the manager only evicts inside another
    managed pre_forward, so the conditioner would otherwise stay beside the whole denoise loop."""
    import torch

    execution = torch.device(device)

    @torch.compiler.disable
    def _pre_forward(_module: Any, _args: Any) -> None:
        moved = False
        for hook in list(getattr(manager, "model_hooks", None) or ()):
            model = getattr(hook, "model", None)
            try:
                where = next(model.parameters()).device
            except Exception:  # noqa: BLE001 -- nothing to measure, nothing to move
                continue
            if where.type != execution.type:
                continue
            if execution.index is not None and where.index not in (None, execution.index):
                continue
            hook.offload()
            moved = True
        if moved and execution.type == "cuda":
            torch.cuda.empty_cache()

    return _pre_forward


def _move_groups_outside_inference_mode(module: Any) -> int:
    """Run group offload moves outside inference_mode (torchao v1 int8 raises
    ``Cannot set version_counter for inference tensor``). Returns the number of groups wrapped."""
    import torch

    seen: set[int] = set()
    for submodule in module.modules():
        hooks = getattr(getattr(submodule, "_diffusers_hook", None), "hooks", None) or {}
        for hook in list(hooks.values()):
            group = getattr(hook, "group", None)
            if group is None or id(group) in seen:
                continue
            seen.add(id(group))
            for name in ("onload_", "offload_"):
                move = getattr(group, name, None)
                if not callable(move):
                    continue

                def _outside(_move: Any = move) -> Any:
                    with torch.inference_mode(False), torch.no_grad():
                        return _move()

                setattr(group, name, torch.compiler.disable(_outside))
    return len(seen)


def stream_prequantized_module(
    manager: Any,
    module: Any,
    device: Any,
    *,
    logger: Any = None,
    label: str = "pre-quantized denoiser",
    defer_pin: bool = False,
) -> Optional[str]:
    """Streams via group offloading; raises once unhooked, as a resident fallback would OOM each render.
    ``defer_pin``: lazy host copies, no up-front pin (the caller pins what does not end up resident)."""
    if not torchao_group_offload_supported():
        return None
    import inspect

    import torch
    from diffusers.hooks import apply_group_offloading

    from .diffusion_memory import (
        DEFAULT_GROUP_BLOCKS,
        _remove_group_offload_hooks,
        _streamed_pin_plan,
        install_group_offload_buffer_restore,
        install_group_offload_hooks_eager,
    )

    onload = torch.device(device)
    if not _unhook_from_manager(manager, module, logger = logger, what = "stream:hook"):
        return None
    try:
        # assign=True leaves weights trainable; group offload then breaks on Int8Tensor's aten.view.
        module.requires_grad_(False)
        install_group_offload_buffer_restore()
        install_group_offload_hooks_eager()
        from .host_pinning import host_pinning_allowed

        pinning = host_pinning_allowed(onload)
        use_stream = onload.type == "cuda" and pinning and _weights_pinnable(module)
        if onload.type == "cuda" and pinning and not use_stream:
            # Sync copies measured 16.4 s/step vs 0.8 s resident (B200): rebuild v1 int8 as pinnable Int8Tensor.
            from .prequant_legacy_int8 import convert_legacy_int8_weights
            converted = convert_legacy_int8_weights(module)
            if converted:
                use_stream = _weights_pinnable(module)
                if logger is not None:
                    logger.info(
                        "diffusion.prequant: rebuilt %d v1 int8 weights as Int8Tensor for streaming",
                        converted,
                    )
        kwargs: dict[str, Any] = {
            "onload_device": onload,
            "offload_device": torch.device("cpu"),
            "offload_type": "block_level",
            "num_blocks_per_group": DEFAULT_GROUP_BLOCKS,
            "use_stream": use_stream,
        }
        params = inspect.signature(apply_group_offloading).parameters
        if use_stream:
            if "non_blocking" in params:
                kwargs["non_blocking"] = True
            if "record_stream" in params:
                kwargs["record_stream"] = True
            if "low_cpu_mem_usage" in params and defer_pin:
                kwargs["low_cpu_mem_usage"] = True
            elif "low_cpu_mem_usage" in params:
                from itertools import chain
                payload_mib = sum(
                    tensor_payload_bytes(t) for t in chain(module.parameters(), module.buffers())
                ) // (1024 * 1024)
                kwargs["low_cpu_mem_usage"] = not _streamed_pin_plan(
                    payload_mib, 0, logger, device = onload
                )[0]
        # Pin through one slab arena: per-tensor pin_memory() rounds each weight to a power of two.
        from .diffusion_pinned_arena import pinned_arena_for_group_offload

        with pinned_arena_for_group_offload(
            enabled = None if use_stream and not kwargs.get("low_cpu_mem_usage") else False
        ) as arena:
            apply_group_offloading(module, **kwargs)
        if arena is not None and arena.payload_bytes:
            module._unsloth_pin_arena_bytes = (arena.payload_bytes, arena.reserved_bytes)
            if logger is not None:
                logger.info(
                    "diffusion.prequant: %s pinned once in %.2f GB of slabs (%.2f GB of weights)",
                    label,
                    arena.reserved_bytes / 1e9,
                    arena.payload_bytes / 1e9,
                )
        _move_groups_outside_inference_mode(module)
        module.register_forward_pre_hook(_evict_rotation_hook(manager, onload))
    except Exception as exc:
        _remove_group_offload_hooks(module)
        raise RuntimeError(f"group offloading could not be set up for the {label}: {exc}") from exc
    # Only a full up-front pin keeps a second host copy; lazy pinning holds one group at a time.
    mode = (
        ("stream_lazy" if kwargs.get("low_cpu_mem_usage") else "stream") if use_stream else "sync"
    )
    if logger is not None:
        logger.info(
            "diffusion.prequant: %s streamed block by block on %s (%s copies)",
            label,
            device,
            "overlapped" if use_stream else "synchronous",
        )
    return mode


class PrequantIntoError(RuntimeError):
    """The module is neither dense nor fully loaded."""


def _prepare_outlier_buffers(transformer: Any, state_dict: dict) -> int:
    from .diffusion_int8_gemv import prepare_outlier_buffers
    return prepare_outlier_buffers(transformer, state_dict)


def _load_into_dense(transformer: Any, state_dict: dict, prepare_model: Optional[Any]) -> None:
    """ValueError leaves the module untouched; PrequantIntoError means it was partly assigned."""
    if prepare_model is not None:
        raise ValueError(
            "prepare_model reshapes a fresh skeleton; it cannot run on an existing transformer"
        )
    own = transformer.state_dict()
    from .diffusion_int8_gemv import OUTLIER_IDX, OUTLIER_WEIGHT

    # A streamed weight-only artifact also stores each modulation's dense outlier columns; the skeleton gets them below.
    outlier_keys = {
        k
        for k in state_dict
        if k.endswith((f".{OUTLIER_WEIGHT}", f".{OUTLIER_IDX}")) and k not in own
    }
    for name in outlier_keys:
        own[name] = state_dict[name]
    if set(own) != set(state_dict):
        missing = sorted(set(own) - set(state_dict))[:3]
        extra = sorted(set(state_dict) - set(own))[:3]
        raise ValueError(
            f"checkpoint keys differ from the transformer (missing {missing}, unexpected {extra})"
        )
    for name, tensor in state_dict.items():
        have = own[name]
        if tuple(getattr(have, "shape", ())) != tuple(getattr(tensor, "shape", ())):
            raise ValueError(
                f"checkpoint shape of {name} {tuple(tensor.shape)} != transformer {tuple(have.shape)}"
            )
    del own
    try:
        if outlier_keys:
            _prepare_outlier_buffers(transformer, state_dict)
        transformer.load_state_dict(state_dict, strict = True, assign = True)
    except Exception as exc:  # noqa: BLE001
        raise PrequantIntoError(f"{type(exc).__name__}: {exc}") from exc


def _has_meta_tensors(module: Any) -> bool:
    """True if any parameter or buffer is still on the meta device after loading."""
    from itertools import chain
    try:
        return any(
            getattr(t, "is_meta", False) for t in chain(module.parameters(), module.buffers())
        )
    except Exception:  # noqa: BLE001
        return False


_LAST_FAILURE = _threading.local()
# Absolute paths reduced to the last component; not after a word, ':' or '/' (URLs, repo ids).
_ABS_PATH = _re.compile(
    r"(?<![\w:/.])(?:[A-Za-z]:[\\/]|/)(?:[^\s'\"<>|:;,()\[\]\\/]+[\\/])+(?=[^\s\\/])"
)


def _warn(logger: Any, what: str, exc: Exception) -> None:
    _LAST_FAILURE.text = _ABS_PATH.sub("", f"{type(exc).__name__}: {exc}")[:300]
    if logger is not None:
        logger.warning("diffusion.prequant: %s failed: %s", what, exc)


def last_prequant_failure() -> Optional[str]:
    text = getattr(_LAST_FAILURE, "text", None)
    _LAST_FAILURE.text = None
    return text


def _unreadable_why(scheme: str) -> str:
    try:
        import torch
        import torchao
        ao = getattr(torchao, "__version__", "unknown")
    except Exception:  # noqa: BLE001
        return "torch or torchao is unavailable"
    if _is_nvfp4_scheme(scheme):
        return (
            f"torchao {ao} cannot rebuild an NVFP4 safetensors checkpoint (needs torchao >= 0.17 and the "
            "safetensors package); "
            "NVFP4 is never read from a .pt pickle"
        )
    if not _tuple_safe_globals_supported():
        return f"torch {torch.__version__} is older than 2.6"
    try:
        from core._torchao_stub import is_stubbed
        if is_stubbed("torchao"):
            return "torchao is not available on this platform"
    except Exception:  # noqa: BLE001
        pass
    missing = _SCHEME_REQUIRED_GLOBALS.get(scheme, frozenset()) - _RESOLVED_SAFE_GLOBALS
    if missing:
        return (
            f"torchao {ao} no longer ships {len(missing)} class(es) the checkpoint was saved with"
        )
    return f"torch {torch.__version__} / torchao {ao} cannot deserialize it"


def prequant_unreadable_reason(
    fam: Any,
    scheme: Optional[str],
    *,
    base_repo: Optional[str] = None,
    task: Optional[str] = None,
) -> Optional[str]:
    """Status line when ``fam`` hosts a ``scheme`` checkpoint this install cannot open; never raises."""
    if not scheme:
        return None
    try:
        src = resolve_prequant_source(fam, scheme, base_repo = base_repo, task = task)
        if src is None or getattr(src, "kind", None) != "repo":
            return None
        from .prequant_safetensors import is_safetensors_checkpoint

        readable = [
            n for n in candidate_filenames_of(src) if restricted_prequant_load_supported(scheme, n)
        ]
        # A derived safetensors name is a guess, as in usable_prequant_source: only a declared or cached one counts.
        if readable and all(is_safetensors_checkpoint(n) for n in readable):
            declared = set(getattr(src, "declared_filenames", ()) or ())
            if (
                not declared.intersection(readable)
                and cached_checkpoint_path(src, names = readable, online = False) is None
            ):
                readable = []
        if readable:
            return None
        return (
            f"the hosted {scheme} checkpoint ({src.location}) cannot be read here: "
            f"{_unreadable_why(scheme)}"
        )
    except Exception:  # noqa: BLE001 - a status nicety must never break a load
        return None