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.

112 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

"""Hermetic CPU tests for the pre-quantized transformer load path, with torch and accelerate stubbed."""

from __future__ import annotations

import contextlib
import dataclasses
import sys
import types

import pytest

import core.inference.diffusion_prequant as pq
from core.inference.diffusion_families import DiffusionFamily
from core.inference.diffusion_prequant import (
    PREQUANT_FORMAT,
    PrequantSource,
    load_prequantized_transformer,
    resolve_prequant_source,
)


def _prequant_source(**overrides):
    """A prequantized checkpoint source, with per-test overrides."""
    return PrequantSource(
        **{
            "kind": "repo",
            "location": "unsloth/Z-Image-Turbo-FP8",
            "filename": "Z-Image-Turbo-FP8.pt",
            "fallback_filenames": ("transformer_fp8.pt",),
            **overrides,
        }
    )


@pytest.fixture(autouse = True)
def _pin_prequant_safe_globals(real_prequant_safe_globals):
    """Apply the shared stand-in allowlist (see conftest) to every test in this module."""
    return real_prequant_safe_globals


def _fam(prequant_repos = (), prequant_variant_repos = ()):
    return DiffusionFamily(
        name = "z-image",
        pipeline_class = "ZImagePipeline",
        transformer_class = "ZImageTransformer2DModel",
        base_repo = "Tongyi-MAI/Z-Image-Turbo",
        prequant_repos = prequant_repos,
        prequant_variant_repos = prequant_variant_repos,
    )


def test_resolve_path_override_wins():
    fam = _fam(prequant_repos = (("fp8", "org/hosted-fp8"),))
    src = resolve_prequant_source(fam, "fp8", path_override = "/tmp/local.pt")
    assert src == PrequantSource(kind = "path", location = "/tmp/local.pt", filename = None)


def test_resolve_family_repo_by_scheme():
    fam = _fam(prequant_repos = (("fp8", "org/hosted-fp8"), ("int8", "org/hosted-int8")))
    src = resolve_prequant_source(fam, "int8")
    assert src.kind == "repo" and src.location == "org/hosted-int8"
    # Order: ComfyUI twin, then model name, safetensors before the pickle, legacy name last.
    assert src.candidate_filenames == (
        "hosted-INT8-ComfyUI.safetensors",
        "hosted-INT8.safetensors",
        "hosted-INT8.pt",
        "transformer_int8.pt",
    )


def test_prequant_repo_filename_convention():
    from core.inference.diffusion_prequant import prequant_repo_filename

    assert prequant_repo_filename("unsloth/Z-Image-Turbo-FP8", "int8") == "Z-Image-Turbo-INT8.pt"
    assert prequant_repo_filename("unsloth/Z-Image-Turbo-FP8", "fp8") == "Z-Image-Turbo-FP8.pt"
    assert (
        prequant_repo_filename("unsloth/Qwen-Image-2512-INT8", "int8") == "Qwen-Image-2512-INT8.pt"
    )
    assert prequant_repo_filename("org/Some-Model-quantized", "fp8") == "Some-Model-FP8.pt"
    assert prequant_repo_filename("org/PlainRepo", "int8") == "PlainRepo-INT8.pt"
    assert (
        prequant_repo_filename("unsloth/Wan2.2-TI2V-5B-NVFP4", "nvfp4") == "Wan2.2-TI2V-5B-NVFP4.pt"
    )
    assert prequant_repo_filename("unsloth/Model-MXFP8", "mxfp8") == "Model-MXFP8.pt"
    assert (
        prequant_repo_filename("unsloth/Wan2.2-T2V-A14B-NVFP4", "nvfp4", component = "transformer_2")
        == "Wan2.2-T2V-A14B-transformer_2-NVFP4.pt"
    )
    assert (
        prequant_repo_filename("unsloth/Wan2.2-T2V-A14B-NVFP4", "nvfp4", component = "transformer")
        == "Wan2.2-T2V-A14B-NVFP4.pt"
    )


def test_resolve_variant_base_picks_variant_repo():
    fam = _fam(
        prequant_repos = (("int8", "org/default-fp8"),),
        prequant_variant_repos = (("org/model-dev", "int8", "org/dev-fp8"),),
    )
    src = resolve_prequant_source(fam, "int8", base_repo = "Org/Model-DEV")
    assert src.kind == "repo" and src.location == "org/dev-fp8"
    assert src.filename == "dev-INT8-ComfyUI.safetensors"
    assert src.fallback_filenames[0] == "dev-INT8.safetensors"


def test_resolve_variant_base_falls_back_to_default():
    # unknown variant keeps the default entry; base_model_id validation then refuses it
    fam = _fam(
        prequant_repos = (("int8", "org/default-fp8"),),
        prequant_variant_repos = (("org/model-dev", "int8", "org/dev-fp8"),),
    )
    assert resolve_prequant_source(fam, "int8").location == "org/default-fp8"
    assert (
        resolve_prequant_source(fam, "int8", base_repo = "org/other-variant").location
        == "org/default-fp8"
    )
    assert resolve_prequant_source(fam, "int8", base_repo = "org/model-dev").location == "org/dev-fp8"


def test_flux1_variant_prequant_wiring():
    from core.inference.diffusion_families import detect_family, family_prequant_repo
    fam = detect_family("black-forest-labs/FLUX.1-schnell")
    for scheme in ("int8", "fp8"):
        assert family_prequant_repo(fam, scheme) == "unsloth/FLUX.1-schnell-FP8"
        assert (
            family_prequant_repo(fam, scheme, base_repo = "black-forest-labs/FLUX.1-dev")
            == "unsloth/FLUX.1-dev-FP8"
        )
        assert (
            family_prequant_repo(fam, scheme, base_repo = "black-forest-labs/FLUX.1-Krea-dev")
            == "unsloth/FLUX.1-Krea-dev-FP8"
        )


def test_resolve_prefers_a_family_declared_filename():
    # a named second artifact becomes primary; the derived name stays as fallback for old builds
    fam = _fam(prequant_repos = (("int8", "unsloth/Model-FP8"),))
    fam = dataclasses.replace(fam, prequant_filenames = (("int8", "Model-INT8-ConvRot.pt"),))
    src = resolve_prequant_source(fam, "int8")
    assert src.filename == "Model-INT8-ConvRot-ComfyUI.safetensors"
    assert src.fallback_filenames == (
        "Model-INT8-ConvRot.safetensors",
        "Model-INT8-ConvRot.pt",
        "Model-INT8-ComfyUI.safetensors",
        "Model-INT8.safetensors",
        "Model-INT8.pt",
        "transformer_int8.pt",
    )
    other = resolve_prequant_source(
        dataclasses.replace(fam, prequant_repos = (("fp8", "unsloth/Model-FP8"),)), "fp8"
    )
    assert other.candidate_filenames == (
        "Model-FP8.safetensors",
        "Model-FP8.pt",
        "Model-FP8-ComfyUI.safetensors",
        "transformer_fp8.pt",
    )


def test_resolve_wrong_scheme_is_none():
    fam = _fam(prequant_repos = (("fp8", "org/hosted-fp8"),))
    assert resolve_prequant_source(fam, "int8") is None


def test_resolve_nothing_configured_is_none():
    assert resolve_prequant_source(_fam(), "fp8") is None
    assert resolve_prequant_source(_fam(), "fp8", path_override = "") is None


def test_local_prequant_path_ready(tmp_path, monkeypatch):
    # a request path only counts if present and allowlisted, else the loader rebuilds dense
    import os

    ckpt = tmp_path / "model.pt"
    ckpt.write_bytes(b"x")
    root = os.path.realpath(str(tmp_path))
    monkeypatch.setattr(pq, "_allowed_prequant_roots", lambda: [root])
    assert pq.local_prequant_path_ready(str(ckpt)) is True
    assert pq.local_prequant_path_ready(str(tmp_path / "missing.pt")) is False
    monkeypatch.setattr(pq, "_allowed_prequant_roots", lambda: [])
    assert pq.local_prequant_path_ready(str(ckpt)) is False


@pytest.fixture
def restricted_load_available(monkeypatch):
    """Pins restricted-load support on: resolution tests do not depend on the host's torchao."""
    monkeypatch.setattr(
        pq, "restricted_prequant_load_supported", lambda scheme = None, filename = None: True
    )


def test_usable_source_missing_path_is_none(tmp_path, monkeypatch, restricted_load_available):
    # an absent allowlisted path would make the loader fall back to dense after evicting
    import os

    monkeypatch.setattr(pq, "_allowed_prequant_roots", lambda: [os.path.realpath(str(tmp_path))])
    fam = _fam(prequant_repos = (("fp8", "org/hosted-fp8"),))
    missing = str(tmp_path / "missing.pt")
    assert pq.usable_prequant_source(fam, "fp8", path_override = missing) is None


def test_usable_source_disallowed_path_is_none(tmp_path, monkeypatch, restricted_load_available):
    # paths outside UNSLOTH_ALLOW_LOCAL_PREQUANT_PATH (empty by default) are refused
    ckpt = tmp_path / "model.pt"
    ckpt.write_bytes(b"x")
    monkeypatch.setattr(pq, "_allowed_prequant_roots", lambda: [])
    fam = _fam(prequant_repos = (("fp8", "org/hosted-fp8"),))
    assert pq.usable_prequant_source(fam, "fp8", path_override = str(ckpt)) is None


def test_usable_source_allowed_present_path_wins(tmp_path, monkeypatch, restricted_load_available):
    import os

    ckpt = tmp_path / "model.pt"
    ckpt.write_bytes(b"x")
    monkeypatch.setattr(pq, "_allowed_prequant_roots", lambda: [os.path.realpath(str(tmp_path))])
    monkeypatch.setattr(pq, "local_prequant_scheme", lambda _p: "fp8")
    fam = _fam(prequant_repos = (("fp8", "org/hosted-fp8"),))
    src = pq.usable_prequant_source(fam, "fp8", path_override = str(ckpt))
    assert src == PrequantSource(kind = "path", location = str(ckpt), filename = None)


def test_usable_source_rejects_an_override_baked_for_another_scheme(
    tmp_path, monkeypatch, restricted_load_available
):
    """An int8 checkpoint must not read as an available fp8 pre-quant, or the dense shards are skipped."""
    import os

    ckpt = tmp_path / "model.pt"
    ckpt.write_bytes(b"x")
    monkeypatch.setattr(pq, "_allowed_prequant_roots", lambda: [os.path.realpath(str(tmp_path))])
    monkeypatch.setattr(pq, "local_prequant_scheme", lambda _p: "int8")
    fam = _fam(prequant_repos = (("fp8", "org/hosted-fp8"),))
    assert pq.usable_prequant_source(fam, "fp8", path_override = str(ckpt)) is None
    src = pq.usable_prequant_source(fam, "int8", path_override = str(ckpt))
    assert src == PrequantSource(kind = "path", location = str(ckpt), filename = None)


def test_an_unreadable_override_is_not_usable(tmp_path, monkeypatch, restricted_load_available):
    # an unparsable checkpoint is rejected by the loader too, so plan dense
    import os

    ckpt = tmp_path / "model.pt"
    ckpt.write_bytes(b"not a checkpoint")
    monkeypatch.setattr(pq, "_allowed_prequant_roots", lambda: [os.path.realpath(str(tmp_path))])
    fam = _fam(prequant_repos = (("fp8", "org/hosted-fp8"),))
    assert pq.local_prequant_scheme(str(ckpt)) is None
    assert pq.usable_prequant_source(fam, "fp8", path_override = str(ckpt)) is None


def test_the_local_scheme_cache_survives_a_same_second_swap(tmp_path):
    """Scheme cache must key on sub-second mtime, so a same-second swap is not read as the old scheme."""
    import os

    import torch

    ckpt = tmp_path / "model.pt"

    def _write(scheme, pad):
        torch.save(
            {"format": pq.PREQUANT_FORMAT, "metadata": {"scheme": scheme, "pad": "x" * pad}},
            str(ckpt),
        )

    _write("int8", 8)
    stamp = os.stat(str(ckpt)).st_mtime_ns
    size = os.stat(str(ckpt)).st_size
    assert pq.local_prequant_scheme(str(ckpt)) == "int8"

    _write("fp8", 9)
    assert os.stat(str(ckpt)).st_size == size, "the two bakes must be same-size for this to bite"
    os.utime(str(ckpt), ns = (stamp + 1, stamp + 1))
    assert int(os.stat(str(ckpt)).st_mtime) == int(stamp / 1e9)

    assert pq.local_prequant_scheme(str(ckpt)) == "fp8"


def test_usable_source_repo_unaffected_by_allowlist(monkeypatch, restricted_load_available):
    # hosted repos are first-party and need no allowlist
    monkeypatch.setattr(pq, "_allowed_prequant_roots", lambda: [])
    fam = _fam(prequant_repos = (("fp8", "org/hosted-fp8"),))
    src = pq.usable_prequant_source(fam, "fp8")
    assert src is not None and src.kind == "repo" and src.location == "org/hosted-fp8"


_UINT8 = object()  # stub torch uint8, so the fingerprint's dtype view is a no-op


class _Bytes:
    """Enough of a tensor for the fingerprint: it views the payload as uint8 and hashes it."""

    dtype = _UINT8

    def __init__(self, payload):
        self._payload = payload

    def detach(self):
        return self

    def contiguous(self):
        return self

    def dim(self):
        return 1

    def view(self, dtype):
        return self

    def cpu(self):
        return self

    def numpy(self):
        import numpy as np
        return np.frombuffer(self._payload, dtype = np.uint8)


class Float8Tensor:
    """A quantized fp8 weight; the class NAME is what the fingerprint and activation-floor checks key on."""

    def __init__(
        self,
        qdata = b"",
        hp_value_lb = 1e-12,
    ):
        self.qdata = _Bytes(qdata)
        self.scale = _Bytes(b"scale")
        self.act_quant_kwargs = types.SimpleNamespace(hp_value_lb = hp_value_lb)


class NVFP4Tensor:
    """The 4-bit half of a per-layer policy checkpoint."""

    def __init__(self, qdata = b""):
        self.qdata = _Bytes(qdata)
        self.scale = _Bytes(b"scale")
        self.act_quant_kwargs = types.SimpleNamespace(scale_dtype = "float8_e4m3fn")


class _Recorder:
    """A logger that keeps what it was told, so a refusal can be asserted to NAME the weight."""

    def __init__(self):
        self.lines: list = []

    def _record(self, msg, *args):
        self.lines.append(msg % args if args else msg)

    debug = info = warning = error = _record

    @property
    def text(self):
        return "\n".join(self.lines)


def _fingerprinted_ckpt(payloads, *, recorded = None):
    """A checkpoint whose state dict holds ``payloads`` and whose metadata fingerprints them."""
    from core.inference.diffusion_prequant import packed_weight_fingerprint

    state_dict = {fqn: Float8Tensor(data) for fqn, data in payloads.items()}
    ckpt = _good_ckpt()
    ckpt["state_dict"] = state_dict
    ckpt["metadata"]["fingerprint"] = recorded or packed_weight_fingerprint(state_dict)
    return ckpt


def test_a_flipped_byte_in_a_packed_weight_is_refused_and_named(monkeypatch, tmp_path):
    good = _fingerprinted_ckpt(
        {"blocks.0.attn1.to_q.weight": b"q0", "blocks.1.attn1.to_q.weight": b"q1"}
    )
    logger = _Recorder()
    assert _load(monkeypatch, tmp_path, good, logger = logger) is not None
    corrupt = _fingerprinted_ckpt(
        {"blocks.0.attn1.to_q.weight": b"q0", "blocks.1.attn1.to_q.weight": b"q1"}
    )
    corrupt["state_dict"]["blocks.1.attn1.to_q.weight"].qdata = _Bytes(b"Q1")
    logger = _Recorder()
    assert _load(monkeypatch, tmp_path, corrupt, logger = logger) is None
    assert "blocks.1.attn1.to_q.weight" in logger.text
    assert "blocks.0.attn1.to_q.weight" not in logger.text


def test_a_checkpoint_without_a_fingerprint_block_still_loads(monkeypatch, tmp_path):
    ckpt = _good_ckpt()
    ckpt["state_dict"] = {"blocks.0.attn1.to_q.weight": Float8Tensor(b"q0")}
    assert _load(monkeypatch, tmp_path, ckpt) is not None
    ckpt["metadata"]["fingerprint"] = {"algo": "md5-packed-v1", "count": 0, "modules": {}}
    assert _load(monkeypatch, tmp_path, ckpt) is not None


def test_the_fingerprint_mode_env_picks_how_much_is_checked(monkeypatch, tmp_path):
    from core.inference.diffusion_prequant import (
        FINGERPRINT_MODE_ENV,
        _fingerprint_sampled,
    )

    sampled = [f"blocks.{i}.attn1.to_q.weight" for i in range(64)]
    checked = [fqn for fqn in sampled if _fingerprint_sampled(fqn)]
    assert 0 < len(checked) < len(sampled)
    assert checked == [fqn for fqn in sampled if _fingerprint_sampled(fqn)]

    payloads = {fqn: fqn.encode("utf-8") for fqn in sampled}
    corrupt = _fingerprinted_ckpt(payloads)
    missed = next(fqn for fqn in sampled if not _fingerprint_sampled(fqn))
    corrupt["state_dict"][checked[0]].qdata = _Bytes(b"flipped")
    monkeypatch.setenv(FINGERPRINT_MODE_ENV, "sample")
    assert _load(monkeypatch, tmp_path, corrupt) is None
    only_missed = _fingerprinted_ckpt(payloads)
    only_missed["state_dict"][missed].qdata = _Bytes(b"flipped")
    assert _load(monkeypatch, tmp_path, only_missed) is not None
    monkeypatch.setenv(FINGERPRINT_MODE_ENV, "full")
    assert _load(monkeypatch, tmp_path, only_missed) is None
    monkeypatch.setenv(FINGERPRINT_MODE_ENV, "off")
    assert _load(monkeypatch, tmp_path, only_missed) is not None
    monkeypatch.setenv(FINGERPRINT_MODE_ENV, "sometimes")
    assert _load(monkeypatch, tmp_path, only_missed) is None


class _CountedBytes(_Bytes):
    """A payload that records the fqn whose bytes were actually read."""

    def __init__(self, fqn, payload, hashed):
        super().__init__(payload)
        self._fqn = fqn
        self._hashed = hashed

    def numpy(self):
        self._hashed.append(self._fqn)
        return super().numpy()


def test_a_class_whose_payload_slots_all_read_none_is_not_fingerprinted():
    from core.inference.diffusion_prequant import packed_weight_fingerprint

    renamed = Float8Tensor(b"q0")
    renamed.qdata = None
    renamed.scale = None
    fingerprint = packed_weight_fingerprint({"blocks.0.attn1.to_q.weight": renamed})
    assert fingerprint["modules"] == {}
    assert fingerprint["skipped"] == ["blocks.0.attn1.to_q.weight"]
    assert fingerprint["count"] == 0


class Int8Tensor:
    """torchao 0.18's int8 weight, as far as the fingerprint is concerned."""

    def __init__(self, qdata):
        self.qdata = _Bytes(qdata)
        self.scale = _Bytes(b"scale")
        self.zero_point = None
        self.act_quant_scale = None
        self.act_quant_zero_point = None
        self.act_pre_scale = None


def test_torchao_018_int8_weights_are_fingerprinted():
    from core.inference.diffusion_prequant import packed_weight_fingerprint

    fqn = "blocks.0.attn1.to_q.weight"
    good = packed_weight_fingerprint({fqn: Int8Tensor(b"q0")})
    assert good["count"] == 1 and good["skipped"] == []
    flipped = packed_weight_fingerprint({fqn: Int8Tensor(b"q1")})
    assert flipped["modules"][fqn] != good["modules"][fqn]


def test_real_torchao_int8_round_trip_fingerprint_catches_corruption():
    torch = pytest.importorskip("torch")
    pytest.importorskip("torchao")
    import io

    from torchao.quantization import quantize_

    from core.inference.diffusion_prequant import (
        _verify_packed_fingerprint,
        packed_weight_fingerprint,
    )
    from core.inference.diffusion_transformer_quant import _make_quant_config

    torch.manual_seed(0)
    model = torch.nn.Sequential(torch.nn.Linear(64, 64, bias = False)).to(torch.bfloat16)
    quantize_(model, _make_quant_config("int8"))
    fingerprint = packed_weight_fingerprint(model.state_dict())
    assert fingerprint["count"] == 1, fingerprint
    assert fingerprint["skipped"] == []

    buf = io.BytesIO()
    torch.save(model.state_dict(), buf)
    buf.seek(0)
    reloaded = torch.load(buf, weights_only = False)
    assert _verify_packed_fingerprint(reloaded, {"fingerprint": fingerprint})

    weight = reloaded["0.weight"]
    inner = getattr(weight, "qdata", None)
    if inner is None:  # torchao <= 0.17: the AffineQuantizedTensor chain
        inner = weight.original_weight_tensor.tensor_impl.int_data
    inner.view(-1)[0] ^= 1
    assert not _verify_packed_fingerprint(reloaded, {"fingerprint": fingerprint})


def test_sample_mode_hashes_only_the_weights_it_compares(monkeypatch, tmp_path):
    from core.inference.diffusion_prequant import FINGERPRINT_MODE_ENV, _fingerprint_sampled

    fqns = [f"blocks.{i}.attn1.to_q.weight" for i in range(64)]
    ckpt = _fingerprinted_ckpt({fqn: fqn.encode("utf-8") for fqn in fqns})
    hashed: list = []
    for fqn, tensor in ckpt["state_dict"].items():
        tensor.qdata = _CountedBytes(fqn, fqn.encode("utf-8"), hashed)
        tensor.scale = _CountedBytes(fqn, b"scale", hashed)
    monkeypatch.setenv(FINGERPRINT_MODE_ENV, "sample")
    assert _load(monkeypatch, tmp_path, ckpt) is not None
    assert sorted(set(hashed)) == sorted(fqn for fqn in fqns if _fingerprint_sampled(fqn))


def test_a_build_that_recognises_no_quantized_weight_loads_unverified(monkeypatch, tmp_path):
    ckpt = _fingerprinted_ckpt({"blocks.0.attn1.to_q.weight": b"q0"})
    ckpt["state_dict"] = {"blocks.0.attn1.to_q.weight": object()}
    assert _load(monkeypatch, tmp_path, ckpt) is not None


class _FakeTransformer:
    calls: dict = {}

    def __init__(self):
        self.assigned = None
        self.moved = None
        self.eval_called = False

    @classmethod
    def load_config(cls, base, **kw):
        cls.calls["load_config"] = {"base": base, **kw}
        return {"cfg": True}

    @classmethod
    def from_config(cls, config):
        cls.calls["from_config"] = config
        return cls()

    @classmethod
    def from_pretrained(cls, *a, **k):  # the dense path: must never run here
        cls.calls["from_pretrained"] = True
        raise AssertionError("from_pretrained must not be called on the prequant path")

    def load_state_dict(
        self,
        sd,
        strict = True,
        assign = False,
    ):
        _FakeTransformer.calls["load_state_dict"] = {"strict": strict, "assign": assign}
        self.assigned = sd

    def parameters(self):
        return []

    def buffers(self):
        return []

    def named_modules(self):
        return []

    def to(self, device):
        self.moved = device
        return self

    def eval(self):
        self.eval_called = True
        return self


def _stub_torch_accelerate(
    monkeypatch,
    ckpt,
    *,
    load_raises = False,
):
    torch = types.ModuleType("torch")
    # registration is gated on torch 2.6+, so the stub needs a version
    torch.__version__ = "2.9.1+cu128"
    seen = {"weights_only": None, "safe_globals": None}

    def _load(
        path,
        weights_only = False,
        map_location = None,
        **kwargs,
    ):
        seen["weights_only"] = weights_only
        if load_raises:
            raise RuntimeError("corrupt checkpoint")
        return ckpt

    def _add_safe_globals(entries):
        seen["safe_globals"] = list(entries)

    torch.load = _load
    torch.uint8 = _UINT8
    # without this namespace an unrestricted-load regression would pass silently
    torch.serialization = types.SimpleNamespace(add_safe_globals = _add_safe_globals)
    monkeypatch.setitem(sys.modules, "torch", torch)
    monkeypatch.setitem(sys.modules, "torch.serialization", torch.serialization)

    accelerate = types.ModuleType("accelerate")
    accelerate.init_empty_weights = lambda: contextlib.nullcontext()
    monkeypatch.setitem(sys.modules, "accelerate", accelerate)
    return seen


def _good_ckpt(scheme = "fp8", base = "Tongyi-MAI/Z-Image-Turbo"):
    meta = {"scheme": scheme, "base_model_id": base}
    # fp8 checkpoints must record per-row granularity or the loader rejects them
    if scheme == "fp8":
        meta["fp8_granularity"] = "per_row"
    return {
        "format": PREQUANT_FORMAT,
        "metadata": meta,
        "state_dict": {"weight": object()},
    }


def _load(
    monkeypatch,
    tmp_path,
    ckpt,
    *,
    scheme = "fp8",
    load_raises = False,
    exists = True,
    allow_local = True,
    fast_accum = None,
    component = None,
    logger = None,
):
    _FakeTransformer.calls = {}
    _stub_torch_accelerate(monkeypatch, ckpt, load_raises = load_raises)
    # the local-path branch is opt-in via a directory allowlist; allow tmp_path by default
    if allow_local:
        monkeypatch.setenv(pq.ALLOW_LOCAL_PREQUANT_PATH_ENV, str(tmp_path))
    else:
        monkeypatch.delenv(pq.ALLOW_LOCAL_PREQUANT_PATH_ENV, raising = False)
    path = tmp_path / ("ckpt.safetensors" if scheme == "nvfp4" else "ckpt.pt")
    if scheme == "nvfp4":
        # nvfp4 is read from safetensors only; the stand-in container returns the fake checkpoint.
        import core.inference.prequant_safetensors as pst
        def _st_load(_path, **_kwargs):
            if load_raises:
                raise RuntimeError("load failed")
            return ckpt

        monkeypatch.setattr(pst, "load_prequant_safetensors", _st_load)
    if exists:
        path.write_bytes(b"x")
    source = PrequantSource(kind = "path", location = str(path), filename = None)
    return load_prequantized_transformer(
        _FakeTransformer,
        "Tongyi-MAI/Z-Image-Turbo",
        source,
        device = "cuda",
        dtype = "bfloat16",
        hf_token = None,
        scheme = scheme,
        fast_accum = fast_accum,
        component = component,
        logger = logger,
    )


def test_load_meta_init_and_assign(monkeypatch, tmp_path):
    t = _load(monkeypatch, tmp_path, _good_ckpt())
    assert t is not None
    assert "from_config" in _FakeTransformer.calls
    assert "from_pretrained" not in _FakeTransformer.calls
    # assign=True is required: copying into meta tensors is a no-op
    assert _FakeTransformer.calls["load_state_dict"] == {"strict": True, "assign": True}
    assert t.moved == "cuda"
    assert t._unsloth_runtime_quant == "fp8"


def test_load_puts_transformer_in_eval_mode(monkeypatch, tmp_path):
    # from_config builds in train mode; dropout would make inference nondeterministic
    t = _load(monkeypatch, tmp_path, _good_ckpt())
    assert t is not None
    assert t.eval_called is True


def test_load_missing_file_is_none(monkeypatch, tmp_path):
    assert _load(monkeypatch, tmp_path, _good_ckpt(), exists = False) is None


def test_load_torch_load_raises_is_none(monkeypatch, tmp_path):
    assert _load(monkeypatch, tmp_path, _good_ckpt(), load_raises = True) is None


def test_load_format_mismatch_is_none(monkeypatch, tmp_path):
    bad = _good_ckpt()
    bad["format"] = "something_else"
    assert _load(monkeypatch, tmp_path, bad) is None


def test_load_scheme_mismatch_is_none(monkeypatch, tmp_path):
    assert _load(monkeypatch, tmp_path, _good_ckpt(scheme = "int8"), scheme = "fp8") is None


def test_load_base_mismatch_is_none(monkeypatch, tmp_path):
    assert _load(monkeypatch, tmp_path, _good_ckpt(base = "other/model")) is None


def test_load_fp8_stale_per_tensor_is_rejected(monkeypatch, tmp_path):
    # old fp8 checkpoints lack fp8_granularity (per-tensor layout) and must be rebuilt
    stale = _good_ckpt(scheme = "fp8")
    del stale["metadata"]["fp8_granularity"]
    assert _load(monkeypatch, tmp_path, stale, scheme = "fp8") is None
    per_tensor = _good_ckpt(scheme = "fp8")
    per_tensor["metadata"]["fp8_granularity"] = "per_tensor"
    assert _load(monkeypatch, tmp_path, per_tensor, scheme = "fp8") is None


def test_load_int8_ignores_fp8_granularity(monkeypatch, tmp_path):
    assert _load(monkeypatch, tmp_path, _good_ckpt(scheme = "int8"), scheme = "int8") is not None


def test_load_missing_base_metadata_is_none(monkeypatch, tmp_path):
    # keys may match a different base and load strict from wrong weights, so refuse no-base
    ckpt = _good_ckpt()
    del ckpt["metadata"]["base_model_id"]
    assert _load(monkeypatch, tmp_path, ckpt) is None


def test_load_fast_accum_mismatch_is_none(monkeypatch, tmp_path):
    # fp8 fast-accum is baked into the kernels; a contradicting request goes dense
    ckpt = _good_ckpt()
    ckpt["metadata"]["fast_accum"] = True
    assert _load(monkeypatch, tmp_path, ckpt, fast_accum = False) is None


def test_load_fast_accum_match_ok(monkeypatch, tmp_path):
    ckpt = _good_ckpt()
    ckpt["metadata"]["fast_accum"] = True
    assert _load(monkeypatch, tmp_path, ckpt, fast_accum = True) is not None


def test_load_fast_accum_auto_ignores_baked(monkeypatch, tmp_path):
    ckpt = _good_ckpt()
    ckpt["metadata"]["fast_accum"] = True
    assert _load(monkeypatch, tmp_path, ckpt, fast_accum = None) is not None


def test_load_exclude_tokens_mismatch_is_none(monkeypatch, tmp_path):
    # a stale int8 exclusion set would quantise M=1 modulation linears and crash
    ckpt = _good_ckpt(scheme = "int8")
    ckpt["metadata"]["exclude_name_tokens"] = ["stale_token"]
    assert _load(monkeypatch, tmp_path, ckpt, scheme = "int8") is None


def test_load_exclude_tokens_match_ok(monkeypatch, tmp_path):
    from core.inference.diffusion_transformer_quant import exclude_tokens_for_scheme

    ckpt = _good_ckpt(scheme = "int8")
    ckpt["metadata"]["exclude_name_tokens"] = list(exclude_tokens_for_scheme("int8"))
    assert _load(monkeypatch, tmp_path, ckpt, scheme = "int8") is not None


def test_load_exclude_tokens_superset_ok(monkeypatch, tmp_path):
    # Excluding MORE than the runtime keeps extra Linears bf16, which load as stored (assign=True) and run at any M. The
    # hosted Wan2.2 fp8 artifacts record ['condition_embedder'] against the runtime's empty fp8 set.
    from core.inference.diffusion_transformer_quant import exclude_tokens_for_scheme

    fp8 = _good_ckpt(scheme = "fp8")
    fp8["metadata"]["exclude_name_tokens"] = ["condition_embedder"]
    assert _load(monkeypatch, tmp_path, fp8, scheme = "fp8") is not None

    int8 = _good_ckpt(scheme = "int8")
    int8["metadata"]["exclude_name_tokens"] = list(exclude_tokens_for_scheme("int8")) + [
        "extra_bf16"
    ]
    assert _load(monkeypatch, tmp_path, int8, scheme = "int8") is not None


def test_load_exclude_tokens_subset_is_none(monkeypatch, tmp_path):
    # Missing one runtime token means the artifact quantised a layer the runtime keeps bf16 (the int8 crash case).
    from core.inference.diffusion_transformer_quant import exclude_tokens_for_scheme

    ckpt = _good_ckpt(scheme = "int8")
    ckpt["metadata"]["exclude_name_tokens"] = list(exclude_tokens_for_scheme("int8"))[1:]
    assert _load(monkeypatch, tmp_path, ckpt, scheme = "int8") is None


@pytest.mark.parametrize("recorded", ["norm", {"norm": 1}, 7])
def test_load_exclude_tokens_not_a_list_is_none(monkeypatch, tmp_path, recorded):
    # A bare string would pass a naive subset test character by character.
    ckpt = _good_ckpt(scheme = "int8")
    ckpt["metadata"]["exclude_name_tokens"] = recorded
    assert _load(monkeypatch, tmp_path, ckpt, scheme = "int8") is None


def test_load_exclude_tokens_need_the_recorded_family(monkeypatch, tmp_path):
    # int8 exclusions are per-family: Qwen's text stream runs at M = prompt tokens, under _int_mm's 16
    from core.inference.diffusion_transformer_quant import exclude_tokens_for_scheme
    for family in ("qwen-image", "qwen-image-edit"):
        family_less = _good_ckpt(scheme = "int8")
        family_less["metadata"]["family"] = family
        family_less["metadata"]["exclude_name_tokens"] = list(exclude_tokens_for_scheme("int8"))
        assert _load(monkeypatch, tmp_path, family_less, scheme = "int8") is None

        family_aware = _good_ckpt(scheme = "int8")
        family_aware["metadata"]["family"] = family
        family_aware["metadata"]["exclude_name_tokens"] = list(
            exclude_tokens_for_scheme("int8", family)
        )
        assert _load(monkeypatch, tmp_path, family_aware, scheme = "int8") is not None


def test_load_require_bf16_mismatch_is_none(monkeypatch, tmp_path):
    # fp8 built without the bf16 gate quantised a different layer set than the runtime filter; reject it
    ckpt = _good_ckpt(scheme = "fp8")
    ckpt["metadata"]["require_bf16"] = False
    assert _load(monkeypatch, tmp_path, ckpt, scheme = "fp8") is None


def test_load_require_bf16_match_ok(monkeypatch, tmp_path):
    ckpt = _good_ckpt(scheme = "fp8")
    ckpt["metadata"]["require_bf16"] = True
    assert _load(monkeypatch, tmp_path, ckpt, scheme = "fp8") is not None


def test_load_require_bf16_int8_true_is_none(monkeypatch, tmp_path):
    # torch._int_mm tolerates non-bf16 weights, so int8 never sets the gate
    ckpt = _good_ckpt(scheme = "int8")
    ckpt["metadata"]["require_bf16"] = True
    assert _load(monkeypatch, tmp_path, ckpt, scheme = "int8") is None


def test_load_require_bf16_nvfp4_false_ok(monkeypatch, tmp_path):
    # nvfp4 quantises fp32 fine, so the bf16 gate stays off
    ckpt = _good_ckpt(scheme = "nvfp4")
    ckpt["metadata"]["require_bf16"] = False
    assert _load(monkeypatch, tmp_path, ckpt, scheme = "nvfp4") is not None


def test_an_nvfp4_checkpoint_is_prewarmed_by_the_shared_loader(monkeypatch, tmp_path):
    from core.inference import diffusion_nvfp4_linear as nl

    seen: list = []
    monkeypatch.setattr(
        nl, "nvfp4_prewarm", lambda module, shapes, **_k: seen.append(tuple(shapes)) or 0
    )
    ckpt = _good_ckpt(scheme = "nvfp4")
    ckpt["metadata"]["require_bf16"] = False
    assert _load(monkeypatch, tmp_path, ckpt, scheme = "nvfp4") is not None
    assert seen == [(1,)]

    seen.clear()
    assert _load(monkeypatch, tmp_path, _good_ckpt(scheme = "fp8"), scheme = "fp8") is not None
    assert seen == []


def test_a_failed_prewarm_keeps_the_loaded_checkpoint(monkeypatch, tmp_path):
    from core.inference import diffusion_nvfp4_linear as nl

    def _boom(*_a, **_k):
        raise RuntimeError("autotune failed")

    monkeypatch.setattr(nl, "nvfp4_prewarm", _boom)
    ckpt = _good_ckpt(scheme = "nvfp4")
    ckpt["metadata"]["require_bf16"] = False
    assert _load(monkeypatch, tmp_path, ckpt, scheme = "nvfp4") is not None


def test_load_require_bf16_nvfp4_true_is_none(monkeypatch, tmp_path):
    ckpt = _good_ckpt(scheme = "nvfp4")
    ckpt["metadata"]["require_bf16"] = True
    assert _load(monkeypatch, tmp_path, ckpt, scheme = "nvfp4") is None


def test_load_require_divisible_mismatch_is_none(monkeypatch, tmp_path):
    ckpt = _good_ckpt(scheme = "fp8")
    ckpt["metadata"]["require_divisible"] = 0
    assert _load(monkeypatch, tmp_path, ckpt, scheme = "fp8") is None


def test_load_require_divisible_match_ok(monkeypatch, tmp_path):
    ckpt = _good_ckpt(scheme = "fp8")
    ckpt["metadata"]["require_divisible"] = 16
    assert _load(monkeypatch, tmp_path, ckpt, scheme = "fp8") is not None


def test_load_require_divisible_absent_is_accepted(monkeypatch, tmp_path):
    ckpt = _good_ckpt(scheme = "fp8")
    assert "require_divisible" not in ckpt["metadata"]
    assert _load(monkeypatch, tmp_path, ckpt, scheme = "fp8") is not None


def test_load_component_mismatch_is_none(monkeypatch, tmp_path):
    ckpt = _good_ckpt()
    ckpt["metadata"]["component"] = "transformer_2"
    assert _load(monkeypatch, tmp_path, ckpt, component = "transformer") is None
    assert _load(monkeypatch, tmp_path, ckpt, component = "transformer_2") is not None


def test_load_component_absent_is_accepted(monkeypatch, tmp_path):
    ckpt = _good_ckpt()
    assert _load(monkeypatch, tmp_path, ckpt, component = "transformer") is not None
    ckpt["metadata"]["component"] = "transformer_2"
    assert _load(monkeypatch, tmp_path, ckpt) is not None


def test_resolve_checkpoint_path_expands_user(monkeypatch, tmp_path):
    # the allowlist gate expands ~, so the existence check must too
    import os

    real = tmp_path / "transformer_fp8.pt"
    real.write_bytes(b"x")
    monkeypatch.setattr(os.path, "expanduser", lambda p: str(real) if p == "~/ckpt.pt" else p)
    source = PrequantSource(kind = "path", location = "~/ckpt.pt", filename = None)
    assert pq._resolve_checkpoint_path(source, None) == str(real)


def test_the_checkpoint_is_deserialized_under_an_allowlist(monkeypatch):
    """Pre-quant checkpoints are pickles, so the load must run weights_only under an allowlist."""
    seen = _stub_torch_accelerate(monkeypatch, _good_ckpt())
    monkeypatch.setattr(pq, "_SAFE_GLOBALS_REGISTERED", None)
    monkeypatch.setattr(pq, "_resolve_checkpoint_path", lambda *a, **k: "/cache/x.pt")
    load_prequantized_transformer(
        _FakeTransformer,
        "Tongyi-MAI/Z-Image-Turbo",
        PrequantSource(kind = "repo", location = "org/hosted-fp8", filename = "x.pt"),
        device = "cpu",
        dtype = "bf16",
        hf_token = None,
        scheme = "fp8",
    )
    assert seen["weights_only"] is True
    assert seen["safe_globals"], "the allowlist has to be registered before the load"


def test_the_allowlist_names_every_constructor_the_hosted_checkpoints_use(
    monkeypatch, real_prequant_safe_globals
):
    """The allowlist names exactly the constructors hosted prequant checkpoints use, from pickletools."""
    listed = {f"{module}.{name}" for module, name in pq._PREQUANT_SAFE_GLOBALS}
    required = {
        # every TQ_SCHEME the builder can bake, not just the hosted ones
        "torchao.prototype.mx_formats.mx_tensor.MXTensor",
        "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.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",
    }
    assert required <= listed, sorted(required - listed)
    # nvfp4 is never unpickled by Studio: its checkpoints load from safetensors only
    assert not any(
        "nvfp4" in f"{module}.{name}".lower() for module, name in pq._PREQUANT_SAFE_GLOBALS
    )
    # nothing outside torch/torchao, so no general-purpose callable is allowed
    assert all(
        module.split(".")[0] in ("torch", "torchao") for module, _ in pq._PREQUANT_SAFE_GLOBALS
    )
    # names missing from a given torchao release are skipped, not raised
    monkeypatch.setattr(
        pq, "_PREQUANT_SAFE_GLOBALS", (("torchao.nowhere", "Nope"), ("collections", "OrderedDict"))
    )
    assert [name for _obj, name in real_prequant_safe_globals()] == ["collections.OrderedDict"]


def test_the_registration_floor_needs_a_real_torchao(real_prequant_safe_globals):
    """With real torchao, the resolver must find the allowlisted names; stubs would hide a rename."""
    pytest.importorskip("torchao")
    resolved = {name for _obj, name in real_prequant_safe_globals()}
    assert "torch.torch_version.TorchVersion" in resolved
    assert [name for name in resolved if name.startswith("torchao.")], (
        "no torchao constructor resolved, so no pre-quant checkpoint could be opened: "
        + repr(sorted(resolved))
    )


def test_the_registration_refuses_when_nothing_resolves(monkeypatch):
    """With torch but no torchao, the load must refuse rather than unpickle without the restriction."""
    monkeypatch.setattr(pq, "_prequant_safe_globals", list)
    monkeypatch.setattr(pq, "_SAFE_GLOBALS_REGISTERED", None)
    assert pq._register_prequant_safe_globals() is False
    assert pq.restricted_prequant_load_supported("fp8") is False
    with pytest.raises(RuntimeError, match = "allowlist"):
        pq._torch_load_prequant("/x.pt", map_location = "cpu")


def test_a_malicious_checkpoint_is_refused_before_it_executes():
    """The whole point, against real torch: a checkpoint carrying a ``__reduce__`` payload must
    fail to load rather than run. The unrestricted load this replaces executes it."""
    import os

    torch = pytest.importorskip("torch")
    if not hasattr(torch.serialization, "safe_globals"):
        pytest.skip("torch < 2.6 has no safe_globals")
    import tempfile

    with tempfile.TemporaryDirectory() as tmp:
        marker = os.path.join(tmp, "executed")

        class _Payload:
            # mkdir: observable proof of execution, confined to the temp dir
            def __reduce__(self):
                return (os.mkdir, (marker,))

        path = os.path.join(tmp, "ckpt.pt")
        torch.save(
            {"format": PREQUANT_FORMAT, "metadata": {"scheme": "int8"}, "state_dict": _Payload()},
            path,
        )
        with pytest.raises(Exception):
            pq._torch_load_prequant(path, map_location = "cpu")
        assert not os.path.exists(marker)


def test_the_scheme_probe_does_not_execute_the_checkpoint_either(tmp_path, monkeypatch):
    """The scheme probe must not execute the checkpoint, since planning reaches it without a load."""
    import os

    torch = pytest.importorskip("torch")
    if not hasattr(torch.serialization, "safe_globals"):
        pytest.skip("torch < 2.6 has no safe_globals")
    marker = tmp_path / "executed"

    class _Payload:
        def __reduce__(self):
            return (os.mkdir, (str(marker),))

    ckpt = tmp_path / "malicious.pt"
    torch.save(
        {"format": PREQUANT_FORMAT, "metadata": {"scheme": "fp8"}, "payload": _Payload()}, ckpt
    )
    monkeypatch.setattr(pq, "_allowed_prequant_roots", lambda: [os.path.realpath(str(tmp_path))])

    assert pq.local_prequant_scheme(str(ckpt)) is None
    assert not marker.exists()
    fam = _fam(prequant_repos = (("fp8", "org/hosted-fp8"),))
    assert pq.usable_prequant_source(fam, "fp8", path_override = str(ckpt)) is None
    assert not marker.exists()


class _UnknownConstructor:
    """A constructor no allowlist entry names. Module level so it pickles by reference."""


def test_the_probe_and_the_loader_agree_on_what_is_readable(tmp_path, monkeypatch):
    """The scheme probe and the loader must read the same set, or planning drops dense shards wrongly."""
    import os

    torch = pytest.importorskip("torch")
    if not hasattr(torch.serialization, "safe_globals"):
        pytest.skip("torch < 2.6 has no safe_globals")

    path = tmp_path / "off-allowlist.pt"
    torch.save(
        {
            "format": PREQUANT_FORMAT,
            "metadata": {"scheme": "int8", "base_model_id": "Tongyi-MAI/Z-Image-Turbo"},
            "state_dict": {"weight": _UnknownConstructor()},
        },
        path,
    )
    monkeypatch.setattr(pq, "_allowed_prequant_roots", lambda: [os.path.realpath(str(tmp_path))])

    assert pq.local_prequant_scheme(str(path)) is None
    fam = _fam(prequant_repos = (("int8", "org/hosted-int8"),))
    assert pq.usable_prequant_source(fam, "int8", path_override = str(path)) is None
    assert (
        load_prequantized_transformer(
            _FakeTransformer,
            "Tongyi-MAI/Z-Image-Turbo",
            PrequantSource(kind = "path", location = str(path), filename = None),
            device = "cpu",
            dtype = "bf16",
            hf_token = None,
            scheme = "int8",
        )
        is None
    )


def test_a_torch_without_safe_globals_refuses_rather_than_reopening_the_pickle(monkeypatch):
    """No allowlist support means no load. Falling back to an unrestricted one would put the
    sink back on exactly the installs least able to defend it."""
    torch = types.ModuleType("torch")
    torch.load = lambda *a, **k: pytest.fail("torch.load must not run without add_safe_globals")
    torch.serialization = types.SimpleNamespace()
    monkeypatch.setitem(sys.modules, "torch", torch)
    monkeypatch.setattr(pq, "_SAFE_GLOBALS_REGISTERED", None)
    with pytest.raises(RuntimeError, match = "add_safe_globals"):
        pq._torch_load_prequant("/nonexistent.pt", map_location = "cpu")


def test_an_old_torch_registers_nothing_at_all(monkeypatch):
    """Below torch 2.6 register nothing: a tuple left in the process-wide list breaks other loads."""
    torch = types.ModuleType("torch")
    torch.serialization = types.SimpleNamespace(
        add_safe_globals = lambda entries: pytest.fail("nothing may be registered below 2.6")
    )
    torch.load = lambda *a, **k: pytest.fail("and no load may run")
    for version in ("2.4.0", "2.5.1+cu124", "2.5.0"):
        torch.__version__ = version
        monkeypatch.setitem(sys.modules, "torch", torch)
        monkeypatch.setattr(pq, "_SAFE_GLOBALS_REGISTERED", None)
        assert pq._tuple_safe_globals_supported() is False, version
        assert pq.restricted_prequant_load_supported() is False, version
    torch.__version__ = "2.6.0"
    assert pq._tuple_safe_globals_supported() is True


def test_a_stubbed_torchao_cannot_open_a_checkpoint(monkeypatch):
    """A stubbed torchao cannot open a checkpoint, so the allowlist must not register its fake classes."""
    import core._torchao_stub as stub

    monkeypatch.setattr(pq, "_SAFE_GLOBALS_REGISTERED", None)
    monkeypatch.setattr(stub, "is_stubbed", lambda package: package == "torchao")
    torch = types.ModuleType("torch")
    torch.__version__ = "2.9.1"
    torch.serialization = types.SimpleNamespace(
        add_safe_globals = lambda entries: pytest.fail("a stub must never be registered")
    )
    monkeypatch.setitem(sys.modules, "torch", torch)
    assert pq.restricted_prequant_load_supported() is False


def test_a_torchao_that_resolves_nothing_reports_no_support(monkeypatch):
    """Registering successfully is not enough: support needs the two entries every artifact requires."""
    registered = []
    torch = types.ModuleType("torch")
    torch.__version__ = "2.9.1"
    torch.serialization = types.SimpleNamespace(add_safe_globals = registered.append)
    monkeypatch.setitem(sys.modules, "torch", torch)

    def only(names):
        return [(object(), n) for n in names]

    monkeypatch.setattr(pq, "_SAFE_GLOBALS_REGISTERED", None)
    monkeypatch.setattr(
        pq, "_prequant_safe_globals", lambda: only(["torch.torch_version.TorchVersion"])
    )
    assert pq.restricted_prequant_load_supported() is False
    assert registered == [], "and nothing is registered on the way to saying no"

    # every torchao checkpoint carries the version stamp
    monkeypatch.setattr(pq, "_SAFE_GLOBALS_REGISTERED", None)
    monkeypatch.setattr(
        pq, "_prequant_safe_globals", lambda: only(["torchao.quantization.Float8Tensor"])
    )
    assert pq.restricted_prequant_load_supported() is False

    monkeypatch.setattr(pq, "_SAFE_GLOBALS_REGISTERED", None)
    monkeypatch.setattr(
        pq,
        "_prequant_safe_globals",
        lambda: only(["torch.torch_version.TorchVersion", "torchao.quantization.Float8Tensor"]),
    )
    assert pq.restricted_prequant_load_supported() is True
    assert len(registered) == 1


def test_support_is_answered_per_scheme(monkeypatch):
    """Support is answered per scheme, since torchao may retire int8 constructors while keeping fp8."""
    torch = types.ModuleType("torch")
    torch.__version__ = "2.9.1"
    torch.serialization = types.SimpleNamespace(add_safe_globals = lambda entries: None)
    monkeypatch.setitem(sys.modules, "torch", torch)

    fp8_only = set(pq._SCHEME_REQUIRED_GLOBALS["fp8"])
    monkeypatch.setattr(pq, "_SAFE_GLOBALS_REGISTERED", None)
    monkeypatch.setattr(pq, "_RESOLVED_SAFE_GLOBALS", set())
    monkeypatch.setattr(pq, "_prequant_safe_globals", lambda: [(object(), n) for n in fp8_only])
    import core.inference.prequant_legacy_int8 as legacy_int8

    monkeypatch.setattr(legacy_int8, "legacy_int8_decode_supported", lambda: False)

    assert pq.restricted_prequant_load_supported("fp8") is True
    assert pq.restricted_prequant_load_supported("int8") is False
    # nvfp4 never reads a pickle, whatever the allowlist resolves
    assert pq.restricted_prequant_load_supported("nvfp4", "x-NVFP4.pt") is False
    assert pq.restricted_prequant_load_supported() is True
    assert pq.restricted_prequant_load_supported("something-else") is True
    fam = _fam(prequant_repos = (("int8", "org/hosted-int8"), ("fp8", "org/hosted-fp8")))
    assert pq.usable_prequant_source(fam, "int8") is None
    assert pq.usable_prequant_source(fam, "fp8") is not None


def test_the_required_sets_are_a_subset_of_the_allowlist():
    """A required name the allowlist never registers would refuse its scheme forever."""
    listed = {f"{module}.{name}" for module, name in pq._PREQUANT_SAFE_GLOBALS}
    for scheme, required in pq._SCHEME_REQUIRED_GLOBALS.items():
        assert required <= listed, (scheme, sorted(required - listed))


def test_an_install_that_cannot_restrict_the_load_offers_no_prequant_source(monkeypatch, tmp_path):
    """Planning must ask whether the install can restrict the load before it sizes it, not after."""
    import os

    fam = _fam(prequant_repos = (("int8", "org/hosted-int8"),))
    monkeypatch.setattr(
        pq, "restricted_prequant_load_supported", lambda scheme = None, filename = None: True
    )
    assert pq.usable_prequant_source(fam, "int8") is not None
    monkeypatch.setattr(
        pq, "restricted_prequant_load_supported", lambda scheme = None, filename = None: False
    )
    assert pq.usable_prequant_source(fam, "int8") is None
    ckpt = tmp_path / "model.pt"
    ckpt.write_bytes(b"x")
    monkeypatch.setattr(pq, "_allowed_prequant_roots", lambda: [os.path.realpath(str(tmp_path))])
    assert pq.usable_prequant_source(fam, "int8", path_override = str(ckpt)) is None


def test_the_allowlist_is_registered_once_and_never_withdrawn(monkeypatch):
    """The allowlist is registered once and never withdrawn, since overlapping loads share it."""
    torch = pytest.importorskip("torch")
    if not hasattr(torch.serialization, "add_safe_globals"):
        pytest.skip("torch without add_safe_globals")
    calls = []
    monkeypatch.setattr(pq, "_SAFE_GLOBALS_REGISTERED", None)
    monkeypatch.setattr(
        torch.serialization, "add_safe_globals", lambda entries: calls.append(list(entries))
    )
    # no remove_safe_globals / safe_globals context: entries are never given back
    monkeypatch.setattr(
        torch.serialization,
        "safe_globals",
        lambda *a, **k: pytest.fail("the load must not scope the allowlist to itself"),
    )
    monkeypatch.setattr(torch, "load", lambda *a, **k: {"ok": True})
    assert pq._torch_load_prequant("/x.pt", map_location = "cpu") == {"ok": True}
    assert pq._torch_load_prequant("/x.pt", map_location = "cpu") == {"ok": True}
    assert len(calls) == 1, "registered once for the process, not per load"
    assert calls[0], "and with the allowlist, not an empty list"


def test_load_local_path_refused_by_default(monkeypatch, tmp_path):
    # torch.load must never run on a request-supplied path without the operator opt-in
    called = {"load": False}

    def _explode(*a, **k):
        called["load"] = True
        raise AssertionError("torch.load must not run on a refused local path")

    torch = types.ModuleType("torch")
    torch.load = _explode
    monkeypatch.setitem(sys.modules, "torch", torch)
    monkeypatch.delenv(pq.ALLOW_LOCAL_PREQUANT_PATH_ENV, raising = False)

    path = tmp_path / "ckpt.pt"
    path.write_bytes(b"x")
    source = PrequantSource(kind = "path", location = str(path), filename = None)
    result = load_prequantized_transformer(
        _FakeTransformer,
        "Tongyi-MAI/Z-Image-Turbo",
        source,
        device = "cuda",
        dtype = "bfloat16",
        hf_token = None,
        scheme = "fp8",
        logger = None,
    )
    assert result is None
    assert called["load"] is False


def test_load_local_path_allowed_with_optin(monkeypatch, tmp_path):
    assert _load(monkeypatch, tmp_path, _good_ckpt(), allow_local = True) is not None


def test_load_repo_source_allowed_without_optin(monkeypatch, tmp_path):
    _FakeTransformer.calls = {}
    _stub_torch_accelerate(monkeypatch, _good_ckpt())
    monkeypatch.delenv(pq.ALLOW_LOCAL_PREQUANT_PATH_ENV, raising = False)

    downloaded = tmp_path / "transformer_fp8.pt"
    downloaded.write_bytes(b"x")
    roots: list = []

    def _dl(
        repo_id,
        filename,
        token = None,
        cache_dir = None,
        local_files_only = False,
    ):
        roots.append(cache_dir)
        return str(downloaded)

    hub = types.ModuleType("huggingface_hub")
    hub.hf_hub_download = _dl
    monkeypatch.setitem(sys.modules, "huggingface_hub", hub)

    source = PrequantSource(kind = "repo", location = "org/hosted-fp8", filename = "transformer_fp8.pt")
    result = load_prequantized_transformer(
        _FakeTransformer,
        "Tongyi-MAI/Z-Image-Turbo",
        source,
        device = "cuda",
        dtype = "bfloat16",
        hf_token = None,
        scheme = "fp8",
        cache_dir = "/live-hub",
        logger = None,
    )
    assert result is not None
    # the loader pins the caller's live root so the fetch cannot split across two
    assert roots == ["/live-hub"]


def test_load_repo_source_falls_back_to_legacy_filename(monkeypatch, tmp_path):
    # legacy transformer_<scheme>.pt serves the download after the model-name file 404s
    _FakeTransformer.calls = {}
    _stub_torch_accelerate(monkeypatch, _good_ckpt())
    monkeypatch.delenv(pq.ALLOW_LOCAL_PREQUANT_PATH_ENV, raising = False)

    downloaded = tmp_path / "transformer_fp8.pt"
    downloaded.write_bytes(b"x")

    class _NotFound(Exception):
        pass

    errors = types.ModuleType("huggingface_hub.errors")
    errors.EntryNotFoundError = _NotFound
    requested = []

    def _dl(
        repo_id,
        filename,
        token = None,
        cache_dir = None,
        local_files_only = False,
    ):
        requested.append(filename)
        if filename != "transformer_fp8.pt":
            raise _NotFound(filename)
        return str(downloaded)

    hub = types.ModuleType("huggingface_hub")
    hub.hf_hub_download = _dl
    hub.errors = errors
    monkeypatch.setitem(sys.modules, "huggingface_hub", hub)
    monkeypatch.setitem(sys.modules, "huggingface_hub.errors", errors)

    source = _prequant_source(location = "org/Z-Image-Turbo-FP8")
    result = load_prequantized_transformer(
        _FakeTransformer,
        "Tongyi-MAI/Z-Image-Turbo",
        source,
        device = "cuda",
        dtype = "bfloat16",
        hf_token = None,
        scheme = "fp8",
        logger = None,
    )
    assert result is not None
    assert requested == ["Z-Image-Turbo-FP8.pt", "transformer_fp8.pt"]


def test_load_local_path_outside_allowlist_refused(monkeypatch, tmp_path):
    # one trusted dir is not a wildcard: outside paths are never unpickled
    called = {"load": False}

    def _explode(*a, **k):
        called["load"] = True
        raise AssertionError("torch.load must not run on a path outside the allowlist")

    torch = types.ModuleType("torch")
    torch.load = _explode
    monkeypatch.setitem(sys.modules, "torch", torch)

    allowed = tmp_path / "allowed"
    allowed.mkdir()
    monkeypatch.setenv(pq.ALLOW_LOCAL_PREQUANT_PATH_ENV, str(allowed))

    outside = tmp_path / "evil.pt"
    outside.write_bytes(b"x")
    source = PrequantSource(kind = "path", location = str(outside), filename = None)
    result = load_prequantized_transformer(
        _FakeTransformer,
        "Tongyi-MAI/Z-Image-Turbo",
        source,
        device = "cuda",
        dtype = "bfloat16",
        hf_token = None,
        scheme = "fp8",
        logger = None,
    )
    assert result is None
    assert called["load"] is False


def test_load_min_features_mismatch_is_none(monkeypatch, tmp_path):
    # a different --min-features quantises a different Linear set
    ckpt = _good_ckpt()
    ckpt["metadata"]["min_features"] = 256
    _FakeTransformer.calls = {}
    _stub_torch_accelerate(monkeypatch, ckpt)
    monkeypatch.setenv(pq.ALLOW_LOCAL_PREQUANT_PATH_ENV, str(tmp_path))
    path = tmp_path / "ckpt.pt"
    path.write_bytes(b"x")
    source = PrequantSource(kind = "path", location = str(path), filename = None)
    result = load_prequantized_transformer(
        _FakeTransformer,
        "Tongyi-MAI/Z-Image-Turbo",
        source,
        device = "cuda",
        dtype = "bfloat16",
        hf_token = None,
        scheme = "fp8",
        min_features = 512,
        logger = None,
    )
    assert result is None


def test_load_base_fork_tail_matches(monkeypatch, tmp_path):
    # a local path or fork id with the canonical base's final segment is accepted
    ckpt = _good_ckpt(base = "Tongyi-MAI/Z-Image-Turbo")
    _FakeTransformer.calls = {}
    _stub_torch_accelerate(monkeypatch, ckpt)
    monkeypatch.setenv(pq.ALLOW_LOCAL_PREQUANT_PATH_ENV, str(tmp_path))
    path = tmp_path / "ckpt.pt"
    path.write_bytes(b"x")
    source = PrequantSource(kind = "path", location = str(path), filename = None)
    result = load_prequantized_transformer(
        _FakeTransformer,
        "/local/models/Z-Image-Turbo",
        source,
        device = "cuda",
        dtype = "bfloat16",
        hf_token = None,
        scheme = "fp8",
        logger = None,
    )
    assert result is not None


class _FakeKernelPreference:
    """Stand-in for torchao's enum: only identity and attribute access matter here."""

    TORCH = "KernelPreference.TORCH"
    AUTO = "KernelPreference.AUTO"


def _stub_kernel_preference(monkeypatch):
    mod = types.ModuleType("torchao.quantization.quantize_.common.kernel_preference")
    mod.KernelPreference = _FakeKernelPreference
    for name in (
        "torchao",
        "torchao.quantization",
        "torchao.quantization.quantize_",
        "torchao.quantization.quantize_.common",
    ):
        monkeypatch.setitem(sys.modules, name, sys.modules.get(name) or types.ModuleType(name))
    monkeypatch.setitem(sys.modules, "torchao.quantization.quantize_.common.kernel_preference", mod)


class _FakeFp8Weight:
    def __init__(self, pref):
        self.kernel_preference = pref


def test_pin_kernel_preference_rewrites_auto(monkeypatch):
    # checkpoints serialize KernelPreference.AUTO, re-arming MSLK which has no fake impl for compile
    _stub_kernel_preference(monkeypatch)
    sd = {
        "a.weight": _FakeFp8Weight(_FakeKernelPreference.AUTO),
        "b.weight": _FakeFp8Weight(_FakeKernelPreference.AUTO),
        "c.weight": _FakeFp8Weight(_FakeKernelPreference.TORCH),
        "d.bias": object(),
    }
    pinned = pq._pin_kernel_preference(sd, logger = None)
    assert pinned == 2
    assert all(
        getattr(t, "kernel_preference", _FakeKernelPreference.TORCH) == _FakeKernelPreference.TORCH
        for t in sd.values()
    )


def test_pin_kernel_preference_survives_a_frozen_weight(monkeypatch):
    # a subclass refusing the assignment must not sink the load; it still works eagerly
    _stub_kernel_preference(monkeypatch)

    class _Frozen:
        kernel_preference = _FakeKernelPreference.AUTO

        def __setattr__(self, name, value):
            raise AttributeError("frozen")

    sd = {"a.weight": _Frozen(), "b.weight": _FakeFp8Weight(_FakeKernelPreference.AUTO)}
    assert pq._pin_kernel_preference(sd, logger = None) == 1


def test_pin_kernel_preference_no_torchao(monkeypatch):
    monkeypatch.setitem(
        sys.modules, "torchao.quantization.quantize_.common.kernel_preference", None
    )
    sd = {"a.weight": _FakeFp8Weight(_FakeKernelPreference.AUTO)}
    assert pq._pin_kernel_preference(sd, logger = None) == 0
    assert sd["a.weight"].kernel_preference == _FakeKernelPreference.AUTO


def test_prequant_checkpoint_cached_reads_only_the_cache(monkeypatch, tmp_path):
    # memory planning calls this, so it must be a pure lookup: no Hub call, no raise
    from core.inference.diffusion_prequant import prequant_checkpoint_cached

    ckpt = tmp_path / "Z-Image-Turbo-FP8.pt"
    ckpt.write_bytes(b"weights")
    legacy = tmp_path / "transformer_fp8.pt"
    legacy.write_bytes(b"weights")
    source = _prequant_source()
    asked: list = []
    absent: set = set()
    no_exist = object()  # huggingface_hub's sentinel for a recorded 404

    def _cache(
        repo_id,
        filename,
        cache_dir = None,
    ):
        asked.append((repo_id, filename, cache_dir))
        if filename in absent:
            return no_exist
        return str(tmp_path / filename) if (tmp_path / filename).is_file() else None

    monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", _cache)
    monkeypatch.setattr(
        "huggingface_hub.hf_hub_download",
        lambda *a, **k: pytest.fail("the cache probe must never download"),
    )

    assert prequant_checkpoint_cached(source, cache_dir = "/models/hub", online = True) is True
    assert asked == [("unsloth/Z-Image-Turbo-FP8", "Z-Image-Turbo-FP8.pt", "/models/hub")]

    # a cached name further down the chain counts, but only if the names ahead are absent online
    ckpt.unlink()
    assert prequant_checkpoint_cached(source, online = True) is False
    absent.add("Z-Image-Turbo-FP8.pt")
    assert prequant_checkpoint_cached(source, online = True) is True
    absent.clear()
    assert prequant_checkpoint_cached(source, online = False) is True
    legacy.unlink()
    assert prequant_checkpoint_cached(source, online = True) is False
    assert prequant_checkpoint_cached(source, online = False) is False


def test_a_live_root_hit_still_goes_through_the_hub_so_it_revalidates(monkeypatch, tmp_path):
    # hf_hub_download(cache_dir=live) revalidates; returning raw would pin a stale checkpoint
    live = tmp_path / "live-hub"
    live.mkdir()
    ckpt = live / "Z-Image-Turbo-FP8.pt"
    ckpt.write_bytes(b"weights")
    source = _prequant_source()

    def _cache(
        repo_id,
        filename,
        cache_dir = None,
    ):
        path = live / filename
        return str(path) if cache_dir == str(live) and path.is_file() else None

    monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", _cache)
    asked: list = []

    def _download(
        repo_id,
        filename,
        token = None,
        cache_dir = None,
        local_files_only = False,
    ):
        asked.append((filename, cache_dir))
        return str(ckpt)

    monkeypatch.setattr("huggingface_hub.hf_hub_download", _download)

    # still cached for the decline gate: a HEAD, not a multi-GB fetch
    assert pq.prequant_checkpoint_cached(source, cache_dir = str(live)) is True
    assert pq._resolve_checkpoint_path(source, None, str(live)) == str(ckpt)
    assert asked == [("Z-Image-Turbo-FP8.pt", str(live))]


def _other_root_source():
    return _prequant_source()


def test_a_hit_only_in_the_other_root_is_revalidated_through_that_root(monkeypatch, tmp_path):
    # rerun the download through the root holding the copy: one HEAD, no re-fetch, no stale pin
    default_root = tmp_path / "default-hub"
    default_root.mkdir()
    ckpt = default_root / "Z-Image-Turbo-FP8.pt"
    ckpt.write_bytes(b"weights")
    source = _other_root_source()

    def _cache(
        repo_id,
        filename,
        cache_dir = None,
    ):
        path = default_root / filename
        return str(path) if cache_dir is None and path.is_file() else None

    monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", _cache)
    asked: list = []

    def _download(
        repo_id,
        filename,
        token = None,
        cache_dir = None,
        local_files_only = False,
    ):
        asked.append((filename, cache_dir))
        return str(ckpt)

    monkeypatch.setattr("huggingface_hub.hf_hub_download", _download)

    assert pq.prequant_checkpoint_cached(source, cache_dir = "/models/live") is True
    assert pq._resolve_checkpoint_path(source, None, "/models/live") == str(ckpt)
    # never pin to the empty live root: that is the multi-GB re-fetch the caller declined
    assert asked == [("Z-Image-Turbo-FP8.pt", None)]


def test_a_republished_checkpoint_in_the_other_root_is_picked_up(monkeypatch, tmp_path):
    default_root = tmp_path / "default-hub"
    default_root.mkdir()
    stale = default_root / "Z-Image-Turbo-FP8.pt"
    stale.write_bytes(b"old weights")
    fresh = default_root / "snapshots-new" / "Z-Image-Turbo-FP8.pt"
    fresh.parent.mkdir()
    fresh.write_bytes(b"corrected weights")

    monkeypatch.setattr(
        "huggingface_hub.try_to_load_from_cache",
        lambda repo_id, filename, cache_dir = None, **k: (
            str(stale) if cache_dir is None and filename == "Z-Image-Turbo-FP8.pt" else None
        ),
    )
    monkeypatch.setattr("huggingface_hub.hf_hub_download", lambda **kwargs: str(fresh))

    assert pq._resolve_checkpoint_path(_other_root_source(), None, "/models/live") == str(fresh)


def test_other_root_revalidation_never_breaks_a_load_that_works(monkeypatch, tmp_path):
    # any other hf_hub_download error must fall back to the copy already located
    default_root = tmp_path / "default-hub"
    default_root.mkdir()
    ckpt = default_root / "Z-Image-Turbo-FP8.pt"
    ckpt.write_bytes(b"weights")

    monkeypatch.setattr(
        "huggingface_hub.try_to_load_from_cache",
        lambda repo_id, filename, cache_dir = None, **k: (
            str(default_root / filename)
            if cache_dir is None and (default_root / filename).is_file()
            else None
        ),
    )
    asked: list = []

    def _download(**kwargs):
        asked.append(kwargs["cache_dir"])
        raise RuntimeError("hub is unhappy")

    monkeypatch.setattr("huggingface_hub.hf_hub_download", _download)

    assert pq._resolve_checkpoint_path(_other_root_source(), None, "/models/live") == str(ckpt)
    assert asked == [None]


def test_an_uncached_checkpoint_downloads_into_the_live_root(monkeypatch):
    asked: list = []
    source = PrequantSource(
        kind = "repo", location = "unsloth/Z-Image-Turbo-FP8", filename = "Z-Image-Turbo-FP8.pt"
    )

    def _dl(**kwargs):
        asked.append(kwargs)
        return "/live-hub/blobs/abc"

    monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", lambda *a, **k: None)
    monkeypatch.setattr("huggingface_hub.hf_hub_download", _dl)

    assert pq._resolve_checkpoint_path(source, "tok", "/live-hub") == "/live-hub/blobs/abc"
    assert asked == [
        {
            "repo_id": "unsloth/Z-Image-Turbo-FP8",
            "filename": "Z-Image-Turbo-FP8.pt",
            "token": "tok",
            "cache_dir": "/live-hub",
            # only API-initiated loads are pinned to the cache, via the caller's flag
            "local_files_only": False,
        }
    ]


def test_prequant_checkpoint_cached_never_raises(monkeypatch):
    # an unanswerable probe is not cached, never an exception into the planner
    from core.inference.diffusion_prequant import prequant_checkpoint_cached

    monkeypatch.setattr(
        "huggingface_hub.try_to_load_from_cache",
        lambda *a, **k: (_ for _ in ()).throw(OSError("unreadable cache")),
    )
    source = PrequantSource(kind = "repo", location = "org/hosted-fp8", filename = "hosted-FP8.pt")
    assert prequant_checkpoint_cached(source) is False
    assert prequant_checkpoint_cached(PrequantSource(kind = "path", location = "/tmp/x.pt")) is False
    assert prequant_checkpoint_cached(None) is False


def test_a_cached_legacy_file_does_not_pre_empt_the_canonical_one(monkeypatch, tmp_path):
    """fallback_filename is tried only once the canonical name is absent remotely, so a cached
    legacy .pt cannot pin a stale file."""
    from core.inference.diffusion_prequant import _resolve_checkpoint_path

    legacy = tmp_path / "transformer_fp8.pt"
    legacy.write_bytes(b"stale")
    source = _prequant_source()
    monkeypatch.setattr(
        "huggingface_hub.try_to_load_from_cache",
        lambda repo_id, filename, cache_dir = None: (
            str(tmp_path / filename) if (tmp_path / filename).is_file() else None
        ),
    )
    asked: list = []

    def _download(
        repo_id,
        filename,
        token = None,
        cache_dir = None,
        local_files_only = False,
    ):
        asked.append(filename)
        return str(tmp_path / "downloaded-canonical.pt")

    monkeypatch.setattr("huggingface_hub.hf_hub_download", _download)

    assert _resolve_checkpoint_path(source, None) == str(tmp_path / "downloaded-canonical.pt")
    assert asked == ["Z-Image-Turbo-FP8.pt"]


def test_the_legacy_name_is_still_used_once_the_canonical_one_is_absent(monkeypatch, tmp_path):
    """A repo shipping only the legacy artifact must still load through fallback_filename."""
    from huggingface_hub.errors import EntryNotFoundError

    from core.inference.diffusion_prequant import _resolve_checkpoint_path

    source = _prequant_source()
    monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", lambda *a, **k: None)
    asked: list = []

    def _download(
        repo_id,
        filename,
        token = None,
        cache_dir = None,
        local_files_only = False,
    ):
        asked.append(filename)
        if filename == "Z-Image-Turbo-FP8.pt":
            raise EntryNotFoundError("404")
        return str(tmp_path / filename)

    monkeypatch.setattr("huggingface_hub.hf_hub_download", _download)

    assert _resolve_checkpoint_path(source, None) == str(tmp_path / "transformer_fp8.pt")
    assert asked == ["Z-Image-Turbo-FP8.pt", "transformer_fp8.pt"]


def test_a_legacy_copy_in_the_other_root_is_reused_after_the_primary_404s(monkeypatch, tmp_path):
    """A legacy copy in the other root is revalidated there after the primary 404s, not re-fetched
    or returned raw."""
    from huggingface_hub.errors import EntryNotFoundError

    default_root = tmp_path / "default-hub"
    default_root.mkdir()
    legacy = default_root / "transformer_fp8.pt"
    legacy.write_bytes(b"weights")
    source = _prequant_source()

    def _cache(
        repo_id,
        filename,
        cache_dir = None,
    ):
        path = default_root / filename
        return str(path) if cache_dir is None and path.is_file() else None

    monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", _cache)
    asked: list = []

    def _download(
        repo_id,
        filename,
        token = None,
        cache_dir = None,
        local_files_only = False,
    ):
        asked.append((filename, cache_dir))
        if filename == "Z-Image-Turbo-FP8.pt":
            raise EntryNotFoundError("404")
        return str(legacy)

    monkeypatch.setattr("huggingface_hub.hf_hub_download", _download)

    assert pq._resolve_checkpoint_path(source, None, "/models/live") == str(legacy)
    # legacy is revalidated through the root holding it, never re-fetched into the live one
    assert asked == [("Z-Image-Turbo-FP8.pt", "/models/live"), ("transformer_fp8.pt", None)]


def test_a_primary_404_during_revalidation_still_reaches_the_legacy_fallback(monkeypatch, tmp_path):
    """Other-root revalidation must not swallow the primary's 404, or an old canonical copy is
    returned and the fallback name is never reached."""
    from huggingface_hub.errors import EntryNotFoundError

    default_root = tmp_path / "default-hub"
    default_root.mkdir()
    stale = default_root / "Z-Image-Turbo-FP8.pt"
    stale.write_bytes(b"obsolete")
    live = str(tmp_path / "live")

    monkeypatch.setattr(
        "huggingface_hub.try_to_load_from_cache",
        lambda repo_id, filename, cache_dir = None, **k: (
            str(default_root / filename)
            if cache_dir is None and (default_root / filename).is_file()
            else None
        ),
    )
    asked: list = []

    def _download(
        repo_id,
        filename,
        token = None,
        cache_dir = None,
        local_files_only = False,
    ):
        asked.append((filename, cache_dir))
        if filename == "Z-Image-Turbo-FP8.pt":
            raise EntryNotFoundError("404: the repo no longer publishes this name")
        return str(tmp_path / "fresh-legacy.pt")

    monkeypatch.setattr("huggingface_hub.hf_hub_download", _download)

    assert pq._resolve_checkpoint_path(_other_root_source(), None, live) == str(
        tmp_path / "fresh-legacy.pt"
    )
    assert asked == [("Z-Image-Turbo-FP8.pt", None), ("transformer_fp8.pt", live)]


def test_offline_revalidation_still_returns_the_other_root_copy(monkeypatch, tmp_path):
    """A LOCAL cache miss is not "absent remotely": huggingface_hub raises LocalEntryNotFoundError
    (a subclass of EntryNotFoundError on both majors) when it cannot reach the Hub, so telling it
    apart from a real 404 is what keeps an offline load from dropping the prequant."""
    from huggingface_hub.errors import LocalEntryNotFoundError

    default_root = tmp_path / "default-hub"
    default_root.mkdir()
    ckpt = default_root / "Z-Image-Turbo-FP8.pt"
    ckpt.write_bytes(b"weights")

    monkeypatch.setattr(
        "huggingface_hub.try_to_load_from_cache",
        lambda repo_id, filename, cache_dir = None, **k: (
            str(default_root / filename)
            if cache_dir is None and (default_root / filename).is_file()
            else None
        ),
    )
    asked: list = []

    def _download(
        repo_id,
        filename,
        token = None,
        cache_dir = None,
        local_files_only = False,
    ):
        asked.append((filename, cache_dir))
        raise LocalEntryNotFoundError("offline and not in this root")

    monkeypatch.setattr("huggingface_hub.hf_hub_download", _download)

    assert pq._resolve_checkpoint_path(_other_root_source(), None, "/models/live") == str(ckpt)
    assert asked == [("Z-Image-Turbo-FP8.pt", None)]


def test_with_no_fallback_name_a_404_keeps_the_other_root_copy(monkeypatch, tmp_path):
    """Propagating the 404 only makes sense while another filename is left to try. With none, the
    copy already located is still the best answer, so revalidation stays a bonus."""
    from huggingface_hub.errors import EntryNotFoundError

    default_root = tmp_path / "default-hub"
    default_root.mkdir()
    ckpt = default_root / "X-FP8.pt"
    ckpt.write_bytes(b"weights")
    source = PrequantSource(kind = "repo", location = "unsloth/X-FP8", filename = "X-FP8.pt")

    monkeypatch.setattr(
        "huggingface_hub.try_to_load_from_cache",
        lambda repo_id, filename, cache_dir = None, **k: (
            str(default_root / filename)
            if cache_dir is None and (default_root / filename).is_file()
            else None
        ),
    )
    monkeypatch.setattr(
        "huggingface_hub.hf_hub_download",
        lambda **k: (_ for _ in ()).throw(EntryNotFoundError("404")),
    )

    assert pq._resolve_checkpoint_path(source, None, "/models/live") == str(ckpt)


def test_load_config_reads_the_same_cache_root_as_the_checkpoint(monkeypatch, tmp_path):
    """load_config forwards cache_dir to hf_hub_download, so unpinned it reads huggingface_hub's
    import-time constant. After a mid-session cache change that root may be gone or read-only, and
    the raise is swallowed into a None return: the prequant is silently dropped."""
    import torch

    from core.inference import diffusion_prequant as P

    seen: list = []
    live_root = tmp_path / "live"
    live_root.mkdir()
    live = str(live_root)
    ckpt = live_root / "ck.pt"
    ckpt.write_bytes(b"x")

    monkeypatch.setattr(P, "_resolve_checkpoint_path", lambda s, t, c = None, **_: str(ckpt))
    monkeypatch.setattr(P, "_validate_checkpoint", lambda *a, **k: True)
    monkeypatch.setattr(P, "_pin_kernel_preference", lambda *a, **k: 0)
    monkeypatch.setattr(torch, "load", lambda *a, **k: {"state_dict": {}, "scheme": "int8"})

    class _Cls:
        @staticmethod
        def load_config(
            base,
            subfolder = None,
            token = None,
            cache_dir = None,
            local_files_only = False,
        ):
            seen.append(cache_dir)
            raise RuntimeError("stop right after the config fetch")

    src = P.PrequantSource(kind = "repo", location = "unsloth/X-FP8", filename = "X-FP8.pt")
    assert (
        P.load_prequantized_transformer(
            _Cls,
            "org/base",
            src,
            device = "cpu",
            dtype = torch.bfloat16,
            scheme = "int8",
            cache_dir = live,
        )
        is None
    )

    assert seen[0] == live


def test_the_config_follows_the_checkpoint_into_the_other_cache_root(monkeypatch, tmp_path):
    """``_resolve_checkpoint_path`` can answer from huggingface_hub's import-time root while Unsloth
    pins its live one, so a config pinned to the live root misses in exactly the cache-moved case
    the checkpoint lookup just accepted -- silently, as the raise becomes a None return."""
    import torch

    from core.inference import diffusion_prequant as P

    seen: list = []
    live = str(tmp_path / "live")
    other_root = tmp_path / "default-hub"
    other_root.mkdir()
    ckpt = other_root / "ck.pt"
    ckpt.write_bytes(b"x")

    monkeypatch.setattr(P, "_resolve_checkpoint_path", lambda s, t, c = None, **_: str(ckpt))
    monkeypatch.setattr(P, "_validate_checkpoint", lambda *a, **k: True)
    monkeypatch.setattr(P, "_pin_kernel_preference", lambda *a, **k: 0)
    monkeypatch.setattr(torch, "load", lambda *a, **k: {"state_dict": {}, "scheme": "int8"})
    monkeypatch.setattr(P, "_has_meta_tensors", lambda *a, **k: False)
    accelerate = types.ModuleType("accelerate")
    accelerate.init_empty_weights = lambda: contextlib.nullcontext()
    monkeypatch.setitem(sys.modules, "accelerate", accelerate)

    class _Transformer:
        def load_state_dict(self, *a, **k):
            return None

        def to(self, device):
            return self

        def eval(self):
            return self

    class _Cls:
        @staticmethod
        def load_config(
            base,
            subfolder = None,
            token = None,
            cache_dir = None,
            local_files_only = False,
        ):
            seen.append(cache_dir)
            if cache_dir is not None:
                raise OSError("the live root has no cached config for this base")
            return {"ok": True}

        @staticmethod
        def from_config(config):
            return _Transformer()

    src = P.PrequantSource(kind = "repo", location = "unsloth/X-FP8", filename = "X-FP8.pt")
    out = P.load_prequantized_transformer(
        _Cls,
        "org/base",
        src,
        device = "cpu",
        dtype = torch.bfloat16,
        scheme = "int8",
        cache_dir = live,
    )

    assert isinstance(out, _Transformer)
    assert seen == [None]


def test_load_pads_the_small_m_linears_with_the_recorded_family(monkeypatch, tmp_path):
    """Pre-quant load must pad the small-M linears using the family recorded in the checkpoint metadata."""
    from core.inference.diffusion_transformer_quant import exclude_tokens_for_scheme

    seen = {}

    def _spy(
        transformer,
        scheme,
        family = None,
        logger = None,
    ):
        seen["args"] = (scheme, family)
        return ("context_embedder",)

    monkeypatch.setattr("core.inference.diffusion_transformer_quant.apply_small_m_padding", _spy)
    ckpt = _good_ckpt(scheme = "int8")
    ckpt["metadata"]["family"] = "minimax-h3"
    ckpt["metadata"]["exclude_name_tokens"] = list(exclude_tokens_for_scheme("int8", "minimax-h3"))
    assert _load(monkeypatch, tmp_path, ckpt, scheme = "int8") is not None
    assert seen["args"] == ("int8", "minimax-h3")


def test_load_is_dropped_when_the_padding_cannot_be_proven(monkeypatch, tmp_path):
    """If padding cannot be proven, drop the prequant and dense-quantise; never half-pad the model."""

    def _boom(
        transformer,
        scheme,
        family = None,
        logger = None,
    ):
        raise RuntimeError("cannot prove per-row granularity")

    monkeypatch.setattr("core.inference.diffusion_transformer_quant.apply_small_m_padding", _boom)
    ckpt = _good_ckpt(scheme = "int8")
    ckpt["metadata"]["family"] = "minimax-h3"
    assert _load(monkeypatch, tmp_path, ckpt, scheme = "int8") is None


def test_an_fp8_checkpoint_without_the_activation_floor_is_detected():
    # pre-floor builds bake hp_value_lb=None (zero row -> scale 0 -> NaN); read the tensors
    floored = {"blocks.0.attn.to_q.weight": Float8Tensor(hp_value_lb = 1e-12)}
    unfloored = {"blocks.0.attn.to_q.weight": Float8Tensor(hp_value_lb = None)}
    assert pq._fp8_activation_floor_present(floored, None) is True
    assert pq._fp8_activation_floor_present(unfloored, None) is False
    # zero is not a floor: it is what an unclamped amax divide produces
    assert pq._fp8_activation_floor_present({"w": Float8Tensor(hp_value_lb = 0.0)}, None) is False


def test_an_fp8_checkpoint_without_the_floor_loads_with_the_runtime_floor(monkeypatch, tmp_path):
    # the floor is not weight data, so a pre-floor artifact holds the exact runtime weights
    from core.inference.diffusion_transformer_quant import FP8_ACTIVATION_VALUE_LB

    ckpt = _good_ckpt(scheme = "fp8")
    shared = types.SimpleNamespace(hp_value_lb = None, hp_value_ub = None)
    first, second, floored = Float8Tensor(), Float8Tensor(), Float8Tensor(hp_value_lb = 1e-9)
    first.act_quant_kwargs = shared
    second.act_quant_kwargs = shared  # a pickle may share one kwargs object between tensors
    ckpt["state_dict"] = {
        "a.weight": first,
        "b.weight": second,
        "c.weight": floored,
        "d.bias": object(),
    }
    out = _load(monkeypatch, tmp_path, ckpt, scheme = "fp8")
    assert out is not None
    assert pq.last_prequant_failure() is None
    assert first.act_quant_kwargs.hp_value_lb == FP8_ACTIVATION_VALUE_LB
    assert second.act_quant_kwargs.hp_value_lb == FP8_ACTIVATION_VALUE_LB
    assert first.act_quant_kwargs is not second.act_quant_kwargs
    assert shared.hp_value_lb is None
    assert floored.act_quant_kwargs.hp_value_lb == 1e-9


def test_an_fp8_checkpoint_differing_in_more_than_the_floor_stays_refused(monkeypatch, tmp_path):
    ckpt = _good_ckpt(scheme = "fp8")
    capped = Float8Tensor(hp_value_lb = None)
    capped.act_quant_kwargs.hp_value_ub = 1e4
    ckpt["state_dict"] = {"a.weight": capped}
    assert _load(monkeypatch, tmp_path, ckpt, scheme = "fp8") is None
    assert "no activation scale floor" in (pq.last_prequant_failure() or "")
    no_field = Float8Tensor()
    no_field.act_quant_kwargs = types.SimpleNamespace()
    assert pq._fp8_activation_floor_restorable({"a.weight": no_field}) is False


def test_the_floor_check_ignores_dense_and_unreadable_state_dicts():
    # dense tensors carry no act_quant_kwargs; failing closed would reject every int8 checkpoint
    assert pq._fp8_activation_floor_present({"w": object()}, None) is True
    assert pq._fp8_activation_floor_present(None, None) is True
    assert pq._fp8_activation_floor_present({}, None) is True


def _policy_meta(
    policy = None,
    *,
    base = "Tongyi-MAI/Z-Image-Turbo",
    family = "z-image",
    **overrides,
):
    from core.inference.diffusion_nvfp4_policy import (
        NVFP4_POLICY_KEY,
        ZIMG_RG76,
        policy_metadata,
    )

    policy = policy or ZIMG_RG76
    assignment = {f"layers.{i}.attention.to_q": "nvfp4" for i in range(76)}
    assignment.update({f"layers.{i}.feed_forward.w1": "fp8" for i in range(195)})
    assignment.update({f"t_embedder.mlp.{i}": "bf16" for i in range(5)})
    block = dict(policy_metadata(policy, assignment)[NVFP4_POLICY_KEY])
    block.update(overrides)
    return {
        "scheme": "nvfp4",
        "base_model_id": base,
        "family": family,
        "fp8_granularity": "per_row",
        NVFP4_POLICY_KEY: block,
    }


def test_the_format_tag_follows_the_policy_and_refuses_to_carry_two_claims():
    from core.inference.diffusion_convrot import rotation_metadata

    assert pq.prequant_format_for({"scheme": "nvfp4"}) == pq.PREQUANT_FORMAT
    assert pq.prequant_format_for(_policy_meta()) == pq.PREQUANT_FORMAT_POLICY
    assert pq.PREQUANT_FORMAT_POLICY not in (pq.PREQUANT_FORMAT, pq.PREQUANT_FORMAT_ROTATED)
    both = {**_policy_meta(), **rotation_metadata(128, ["layers.0.attention.to_q"])}
    with pytest.raises(ValueError, match = "both"):
        pq.prequant_format_for(both)


@pytest.mark.parametrize(
    ("fmt", "declared", "ok"),
    [
        (pq.PREQUANT_FORMAT_POLICY, True, True),
        (pq.PREQUANT_FORMAT, False, True),
        (pq.PREQUANT_FORMAT, True, False),
        (pq.PREQUANT_FORMAT_ROTATED, True, False),
        (pq.PREQUANT_FORMAT_POLICY, False, False),
    ],
)
def test_the_validator_enforces_the_format_policy_biconditional(fmt, declared, ok):
    meta = _policy_meta() if declared else {"scheme": "nvfp4"}
    assert pq._validate_policy(fmt, meta, "nvfp4", None) is ok


def test_a_policy_declaration_this_build_cannot_reproduce_is_refused():
    from core.inference.diffusion_nvfp4_policy import NVFP4_POLICY_KEY

    fmt = pq.PREQUANT_FORMAT_POLICY
    assert pq._validate_policy(fmt, _policy_meta(), "nvfp4", None) is True
    assert pq._validate_policy(fmt, _policy_meta(kind = "v2"), "nvfp4", None) is False
    assert pq._validate_policy(fmt, _policy_meta(nvfp4_fqns = []), "nvfp4", None) is False
    assert pq._validate_policy(fmt, _policy_meta(), "fp8", None) is False
    assert pq._validate_policy(fmt, _policy_meta(base = "some/other-dit"), "nvfp4", None) is False
    assert pq._validate_policy(fmt, _policy_meta(family = "flux.1"), "nvfp4", None) is False
    assert pq._validate_policy(fmt, _policy_meta(policy_version = 2), "nvfp4", None) is False
    assert pq._validate_policy(fmt, _policy_meta(policy_id = "qwen_p02_v1"), "nvfp4", None) is False
    drifted = _policy_meta()
    drifted[NVFP4_POLICY_KEY]["counts"] = {"nvfp4": 34, "fp8": 236, "bf16": 6}
    assert pq._validate_policy(fmt, drifted, "nvfp4", None) is False


def test_a_policy_checkpoint_is_validated_end_to_end():
    logger = _Recorder()
    ckpt = {
        "format": pq.PREQUANT_FORMAT_POLICY,
        "metadata": _policy_meta(),
        "state_dict": {"weight": object()},
    }
    assert pq._validate_checkpoint(ckpt, "nvfp4", "Tongyi-MAI/Z-Image-Turbo", logger) is True
    ckpt["format"] = pq.PREQUANT_FORMAT
    assert pq._validate_checkpoint(ckpt, "nvfp4", "Tongyi-MAI/Z-Image-Turbo", logger) is False
    assert "v3" in logger.text


def test_the_fp8_invariants_cover_the_fp8_half_of_a_policy_checkpoint():
    # policy artifacts are declared nvfp4 but mostly Float8Tensor, so do not gate on scheme
    logger = _Recorder()
    ckpt = {
        "format": pq.PREQUANT_FORMAT_POLICY,
        "metadata": _policy_meta(),
        "state_dict": {
            "layers.0.attention.to_q.weight": NVFP4Tensor(b"q4"),
            "layers.0.feed_forward.w1.weight": Float8Tensor(hp_value_lb = 1e-12),
        },
    }
    base = "Tongyi-MAI/Z-Image-Turbo"
    assert pq._validate_checkpoint(ckpt, "nvfp4", base, logger) is True
    unfloored = dict(ckpt)
    unfloored["state_dict"] = dict(ckpt["state_dict"])
    unfloored["state_dict"]["layers.0.feed_forward.w1.weight"] = Float8Tensor(hp_value_lb = None)
    # an unfloored fp8 half is restorable: the load writes the runtime floor in, so it validates
    assert pq._validate_checkpoint(unfloored, "nvfp4", base, logger) is True
    capped = Float8Tensor(hp_value_lb = None)
    capped.act_quant_kwargs.hp_value_ub = 1.0
    unfloored["state_dict"]["layers.0.feed_forward.w1.weight"] = capped
    assert pq._validate_checkpoint(unfloored, "nvfp4", base, logger) is False
    per_tensor = dict(ckpt)
    per_tensor["metadata"] = _policy_meta()
    per_tensor["metadata"]["fp8_granularity"] = "per_tensor"
    assert pq._validate_checkpoint(per_tensor, "nvfp4", base, logger) is False


def test_the_floor_check_skips_the_4_bit_weights_beside_the_fp8_ones():
    mixed = {
        "layers.0.attention.to_q.weight": NVFP4Tensor(b"q4"),
        "layers.0.feed_forward.w1.weight": Float8Tensor(hp_value_lb = 1e-12),
    }
    assert pq._fp8_activation_floor_present(mixed, None) is True
    mixed["layers.0.feed_forward.w1.weight"] = Float8Tensor(hp_value_lb = None)
    assert pq._fp8_activation_floor_present(mixed, None) is False
    assert pq._fp8_activation_floor_present({"w": NVFP4Tensor()}, None) is True


def test_pinning_the_fp8_kernel_leaves_the_4_bit_weights_alone(monkeypatch):
    _stub_kernel_preference(monkeypatch)
    sd = {
        "layers.0.attention.to_q.weight": NVFP4Tensor(b"q4"),
        "layers.0.feed_forward.w1.weight": _FakeFp8Weight(_FakeKernelPreference.AUTO),
    }
    assert pq._pin_kernel_preference(sd, logger = None) == 1
    assert not hasattr(sd["layers.0.attention.to_q.weight"], "kernel_preference")


def test_nvfp4_has_no_pickle_requirements_because_it_is_never_unpickled():
    assert "nvfp4" not in pq._SCHEME_REQUIRED_GLOBALS
    # fp8 / int8 keep their pickle requirements unchanged
    assert {"int8", "fp8", "mxfp8"} <= set(pq._SCHEME_REQUIRED_GLOBALS)


def test_the_checkpoint_is_released_before_the_device_copy(monkeypatch, tmp_path):
    """The CPU checkpoint must be unreferenced by the time ``.to(device)`` allocates (unified memory peak)."""
    import weakref

    seen: dict = {}

    class _StateDict(dict):
        """A weak-referenceable state dict: plain dicts cannot be weakly referenced."""

    class _ReleaseProbe(_FakeTransformer):
        def load_state_dict(
            self,
            sd,
            strict = True,
            assign = False,
        ):
            _FakeTransformer.calls["load_state_dict"] = {"strict": strict, "assign": assign}
            seen["state_dict"] = weakref.ref(sd)

        def to(self, device):
            seen["alive_at_move"] = seen["state_dict"]() is not None
            return super().to(device)

    _FakeTransformer.calls = {}
    _stub_torch_accelerate(monkeypatch, None)
    monkeypatch.setattr(
        pq,
        "_torch_load_prequant",
        lambda path, **kwargs: {
            "format": PREQUANT_FORMAT,
            "metadata": {"scheme": "int8", "base_model_id": "Tongyi-MAI/Z-Image-Turbo"},
            "state_dict": _StateDict(weight = object()),
        },
    )
    monkeypatch.setenv(pq.ALLOW_LOCAL_PREQUANT_PATH_ENV, str(tmp_path))
    path = tmp_path / "ckpt.pt"
    path.write_bytes(b"x")

    out = load_prequantized_transformer(
        _ReleaseProbe,
        "Tongyi-MAI/Z-Image-Turbo",
        PrequantSource(kind = "path", location = str(path), filename = None),
        device = "cuda",
        dtype = "bfloat16",
        scheme = "int8",
    )

    assert out is not None
    assert seen["alive_at_move"] is False


def test_the_plan_only_commits_to_a_hosted_name_this_install_can_open(monkeypatch):
    """The plan may commit to a hosted name only if this install can open it, not merely if it exists."""
    from core.inference.diffusion import DiffusionBackend

    class _Sibling:
        def __init__(self, name, size):
            self.rfilename, self.size = name, size

    class _Info:
        siblings = [_Sibling("Model-FP8.pt", 4096)]

    class _Api:
        def __init__(self, *a, **k):
            pass

        def model_info(self, *a, **k):
            return _Info()

    import huggingface_hub

    monkeypatch.setattr(huggingface_hub, "HfApi", _Api)
    source = pq.PrequantSource(
        kind = "repo",
        location = "unsloth/Model-FP8",
        filename = "Model-FP8.safetensors",
        fallback_filenames = ("Model-FP8.pt",),
    )

    monkeypatch.setattr(pq, "restricted_prequant_load_supported", lambda *a, **k: True)
    assert DiffusionBackend._prequant_source_hub_entry(source, None, scheme = "fp8") == (
        "unsloth/Model-FP8",
        "Model-FP8.pt",
        4096,
    )

    monkeypatch.setattr(
        pq,
        "restricted_prequant_load_supported",
        lambda scheme = None, filename = None: bool(filename) and filename.endswith(".safetensors"),
    )
    failures: list = []
    assert DiffusionBackend._prequant_source_hub_entry(source, None, failures, scheme = "fp8") is None
    assert failures, "an unopenable artifact has to leave the plan marked partial"


def test_the_runtime_resolver_applies_the_same_capability_filter_as_the_plan(monkeypatch):
    """Plan and runtime must select the same artifact, or a second multi-GB download fails on it."""
    asked: list = []

    def _download(
        source,
        name,
        hf_token,
        cache_dir,
        *,
        propagate_missing,
        local_files_only = False,
    ):
        asked.append(name)
        return "/tmp/" + name

    monkeypatch.setattr(pq, "_download_checkpoint_name", _download)
    monkeypatch.setattr(
        pq,
        "restricted_prequant_load_supported",
        lambda scheme = None, filename = None: not str(filename or "").endswith(".safetensors"),
    )
    source = pq.PrequantSource(
        kind = "repo",
        location = "unsloth/Model-FP8",
        filename = "Model-FP8.safetensors",
        fallback_filenames = ("Model-FP8.pt",),
    )
    assert pq._resolve_checkpoint_path(source, None, scheme = "fp8") == "/tmp/Model-FP8.pt"
    assert asked == ["Model-FP8.pt"], f"the unreadable container was fetched anyway: {asked}"

    asked.clear()
    assert pq._resolve_checkpoint_path(source, None) == "/tmp/Model-FP8.safetensors"
    assert asked == ["Model-FP8.safetensors"], asked


def test_a_cached_pickle_is_not_evidence_for_a_safetensors_artifact(monkeypatch):
    """A cached legacy .pt must not count as evidence for a safetensors artifact, or planning drops
    the dense shards and resolves neither file."""
    fam = DiffusionFamily(
        name = "probe-fam",
        pipeline_class = "ProbePipeline",
        transformer_class = "ProbeTransformer",
        base_repo = "probe/Probe",
        prequant_repos = (("fp8", "unsloth/Probe-FP8"),),
    )
    monkeypatch.setattr(
        pq,
        "restricted_prequant_load_supported",
        lambda scheme = None, filename = None: str(filename or "").endswith(".safetensors"),
    )
    cached: dict = {}
    monkeypatch.setattr(
        pq,
        "cached_checkpoint_path",
        lambda source, cache_dir = None, names = None, **kw: next(
            (v for k, v in cached.items() if names is None or k in names), None
        ),
    )
    # a cached .pt is no evidence for the derived safetensors name
    cached["Probe-FP8.pt"] = "/cache/Probe-FP8.pt"
    assert pq.usable_prequant_source(fam, "fp8", base_repo = "probe/Probe") is None
    cached["Probe-FP8.safetensors"] = "/cache/Probe-FP8.safetensors"
    assert pq.usable_prequant_source(fam, "fp8", base_repo = "probe/Probe") is not None


def test_an_unreachable_hub_is_reported_as_itself_not_blamed_on_the_last_candidate(monkeypatch):
    """An unreachable Hub must be reported as itself, not blamed on the last candidate name."""
    from huggingface_hub.errors import EntryNotFoundError, LocalEntryNotFoundError

    asked: list = []

    def _dl(
        repo_id,
        filename,
        token = None,
        cache_dir = None,
        local_files_only = False,
    ):
        asked.append(filename)
        raise LocalEntryNotFoundError("connection error")

    hub = types.ModuleType("huggingface_hub")
    hub.hf_hub_download = _dl
    monkeypatch.setitem(sys.modules, "huggingface_hub", hub)

    source = PrequantSource(
        kind = "repo",
        location = "org/hosted-fp8",
        filename = "Hosted-FP8.safetensors",
        fallback_filenames = ("Hosted-FP8.pt", "transformer_fp8.pt"),
    )
    with pytest.raises(LocalEntryNotFoundError):
        pq._resolve_checkpoint_path(source, None, None)
    assert asked == ["Hosted-FP8.safetensors"], asked

    # offline, that exception is the only verdict, so the chain must be walked
    asked.clear()
    with pytest.raises(EntryNotFoundError):
        pq._resolve_checkpoint_path(source, None, None, local_files_only = True)
    assert asked == ["Hosted-FP8.safetensors", "Hosted-FP8.pt", "transformer_fp8.pt"], asked


def test_a_cached_name_this_install_cannot_open_is_not_a_cache_hit(monkeypatch, tmp_path):
    """A cached file this install cannot open is not a hit, or the dense shards are dropped for nothing."""
    source = PrequantSource(
        kind = "repo",
        location = "org/hosted-fp8",
        filename = "Hosted-FP8.safetensors",
        fallback_filenames = ("Hosted-FP8.pt",),
    )
    cached = {"Hosted-FP8.safetensors": str(tmp_path / "st"), "Hosted-FP8.pt": None}
    monkeypatch.setattr(pq, "_cached_in_root", lambda src, root, name = None: cached.get(name))

    monkeypatch.setattr(
        pq, "restricted_prequant_load_supported", lambda scheme = None, name = None: True
    )
    assert pq.cached_checkpoint_path(source) == str(tmp_path / "st")

    # the only cached name is unreadable by this install: a miss, so dense shards stay planned
    monkeypatch.setattr(
        pq,
        "restricted_prequant_load_supported",
        lambda scheme = None, name = None: not str(name).endswith(".safetensors"),
    )
    assert pq.cached_checkpoint_path(source) is None

    def _boom(scheme = None, name = None):
        raise RuntimeError("torchao exploded")

    monkeypatch.setattr(pq, "restricted_prequant_load_supported", _boom)
    assert pq.cached_checkpoint_path(source) == str(tmp_path / "st")


def _refused(cls, status):
    message = f"{status} Client Error: unsloth/Z-Image-Turbo-NVFP4"
    try:
        return cls(message, response = None)
    except (TypeError, AttributeError):  # huggingface_hub >= 1.0 reads an httpx response
        import httpx
        request = httpx.Request(
            "GET", "https://huggingface.co/api/models/unsloth/Z-Image-Turbo-NVFP4"
        )
        return cls(message, response = httpx.Response(status, request = request))


def _nvfp4_repo_source():
    return PrequantSource(
        kind = "repo",
        location = "unsloth/Z-Image-Turbo-NVFP4",
        filename = "Z-Image-Turbo-NVFP4.safetensors",
    )


@pytest.mark.parametrize(
    "error_name,status",
    [("RepositoryNotFoundError", 401), ("RepositoryNotFoundError", 404), ("GatedRepoError", 403)],
)
def test_a_refused_prequant_repo_is_no_checkpoint_not_a_plan_failure(
    monkeypatch, error_name, status
):
    import huggingface_hub
    from huggingface_hub import errors as hub_errors

    from core.inference.diffusion import DiffusionBackend

    def _refuse(self, *a, **k):
        raise _refused(getattr(hub_errors, error_name), status)

    monkeypatch.setattr(huggingface_hub.HfApi, "model_info", _refuse)
    failures: list = []
    entry = DiffusionBackend._prequant_source_hub_entry(
        _nvfp4_repo_source(), None, failures, scheme = "nvfp4"
    )
    assert entry is None
    assert failures == [], "a repo this user cannot see must not mark the download plan failed"


def test_a_transient_hub_error_still_fails_the_plan(monkeypatch):
    """Only the repo-level refusal is "no checkpoint". A network error says nothing about the repo,
    so it still propagates and the planner records it."""
    import huggingface_hub

    from core.inference.diffusion import DiffusionBackend

    def _boom(self, *a, **k):
        raise ConnectionError("no route to host")

    monkeypatch.setattr(huggingface_hub.HfApi, "model_info", _boom)
    with pytest.raises(ConnectionError):
        DiffusionBackend._prequant_source_hub_entry(_nvfp4_repo_source(), None, [], scheme = "nvfp4")


def _prefetch_backend(monkeypatch, *, cached, model_info):
    """A backend whose dense-quant candidate is the hosted NVFP4 prequant, with the Hub answering
    ``model_info``. Explicit nvfp4, so the auto-only cache gates do not decide it first."""
    import types

    import huggingface_hub

    from core.inference import diffusion as dmod
    from core.inference import diffusion_memory as dmem
    from core.inference.diffusion import DiffusionBackend

    tokens: list = []

    class _Api:
        def __init__(
            self,
            token = None,
            **k,
        ):
            tokens.append(token)

        def model_info(self, repo_id, **k):
            return model_info(repo_id)

    monkeypatch.setattr(huggingface_hub, "HfApi", _Api)
    monkeypatch.setattr(
        dmod,
        "resolve_dense_quant_candidate",
        lambda **kw: types.SimpleNamespace(prequant = True, scheme = "nvfp4", steady_total_mib = 1),
    )
    monkeypatch.setattr(
        dmod, "usable_prequant_source", lambda fam, scheme, **kw: _nvfp4_repo_source()
    )
    monkeypatch.setattr(dmod, "prequant_checkpoint_cached", lambda source, **kw: cached)
    monkeypatch.setattr(
        dmem,
        "snapshot_device_memory",
        lambda target: types.SimpleNamespace(total_mib = None, memory_kind = "discrete_vram"),
    )
    monkeypatch.setattr(
        pq, "restricted_prequant_load_supported", lambda scheme = None, filename = None: True
    )
    backend = DiffusionBackend()
    monkeypatch.setattr(backend, "_target_for_ordinal", lambda fam, ordinal: object())
    return backend, tokens


_NVFP4_PREFETCH_KWARGS = {"transformer_quant": "nvfp4", "hf_token": "hf_user_token"}


def test_an_unreachable_prequant_does_not_suppress_the_dense_shards(monkeypatch):
    """PREQUANT is chosen from the family table even when this user cannot read it, so the dense
    shards must still be staged, not pulled ~25 GB inline."""
    from huggingface_hub import errors as hub_errors

    def _refuse(repo_id):
        raise _refused(hub_errors.RepositoryNotFoundError, 401)

    backend, tokens = _prefetch_backend(monkeypatch, cached = False, model_info = _refuse)
    fam = _fam()
    assert backend._dense_quant_prefetch_needed(fam, dict(_NVFP4_PREFETCH_KWARGS)) is True
    assert tokens == [
        "hf_user_token"
    ], "the probe must ask as the user, else a granted token reads as refused"


def test_an_unreachable_prequant_is_carried_into_the_load(monkeypatch):
    """begin_load hands these kwargs to load_pipeline, so the load sizes the scheme as the dense build
    it will fall back to rather than as a checkpoint that will never arrive."""
    from huggingface_hub import errors as hub_errors

    def _refuse(repo_id):
        raise _refused(hub_errors.RepositoryNotFoundError, 401)

    backend, _tokens = _prefetch_backend(monkeypatch, cached = False, model_info = _refuse)
    kwargs = dict(_NVFP4_PREFETCH_KWARGS)
    assert backend._dense_quant_prefetch_needed(_fam(), kwargs) is True
    assert kwargs["_prequant_unreachable"] == ("nvfp4",)
    backend._dense_quant_prefetch_needed(_fam(), kwargs)
    assert kwargs["_prequant_unreachable"] == ("nvfp4",)


def test_a_readable_prequant_is_not_marked_unreachable(monkeypatch):
    import types

    def _listing(repo_id):
        return types.SimpleNamespace(
            siblings = [types.SimpleNamespace(rfilename = "Z-Image-Turbo-NVFP4.safetensors", size = 4096)]
        )

    backend, _tokens = _prefetch_backend(monkeypatch, cached = False, model_info = _listing)
    kwargs = dict(_NVFP4_PREFETCH_KWARGS)
    assert backend._dense_quant_prefetch_needed(_fam(), kwargs) is False
    assert "_prequant_unreachable" not in kwargs


def test_local_only_treats_an_uncached_prequant_as_unreachable(monkeypatch):
    """local_files_only forbids the loader from fetching the checkpoint, so a Hub listing that
    names it must not keep the load sizing a packed artifact that will never arrive."""
    import types

    def _listing(repo_id):
        return types.SimpleNamespace(
            siblings = [types.SimpleNamespace(rfilename = "Z-Image-Turbo-NVFP4.safetensors", size = 4096)]
        )

    backend, tokens = _prefetch_backend(monkeypatch, cached = False, model_info = _listing)
    kwargs = {**_NVFP4_PREFETCH_KWARGS, "local_files_only": True}
    assert backend._dense_quant_prefetch_needed(_fam(), kwargs) is True
    assert kwargs["_prequant_unreachable"] == ("nvfp4",)
    assert tokens == [], "local-only mode must not ask the Hub"
    backend, _tokens = _prefetch_backend(monkeypatch, cached = True, model_info = _listing)
    kwargs = {**_NVFP4_PREFETCH_KWARGS, "local_files_only": True}
    assert backend._dense_quant_prefetch_needed(_fam(), kwargs) is False
    assert "_prequant_unreachable" not in kwargs


def test_a_readable_prequant_still_drops_the_dense_shards(monkeypatch):
    """Positive control: a repo that lists the checkpoint keeps the small download."""
    import types

    def _listing(repo_id):
        return types.SimpleNamespace(
            siblings = [types.SimpleNamespace(rfilename = "Z-Image-Turbo-NVFP4.safetensors", size = 4096)]
        )

    backend, _tokens = _prefetch_backend(monkeypatch, cached = False, model_info = _listing)
    assert backend._dense_quant_prefetch_needed(_fam(), dict(_NVFP4_PREFETCH_KWARGS)) is False


def test_a_cached_prequant_drops_the_dense_shards_without_asking_the_hub(monkeypatch):
    def _no_hub(repo_id):
        raise AssertionError("a cached checkpoint must not cost a Hub round trip")

    backend, tokens = _prefetch_backend(monkeypatch, cached = True, model_info = _no_hub)
    assert backend._dense_quant_prefetch_needed(_fam(), dict(_NVFP4_PREFETCH_KWARGS)) is False
    assert tokens == []


def test_an_unanswerable_reachability_probe_keeps_the_prequant_verdict(monkeypatch):
    """Offline or a Hub hiccup says nothing about access, so it must not widen a multi-GB pull."""

    def _offline(repo_id):
        raise ConnectionError("offline")

    backend, _tokens = _prefetch_backend(monkeypatch, cached = False, model_info = _offline)
    assert backend._dense_quant_prefetch_needed(_fam(), dict(_NVFP4_PREFETCH_KWARGS)) is False


def test_the_download_plan_probes_with_the_user_token():
    """download_plan builds its own kwargs for the prefetch decision; without the token threaded in,
    a user granted access to a private prequant reads as refused and stages the dense shards."""
    import inspect

    from core.inference.diffusion import DiffusionBackend

    src = inspect.getsource(DiffusionBackend.download_plan)
    assert '"base_repo": base,' in src and '"hf_token": hf_token,' in src


def test_a_full_fingerprint_pass_is_remembered_per_unchanged_file(monkeypatch, tmp_path):
    import os

    import core.inference.diffusion_compile_cache as cc
    import core.inference.diffusion_prequant as pq

    monkeypatch.setenv(cc._ENV_DIR, str(tmp_path / "cache"))
    monkeypatch.delenv(pq.FINGERPRINT_MODE_ENV, raising = False)
    ckpt_file = tmp_path / "w.safetensors"
    ckpt_file.write_bytes(b"weights")
    expected = {"a.weight": "x", "b.weight": "y"}
    meta = {"fingerprint": {"modules": expected}}
    calls: list = []

    def fingerprint(state_dict, *, select = None):
        calls.append(select)
        return {"modules": dict(state_dict)}

    monkeypatch.setattr(pq, "packed_weight_fingerprint", fingerprint)
    assert pq._verify_packed_fingerprint(expected, meta, path = ckpt_file)
    assert pq._verify_packed_fingerprint(expected, meta, path = ckpt_file)
    assert len(calls) == 1
    ckpt_file.write_bytes(b"weights, rebuilt")
    os.utime(ckpt_file, ns = (1, 1))
    assert not pq._verify_packed_fingerprint(
        {"a.weight": "x", "b.weight": "z"}, meta, path = ckpt_file
    )
    assert not pq._verify_packed_fingerprint(
        {"a.weight": "x", "b.weight": "z"}, meta, path = ckpt_file
    )
    assert len(calls) == 3
    assert pq._verify_packed_fingerprint(expected, meta)
    assert pq._verify_packed_fingerprint(expected, meta)
    assert len(calls) == 5


# ---- ComfyUI-format twins in the hosted chain ----


def _own_names(names):
    from core.inference.diffusion_prequant import is_comfy_prequant_filename
    return tuple(n for n in names if not is_comfy_prequant_filename(n))


@pytest.mark.parametrize(
    "repo, family, scheme, env, own",
    [
        ("Tongyi-MAI/Z-Image-Turbo", None, "int8", {}, "Z-Image-Turbo-INT8-ConvRot.safetensors"),
        ("Tongyi-MAI/Z-Image-Turbo", None, "fp8", {}, "Z-Image-Turbo-FP8.safetensors"),
        (
            "Qwen/Qwen-Image-2.1",
            "qwen-image-2.1",
            "int8",
            {"UNSLOTH_DIFFUSION_INT8_CONVROT": "1"},
            "Qwen-Image-2.1-INT8-ConvRot.safetensors",
        ),
        (
            "Qwen/Qwen-Image-2.1",
            "qwen-image-2.1",
            "int8",
            {},
            "Qwen-Image-2.1-INT8-ConvRot.safetensors",
        ),
        (
            "Qwen/Qwen-Image-2.1",
            "qwen-image-2.1",
            "int8",
            {"UNSLOTH_DIFFUSION_INT8_CONVROT": "0"},
            "Qwen-Image-2.1-INT8.safetensors",
        ),
        ("Qwen/Qwen-Image-2.1", "qwen-image-2.1", "fp8", {}, "Qwen-Image-2.1-FP8.safetensors"),
        ("black-forest-labs/FLUX.2-klein-4B", None, "fp8", {}, "FLUX.2-klein-4B-FP8.safetensors"),
    ],
)
def test_image_families_resolve_the_comfy_twin_and_keep_every_old_name(
    monkeypatch, repo, family, scheme, env, own
):
    """New builds also ask for ``<stem>-ComfyUI.safetensors``: AHEAD of the artifact for int8 (the twin holds the
    same codes and scales), BEHIND it for fp8 (ComfyUI's per-tensor fp8 is a coarser rounding). Older builds never
    ask for it, and the chain without it is exactly what the kill switch (and an older build) resolves."""
    from core.inference.diffusion_families import detect_family
    from core.inference.diffusion_prequant import COMFY_PREQUANT_ENV, comfy_prequant_filename

    for k, v in env.items():
        monkeypatch.setenv(k, v)
    fam = detect_family(repo, override = family) if family else detect_family(repo)
    names = resolve_prequant_source(fam, scheme).candidate_filenames
    twin = comfy_prequant_filename(own)
    monkeypatch.setenv(COMFY_PREQUANT_ENV, "0")
    old = resolve_prequant_source(fam, scheme).candidate_filenames
    assert _own_names(names) == old
    assert old[0] == own
    if scheme == "int8":
        assert names[0] == twin
        # every artifact gets its twin right ahead of its first container
        for name in old:
            other = comfy_prequant_filename(name)
            if other is not None and not name.endswith(".pt"):
                assert names.index(other) == names.index(name) - 1
    else:
        stems = [n for n in names if n.startswith(own[: -len(".safetensors")] + ".")]
        assert names.index(twin) == names.index(stems[-1]) + 1


def test_comfy_twin_names():
    from core.inference.diffusion_prequant import (
        comfy_prequant_filename,
        is_comfy_prequant_filename,
        with_comfy_twins,
    )

    assert (
        comfy_prequant_filename("Z-Image-Turbo-FP8.safetensors")
        == "Z-Image-Turbo-FP8-ComfyUI.safetensors"
    )
    assert (
        comfy_prequant_filename("Z-Image-Turbo-INT8.pt") == "Z-Image-Turbo-INT8-ComfyUI.safetensors"
    )
    # the legacy names, nested paths and the twin itself have none
    assert comfy_prequant_filename("transformer_int8.pt") is None
    assert comfy_prequant_filename("text_encoders/x.safetensors") is None
    assert comfy_prequant_filename("A-FP8-ComfyUI.safetensors") is None
    assert is_comfy_prequant_filename("A-FP8-ComfyUI.safetensors")
    assert not is_comfy_prequant_filename("A-FP8.safetensors")
    assert with_comfy_twins(["A-INT8.safetensors", "A-INT8.pt", "transformer_int8.pt"]) == [
        "A-INT8-ComfyUI.safetensors",
        "A-INT8.safetensors",
        "A-INT8.pt",
        "transformer_int8.pt",
    ]
    assert with_comfy_twins(
        ["A-FP8.safetensors", "A-FP8.pt", "transformer_fp8.pt"], lead = False
    ) == [
        "A-FP8.safetensors",
        "A-FP8.pt",
        "A-FP8-ComfyUI.safetensors",
        "transformer_fp8.pt",
    ]
    # a pickle-only chain still gets the twin ahead of it; a declared twin is not duplicated
    assert with_comfy_twins(["A-INT8.pt"]) == ["A-INT8-ComfyUI.safetensors", "A-INT8.pt"]
    assert with_comfy_twins(["A-INT8-ComfyUI.safetensors", "A-INT8.safetensors"]) == [
        "A-INT8-ComfyUI.safetensors",
        "A-INT8.safetensors",
    ]


def test_video_families_get_no_comfy_twin():
    """Only the image denoiser loader reads the ComfyUI layout; video chains are unchanged."""
    from core.inference.diffusion_prequant import is_comfy_prequant_filename
    from core.inference.video_families import _FAMILIES as VIDEO_FAMILIES

    checked = 0
    for fam in VIDEO_FAMILIES:
        for scheme, _repo in getattr(fam, "prequant_repos", ()) or ():
            src = resolve_prequant_source(fam, scheme)
            if src is None:
                continue
            checked += 1
            assert not any(is_comfy_prequant_filename(n) for n in src.candidate_filenames)
    assert checked


def test_task_specific_artifacts_get_no_twin():
    fam = dataclasses.replace(
        _fam(prequant_repos = (("int8", "unsloth/Model-FP8"),)),
        prequant_filenames = (("int8", "keyframe", "Model-KF-INT8.safetensors"),),
    )
    src = resolve_prequant_source(fam, "int8", task = "keyframe")
    assert src.candidate_filenames == ("Model-KF-INT8.safetensors",)


def _qwen_int8_ckpt():
    from core.inference.diffusion_transformer_quant import exclude_tokens_for_scheme

    ckpt = _good_ckpt(scheme = "int8")
    ckpt["metadata"].update(
        {
            "family": "qwen-image",
            "exclude_name_tokens": list(
                exclude_tokens_for_scheme("int8", "qwen-image", baked = True)
            ),
            "min_features": 512,
        }
    )
    return ckpt


def test_load_tops_up_the_dense_text_stream_of_a_baked_artifact(monkeypatch, tmp_path):
    import core.inference.diffusion_transformer_quant as tq

    seen = []
    monkeypatch.setattr(
        tq,
        "quantize_runtime_leftovers",
        lambda transformer, scheme, family, baked, **kw: seen.append(
            (scheme, family, list(baked), kw)
        )
        or 0,
    )
    ckpt = _qwen_int8_ckpt()
    t = _load(monkeypatch, tmp_path, ckpt, scheme = "int8")
    assert t is not None
    assert len(seen) == 1
    scheme, family, baked, kw = seen[0]
    assert (scheme, family) == ("int8", "qwen-image")
    assert baked == ckpt["metadata"]["exclude_name_tokens"]
    assert kw["min_features"] == 512 and kw["device"] == "cuda"


def test_load_survives_a_failed_top_up(monkeypatch, tmp_path):
    import core.inference.diffusion_transformer_quant as tq

    def boom(*a, **k):
        raise RuntimeError("no torchao")

    monkeypatch.setattr(tq, "quantize_runtime_leftovers", boom)
    assert _load(monkeypatch, tmp_path, _qwen_int8_ckpt(), scheme = "int8") is not None


def test_kill_switch_refuses_an_artifact_built_with_the_int8_text_stream(monkeypatch, tmp_path):
    from core.inference.diffusion_transformer_quant import (
        INT8_TEXT_STREAM_ENV,
        exclude_tokens_for_scheme,
    )

    ckpt = _qwen_int8_ckpt()
    from core.inference.diffusion_transformer_quant import int8_text_stream_scope

    with int8_text_stream_scope(True):
        ckpt["metadata"]["exclude_name_tokens"] = list(
            exclude_tokens_for_scheme("int8", "qwen-image")
        )
        assert _load(monkeypatch, tmp_path, ckpt, scheme = "int8") is not None
    assert _load(monkeypatch, tmp_path, ckpt, scheme = "int8") is None
    monkeypatch.setenv(INT8_TEXT_STREAM_ENV, "0")
    with int8_text_stream_scope(True):
        assert _load(monkeypatch, tmp_path, ckpt, scheme = "int8") is None