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.

148 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

"""Tests for the native sd.cpp diffusion backend (the no-GPU engine)."""

from __future__ import annotations

import os
import shutil
import threading
import time
import types
from pathlib import Path

import pytest
from PIL import Image

from core.inference import sd_cpp_backend as bk
from core.inference.diffusion_families import (
    _FLUX2_KLEIN_9B_SD_CPP_TEXT_ENCODERS,
    detect_family,
)
from core.inference.sd_cpp_args import SdCppGenParams, SdCppModelFiles
from core.inference.sd_cpp_backend import (
    SdCppDiffusionBackend,
    _map_guidance,
    ensure_sd_cpp_binary,
)
from core.inference.sd_cpp_engine import SdCppCancelled


def _shared_setup_1(b, fake, monkeypatch):
    monkeypatch.setattr(b, "_resolve_engine", lambda: fake)
    monkeypatch.setattr(b, "_asset_specs", lambda *a, **k: [])
    monkeypatch.setattr(b, "_set_expected_bytes", lambda *a, **k: None)
    monkeypatch.setattr(
        b,
        "_fetch_assets",
        lambda *a, **k: {"diffusion_model": "/m/z.gguf", "vae": "/m/vae.sft", "llm": "/m/llm.sft"},
    )
    monkeypatch.setattr(
        bk, "resolve_diffusion_device_target", lambda: types.SimpleNamespace(device = "cpu")
    )


def _shared_setup_2(b, fam):
    b._run_load(
        repo_id = "unsloth/Z-Image-Turbo-GGUF",
        gguf_filename = "z.gguf",
        base = fam.base_repo,
        fam = fam,
        hf_token = None,
        _load_token = 1,
    )


def _shared_setup_3(monkeypatch, own):
    monkeypatch.setattr(bk, "ensure_sd_cpp_binary", lambda **_kwargs: str(own))
    monkeypatch.setattr(bk, "is_managed_binary", lambda _b: False)
    monkeypatch.setattr(bk, "_sd_cpp_probe_output", lambda *_args: _PRE_H3_HELP)

    with pytest.raises(RuntimeError, match = "does not advertise MiniMax-H3") as excinfo:
        bk.ensure_h3_sd_cpp_binary()
    return excinfo


def _shared_setup_4(monkeypatch):
    b = SdCppDiffusionBackend(engine = _FakeEngine())
    monkeypatch.setattr(
        SdCppDiffusionBackend, "_plan_file_sizes", staticmethod(lambda by_repo, token: {})
    )
    return b


class _FakeEngine:
    """Stands in for SdCppEngine: writes a 1x1 PNG and records the args."""

    def __init__(
        self,
        *,
        fail = None,
        cancel_on_call = False,
    ):
        self.calls = []
        self.fail = fail
        self.cancel_on_call = cancel_on_call

    def is_available(self):
        return True

    def version(self, **_):
        return "fake sd-cli"

    def generate(
        self,
        files,
        params,
        *,
        output_path,
        cancel_event = None,
        **kw,
    ):
        self.calls.append((files, params, output_path, kw))
        if self.cancel_on_call and cancel_event is not None:
            cancel_event.set()
        if self.fail is not None:
            raise self.fail
        if cancel_event is not None and cancel_event.is_set():
            raise SdCppCancelled("cancelled")
        Image.new("RGB", (1, 1), (10, 20, 30)).save(output_path)
        from pathlib import Path

        return Path(output_path)


def _loaded_backend(fam_name = "z-image", engine = None):
    b = SdCppDiffusionBackend(engine = engine or _FakeEngine())
    fam = detect_family(fam_name)
    b._state = bk._SdState(
        repo_id = "unsloth/Z-Image-Turbo-GGUF",
        base_repo = fam.base_repo,
        family = fam,
        device = "cpu",
        files = SdCppModelFiles(
            diffusion_model = "/m/z.gguf", vae = "/m/vae.safetensors", llm = "/m/llm.safetensors"
        ),
        vae_format = fam.sd_cpp_vae_format,
        sampling_method = fam.sd_cpp_sampling_method,
        flow_shift = fam.sd_cpp_flow_shift,
        mode = "oneshot",
    )
    return b


def test_loaded_repo_ids_includes_native_companions():
    # The one-shot engine re-reads companion files, so the delete guard must list VAE + encoder repos.
    b = _loaded_backend("flux.1")
    ids = set(b.loaded_repo_ids())
    fam = detect_family("flux.1")
    assert "unsloth/Z-Image-Turbo-GGUF" in ids
    assert fam.base_repo in ids
    assert fam.sd_cpp_vae[0] in ids
    for terepo, _f, _k in fam.sd_cpp_text_encoders:
        assert terepo in ids  # black-forest-labs/FLUX.1-schnell (CLIP-L + sharded T5-XXL)
    b._state = None
    assert b.loaded_repo_ids() == ()


def test_native_status_preserves_the_logical_picker_identity():
    import dataclasses

    b = _loaded_backend()
    b._state = dataclasses.replace(
        b._state,
        repo_id = "/cache/models--unsloth--Z-Image-Turbo-GGUF/snapshots/abc",
        display_repo_id = "unsloth/Z-Image-Turbo-GGUF",
    )
    status = b.status()
    assert status["repo_id"].endswith("/snapshots/abc")
    assert status["display_repo_id"] == "unsloth/Z-Image-Turbo-GGUF"
    result = b.generate(prompt = "logical identity", steps = 1, seed = 1)
    assert result["repo_id"] == "unsloth/Z-Image-Turbo-GGUF"


def test_loaded_repo_ids_tracks_variant_encoder_by_gguf_filename():
    # A local GGUF carries the variant keyword only in the basename.
    b = SdCppDiffusionBackend(engine = _FakeEngine())
    fam = detect_family("flux.2-klein")
    b._state = bk._SdState(
        repo_id = "local/my-klein-checkpoints",
        base_repo = fam.base_repo,
        family = fam,
        device = "cpu",
        files = SdCppModelFiles(diffusion_model = "/m/FLUX.2-klein-9B-Q4_K_M.gguf"),
        vae_format = fam.sd_cpp_vae_format,
        sampling_method = fam.sd_cpp_sampling_method,
        flow_shift = fam.sd_cpp_flow_shift,
        mode = "oneshot",
        gguf_filename = "FLUX.2-klein-9B-Q4_K_M.gguf",
    )
    ids = set(b.loaded_repo_ids())
    nine_b = _FLUX2_KLEIN_9B_SD_CPP_TEXT_ENCODERS[0][0]
    four_b = fam.sd_cpp_text_encoders[0][0]
    assert nine_b != four_b
    assert nine_b in ids  # the 8B encoder this load pulled (unsloth/Qwen3-8B-GGUF)
    # The 4B default must not be protected instead.
    assert four_b not in ids


class _FakeServer:
    """Stands in for SdCppServer: records the spawn + one img_gen per whole batch."""

    def __init__(self, binary):
        self.binary = binary
        self.started = None
        self.stopped = False
        self.payloads = []
        self.timeouts = []
        self.alive = True
        self.lora_dir = None
        self.img_gen_error = None

    def is_alive(self):
        return self.alive and not self.stopped

    def start(
        self,
        files,
        *,
        vae_format = None,
        offload = None,
        native_speed = None,
        threads = None,
        extra_args = None,
        env = None,
    ):
        self.env = env
        self.started = dict(
            files = files,
            vae_format = vae_format,
            offload = offload,
            native_speed = native_speed,
            threads = threads,
            extra_args = list(extra_args or []),
        )

    def img_gen(
        self,
        payload,
        *,
        on_step = None,
        cancel_event = None,
        total_timeout = None,
    ):
        import io as _io

        self.payloads.append(payload)
        self.timeouts.append(total_timeout)
        if self.img_gen_error is not None:
            err, self.img_gen_error = self.img_gen_error, None
            self.alive = False
            raise err
        if on_step is not None:
            steps = payload.get("sample_params", {}).get("sample_steps", 0)
            on_step(f"  {steps}/{steps}")
        n = int(payload.get("batch_count", 1))
        blobs = []
        for i in range(n):
            buf = _io.BytesIO()
            Image.new("RGB", (1, 1), (i, i, i)).save(buf, format = "PNG")
            blobs.append(buf.getvalue())
        return blobs

    def stop(self):
        self.stopped = True


@pytest.mark.parametrize(
    "fam_name,expect_kinds",
    [
        # The T5-XXL is sharded: the index is the t5xxl input, its shards ride along as t5xxl_shard.
        ("flux.1", {"diffusion_model", "vae", "clip_l", "t5xxl", "t5xxl_shard"}),
        ("z-image", {"diffusion_model", "vae", "llm"}),
        ("qwen-image", {"diffusion_model", "vae", "qwen2vl"}),
        ("flux.2-klein", {"diffusion_model", "vae", "llm"}),
    ],
)
def test_asset_specs_cover_required_files(fam_name, expect_kinds):
    b = SdCppDiffusionBackend(engine = _FakeEngine())
    fam = detect_family(fam_name)
    specs = b._asset_specs("unsloth/x-GGUF", "x-Q4_K_M.gguf", fam)
    kinds = {kind for _, _, kind in specs}
    assert kinds == expect_kinds
    assert all(repo and fn for repo, fn, _ in specs)
    tr = [s for s in specs if s[2] == "diffusion_model"][0]
    assert tr[0] == "unsloth/x-GGUF" and tr[1] == "x-Q4_K_M.gguf"


@pytest.fixture(autouse = True)
def _plan_sees_an_empty_cache(monkeypatch):
    """Plan tests describe their cache state, so a developer's real one cannot drop an entry."""
    from core.inference.diffusion import DiffusionBackend
    monkeypatch.setattr(
        DiffusionBackend,
        "_hub_file_is_cached",
        staticmethod(lambda repo_id, filename, revision = None, expected_size = None, **kwargs: False),
    )


_Z_IMAGE_KIND_BYTES = {"diffusion_model": 4_000, "vae": 300, "llm": 8_000}


def _z_image_native_assets(monkeypatch, b):
    """kind -> (fetch repo, file) and (fetch repo, file) -> size for a z-image GGUF pick, read off the family table
    and the same fetch map the plan uses, so the test follows the table instead of naming its repos."""
    monkeypatch.setattr(
        "core.inference.diffusion_families._upstream_is_cached",
        lambda repo_id, files = None, **kwargs: False,
    )
    monkeypatch.delenv("UNSLOTH_DIFFUSION_NO_MIRROR", raising = False)
    specs = b._asset_specs(
        "unsloth/Z-Image-Turbo-GGUF", "z-image-turbo-Q4_K_M.gguf", detect_family("z-image")
    )
    fetch = bk._fetch_repo_map(specs, None)
    by_kind = {k: (fetch[r], f) for r, f, k in specs}
    assert set(by_kind) == set(_Z_IMAGE_KIND_BYTES)
    return by_kind, {by_kind[k]: n for k, n in _Z_IMAGE_KIND_BYTES.items()}


def test_download_plan_skips_assets_already_in_the_cache(monkeypatch):
    # _fetch_assets resolves either cache root, so staging a readable file re-downloads it for nothing.
    from core.inference.diffusion import DiffusionBackend

    b = SdCppDiffusionBackend(engine = _FakeEngine())
    by_kind, sizes = _z_image_native_assets(monkeypatch, b)
    monkeypatch.setattr(
        SdCppDiffusionBackend, "_plan_file_sizes", staticmethod(lambda by_repo, token: sizes)
    )
    cached = {"z-image-turbo-Q4_K_M.gguf"}

    monkeypatch.setattr(
        DiffusionBackend,
        "_hub_file_is_cached",
        staticmethod(
            lambda repo_id, filename, revision = None, expected_size = None, **kwargs: (
                filename in cached
            )
        ),
    )

    plan = b.download_plan(
        "unsloth/Z-Image-Turbo-GGUF",
        gguf_filename = "z-image-turbo-Q4_K_M.gguf",
        model_kind = "gguf",
    )
    cached.add(by_kind["vae"][1])
    warming = b.download_plan(
        "unsloth/Z-Image-Turbo-GGUF",
        gguf_filename = "z-image-turbo-Q4_K_M.gguf",
        model_kind = "gguf",
    )

    vae_repo, llm_repo = by_kind["vae"][0], by_kind["llm"][0]
    assert vae_repo != llm_repo  # the VAE and the encoder now come from separate repos
    assert [e["repo_id"] for e in plan["entries"]] == [vae_repo, llm_repo]
    # Once the VAE is cached its repo has nothing left to stage; the encoder entry is unchanged.
    assert [e["repo_id"] for e in warming["entries"]] == [llm_repo]
    assert plan["entries"][1]["files"] == warming["entries"][0]["files"]
    assert plan["total_bytes"] == 8_300
    assert warming["total_bytes"] == 8_000
    assert plan["required_bytes"] == 12_300
    assert plan["checkpoint_bytes"] == 4_000


def test_download_plan_does_not_label_same_repo_companions_as_checkpoint(monkeypatch):
    import core.inference.sd_cpp_backend as module
    from core.inference.diffusion import DiffusionBackend

    repo = "unsloth/Z-Image-Turbo-GGUF"
    checkpoint = "model-Q4_K_M.gguf"
    companion = "vae/ae.safetensors"
    backend = SdCppDiffusionBackend(engine = _FakeEngine())
    monkeypatch.setattr(
        backend,
        "_asset_specs",
        lambda *args, **kwargs: [
            (repo, checkpoint, "diffusion_model"),
            (repo, companion, "vae"),
        ],
    )
    monkeypatch.setattr(module, "_fetch_repo_map", lambda specs, token: {repo: repo})
    monkeypatch.setattr(backend, "_preflight_companion_repos", lambda *args, **kwargs: None)
    monkeypatch.setattr(
        backend,
        "_plan_file_sizes",
        lambda by_repo, token: {(repo, checkpoint): 4_000, (repo, companion): 300},
    )
    monkeypatch.setattr(
        DiffusionBackend,
        "_hub_file_is_loadable",
        staticmethod(lambda _repo, filename, *_args, **_kwargs: filename == checkpoint),
    )

    plan = backend.download_plan(repo, gguf_filename = checkpoint, model_kind = "gguf")

    assert plan["entries"][0]["bytes"] == 300
    assert plan["entries"][0]["checkpoint"] is False


def test_download_plan_restages_a_native_asset_a_stale_live_copy_shadows(monkeypatch):
    # reuse_other_cache_root switches only when the live lookup misses, so a stale live copy shadows.
    from core.inference.diffusion import DiffusionBackend

    shadowed = "split_files/vae/ae.safetensors"

    def probe(
        repo_id,
        filename,
        revision = None,
        expected_size = None,
        roots = None,
        **kwargs,
    ):
        asks_live = roots is not None and roots != (None,)
        if filename == shadowed:
            return expected_size is None if asks_live else True
        return True

    monkeypatch.setattr(DiffusionBackend, "_hub_file_is_cached", staticmethod(probe))

    assert not DiffusionBackend._hub_file_is_loadable("r", shadowed, None, 300)
    assert DiffusionBackend._hub_file_is_loadable("r", "other.safetensors", None, 300)


def test_download_plan_restages_a_native_asset_that_changed_size(monkeypatch):
    # Pass the declared size: a same-named republish is invisible from the ref alone.
    from core.inference.diffusion import DiffusionBackend

    b = SdCppDiffusionBackend(engine = _FakeEngine())
    seen = {}
    by_kind, sizes = _z_image_native_assets(monkeypatch, b)
    monkeypatch.setattr(
        SdCppDiffusionBackend, "_plan_file_sizes", staticmethod(lambda by_repo, token: sizes)
    )

    def probe(
        repo_id,
        filename,
        revision = None,
        expected_size = None,
        **kwargs,
    ):
        seen[filename] = expected_size
        return True

    monkeypatch.setattr(DiffusionBackend, "_hub_file_is_cached", staticmethod(probe))

    b.download_plan(
        "unsloth/Z-Image-Turbo-GGUF",
        gguf_filename = "z-image-turbo-Q4_K_M.gguf",
        model_kind = "gguf",
    )

    assert seen["z-image-turbo-Q4_K_M.gguf"] == 4_000
    assert seen[by_kind["vae"][1]] == 300
    assert seen[by_kind["llm"][1]] == 8_000
    assert all(size for size in seen.values()), "an unsized probe trusts the local ref alone"


def test_download_plan_is_empty_when_every_native_asset_is_cached(monkeypatch):
    from core.inference.diffusion import DiffusionBackend

    b = _shared_setup_4(monkeypatch)
    monkeypatch.setattr(
        DiffusionBackend,
        "_hub_file_is_cached",
        staticmethod(lambda repo_id, filename, revision = None, expected_size = None, **kwargs: True),
    )

    plan = b.download_plan(
        "unsloth/Z-Image-Turbo-GGUF",
        gguf_filename = "z-image-turbo-Q4_K_M.gguf",
        model_kind = "gguf",
    )

    assert plan["entries"] == [] and plan["total_bytes"] == 0


def test_download_plan_stages_exactly_what_sd_cli_opens(monkeypatch):
    b = SdCppDiffusionBackend(engine = _FakeEngine())
    by_kind, sizes = _z_image_native_assets(monkeypatch, b)
    monkeypatch.setattr(
        SdCppDiffusionBackend,
        "_plan_file_sizes",
        staticmethod(lambda by_repo, token: sizes),
    )

    plan = b.download_plan(
        "unsloth/Z-Image-Turbo-GGUF",
        gguf_filename = "z-image-turbo-Q4_K_M.gguf",
        model_kind = "gguf",
        transformer_quant = "int8",
        memory_mode = "low_vram",
    )

    expected = set(by_kind.values())  # every asset spec, under the repo the fetch pulls it from
    listed = {(e["repo_id"], f) for e in plan["entries"] for f in e["files"]}
    assert listed == expected
    assert plan["total_bytes"] == 12_300
    assert plan["required_bytes"] == 12_300
    assert plan["checkpoint_bytes"] == 4_000
    # The transformer entry is the only one carrying the GGUF filename; the VAE and the encoder get one entry each.
    tr = [e for e in plan["entries"] if e["gguf_filename"]]
    assert len(tr) == 1 and tr[0]["repo_id"] == "unsloth/Z-Image-Turbo-GGUF"
    for kind in ("vae", "llm"):
        assert len([e for e in plan["entries"] if e["repo_id"] == by_kind[kind][0]]) == 1, kind


def test_download_plan_merges_asset_repos_that_share_one_fetch_repo(monkeypatch):
    # Two upstream repos can resolve to one fetch repo; keying by it drops whichever landed first.
    import core.inference.sd_cpp_backend as S

    b = SdCppDiffusionBackend(engine = _FakeEngine())
    specs = [
        ("unsloth/FLUX.2-dev-GGUF", "flux2-dev-Q4_K_M.gguf", "transformer"),
        ("unsloth/example-vae-mirror", "vae/ae.safetensors", "vae"),
        ("unsloth/example-encoder-mirror", "text_encoders/mistral.safetensors", "text_encoder"),
    ]
    monkeypatch.setattr(SdCppDiffusionBackend, "_asset_specs", lambda *a, **k: specs)
    monkeypatch.setattr(
        S,
        "_fetch_repo_map",
        lambda assets, token: {
            "unsloth/FLUX.2-dev-GGUF": "unsloth/FLUX.2-dev-GGUF",
            "unsloth/example-vae-mirror": "some-org/example-repack",
            "unsloth/example-encoder-mirror": "some-org/example-repack",
        },
    )
    monkeypatch.setattr(SdCppDiffusionBackend, "_preflight_companion_repos", lambda *a, **k: None)
    sizes = {
        ("unsloth/FLUX.2-dev-GGUF", "flux2-dev-Q4_K_M.gguf"): 4_000,
        ("some-org/example-repack", "vae/ae.safetensors"): 300,
        ("some-org/example-repack", "text_encoders/mistral.safetensors"): 8_000,
    }
    monkeypatch.setattr(
        SdCppDiffusionBackend, "_plan_file_sizes", staticmethod(lambda by_repo, token: sizes)
    )
    from core.inference.diffusion import DiffusionBackend

    monkeypatch.setattr(
        DiffusionBackend,
        "_hub_file_is_loadable",
        staticmethod(lambda *a, **k: False),
    )

    plan = b.download_plan(
        "unsloth/FLUX.2-dev-GGUF", gguf_filename = "flux2-dev-Q4_K_M.gguf", model_kind = "gguf"
    )

    shared = next(e for e in plan["entries"] if e["repo_id"] == "some-org/example-repack")
    assert sorted(shared["files"]) == [
        "text_encoders/mistral.safetensors",
        "vae/ae.safetensors",
    ], "neither collapsed repo's files may be dropped"
    assert plan["required_bytes"] == 12_300


def test_download_plan_skips_a_local_transformer_but_still_stages_the_assets(monkeypatch, tmp_path):
    b = SdCppDiffusionBackend(engine = _FakeEngine())
    (tmp_path / "z-image-turbo-Q4_K_M.gguf").write_bytes(b"gguf")
    monkeypatch.setattr(
        SdCppDiffusionBackend, "_plan_file_sizes", staticmethod(lambda by_repo, token: {})
    )

    plan = b.download_plan(
        str(tmp_path), gguf_filename = "z-image-turbo-Q4_K_M.gguf", model_kind = "gguf"
    )

    by_kind, _sizes = _z_image_native_assets(monkeypatch, b)
    assert str(tmp_path) not in {e["repo_id"] for e in plan["entries"]}
    assert {e["repo_id"] for e in plan["entries"]} == {by_kind["vae"][0], by_kind["llm"][0]}
    # An unreadable size understates the total; it must never fail the plan.
    assert plan["total_bytes"] == 0


def _no_cache(monkeypatch):
    """Report every upstream as uncached, so a local cache cannot mask the mirror decision."""
    monkeypatch.setattr(
        "core.inference.diffusion_families._upstream_is_cached",
        lambda repo_id, files = None, **kwargs: False,
    )
    monkeypatch.delenv("UNSLOTH_DIFFUSION_NO_MIRROR", raising = False)


def test_download_plan_stages_the_mirrored_asset_repo(monkeypatch):
    """STAGED before the load runs, so a gated asset repo left here 401s an anonymous user and
    _fetch_assets' swap is never reached. FLUX.1's VAE lives in the gated FLUX.1-schnell."""
    _no_cache(monkeypatch)
    b = _shared_setup_4(monkeypatch)

    plan = b.download_plan(
        "unsloth/FLUX.1-dev-GGUF", gguf_filename = "flux1-dev-Q4_K_M.gguf", model_kind = "gguf"
    )

    staged = {e["repo_id"] for e in plan["entries"]}
    assert "unsloth/FLUX.1-schnell" in staged
    assert "black-forest-labs/FLUX.1-schnell" not in staged
    tr = [e for e in plan["entries"] if e["gguf_filename"]]
    assert len(tr) == 1 and tr[0]["repo_id"] == "unsloth/FLUX.1-dev-GGUF"


def test_download_plan_and_fetch_assets_pick_the_same_repo(monkeypatch, tmp_path):
    """Staging one repo and then downloading from the other is the failure this feature removes,
    so both sides take the decision from the same per-repo file list."""
    import json

    _no_cache(monkeypatch)
    b = _shared_setup_4(monkeypatch)
    pulled: list = []

    def fake_download(repo, fn, tok, **k):
        # Real files in one snapshot dir per repo: the load checks the T5-XXL index's shards sit beside it.
        pulled.append((repo, fn))
        path = tmp_path / repo.replace("/", "--") / fn
        path.parent.mkdir(parents = True, exist_ok = True)
        if fn.endswith(".safetensors.index.json"):
            shards = [f.rsplit("/", 1)[-1] for _r, f, kind in specs if kind == "t5xxl_shard"]
            path.write_text(json.dumps({"weight_map": {str(i): n for i, n in enumerate(shards)}}))
        else:
            path.write_bytes(b"x")
        return str(path)

    monkeypatch.setattr("utils.hf_xet_fallback.hf_hub_download_with_xet_fallback", fake_download)

    fam = detect_family("flux.1")
    specs = b._asset_specs("unsloth/FLUX.1-dev-GGUF", "flux1-dev-Q4_K_M.gguf", fam)
    b._fetch_assets(specs, None)
    plan = b.download_plan(
        "unsloth/FLUX.1-dev-GGUF", gguf_filename = "flux1-dev-Q4_K_M.gguf", model_kind = "gguf"
    )

    assert {(e["repo_id"], f) for e in plan["entries"] for f in e["files"]} == set(pulled)


def test_delete_guard_covers_the_mirrored_asset_repos(monkeypatch):
    """The bytes land under whichever of the pair was fetched, so guarding only the upstream leaves
    the mirror cache deletable under a one-shot sd-cli that re-reads it."""
    b = _loaded_backend("flux.1")
    ids = set(b.loaded_repo_ids())
    assert "black-forest-labs/FLUX.1-schnell" in ids
    assert "unsloth/FLUX.1-schnell" in ids

    b._state = None
    b._loading = bk._SdLoading(
        repo_id = "unsloth/FLUX.1-dev-GGUF",
        base_repo = "black-forest-labs/FLUX.1-dev",
        asset_repos = ("black-forest-labs/FLUX.1-schnell",),
    )
    loading = set(b.loading_repo_ids())
    assert {"black-forest-labs/FLUX.1-schnell", "unsloth/FLUX.1-schnell"} <= loading
    assert {"black-forest-labs/FLUX.1-dev", "unsloth/FLUX.1-dev"} <= loading


def test_download_plan_refuses_a_pick_native_cannot_serve():
    b = SdCppDiffusionBackend(engine = _FakeEngine())
    with pytest.raises(ValueError, match = "gguf_filename is required"):
        b.download_plan("unsloth/Z-Image-Turbo-GGUF", model_kind = "gguf")
    with pytest.raises(ValueError, match = "native sd.cpp asset mapping"):
        b.download_plan(
            "stabilityai/sdxl-turbo", gguf_filename = "sdxl-Q4_K_M.gguf", model_kind = "gguf"
        )


def test_asset_specs_flux2_klein_selects_encoder_by_variant():
    # FLUX.2-klein 4B pairs with Qwen3-4B, 9B with Qwen3-8B, so the encoder must come from the load identity, not the family default.
    b = SdCppDiffusionBackend(engine = _FakeEngine())
    fam = detect_family("flux.2-klein")

    specs_4b = b._asset_specs("unsloth/FLUX.2-klein-4B-GGUF", "FLUX.2-klein-4B-Q4_K_M.gguf", fam)
    te_4b = [(r, f) for r, f, k in specs_4b if k == "llm"]
    assert te_4b == [(r, f) for r, f, _k in fam.sd_cpp_text_encoders]
    assert te_4b[0][0] == "unsloth/Qwen3-4B-GGUF"

    specs_9b = b._asset_specs("unsloth/FLUX.2-klein-9B-GGUF", "FLUX.2-klein-9B-Q4_K_M.gguf", fam)
    te_9b = [(r, f) for r, f, k in specs_9b if k == "llm"]
    assert te_9b == [(r, f) for r, f, _k in _FLUX2_KLEIN_9B_SD_CPP_TEXT_ENCODERS]
    assert te_9b[0][0] == "unsloth/Qwen3-8B-GGUF"
    assert te_4b != te_9b


# Every community repack Unsloth depends on has a byte-identical unsloth mirror.
_REPACKER_ORGS = frozenset(
    {"comfy-org", "comfyanonymous", "quantstack", "city96", "calcuis", "orabazes"}
)


def test_no_sd_cpp_asset_comes_from_a_community_repack():
    from core.inference.diffusion_families import _FAMILIES

    offenders = []
    for fam in _FAMILIES:
        specs = list(fam.sd_cpp_text_encoders)
        if fam.sd_cpp_vae:
            specs.append((*fam.sd_cpp_vae, "vae"))
        specs.extend(_FLUX2_KLEIN_9B_SD_CPP_TEXT_ENCODERS)
        for repo, _f, _k in specs:
            if repo.split("/", 1)[0].lower() in _REPACKER_ORGS:
                offenders.append((fam.name, repo))
    assert offenders == []


def test_the_moved_sd_cpp_assets_keep_their_upstream_relative_paths():
    # Image sd-cli assets are upstream files at their upstream path on the mirror, or an unsloth
    # GGUF; a reorganised mirror would 404 sd-cli.
    from core.inference.diffusion_families import _FLUX1_SD_CPP_TEXT_ENCODERS, mirror_repo

    flux1 = [(r, f) for r, f, _k in _FLUX1_SD_CPP_TEXT_ENCODERS]
    assert flux1 == [
        ("black-forest-labs/FLUX.1-schnell", "text_encoder/model.safetensors"),
        ("black-forest-labs/FLUX.1-schnell", "text_encoder_2/model.safetensors.index.json"),
        ("black-forest-labs/FLUX.1-schnell", "text_encoder_2/model-00001-of-00002.safetensors"),
        ("black-forest-labs/FLUX.1-schnell", "text_encoder_2/model-00002-of-00002.safetensors"),
    ]
    assert [k for _r, _f, k in _FLUX1_SD_CPP_TEXT_ENCODERS] == [
        "clip_l",
        "t5xxl",
        "t5xxl_shard",
        "t5xxl_shard",
    ]
    for name in ("flux.1", "flux.1-kontext"):
        assert detect_family(name).sd_cpp_text_encoders == _FLUX1_SD_CPP_TEXT_ENCODERS, name
        assert detect_family(name).sd_cpp_vae == (
            "black-forest-labs/FLUX.1-schnell",
            "ae.safetensors",
        )
    # Klein 4B and Z-Image share one Qwen3-4B GGUF; FLUX.2-dev reads the Mistral-Small-3.2 GGUF.
    for name in ("flux.2-klein", "z-image"):
        [(repo, fn, kind)] = detect_family(name).sd_cpp_text_encoders
        assert (repo, kind) == ("unsloth/Qwen3-4B-GGUF", "llm"), name
        assert fn.startswith("Qwen3-4B-") and fn.endswith(".gguf"), name
    [(repo, fn, kind)] = detect_family("flux.2-dev").sd_cpp_text_encoders
    assert (repo, kind) == ("unsloth/Mistral-Small-3.2-24B-Instruct-2506-GGUF", "llm")
    assert fn.startswith("Mistral-Small-3.2-24B-Instruct-2506-") and fn.endswith(".gguf")

    for name in ("qwen-image", "qwen-image-edit"):
        assert detect_family(name).sd_cpp_vae == (
            "Qwen/Qwen-Image",
            "vae/diffusion_pytorch_model.safetensors",
        ), name
    # Z-Image decodes with the FLUX.1 autoencoder.
    assert detect_family("z-image").sd_cpp_vae == (
        "black-forest-labs/FLUX.1-schnell",
        "ae.safetensors",
    )
    for name in ("flux.2-klein", "flux.2-dev"):
        assert detect_family(name).sd_cpp_vae == (
            "black-forest-labs/FLUX.2-dev",
            "vae/diffusion_pytorch_model.safetensors",
        ), name
    # Each vendor VAE / encoder repo is reached through an unsloth mirror holding the same path.
    for upstream in (
        "black-forest-labs/FLUX.1-schnell",
        "black-forest-labs/FLUX.2-dev",
        "Qwen/Qwen-Image",
    ):
        assert (mirror_repo(upstream) or "").startswith("unsloth/"), upstream


def test_map_guidance_flux_uses_distilled_guidance():
    # cfg must be explicit: unset, sd.cpp applies its default 7.0 and FLUX.1 renders dark or burnt.
    assert _map_guidance(detect_family("flux.1"), 3.5) == (1.0, 3.5)
    assert _map_guidance(detect_family("flux.1"), 0.0) == (1.0, 0.0)
    assert _map_guidance(detect_family("flux.1-kontext"), 2.5) == (1.0, 2.5)
    assert _map_guidance(detect_family("flux.2-dev"), 4.0) == (1.0, 4.0)
    assert _map_guidance(detect_family("flux.1"), None) == (1.0, None)


def test_map_guidance_flux2_klein_distilled_off_base_real_cfg():
    assert _map_guidance(detect_family("flux.2-klein"), 1.0) == (1.0, None)
    assert _map_guidance(detect_family("flux.2-klein"), 5.0) == (5.0, None)
    assert _map_guidance(detect_family("flux.2-klein"), None) == (1.0, None)


_FLUX_DEFAULT_GUIDANCE_CASES = [
    ("unsloth/FLUX.1-dev-GGUF", "flux.1", 1.0, 3.5),
    ("unsloth/FLUX.1-schnell-GGUF", "flux.1", 1.0, 0.0),
    ("unsloth/FLUX.1-Kontext-dev-GGUF", "flux.1-kontext", 1.0, 2.5),
    ("unsloth/FLUX.2-dev-GGUF", "flux.2-dev", 1.0, 4.0),
    ("unsloth/FLUX.2-klein-4B-GGUF", "flux.2-klein", 1.0, None),
    ("unsloth/FLUX.2-klein-9B-GGUF", "flux.2-klein", 1.0, None),
    ("unsloth/FLUX.2-klein-base-4B-GGUF", "flux.2-klein", 5.0, None),
    ("unsloth/FLUX.2-klein-base-9B-GGUF", "flux.2-klein", 5.0, None),
]


def _edit_source(fam_name):
    """Kontext is edit-only on both engines: it renders from a source image, never from text alone."""
    if detect_family(fam_name).edit:
        import base64
        import io

        buf = io.BytesIO()
        Image.new("RGB", (512, 512), (10, 20, 30)).save(buf, format = "PNG")
        return {"init_image": base64.b64encode(buf.getvalue()).decode()}
    return {}


@pytest.mark.parametrize("repo_id,fam_name,cfg,distilled", _FLUX_DEFAULT_GUIDANCE_CASES)
def test_flux_oneshot_argv_sends_explicit_cfg(repo_id, fam_name, cfg, distilled):
    from core.inference.diffusion_families import default_generation_params
    from core.inference.sd_cpp_args import build_sd_cpp_command

    steps, guidance = default_generation_params(repo_id)
    eng = _FakeEngine()
    b = _loaded_backend(fam_name, engine = eng)
    b.generate(prompt = "a fox", steps = steps, guidance = guidance, seed = 1, **_edit_source(fam_name))
    files, params, out, _kw = eng.calls[-1]
    argv = build_sd_cpp_command("/bin/sd-cli", files, params, output_path = str(out))
    assert float(argv[argv.index("--cfg-scale") + 1]) == cfg
    if distilled is None:
        assert "--guidance" not in argv
    else:
        assert float(argv[argv.index("--guidance") + 1]) == distilled


@pytest.mark.parametrize("repo_id,fam_name,cfg,distilled", _FLUX_DEFAULT_GUIDANCE_CASES)
def test_flux_server_request_sends_txt_cfg(repo_id, fam_name, cfg, distilled):
    import dataclasses

    from core.inference.diffusion_families import default_generation_params

    steps, guidance = default_generation_params(repo_id)
    b = _loaded_backend(fam_name)
    server = _FakeServer("/bin/sd-server")
    b._state = dataclasses.replace(b._state, mode = "server", server = server)
    b.generate(prompt = "a fox", steps = steps, guidance = guidance, seed = 1, **_edit_source(fam_name))
    g = server.payloads[-1]["sample_params"]["guidance"]
    assert g["txt_cfg"] == cfg
    assert g.get("distilled_guidance") == distilled


def test_map_guidance_cfg_family_off_when_distilled():
    assert _map_guidance(detect_family("qwen-image"), 0.0) == (1.0, None)
    assert _map_guidance(detect_family("qwen-image"), 4.0) == (4.0, None)


def test_map_guidance_z_image_converts_diffusers_g_to_standard_cfg():
    # The shared default is diffusers' g = 3 (ComfyUI cfg 4); sd.cpp's standard CFG must get 4, Turbo's 0 stays off.
    assert _map_guidance(detect_family("Tongyi-MAI/Z-Image"), 3.0) == (4.0, None)
    assert _map_guidance(detect_family("Tongyi-MAI/Z-Image-Turbo"), 0.0) == (1.0, None)


def test_status_unloaded_reports_sd_cpp_engine():
    b = SdCppDiffusionBackend(engine = _FakeEngine())
    st = b.status()
    assert st["loaded"] is False and st["engine"] == "sd_cpp"


def test_status_loaded_shape():
    b = _loaded_backend()
    st = b.status()
    assert st["loaded"] is True
    assert st["engine"] == "sd_cpp"
    assert st["family"] == "z-image"
    assert st["device"] == "cpu"
    assert st["gguf_variant"] is None
    for k in ("transformer_quant", "attention_backend", "transformer_cache", "text_encoder_quant"):
        assert st[k] is None
    assert st["supports_lora"] is True and st["lora_unavailable_reason"] is None


def test_status_names_why_a_native_family_has_no_lora():
    st = _loaded_backend(fam_name = "qwen-image").status()
    assert st["supports_lora"] is False
    assert (
        st["lora_unavailable_reason"]
        == "The native sd.cpp engine cannot apply LoRAs to qwen-image."
    )


def test_generate_returns_images_and_seed():
    eng = _FakeEngine()
    b = _loaded_backend(engine = eng)
    out = b.generate(prompt = "a fox", width = 256, height = 256, steps = 8, seed = 123, batch_size = 2)
    assert out["seed"] == 123
    assert out["repo_id"] == "unsloth/Z-Image-Turbo-GGUF"
    assert len(out["images"]) == 2
    assert all(isinstance(im, Image.Image) for im in out["images"])
    assert len(eng.calls) == 2
    seeds = [params.seed for _, params, _, _ in eng.calls]
    assert seeds == [123, 124]
    assert out["seeds"] == [123, 124]


def test_generate_qwen_passes_sampling_args():
    eng = _FakeEngine()
    b = _loaded_backend(fam_name = "qwen-image", engine = eng)
    b.generate(prompt = "x", steps = 20, guidance = 4.0, seed = 1)
    _, params, _, kw = eng.calls[0]
    assert params.sampling_method == "euler"
    assert "--flow-shift" in (kw.get("extra_args") or [])


def test_generate_refuses_a_snapshot_naming_another_model():
    eng = _FakeEngine()
    b = _loaded_backend(engine = eng)
    st = b.status()
    loaded = bk.load_identity(st["repo_id"], st["base_repo"], st["family"])
    with pytest.raises(bk.DiffusionModelReplacedError) as replaced:
        stale = bk.load_identity("other/model", st["base_repo"], st["family"])
        b.generate(prompt = "stale", expected_load = stale)
    assert replaced.value.expected.repo_id == "other/model"
    assert replaced.value.actual == loaded
    assert eng.calls == []
    assert b.generate(prompt = "x", steps = 4, expected_load = loaded)
    assert b.generate(prompt = "x", steps = 4)


def test_generate_raises_when_not_loaded():
    b = SdCppDiffusionBackend(engine = _FakeEngine())
    with pytest.raises(RuntimeError, match = "No diffusion model is loaded"):
        b.generate(prompt = "x")


def test_generate_passes_vae_format_for_flux2():
    eng = _FakeEngine()
    b = _loaded_backend(fam_name = "flux.2-klein", engine = eng)
    b.generate(prompt = "x", steps = 4, seed = 1)
    _, _, _, kw = eng.calls[0]
    assert kw.get("extra_args") == ["--vae-format", "flux2"]


def test_oneshot_generate_refuses_a_binary_swapped_for_another_accelerator(monkeypatch):
    # The one-shot path re-resolves sd-cli per image; a build for another accelerator must be refused.
    import dataclasses

    b = _loaded_backend()
    b._state = dataclasses.replace(b._state, sd_accelerator = "cuda")
    monkeypatch.setattr(bk, "_installed_accelerator_of", lambda _binary: "cpu")
    with pytest.raises(RuntimeError, match = "different accelerator"):
        b.generate(prompt = "x", steps = 4, seed = 1)


def test_oneshot_generate_accepts_a_binary_for_the_same_accelerator(monkeypatch):
    # Control: the guard must not fire when the re-resolved binary is the committed build.
    import dataclasses

    eng = _FakeEngine()
    b = _loaded_backend(engine = eng)
    b._state = dataclasses.replace(b._state, sd_accelerator = "cuda")
    monkeypatch.setattr(bk, "_installed_accelerator_of", lambda _binary: "cuda")
    b.generate(prompt = "x", steps = 4, seed = 1)
    assert len(eng.calls) == 1


def test_generate_cancellation_raises_cancelled_not_failure():
    eng = _FakeEngine(cancel_on_call = True)
    b = _loaded_backend(engine = eng)
    with pytest.raises(RuntimeError, match = "cancelled"):
        b.generate(prompt = "x", steps = 8, seed = 5)


def test_cancel_generate_stops_a_running_native_run():
    started = threading.Event()
    b = None

    class _BlockingEngine(_FakeEngine):
        def generate(
            self,
            files,
            params,
            *,
            output_path,
            cancel_event = None,
            **kw,
        ):
            started.set()
            assert cancel_event is not None and cancel_event.wait(5)
            raise SdCppCancelled("cancelled")

    b = _loaded_backend(engine = _BlockingEngine())
    assert b.cancel_generate() is False

    outcome: dict = {}

    def _run():
        try:
            b.generate(prompt = "x", steps = 8, seed = 5)
        except BaseException as exc:  # noqa: BLE001 -- the assertion below pins the type
            outcome["error"] = exc

    worker = threading.Thread(target = _run, daemon = True)
    worker.start()
    assert started.wait(5)

    assert b.cancel_generate() is True
    worker.join(10)
    assert isinstance(outcome["error"], RuntimeError)
    assert b.cancel_generate() is False


def test_cancel_generate_is_a_no_op_when_idle():
    assert SdCppDiffusionBackend(engine = _FakeEngine()).cancel_generate() is False


def test_generate_progress_tracks_parsed_steps():
    b = _loaded_backend()
    b._gen = bk._SdGen(total_steps = 8)
    b._on_log("  sampling 4/8 done")
    p = b.generate_progress()
    assert p["active"] is True and p["step"] == 4 and p["total_steps"] == 8
    b._on_log("loaded 1/3 tensors")
    assert b.generate_progress()["step"] == 4


def test_generate_publishes_progress_before_lora_resolution(monkeypatch):
    # LoRA resolution runs during pre-generate setup while _generate_lock is held, so a progress probe then must read ACTIVE.
    from core.inference import diffusion_lora

    eng = _FakeEngine()
    b = _loaded_backend(engine = eng)
    monkeypatch.setattr(diffusion_lora, "supports_lora", lambda **_k: True)

    seen: dict = {}

    def _resolve(
        active,
        *,
        family = None,
        hf_token = None,
        cancel_event = None,
    ):
        seen["progress"] = b.generate_progress()
        return []

    monkeypatch.setattr(diffusion_lora, "resolve_specs", _resolve)

    out = b.generate(prompt = "a fox", width = 256, height = 256, steps = 8, loras = [("some/lora", 1.0)])
    assert out["images"]
    assert seen["progress"]["active"] is True
    assert seen["progress"]["total_steps"] == 8


def test_begin_load_rejects_unsupported_family(monkeypatch):
    b = SdCppDiffusionBackend(engine = _FakeEngine())
    monkeypatch.setattr(bk, "family_sd_cpp_supported", lambda fam: False)
    with pytest.raises(ValueError, match = "no native sd.cpp asset mapping"):
        b.begin_load("unsloth/Z-Image-Turbo-GGUF", gguf_filename = "z.gguf")


def test_begin_load_requires_gguf_filename():
    b = SdCppDiffusionBackend(engine = _FakeEngine())
    with pytest.raises(ValueError, match = "gguf_filename is required"):
        b.begin_load("unsloth/Z-Image-Turbo-GGUF")


def test_begin_load_resolves_family_from_filename_only(monkeypatch):
    b = SdCppDiffusionBackend(engine = _FakeEngine())
    monkeypatch.setattr(b, "_run_load", lambda **kwargs: None)
    b.begin_load("/models/gguf-store", gguf_filename = "Z-Image-Turbo-Q4_K_M.gguf")
    assert b._loading is not None and b._loading.repo_id == "/models/gguf-store"


def test_each_load_owns_its_cancel_event(monkeypatch):
    # A fresh Event per load: clearing one shared event would un-cancel the superseded worker.
    b = SdCppDiffusionBackend(engine = _FakeEngine())
    started = threading.Event()
    seen: list[threading.Event] = []

    def _capture(**kwargs):
        seen.append(kwargs["_cancel_event"])
        started.set()

    monkeypatch.setattr(b, "_run_load", _capture)

    b.begin_load("unsloth/Z-Image-Turbo-GGUF", gguf_filename = "z.gguf")
    assert started.wait(5)
    first = seen[0]
    b.unload()
    assert first.is_set()

    started.clear()
    b.begin_load("unsloth/Z-Image-Turbo-GGUF", gguf_filename = "z.gguf")
    assert started.wait(5)
    second = seen[1]
    assert second is not first, "each load needs its own event, not a clear() of the shared one"
    assert not second.is_set()
    assert first.is_set(), "the superseded worker's event must stay set"
    with pytest.raises(SdCppCancelled):
        b._fetch_assets(
            [("unsloth/Z-Image-Turbo-GGUF", "z.gguf", "diffusion_model")],
            None,
            cancel_event = first,
        )


def test_ensure_binary_returns_found(monkeypatch):
    monkeypatch.setattr(bk, "find_sd_cpp_binary", lambda: "/usr/bin/sd-cli")
    assert ensure_sd_cpp_binary() == "/usr/bin/sd-cli"


def test_ensure_binary_install_disabled_returns_none(monkeypatch):
    monkeypatch.setattr(bk, "find_sd_cpp_binary", lambda: None)
    assert ensure_sd_cpp_binary(allow_install = False) is None


# Only the H3-only --ref-video separates a pre-H3 build from an H3 one.
_PRE_H3_HELP = (
    # The banner separates a pre-H3 sd.cpp build from a program that is not sd.cpp.
    "stable-diffusion.cpp version unknown, commit unknown\n"
    "  -M, --mode                    run mode, one of [img_gen, vid_gen, upscale, convert]\n"
    "  --audio-vae <string>          path to standalone LTX audio vae model\n"
)
_H3_HELP = _PRE_H3_HELP + (
    "  --ref-video                   MiniMax-H3 Ref2VA reference video frame directory at 24 fps\n"
)


def test_h3_binary_gate_replaces_a_stale_managed_install(monkeypatch, tmp_path):
    stale = tmp_path / "stale" / "sd-cli"
    fresh = tmp_path / "fresh" / "sd-cli"
    for p in (stale, fresh):
        p.parent.mkdir()
        p.write_text("binary")
    found = [str(stale), str(fresh)]

    monkeypatch.setattr(bk, "ensure_sd_cpp_binary", lambda **_kwargs: found.pop(0))
    monkeypatch.setattr(bk, "is_managed_binary", lambda _b: True)
    monkeypatch.setattr(
        bk,
        "_sd_cpp_probe_output",
        lambda binary, *_args: _H3_HELP if binary == str(fresh) else _PRE_H3_HELP,
    )

    assert bk.ensure_h3_sd_cpp_binary() == str(fresh)
    assert not stale.exists()


def test_h3_binary_gate_defers_while_a_generation_holds_the_tree(monkeypatch, tmp_path):
    # Dropping the stale copy writes to the managed tree, so it takes install admission.
    stale = tmp_path / "stale" / "sd-cli"
    stale.parent.mkdir()
    stale.write_text("binary")
    ensures: list[bool] = []

    monkeypatch.setattr(
        bk,
        "ensure_sd_cpp_binary",
        lambda **kwargs: (ensures.append(kwargs.get("allow_install", True)), str(stale))[1],
    )
    monkeypatch.setattr(bk, "is_managed_binary", lambda _b: True)
    monkeypatch.setattr(bk, "_sd_cpp_probe_output", lambda *_args: _PRE_H3_HELP)
    monkeypatch.setattr(bk, "_sd_cpp_backend", None)

    with bk._tree_reader(str(stale)):
        assert bk.ensure_h3_sd_cpp_binary() is None
    assert stale.exists()
    assert ensures == [True]


def test_h3_binary_gate_refuses_but_keeps_a_user_supplied_build(monkeypatch, tmp_path):
    # The user's own build is not ours to delete, so the load fails naming the binary.
    own = tmp_path / "sd-cli"
    own.write_text("binary")
    excinfo = _shared_setup_3(monkeypatch, own)
    assert own.exists()
    # PATH discovery can hand this /usr/bin/sd, so the message must not say "remove".
    assert "remove" not in str(excinfo.value)
    assert str(own) in str(excinfo.value)


def test_h3_binary_gate_offers_to_clear_an_unmarked_install_directory(monkeypatch, tmp_path):
    root = tmp_path / "studio" / "stable-diffusion.cpp"
    own = root / "sd-cli"
    root.mkdir(parents = True)
    own.write_text("binary")
    monkeypatch.setattr(bk, "managed_install_root", lambda: root)
    excinfo = _shared_setup_3(monkeypatch, own)
    assert f"move {root} aside" in str(excinfo.value)
    assert "remove" not in str(excinfo.value)
    assert own.exists()


def test_h3_binary_gate_never_offers_to_delete_the_in_tree_developer_build(monkeypatch, tmp_path):
    # <repo_root>/stable-diffusion.cpp may be the user's git clone, so deletion is never offered.
    root = tmp_path / "repo" / "stable-diffusion.cpp"
    own = root / "build" / "bin" / "sd-cli"
    own.parent.mkdir(parents = True)
    own.write_text("binary")
    # raising=False: the hint does not import it; the patch makes this a regression guard.
    monkeypatch.setattr(bk, "in_tree_install_root", lambda: root, raising = False)
    excinfo = _shared_setup_3(monkeypatch, own)
    assert "remove" not in str(excinfo.value)
    assert own.exists()


def test_h3_binary_gate_logs_the_real_fault_for_a_managed_non_sd_cpp_binary(
    monkeypatch, tmp_path, capsys
):
    own = tmp_path / "sd-cli"
    own.write_text("binary")
    monkeypatch.setattr(bk, "ensure_sd_cpp_binary", lambda **_kwargs: str(own))
    monkeypatch.setattr(bk, "is_managed_binary", lambda _b: True)
    monkeypatch.setattr(bk, "_sd_cpp_probe_output", lambda *_args: "sd 1.0.0\nFind & replace CLI\n")

    assert bk.ensure_h3_sd_cpp_binary(allow_install = False) is None
    # capsys, not caplog: the backend logs through structlog, which writes to stdout.
    logged = capsys.readouterr().out
    assert "is not stable-diffusion.cpp" in logged
    assert "MiniMax-H3" not in logged
    assert own.exists()


def test_h3_binary_gate_names_a_binary_that_is_not_sd_cpp_at_all(monkeypatch, tmp_path):
    # #8507: SD_CLI_PATH pointed at Debian's `sd` find-and-replace tool; identity is not capability.
    own = tmp_path / "sd"
    own.write_text("binary")
    monkeypatch.setattr(bk, "ensure_sd_cpp_binary", lambda **_kwargs: str(own))
    monkeypatch.setattr(bk, "is_managed_binary", lambda _b: False)
    monkeypatch.setattr(
        bk,
        "_sd_cpp_probe_output",
        lambda *_args: "sd 1.0.0\nFind & replace CLI\n\nUSAGE:\n    sd <find> <replace-with>\n",
    )

    with pytest.raises(RuntimeError, match = "is not stable-diffusion.cpp"):
        bk.ensure_h3_sd_cpp_binary()
    assert own.exists()


def test_h3_binary_gate_requires_identity_not_just_the_h3_marker(monkeypatch, tmp_path):
    # --ref-video alone is not a signature: unrelated tools expose it too.
    own = tmp_path / "reference-video-cli"
    own.write_text("binary")
    monkeypatch.setattr(bk, "ensure_sd_cpp_binary", lambda **_kwargs: str(own))
    monkeypatch.setattr(bk, "is_managed_binary", lambda _b: False)
    monkeypatch.setattr(
        bk,
        "_sd_cpp_probe_output",
        lambda *_args: "reference-video-cli 2.1\n  --ref-video PATH   reference clip\n",
    )

    with pytest.raises(RuntimeError, match = "is not stable-diffusion.cpp"):
        bk.ensure_h3_sd_cpp_binary()


def test_h3_binary_gate_probes_help_once_for_both_questions(monkeypatch, tmp_path):
    # Identity is read off the capability probe's output; a second spawn could read another build.
    own = tmp_path / "sd-cli"
    own.write_text("binary")
    calls: list[tuple] = []

    def _probe(binary, *args):
        calls.append((binary, args))
        return "sd 1.0.0\nFind & replace CLI\n"

    monkeypatch.setattr(bk, "ensure_sd_cpp_binary", lambda **_kwargs: str(own))
    monkeypatch.setattr(bk, "is_managed_binary", lambda _b: False)
    monkeypatch.setattr(bk, "_sd_cpp_probe_output", _probe)

    with pytest.raises(RuntimeError, match = "is not stable-diffusion.cpp"):
        bk.ensure_h3_sd_cpp_binary()
    assert [args for _b, args in calls] == [("--help",)]


def test_h3_binary_gate_keeps_a_binary_it_cannot_probe(monkeypatch):
    # An unreadable --help is "cannot tell", not "no H3".
    monkeypatch.setattr(bk, "ensure_sd_cpp_binary", lambda **_kwargs: "/usr/bin/sd-cli")
    monkeypatch.setattr(bk, "_sd_cpp_probe_output", lambda *_args: None)
    assert bk.ensure_h3_sd_cpp_binary() == "/usr/bin/sd-cli"


def test_lists_accelerator_device_reads_the_ggml_device_list(monkeypatch):
    # --list-devices is the only way to tell a reused CPU prebuilt from an accelerator build after
    # the fact: the finder returns whichever binary is installed, whatever accelerator was asked for.
    monkeypatch.setattr(bk, "_sd_cpp_probe_output", lambda *_a: "CPU\tIntel(R) Xeon(R) Platinum\n")
    assert bk.sd_cpp_lists_accelerator_device("/existing/sd-cli") is False

    monkeypatch.setattr(
        bk,
        "_sd_cpp_probe_output",
        lambda *_a: "CUDA0\tNVIDIA GeForce RTX 4090\nCPU\tIntel(R) Xeon(R) Platinum\n",
    )
    assert bk.sd_cpp_lists_accelerator_device("/existing/sd-cli") is True

    monkeypatch.setattr(bk, "_sd_cpp_probe_output", lambda *_a: None)
    assert bk.sd_cpp_lists_accelerator_device("/existing/sd-cli") is True
    assert bk.sd_cpp_lists_accelerator_device(None) is False


def test_graph_cut_options_support_legacy_and_current_builds_and_fail_closed(monkeypatch):
    # unknown flags fail closed because sd-cli rejects them.
    monkeypatch.setattr(
        bk,
        "_sd_cpp_probe_output",
        lambda *_a: "  --max-vram         budget\n  --stream-layers    residency\n",
    )
    assert bk.sd_cpp_graph_cut_options("/existing/sd-cli") == {"--max-vram", "--stream-layers"}

    # current builds stream automatically and reject the removed --stream-layers flag.
    monkeypatch.setattr(bk, "_sd_cpp_probe_output", lambda *_a: "  --max-vram budget\n")
    assert bk.sd_cpp_graph_cut_options("/existing/sd-cli") == {"--max-vram"}

    # --stream-layers requires --max-vram, so a partial advertisement emits neither.
    monkeypatch.setattr(bk, "_sd_cpp_probe_output", lambda *_a: "  --stream-layers    residency\n")
    assert bk.sd_cpp_graph_cut_options("/existing/sd-cli") == frozenset()

    monkeypatch.setattr(bk, "_sd_cpp_probe_output", lambda *_a: _PRE_H3_HELP)
    assert bk.sd_cpp_graph_cut_options("/existing/sd-cli") == frozenset()

    monkeypatch.setattr(bk, "_sd_cpp_probe_output", lambda *_a: None)
    assert bk.sd_cpp_graph_cut_options("/existing/sd-cli") == frozenset()
    assert bk.sd_cpp_graph_cut_options(None) == frozenset()


def test_vulkan_uma_reads_ggml_vulkans_own_device_line(monkeypatch):
    listing = (
        "ggml_vulkan: Found 2 Vulkan devices:\n"
        "ggml_vulkan: 0 = AMD Radeon RX 7900 XTX (RADV NAVI31) (radv) | uma: 0 | fp16: 1 | bf16: 0 |\n"
        "ggml_vulkan: 1 = AMD Radeon Graphics (RADV RAPHAEL_MENDOCINO) (radv) | uma: 1 | fp16: 1 | bf16: 0 |\n"
        "Vulkan0\tAMD Radeon RX 7900 XTX (RADV NAVI31)\nVulkan1\tAMD Radeon Graphics\nCPU\tAMD Ryzen 9 9900X\n"
    )
    monkeypatch.setattr(bk, "_LAST_DEVICE_LISTING", {})
    monkeypatch.setattr(bk, "_sd_cpp_probe_output", lambda *_a: listing)
    assert bk.sd_cpp_vulkan_device_is_uma("/existing/sd-cli", None) is False
    assert bk.sd_cpp_vulkan_device_is_uma("/existing/sd-cli", "Vulkan1") is True
    assert bk.sd_cpp_vulkan_device_is_uma("/existing/sd-cli", "Vulkan2") is None
    assert bk.sd_cpp_vulkan_device_is_uma("/existing/sd-cli", "ROCm0") is None
    monkeypatch.setattr(bk, "_sd_cpp_probe_output", lambda *_a: "Vulkan0\tAMD Radeon\n")
    assert bk.sd_cpp_vulkan_device_is_uma("/existing/sd-cli", None) is None
    assert bk.sd_cpp_vulkan_device_is_uma(None, None) is None


def test_device_name_for_ordinal_reads_the_ggml_device_list(monkeypatch):
    monkeypatch.setattr(
        bk,
        "_sd_cpp_probe_output",
        lambda *_a: "CUDA0\tRTX 4070 Ti\nCUDA1\tRTX 5060 Ti\nCPU\tAMD Ryzen 9\n",
    )
    assert bk.sd_cpp_device_name_for_ordinal("/existing/sd-cli", 1) == "CUDA1"
    assert bk.sd_cpp_device_name_for_ordinal("/existing/sd-cli", 0) == "CUDA0"
    assert bk.sd_cpp_device_name_for_ordinal("/existing/sd-cli", 3) is None
    assert bk.sd_cpp_device_name_for_ordinal("/existing/sd-cli", None) is None
    assert bk.sd_cpp_device_name_for_ordinal(None, 1) is None

    monkeypatch.setattr(bk, "_sd_cpp_probe_output", lambda *_a: "ROCm1\tRadeon RX 7900\n")
    assert bk.sd_cpp_device_name_for_ordinal("/existing/sd-cli", 1) == "ROCm1"

    # Vulkan ordinals are another namespace, so they never match: pinning one would name a card the user did not choose.
    monkeypatch.setattr(bk, "_sd_cpp_probe_output", lambda *_a: "Vulkan1\tRTX 5060 Ti\n")
    assert bk.sd_cpp_device_name_for_ordinal("/existing/sd-cli", 1) is None

    monkeypatch.setattr(bk, "_sd_cpp_probe_output", lambda *_a: None)
    assert bk.sd_cpp_device_name_for_ordinal("/existing/sd-cli", 1) is None


def test_offload_device_pin_is_probed_against_the_binary_it_is_given(monkeypatch):
    # A deferred install swaps the build after the offload policy, so probe the binary given.
    seen: list = []

    def _probe(binary, *_args):
        seen.append(binary)
        return "CUDA0\tA\nCUDA1\tB\n" if binary == "/new/sd-cli" else "CPU\tRyzen\n"

    monkeypatch.setattr(bk, "_sd_cpp_probe_output", _probe)
    monkeypatch.setattr(bk, "physical_card_name", lambda ordinal: (None, None))
    base = ["--offload-to-cpu"]
    assert bk._offload_with_device_pin_impl(base, "/old/sd-cli", 1) == base
    assert bk._offload_with_device_pin_impl(base, "/new/sd-cli", 1) == [
        "--offload-to-cpu",
        "--backend",
        "diffusion=CUDA1,te=CUDA1,vae=CUDA1",
    ]
    assert seen == ["/old/sd-cli", "/new/sd-cli"]
    seen.clear()
    assert bk._offload_with_device_pin_impl(base, "/new/sd-cli", None) == base
    assert seen == []


def test_unload_clears_state_and_signals_cancel():
    cancel = threading.Event()
    b = _loaded_backend()
    b._active_generate_cancel = cancel
    st = b.unload()
    assert st["loaded"] is False
    assert cancel.is_set()
    assert b._cancel_event.is_set()


def test_status_reports_offload_when_flags_active():
    b = _loaded_backend()
    assert b.status()["offload_policy"] == "none" and b.status()["cpu_offload"] is False
    s = b._state
    b._state = bk._SdState(
        repo_id = s.repo_id,
        base_repo = s.base_repo,
        family = s.family,
        device = "cuda",
        files = s.files,
        offload_flags = ("--vae-on-cpu", "--clip-on-cpu"),
    )
    st = b.status()
    assert st["cpu_offload"] is True and st["offload_policy"] == "active"


def test_run_load_cancels_and_waits_for_inflight_generation(monkeypatch):
    # _run_load must cancel an in-flight generation and wait on _generate_lock before committing.
    b = SdCppDiffusionBackend(engine = _FakeEngine())
    fam = detect_family("z-image")
    monkeypatch.setattr(b, "_asset_specs", lambda *a, **k: [])
    monkeypatch.setattr(b, "_set_expected_bytes", lambda *a, **k: None)
    monkeypatch.setattr(
        b,
        "_fetch_assets",
        lambda *a, **k: {"diffusion_model": "/m/z.gguf", "vae": "/m/vae.sft", "llm": "/m/llm.sft"},
    )
    # Avoid importing torch from the worker thread (its first import deadlocks off the main thread); the device only needs to be CPU.
    monkeypatch.setattr(
        bk, "resolve_diffusion_device_target", lambda: types.SimpleNamespace(device = "cpu")
    )

    b._load_token = 5
    cancel = threading.Event()
    b._active_generate_cancel = cancel

    committed = threading.Event()

    def _load():
        b._run_load(
            repo_id = "unsloth/Z-Image-Turbo-GGUF",
            gguf_filename = "z.gguf",
            base = fam.base_repo,
            fam = fam,
            hf_token = None,
            _load_token = 5,
        )
        committed.set()

    b._generate_lock.acquire()
    try:
        threading.Thread(target = _load, daemon = True).start()
        assert not committed.wait(0.5)
        assert b._state is None
        assert cancel.is_set()
    finally:
        b._generate_lock.release()
    assert committed.wait(5)
    assert b._state is not None and b._state.repo_id == "unsloth/Z-Image-Turbo-GGUF"


def test_resolve_backend_prefers_server(monkeypatch):
    b = SdCppDiffusionBackend()
    monkeypatch.setattr(bk, "find_sd_server_binary", lambda: "/x/sd-server")
    mode, binary, engine = b._resolve_backend()
    assert mode == "server" and binary == "/x/sd-server" and engine is None


def test_resolve_backend_injected_engine_forces_oneshot():
    b = SdCppDiffusionBackend(engine = _FakeEngine())
    mode, binary, engine = b._resolve_backend()
    assert mode == "oneshot" and binary is None and engine is not None


def test_resolve_backend_falls_back_to_oneshot_without_server(monkeypatch):
    b = SdCppDiffusionBackend()
    monkeypatch.setattr(bk, "find_sd_server_binary", lambda: None)
    monkeypatch.setattr(bk, "_install_allowed", lambda: False)
    monkeypatch.setattr(bk, "find_sd_cpp_binary", lambda: "/usr/bin/sd-cli")
    mode, binary, engine = b._resolve_backend()
    assert mode == "oneshot" and engine is not None


def test_resolve_backend_cached_fallback_engine_does_not_pin_oneshot(monkeypatch):
    # A lazily cached fallback engine (NOT an explicit injection) must not force one-shot: a later load can use a server again.
    b = SdCppDiffusionBackend()
    b._engine = _FakeEngine()
    monkeypatch.setattr(bk, "find_sd_server_binary", lambda: "/x/sd-server")
    mode, binary, engine = b._resolve_backend()
    assert mode == "server" and binary == "/x/sd-server" and engine is None


def _run_server_load(
    monkeypatch,
    b,
    servers,
    fam_name = "z-image",
    device = "cpu",
    gguf_filename = "z.gguf",
    family_override = None,
    gpu_ordinal = None,
    asset_paths = None,
):
    fam = detect_family(fam_name)
    monkeypatch.setattr(bk, "find_sd_server_binary", lambda: "/x/sd-server")
    monkeypatch.setattr(bk, "_server_binary_runnable", lambda *_a, **_k: True)

    def _factory(binary):
        s = _FakeServer(binary)
        servers.append(s)
        return s

    monkeypatch.setattr(bk, "SdCppServer", _factory)
    monkeypatch.setattr(b, "_asset_specs", lambda *a, **k: [])
    monkeypatch.setattr(b, "_set_expected_bytes", lambda *a, **k: None)
    monkeypatch.setattr(
        b,
        "_fetch_assets",
        lambda *a, **k: dict(
            asset_paths
            or {"diffusion_model": "/m/z.gguf", "vae": "/m/vae.sft", "llm": "/m/llm.sft"}
        ),
    )
    monkeypatch.setattr(
        bk, "resolve_diffusion_device_target", lambda: types.SimpleNamespace(device = device)
    )
    b._load_token = 1
    b._run_load(
        repo_id = "unsloth/Z-Image-Turbo-GGUF",
        gguf_filename = gguf_filename,
        base = fam.base_repo,
        fam = fam,
        family_override = family_override,
        hf_token = None,
        _load_token = 1,
        gpu_ordinal = gpu_ordinal,
    )


def test_paravirtual_mac_load_records_the_cpu_device(monkeypatch):
    # The command builders force --backend cpu on a paravirtual Metal GPU, so state/status must say cpu, not mps.
    import core.inference.sd_cpp_args as sd_cpp_args

    monkeypatch.setattr(sd_cpp_args, "metal_is_paravirtual", lambda: True)
    b = SdCppDiffusionBackend()
    servers: list = []
    _run_server_load(monkeypatch, b, servers, device = "mps")
    assert b._state.device == "cpu" and b.status()["device"] == "cpu"
    # A CPU-backend abort is then not retried as a GPU-placement problem.
    assert (
        b._restart_server_on_cpu_backend(
            b._state, "unsupported op 'MUL_MAT' ggml_abort", threading.Event()
        )
        is None
    )

    monkeypatch.setattr(sd_cpp_args, "metal_is_paravirtual", lambda: False)
    b = SdCppDiffusionBackend()
    _run_server_load(monkeypatch, b, [], device = "mps")
    assert b._state.device == "mps"


@pytest.mark.parametrize("accelerator", ["vulkan", "auto"])
def test_cpu_torch_on_the_vulkan_build_offloads_by_default(monkeypatch, accelerator):
    # #13666: the card's VRAM was never measured, so auto streams weights instead of assuming they fit.
    monkeypatch.setattr(bk, "_installed_accelerator_of", lambda binary: accelerator)
    b = SdCppDiffusionBackend()
    _run_server_load(monkeypatch, b, [], device = "cpu")
    if accelerator == "vulkan":
        assert b._state.device == "vulkan"
        assert "--offload-to-cpu" in b._state.offload_flags
    else:
        assert b._state.device == "cpu"
        assert b._state.offload_flags == ()


@pytest.mark.parametrize("lands", [True, False])
def test_cpu_torch_placement_follows_a_deferred_vulkan_install(monkeypatch, lands):
    # The deferred upgrade may land the Vulkan build or keep the resident CPU one; place for what runs.
    installed = {"accelerator": "cpu"}
    monkeypatch.setattr(bk, "_installed_accelerator_of", lambda binary: installed["accelerator"])

    def _upgrade(self, server_binary, **_kw):
        if lands:
            installed["accelerator"] = "vulkan"
        return server_binary

    monkeypatch.setattr(SdCppDiffusionBackend, "_upgraded_or_refused", _upgrade)
    monkeypatch.setattr(
        SdCppDiffusionBackend, "_resolved_accelerator", staticmethod(lambda card = None: "vulkan")
    )
    monkeypatch.setattr(bk, "_managed_tree_in_use", lambda: True)  # a resident server defers it
    b = SdCppDiffusionBackend()
    _run_server_load(monkeypatch, b, [], device = "cpu")
    assert b._state.device == ("vulkan" if lands else "cpu")
    assert ("--offload-to-cpu" in b._state.offload_flags) is lands


@pytest.mark.parametrize("listed,expected", [("vulkan", "vulkan"), (None, "cpu")])
def test_an_unowned_build_on_cpu_torch_places_by_its_device_listing(monkeypatch, listed, expected):
    # SD_SERVER_PATH builds carry no install record; their --list-devices says what they render on.
    monkeypatch.setattr(bk, "_installed_accelerator_of", lambda binary: None)
    monkeypatch.setattr(bk, "sd_cpp_listed_device", lambda binary, *a, **k: (listed, None))
    monkeypatch.setattr(
        SdCppDiffusionBackend, "_resolved_accelerator", staticmethod(lambda card = None: "vulkan")
    )
    b = SdCppDiffusionBackend()
    _run_server_load(monkeypatch, b, [], device = "cpu")
    assert b._state.device == expected


@pytest.mark.parametrize("device,expected", [("cuda", "cpu"), ("xpu", "cpu"), ("mps", "mps")])
def test_the_cpu_build_on_a_gpu_torch_places_on_cpu(monkeypatch, device, expected):
    # CUDA or XPU torch can land on the CPU build; macOS is recorded cpu but renders on Metal.
    monkeypatch.setattr(bk, "_installed_accelerator_of", lambda binary: "cpu")
    b = SdCppDiffusionBackend()
    _run_server_load(monkeypatch, b, [], device = device)
    assert b._state.device == expected
    if expected == "cpu":
        assert b._state.offload_flags == ()


def test_server_load_spawns_once_and_status_reports_mode(monkeypatch):
    b = SdCppDiffusionBackend()
    servers: list = []
    _run_server_load(monkeypatch, b, servers)
    assert len(servers) == 1
    assert servers[0].started is not None
    assert b._state is not None and b._state.mode == "server" and b._state.server is servers[0]
    assert b.status()["native_mode"] == "server"


def test_server_status_preserves_explicit_family_provenance(monkeypatch):
    b = SdCppDiffusionBackend()
    servers: list = []
    _run_server_load(monkeypatch, b, servers, family_override = "z-image")

    family = b.status()["resolved"]["family_override"]
    assert (family["value"], family["requested"], family["source"]) == ("z-image",) * 2 + (
        "explicit",
    )
    assert (family["status"], family["reason"]) == ("applied", "requested")


def test_server_status_reports_selected_gguf_quant(monkeypatch):
    b = SdCppDiffusionBackend()
    servers: list = []
    _run_server_load(monkeypatch, b, servers, gguf_filename = "z-image-turbo-Q8_0.gguf")
    assert b.status()["gguf_variant"] == "Q8_0"


def test_server_generate_uses_one_request_for_whole_batch(monkeypatch):
    b = SdCppDiffusionBackend()
    servers: list = []
    _run_server_load(monkeypatch, b, servers)
    out = b.generate(prompt = "a fox", width = 256, height = 256, steps = 8, seed = 7, batch_size = 3)
    assert len(out["images"]) == 3
    assert all(isinstance(im, Image.Image) for im in out["images"])
    assert len(servers[0].payloads) == 1
    assert servers[0].payloads[0]["batch_count"] == 3
    assert out["seed"] == 7 and out["seeds"] == [7, 8, 9]
    assert b._gen is None


_GGML_ABORT = (
    "sd-server connection lost during img_gen poll (process exited, code -6)\n"
    "Last output:\n"
    "[ERROR] ggml_extend.hpp:70   - ggml_metal_op_encode_impl: error: unsupported op 'MUL_MAT'\n"
    "1   sd-server   0x00000001044f8df4 ggml_abort + 156\n"
    "10  sd-server   0x00000001043f6ce8 StableDiffusionGGML::sample"
)


def test_server_generation_restarts_on_the_cpu_backend_after_a_ggml_abort(monkeypatch):
    # ggml aborts on an unimplemented op with no CPU fallback, so the load restarts on --backend cpu.
    b = SdCppDiffusionBackend()
    servers: list = []
    _run_server_load(monkeypatch, b, servers, device = "mps")
    servers[0].img_gen_error = RuntimeError(_GGML_ABORT)

    out = b.generate(prompt = "a fox", width = 256, height = 256, steps = 4, seed = 3)

    assert len(out["images"]) == 1
    assert len(servers) == 2 and servers[0].stopped is True
    assert servers[1].started["extra_args"] == ["--backend", "cpu"]
    assert servers[1].started["files"] is servers[0].started["files"]
    assert servers[1].started["native_speed"] == servers[0].started["native_speed"]
    assert b._state is not None and b._state.server is servers[1]


def test_cpu_backend_restart_happens_once_per_load(monkeypatch):
    b = SdCppDiffusionBackend()
    servers: list = []
    _run_server_load(monkeypatch, b, servers, device = "mps")
    servers[0].img_gen_error = RuntimeError(_GGML_ABORT)
    b.generate(prompt = "x", steps = 4, seed = 1)
    assert len(servers) == 2

    servers[1].img_gen_error = RuntimeError(_GGML_ABORT)
    with pytest.raises(RuntimeError, match = "unsupported op"):
        b.generate(prompt = "x", steps = 4, seed = 1)
    assert len(servers) == 2


def test_server_death_without_the_abort_signature_is_not_retried(monkeypatch):
    b = SdCppDiffusionBackend()
    servers: list = []
    _run_server_load(monkeypatch, b, servers, device = "mps")
    servers[0].img_gen_error = RuntimeError(
        "sd-server connection lost during img_gen poll (process exited, code -9)"
    )
    with pytest.raises(RuntimeError, match = "code -9"):
        b.generate(prompt = "x", steps = 4, seed = 1)
    assert len(servers) == 1


def test_cpu_device_does_not_restart_on_an_abort(monkeypatch):
    b = SdCppDiffusionBackend()
    servers: list = []
    _run_server_load(monkeypatch, b, servers, device = "cpu")
    servers[0].img_gen_error = RuntimeError(_GGML_ABORT)
    with pytest.raises(RuntimeError, match = "unsupported op"):
        b.generate(prompt = "x", steps = 4, seed = 1)
    assert len(servers) == 1


def test_server_generate_splits_batches_above_server_limit(monkeypatch):
    b = SdCppDiffusionBackend()
    servers: list = []
    _run_server_load(monkeypatch, b, servers)
    out = b.generate(prompt = "x", width = 256, height = 256, steps = 4, seed = 100, batch_size = 10)
    assert len(out["images"]) == 10
    counts = [p["batch_count"] for p in servers[0].payloads]
    assert counts == [bk._MAX_SERVER_BATCH, 10 - bk._MAX_SERVER_BATCH]
    # Chunks share one request deadline; the server only splits because it caps images per job.
    assert servers[0].timeouts[0] <= bk.NATIVE_GENERATION_TIMEOUT_S
    assert servers[0].timeouts[1] <= servers[0].timeouts[0]
    assert servers[0].timeouts[-1] > 1800.0
    assert out["seeds"] == list(range(100, 110))
    assert servers[0].payloads[1]["seed"] == 108


def test_server_generate_masks_large_seed(monkeypatch):
    # sd.cpp's image seed is signed int64, so a larger explicit seed must be masked before it reaches the server.
    b = SdCppDiffusionBackend()
    servers: list = []
    _run_server_load(monkeypatch, b, servers)
    out = b.generate(prompt = "x", width = 256, height = 256, steps = 4, seed = 2**64 - 1, batch_size = 1)
    assert servers[0].payloads[0]["seed"] <= (1 << 63) - 1
    assert all(s <= (1 << 63) - 1 for s in out["seeds"])


def test_status_clears_when_server_died(monkeypatch):
    b = SdCppDiffusionBackend()
    servers: list = []
    _run_server_load(monkeypatch, b, servers)
    assert b.status()["loaded"] is True
    servers[0].alive = False
    st = b.status()
    assert st["loaded"] is False
    assert b._state is None


def test_server_generate_progress_from_stdout(monkeypatch):
    b = SdCppDiffusionBackend()
    servers: list = []
    _run_server_load(monkeypatch, b, servers)

    seen = {}

    class _WatchServer(_FakeServer):
        def img_gen(
            self,
            payload,
            *,
            on_step = None,
            cancel_event = None,
            total_timeout = None,
        ):
            on_step("  4/8")
            seen["mid"] = b.generate_progress()
            return super().img_gen(
                payload, on_step = on_step, cancel_event = cancel_event, total_timeout = total_timeout
            )

    b._state = bk._SdState(
        repo_id = b._state.repo_id,
        base_repo = b._state.base_repo,
        family = b._state.family,
        device = b._state.device,
        files = b._state.files,
        vae_format = b._state.vae_format,
        sampling_method = b._state.sampling_method,
        flow_shift = b._state.flow_shift,
        server = _WatchServer("/x/sd-server"),
        mode = "server",
    )
    b.generate(prompt = "x", steps = 8, seed = 1)
    assert seen["mid"]["step"] == 4 and seen["mid"]["total_steps"] == 8


def test_server_unload_stops_server(monkeypatch):
    b = SdCppDiffusionBackend()
    servers: list = []
    _run_server_load(monkeypatch, b, servers)
    st = b.unload()
    assert st["loaded"] is False
    assert servers[0].stopped is True
    assert b._state is None


def test_server_reload_stops_old_server_before_new(monkeypatch):
    b = SdCppDiffusionBackend()
    servers: list = []
    _run_server_load(monkeypatch, b, servers)
    b._load_token = 2
    fam = detect_family("z-image")
    b._run_load(
        repo_id = "unsloth/Z-Image-Turbo-GGUF",
        gguf_filename = "z.gguf",
        base = fam.base_repo,
        fam = fam,
        hf_token = None,
        _load_token = 2,
    )
    assert len(servers) == 2
    assert servers[0].stopped is True
    assert b._state.server is servers[1] and servers[1].stopped is False


def test_a_cancel_during_server_revalidation_stops_before_the_process_spawns(monkeypatch):
    # An unload during the ~20s binary probe must be seen under the same lock that publishes.
    b = SdCppDiffusionBackend()
    cancel = threading.Event()
    monkeypatch.setattr(bk, "find_sd_server_binary", lambda: "/x/sd-server")

    def _revalidate_then_cancel(*_a, **_k):
        cancel.set()
        return True

    monkeypatch.setattr(bk, "_server_binary_runnable", _revalidate_then_cancel)

    started: list[str] = []

    class _RecordingServer:
        def __init__(self, binary):
            self.stopped = False

        def start(self, *a, **k):
            started.append("start")

        def stop(self):
            self.stopped = True

    monkeypatch.setattr(bk, "SdCppServer", _RecordingServer)
    fake = _FakeEngine()
    _shared_setup_1(b, fake, monkeypatch)
    fam = detect_family("z-image")
    b._load_token = 1
    b._run_load(
        repo_id = "unsloth/Z-Image-Turbo-GGUF",
        gguf_filename = "z.gguf",
        base = fam.base_repo,
        fam = fam,
        hf_token = None,
        _load_token = 1,
        _cancel_event = cancel,
    )
    assert started == [], "a cancelled load must not spawn the server process"
    # A leaked _pending_server reads as a busy managed tree and blocks later installs.
    assert b._pending_server is None
    assert bk._tree_in_use(b) is False


def test_server_start_failure_falls_back_to_oneshot(monkeypatch):
    b = SdCppDiffusionBackend()
    monkeypatch.setattr(bk, "find_sd_server_binary", lambda: "/x/sd-server")
    monkeypatch.setattr(bk, "_server_binary_runnable", lambda *_a, **_k: True)

    class _BadServer:
        def __init__(self, binary):
            self.stopped = False

        def start(self, *a, **k):
            raise RuntimeError("sd-server broken")

        def stop(self):
            self.stopped = True

    monkeypatch.setattr(bk, "SdCppServer", _BadServer)
    fake = _FakeEngine()
    _shared_setup_1(b, fake, monkeypatch)
    fam = detect_family("z-image")
    b._load_token = 1
    _shared_setup_2(b, fam)
    assert b._state is not None and b._state.mode == "oneshot" and b._state.server is None
    # A stale _pending_server would suppress every later accelerator install.
    assert b._pending_server is None
    assert bk._tree_in_use(b) is False
    out = b.generate(prompt = "x", steps = 4, seed = 1)
    assert len(out["images"]) == 1 and len(fake.calls) == 1


def test_server_start_failure_keeps_the_engine_the_fallback_resolved(monkeypatch):
    # The fallback must record the accelerator of the sd-cli it resolved, not of None.
    b = SdCppDiffusionBackend()
    monkeypatch.setattr(bk, "find_sd_server_binary", lambda: "/x/sd-server")
    monkeypatch.setattr(bk, "_server_binary_runnable", lambda *_a, **_k: True)

    class _BadServer:
        def __init__(self, binary):
            pass

        def start(self, *a, **k):
            raise RuntimeError("sd-server broken")

        def stop(self):
            pass

    monkeypatch.setattr(bk, "SdCppServer", _BadServer)
    fake = _FakeEngine()
    fake.binary = "/x/sd-cli"
    _shared_setup_1(b, fake, monkeypatch)
    # Keyed on the binary: a constant stub would pass whether or not the bug is fixed.
    monkeypatch.setattr(
        bk, "_installed_accelerator_of", lambda binary: "cuda" if binary == "/x/sd-cli" else None
    )
    fam = detect_family("z-image")
    b._load_token = 1
    _shared_setup_2(b, fam)
    assert b._state is not None and b._state.mode == "oneshot"
    assert b._state.sd_accelerator == "cuda"
    out = b.generate(prompt = "x", steps = 4, seed = 1)
    assert len(out["images"]) == 1 and len(fake.calls) == 1


def test_server_unusable_after_the_download_keeps_the_engine_the_fallback_resolved(monkeypatch):
    # Server to one-shot fallback after the download: the pin must not be taken off an engine of None.
    b = SdCppDiffusionBackend()
    monkeypatch.setattr(bk, "find_sd_server_binary", lambda: "/x/sd-server")
    # Runnable up front so the pre-download fallback is not the path under test; unusable by the
    # time the claim re-checks it, which is what sends the load to sd-cli after the download.
    runnable = [True]

    def _runnable(*_a, **_k):
        answer = runnable[0]
        runnable[0] = False
        return answer

    monkeypatch.setattr(bk, "_server_binary_runnable", _runnable)
    monkeypatch.setattr(bk, "ensure_sd_server_binary", lambda **_k: "/x/sd-server")
    fake = _FakeEngine()
    fake.binary = "/x/sd-cli"
    _shared_setup_1(b, fake, monkeypatch)
    monkeypatch.setattr(bk, "_installed_accelerator_of", lambda binary: "cuda" if binary else None)
    fam = detect_family("z-image")
    b._load_token = 1
    b._loading = bk._SdLoading(repo_id = "unsloth/Z-Image-Turbo-GGUF", base_repo = fam.base_repo)
    _shared_setup_2(b, fam)
    assert b._state is not None, f"the fallback was refused: {b.load_progress().get('error')}"
    assert b._state.mode == "oneshot" and b._state.server is None
    assert b._state.sd_accelerator == "cuda"
    out = b.generate(prompt = "x", steps = 4, seed = 1)
    assert len(out["images"]) == 1 and len(fake.calls) == 1


def test_a_oneshot_load_refuses_a_cli_swapped_during_the_asset_download(monkeypatch):
    # The one-shot accelerator is pinned when the engine is vetted, not after the long download.
    b = SdCppDiffusionBackend()
    monkeypatch.setattr(bk, "find_sd_server_binary", lambda: None)
    monkeypatch.setattr(bk, "_install_allowed", lambda: False)
    fake = _FakeEngine()
    fake.binary = "/x/sd-cli"
    monkeypatch.setattr(b, "_resolve_engine", lambda: fake)
    monkeypatch.setattr(b, "_asset_specs", lambda *a, **k: [])
    monkeypatch.setattr(b, "_set_expected_bytes", lambda *a, **k: None)
    monkeypatch.setattr(
        bk, "resolve_diffusion_device_target", lambda: types.SimpleNamespace(device = "cpu")
    )
    installed = ["cuda"]
    monkeypatch.setattr(
        bk, "_installed_accelerator_of", lambda binary: installed[0] if binary else None
    )

    def _fetch(*a, **k):
        installed[0] = "cpu"
        return {"diffusion_model": "/m/z.gguf", "vae": "/m/vae.sft", "llm": "/m/llm.sft"}

    monkeypatch.setattr(b, "_fetch_assets", _fetch)
    fam = detect_family("z-image")
    b._load_token = 1
    b._loading = bk._SdLoading(repo_id = "unsloth/Z-Image-Turbo-GGUF", base_repo = fam.base_repo)
    _shared_setup_2(b, fam)

    assert b._state is None
    assert "different accelerator" in (b.load_progress()["error"] or "")


def test_run_load_redacts_paths_in_progress_error(monkeypatch):
    from utils import native_path_leases as npl

    secret_root = "/managed/native/root"
    npl._remember_native_path_for_redaction(secret_root, "model dir")
    try:
        b = SdCppDiffusionBackend(engine = _FakeEngine())
        fam = detect_family("z-image")
        monkeypatch.setattr(b, "_asset_specs", lambda *a, **k: [])
        monkeypatch.setattr(b, "_set_expected_bytes", lambda *a, **k: None)

        def _boom(*a, **k):
            raise RuntimeError(f"failed to read {secret_root}/z.gguf")

        monkeypatch.setattr(b, "_fetch_assets", _boom)

        b._load_token = 1
        b._loading = bk._SdLoading(repo_id = "unsloth/Z-Image-Turbo-GGUF", base_repo = fam.base_repo)
        b._run_load(
            repo_id = "unsloth/Z-Image-Turbo-GGUF",
            gguf_filename = "z.gguf",
            base = fam.base_repo,
            fam = fam,
            hf_token = None,
            _load_token = 1,
        )
        err = b.load_progress()["error"]
        assert err and secret_root not in err and "<native_path>" in err
    finally:
        with npl._REDACTION_LOCK:
            if secret_root in npl._NATIVE_PATH_REDACTIONS:
                npl._NATIVE_PATH_REDACTIONS.remove(secret_root)


def _fake_materialize(resolved, dest, **kwargs):
    """Stand-in for diffusion_lora.materialize_native_dir: write a stub file per adapter
    into ``dest`` and return the resolved list pointing at the written paths (mirroring the
    real helper's contract without touching the Hub / real weights)."""
    from pathlib import Path as _P

    from core.inference import diffusion_lora as dl

    dest.mkdir(parents = True, exist_ok = True)
    out = []
    for r in resolved:
        p = _P(dest) / f"{r.alias}.safetensors"
        p.write_bytes(b"stub")
        out.append(dl.ResolvedLora(r.id, r.alias, str(p), r.fmt, r.weight))
    return out


def _patch_lora(
    monkeypatch,
    resolved,
    supported = True,
):
    from core.inference import diffusion_lora as dl

    monkeypatch.setattr(dl, "supports_lora", lambda **k: supported)
    monkeypatch.setattr(dl, "resolve_specs", lambda specs, **k: list(resolved))
    monkeypatch.setattr(dl, "materialize_native_dir", _fake_materialize)


def test_generate_oneshot_applies_loras_via_prompt_tags(monkeypatch):
    from core.inference import diffusion_lora as dl

    eng = _FakeEngine()
    b = _loaded_backend(engine = eng)
    _patch_lora(
        monkeypatch, [dl.ResolvedLora("id1", "myalias", "/x/a.safetensors", "safetensors", 0.8)]
    )
    b.generate(prompt = "a fox", steps = 4, seed = 1, loras = [("id1", 0.8)])
    _, params, _, _ = eng.calls[0]
    assert params.lora_dir is not None and params.lora_apply_mode == "auto"
    assert "<lora:myalias:0.8>" in params.prompt


def test_generate_server_stages_loras_and_sends_structured_field(monkeypatch, tmp_path):
    # Server-mode LoRA rides the structured `lora` field (the sdcpp API ignores prompt tags): staged into --lora-model-dir and referenced by relative path.
    from pathlib import Path as _P

    from core.inference import diffusion_lora as dl

    b = SdCppDiffusionBackend()
    servers: list = []
    _run_server_load(monkeypatch, b, servers)
    servers[0].lora_dir = str(tmp_path)
    _patch_lora(
        monkeypatch, [dl.ResolvedLora("id1", "myalias", "/x/a.safetensors", "safetensors", 0.7)]
    )
    b.generate(prompt = "x", steps = 4, seed = 1, batch_size = 1, loras = [("id1", 0.7)])
    payload = servers[0].payloads[0]
    assert "lora" in payload and len(payload["lora"]) == 1
    assert payload["lora"][0]["multiplier"] == 0.7
    assert payload["lora"][0]["path"].endswith("myalias.safetensors")
    assert "<lora:" not in payload["prompt"]
    assert not list(_P(tmp_path).glob("gen_*"))


def test_generate_server_stages_loras_as_real_files_inside_the_lora_dir(monkeypatch, tmp_path):
    # sd-server (master-982+) canonicalizes every file under --lora-model-dir and skips one resolving outside it
    # (examples/server/runtime.cpp refresh_lora_cache / get_lora_full_path), so a symlink into the cache is dropped.
    import os

    from core.inference import diffusion_lora as dl

    cache = tmp_path / "cache"
    cache.mkdir()
    src = cache / "adapter.safetensors"
    src.write_bytes(b"weights")
    server_dir = tmp_path / "server_loras"
    server_dir.mkdir()
    b = SdCppDiffusionBackend()
    servers: list = []
    _run_server_load(monkeypatch, b, servers)
    servers[0].lora_dir = str(server_dir)
    monkeypatch.setattr(dl, "supports_lora", lambda **k: True)
    monkeypatch.setattr(
        dl,
        "resolve_specs",
        lambda specs, **k: [dl.ResolvedLora("id1", "myalias", str(src), "safetensors", 0.7)],
    )
    real = dl.materialize_native_dir
    seen = []

    def _spy(resolved, dest, **kwargs):
        out = real(resolved, dest, **kwargs)
        for m in out:
            seen.append(
                (os.path.islink(m.path), os.path.realpath(m.path), Path(m.path).read_bytes())
            )
        return out

    monkeypatch.setattr(dl, "materialize_native_dir", _spy)
    b.generate(prompt = "x", steps = 4, seed = 1, batch_size = 1, loras = [("id1", 0.7)])
    assert len(seen) == 1
    is_link, resolved_path, data = seen[0]
    assert not is_link
    assert Path(resolved_path).is_relative_to(Path(os.path.realpath(server_dir)))
    assert data == b"weights"
    assert src.read_bytes() == b"weights"
    assert not list(server_dir.glob("gen_*"))


def _server_lora_run(monkeypatch, tmp_path, *, fail_first):
    import dataclasses
    import io

    from core.inference import diffusion_lora as dl

    buf = io.BytesIO()
    Image.new("RGB", (64, 64)).save(buf, format = "PNG")
    png = buf.getvalue()
    seen = []

    class _Server:
        def __init__(self, lora_dir, fail):
            self.lora_dir, self.fail = str(lora_dir), fail

        def img_gen(self, payload, **kw):
            # What sd-server would resolve: every payload path must exist under THIS server's lora dir.
            seen.append(
                (
                    self.lora_dir,
                    [(Path(self.lora_dir) / e["path"]).is_file() for e in payload["lora"]],
                )
            )
            if self.fail:
                raise RuntimeError("ggml unsupported op abort")
            return [png]

    @dataclasses.dataclass(frozen = True)
    class _State:
        family: object
        server: object
        sampling_method: object = None
        flow_shift: object = None
        sample_sigmas: object = None

    src = tmp_path / "cache" / "a.safetensors"
    src.parent.mkdir()
    src.write_bytes(b"w")
    old_dir, new_dir = tmp_path / "old", tmp_path / "new"
    old_dir.mkdir()
    new_dir.mkdir()
    b = SdCppDiffusionBackend()
    monkeypatch.setattr(
        b,
        "_restart_server_on_cpu_backend",
        lambda state, text, cancel, **kw: _Server(new_dir, False),
    )
    # Published like a real load: a restart hands over only while _state still holds the server it replaces.
    b._state = _State(family = detect_family("flux.1"), server = _Server(old_dir, fail_first))
    b._generate_server(
        b._state,
        prompt = "p",
        negative_prompt = None,
        width = 64,
        height = 64,
        steps = 4,
        seed = 1,
        batch_size = 1,
        cfg_scale = None,
        flux_guidance = None,
        lora_resolved = [dl.ResolvedLora("id1", "a", str(src), "safetensors", 0.5)],
        cancel = threading.Event(),
    )
    return seen, old_dir, new_dir


def test_server_cpu_restart_restages_loras_in_the_new_server_dir(monkeypatch, tmp_path):
    seen, old_dir, new_dir = _server_lora_run(monkeypatch, tmp_path, fail_first = True)
    assert seen == [(str(old_dir), [True]), (str(new_dir), [True])]
    assert not list(old_dir.glob("gen_*")) and not list(new_dir.glob("gen_*"))


def test_server_lora_staging_failure_leaves_no_partial_stage(monkeypatch, tmp_path):
    import shutil

    from core.inference import diffusion_lora as dl

    def _no_link(*a, **k):
        raise OSError(18, "Invalid cross-device link")

    def _partial_copy(src, dst, *a, **k):
        Path(dst).write_bytes(b"part")
        raise OSError(28, "No space left on device")

    monkeypatch.setattr(dl.os, "link", _no_link)
    monkeypatch.setattr(shutil, "copy2", _partial_copy)
    with pytest.raises(OSError, match = "No space left"):
        _server_lora_run(monkeypatch, tmp_path, fail_first = False)
    assert not list((tmp_path / "old").iterdir())


def test_generate_rejects_loras_on_unsupported_family(monkeypatch):
    b = _loaded_backend(engine = _FakeEngine())
    _patch_lora(monkeypatch, [], supported = False)
    with pytest.raises(ValueError, match = "LoRA is not supported"):
        b.generate(prompt = "x", steps = 4, seed = 1, loras = [("id1", 1.0)])


def test_generate_zero_weight_loras_are_noop(monkeypatch):
    # weight-0 rows are dropped BEFORE the support gate, so an only-disabled request stays a no-op even where native LoRA is unsupported.
    eng = _FakeEngine()
    b = _loaded_backend(engine = eng)
    _patch_lora(monkeypatch, [], supported = False)
    b.generate(prompt = "x", steps = 4, seed = 1, loras = [("id1", 0.0)])
    _, params, _, _ = eng.calls[0]
    assert params.lora_dir is None


def test_generate_rejects_controlnet_on_native_engine():
    b = _loaded_backend(engine = _FakeEngine())
    with pytest.raises(ValueError, match = "ControlNet is not yet supported on the native"):
        b.generate(prompt = "x", steps = 4, seed = 1, controlnet = ("id", "img", "canny", 1.0, 0.0, 1.0))


@pytest.mark.parametrize("cn_strength", [0, 0.0, None])
def test_generate_treats_zero_strength_controlnet_as_disabled(cn_strength):
    eng = _FakeEngine()
    b = _loaded_backend(engine = eng)
    out = b.generate(
        prompt = "x",
        steps = 4,
        seed = 1,
        controlnet = ("id", "img", "canny", cn_strength, 0.0, 1.0),
    )
    assert len(out["images"]) == 1


def test_generate_rejects_image_conditioned_on_native_engine():
    # image-conditioned generation is diffusers-only; native calls must fail, not use txt2img.
    b = _loaded_backend(engine = _FakeEngine())
    with pytest.raises(ValueError, match = "not yet supported on the native"):
        b.generate(prompt = "x", steps = 4, seed = 1, init_image = "data:image/png;base64,AAAA")


def test_status_native_reports_supports_controlnet_false():
    b = _loaded_backend()
    assert b.status()["supports_controlnet"] is False


def test_native_negative_prompt_reaches_sd_cli_only_when_cfg_runs():
    klein = _loaded_backend("flux.2-klein")
    assert klein.status()["supports_negative_prompt"] is True
    kw = dict(prompt = "a fox", negative_prompt = "text", width = 256, height = 256, steps = 4, seed = 1)
    out = klein.generate(guidance = 4.0, **kw)
    assert klein._engine.calls[-1][1].negative_prompt == "text"
    assert out["negative_prompt"] == "text"
    out = klein.generate(guidance = 1.0, **kw)
    assert klein._engine.calls[-1][1].negative_prompt is None
    assert out["negative_prompt"] is None

    flux = _loaded_backend("flux.1")
    assert flux.status()["supports_negative_prompt"] is False
    out = flux.generate(guidance = 3.5, **kw)
    assert flux._engine.calls[-1][1].negative_prompt is None
    assert out["negative_prompt"] is None


def _synthetic_legacy_row(monkeypatch):
    """(repack, mirror) after adding a made-up mirror -> community repack row to the legacy table."""
    from core.inference import diffusion_families

    repack, mirror = "some-org/example-repack", "unsloth/example-repack-mirror"
    monkeypatch.setitem(diffusion_families._SD_CPP_LEGACY_SOURCES, mirror.lower(), repack)
    return repack, mirror


def test_a_cached_community_repack_is_reused_instead_of_re_downloading_the_mirror(
    monkeypatch, tmp_path
):
    """Legacy repo-id caches are reused, so a cached community repack avoids redownloads."""
    from core.inference.diffusion_families import prefer_cached_legacy_source
    from core.inference.sd_cpp_backend import _fetch_repo_map

    repack, mirror = _synthetic_legacy_row(monkeypatch)
    root = tmp_path / f"models--{repack.replace('/', '--')}"
    snapshot = root / "snapshots" / ("d" * 40)
    (snapshot / "split_files" / "vae").mkdir(parents = True)
    (snapshot / "split_files" / "vae" / "ae.safetensors").write_bytes(b"x" * 64)
    (root / "refs").mkdir(parents = True)
    (root / "refs" / "main").write_text("d" * 40, encoding = "utf-8")
    monkeypatch.setattr(
        "utils.hf_cache_settings.active_hf_hub_cache", lambda: str(tmp_path), raising = False
    )

    assets = [(mirror, "split_files/vae/ae.safetensors", "vae")]
    assert _fetch_repo_map(assets, None)[mirror] == repack

    monkeypatch.setattr(
        "utils.hf_cache_settings.active_hf_hub_cache",
        lambda: str(tmp_path / "empty"),
        raising = False,
    )
    assert _fetch_repo_map(assets, None)[mirror] == mirror
    # And a repo that mirrors nothing is returned unchanged.
    assert prefer_cached_legacy_source("unsloth/Qwen-Image", ["x"]) == "unsloth/Qwen-Image"


def test_a_repack_left_in_the_pre_change_cache_root_still_wins_over_the_mirror(
    monkeypatch, tmp_path
):
    """A repack left in the old cache root must win over the mirror, or its bytes become unreachable."""
    from core.inference.sd_cpp_backend import _fetch_repo_map

    repack, mirror = _synthetic_legacy_row(monkeypatch)
    other = tmp_path / "before_the_move"
    root = other / f"models--{repack.replace('/', '--')}"
    snapshot = root / "snapshots" / ("d" * 40)
    (snapshot / "split_files" / "vae").mkdir(parents = True)
    (snapshot / "split_files" / "vae" / "ae.safetensors").write_bytes(b"x" * 64)
    (root / "refs").mkdir(parents = True)
    (root / "refs" / "main").write_text("d" * 40, encoding = "utf-8")
    monkeypatch.setattr(
        "utils.hf_cache_settings.active_hf_hub_cache",
        lambda: str(tmp_path / "after_the_move"),
        raising = False,
    )
    monkeypatch.setattr("huggingface_hub.constants.HF_HUB_CACHE", str(other))

    assets = [(mirror, "split_files/vae/ae.safetensors", "vae")]
    assert _fetch_repo_map(assets, None)[mirror] == repack


def test_the_delete_guard_names_the_repack_as_well_as_the_mirror(monkeypatch):
    """The bytes land in whichever of the three the load chose, and that is re-decided per load, so
    a guard naming only one of them can delete a repo the next load needs."""
    from core.inference.sd_cpp_backend import _with_mirrors

    repack, mirror = _synthetic_legacy_row(monkeypatch)
    protected = _with_mirrors([mirror])
    assert mirror in protected
    assert repack in protected
    # No real row is left: the Wan GGUF no longer drags its old QuantStack repack along.
    assert "QuantStack/Wan2.2-TI2V-5B-GGUF" not in _with_mirrors(["unsloth/Wan2.2-TI2V-5B-GGUF"])


def test_begin_load_answers_without_waiting_on_the_header_probe(monkeypatch):
    """begin_load must not wait on the network probe, which the worker repeats before any fetch."""
    import time as _time

    from core.inference import diffusion_compat

    diffusion_compat._reset_inner_dim_cache()
    probed: list[str] = []

    class _Slow:
        def get(
            self,
            url,
            headers = None,
            timeout = None,
            stream = False,
        ):
            probed.append(url)
            _time.sleep(30)
            raise AssertionError("unreachable")

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

    b = SdCppDiffusionBackend(engine = _FakeEngine())
    monkeypatch.setattr(b, "_run_load", lambda **kwargs: None)

    started = _time.monotonic()
    b.begin_load("unsloth/FLUX.2-klein-4B-GGUF", gguf_filename = "flux-2-klein-4b-Q4_K_M.gguf")
    elapsed = _time.monotonic() - started

    assert probed == [], "begin_load must not range-read the header on the route thread"
    assert elapsed < 5, f"begin_load blocked for {elapsed:.1f}s"


def test_the_worker_publishes_the_real_encoder_repos_before_fetching(monkeypatch):
    # The delete-cached guard reads _loading.asset_repos, so it must be refreshed for FLUX.2 9B.
    from core.inference import diffusion_compat

    diffusion_compat._reset_inner_dim_cache()
    nine_b = {repo for repo, _f, _k in _FLUX2_KLEIN_9B_SD_CPP_TEXT_ENCODERS}
    # A name with no size: the string fallback answers 4B while the header says 9B.
    repo, filename = "unsloth/FLUX.2-klein-GGUF", "flux-2-klein-Q4_K_M.gguf"
    monkeypatch.setattr(
        bk.SdCppDiffusionBackend,
        "_flux2_inner_dim",
        staticmethod(
            lambda repo_id, fn, fam, tok, allow_network = True: 4096 if allow_network else None
        ),
    )

    b = SdCppDiffusionBackend(engine = _FakeEngine())
    monkeypatch.setattr(b, "_run_load", lambda **kwargs: None)
    b.begin_load(repo, gguf_filename = filename)
    token = b._load_token
    assert not nine_b & set(
        b.loading_repo_ids()
    ), "fixture is not discriminating: begin_load already guessed the 9B encoders"

    monkeypatch.setattr(b, "_resolve_backend", lambda: ("oneshot", None, _FakeEngine()))
    monkeypatch.setattr(b, "_preflight_companion_repos", lambda *a, **k: None)
    monkeypatch.setattr(b, "_set_expected_bytes", lambda *a, **k: None)
    seen_at_fetch: list[tuple[str, ...]] = []

    def _fetch(*_a, **_k):
        seen_at_fetch.append(b.loading_repo_ids())
        raise SdCppCancelled("stop here; the publish already had to happen")

    monkeypatch.setattr(b, "_fetch_assets", _fetch)
    bk.SdCppDiffusionBackend._run_load(
        b,
        repo_id = repo,
        gguf_filename = filename,
        base = "black-forest-labs/FLUX.2-klein-9B",
        fam = detect_family(repo),
        hf_token = None,
        _load_token = token,
    )

    assert seen_at_fetch, "the fetch was never reached"
    assert nine_b <= set(
        seen_at_fetch[0]
    ), "the delete guard did not name the encoders this load is about to write"


def test_generate_reports_the_build_the_recipe_persists():
    b = _loaded_backend()
    s = b._state
    b._state = bk._SdState(
        repo_id = s.repo_id,
        base_repo = s.base_repo,
        family = s.family,
        device = "cuda",
        files = s.files,
        vae_format = s.vae_format,
        sampling_method = s.sampling_method,
        flow_shift = s.flow_shift,
        mode = s.mode,
        gguf_filename = "z-image-turbo-Q4_K_M.gguf",
        offload_flags = ("--vae-on-cpu", "--clip-on-cpu"),
    )
    out = b.generate(prompt = "a fox", width = 256, height = 256, steps = 4, seed = 1)
    assert out["model_kind"] == "gguf"
    assert out["gguf_filename"] == "z-image-turbo-Q4_K_M.gguf"
    assert out["offload_policy"] == "active"
    assert out["offload_policy"] == b.status()["offload_policy"]
    assert out["transformer_quant"] is None and out["text_encoder_quant"] is None
    assert out["memory_mode"] is None
    assert out["cpu_offload"] is True and out["cpu_offload"] == b.status()["cpu_offload"]
    assert out["speed_mode"] == b.status()["speed_mode"]


def test_a_completed_native_generation_stops_advertising_itself_as_cancellable(monkeypatch):
    # Final check and deregistration share cancel_generate's lock: no Stop is true for a finished run.
    b = _loaded_backend()
    seen: list[bool] = []
    real_oneshot = b._generate_oneshot

    def _oneshot(*args, **kwargs):
        out = real_oneshot(*args, **kwargs)
        assert b.cancel_generate() is True
        return out

    monkeypatch.setattr(b, "_generate_oneshot", _oneshot)
    with pytest.raises(RuntimeError, match = "cancelled"):
        b.generate(prompt = "a fox", width = 256, height = 256, steps = 4, seed = 1)

    b2 = _loaded_backend()
    out = b2.generate(prompt = "a fox", width = 256, height = 256, steps = 4, seed = 1)
    assert out["images"]
    seen.append(b2.cancel_generate())
    assert seen == [False]


def _pinned_state(
    b,
    *,
    policy_flags = (),
    device = "cuda",
):
    """A resident native load whose argv carries the --backend device pin on top of `policy_flags`,
    exactly as _run_load builds it once a card has been selected."""
    from core.inference.sd_cpp_args import device_backend_flags

    s = b._state
    return bk._SdState(
        repo_id = s.repo_id,
        base_repo = s.base_repo,
        family = s.family,
        device = device,
        files = s.files,
        vae_format = s.vae_format,
        sampling_method = s.sampling_method,
        flow_shift = s.flow_shift,
        mode = s.mode,
        gguf_filename = "z-image-turbo-Q4_K_M.gguf",
        offload_flags = (
            *policy_flags,
            *device_backend_flags("CUDA1", list(policy_flags)),
        ),
    )


def test_a_card_pick_is_not_reported_as_an_offload():
    # The device pin shares the offload flag tuple; it must not make a "fast" load look offloaded.
    b = _loaded_backend()
    b._state = _pinned_state(b, policy_flags = ())
    assert b._state.offload_flags, "the fixture must actually carry the pin"
    status = b.status()
    assert status["cpu_offload"] is False
    assert status["offload_policy"] == "none"
    out = b.generate(prompt = "a fox", width = 256, height = 256, steps = 4, seed = 1)
    assert out["offload_policy"] == "none"


def test_a_real_offload_still_reports_itself_when_a_card_is_pinned():
    b = _loaded_backend()
    b._state = _pinned_state(b, policy_flags = ("--offload-to-cpu", "--diffusion-fa"))
    assert b.status()["cpu_offload"] is True
    assert b.status()["offload_policy"] == "active"


def test_the_cpu_backend_restart_drops_the_device_pin(monkeypatch):
    # sd.cpp concatenates repeated --backend and per-module entries win, so the pin must be stripped.
    started: dict = {}

    class _FakeServer:
        def __init__(self, binary):
            self.binary = binary

        def start(self, files, **kwargs):
            started.update(kwargs)

        def stop(self):
            pass

    b = _loaded_backend()
    b._state = _pinned_state(b, policy_flags = ("--offload-to-cpu", "--clip-on-cpu"))
    object.__setattr__(b._state, "server", _FakeServer("/bin/sd-server"))
    monkeypatch.setattr(bk, "find_sd_server_binary", lambda: "/bin/sd-server")
    monkeypatch.setattr(bk, "SdCppServer", _FakeServer)

    server = b._restart_server_on_cpu_backend(
        b._state,
        "ggml_metal_op_encode_impl: unsupported op 'MUL_MAT' -> ggml_abort",
        threading.Event(),
    )
    assert server is not None
    argv = [*started["offload"], *started["extra_args"]]
    backends = [argv[i + 1] for i, flag in enumerate(argv) if flag == "--backend"]
    assert backends == ["cpu"]
    assert "--offload-to-cpu" in argv and "--clip-on-cpu" in argv


def test_the_native_engine_resolves_a_bare_gpu_selection_itself(monkeypatch):
    # A direct caller passes gpu_ids alone; native must re-rank like diffusers and video.
    import core.inference.sd_cpp_backend as backend_module

    seen: dict = {}
    monkeypatch.setattr(
        backend_module,
        "resolve_diffusion_device_target",
        lambda **kw: types.SimpleNamespace(device = "cuda"),
    )
    monkeypatch.setattr(
        backend_module,
        "resolve_selected_cuda_ordinal",
        lambda ids: (seen.update(ids = list(ids)), 1)[1],
    )
    b = SdCppDiffusionBackend(engine = _FakeEngine())
    monkeypatch.setattr(b, "_start_load_thread", lambda *a, **k: None, raising = False)
    captured: dict = {}

    def _fake_thread(
        target = None,
        kwargs = None,
        **_,
    ):
        captured.update(kwargs or {})
        return types.SimpleNamespace(start = lambda: None, join = lambda *a, **k: None)

    monkeypatch.setattr(backend_module.threading, "Thread", _fake_thread)
    b.begin_load(
        "unsloth/Z-Image-Turbo-GGUF",
        gguf_filename = "z-image-turbo-Q4_K_M.gguf",
        gpu_ids = [3],
    )
    assert seen["ids"] == [3]
    assert captured["gpu_ordinal"] == 1


def test_an_unresolvable_device_pin_says_so_and_still_loads(tmp_path, capsys):
    # Older builds treat --list-devices as fatal, so an unresolved pick runs on the default device.
    binary = tmp_path / "sd-cli-old"
    binary.write_text("#!/usr/bin/env bash\nexit 1\n")
    binary.chmod(0o755)
    assert bk.sd_cpp_device_name_for_ordinal(str(binary), 1) is None
    assert "device_pin_unresolved" in capsys.readouterr().out
    assert bk.sd_cpp_device_name_for_ordinal(str(binary), None) is None
    assert "device_pin_unresolved" not in capsys.readouterr().out


def test_generation_in_flight_tracks_a_generation(monkeypatch):
    from core.inference import diffusion_lora

    eng = _FakeEngine()
    b = _loaded_backend(engine = eng)
    monkeypatch.setattr(bk, "_sd_cpp_backend", b)
    monkeypatch.setattr(diffusion_lora, "supports_lora", lambda **_k: True)

    seen: dict = {}

    def _resolve(
        active,
        *,
        family = None,
        hf_token = None,
        cancel_event = None,
    ):
        seen["in_flight"] = bk.generation_in_flight()
        return []

    monkeypatch.setattr(diffusion_lora, "resolve_specs", _resolve)

    assert bk.generation_in_flight() is False
    b.generate(prompt = "a fox", width = 256, height = 256, steps = 8, loras = [("some/lora", 1.0)])
    assert (
        seen["in_flight"] is True
    ), "liveness cannot tell this backend from a dead one while the native engine renders"
    assert bk.generation_in_flight() is False


def test_generation_in_flight_never_builds_a_backend(monkeypatch):
    monkeypatch.setattr(bk, "_sd_cpp_backend", None)
    monkeypatch.setattr(
        bk,
        "SdCppDiffusionBackend",
        lambda *a, **k: pytest.fail("liveness constructed a native diffusion backend"),
    )
    assert bk.generation_in_flight() is False


def test_the_marker_is_found_even_when_it_straddles_a_read_boundary(tmp_path):
    # The scan reads 8 MiB blocks; the marker is placed across the seam.
    marker = "qwen_image_2_1"
    chunk = 8 << 20
    path = tmp_path / "sd-cli"
    body = bytearray(b"\0" * (chunk + len(marker) * 2))
    body[chunk - len(marker) // 2 : chunk - len(marker) // 2 + len(marker)] = marker.encode()
    path.write_bytes(bytes(body))
    assert bk.binary_carries_marker(str(path), marker) is True
    assert bk.binary_carries_marker(str(path), "wan_2_2_no_such_arch") is False


def test_an_unreadable_binary_and_an_unmarked_family_both_leave_the_route_alone(tmp_path):
    # No marker, or an unreadable path, is no evidence, so neither may refuse.
    present = tmp_path / "sd-cli"
    present.write_bytes(b"nothing interesting")
    assert bk.binary_carries_marker(str(present), None) is True
    assert bk.binary_carries_marker(str(tmp_path / "missing"), "qwen_image_2_1") is True
    assert bk.binary_carries_marker(None, "qwen_image_2_1") is False
    assert bk.sd_cpp_binary_runs_family(str(present), detect_family("z-image")) is True
    assert bk.sd_cpp_binary_runs_family(str(present), detect_family("qwen-image-2.1")) is False


def test_the_scan_is_redone_when_the_binary_on_that_path_changes(tmp_path):
    # Memo keyed on size and mtime too: an upgrade writes a new build to the same path.
    path = tmp_path / "sd-cli"
    path.write_bytes(b"an old build")
    assert bk.binary_carries_marker(str(path), "qwen_image_2_1") is False
    path.write_bytes(b"a new build with qwen_image_2_1 in it")
    assert bk.binary_carries_marker(str(path), "qwen_image_2_1") is True


def test_a_cached_engine_is_re_checked_against_the_family_now_loading(tmp_path):
    # _engine is cached across loads, so it must be re-gated for the new family.
    old = tmp_path / "sd-cli-old"
    old.write_bytes(b"a build from before the family landed")
    backend = SdCppDiffusionBackend.__new__(SdCppDiffusionBackend)
    backend._engine = types.SimpleNamespace(binary = str(old), is_available = lambda: True)
    backend._engine_injected = False

    backend._loading_family = detect_family("z-image")
    assert backend._resolve_engine() is backend._engine

    backend._loading_family = detect_family("qwen-image-2.1")
    with pytest.raises(RuntimeError, match = "predates qwen-image-2.1 support"):
        backend._resolve_engine()


def test_a_rejected_concurrent_load_cannot_move_the_family_the_worker_validates_against():
    # Take _lock before assigning the family, or a refused load replaces the family the worker checks.
    backend = SdCppDiffusionBackend.__new__(SdCppDiffusionBackend)
    worker_family = detect_family("qwen-image-2.1")
    backend._loading_family = worker_family
    seen = {}
    started = threading.Event()

    def _other_request():
        backend._loading_family = detect_family("z-image")
        started.set()

    other = threading.Thread(target = _other_request)
    other.start()
    started.wait(timeout = 5)
    other.join(timeout = 5)
    seen["worker"] = backend._loading_family
    assert seen["worker"] is worker_family, "another thread's family reached this worker"


def test_server_failure_drops_a_cached_sd_cli_of_the_failed_build(monkeypatch):
    # An earlier one-shot load cached the Vulkan sd-cli; the Vulkan server now fails and the
    # recorded failure moves the preferred build to CPU, so the fallback must not reuse the cache.
    b = SdCppDiffusionBackend()
    monkeypatch.setattr(bk, "find_sd_server_binary", lambda: "/x/sd-server")
    monkeypatch.setattr(bk, "_server_binary_runnable", lambda *_a, **_k: True)

    class _BadServer:
        def __init__(self, binary):
            pass

        def start(self, *a, **k):
            raise RuntimeError("ggml_vulkan: No devices found")

        def stop(self):
            pass

    monkeypatch.setattr(bk, "SdCppServer", _BadServer)
    fake = _FakeEngine()
    fake.binary = "/vk/sd-cli"
    _shared_setup_1(b, fake, monkeypatch)
    monkeypatch.setattr(b, "_resolve_engine", SdCppDiffusionBackend._resolve_engine.__get__(b))
    b._engine = fake
    accelerators = {"/vk/sd-cli": "vulkan", "/cpu/sd-cli": "cpu"}
    monkeypatch.setattr(bk, "_installed_accelerator_of", lambda binary: accelerators.get(binary))
    monkeypatch.setattr(b, "_resolved_accelerator", lambda card = None: "cpu")
    asked = []

    def _ensure(**kwargs):
        asked.append(kwargs.get("accelerator"))
        return "/cpu/sd-cli"

    monkeypatch.setattr(bk, "ensure_sd_cpp_binary", _ensure)
    monkeypatch.setattr(b, "_refuse_incapable_build", lambda *_a, **_k: None)

    class _CpuEngine(_FakeEngine):
        def __init__(self, binary):
            super().__init__()
            self.binary = binary

    monkeypatch.setattr(bk, "SdCppEngine", _CpuEngine)
    fam = detect_family("z-image")
    b._load_token = 1
    _shared_setup_2(b, fam)
    assert asked == ["cpu"]
    assert b._state is not None and b._state.mode == "oneshot"
    assert b._state.sd_accelerator == "cpu"


def test_a_deferred_cuda_upgrade_keeps_the_selected_card(monkeypatch):
    # A CUDA load starts on the resident CPU bundle (placed on the CPU) and the deferred upgrade then
    # lands the CUDA build: the server must still be pinned to the card the route selected.
    b = SdCppDiffusionBackend()
    monkeypatch.setattr(bk, "find_sd_server_binary", lambda: "/x/sd-server")
    monkeypatch.setattr(bk, "_server_binary_runnable", lambda *_a, **_k: True)
    monkeypatch.setattr(bk, "ensure_sd_server_binary", lambda **_k: "/x/sd-server")
    started = []

    class _Server:
        def __init__(self, binary):
            pass

        def start(self, *a, **k):
            started.append(k.get("offload"))

        def stop(self):
            pass

    monkeypatch.setattr(bk, "SdCppServer", _Server)
    fake = _FakeEngine()
    _shared_setup_1(b, fake, monkeypatch)
    monkeypatch.setattr(
        bk, "resolve_diffusion_device_target", lambda: types.SimpleNamespace(device = "cuda")
    )
    installed = {"/x/sd-server": "cpu"}
    monkeypatch.setattr(bk, "_installed_accelerator_of", lambda binary: installed.get(binary))

    def _upgrade(server_binary, **_k):
        installed["/x/sd-server"] = "cuda"
        return server_binary

    monkeypatch.setattr(b, "_upgraded_or_refused", _upgrade)
    monkeypatch.setattr(b, "_resolved_accelerator", lambda card = None: "cuda")
    pins = []
    monkeypatch.setattr(
        bk,
        "_offload_with_device_pin_impl",
        lambda offload, binary, ordinal: pins.append(ordinal) or list(offload),
    )
    # The resident CPU bundle is in use, so _resolve_backend defers the upgrade to the teardown.
    monkeypatch.setattr(bk, "_managed_tree_in_use", lambda: True)
    fam = detect_family("z-image")
    b._load_token = 1
    b._run_load(
        repo_id = "unsloth/Z-Image-Turbo-GGUF",
        gguf_filename = "z.gguf",
        base = fam.base_repo,
        fam = fam,
        hf_token = None,
        _load_token = 1,
        gpu_ordinal = 1,
    )
    assert started, "the server must start"
    assert pins and all(p == 1 for p in pins), pins
    assert b._state is not None and b._state.device == "cuda"


def test_the_arbiter_preflight_reads_the_cli_behind_an_unowned_server(monkeypatch):
    # SD_SERVER_PATH is not installer-owned, so the managed sd-cli record is the answer.
    monkeypatch.setattr(bk, "find_sd_server_binary", lambda: "/custom/sd-server")
    monkeypatch.setattr(bk, "find_sd_cpp_binary", lambda: "/managed/sd-cli")
    records = {"/managed/sd-cli": "vulkan"}
    monkeypatch.setattr(bk, "_installed_accelerator_of", lambda binary: records.get(binary))
    assert bk.managed_sd_cpp_accelerator() == "vulkan"
    records["/custom/sd-server"] = "cpu"
    assert bk.managed_sd_cpp_accelerator() == "cpu"
    records.clear()
    assert bk.managed_sd_cpp_accelerator() is None


def test_only_managed_cpu_binaries_count_as_cpu_only(monkeypatch):
    monkeypatch.setattr(bk, "find_sd_server_binary", lambda: "/custom/sd-server")
    monkeypatch.setattr(bk, "find_sd_cpp_binary", lambda: "/managed/sd-cli")
    records = {"/managed/sd-cli": "cpu"}
    monkeypatch.setattr(bk, "_installed_accelerator_of", lambda binary: records.get(binary))
    # The unowned SD_SERVER_PATH build may render on a GPU.
    assert bk.sd_cpp_binaries_all_cpu() is False
    records["/custom/sd-server"] = "cpu"
    assert bk.sd_cpp_binaries_all_cpu() is True
    records["/managed/sd-cli"] = "vulkan"
    assert bk.sd_cpp_binaries_all_cpu() is False
    monkeypatch.setattr(bk, "find_sd_server_binary", lambda: None)
    monkeypatch.setattr(bk, "find_sd_cpp_binary", lambda: None)
    assert bk.sd_cpp_binaries_all_cpu() is False


def test_a_t5_index_from_the_old_cache_root_gets_its_shards_beside_it(monkeypatch, tmp_path):
    """After a cache move the T5 index resolves from the old root; its shards are linked beside it,
    since sd-cli reads them there rather than refusing a cache holding every file."""
    import json
    from pathlib import Path

    _no_cache(monkeypatch)
    b = _shared_setup_4(monkeypatch)
    old_root, live_root = tmp_path / "old", tmp_path / "live"

    def fake_download(repo, fn, tok, **k):
        root = old_root if fn.endswith(".safetensors.index.json") else live_root
        path = root / repo.replace("/", "--") / fn
        path.parent.mkdir(parents = True, exist_ok = True)
        if fn.endswith(".safetensors.index.json"):
            shards = [f.rsplit("/", 1)[-1] for _r, f, kind in specs if kind == "t5xxl_shard"]
            path.write_text(json.dumps({"weight_map": {str(i): n for i, n in enumerate(shards)}}))
        else:
            path.write_bytes(b"shard:" + fn.encode())
        return str(path)

    monkeypatch.setattr("utils.hf_xet_fallback.hf_hub_download_with_xet_fallback", fake_download)
    fam = detect_family("flux.1")
    specs = b._asset_specs("unsloth/FLUX.1-dev-GGUF", "flux1-dev-Q4_K_M.gguf", fam)
    shard_files = [f for _r, f, kind in specs if kind == "t5xxl_shard"]
    assert len(shard_files) == 2

    paths = b._fetch_assets(specs, None, local_files_only = True)

    index = Path(paths["t5xxl"])
    assert index.is_relative_to(old_root)
    for fn in shard_files:
        beside = index.parent / fn.rsplit("/", 1)[-1]
        assert beside.read_bytes() == b"shard:" + fn.encode()
        # Never a symlink into the other root: deleting or unmounting either root must not break the other.
        assert not beside.is_symlink()


def test_a_cross_device_shard_copy_never_leaves_a_truncated_shard(monkeypatch, tmp_path):
    """A cut-off copy (full disk) must not leave a short file at the final name, since the existence
    check accepts it; an earlier short file is replaced on next load."""
    import json
    import os
    import shutil

    from core.inference import sd_cpp_backend as mod

    src = tmp_path / "live" / "model-00001-of-00001.safetensors"
    src.parent.mkdir(parents = True)
    src.write_bytes(b"x" * 4096)
    index = tmp_path / "old" / "model.safetensors.index.json"
    index.parent.mkdir(parents = True)
    index.write_text(json.dumps({"weight_map": {"a": src.name}}))
    target = index.parent / src.name

    def no_link(*_a, **_k):
        raise OSError("cross-device link")

    def full_disk(a, b):
        with open(b, "wb") as fh:
            fh.write(b"x" * 100)
        raise OSError("No space left on device")

    real_copyfile = shutil.copyfile
    monkeypatch.setattr(mod.os, "link", no_link)
    monkeypatch.setattr(mod.shutil, "copyfile", full_disk)
    mod._colocate_shards(str(index), {src.name: str(src)})
    assert not target.exists()
    assert os.listdir(index.parent) == [index.name]

    # A short shard from an earlier, cut-off copy is replaced by a complete one.
    target.write_bytes(b"x" * 100)
    monkeypatch.setattr(mod.shutil, "copyfile", real_copyfile)
    mod._colocate_shards(str(index), {src.name: str(src)})
    assert target.read_bytes() == src.read_bytes()
    assert sorted(os.listdir(index.parent)) == sorted([index.name, src.name])


def test_the_native_fetch_keeps_an_upstream_cached_only_in_the_pre_change_root(monkeypatch):
    """_fetch_assets resolves each file through either cache root, so FLUX.1's CLIP / T5 left in the previous root
    serve the load. Deciding the mirror swap off the live root alone rewrote them to unsloth/FLUX.1-schnell, which a
    cache-only load then could not find and an online one re-pulled (~10 GB)."""
    monkeypatch.delenv("UNSLOTH_DIFFUSION_NO_MIRROR", raising = False)
    monkeypatch.setattr(
        "core.inference.diffusion_families._upstream_is_cached",
        lambda repo_id, files = None, *, other_root = False: other_root,
    )
    assets = [
        ("black-forest-labs/FLUX.1-schnell", "text_encoder/model.safetensors", "clip_l"),
        ("black-forest-labs/FLUX.1-schnell", "ae.safetensors", "vae"),
    ]
    assert bk._fetch_repo_map(assets, None) == {
        "black-forest-labs/FLUX.1-schnell": "black-forest-labs/FLUX.1-schnell"
    }


def test_the_native_progress_total_is_sized_where_the_assets_are_fetched(monkeypatch):
    """An anonymous user gets nothing back from a gated vendor id, so sizing FLUX.1's CLIP / T5 there left them at 0
    bytes and the bar finalizing while they downloaded. The total asks the repo _fetch_assets pulls from."""
    from types import SimpleNamespace

    from huggingface_hub import HfApi

    _no_cache(monkeypatch)
    asked = []

    def get_paths_info(self, repo_id, paths, **kwargs):
        asked.append(repo_id)
        if not repo_id.startswith("unsloth/"):
            raise PermissionError("gated")
        return [SimpleNamespace(path = p, size = 1_000) for p in paths]

    monkeypatch.setattr(HfApi, "get_paths_info", get_paths_info)
    b = SdCppDiffusionBackend(engine = _FakeEngine())
    b._loading = SimpleNamespace(expected_bytes = 0)
    assets = [
        ("black-forest-labs/FLUX.1-schnell", "text_encoder/model.safetensors", "clip_l"),
        ("black-forest-labs/FLUX.1-schnell", "ae.safetensors", "vae"),
    ]
    b._set_expected_bytes(assets, None)
    assert asked == ["unsloth/FLUX.1-schnell", "unsloth/FLUX.1-schnell"]
    assert b._loading.expected_bytes == 2_000


def _png_bytes():
    import io

    from PIL import Image

    buf = io.BytesIO()
    Image.new("RGB", (8, 8)).save(buf, format = "PNG")
    return buf.getvalue()


@pytest.mark.parametrize("losses, recovers", [(1, True), (2, False)])
def test_a_lost_vulkan_device_restarts_the_resident_server(monkeypatch, losses, recovers):
    # After VK_ERROR_DEVICE_LOST, restart the server on a fresh device and retry once; a second loss
    # surfaces only where no CPU rung applies; no strike.
    monkeypatch.setattr(bk, "_vulkan_cpu_rung_applies", lambda: False)
    events: list = []
    remaining = {"losses": losses}

    class _FakeServer:
        def __init__(self, binary):
            self.binary = binary
            events.append(("new", binary))

        def start(self, files, **kwargs):
            events.append(("start", kwargs.get("offload")))

        def stop(self):
            events.append(("stop", self.binary))

        def img_gen(self, payload, **_kw):
            if remaining["losses"]:
                remaining["losses"] -= 1
                raise RuntimeError("sd-server job failed: vk::Queue::submit: ErrorDeviceLost")
            return [_png_bytes()]

    b = _loaded_backend()
    b._state = _pinned_state(b, policy_flags = ("--offload-to-cpu",), device = "vulkan")
    object.__setattr__(b._state, "server", _FakeServer("/bin/sd-server-vulkan"))
    monkeypatch.setattr(bk, "SdCppServer", _FakeServer)
    monkeypatch.setattr(bk, "find_sd_server_binary", lambda: "/bin/sd-server-cpu")
    bk._accelerator_runtime_failures.clear()
    kwargs = dict(
        prompt = "a fox",
        negative_prompt = None,
        width = 64,
        height = 64,
        steps = 2,
        seed = 1,
        batch_size = 1,
        cfg_scale = None,
        flux_guidance = None,
        lora_resolved = [],
        cancel = threading.Event(),
    )
    if recovers:
        images, _seeds = b._generate_server(b._state, **kwargs)
        assert len(images) == 1
    else:
        with pytest.raises(RuntimeError, match = "ErrorDeviceLost"):
            b._generate_server(b._state, **kwargs)
    # The same build, with the load's own flags (device pin included), not the CPU backend.
    assert ("new", "/bin/sd-server-vulkan") in events[1:]
    assert ("start", b._state.offload_flags) in events or any(
        e[0] == "start" and "--offload-to-cpu" in (e[1] or ()) for e in events
    )
    assert not bk._accelerator_runtime_failures


def _repeated_device_loss_backend(
    monkeypatch,
    *,
    losses,
    gpu_explicit = False,
):
    """A CPU-torch Vulkan load whose first ``losses`` jobs lose the device, on whichever server runs them."""
    events: list = []
    remaining = {"losses": losses}
    persisted: list = []

    class _FakeServer:
        lora_dir = None

        def __init__(self, binary):
            self.binary = binary

        def start(self, files, **kwargs):
            events.append(("start", self.binary, tuple(kwargs.get("extra_args") or ())))

        def stop(self):
            events.append(("stop", self.binary))

        def is_alive(self):
            return True

        def img_gen(self, payload, **_kw):
            if remaining["losses"]:
                remaining["losses"] -= 1
                raise RuntimeError("sd-server job failed: vk::Queue::submit: ErrorDeviceLost")
            return [_png_bytes()]

    b = _loaded_backend()
    b._state = _pinned_state(b, policy_flags = ("--offload-to-cpu",), device = "vulkan")
    object.__setattr__(b._state, "server", _FakeServer("/bin/sd-server-vulkan"))
    object.__setattr__(b._state, "mode", "server")
    object.__setattr__(b._state, "gpu_explicit", gpu_explicit)
    monkeypatch.setattr(bk, "SdCppServer", _FakeServer)
    monkeypatch.setattr(bk, "find_sd_server_binary", lambda: "/bin/sd-server-vulkan")
    monkeypatch.setattr(bk, "_vulkan_cpu_rung_applies", lambda: True)
    monkeypatch.setattr(
        bk, "fallback_accelerator_for", lambda acc: "cpu" if acc == "vulkan" else None
    )
    monkeypatch.setattr(
        bk, "_persist_accelerator_runtime_failures", lambda records: persisted.append(records)
    )
    monkeypatch.setattr(bk, "_stored_accelerator_runtime_failures", lambda: {})
    bk._accelerator_runtime_failures.clear()
    return b, events, persisted


def test_a_vulkan_device_lost_again_after_the_respawn_renders_this_load_on_cpu(monkeypatch):
    # A driver that resets the card on every render (Windows TDR) must not fail every request; if
    # the respawn also loses the device, only this load moves to CPU; nothing is persisted.
    b, events, persisted = _repeated_device_loss_backend(monkeypatch, losses = 2)
    images, _seeds = b._generate_server(b._state, **_gen_kwargs())
    assert len(images) == 1
    starts = [e for e in events if e[0] == "start"]
    # First the same-build respawn on Vulkan, then the CPU backend.
    assert [s[2] for s in starts] == [(), ("--backend", "cpu")]
    assert b._cpu_backend_forced is True
    # The published state follows the server to CPU: status() no longer reports a Vulkan renderer, and the flags are
    # the ones the CPU server got (the Vulkan device pin dropped).
    assert b._state.device == "cpu"
    assert b._state.physical_gpu_id is None
    assert "--backend" not in b._state.offload_flags
    assert b._state.offload_flags == ("--offload-to-cpu",)
    assert b.status()["device"] == "cpu"
    assert not persisted and not bk._accelerator_runtime_failures
    # The failure text is not a strike either, and the next load still prefers Vulkan.
    bk.note_accelerator_failure_from_output(
        "/bin/sd-server-vulkan", "sd-server job failed: vk::Queue::submit: ErrorDeviceLost"
    )
    assert not persisted and not bk._accelerator_runtime_failures
    assert bk.preferred_accelerator("vulkan") == "vulkan"
    # Later requests on this load keep the CPU server without another restart.
    images, _seeds = b._generate_server(b._state, **_gen_kwargs())
    assert len(images) == 1
    assert len([e for e in events if e[0] == "start"]) == 2


def test_a_single_vulkan_device_loss_stays_on_vulkan(monkeypatch):
    b, events, persisted = _repeated_device_loss_backend(monkeypatch, losses = 1)
    images, _seeds = b._generate_server(b._state, **_gen_kwargs())
    assert len(images) == 1
    assert [e[2] for e in events if e[0] == "start"] == [()]
    assert b._cpu_backend_forced is False
    assert b._state.device == "vulkan"
    assert not persisted


_VRAM_REFUSAL = (
    "sd-server generation failed: generation_failed: generate_image returned no results\n"
    "Last output:\n"
    "[E] MOSS-Image segment 1/43 (moss_image.layers.0) failed during weight preparation --- ggml_runner.cpp:934\n"
    "[E] diffusion model compute failed --- diffusion_engine.cpp:2729\n"
    "[E] Diffusion model sampling failed --- diffusion_engine.cpp:2976\n"
    "[E] sampling for image 1/1 failed after 0.09s --- image.cpp:1007"
)


_ALLOCATION_FAILURE = (
    "sd-server generation failed: generation_failed: generate_image returned no results\n"
    "Last output:\n"
    "[E] ggml: ggml_backend_cuda_buffer_type_alloc_buffer: allocating 210.08 MiB on device 0: "
    "cudaMalloc failed: out of memory\n"
    "[E] ggml: alloc_tensor_range: failed to allocate CUDA0 buffer of size 220288512\n"
    "[E] MOSS-Image segment 12/43 (moss_image.layers.11) failed during {stage} --- ggml_runner.cpp:934\n"
    "[E] diffusion model compute failed --- diffusion_engine.cpp:2729"
)


def _vram_refusal_backend(
    monkeypatch,
    *,
    refusals,
    planned_free_mib = None,
    restarted_plans = (),
    error = _VRAM_REFUSAL,
    max_vram_supported = True,
    per_device_supported = True,
    policy_flags = (),
    device = "cuda",
):
    """CUDA load pinned to CUDA1 whose first ``refusals`` jobs fail with ``error``; ``restarted_plans`` are the
    free-VRAM plans each replacement server reads in turn."""
    events: list = []
    remaining = {"refusals": refusals}
    planned = {"CUDA1": 6666} if planned_free_mib is None else planned_free_mib
    plans = [planned, *restarted_plans]

    class _FakeServer:
        lora_dir = None

        def __init__(self, binary):
            self.binary = binary
            self.planned_free_vram_mib = dict(plans.pop(0) if len(plans) > 1 else plans[0])

        def start(self, files, **kwargs):
            events.append(
                ("start", tuple(kwargs.get("extra_args") or ()), tuple(kwargs.get("offload") or ()))
            )

        def stop(self):
            events.append(("stop",))

        def is_alive(self):
            return True

        def img_gen(self, payload, **_kw):
            if remaining["refusals"]:
                remaining["refusals"] -= 1
                raise RuntimeError(error)
            return [_png_bytes()]

    b = _loaded_backend()
    b._state = _pinned_state(b, policy_flags = policy_flags, device = device)
    object.__setattr__(b._state, "server", _FakeServer("/bin/sd-server"))
    object.__setattr__(b._state, "mode", "server")
    monkeypatch.setattr(bk, "SdCppServer", _FakeServer)
    monkeypatch.setattr(
        bk,
        "sd_cpp_graph_cut_options",
        lambda binary: frozenset({"--max-vram"}) if max_vram_supported else frozenset(),
    )
    monkeypatch.setattr(bk, "_layer_split_supported", lambda binary: per_device_supported)
    return b, events


def test_a_vram_refusal_restarts_once_under_half_the_planned_free_vram(monkeypatch):
    b, events = _vram_refusal_backend(monkeypatch, refusals = 1)
    flags = b._state.offload_flags
    images, _seeds = b._generate_server(b._state, **_gen_kwargs())
    assert len(images) == 1
    # Half of 6666 MiB, rounded down to 0.01 GiB.
    assert [e for e in events if e[0] == "start"] == [("start", ("--max-vram", "3.25"), flags)]
    assert b._state.vram_budget == "3.25"
    assert b._state.device == "cuda" and b._state.offload_flags == flags
    images, _seeds = b._generate_server(b._state, **_gen_kwargs())
    assert len(images) == 1
    assert len([e for e in events if e[0] == "start"]) == 1


def test_a_vram_refusal_budgets_each_visible_card_from_its_own_free_vram(monkeypatch):
    b, events = _vram_refusal_backend(
        monkeypatch, refusals = 1, planned_free_mib = {"CUDA0": 45979, "CUDA1": 5771}
    )
    images, _seeds = b._generate_server(b._state, **_gen_kwargs())
    assert len(images) == 1
    assert [e[1] for e in events if e[0] == "start"] == [("--max-vram", "CUDA0=22.45,CUDA1=2.81")]


def test_a_vram_refusal_leaves_a_full_bystander_card_to_sd_cpp(monkeypatch):
    b, events = _vram_refusal_backend(
        monkeypatch, refusals = 1, planned_free_mib = {"CUDA0": 1800, "CUDA1": 6666}
    )
    images, _seeds = b._generate_server(b._state, **_gen_kwargs())
    assert len(images) == 1
    assert [e[1] for e in events if e[0] == "start"] == [("--max-vram", "CUDA1=3.25")]


def test_a_second_vram_refusal_in_the_same_request_is_surfaced(monkeypatch):
    b, events = _vram_refusal_backend(monkeypatch, refusals = 2)
    with pytest.raises(RuntimeError, match = "failed during weight preparation"):
        b._generate_server(b._state, **_gen_kwargs())
    assert len([e for e in events if e[0] == "start"]) == 1


def test_a_load_recovers_once_another_application_frees_the_card(monkeypatch):
    # The restart planned while the card was busy (466 MiB); the next request restarts under the first plan's budget.
    b, events = _vram_refusal_backend(
        monkeypatch,
        refusals = 3,
        restarted_plans = ({"CUDA1": 466}, {"CUDA1": 6666}),
    )
    with pytest.raises(RuntimeError, match = "failed during weight preparation"):
        b._generate_server(b._state, **_gen_kwargs())
    assert b._state.vram_budget == "3.25"
    assert b._state.server.planned_free_vram_mib == {"CUDA1": 466}
    images, _seeds = b._generate_server(b._state, **_gen_kwargs())
    assert len(images) == 1
    assert [e[1] for e in events if e[0] == "start"] == [("--max-vram", "3.25")] * 2


@pytest.mark.parametrize(
    "kwargs",
    [
        {"planned_free_mib": {}},
        {"planned_free_mib": {"CUDA1": 1800}},
        {"planned_free_mib": {"CUDA0": 45979, "CUDA1": 1800}},
        {"planned_free_mib": {"CUDA0": 6666}},
        {"max_vram_supported": False},
        {"planned_free_mib": {"CUDA0": 45979, "CUDA1": 5771}, "per_device_supported": False},
        {"device": "cpu"},
        {"error": "sd-server generation failed: generation_failed: invalid sampler"},
        {"error": _ALLOCATION_FAILURE.format(stage = "workspace allocation")},
        {"error": _ALLOCATION_FAILURE.format(stage = "weight preparation")},
        {
            "error": _VRAM_REFUSAL.replace(
                "Last output:\n",
                "Last output:\n[E] ggml: ggml_backend_cpu_buffer_type_alloc_buffer: failed to allocate buffer of "
                "size 220288512\n",
            )
        },
    ],
    ids = [
        "no_plan",
        "below_floor",
        "render_card_below_floor",
        "render_card_not_planned",
        "no_max_vram",
        "no_per_device_budgets",
        "cpu",
        "other_error",
        "workspace_allocation_failure",
        "weight_staging_allocation_failure",
        "host_allocation_failure",
    ],
)
def test_a_vram_refusal_without_a_usable_budget_is_surfaced_unchanged(monkeypatch, kwargs):
    b, events = _vram_refusal_backend(monkeypatch, refusals = 1, **kwargs)
    with pytest.raises(RuntimeError):
        b._generate_server(b._state, **_gen_kwargs())
    assert not [e for e in events if e[0] in ("start", "stop")]
    assert b._state.vram_budget is None


def test_a_device_loss_respawn_keeps_the_reduced_vram_budget(monkeypatch):
    b, events = _vram_refusal_backend(monkeypatch, refusals = 0, device = "vulkan")
    object.__setattr__(b._state, "vram_budget", "3.25")
    server = b._respawn_server_after_device_loss(
        b._state, "sd-server job failed: vk::Queue::submit: ErrorDeviceLost", threading.Event()
    )
    assert server is not None
    assert [e[1] for e in events if e[0] == "start"] == [("--max-vram", "3.25")]


@pytest.mark.parametrize("why", ["explicit_gpu", "no_cpu_rung", "fallback_disabled"])
def test_a_repeated_vulkan_device_loss_without_a_cpu_rung_errors_with_a_hint(monkeypatch, why):
    # A user-picked GPU is never moved to CPU behind their back, and an Arc / ROCm host (no CPU rung) or a disabled
    # Vulkan fallback keeps Vulkan: the second loss surfaces, with what to try.
    b, events, persisted = _repeated_device_loss_backend(
        monkeypatch, losses = 2, gpu_explicit = why == "explicit_gpu"
    )
    if why == "no_cpu_rung":
        monkeypatch.setattr(bk, "_vulkan_cpu_rung_applies", lambda: False)
    if why == "fallback_disabled":
        monkeypatch.setattr(bk, "fallback_accelerator_for", lambda acc: None)
    with pytest.raises(RuntimeError, match = "ErrorDeviceLost") as info:
        b._generate_server(b._state, **_gen_kwargs())
    assert "twice in a row" in str(info.value)
    assert not bk.output_shows_accelerator_failure(str(info.value))
    assert all(e[2] != ("--backend", "cpu") for e in events if e[0] == "start")
    assert b._cpu_backend_forced is False
    assert not persisted


@pytest.mark.parametrize("losses, device", [(1, "vulkan"), (2, "cpu")])
def test_a_device_loss_replacement_restages_the_hires_upscaler(
    monkeypatch, tmp_path, losses, device
):
    # Every replacement server (the same-build respawn after one lost device, the CPU backend after a second) has its
    # own scratch dir, and the old server's stop removed the upscaler staged in its own: the retry must stage the model
    # upscaler again under the server that runs it, or sd.cpp cannot find the hires upscaler file.
    from core.inference import diffusion_hires as hires

    b, events, persisted = _repeated_device_loss_backend(monkeypatch, losses = losses)
    server_cls = type(b._state.server)
    dirs: dict = {}
    seen: list = []

    def _lora_dir(self):
        if id(self) not in dirs:
            dirs[id(self)] = tmp_path / f"srv{len(dirs)}"
            dirs[id(self)].mkdir()
        return str(dirs[id(self)])

    real_img_gen = server_cls.img_gen

    def _img_gen(self, payload, **kw):
        seen.append((self.lora_dir, dict(payload["hires"])))
        return real_img_gen(self, payload, **kw)

    monkeypatch.setattr(server_cls, "lora_dir", property(_lora_dir), raising = False)
    monkeypatch.setattr(server_cls, "img_gen", _img_gen)
    staged: list = []

    def _stage(
        upscaler_id,
        scratch_dir,
        *,
        cancel = None,
    ):
        dest = Path(scratch_dir) / "hires_x.pth"
        dest.write_bytes(b"w")
        staged.append(dest)
        return "hires_x", dest

    monkeypatch.setattr(hires, "stage_sd_cpp_upscaler", _stage)
    plan = hires.SdCppHiresPlan(
        params = hires.HiresParams(upscaler = "realesrgan_x4plus"),
        base_width = 64,
        base_height = 64,
        target = (96, 96),
        refine_steps = 2,
    )
    images, _seeds = b._generate_server(b._state, hires_plan = plan, **_gen_kwargs())
    assert len(images) == 1
    assert b._state.device == device
    assert not persisted
    # One server per attempt, each sent the upscaler staged in its own dir.
    assert len(seen) == losses + 1
    assert len({d for d, _ in seen}) == losses + 1
    assert all(h["upscaler"] == "hires_x" for _, h in seen)
    assert [str(p.parent) for p in staged] == [d for d, _ in seen]
    assert b._state.server.lora_dir == seen[-1][0]
    assert not any(p.exists() for p in staged)


def test_an_explicit_gpu_pool_marks_the_native_load_explicit(monkeypatch):
    seen: dict = {}
    monkeypatch.setattr(
        "core.inference.diffusion_engine_router.off_torch_sd_cpp_device", lambda *a, **k: None
    )
    b = SdCppDiffusionBackend(engine = _FakeEngine())
    monkeypatch.setattr(b, "_run_load", lambda **kw: seen.update(kw))
    monkeypatch.setattr(bk, "resolve_selected_cuda_ordinal", lambda ids: None, raising = False)
    b.begin_load(
        repo_id = "unsloth/Z-Image-Turbo-GGUF", gguf_filename = "z-image-turbo-Q4_K_M.gguf", gpu_ids = [0]
    )
    deadline = time.monotonic() + 5
    while "gpu_explicit" not in seen and time.monotonic() < deadline:
        time.sleep(0.01)
    assert seen.get("gpu_explicit") is True


def _device_loss_backend(
    monkeypatch,
    tmp_path,
    *,
    on_start = None,
):
    """A loaded backend whose first job loses its Vulkan device; each server gets its own lora dir."""
    servers: list = []
    payloads: list = []

    class _FakeServer:
        def __init__(self, binary):
            self.binary = binary
            self.lora_dir = str(tmp_path / f"srv{len(servers)}")
            os.makedirs(self.lora_dir, exist_ok = True)
            self.stopped = False
            servers.append(self)

        def start(self, files, **kwargs):
            if on_start is not None:
                on_start(self)

        def stop(self):
            self.stopped = True
            shutil.rmtree(self.lora_dir, ignore_errors = True)

        def is_alive(self):
            return not self.stopped

        def img_gen(self, payload, **_kw):
            payloads.append((self, dict(payload)))
            if len(payloads) == 1:
                raise RuntimeError("sd-server job failed: vk::Queue::submit: ErrorDeviceLost")
            return [_png_bytes()]

    b = _loaded_backend()
    b._state = _pinned_state(b, policy_flags = (), device = "vulkan")
    object.__setattr__(b._state, "server", _FakeServer("/bin/sd-server-vulkan"))
    object.__setattr__(b._state, "mode", "server")
    monkeypatch.setattr(bk, "SdCppServer", _FakeServer)
    bk._accelerator_runtime_failures.clear()
    return b, servers, payloads


def _gen_kwargs(lora_resolved = ()):
    return dict(
        prompt = "a fox",
        negative_prompt = None,
        width = 64,
        height = 64,
        steps = 2,
        seed = 1,
        batch_size = 1,
        cfg_scale = None,
        flux_guidance = None,
        lora_resolved = list(lora_resolved),
        cancel = threading.Event(),
    )


def test_a_device_loss_retry_restages_the_loras_under_the_new_server(monkeypatch, tmp_path):
    # The old server's stop removes its scratch dir and the staged adapters: the retry must stage them again.
    from core.inference import diffusion_lora

    def _materialize(
        resolved,
        stage,
        real_files = False,
    ):
        os.makedirs(stage, exist_ok = True)
        (Path(stage) / "adapter.gguf").write_bytes(b"x")
        return [types.SimpleNamespace(path = str(Path(stage) / "adapter.gguf"), weight = 0.8)]

    monkeypatch.setattr(diffusion_lora, "materialize_native_dir", _materialize)
    b, servers, payloads = _device_loss_backend(monkeypatch, tmp_path)
    images, _seeds = b._generate_server(b._state, **_gen_kwargs(lora_resolved = ["adapter"]))
    assert len(images) == 1 and len(servers) == 2
    retry_server, retry_payload = payloads[-1]
    assert retry_server is servers[1]
    (entry,) = retry_payload["lora"]
    # Staged under the replacement's own lora dir (the file exists there when the retry runs).
    assert entry["path"] != payloads[0][1]["lora"][0]["path"]
    assert entry["multiplier"] == 0.8


def test_an_unload_during_the_respawn_leaves_no_live_server(monkeypatch, tmp_path):
    # unload() racing the restart must find the replacement (pending) or the handover must stop it.
    holder: dict = {}

    def _unload_mid_start(server):
        holder["backend"].unload()

    b, servers, _payloads = _device_loss_backend(monkeypatch, tmp_path, on_start = _unload_mid_start)
    holder["backend"] = b
    monkeypatch.setattr(b, "status", lambda: {})
    with pytest.raises(SdCppCancelled):
        b._generate_server(b._state, **_gen_kwargs())
    assert len(servers) == 2
    assert all(s.stopped for s in servers)
    assert b._state is None and b._pending_server is None


def test_a_status_poll_during_the_respawn_keeps_the_replacement(monkeypatch, tmp_path):
    # The UI polls /images/status while the respawn runs. The old server is already stopped then, and the idle-crash
    # reap used to clear _state, so the handover read an unload and killed the healthy replacement.
    holder: dict = {}
    polls: list = []

    def _poll_mid_start(server):
        polls.append(holder["backend"].status()["loaded"])

    b, servers, _payloads = _device_loss_backend(monkeypatch, tmp_path, on_start = _poll_mid_start)
    holder["backend"] = b
    images, _seeds = b._generate_server(b._state, **_gen_kwargs())
    assert len(images) == 1 and len(servers) == 2
    assert polls == [True]
    assert b._state is not None and b._state.server is servers[1]
    assert not servers[1].stopped and b._replacing_server is None
    # Once the generation is done, a server that really died is reaped again.
    servers[1].stopped = True
    assert b.status()["loaded"] is False


def test_a_status_poll_during_the_cpu_backend_restart_keeps_the_load(monkeypatch):
    import dataclasses

    class _FakeServer:
        def __init__(self, binary):
            self.binary = binary
            self.stopped = False

        def start(self, files, **kwargs):
            polls.append(b.status()["loaded"])

        def stop(self):
            self.stopped = True

        def is_alive(self):
            return not self.stopped

    polls: list = []
    b = _loaded_backend()
    b._state = _pinned_state(b, policy_flags = ("--offload-to-cpu",))
    object.__setattr__(b._state, "server", _FakeServer("/bin/sd-server"))
    object.__setattr__(b._state, "mode", "server")
    monkeypatch.setattr(bk, "find_sd_server_binary", lambda: "/bin/sd-server")
    monkeypatch.setattr(bk, "SdCppServer", _FakeServer)
    state = b._state
    server = b._restart_server_on_cpu_backend(
        state,
        "ggml_metal_op_encode_impl: unsupported op 'MUL_MAT' -> ggml_abort",
        threading.Event(),
    )
    assert server is not None and polls == [True] and b._state is state
    b._hand_over_replacement(dataclasses.replace(state, server = server), server, state.server)
    assert b._state.server is server and not server.stopped


def test_a_superseding_load_during_the_respawn_is_not_overwritten(monkeypatch, tmp_path):
    # A newer load that commits while the replacement starts owns _state: the handover must not publish the old
    # model's replacement over it, and the replacement must not be left running untracked.
    import dataclasses

    holder: dict = {}

    def _supersede_mid_start(server):
        b = holder["backend"]
        newer = _FakeNewer("/bin/sd-server-newer")
        holder["newer"] = newer
        with b._lock:
            b._state = dataclasses.replace(b._state, server = newer)

    class _FakeNewer:
        def __init__(self, binary):
            self.binary = binary
            self.stopped = False

        def stop(self):
            self.stopped = True

        def is_alive(self):
            return not self.stopped

    b, servers, payloads = _device_loss_backend(
        monkeypatch, tmp_path, on_start = _supersede_mid_start
    )
    holder["backend"] = b
    monkeypatch.setattr(b, "status", lambda: {})
    with pytest.raises(SdCppCancelled):
        b._generate_server(b._state, **_gen_kwargs())
    assert len(servers) == 2 and servers[1].stopped  # the stale replacement is stopped
    assert b._state.server is holder["newer"] and not holder["newer"].stopped
    assert len(payloads) == 1 and b._pending_server is None


def test_a_cancel_during_the_respawn_stops_the_replacement_start(monkeypatch, tmp_path):
    # cancel_generate() (or a superseding load) only sets the generation's event; the replacement start blocks for the
    # model load while _generate_lock is held, so it must notice and bail instead of loading for the full timeout.
    kwargs = _gen_kwargs()
    cancel = kwargs["cancel"]

    def _cancel_mid_start(server):
        cancel.set()
        deadline = time.monotonic() + 5.0
        while time.monotonic() < deadline:
            if server.stopped:
                raise RuntimeError("sd-server startup aborted before ready")
            time.sleep(0.01)

    b, servers, payloads = _device_loss_backend(monkeypatch, tmp_path, on_start = _cancel_mid_start)
    monkeypatch.setattr(b, "status", lambda: {})
    started = time.monotonic()
    with pytest.raises(SdCppCancelled):
        b._generate_server(b._state, **kwargs)
    assert time.monotonic() - started < 4.0
    assert len(servers) == 2 and all(s.stopped for s in servers)
    assert len(payloads) == 1  # no retry job was posted
    assert b._pending_server is None and b._replacing_server is None


def test_an_unload_before_the_respawn_starts_skips_it(monkeypatch, tmp_path):
    # unload() wins outright when it lands first: no replacement is started at all.
    b, servers, _payloads = _device_loss_backend(monkeypatch, tmp_path)
    state = b._state
    monkeypatch.setattr(b, "status", lambda: {})
    b.unload()
    assert (
        b._respawn_server_after_device_loss(
            state, "vk::Queue::submit: ErrorDeviceLost", threading.Event()
        )
        is None
    )
    assert len(servers) == 1 and b._replacing_server is None


@pytest.mark.parametrize(
    "device,ccs,expected",
    [
        ("cuda", [(10, 0)], {"GGML_CUDA_QUANT_CUBLAS_MIN_BATCH": "1024"}),
        ("cuda", [(8, 9)], None),
        ("cuda", [], None),
        ("cpu", [(10, 0)], None),
    ],
)
def test_cuda_sd_server_gets_the_bf16_cublas_route_by_compute_capability(
    monkeypatch, device, ccs, expected
):
    monkeypatch.delenv("GGML_CUDA_QUANT_CUBLAS_MIN_BATCH", raising = False)
    monkeypatch.setattr(bk, "_torch_cuda_capabilities", lambda ordinal: list(ccs))
    monkeypatch.setattr(
        bk.sd_cpp_args_mod, "gguf_quantized_weight_types", lambda path: frozenset({"Q8_0"})
    )
    b = SdCppDiffusionBackend()
    servers: list = []
    _run_server_load(monkeypatch, b, servers, device = device)
    assert servers and servers[-1].env == expected
    assert dict(b._state.child_env) == (expected or {})


@pytest.mark.parametrize(
    "weight_types", [frozenset({"Q4_K", "Q5_K"}), frozenset({"Q8_0", "Q4_K"}), None]
)
def test_a_k_quant_diffusion_gguf_keeps_mmq(monkeypatch, weight_types):
    monkeypatch.delenv("GGML_CUDA_QUANT_CUBLAS_MIN_BATCH", raising = False)
    monkeypatch.setattr(bk, "_torch_cuda_capabilities", lambda ordinal: [(10, 0)])
    seen: list = []
    monkeypatch.setattr(
        bk.sd_cpp_args_mod,
        "gguf_quantized_weight_types",
        lambda path: seen.append(path) or weight_types,
    )
    b = SdCppDiffusionBackend()
    servers: list = []
    _run_server_load(monkeypatch, b, servers, device = "cuda")
    assert seen == ["/m/z.gguf"]
    assert servers[-1].env is None
    assert dict(b._state.child_env) == {}


@pytest.mark.parametrize(
    "companions",
    [
        {"llm": ("/m/llm.gguf", frozenset({"Q4_K", "Q6_K"}))},
        {"llm": ("/m/llm.gguf", frozenset({"Q8_0"})), "vae": ("/m/vae.gguf", frozenset({"Q5_K"}))},
        {"llm": ("/m/llm.gguf", None)},
        {"qwen2vl": ("/m/te.gguf", frozenset({"Q4_K"})), "llm_vision": ("/m/mm.gguf", frozenset())},
    ],
)
def test_a_q8_0_diffusion_gguf_takes_the_route_whatever_its_companions_hold(
    monkeypatch, companions
):
    # The route follows the diffusion GGUF: a k-quant / unreadable encoder or VAE GGUF no longer keeps it on MMQ.
    monkeypatch.delenv("GGML_CUDA_QUANT_CUBLAS_MIN_BATCH", raising = False)
    monkeypatch.setattr(bk, "_torch_cuda_capabilities", lambda ordinal: [(10, 0)])
    types_by_path = {"/m/z.gguf": frozenset({"Q8_0"})}
    types_by_path.update(dict(companions.values()))
    seen: list = []
    monkeypatch.setattr(
        bk.sd_cpp_args_mod,
        "gguf_quantized_weight_types",
        lambda path: seen.append(path) or types_by_path[path],
    )
    paths = {"diffusion_model": "/m/z.gguf", "vae": "/m/vae.sft", "llm": "/m/llm.sft"}
    paths.update({kind: path for kind, (path, _types) in companions.items()})
    b = SdCppDiffusionBackend()
    servers: list = []
    _run_server_load(monkeypatch, b, servers, device = "cuda", asset_paths = paths)
    want = {"GGML_CUDA_QUANT_CUBLAS_MIN_BATCH": "1024"}
    assert servers[-1].env == want
    assert dict(b._state.child_env) == want
    assert seen == ["/m/z.gguf"]


def test_a_user_quant_cublas_value_reaches_sd_server_unchanged(monkeypatch):
    monkeypatch.setenv("GGML_CUDA_QUANT_CUBLAS_MIN_BATCH", "0")
    monkeypatch.setattr(bk, "_torch_cuda_capabilities", lambda ordinal: [(10, 0)])
    monkeypatch.setattr(
        bk.sd_cpp_args_mod, "gguf_quantized_weight_types", lambda path: frozenset({"Q8_0"})
    )
    b = SdCppDiffusionBackend()
    servers: list = []
    _run_server_load(monkeypatch, b, servers, device = "cuda")
    assert servers[-1].env is None


def test_the_capability_probe_is_bounded_when_the_driver_stalls(monkeypatch):
    import sys
    import time

    release = threading.Event()
    cuda = types.SimpleNamespace(is_available = lambda: release.wait(30) or True)
    fake_torch = types.SimpleNamespace(version = types.SimpleNamespace(hip = None), cuda = cuda)
    monkeypatch.setitem(sys.modules, "torch", fake_torch)
    start = time.monotonic()
    try:
        assert bk._torch_cuda_capabilities(None, timeout_s = 0.2) == []
    finally:
        release.set()
    assert time.monotonic() - start < 5


def test_the_cublas_route_follows_a_deferred_install_onto_cuda(monkeypatch):
    # Placed on the CPU bundle first; the deferred upgrade lands the CUDA build, so the committed env must follow.
    monkeypatch.delenv("GGML_CUDA_QUANT_CUBLAS_MIN_BATCH", raising = False)
    monkeypatch.setattr(bk, "_torch_cuda_capabilities", lambda ordinal: [(10, 0)])
    monkeypatch.setattr(
        bk.sd_cpp_args_mod, "gguf_quantized_weight_types", lambda path: frozenset({"Q8_0"})
    )
    installed = {"accelerator": "cpu"}
    monkeypatch.setattr(bk, "_installed_accelerator_of", lambda binary: installed["accelerator"])

    def _upgrade(self, server_binary, **_kw):
        installed["accelerator"] = "cuda"
        return server_binary

    monkeypatch.setattr(SdCppDiffusionBackend, "_upgraded_or_refused", _upgrade)
    monkeypatch.setattr(
        SdCppDiffusionBackend, "_resolved_accelerator", staticmethod(lambda card = None: "cuda")
    )
    monkeypatch.setattr(bk, "_managed_tree_in_use", lambda: True)
    b = SdCppDiffusionBackend()
    servers: list = []
    _run_server_load(monkeypatch, b, servers, device = "cuda")
    assert b._state.device == "cuda"
    assert servers[-1].env == {"GGML_CUDA_QUANT_CUBLAS_MIN_BATCH": "1024"}
    assert dict(b._state.child_env) == {"GGML_CUDA_QUANT_CUBLAS_MIN_BATCH": "1024"}


@pytest.mark.parametrize(
    "resolved,expected", [("CUDA1", {"GGML_CUDA_QUANT_CUBLAS_MIN_BATCH": "1024"}), (None, None)]
)
def test_an_unresolved_pin_judges_every_visible_card(monkeypatch, resolved, expected):
    # Card 1 is an A100, card 0 (sd.cpp's default) an Ada card. Without the pin sd.cpp runs on card 0.
    monkeypatch.delenv("GGML_CUDA_QUANT_CUBLAS_MIN_BATCH", raising = False)
    caps = {None: [(8, 9), (8, 0)], 0: [(8, 9)], 1: [(8, 0)]}
    monkeypatch.setattr(bk, "_torch_cuda_capabilities", lambda ordinal: list(caps[ordinal]))
    monkeypatch.setattr(
        bk.sd_cpp_args_mod, "gguf_quantized_weight_types", lambda path: frozenset({"Q8_0"})
    )
    monkeypatch.setattr(bk, "sd_cpp_device_name_for_ordinal", lambda binary, ordinal: resolved)
    monkeypatch.setattr(bk, "physical_card_name", lambda ordinal: (None, None))
    monkeypatch.setattr(bk, "sd_cpp_device_named", lambda binary, name, position = None: None)
    b = SdCppDiffusionBackend()
    servers: list = []
    _run_server_load(monkeypatch, b, servers, device = "cuda", gpu_ordinal = 1)
    assert servers[-1].env == expected
    assert dict(b._state.child_env) == (expected or {})