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.

58.7 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

"""FLUX.2 GGUF inner_dim must be checked from a range-read header, before any base download."""

from __future__ import annotations

import inspect
import re
import threading
import time
import types

import pytest

from core.inference import diffusion_compat
from core.inference.diffusion import DiffusionBackend, _LoadingState
from core.inference.diffusion_families import (
    detect_family,
    gguf_flux2_inner_dim_from_header,
    sd_cpp_text_encoders_for,
)

KLEIN_4B_BASE = "black-forest-labs/FLUX.2-klein-4B"
KLEIN_9B_BASE = "black-forest-labs/FLUX.2-klein-9B"
KLEIN_4B_GGUF = "unsloth/FLUX.2-klein-4B-GGUF"
KLEIN_4B_FILE = "flux-2-klein-4b-Q4_K_M.gguf"

FLUX2_FAMILY = types.SimpleNamespace(name = "flux.2-klein", single_file_is_pipeline = False)


def _gguf_header(
    inner_dim: int,
    tmp_path,
    *,
    name = "double_stream_modulation_img.lin.weight",
    siblings = 4,
    probe_last = False,
):
    """Real GGUF header with no tensor data, from the shipped writer, as a range request would return."""
    import numpy as np
    from gguf import GGMLQuantizationType, GGUFWriter

    path = tmp_path / f"header-{inner_dim}-{siblings}-{int(probe_last)}.gguf"
    writer = GGUFWriter(str(path), "flux")

    def _probe():
        # FLUX.2 sizes this projection as (6 * inner_dim, inner_dim); GGUF stores dims reversed.
        writer.add_tensor_info(
            name,
            [6 * inner_dim, inner_dim],
            np.dtype(np.float16),
            6 * inner_dim * inner_dim * 2,
            raw_dtype = GGMLQuantizationType.F16,
        )

    if not probe_last:
        _probe()
    for i in range(siblings):
        writer.add_tensor_info(
            f"blk.{i}.weight",
            [64, 64],
            np.dtype(np.float16),
            64 * 64 * 2,
            raw_dtype = GGMLQuantizationType.F16,
        )
    if probe_last:
        _probe()
    writer.write_header_to_file()
    writer.write_kv_data_to_file()
    writer.write_ti_data_to_file()
    writer.close()
    return path.read_bytes()


class _FakeResponse:
    """The slice of ``requests.Response`` the header read uses."""

    def __init__(
        self,
        status_code,
        body = b"",
    ):
        self.status_code = status_code
        self._body = body

    def iter_content(self, chunk_size = 1):
        for i in range(0, len(self._body), chunk_size):
            yield self._body[i : i + chunk_size]

    def __enter__(self):
        return self

    def __exit__(self, *_exc):
        return False


def _stub_range_reads(
    monkeypatch,
    bodies,
    *,
    status = 206,
):
    """Serves header bytes over a stubbed Hub session; any hf_hub_download call fails the test."""
    requests: list[tuple[str, str]] = []

    class _Session:
        def get(
            self,
            url,
            headers = None,
            timeout = None,
            stream = False,
        ):
            requests.append((url, (headers or {}).get("Range", "")))
            body = next((b for name, b in bodies.items() if url.endswith(name)), None)
            if body is None:
                return _FakeResponse(404)
            return _FakeResponse(status, body)

    monkeypatch.setattr("huggingface_hub.utils.get_session", lambda: _Session())
    monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", lambda *a, **k: None)
    monkeypatch.setattr(
        "huggingface_hub.hf_hub_download",
        lambda *a, **k: pytest.fail("the compatibility preflight must not download the file"),
    )
    diffusion_compat._reset_inner_dim_cache()
    return requests


@pytest.fixture(autouse = True)
def _clean_probe_cache():
    # The memo is process-global by design; a leak between tests would hide a missing probe.
    diffusion_compat._reset_inner_dim_cache()
    yield
    diffusion_compat._reset_inner_dim_cache()


@pytest.mark.parametrize("inner_dim", [3072, 4096, 6144])
def test_the_inner_dim_is_read_from_a_header_with_no_tensor_data(inner_dim, tmp_path):
    assert gguf_flux2_inner_dim_from_header(_gguf_header(inner_dim, tmp_path)) == inner_dim


def test_a_plain_reader_cannot_read_the_same_prefix(tmp_path):
    # GGUFReader also builds numpy views over tensor DATA, so it raises on a header prefix.
    from gguf import GGUFReader
    from core.inference.diffusion_families import gguf_flux2_inner_dim

    prefix = tmp_path / "prefix-only.gguf"
    prefix.write_bytes(_gguf_header(3072, tmp_path))

    with pytest.raises(Exception):
        GGUFReader(str(prefix))
    assert gguf_flux2_inner_dim(prefix) is None
    assert gguf_flux2_inner_dim_from_header(prefix.read_bytes()) == 3072


@pytest.mark.parametrize(
    "header",
    [b"", b"not a gguf at all", b"GGUF" + b"\x00" * 64],
    ids = ["empty", "garbage", "truncated"],
)
def test_an_unreadable_header_yields_no_opinion(header):
    assert gguf_flux2_inner_dim_from_header(header) is None


def test_a_header_without_the_probe_tensor_yields_no_opinion(tmp_path):
    header = _gguf_header(3072, tmp_path, name = "blk.0.attn.weight")
    assert gguf_flux2_inner_dim_from_header(header) is None


@pytest.mark.parametrize("probe_last", [False, True], ids = ["probe-first", "probe-last"])
def test_no_truncation_of_a_valid_header_can_invent_a_dim(probe_last, tmp_path):
    # Every prefix of a real header must read as the real dim or as nothing, never inner_dim 0.
    header = _gguf_header(4096, tmp_path, probe_last = probe_last)
    assert gguf_flux2_inner_dim_from_header(header) == 4096

    verdicts = {gguf_flux2_inner_dim_from_header(header[:cut]) for cut in range(1, len(header))}
    assert verdicts <= {None, 4096}, f"a truncated header invented {verdicts - {None, 4096}}"


def test_a_header_declaring_a_huge_checkpoint_is_cheap(tmp_path):
    # Satisfying data views from a prefix would allocate the full declared size (~37 GiB here).
    import time

    header = _gguf_header(4096, tmp_path, siblings = 1200)
    started = time.monotonic()
    assert gguf_flux2_inner_dim_from_header(header) == 4096
    assert time.monotonic() - started < 5.0


def test_a_mismatched_pair_is_refused_from_the_header_alone(monkeypatch, tmp_path):
    requests = _stub_range_reads(monkeypatch, {KLEIN_4B_FILE: _gguf_header(3072, tmp_path)})

    with pytest.raises(ValueError) as excinfo:
        diffusion_compat.assert_flux2_pick_compatible(
            FLUX2_FAMILY, KLEIN_4B_GGUF, KLEIN_4B_FILE, KLEIN_9B_BASE
        )

    detail = str(excinfo.value)
    assert KLEIN_4B_FILE in detail and KLEIN_9B_BASE in detail
    assert "klein-4B" in detail and "klein-9B" in detail
    assert len(requests) == 1
    url, byte_range = requests[0]
    assert url.endswith(f"{KLEIN_4B_GGUF}/resolve/main/{KLEIN_4B_FILE}")
    assert byte_range == f"bytes=0-{diffusion_compat._GGUF_HEADER_BYTES - 1}"


def test_a_matching_pair_passes(monkeypatch, tmp_path):
    _stub_range_reads(monkeypatch, {KLEIN_4B_FILE: _gguf_header(3072, tmp_path)})

    assert (
        diffusion_compat.flux2_pick_mismatch(
            FLUX2_FAMILY, KLEIN_4B_GGUF, KLEIN_4B_FILE, KLEIN_4B_BASE
        )
        is None
    )


def test_an_unreadable_header_fails_open(monkeypatch):
    _stub_range_reads(monkeypatch, {KLEIN_4B_FILE: b"not a gguf"})

    assert (
        diffusion_compat.flux2_pick_mismatch(
            FLUX2_FAMILY, KLEIN_4B_GGUF, KLEIN_4B_FILE, KLEIN_9B_BASE
        )
        is None
    )


def test_an_offline_host_fails_open(monkeypatch):
    def _boom(*_a, **_k):
        raise OSError("no route to host")

    monkeypatch.setattr(
        "huggingface_hub.utils.get_session", lambda: types.SimpleNamespace(get = _boom)
    )
    monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", lambda *a, **k: None)

    assert (
        diffusion_compat.flux2_pick_mismatch(
            FLUX2_FAMILY, KLEIN_4B_GGUF, KLEIN_4B_FILE, KLEIN_9B_BASE
        )
        is None
    )


def test_a_trickling_server_cannot_hold_the_picker_open(monkeypatch):
    # Per-read timeout: a trickling server never times out; only half-close ends iter_content.
    interrupted = threading.Event()

    class _Trickle:
        status_code = 206

        def __init__(self):
            self.raw = types.SimpleNamespace(shutdown = interrupted.set)

        def iter_content(self, chunk_size = 1):
            if not interrupted.wait(10):
                raise AssertionError("the header read was never interrupted")
            raise OSError("Connection broken: IncompleteRead(12 bytes read)")

        def close(self):
            pass

        def __enter__(self):
            return self

        def __exit__(self, *_exc):
            return False

    monkeypatch.setattr(diffusion_compat, "_HEADER_TIMEOUT_SECONDS", 0.5)
    monkeypatch.setattr(
        "huggingface_hub.utils.get_session",
        lambda: types.SimpleNamespace(get = lambda *a, **k: _Trickle()),
    )
    monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", lambda *a, **k: None)

    out: list[bytes] = []
    reader = threading.Thread(
        target = lambda: out.append(
            diffusion_compat._read_gguf_header(KLEIN_4B_GGUF, KLEIN_4B_FILE, None)
        ),
        daemon = True,
    )
    reader.start()
    reader.join(8)

    assert not reader.is_alive(), "the header read outlived its own deadline"
    assert out == [b""]


def test_an_old_urllib3_with_no_shutdown_still_cannot_hold_the_picker_open(monkeypatch):
    # urllib3 below 2.3.0 lacks HTTPResponse.shutdown, so the worker thread is abandoned.
    still_reading = threading.Event()

    class _Unwakeable:
        status_code = 206
        raw = None

        def iter_content(self, chunk_size = 1):
            still_reading.set()
            time.sleep(30)
            yield b"never arrives"

        def close(self):
            pass

        def __enter__(self):
            return self

        def __exit__(self, *_exc):
            return False

    monkeypatch.setattr(diffusion_compat, "_HEADER_TIMEOUT_SECONDS", 0.5)
    monkeypatch.setattr(
        "huggingface_hub.utils.get_session",
        lambda: types.SimpleNamespace(get = lambda *a, **k: _Unwakeable()),
    )
    monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", lambda *a, **k: None)

    started = time.monotonic()
    assert diffusion_compat._read_gguf_header(KLEIN_4B_GGUF, KLEIN_4B_FILE, None) == b""
    elapsed = time.monotonic() - started

    assert still_reading.is_set(), "the fixture never got as far as blocking"
    # Deadline plus abandon grace, with room for a loaded CI box.
    assert elapsed < 5, f"the picker waited {elapsed:.1f}s on a read it cannot interrupt"


def test_a_server_that_ignores_the_range_header_is_abandoned(monkeypatch, tmp_path):
    # A 200 means the whole checkpoint is on the wire, so the body is dropped unread (fail open).
    body_reads: list[int] = []

    class _WholeFile(_FakeResponse):
        def iter_content(self, chunk_size = 1):
            body_reads.append(chunk_size)
            yield b""

    class _Session:
        def get(
            self,
            url,
            headers = None,
            timeout = None,
            stream = False,
        ):
            return _WholeFile(200, _gguf_header(3072, tmp_path))

    monkeypatch.setattr("huggingface_hub.utils.get_session", lambda: _Session())
    monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", lambda *a, **k: None)

    assert (
        diffusion_compat.flux2_pick_mismatch(
            FLUX2_FAMILY, KLEIN_4B_GGUF, KLEIN_4B_FILE, KLEIN_9B_BASE
        )
        is None
    )
    assert body_reads == []


@pytest.mark.parametrize(
    "base",
    ["someone/a-base-we-do-not-ship", "/models/my-local-flux2"],
    ids = ["unknown-repo", "local-path"],
)
def test_a_base_outside_the_size_table_costs_no_request_at_all(base, monkeypatch, tmp_path):
    requests = _stub_range_reads(monkeypatch, {KLEIN_4B_FILE: _gguf_header(3072, tmp_path)})

    assert (
        diffusion_compat.flux2_pick_mismatch(FLUX2_FAMILY, KLEIN_4B_GGUF, KLEIN_4B_FILE, base)
        is None
    )
    assert requests == []


def test_a_known_ungated_mirror_is_checked_like_its_upstream(monkeypatch, tmp_path):
    _stub_range_reads(monkeypatch, {KLEIN_4B_FILE: _gguf_header(3072, tmp_path)})
    from core.inference.diffusion_families import canonical_base

    mirror = "unsloth/FLUX.2-klein-9B"
    assert canonical_base(mirror).lower() == KLEIN_9B_BASE.lower(), "mirror table changed"

    reason = diffusion_compat.flux2_pick_mismatch(
        FLUX2_FAMILY, KLEIN_4B_GGUF, KLEIN_4B_FILE, mirror
    )

    assert reason is not None and mirror in reason


def test_a_non_flux2_family_costs_no_request_at_all(monkeypatch, tmp_path):
    requests = _stub_range_reads(monkeypatch, {"z.gguf": _gguf_header(3072, tmp_path)})

    assert (
        diffusion_compat.flux2_pick_mismatch(
            types.SimpleNamespace(name = "z-image"),
            "unsloth/Z-Image-Turbo-GGUF",
            "z.gguf",
            KLEIN_9B_BASE,
        )
        is None
    )
    assert requests == []


def test_a_non_gguf_single_file_costs_no_request_at_all(monkeypatch, tmp_path):
    requests = _stub_range_reads(monkeypatch, {"model.safetensors": _gguf_header(3072, tmp_path)})

    assert (
        diffusion_compat.flux2_pick_mismatch(
            FLUX2_FAMILY, KLEIN_4B_GGUF, "model.safetensors", KLEIN_9B_BASE
        )
        is None
    )
    assert requests == []


def test_pasting_a_token_re_probes_a_pick_that_missed_anonymously(monkeypatch, tmp_path):
    # The memo keeps a miss, but a token paste must re-probe or a gated GGUF stays unguarded.
    bodies: dict[str, bytes] = {}
    requests = _stub_range_reads(monkeypatch, bodies)

    assert (
        diffusion_compat.flux2_pick_mismatch(
            FLUX2_FAMILY, KLEIN_4B_GGUF, KLEIN_4B_FILE, KLEIN_9B_BASE
        )
        is None
    )
    assert len(requests) == 1
    diffusion_compat.flux2_pick_mismatch(FLUX2_FAMILY, KLEIN_4B_GGUF, KLEIN_4B_FILE, KLEIN_9B_BASE)
    assert len(requests) == 1

    bodies[KLEIN_4B_FILE] = _gguf_header(3072, tmp_path)
    reason = diffusion_compat.flux2_pick_mismatch(
        FLUX2_FAMILY, KLEIN_4B_GGUF, KLEIN_4B_FILE, KLEIN_9B_BASE, "hf_token_value"
    )

    assert len(requests) == 2
    assert reason is not None and KLEIN_9B_BASE in reason


def test_the_header_probe_is_memoised_across_the_three_checks(monkeypatch, tmp_path):
    requests = _stub_range_reads(monkeypatch, {KLEIN_4B_FILE: _gguf_header(3072, tmp_path)})

    for _ in range(3):
        with pytest.raises(ValueError):
            diffusion_compat.assert_flux2_pick_compatible(
                FLUX2_FAMILY, KLEIN_4B_GGUF, KLEIN_4B_FILE, KLEIN_9B_BASE
            )

    assert len(requests) == 1


def test_a_remembered_hub_failure_does_not_outlive_the_download(monkeypatch, tmp_path):
    # A memoised negative must not shadow a local file that appeared after the download.
    requests = _stub_range_reads(monkeypatch, {})

    assert diffusion_compat.flux2_inner_dim_for_pick(KLEIN_4B_GGUF, KLEIN_4B_FILE) is None
    assert len(requests) == 1

    staged = tmp_path / "blobs" / KLEIN_4B_FILE
    staged.parent.mkdir(parents = True, exist_ok = True)
    staged.write_bytes(_gguf_header(4096, tmp_path))
    monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", lambda *a, **k: str(staged))

    assert diffusion_compat.flux2_inner_dim_for_pick(KLEIN_4B_GGUF, KLEIN_4B_FILE) == 4096
    assert len(requests) == 1


def test_a_remembered_hub_failure_still_suppresses_a_re_probe_while_nothing_is_on_disk(
    monkeypatch, tmp_path
):
    requests = _stub_range_reads(monkeypatch, {})

    for _ in range(3):
        assert diffusion_compat.flux2_inner_dim_for_pick(KLEIN_4B_GGUF, KLEIN_4B_FILE) is None

    assert len(requests) == 1


def test_a_checkpoint_swapped_in_place_is_read_again(monkeypatch, tmp_path):
    """Same directory and filename, different checkpoint: keying the memo on the name alone answers
    the new file with the old dim, refusing a valid 9B pairing until restart."""
    local = tmp_path / "on-device"
    local.mkdir()
    target = local / KLEIN_4B_FILE
    target.write_bytes(_gguf_header(3072, tmp_path))
    _stub_range_reads(monkeypatch, {})

    assert diffusion_compat.flux2_inner_dim_for_pick(str(local), KLEIN_4B_FILE) == 3072

    # Headers differ in length too: os.stat resolution can tie a same-size overwrite.
    target.write_bytes(_gguf_header(4096, tmp_path, siblings = 9))

    assert (
        diffusion_compat.flux2_inner_dim_for_pick(str(local), KLEIN_4B_FILE) == 4096
    ), "the memo answered for the file that used to be at this path"


def test_a_bad_token_does_not_poison_the_good_one_that_replaces_it(monkeypatch, tmp_path):
    """Keying on the token's mere PRESENCE made every non-empty credential one key. A first probe
    with an expired token cached its miss there, and pasting a working token afterwards inherited
    it for the rest of the process -- the preflight silently off for that pick."""
    served: dict[str, bytes] = {}
    requests: list[tuple[str, str]] = []

    class _GatedSession:
        def get(
            self,
            url,
            headers = None,
            timeout = None,
            stream = False,
        ):
            token = (headers or {}).get("authorization", "")
            requests.append((url, token))
            if "good" not in token:
                return _FakeResponse(401)
            return _FakeResponse(206, served[KLEIN_4B_FILE])

    served[KLEIN_4B_FILE] = _gguf_header(4096, tmp_path)
    monkeypatch.setattr("huggingface_hub.utils.get_session", lambda: _GatedSession())
    monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", lambda *a, **k: None)
    diffusion_compat._reset_inner_dim_cache()

    assert (
        diffusion_compat.flux2_inner_dim_for_pick(KLEIN_4B_GGUF, KLEIN_4B_FILE, "expired") is None
    )
    assert diffusion_compat.flux2_inner_dim_for_pick(KLEIN_4B_GGUF, KLEIN_4B_FILE, "good") == 4096
    before = len(requests)
    assert diffusion_compat.flux2_inner_dim_for_pick(KLEIN_4B_GGUF, KLEIN_4B_FILE, "good") == 4096
    assert len(requests) == before


def test_the_memo_never_holds_the_token_itself():
    """It is a process-global dict; a traceback or a heap dump renders it."""
    diffusion_compat._reset_inner_dim_cache()
    secret = "hf_averyrealsecrettoken"
    assert secret not in diffusion_compat._token_fingerprint(secret)
    assert diffusion_compat._token_fingerprint(None) == ""
    assert diffusion_compat._token_fingerprint("a") != diffusion_compat._token_fingerprint("b")


def test_a_gguf_already_on_disk_is_read_instead_of_fetched(monkeypatch, tmp_path):
    local = tmp_path / "local-repo"
    local.mkdir()
    (local / KLEIN_4B_FILE).write_bytes(_gguf_header(4096, tmp_path))
    requests = _stub_range_reads(monkeypatch, {})

    reason = diffusion_compat.flux2_pick_mismatch(
        FLUX2_FAMILY, str(local), KLEIN_4B_FILE, KLEIN_4B_BASE
    )

    assert reason is not None and "klein-9B" in reason
    assert requests == []


def test_a_local_header_past_the_prefix_cap_falls_back_to_the_full_reader(monkeypatch, tmp_path):
    import numpy as np
    from gguf import GGUFWriter
    from core.inference.diffusion_families import gguf_flux2_inner_dim_from_header

    local = tmp_path / "big-header-repo"
    local.mkdir()
    path = local / "wide.gguf"
    writer = GGUFWriter(str(path), "flux")
    writer.add_tensor(
        "double_stream_modulation_img.lin.weight", np.zeros((48, 8), dtype = np.float16)
    )
    for i in range(1200):
        writer.add_tensor(f"blk.{i}.{'x' * 220}.weight", np.zeros((8, 8), dtype = np.float16))
    writer.write_header_to_file()
    writer.write_kv_data_to_file()
    writer.write_tensors_to_file()
    writer.close()

    prefix = path.read_bytes()[: diffusion_compat._GGUF_HEADER_BYTES]
    assert gguf_flux2_inner_dim_from_header(prefix) is None, "fixture must overflow the cap"
    _stub_range_reads(monkeypatch, {})

    assert diffusion_compat.flux2_inner_dim_for_pick(str(local), "wide.gguf") == 8


def test_the_download_plan_reports_the_mismatch_instead_of_raising(monkeypatch, tmp_path):
    # Reported, not raised: the images page falls back to /images/load on any plan failure.
    _stub_range_reads(monkeypatch, {KLEIN_4B_FILE: _gguf_header(3072, tmp_path)})
    monkeypatch.setattr(
        "core.inference.diffusion._resolve_base_repo", lambda *a, **k: KLEIN_9B_BASE
    )
    monkeypatch.setattr(
        DiffusionBackend, "_te_prequant_plan_files", staticmethod(lambda *a, **k: {})
    )
    monkeypatch.setattr(
        DiffusionBackend, "_estimate_download_bytes", staticmethod(lambda *a, **k: (0, []))
    )
    monkeypatch.setattr(
        "core.inference.diffusion._assert_base_repo_accessible", lambda *a, **k: None
    )

    plan = DiffusionBackend().download_plan(KLEIN_4B_GGUF, gguf_filename = KLEIN_4B_FILE)

    assert KLEIN_9B_BASE in (plan["incompatible_reason"] or "")
    from models.inference import DiffusionDownloadPlanResponse

    assert KLEIN_9B_BASE in (DiffusionDownloadPlanResponse(**plan).incompatible_reason or "")


def test_a_planner_that_omits_the_field_still_answers():
    # Native and video planners share this envelope, so the field must default rather than 500.
    from models.inference import DiffusionDownloadPlanResponse
    assert DiffusionDownloadPlanResponse(entries = [], total_bytes = 0).incompatible_reason is None


def test_a_compatible_plan_reports_nothing(monkeypatch, tmp_path):
    _stub_range_reads(monkeypatch, {KLEIN_4B_FILE: _gguf_header(3072, tmp_path)})
    monkeypatch.setattr(
        "core.inference.diffusion._resolve_base_repo", lambda *a, **k: KLEIN_4B_BASE
    )
    monkeypatch.setattr(
        DiffusionBackend, "_te_prequant_plan_files", staticmethod(lambda *a, **k: {})
    )
    monkeypatch.setattr(
        DiffusionBackend, "_estimate_download_bytes", staticmethod(lambda *a, **k: (0, []))
    )
    monkeypatch.setattr(
        "core.inference.diffusion._assert_base_repo_accessible", lambda *a, **k: None
    )

    plan = DiffusionBackend().download_plan(KLEIN_4B_GGUF, gguf_filename = KLEIN_4B_FILE)

    assert plan["incompatible_reason"] is None


def test_the_pre_eviction_preflight_refuses_the_mismatch(monkeypatch, tmp_path):
    _stub_range_reads(monkeypatch, {KLEIN_4B_FILE: _gguf_header(3072, tmp_path)})
    monkeypatch.setattr(
        "core.inference.diffusion._resolve_base_repo", lambda *a, **k: KLEIN_9B_BASE
    )
    monkeypatch.setattr(
        "core.inference.diffusion._assert_base_repo_accessible", lambda *a, **k: None
    )

    with pytest.raises(ValueError, match = "klein"):
        DiffusionBackend().preflight_base_access(
            KLEIN_4B_GGUF,
            FLUX2_FAMILY,
            gguf_filename = KLEIN_4B_FILE,
            model_kind = "gguf",
        )


def test_the_load_refuses_before_prefetching_or_unloading_anything(monkeypatch, tmp_path):
    _stub_range_reads(monkeypatch, {KLEIN_4B_FILE: _gguf_header(3072, tmp_path)})
    monkeypatch.setattr(
        "core.inference.diffusion._resolve_base_repo", lambda *a, **k: KLEIN_9B_BASE
    )
    monkeypatch.setattr(
        "core.inference.diffusion._assert_base_repo_accessible", lambda *a, **k: None
    )
    monkeypatch.setattr(
        DiffusionBackend, "_te_prequant_plan_files", staticmethod(lambda *a, **k: {})
    )
    monkeypatch.setattr(
        DiffusionBackend, "_estimate_download_bytes", staticmethod(lambda *a, **k: (0, []))
    )
    monkeypatch.setattr(
        DiffusionBackend,
        "_prefetch_files",
        lambda self, *a, **k: pytest.fail("a rejected pick must not stage a single byte"),
    )
    monkeypatch.setattr(
        DiffusionBackend,
        "load_pipeline",
        lambda self, **k: pytest.fail("a rejected pick must not reach the load"),
    )
    backend = DiffusionBackend()
    monkeypatch.setattr(
        backend,
        "_unload_locked",
        lambda: pytest.fail("a rejected pick must not free the resident pipeline"),
    )
    resident = object()
    backend._state = resident
    backend._load_token = 7
    backend._loading = _LoadingState(repo_id = KLEIN_4B_GGUF, base_repo = "")

    backend._run_load(
        repo_id = KLEIN_4B_GGUF,
        gguf_filename = KLEIN_4B_FILE,
        model_kind = "gguf",
        _load_token = 7,
    )

    progress = backend.load_progress()
    assert progress["phase"] == "error"
    assert KLEIN_9B_BASE in progress["error"]
    assert backend._state is resident


# ── the sibling hole: the native text-encoder pick ─────────────────────────────


from core.inference.diffusion_families import _FLUX2_KLEIN_9B_SD_CPP_TEXT_ENCODERS  # noqa: E402


def test_the_native_encoder_follows_the_header_over_the_filename():
    fam = detect_family("unsloth/FLUX.2-klein-4B-GGUF")
    assert fam is not None and fam.name == "flux.2-klein"

    by_name = sd_cpp_text_encoders_for(fam, "unsloth/FLUX.2-klein-4B-GGUF", "my-checkpoint.gguf")
    by_header = sd_cpp_text_encoders_for(
        fam, "unsloth/FLUX.2-klein-4B-GGUF", "my-checkpoint.gguf", inner_dim = 4096
    )

    assert by_name == fam.sd_cpp_text_encoders
    assert by_header != by_name
    # The 9B checkpoint reads Qwen3-8B.
    assert by_header == _FLUX2_KLEIN_9B_SD_CPP_TEXT_ENCODERS


def test_the_header_also_overrides_a_misleading_9b_filename():
    fam = detect_family("unsloth/FLUX.2-klein-9B-GGUF")
    assert fam is not None

    picked = sd_cpp_text_encoders_for(
        fam, "unsloth/FLUX.2-klein-9B-GGUF", "flux-2-klein-9b-Q4_K_M.gguf", inner_dim = 3072
    )

    assert picked == fam.sd_cpp_text_encoders


def test_an_unmapped_or_absent_inner_dim_keeps_the_filename_rule():
    fam = detect_family("unsloth/FLUX.2-klein-9B-GGUF")
    assert fam is not None
    nine_b = sd_cpp_text_encoders_for(fam, "unsloth/FLUX.2-klein-9B-GGUF", "klein-9b.gguf")

    for inner_dim in (None, 1234):
        assert (
            sd_cpp_text_encoders_for(
                fam, "unsloth/FLUX.2-klein-9B-GGUF", "klein-9b.gguf", inner_dim = inner_dim
            )
            == nine_b
        )
    assert nine_b == _FLUX2_KLEIN_9B_SD_CPP_TEXT_ENCODERS


def test_a_stalled_response_header_cannot_hold_the_picker_open(monkeypatch):
    """requests' timeout is inactivity only, so the header call must run on an abandonable worker."""
    import threading
    import types

    released = threading.Event()

    def _never_returns(*_args, **_kwargs):
        released.wait(30)
        raise AssertionError("the request should have been abandoned, not awaited")

    monkeypatch.setattr(diffusion_compat, "_HEADER_TIMEOUT_SECONDS", 0.5)
    monkeypatch.setattr(
        "huggingface_hub.utils.get_session",
        lambda: types.SimpleNamespace(get = _never_returns),
    )
    monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", lambda *a, **k: None)

    out: list[bytes] = []
    caller = threading.Thread(
        target = lambda: out.append(
            diffusion_compat._read_gguf_header(KLEIN_4B_GGUF, KLEIN_4B_FILE, None)
        ),
        daemon = True,
    )
    caller.start()
    caller.join(8)
    released.set()

    assert not caller.is_alive(), "the caller waited on a request that never returned headers"
    assert out == [b""]


def test_the_offline_caller_still_gets_a_memoised_remote_answer(monkeypatch, tmp_path):
    """Offline begin_load must reuse a memoised remote answer, not fall back to the filename heuristic."""
    monkeypatch.setattr(diffusion_compat, "_INNER_DIM_CACHE", {})
    monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", lambda *a, **k: None)
    monkeypatch.setattr(
        diffusion_compat,
        "_read_gguf_header",
        lambda *a, **k: _gguf_header(4096, tmp_path),
    )

    online = diffusion_compat.flux2_inner_dim_for_pick(KLEIN_4B_GGUF, "renamed-4b.gguf")
    assert online == 4096

    monkeypatch.setattr(
        diffusion_compat,
        "_read_gguf_header",
        lambda *a, **k: pytest.fail("the offline caller made a range request"),
    )
    assert (
        diffusion_compat.flux2_inner_dim_for_pick(
            KLEIN_4B_GGUF, "renamed-4b.gguf", allow_network = False
        )
        == 4096
    )


def _cached_snapshot(
    tmp_path,
    sha,
    body,
    filename = KLEIN_4B_FILE,
):
    """A file where huggingface_hub puts it: ``models--org--repo/snapshots/<sha>/<file>``."""
    path = tmp_path / f"models--{KLEIN_4B_GGUF.replace('/', '--')}" / "snapshots" / sha / filename
    path.parent.mkdir(parents = True, exist_ok = True)
    path.write_bytes(body)
    return path


def _stub_revision(monkeypatch, sha):
    def _meta(*_args, **_kwargs):
        if sha is None:
            raise OSError("offline")
        return types.SimpleNamespace(commit_hash = sha, etag = sha)

    monkeypatch.setattr("huggingface_hub.get_hf_file_metadata", _meta)


def test_a_republished_checkpoint_is_not_refused_from_the_stale_cache(monkeypatch, tmp_path):
    """try_to_load_from_cache resolves the LOCAL refs/main, so a 4B file republished at the same
    name as a 9B one would refuse a pick the loader's own hf_hub_download refreshes and loads."""
    requests = _stub_range_reads(monkeypatch, {KLEIN_4B_FILE: _gguf_header(4096, tmp_path)})
    cached = _cached_snapshot(tmp_path, "oldcommit", _gguf_header(3072, tmp_path))
    monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", lambda *a, **k: str(cached))
    _stub_revision(monkeypatch, "newcommit")

    reason = diffusion_compat.flux2_pick_mismatch(
        FLUX2_FAMILY, KLEIN_4B_GGUF, KLEIN_4B_FILE, KLEIN_9B_BASE
    )

    assert reason is None, "a stale cached header refused a pick the loader would have loaded"
    assert requests, "the live header was never read"


def test_a_cached_checkpoint_at_the_current_revision_is_still_refused(monkeypatch, tmp_path):
    requests = _stub_range_reads(monkeypatch, {KLEIN_4B_FILE: _gguf_header(4096, tmp_path)})
    cached = _cached_snapshot(tmp_path, "oldcommit", _gguf_header(3072, tmp_path))
    monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", lambda *a, **k: str(cached))
    _stub_revision(monkeypatch, "oldcommit")

    reason = diffusion_compat.flux2_pick_mismatch(
        FLUX2_FAMILY, KLEIN_4B_GGUF, KLEIN_4B_FILE, KLEIN_9B_BASE
    )

    assert reason is not None and "klein-9B" in reason
    assert requests == []


def test_a_revision_check_that_cannot_run_keeps_the_cached_refusal(monkeypatch, tmp_path):
    requests = _stub_range_reads(monkeypatch, {KLEIN_4B_FILE: _gguf_header(4096, tmp_path)})
    cached = _cached_snapshot(tmp_path, "oldcommit", _gguf_header(3072, tmp_path))
    monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", lambda *a, **k: str(cached))
    _stub_revision(monkeypatch, None)

    reason = diffusion_compat.flux2_pick_mismatch(
        FLUX2_FAMILY, KLEIN_4B_GGUF, KLEIN_4B_FILE, KLEIN_9B_BASE
    )

    assert reason is not None and "klein-9B" in reason
    assert requests == []


def test_an_on_device_checkpoint_is_never_revalidated(monkeypatch, tmp_path):
    local = tmp_path / "on-device"
    local.mkdir()
    (local / KLEIN_4B_FILE).write_bytes(_gguf_header(3072, tmp_path))
    requests = _stub_range_reads(monkeypatch, {})
    monkeypatch.setattr(
        diffusion_compat,
        "_hub_revision",
        lambda *a, **k: pytest.fail("an On Device pick asked the Hub for a revision"),
    )

    reason = diffusion_compat.flux2_pick_mismatch(
        FLUX2_FAMILY, str(local), KLEIN_4B_FILE, KLEIN_9B_BASE
    )

    assert reason is not None and "klein-9B" in reason
    assert requests == []


# Undownloaded speech quants stay listed, and detect_family_for_pick reads the folder name.

CSM_REPO = "someone/mixed-media-GGUF"
CSM_FILE = "csm-1b-Q4_0.gguf"
DENOISER_FILE = "flux1-dev-Q4_K_M.gguf"


def _arch_header(architecture: str) -> bytes:
    """Minimal GGUF prefix with only general.architecture, read by hand to match the listing-side gate."""
    import struct

    def string(value: str) -> bytes:
        data = value.encode()
        return struct.pack("<Q", len(data)) + data

    return (
        struct.pack("<IIQQ", 0x46554747, 3, 0, 1)
        + string("general.architecture")
        + struct.pack("<I", 8)
        + string(architecture)
    )


def test_an_undownloaded_speech_pick_is_refused_before_any_download(monkeypatch):
    """The whole point: the refusal lands off one range request, so the checkpoint is never
    pulled and the resident pipeline never torn down for a file that cannot decode."""
    requests = _stub_range_reads(monkeypatch, {CSM_FILE: _arch_header("llama-csm")})

    with pytest.raises(ValueError) as excinfo:
        diffusion_compat.assert_pick_is_not_speech(CSM_REPO, CSM_FILE)

    detail = str(excinfo.value)
    assert CSM_FILE in detail and "llama-csm" in detail
    assert len(requests) == 1
    url, byte_range = requests[0]
    assert url.endswith(f"{CSM_REPO}/resolve/main/{CSM_FILE}")
    assert byte_range == f"bytes=0-{diffusion_compat._GGUF_HEADER_BYTES - 1}"


def test_a_runnable_media_pick_in_the_same_repo_still_loads(monkeypatch):
    """A runnable media sibling in the repo must still load: catching it too would hide it."""
    _stub_range_reads(monkeypatch, {DENOISER_FILE: _arch_header("flux")})

    assert diffusion_compat.speech_pick_refusal(CSM_REPO, DENOISER_FILE) is None
    diffusion_compat.assert_pick_is_not_speech(CSM_REPO, DENOISER_FILE)


TE_REPO = "ponpoke/flux2-klein-9b-uncensored-text-encoder"
TE_FILE = "flux2-klein-9b-uncensored-q4_k_m.gguf"


def test_an_undownloaded_text_encoder_pick_is_refused_before_any_download(monkeypatch):
    """#9875: the repo name matches flux.2-klein, so without this the Qwen3 encoder loads as the denoiser and dies
    with "Cannot copy out of meta tensor" after the download and the teardown."""
    requests = _stub_range_reads(monkeypatch, {TE_FILE: _arch_header("qwen3")})

    with pytest.raises(ValueError) as excinfo:
        diffusion_compat.assert_pick_is_not_speech(TE_REPO, TE_FILE)

    detail = str(excinfo.value)
    assert TE_FILE in detail and "text encoder (qwen3 GGUF)" in detail
    assert len(requests) == 1


def test_an_unreadable_speech_header_fails_open(monkeypatch):
    """Fail-open throughout: refusing a pick that works is worse than the download this saves."""
    _stub_range_reads(monkeypatch, {}, status = 200)

    assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is None
    diffusion_compat.assert_pick_is_not_speech(CSM_REPO, CSM_FILE)


def test_a_pick_with_no_gguf_filename_is_not_probed(monkeypatch):
    """A pipeline or single_file pick names no GGUF, so there is no header to ask."""
    requests = _stub_range_reads(monkeypatch, {CSM_FILE: _arch_header("llama-csm")})

    assert diffusion_compat.speech_pick_refusal(CSM_REPO, None) is None
    assert requests == []


def test_the_speech_verdict_is_memoised_per_pick(monkeypatch):
    """Expanding and re-picking a row must not re-spend the range request."""
    requests = _stub_range_reads(monkeypatch, {CSM_FILE: _arch_header("llama-csm")})

    assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None
    assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None
    assert len(requests) == 1


def test_a_failed_probe_is_not_reused_for_a_retry_with_a_working_token(monkeypatch):
    """A probe that failed on an expired credential memoises "no verdict". Keyed without the
    token, the retry with a working one reads that back and the speech file reaches the download
    this preflight exists to stop."""
    bodies = {CSM_FILE: _arch_header("llama-csm")}
    requests: list = []

    class _Session:
        def get(
            self,
            url,
            headers = None,
            timeout = None,
            stream = False,
        ):
            header_map = headers or {}
            requests.append(header_map.get("authorization") or header_map.get("Authorization"))
            if not any("good" in str(v) for v in header_map.values()):
                return _FakeResponse(401)
            body = next((b for name, b in bodies.items() if url.endswith(name)), None)
            return _FakeResponse(206, body) if body is not None else _FakeResponse(404)

    monkeypatch.setattr("huggingface_hub.utils.get_session", lambda: _Session())
    monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", lambda *a, **k: None)
    monkeypatch.setattr(diffusion_compat, "_local_gguf_path", lambda *a, **k: None)

    assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE, "expired") is None
    assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE, "good-token") is not None
    assert len(requests) == 2


def test_a_checkpoint_that_lands_after_a_miss_is_probed_again(monkeypatch, tmp_path):
    """A file replaced under the same name is a different checkpoint; keyed without its identity
    the verdict never revisits it."""
    _stub_range_reads(monkeypatch, {})
    landed = tmp_path / CSM_FILE
    seen: dict = {"path": None}
    monkeypatch.setattr(diffusion_compat, "_local_gguf_path", lambda *a, **k: seen["path"])

    assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is None

    landed.write_bytes(_arch_header("llama-csm"))
    seen["path"] = str(landed)

    assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None


def _cache_entry(tmp_path, revision, arch):
    """A GGUF sitting in an HF cache snapshot dir, so ``_snapshot_revision`` can read its commit."""
    snapshot = tmp_path / "models--someone--mixed-media-GGUF" / "snapshots" / revision
    snapshot.mkdir(parents = True, exist_ok = True)
    path = snapshot / CSM_FILE
    path.write_bytes(_arch_header(arch))
    return str(path)


def test_a_republished_gguf_is_not_refused_from_the_stale_cached_copy(monkeypatch, tmp_path):
    """``try_to_load_from_cache`` resolves the LOCAL refs/main, so a republished filename would
    be refused off the csm bytes still on disk while ``hf_hub_download`` refreshes and loads the
    new ones."""
    cached = _cache_entry(tmp_path, "oldsha", "llama-csm")
    monkeypatch.setattr(diffusion_compat, "_local_gguf_path", lambda *a, **k: cached)
    monkeypatch.setattr(diffusion_compat, "_hub_revision", lambda *a, **k: "newsha")
    _stub_range_reads(monkeypatch, {CSM_FILE: _arch_header("flux")})

    assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is None


def test_a_cached_gguf_at_the_current_revision_is_still_refused(monkeypatch, tmp_path):
    """The revalidation must not become an escape hatch: same commit, same verdict."""
    cached = _cache_entry(tmp_path, "samesha", "llama-csm")
    monkeypatch.setattr(diffusion_compat, "_local_gguf_path", lambda *a, **k: cached)
    monkeypatch.setattr(diffusion_compat, "_hub_revision", lambda *a, **k: "samesha")
    _stub_range_reads(monkeypatch, {})

    assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None


def test_a_revision_check_that_cannot_run_keeps_the_refusal(monkeypatch, tmp_path):
    """An offline or erroring host leaves today's verdict alone rather than opening the gate."""
    cached = _cache_entry(tmp_path, "oldsha", "llama-csm")
    monkeypatch.setattr(diffusion_compat, "_local_gguf_path", lambda *a, **k: cached)
    monkeypatch.setattr(diffusion_compat, "_hub_revision", lambda *a, **k: None)
    _stub_range_reads(monkeypatch, {})

    assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None


def test_an_on_device_speech_checkpoint_is_never_revalidated(monkeypatch, tmp_path):
    """An On Device file is the one the loader opens, so there is no revision to be behind."""
    on_device = tmp_path / CSM_FILE
    on_device.write_bytes(_arch_header("llama-csm"))
    monkeypatch.setattr(diffusion_compat, "_local_gguf_path", lambda *a, **k: str(on_device))
    asked: list = []

    def _never(*a, **k):
        asked.append(a)
        return "newsha"

    monkeypatch.setattr(diffusion_compat, "_hub_revision", _never)
    _stub_range_reads(monkeypatch, {})

    assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None
    assert asked == []


def test_a_pick_that_names_the_checkpoint_outright_is_probed_like_the_loader_opens_it(tmp_path):
    """A file-valued repo_id is accepted by the video loader, so the preflight must probe it as a file."""
    direct = tmp_path / "wan-models" / CSM_FILE
    direct.parent.mkdir(parents = True)
    direct.write_bytes(_arch_header("llama-csm"))

    reason = diffusion_compat.speech_pick_refusal(str(direct), CSM_FILE, None, False)
    assert reason is not None and "llama-csm" in reason

    assert diffusion_compat._local_gguf_path(str(direct), CSM_FILE) == str(direct)

    denoiser = direct.parent / DENOISER_FILE
    denoiser.write_bytes(_arch_header("flux"))
    assert diffusion_compat.speech_pick_refusal(str(denoiser), DENOISER_FILE, None, False) is None

    assert diffusion_compat._local_gguf_path(str(direct.parent), CSM_FILE) == str(direct)


# Pages stage and download BEFORE load; Video and sd.cpp do not share DiffusionBackend's preflight.


def test_the_shared_refusal_is_wired_into_every_plan_and_load_path():
    """Structural, deliberately: the tests above pin the verdict, but what keeps regressing is
    where it is CALLED, and exercising each engine's plan/load needs a live backend and a Hub."""
    import inspect

    from core.inference import diffusion, sd_cpp_backend, video

    plan = inspect.getsource(diffusion.DiffusionBackend.download_plan)
    assert "speech_pick_refusal" in plan

    assert "_assert_pick_is_not_speech" in inspect.getsource(video.VideoBackend.download_plan)
    assert "_assert_pick_is_not_speech" in inspect.getsource(video.VideoBackend._run_load)

    # sd.cpp: plan and worker. NOT begin_load, which is offline-only and cannot afford the bound.
    sd_plan = inspect.getsource(sd_cpp_backend.SdCppDiffusionBackend.download_plan)
    assert "_assert_pick_is_not_speech" in sd_plan
    assert "_assert_pick_is_not_speech" not in inspect.getsource(
        sd_cpp_backend.SdCppDiffusionBackend.begin_load
    )


def test_the_video_and_sd_cpp_helpers_delegate_to_the_one_verdict(monkeypatch):
    """Three engines, one refusal. A second copy of the speech arch set is how they drift."""
    from core.inference import sd_cpp_backend, video

    seen: list = []
    monkeypatch.setattr(
        diffusion_compat,
        "assert_pick_is_not_speech",
        lambda *a, **k: seen.append(a),
    )

    video._assert_pick_is_not_speech(CSM_REPO, CSM_FILE, "tok", allow_network = False)
    sd_cpp_backend._assert_pick_is_not_speech(CSM_REPO, CSM_FILE, "tok", allow_network = False)

    assert seen == [(CSM_REPO, CSM_FILE, "tok", False), (CSM_REPO, CSM_FILE, "tok", False)]


def test_a_media_gguf_republished_as_speech_is_refused(monkeypatch, tmp_path):
    """A stale refusal only costs a pick, but a stale ALLOW hands csm bytes to a media loader, so
    revalidation cannot be the cheap side of the asymmetry."""
    snapshot = tmp_path / "models--someone--mixed-media-GGUF" / "snapshots" / "oldsha"
    snapshot.mkdir(parents = True)
    cached = snapshot / CSM_FILE
    cached.write_bytes(_arch_header("flux"))

    monkeypatch.setattr(diffusion_compat, "_local_gguf_path", lambda *a, **k: str(cached))
    monkeypatch.setattr(diffusion_compat, "_hub_revision", lambda *a, **k: "newsha")
    _stub_range_reads(monkeypatch, {CSM_FILE: _arch_header("llama-csm")})

    assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None


def test_an_uncached_pick_never_spends_a_revision_head(monkeypatch):
    """No cached copy, no revision to be behind: uncached picks must not spend a Hub HEAD."""
    monkeypatch.setattr(diffusion_compat, "_local_gguf_path", lambda *a, **k: None)
    asked: list = []
    monkeypatch.setattr(
        diffusion_compat, "_hub_revision", lambda *a, **k: asked.append(a) or "newsha"
    )
    _stub_range_reads(monkeypatch, {CSM_FILE: _arch_header("llama-csm")})

    assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None
    assert asked == []


def test_a_cache_only_load_never_range_reads_an_uncached_pick(monkeypatch):
    """An automatic load sets local_files_only, and that contract covers the metadata probes too:
    an uncached pick gives up rather than spend the range request and its 15s bound."""
    requests = _stub_range_reads(monkeypatch, {CSM_FILE: _arch_header("llama-csm")})
    monkeypatch.setattr(diffusion_compat, "_local_gguf_path", lambda *a, **k: None)

    assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE, allow_network = False) is None
    assert requests == []

    assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None
    assert len(requests) == 1


def test_a_cache_only_load_still_reads_a_checkpoint_already_on_disk(monkeypatch, tmp_path):
    """Offline does not mean blind: a copy already on disk answers with no request at all."""
    on_device = tmp_path / CSM_FILE
    on_device.write_bytes(_arch_header("llama-csm"))
    requests = _stub_range_reads(monkeypatch, {})
    monkeypatch.setattr(diffusion_compat, "_local_gguf_path", lambda *a, **k: str(on_device))

    assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE, allow_network = False) is not None
    assert requests == []


def test_a_cache_only_probe_does_not_memoise_a_skipped_revision_check(monkeypatch, tmp_path):
    """A cached copy read WITHOUT its revision check is half an answer; memoising it would let
    the network-allowed caller behind it read that back and never revalidate."""
    snapshot = tmp_path / "models--someone--mixed-media-GGUF" / "snapshots" / "oldsha"
    snapshot.mkdir(parents = True)
    cached = snapshot / CSM_FILE
    cached.write_bytes(_arch_header("flux"))
    monkeypatch.setattr(diffusion_compat, "_local_gguf_path", lambda *a, **k: str(cached))

    heads: list = []
    monkeypatch.setattr(
        diffusion_compat, "_hub_revision", lambda *a, **k: heads.append(a) or "newsha"
    )
    _stub_range_reads(monkeypatch, {CSM_FILE: _arch_header("llama-csm")})

    assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE, allow_network = False) is None
    assert heads == []

    assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None
    assert len(heads) == 1


def test_an_uncached_remote_verdict_is_not_memoised_forever(monkeypatch):
    """An uncached remote pick keys on a None identity, so a republish under the same filename
    changes nothing; without a TTL the verdict would outlive the process."""
    monkeypatch.setattr(diffusion_compat, "_local_gguf_path", lambda *a, **k: None)
    bodies = {CSM_FILE: _arch_header("llama-csm")}
    _stub_range_reads(monkeypatch, bodies)
    # Driven, not real: the entry expires relative to whatever monotonic said when it was written.
    clock = [1000.0]
    monkeypatch.setattr(diffusion_compat.time, "monotonic", lambda: clock[0])

    assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None
    assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None

    bodies[CSM_FILE] = _arch_header("flux")
    clock[0] += diffusion_compat._SPEECH_REMOTE_TTL_SECONDS + 1.0

    assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is None


def test_a_snapshot_backed_verdict_keeps_its_entry_across_the_window(monkeypatch, tmp_path):
    """A cached entry needs no TTL: its key carries the file identity and the revision check asks
    the Hub. Expiring it too would spend a range read per pick for nothing."""
    snapshot = tmp_path / "models--someone--mixed-media-GGUF" / "snapshots" / "samesha"
    snapshot.mkdir(parents = True)
    cached = snapshot / CSM_FILE
    cached.write_bytes(_arch_header("llama-csm"))
    monkeypatch.setattr(diffusion_compat, "_local_gguf_path", lambda *a, **k: str(cached))
    monkeypatch.setattr(diffusion_compat, "_hub_revision", lambda *a, **k: "samesha")
    requests = _stub_range_reads(monkeypatch, {})

    clock = [1000.0]
    monkeypatch.setattr(diffusion_compat.time, "monotonic", lambda: clock[0])

    assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None
    clock[0] += diffusion_compat._SPEECH_REMOTE_TTL_SECONDS * 10
    assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None
    assert requests == []


def test_both_media_routes_refuse_a_speech_pick_before_taking_the_gpu():
    """Media routes refuse a speech pick before the GPU arbiter, or the resident model is evicted first."""
    import inspect

    from routes import inference as inference_route
    from routes import video as video_route

    for source, acquire, label in (
        (
            inspect.getsource(video_route.load_video_model_gated),
            r"acquire_for_request\(\s*VIDEO\b",
            "video",
        ),
        (
            inspect.getsource(inference_route.load_diffusion_model_gated),
            r"acquire_for_request\(\s*DIFFUSION\b",
            "images",
        ),
    ):
        assert "assert_pick_is_not_speech" in source, label
        # The call may wrap its arguments over several lines (e.g. with policy_kwargs).
        call = re.search(acquire, source)
        assert call is not None, label
        assert source.index("assert_pick_is_not_speech") < call.start(), label


def test_an_automatic_image_load_keeps_the_pre_eviction_preflight_offline():
    """Automatic image loads keep the pre-eviction preflight offline, so no revision HEAD hits the Hub."""
    import inspect

    from core.inference import diffusion, sd_cpp_backend
    from routes import inference as inference_route

    preflight = inspect.getsource(diffusion.DiffusionBackend.preflight_base_access)
    assert "assert_pick_is_not_speech(repo_id, gguf_filename, hf_token, allow_network)" in preflight

    route = inspect.getsource(inference_route.load_diffusion_model_gated)
    assert "allow_network = user_initiated" in route

    for backend in (diffusion.DiffusionBackend, sd_cpp_backend.SdCppDiffusionBackend):
        assert "allow_network" in inspect.signature(backend.preflight_base_access).parameters


# The Mimi vocoder in ggml-org/sesame-csm-1b-GGUF writes a sentence as its architecture id.
_VOCODER_ARCH = "this model cannot be used as LLM, use it via --model-vocoder in TTS examples"


class _HttpxLikeClient:
    """Fake httpx.Client surface matching get_session on huggingface_hub 1.x, not a requests mock."""

    def __init__(self, body):
        self.body = body
        self.calls: list[tuple[str, str]] = []

    def get(
        self,
        url,
        params = None,
        headers = None,
        timeout = None,
        **kwargs,
    ):
        if "stream" in kwargs:
            raise TypeError("Client.get() got an unexpected keyword argument 'stream'")
        raise AssertionError("a ranged header read must use the streaming API")

    def stream(
        self,
        method,
        url,
        headers = None,
        timeout = None,
        follow_redirects = False,
    ):
        self.calls.append((method, (headers or {}).get("Range", "")))
        assert follow_redirects, "the Hub answers a resolve URL with a 302 to the CDN"
        return _HttpxLikeStream(self.body)


class _HttpxLikeStream:
    def __init__(self, body):
        self.body = body

    def __enter__(self):
        return self

    def __exit__(self, *exc):
        return False

    @property
    def status_code(self):
        return 206

    def iter_bytes(self, chunk_size = 65536):
        for start in range(0, len(self.body), chunk_size):
            yield self.body[start : start + chunk_size]

    def close(self):
        pass


def test_the_ranged_read_works_on_the_httpx_client_hub_1_x_returns(monkeypatch):
    """huggingface_hub 1.0 moved to httpx, which has no stream = True keyword; the TypeError was
    swallowed by a blanket except, so every uncached remote pick failed open."""
    client = _HttpxLikeClient(_arch_header("llama-csm"))
    monkeypatch.setattr("huggingface_hub.utils.get_session", lambda: client)
    monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", lambda *a, **k: None)
    diffusion_compat._reset_inner_dim_cache()

    assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None
    assert client.calls == [("GET", f"bytes=0-{diffusion_compat._GGUF_HEADER_BYTES - 1}")]


def test_the_ranged_read_still_works_on_the_requests_session_hub_0_x_returns(monkeypatch):
    """The other half of the floor: python < 3.10 pins 0.36, whose session is requests'."""
    requests_log = _stub_range_reads(monkeypatch, {CSM_FILE: _arch_header("llama-csm")})

    assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None
    assert len(requests_log) == 1


def test_a_requests_session_is_not_mistaken_for_an_httpx_client(monkeypatch):
    """``requests.Session.stream`` is a plain bool attribute and ``httpx.Client.stream`` is a
    method, so the branch has to test for a CALLABLE. Testing for the name alone sends a requests
    session down the httpx path and breaks the client that works today."""
    import requests

    assert hasattr(requests.Session(), "stream")
    assert not callable(getattr(requests.Session(), "stream", None))


def test_a_cached_snapshot_verdict_does_not_outlive_its_revision_check(monkeypatch, tmp_path):
    """A snapshot-backed entry memoises a revision check; holding it forever meant the Hub was asked
    once per file per process, so a republished checkpoint kept its stale verdict."""
    cached = _cache_entry(tmp_path, "oldsha", "llama-csm")
    monkeypatch.setattr(diffusion_compat, "_local_gguf_path", lambda *a, **k: cached)
    heads: list = []

    def _head(*a, **k):
        heads.append(a)
        return "oldsha"

    monkeypatch.setattr(diffusion_compat, "_hub_revision", _head)
    _stub_range_reads(monkeypatch, {})

    assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None
    assert len(heads) == 1
    assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None
    assert len(heads) == 1
    monkeypatch.setattr(
        diffusion_compat.time,
        "monotonic",
        lambda: 1e9 + diffusion_compat._SPEECH_REMOTE_TTL_SECONDS,
    )
    assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None
    assert len(heads) == 2


def test_an_on_device_verdict_is_still_cached_permanently(monkeypatch, tmp_path):
    """On Device files have no revision to lag, so the identity-keyed verdict never expires."""
    on_device = tmp_path / CSM_FILE
    on_device.write_bytes(_arch_header("llama-csm"))
    monkeypatch.setattr(diffusion_compat, "_local_gguf_path", lambda *a, **k: str(on_device))
    _stub_range_reads(monkeypatch, {})

    assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None
    key = next(iter(diffusion_compat._SPEECH_ARCH_CACHE))
    assert diffusion_compat._SPEECH_ARCH_CACHE[key][1] is None


def test_a_failed_refresh_keeps_the_verdict_it_already_had(monkeypatch, tmp_path):
    """A new-revision HEAD followed by a failed re-read must keep a known llama-csm verdict, not
    replace it with None; failing open is for UNKNOWN picks only."""
    cached = _cache_entry(tmp_path, "oldsha", "llama-csm")
    monkeypatch.setattr(diffusion_compat, "_local_gguf_path", lambda *a, **k: cached)
    monkeypatch.setattr(diffusion_compat, "_hub_revision", lambda *a, **k: "newsha")
    _stub_range_reads(monkeypatch, {})

    assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None

    diffusion_compat._reset_inner_dim_cache()
    _stub_range_reads(monkeypatch, {CSM_FILE: _arch_header("flux")})
    monkeypatch.setattr(diffusion_compat, "_local_gguf_path", lambda *a, **k: cached)
    monkeypatch.setattr(diffusion_compat, "_hub_revision", lambda *a, **k: "newsha")
    assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is None


def test_every_published_csm_spelling_is_refused_by_the_media_preflight(monkeypatch):
    """A bundle's vocoder reaches media loaders too, so every CSM spelling must be refused."""
    for arch in ("llama-csm", "csm", "csm-tts", "mimi"):
        _stub_range_reads(monkeypatch, {CSM_FILE: _arch_header(arch)})
        assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None, arch
    _stub_range_reads(monkeypatch, {CSM_FILE: _arch_header(_VOCODER_ARCH)})
    reason = diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE)
    assert reason is not None and "--model-vocoder" not in reason


def test_one_pick_range_reads_the_header_once_for_both_probes(monkeypatch, tmp_path):
    """Size pairing and the speech verdict must share one range read of the same GGUF prefix."""
    requests = _stub_range_reads(monkeypatch, {KLEIN_4B_FILE: _gguf_header(3072, tmp_path)})

    assert (
        diffusion_compat.flux2_pick_mismatch(
            FLUX2_FAMILY, KLEIN_4B_GGUF, KLEIN_4B_FILE, KLEIN_4B_BASE
        )
        is None
    ), "the fixture pairs correctly, so the speech probe behind it really does run"
    assert diffusion_compat.speech_pick_refusal(KLEIN_4B_GGUF, KLEIN_4B_FILE) is None

    assert len(requests) == 1, f"one pick, one header read; got {len(requests)}"


def test_a_revalidation_still_re_reads_rather_than_answering_from_the_shared_prefix(
    monkeypatch, tmp_path
):
    """Revalidation must re-read the header, never answer from the shared prefix memo."""
    source = inspect.getsource(diffusion_compat)
    for fn in ("_revalidated_inner_dim", "_revalidated_speech_arch"):
        body = source.split(f"def {fn}(", 1)[1].split("\ndef ", 1)[0]
        assert "_shared_gguf_header" not in body, f"{fn} must re-read, not consult the memo"
        assert "_read_gguf_header" in body


def test_the_chat_backend_does_not_import_pyyaml_to_learn_the_speech_verdict():
    """llama_cpp must not import the models package, or PyYAML becomes a hard chat-backend dependency."""
    import importlib
    import subprocess
    import sys
    from pathlib import Path

    backend = Path(diffusion_compat.__file__).resolve().parents[2]
    probe = (
        "import sys\n"
        "class Blocker:\n"
        "    def find_spec(self, name, path=None, target=None):\n"
        "        if name == 'yaml' or name.startswith('yaml.'):\n"
        "            raise ModuleNotFoundError(\"No module named 'yaml'\")\n"
        "        return None\n"
        "sys.meta_path.insert(0, Blocker())\n"
        f"sys.path.insert(0, {str(backend)!r})\n"
        "import core.inference.llama_cpp as m\n"
        "from utils.gguf_archs import SPEECH_GGUF_ARCHS\n"
        "assert m.LlamaCppBackend._SPEECH_ARCHES is SPEECH_GGUF_ARCHS\n"
        "print('ok')\n"
    )
    # Subprocess: yaml is already imported here, and meta_path blockers cannot un-import it.
    result = subprocess.run(
        [sys.executable, "-c", probe], capture_output = True, text = True, timeout = 300
    )
    assert result.returncode == 0, f"stderr: {result.stderr}"

    # No re-export from the heavy package; scripts/verify_import_hoist.py blocks those anyway.
    gguf_metadata = importlib.import_module("utils.models.gguf_metadata")
    for name in ("SPEECH_GGUF_ARCHS", "is_speech_gguf_architecture"):
        assert not hasattr(
            gguf_metadata, name
        ), f"{name} must be imported from utils.gguf_archs, not through utils.models"


def test_qwen_image_2_1_takes_the_dynamic_4bit_text_encoder():
    """Pin the Qwen-Image-2.1 encoder filename exactly; a missing name 404s mid-load, after staging."""
    from core.inference.diffusion_families import detect_family

    fam = detect_family("Qwen/Qwen-Image-2.1")
    assert fam.sd_cpp_text_encoders == (
        (
            "unsloth/Qwen3-VL-8B-Instruct-GGUF",
            "Qwen3-VL-8B-Instruct-UD-Q4_K_XL.gguf",
            "llm",
        ),
        ("unsloth/Qwen3-VL-8B-Instruct-GGUF", "mmproj-F16.gguf", "llm_vision"),
    )