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.

129 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

"""Prebuilt sd-cli asset resolver tests: host to release-asset mapping against a fixed asset list."""

from __future__ import annotations

import sys
from pathlib import Path


def _shared_setup_1(monkeypatch, tmp_path):
    import core.inference.sd_cpp_backend as bk

    root = _managed_tree(tmp_path, monkeypatch, accelerator = "cpu")
    server = root / "sd-bin" / _SERVER
    server.write_bytes(b"cpu-build")
    monkeypatch.setattr(bk, "find_sd_server_binary", lambda: str(server))
    monkeypatch.setattr(bk, "_server_binary_runnable", lambda *_a, **_k: True)
    monkeypatch.setattr(bk, "_failed_accelerator_upgrades", set())
    return bk, root, server


def _shared_setup_2(tmp_path):
    if not _can_create_symlinks(tmp_path):
        pytest.skip("symlink creation needs privilege on this host (Windows non-dev-mode)")
    target = tmp_path / "install"
    target.mkdir()
    return target


def _shared_setup_3(monkeypatch, tmp_path):
    import core.inference.sd_cpp_backend as bk

    home = tmp_path / "sd-home" / "studio"
    home.mkdir(parents = True)
    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(home))
    legacy = tmp_path / "sd-home" / "stable-diffusion.cpp"
    (legacy / "sd-bin").mkdir(parents = True)
    (legacy / ".unsloth-studio-owned").touch()
    sdmod._write_install_record(legacy, accelerator = "cpu", repo = "r", tag = "t")
    return bk, home, legacy


def _shared_setup_4(bk, monkeypatch):
    monkeypatch.setattr(bk, "_install_allowed", lambda: True)
    monkeypatch.setattr(
        bk, "resolve_diffusion_device_target", lambda: types.SimpleNamespace(backend = "cuda")
    )


def _shared_setup_5(monkeypatch):
    zb = _zip_with_sd_cli()
    _stub_two_repos(
        monkeypatch,
        mirror_serves = False,
        upstream_serves = True,
        zip_bytes = zb,
        digest = "sha256:" + hashlib.sha256(zb).hexdigest(),
    )


def _shared_setup_6(monkeypatch):
    monkeypatch.setattr(
        sdmod,
        "_maybe_fetch_windows_cudart",
        lambda *_a, **_k: (_ for _ in ()).throw(RuntimeError("cudart 404")),
    )


def _shared_setup_7(tmp_path):
    archive = tmp_path / "libs.zip"
    with zipfile.ZipFile(archive, "w") as zf:
        zf.writestr("libwebp.so.7.2.0", b"ELFpayload")
        _link_member(zf, "libwebp.so.7", "libwebp.so.7.2.0")
    return archive


def _shared_setup_8(monkeypatch, tmp_path):
    import core.inference.sd_cpp_backend as bk

    root = _managed_tree(tmp_path, monkeypatch, accelerator = "cpu")
    cli = root / "sd-bin" / _CLI
    return bk, cli, root


def _shared_setup_9(monkeypatch, tmp_path):
    import core.inference.sd_cpp_backend as bk

    root = _managed_tree(tmp_path, monkeypatch, accelerator = "cuda")
    server = root / "sd-bin" / _SERVER
    server.write_bytes(b"cuda-build")
    return bk, root, server


def _shared_setup_10(tmp_path):
    root = tmp_path / "sd"
    root.mkdir()
    with open(root / sdmod.INSTALL_RECORD, "w", encoding = "utf-8") as f:
        json.dump({"accelerator": "cpu", "repo": "r", "tag": "old"}, f)
    sdmod._INSTALLED_ACCELERATOR_MEMO.clear()
    return root


def _shared_setup_11(root):
    old = root / "build" / "bin" / _CLI
    old.parent.mkdir(parents = True)
    old.write_bytes(b"old-cpu-cli")
    new = root / "sd-bundle-cuda12" / "bin" / _CLI
    new.parent.mkdir(parents = True)
    return new, old


def _shared_setup_12(archive, target):
    with zipfile.ZipFile(archive) as zf:
        supplied = sdmod._archive_binary_paths(zf, target)
        _safe_extractall(zf, target)
    sdmod._discard_superseded_binaries(target, supplied)


def _shared_setup_13(archive, target):
    with zipfile.ZipFile(archive) as zf:
        with pytest.raises(RuntimeError, match = "symlink cycle"):
            _safe_extractall(zf, target)
    assert not any(target.iterdir())


_STUDIO = Path(__file__).resolve().parents[2]
if str(_STUDIO) not in sys.path:
    sys.path.insert(0, str(_STUDIO))

import os  # noqa: E402
import hashlib  # noqa: E402
import builtins  # noqa: E402
import types  # noqa: E402
import threading  # noqa: E402
import time  # noqa: E402
import io  # noqa: E402
import re  # noqa: E402
import json  # noqa: E402
import urllib.error  # noqa: E402
import zipfile  # noqa: E402

import pytest  # noqa: E402

import install_sd_cpp_prebuilt as sdmod  # noqa: E402
from install_sd_cpp_prebuilt import (  # noqa: E402
    DEFAULT_REPO,
    DEFAULT_TAG,
    _fetch_release,
    _pinned_tag,
    _repo,
    _safe_extractall,
    _verify_sha256,
    default_install_dir,
    install,
    resolve_release_asset,
    upstream_tag_for,
)

_ASSETS = [
    "cudart-sd-bin-win-cu12-x64.zip",
    "sd-master-8caa3f9-bin-Darwin-macOS-15.7.7-arm64.zip",
    "sd-master-8caa3f9-bin-Linux-Ubuntu-24.04-x86_64-rocm-7.13.0.zip",
    "sd-master-8caa3f9-bin-Linux-Ubuntu-24.04-x86_64-rocm-7.2.1.zip",
    "sd-master-8caa3f9-bin-Linux-Ubuntu-24.04-x86_64-vulkan.zip",
    "sd-master-8caa3f9-bin-Linux-Ubuntu-24.04-x86_64.zip",
    "sd-master-8caa3f9-bin-win-avx-x64.zip",
    "sd-master-8caa3f9-bin-win-avx2-x64.zip",
    "sd-master-8caa3f9-bin-win-avx512-x64.zip",
    "sd-master-8caa3f9-bin-win-cuda12-x64.zip",
    "sd-master-8caa3f9-bin-win-noavx-x64.zip",
    "sd-master-8caa3f9-bin-win-rocm-7.13.0-x64.zip",
    "sd-master-8caa3f9-bin-win-vulkan-x64.zip",
]


def _resolve(
    system,
    machine,
    accelerator = "auto",
):
    return resolve_release_asset(_ASSETS, system = system, machine = machine, accelerator = accelerator)


def test_macos_arm64_picks_darwin_arm64():
    assert _resolve("Darwin", "arm64") == "sd-master-8caa3f9-bin-Darwin-macOS-15.7.7-arm64.zip"
    assert _resolve("Darwin", "aarch64").startswith("sd-master") and "arm64" in _resolve(
        "Darwin", "aarch64"
    )


def test_macos_intel_has_no_prebuilt():
    # only an arm64 Darwin asset exists -> Intel Macs must build from source
    assert _resolve("Darwin", "x86_64") is None


def test_linux_x86_64_auto_picks_plain_cpu_build():
    assert _resolve("Linux", "x86_64") == "sd-master-8caa3f9-bin-Linux-Ubuntu-24.04-x86_64.zip"


def test_linux_vulkan_and_rocm_select_accelerator_builds():
    assert (
        _resolve("Linux", "x86_64", "vulkan")
        == "sd-master-8caa3f9-bin-Linux-Ubuntu-24.04-x86_64-vulkan.zip"
    )
    assert "rocm" in _resolve("Linux", "x86_64", "rocm")


def test_linux_arm64_has_no_prebuilt():
    assert _resolve("Linux", "aarch64") is None


def test_windows_auto_picks_avx2():
    assert _resolve("Windows", "AMD64") == "sd-master-8caa3f9-bin-win-avx2-x64.zip"


@pytest.mark.parametrize("accelerator", ["auto", "cpu"])
@pytest.mark.parametrize("reverse", [False, True])
def test_windows_cpu_selection_with_unsloth_vulkan_asset(accelerator, reverse):
    cpu = "sd-master-813-bfbef5b-u1d02858-bin-win-cpu-x64.zip"
    vulkan = "sd-master-813-bfbef5b-u1d02858-bin-win-vulkan-x64.zip"
    assets = [cpu, vulkan]
    if reverse:
        assets.reverse()
    assert (
        resolve_release_asset(assets, system = "Windows", machine = "AMD64", accelerator = accelerator)
        == cpu
    )


@pytest.mark.parametrize("accelerator", ["auto", "cpu"])
@pytest.mark.parametrize("gpu", ["cuda12", "vulkan", "rocm", "sycl", "musa"])
def test_windows_cpu_selection_never_uses_accelerator_build(accelerator, gpu):
    assets = [f"sd-master-test-bin-win-{gpu}-avx2-x64.zip"]
    assert (
        resolve_release_asset(assets, system = "Windows", machine = "AMD64", accelerator = accelerator)
        is None
    )
    cpu = "sd-master-test-bin-win-cpu-x64.zip"
    assert (
        resolve_release_asset(
            [*assets, cpu], system = "Windows", machine = "AMD64", accelerator = accelerator
        )
        == cpu
    )


@pytest.mark.parametrize("accelerator", ["auto", "cpu"])
def test_windows_cpu_selection_keeps_upstream_avx2_preference(accelerator):
    avx2 = "sd-master-test-bin-win-avx2-x64.zip"
    assets = ["sd-master-test-bin-win-cpu-x64.zip", avx2]
    assert (
        resolve_release_asset(assets, system = "Windows", machine = "AMD64", accelerator = accelerator)
        == avx2
    )


def test_windows_cuda_picks_cuda12():
    assert _resolve("Windows", "AMD64", "cuda") == "sd-master-8caa3f9-bin-win-cuda12-x64.zip"


_CUDA_SPLIT = [
    "sd-x-bin-Linux-Ubuntu-22.04-x86_64-cuda12.zip",
    "sd-x-bin-Linux-Ubuntu-22.04-x86_64-cuda13.zip",
    "sd-x-bin-win-cuda12-x64.zip",
    "sd-x-bin-win-cuda13-x64.zip",
    "sd-x-bin-win-cpu-x64.zip",
]


@pytest.mark.parametrize(
    "system, machine, major, want",
    [
        ("Linux", "x86_64", "13", "sd-x-bin-Linux-Ubuntu-22.04-x86_64-cuda13.zip"),
        ("Linux", "x86_64", "12", "sd-x-bin-Linux-Ubuntu-22.04-x86_64-cuda12.zip"),
        ("Windows", "AMD64", "13", "sd-x-bin-win-cuda13-x64.zip"),
        ("Windows", "AMD64", "12", "sd-x-bin-win-cuda12-x64.zip"),
        ("Windows", "AMD64", None, "sd-x-bin-win-cuda12-x64.zip"),
    ],
)
def test_cuda_bundles_follow_the_host_runtime_major(system, machine, major, want):
    assert (
        resolve_release_asset(
            _CUDA_SPLIT, system = system, machine = machine, accelerator = "cuda", cuda_major = major
        )
        == want
    )


def test_a_release_without_the_hosts_cuda_major_still_offers_its_cuda_build():
    for system, machine in (("Linux", "x86_64"), ("Windows", "AMD64")):
        got = resolve_release_asset(
            [n for n in _CUDA_SPLIT if "cuda13" not in n],
            system = system,
            machine = machine,
            accelerator = "cuda",
            cuda_major = "13",
        )
        assert got is not None and "cuda12" in got


def test_windows_vulkan_picks_vulkan():
    assert _resolve("Windows", "AMD64", "vulkan") == "sd-master-8caa3f9-bin-win-vulkan-x64.zip"


def test_windows_arm64_takes_no_x64_build():
    """An x64 zip cannot run natively on a Windows arm64 host. Reporting no match lets the caller
    fall back instead of downloading and installing a binary that fails on first launch."""
    for accel in ("auto", "cuda", "vulkan", "rocm"):
        assert _resolve("Windows", "ARM64", accel) is None
        assert _resolve("Windows", "aarch64", accel) is None


def test_windows_arm64_picks_an_arm64_build_when_one_exists():
    assets = [*_ASSETS, "sd-master-8caa3f9-bin-win-avx2-arm64.zip"]
    assert (
        resolve_release_asset(assets, system = "Windows", machine = "ARM64", accelerator = "auto")
        == "sd-master-8caa3f9-bin-win-avx2-arm64.zip"
    )


def test_cudart_runtime_archive_never_selected():
    for accel in ("auto", "cuda", "vulkan", "rocm"):
        chosen = _resolve("Windows", "AMD64", accel)
        assert chosen is None or not chosen.startswith("cudart")


def test_default_install_dir_is_sibling_of_llama(monkeypatch):
    monkeypatch.delenv("UNSLOTH_STUDIO_HOME", raising = False)
    monkeypatch.delenv("STUDIO_HOME", raising = False)
    d = default_install_dir()
    assert d.name == "stable-diffusion.cpp"
    assert d.parent.name == ".unsloth"


def test_pinned_tag_default_and_override(monkeypatch):
    monkeypatch.delenv("UNSLOTH_SD_CPP_TAG", raising = False)
    assert _pinned_tag() == DEFAULT_TAG
    monkeypatch.setenv("UNSLOTH_SD_CPP_TAG", "master-999-deadbee")
    assert _pinned_tag() == "master-999-deadbee"
    monkeypatch.setenv("UNSLOTH_SD_CPP_TAG", "")
    assert _pinned_tag() is None


def test_repo_default_and_override(monkeypatch):
    monkeypatch.delenv("UNSLOTH_SD_CPP_REPO", raising = False)
    assert _repo() == DEFAULT_REPO == "unslothai/stable-diffusion.cpp"
    monkeypatch.setenv("UNSLOTH_SD_CPP_REPO", "leejet/stable-diffusion.cpp")
    assert _repo() == "leejet/stable-diffusion.cpp"


def test_verify_sha256_accepts_matching_digest(tmp_path):
    f = tmp_path / "asset.zip"
    f.write_bytes(b"hello sd-cli")
    digest = "sha256:" + hashlib.sha256(b"hello sd-cli").hexdigest()
    _verify_sha256(f, digest)


def test_verify_sha256_rejects_mismatch(tmp_path):
    f = tmp_path / "asset.zip"
    f.write_bytes(b"tampered")
    bad = "sha256:" + hashlib.sha256(b"original").hexdigest()
    with pytest.raises(RuntimeError, match = "sha256 mismatch"):
        _verify_sha256(f, bad)


def test_verify_sha256_skips_when_absent_or_unknown(tmp_path):
    f = tmp_path / "asset.zip"
    f.write_bytes(b"x")
    _verify_sha256(f, None)
    _verify_sha256(f, "md5:abc")


def test_fetch_release_falls_back_to_latest_on_404(monkeypatch):
    calls: list[str] = []

    class _Resp:
        def __enter__(self):
            return self

        def __exit__(self, *a):
            return False

        def read(self):
            return json.dumps({"tag_name": "latest-xyz", "assets": []}).encode()

    def fake_urlopen(req, timeout = 30.0):
        url = getattr(req, "full_url", req)
        calls.append(url)
        if "/tags/" in url:
            raise urllib.error.HTTPError(url, 404, "not found", None, None)
        return _Resp()

    monkeypatch.setattr(sdmod, "auth_safe_open", fake_urlopen)
    rel = _fetch_release("gone-tag", repo = "leejet/stable-diffusion.cpp")
    assert rel["tag_name"] == "latest-xyz"
    assert any("/tags/gone-tag" in c for c in calls) and any(c.endswith("/latest") for c in calls)


def test_fetch_release_propagates_non_404(monkeypatch):
    def fake_urlopen(req, timeout = 30.0):
        url = getattr(req, "full_url", req)
        raise urllib.error.HTTPError(url, 403, "rate limited", None, None)

    monkeypatch.setattr(sdmod, "auth_safe_open", fake_urlopen)
    with pytest.raises(urllib.error.HTTPError):
        _fetch_release("any-tag")


def _zip_with_sd_cli() -> bytes:
    buf = io.BytesIO()
    with zipfile.ZipFile(buf, "w") as zf:
        zf.writestr(f"build/bin/{_CLI}", b"#!/bin/sh\necho sd-cli\n")
    return buf.getvalue()


def _stub_release(monkeypatch, *, zip_bytes: bytes, digest: str):
    name = "sd-master-deadbee-bin-Linux-Ubuntu-24.04-x86_64.zip"
    release = {
        "tag_name": "master-1-deadbee",
        "assets": [
            {
                "name": name,
                "browser_download_url": f"https://example.invalid/{name}",
                "digest": digest,
            }
        ],
    }
    monkeypatch.setattr(sdmod, "_fetch_release", lambda *a, **k: release)
    monkeypatch.setattr(sdmod, "_download", lambda url, dest, **k: dest.write_bytes(zip_bytes))
    monkeypatch.setattr(sdmod.platform, "system", lambda: "Linux")
    monkeypatch.setattr(sdmod.platform, "machine", lambda: "x86_64")
    return name


def test_install_downloads_verifies_extracts(tmp_path, monkeypatch):
    zb = _zip_with_sd_cli()
    name = _stub_release(
        monkeypatch, zip_bytes = zb, digest = "sha256:" + hashlib.sha256(zb).hexdigest()
    )
    sd_cli = install(install_dir = tmp_path)
    assert sd_cli.name == _CLI and sd_cli.is_file()
    assert not (tmp_path / name).exists()
    # The ownership marker lets the uninstaller delete an Unsloth-installed sd.cpp while keeping a user's own checkout.
    assert (tmp_path / ".unsloth-studio-owned").is_file()


def test_install_into_empty_dir_claims_ownership(tmp_path, monkeypatch):
    zb = _zip_with_sd_cli()
    _stub_release(monkeypatch, zip_bytes = zb, digest = "sha256:" + hashlib.sha256(zb).hexdigest())
    empty = tmp_path / "sdcpp"
    empty.mkdir()
    install(install_dir = empty)
    assert (empty / ".unsloth-studio-owned").is_file()


def test_install_into_nonempty_unowned_dir_is_refused(tmp_path, monkeypatch):
    zb = _zip_with_sd_cli()
    _stub_release(monkeypatch, zip_bytes = zb, digest = "sha256:" + hashlib.sha256(zb).hexdigest())
    target = tmp_path / "stable-diffusion.cpp"
    target.mkdir()
    user_file = target / "USER_WORK"
    user_file.write_text("keep", encoding = "utf-8")

    with pytest.raises(RuntimeError, match = "not an Unsloth-managed directory"):
        install(install_dir = target)

    assert user_file.read_text(encoding = "utf-8") == "keep"
    assert not (target / ".unsloth-studio-owned").exists()
    assert list(target.iterdir()) == [user_file]


def test_reinstall_into_owned_dir_keeps_ownership(tmp_path, monkeypatch):
    zb = _zip_with_sd_cli()
    _stub_release(monkeypatch, zip_bytes = zb, digest = "sha256:" + hashlib.sha256(zb).hexdigest())
    target = tmp_path / "stable-diffusion.cpp"
    target.mkdir()
    (target / ".unsloth-studio-owned").touch()
    (target / "old-junk").write_text("x", encoding = "utf-8")

    install(install_dir = target)
    assert (target / ".unsloth-studio-owned").is_file()


def test_install_sha256_mismatch_raises_and_cleans_up(tmp_path, monkeypatch):
    zb = _zip_with_sd_cli()
    name = _stub_release(monkeypatch, zip_bytes = zb, digest = "sha256:" + "0" * 64)
    with pytest.raises(RuntimeError, match = "sha256 mismatch"):
        install(install_dir = tmp_path)
    assert not (tmp_path / name).exists()


def test_partial_install_failure_is_reclaimed_on_retry(tmp_path, monkeypatch):
    # Ownership is marked before extraction, so a retry recognises crash debris as ours.
    zb = _zip_with_sd_cli()
    _stub_release(monkeypatch, zip_bytes = zb, digest = "sha256:" + hashlib.sha256(zb).hexdigest())
    target = tmp_path / "sdcpp"

    state = {"failed": False}

    def flaky_cudart(*a, **k):
        if not state["failed"]:
            state["failed"] = True
            raise RuntimeError("simulated interrupted post-extract step")

    monkeypatch.setattr(sdmod, "_maybe_fetch_windows_cudart", flaky_cudart)

    with pytest.raises(RuntimeError, match = "simulated interrupted"):
        install(install_dir = target)
    assert (target / ".unsloth-studio-owned").is_file()
    assert any(target.iterdir())

    sd_cli = install(install_dir = target)
    assert sd_cli.name == _CLI and sd_cli.is_file()
    assert (target / ".unsloth-studio-owned").is_file()


def test_safe_extractall_rejects_path_traversal(tmp_path):
    target = tmp_path / "install"
    target.mkdir()
    archive = tmp_path / "evil.zip"
    with zipfile.ZipFile(archive, "w") as zf:
        zf.writestr(_CLI, b"ok")
        zf.writestr("../escape.txt", b"pwned")
    with zipfile.ZipFile(archive) as zf:
        with pytest.raises(RuntimeError, match = "unsafe path"):
            _safe_extractall(zf, target)
    assert not (tmp_path / "escape.txt").exists()


def test_safe_extractall_restores_symlink_members(tmp_path):
    target = _shared_setup_2(tmp_path)
    archive = tmp_path / "libs.zip"
    # Unix symlink mode in external_attr, target as data: how zipfile and sd.cpp releases ship lib*.so.
    with zipfile.ZipFile(archive, "w") as zf:
        zf.writestr("libwebpmux.so.3.1.2", b"\x7fELFpayload")
        info = zipfile.ZipInfo("libwebpmux.so.3")
        info.create_system = 3
        info.external_attr = (0o120777 << 16) | 0o777
        zf.writestr(info, "libwebpmux.so.3.1.2")

    with zipfile.ZipFile(archive) as zf:
        _safe_extractall(zf, target)

    link = target / "libwebpmux.so.3"
    real = target / "libwebpmux.so.3.1.2"
    assert link.is_symlink()
    assert link.readlink().name == "libwebpmux.so.3.1.2"
    # Compare bytes: stat() follows the link, so a size check cannot fail.
    assert link.resolve(strict = True) == real.resolve()
    assert link.read_bytes() == b"\x7fELFpayload"
    assert not real.is_symlink()


_CLI = sdmod._binary_names()[0]
_SERVER = sdmod._binary_names()[1]


def _can_create_symlinks(tmp_path) -> bool:
    probe = tmp_path / "_link_probe"
    try:
        probe.symlink_to("target.txt")
    except OSError:
        return False
    probe.unlink(missing_ok = True)
    return True


def _link_member(
    zf,
    name: str,
    link_target: str,
    create_system: int = 3,
) -> None:
    """The symlink member CPython's zipfile produces: Unix link mode, target as the data."""
    info = zipfile.ZipInfo(name)
    info.create_system = create_system
    info.external_attr = (0o120777 << 16) | 0o777
    zf.writestr(info, link_target)


def test_safe_extractall_rejects_escaping_symlink(tmp_path):
    # Validation precedes every write, so this holds even where symlinks need privilege.
    target = tmp_path / "install"
    target.mkdir()
    (target / _CLI).write_bytes(b"working binary from the previous install")
    archive = tmp_path / "evil.zip"
    with zipfile.ZipFile(archive, "w") as zf:
        zf.writestr(_CLI, b"replacement from the rejected archive")
        _link_member(zf, "libescape.so", "../../outside.so")
    with zipfile.ZipFile(archive) as zf:
        with pytest.raises(RuntimeError, match = "unsafe symlink"):
            _safe_extractall(zf, target)
    assert not (tmp_path / "outside.so").exists()
    assert (target / _CLI).read_bytes() == b"working binary from the previous install"
    assert not (target / "libescape.so").exists()


@pytest.mark.parametrize(
    "link_target",
    [
        "/etc/passwd",
        "C:outside.dll",  # Windows drive-relative: Win32 resolves it off that drive's cwd
        "",
        "real\x00.so",
        "libself.so",  # self-referential, the shape the old resolve() bug produced
    ],
)
def test_safe_extractall_rejects_malformed_symlink_targets(tmp_path, link_target):
    target = tmp_path / "install"
    target.mkdir()
    archive = tmp_path / "evil.zip"
    with zipfile.ZipFile(archive, "w") as zf:
        _link_member(zf, "libself.so", link_target)
    with zipfile.ZipFile(archive) as zf:
        with pytest.raises(RuntimeError, match = "unsafe symlink"):
            _safe_extractall(zf, target)
    assert not any(target.iterdir())


def test_safe_extractall_rejects_a_symlink_redirected_parent(tmp_path):
    if not _can_create_symlinks(tmp_path):
        pytest.skip("symlink creation needs privilege on this host (Windows non-dev-mode)")
    # An earlier member can turn a later member's parent into a link; preflight refuses it.
    target = tmp_path / "install"
    target.mkdir()
    (target / _CLI).write_bytes(b"working binary from the previous install")
    outside = tmp_path / "outside_dir"
    outside.mkdir()
    victim = outside / "victim"
    victim.write_bytes(b"outside the install dir")
    archive = tmp_path / "evil.zip"
    with zipfile.ZipFile(archive, "w") as zf:
        zf.writestr(_CLI, b"replacement from the rejected archive")
        _link_member(zf, "a", ".")
        _link_member(zf, "a/out", "../outside_dir")
        _link_member(zf, "a/out/victim", "replacement")
    with zipfile.ZipFile(archive) as zf:
        with pytest.raises(RuntimeError, match = "under a symlink member"):
            _safe_extractall(zf, target)
    assert not victim.is_symlink()
    assert victim.read_bytes() == b"outside the install dir"
    assert (target / _CLI).read_bytes() == b"working binary from the previous install"
    assert sorted(p.name for p in target.iterdir()) == [_CLI]


def test_the_sweep_keeps_a_binary_supplied_under_a_symlinked_directory(tmp_path):
    if not _can_create_symlinks(tmp_path):
        pytest.skip("symlink creation needs privilege on this host (Windows non-dev-mode)")
    # rglob reports the binary under the real dir, so a lexical path would get it swept.
    target = tmp_path / "install"
    target.mkdir()
    (target / "real").mkdir()
    (target / "build").mkdir()
    (target / "build" / "bin").symlink_to(target / "real")
    archive = tmp_path / "bundle.zip"
    with zipfile.ZipFile(archive, "w") as zf:
        zf.writestr(f"build/bin/{_CLI}", b"\x7fELF new binary")

    _shared_setup_12(archive, target)

    assert sdmod._locate_sd_cli(target) is not None
    assert (target / "real" / _CLI).read_bytes() == b"\x7fELF new binary"


def test_the_sweep_keeps_a_binary_whose_parent_link_the_archive_replaces(tmp_path):
    if not _can_create_symlinks(tmp_path):
        pytest.skip("symlink creation needs privilege on this host (Windows non-dev-mode)")
    # A directory member replaces the previous bundle's dir symlink, invalidating pre-resolved keys.
    target = tmp_path / "install"
    target.mkdir()
    (target / "real").mkdir()
    (target / "build").mkdir()
    (target / "build" / "bin").symlink_to(target / "real")
    archive = tmp_path / "bundle.zip"
    with zipfile.ZipFile(archive, "w") as zf:
        zf.writestr("build/bin/", b"")
        zf.writestr(f"build/bin/{_CLI}", b"\x7fELF new binary")

    _shared_setup_12(archive, target)

    assert sdmod._locate_sd_cli(target) is not None


def test_safe_extractall_rejects_an_existing_cycle_before_writing_anything(tmp_path):
    if not _can_create_symlinks(tmp_path):
        pytest.skip("symlink creation needs privilege on this host (Windows non-dev-mode)")
    # The cycle closes through a link the previous bundle left, so it is only visible on disk.
    target = tmp_path / "install"
    target.mkdir()
    (target / "b").symlink_to("a")
    (target / _CLI).write_bytes(b"\x7fELF working binary")
    archive = tmp_path / "evil.zip"
    with zipfile.ZipFile(archive, "w") as zf:
        zf.writestr(_CLI, b"replacement from the rejected archive")
        _link_member(zf, "a", "b")
    with zipfile.ZipFile(archive) as zf:
        with pytest.raises(RuntimeError, match = "symlink cycle"):
            _safe_extractall(zf, target)
    assert (target / _CLI).read_bytes() == b"\x7fELF working binary"
    assert not (target / "a").exists() and not (target / "a").is_symlink()


def test_the_sweep_keeps_a_binary_the_bundle_ships_as_a_symlink(tmp_path):
    if not _can_create_symlinks(tmp_path):
        pytest.skip("symlink creation needs privilege on this host (Windows non-dev-mode)")
    # Resolving the final component would spell the binary sd-cli-1.2, which the sweep would take.
    target = tmp_path / "install"
    target.mkdir()
    archive = tmp_path / "bundle.zip"
    with zipfile.ZipFile(archive, "w") as zf:
        zf.writestr(f"build/bin/{_CLI}-1.2", b"\x7fELF new binary")
        _link_member(zf, f"build/bin/{_CLI}", f"{_CLI}-1.2")

    _shared_setup_12(archive, target)

    assert (target / "build" / "bin" / _CLI).is_symlink()
    assert sdmod._locate_sd_cli(target) is not None


def test_safe_extractall_allows_a_parent_symlinked_inside_the_tree(tmp_path):
    if not _can_create_symlinks(tmp_path):
        pytest.skip("symlink creation needs privilege on this host (Windows non-dev-mode)")
    # The re-check asks whether the parent resolves inside the install dir, not whether it is link-free.
    target = tmp_path / "install"
    target.mkdir()
    (target / "real_bin").mkdir()
    (target / "build").mkdir()
    (target / "build" / "bin").symlink_to(target / "real_bin")
    archive = tmp_path / "libs.zip"
    with zipfile.ZipFile(archive, "w") as zf:
        zf.writestr("build/bin/libwebp.so.7.2.0", b"\x7fELFpayload")
        _link_member(zf, "build/bin/libwebp.so.7", "libwebp.so.7.2.0")

    with zipfile.ZipFile(archive) as zf:
        _safe_extractall(zf, target)

    link = target / "build" / "bin" / "libwebp.so.7"
    assert link.is_symlink()
    assert link.read_bytes() == b"\x7fELFpayload"


def test_safe_extractall_drops_a_stale_link_at_a_regular_members_path(tmp_path):
    if not _can_create_symlinks(tmp_path):
        pytest.skip("symlink creation needs privilege on this host (Windows non-dev-mode)")
    # Upstream ships links, the mirror copies; extractall opens "wb", writing through a stale link.
    target = tmp_path / "install"
    target.mkdir()
    (target / "real").write_bytes(b"old real lib")
    (target / "name").symlink_to("real")
    archive = tmp_path / "next.zip"
    with zipfile.ZipFile(archive, "w") as zf:
        zf.writestr("name", b"new name bytes")
        zf.writestr("real", b"new real bytes")

    with zipfile.ZipFile(archive) as zf:
        _safe_extractall(zf, target)

    assert not (target / "name").is_symlink()
    assert (target / "name").read_bytes() == b"new name bytes"
    assert (target / "real").read_bytes() == b"new real bytes"


def test_safe_extractall_rejects_a_cycle_closed_by_an_existing_link(tmp_path):
    if not _can_create_symlinks(tmp_path):
        pytest.skip("symlink creation needs privilege on this host (Windows non-dev-mode)")
    # Cycles can include links a previous bundle left; the half this archive made must be removed.
    target = tmp_path / "install"
    target.mkdir()
    (target / "b").symlink_to("a")
    archive = tmp_path / "next.zip"
    with zipfile.ZipFile(archive, "w") as zf:
        _link_member(zf, "a", "b")
    with zipfile.ZipFile(archive) as zf:
        with pytest.raises(RuntimeError, match = "symlink cycle"):
            _safe_extractall(zf, target)
    assert not (target / "a").is_symlink()


def test_safe_extractall_rejects_a_symlink_at_a_reserved_installer_path(tmp_path):
    # Opening the record with "w" follows a planted link and overwrites its target.
    target = tmp_path / "install"
    target.mkdir()
    archive = tmp_path / "evil.zip"
    with zipfile.ZipFile(archive, "w") as zf:
        zf.writestr(_CLI, b"\x7fELF real binary")
        _link_member(zf, sdmod.INSTALL_RECORD, _CLI)
    with zipfile.ZipFile(archive) as zf:
        with pytest.raises(RuntimeError, match = "reserved installer path"):
            _safe_extractall(zf, target)
    assert not any(target.iterdir())


def test_safe_extractall_rejects_a_symlink_onto_a_reserved_installer_path(tmp_path):
    # The marker exists before extraction, so a link to it would resolve to an empty "executable".
    target = tmp_path / "install"
    target.mkdir()
    (target / sdmod.OWNERSHIP_MARKER).write_text("")
    archive = tmp_path / "evil.zip"
    with zipfile.ZipFile(archive, "w") as zf:
        _link_member(zf, _CLI, sdmod.OWNERSHIP_MARKER)
    with zipfile.ZipFile(archive) as zf:
        with pytest.raises(RuntimeError, match = "onto a reserved installer path"):
            _safe_extractall(zf, target)
    assert sdmod._locate_sd_cli(target) is None


def test_safe_extractall_rejects_a_reserved_path_reached_through_a_directory_alias(tmp_path):
    # A previous dir link can make alias/<record> the record itself; a lexical compare misses it.
    target = _shared_setup_2(tmp_path)
    (target / _CLI).write_bytes(b"\x7fELF real binary")
    (target / "alias").symlink_to(".")
    archive = tmp_path / "evil.zip"
    with zipfile.ZipFile(archive, "w") as zf:
        _link_member(zf, "alias/" + sdmod.INSTALL_RECORD, _CLI)
    with zipfile.ZipFile(archive) as zf:
        with pytest.raises(RuntimeError, match = "reserved installer path"):
            _safe_extractall(zf, target)
    assert not (target / sdmod.INSTALL_RECORD).exists()
    assert (target / _CLI).read_bytes() == b"\x7fELF real binary"


def test_safe_extractall_rejects_a_cycle_hidden_behind_a_directory_alias(tmp_path):
    target = _shared_setup_2(tmp_path)
    (target / "real").mkdir()
    (target / "alias").symlink_to("real")
    archive = tmp_path / "cycle.zip"
    with zipfile.ZipFile(archive, "w") as zf:
        _link_member(zf, "alias/a", "b")
        _link_member(zf, "real/b", "a")
    with zipfile.ZipFile(archive) as zf:
        with pytest.raises(RuntimeError, match = "symlink cycle"):
            _safe_extractall(zf, target)
    assert not (target / "real" / "a").is_symlink()
    assert not (target / "real" / "b").is_symlink()


def test_safe_extractall_rejects_a_directory_collision_before_writing_anything(tmp_path):
    target = tmp_path / "install"
    (target / "build" / "bin").mkdir(parents = True)
    (target / "build" / "bin" / _CLI).write_bytes(b"\x7fELF working")
    (target / "libz.so").mkdir()
    archive = tmp_path / "collide.zip"
    with zipfile.ZipFile(archive, "w") as zf:
        zf.writestr(f"build/bin/{_CLI}", b"\x7fELF replacement")
        _link_member(zf, "libz.so", "libz.so.1")
    with zipfile.ZipFile(archive) as zf:
        with pytest.raises(RuntimeError, match = "collides with a directory"):
            _safe_extractall(zf, target)
    assert (target / "build" / "bin" / _CLI).read_bytes() == b"\x7fELF working"
    assert (target / "libz.so").is_dir() and not (target / "libz.so").is_symlink()


def _chain_archive(path, hops):
    with zipfile.ZipFile(path, "w") as zf:
        zf.writestr("l.so.0", b"ELFpayload")
        prev = "l.so.0"
        for i in range(1, hops + 1):
            _link_member(zf, f"l.so.{i}", prev)
            prev = f"l.so.{i}"


def test_safe_extractall_installs_a_chain_the_loader_can_still_walk(tmp_path):
    # The kernel allows 40 traversals, so 40 is readable and must not be refused.
    target = _shared_setup_2(tmp_path)
    archive = tmp_path / "chain40.zip"
    _chain_archive(archive, 40)
    with zipfile.ZipFile(archive) as zf:
        _safe_extractall(zf, target)
    assert (target / "l.so.40").read_bytes() == b"ELFpayload"


def test_safe_extractall_rejects_a_chain_deeper_than_the_loader_allows(tmp_path):
    # At 41 the loader ELOOPs, so the library would be unreadable.
    target = tmp_path / "install"
    target.mkdir()
    archive = tmp_path / "chain41.zip"
    _chain_archive(archive, 41)
    with zipfile.ZipFile(archive) as zf:
        with pytest.raises(RuntimeError, match = "too deep"):
            _safe_extractall(zf, target)


def test_safe_extractall_rejects_symlink_cycles(tmp_path):
    target = tmp_path / "install"
    target.mkdir()
    archive = tmp_path / "cycle.zip"
    with zipfile.ZipFile(archive, "w") as zf:
        _link_member(zf, "liba.so", "libb.so")
        _link_member(zf, "libb.so", "liba.so")
    _shared_setup_13(archive, target)


def test_safe_extractall_keeps_valid_symlink_chains(tmp_path):
    if not _can_create_symlinks(tmp_path):
        pytest.skip("symlink creation needs privilege on this host (Windows non-dev-mode)")
    target = tmp_path / "install"
    target.mkdir()
    archive = tmp_path / "libs.zip"
    with zipfile.ZipFile(archive, "w") as zf:
        zf.writestr("libwebp.so.7.2.0", b"\x7fELFpayload")
        _link_member(zf, "libwebp.so.7", "libwebp.so.7.2.0")
        _link_member(zf, "libwebp.so", "libwebp.so.7")
    with zipfile.ZipFile(archive) as zf:
        _safe_extractall(zf, target)
    assert (target / "libwebp.so").read_bytes() == b"\x7fELFpayload"


def test_safe_extractall_rejects_oversized_symlink_target(tmp_path):
    # zf.read holds the payload in memory, and a pathname cannot exceed PATH_MAX.
    target = tmp_path / "install"
    target.mkdir()
    archive = tmp_path / "bomb.zip"
    with zipfile.ZipFile(archive, "w", zipfile.ZIP_DEFLATED) as zf:
        _link_member(zf, "libbomb.so", "a" * (1 << 20))
    with zipfile.ZipFile(archive) as zf:
        with pytest.raises(RuntimeError, match = "oversized symlink target"):
            _safe_extractall(zf, target)
    assert not any(target.iterdir())


def test_safe_extractall_ignores_symlink_mode_from_non_unix_hosts(tmp_path):
    # Those high bits are a Unix mode only when a Unix host wrote the entry.
    target = tmp_path / "install"
    target.mkdir()
    archive = tmp_path / "dos.zip"
    with zipfile.ZipFile(archive, "w") as zf:
        _link_member(zf, "plain.txt", "not a link", create_system = 0)
    with zipfile.ZipFile(archive) as zf:
        _safe_extractall(zf, target)
    extracted = target / "plain.txt"
    assert not extracted.is_symlink()
    assert extracted.read_bytes() == b"not a link"


def test_safe_extractall_restores_links_from_a_macos_creator(tmp_path):
    # Apple ditto / Archive Utility stamp creator 19 with a Unix-style external_attr.
    target = _shared_setup_2(tmp_path)
    archive = tmp_path / "ditto.zip"
    with zipfile.ZipFile(archive, "w") as zf:
        zf.writestr("libwebp.so.7.2.0", b"ELFpayload")
        _link_member(zf, "libwebp.so.7", "libwebp.so.7.2.0", create_system = 19)
    with zipfile.ZipFile(archive) as zf:
        _safe_extractall(zf, target)
    link = target / "libwebp.so.7"
    assert link.is_symlink()
    assert link.read_bytes() == b"ELFpayload"


def test_safe_extractall_creates_the_install_root_before_probing_for_symlinks(tmp_path):
    # extractall creates the root, so a missing root must not fail the symlink probe.
    if not _can_create_symlinks(tmp_path):
        pytest.skip("symlink creation needs privilege on this host (Windows non-dev-mode)")
    target = tmp_path / "not-created-yet"
    archive = tmp_path / "fresh.zip"
    with zipfile.ZipFile(archive, "w") as zf:
        zf.writestr("libwebp.so.7.2.0", b"ELFpayload")
        _link_member(zf, "libwebp.so.7", "libwebp.so.7.2.0")
    with zipfile.ZipFile(archive) as zf:
        _safe_extractall(zf, target)
    assert (target / "libwebp.so.7").is_symlink()
    assert (target / "libwebp.so.7").read_bytes() == b"ELFpayload"


def test_safe_extractall_survives_a_probe_left_by_a_killed_install(tmp_path):
    # A killed install's probe can survive and a restarted container reuses the pid: EEXIST is not
    # "no symlink support".
    target = _shared_setup_2(tmp_path)
    (target / f".unsloth-symlink-probe-{os.getpid()}").symlink_to(".")
    archive = _shared_setup_7(tmp_path)
    with zipfile.ZipFile(archive) as zf:
        _safe_extractall(zf, target)
    assert (target / "libwebp.so.7").is_symlink()
    assert (target / "libwebp.so.7").read_bytes() == b"ELFpayload"
    assert list(target.glob(".unsloth-symlink-probe-*")) == []


def test_safe_extractall_is_idempotent_across_reinstalls(tmp_path):
    target = _shared_setup_2(tmp_path)
    archive = tmp_path / "libs.zip"
    # The chained shape upstream ships: libwebp.so -> libwebp.so.7 -> libwebp.so.7.2.0.
    with zipfile.ZipFile(archive, "w") as zf:
        zf.writestr("libwebp.so.7.2.0", b"ELFpayload")
        _link_member(zf, "libwebp.so.7", "libwebp.so.7.2.0")
        _link_member(zf, "libwebp.so", "libwebp.so.7")

    # install() merges, so re-extracting must not resolve through existing links.
    for _ in range(3):
        with zipfile.ZipFile(archive) as zf:
            _safe_extractall(zf, target)

    real = target / "libwebp.so.7.2.0"
    assert not real.is_symlink()
    assert real.read_bytes() == b"ELFpayload"
    for name in ("libwebp.so", "libwebp.so.7"):
        assert (target / name).is_symlink()
        assert (target / name).read_bytes() == b"ELFpayload"


def test_safe_extractall_repairs_a_flattened_install(tmp_path):
    target = _shared_setup_2(tmp_path)
    (target / "libwebp.so.7.2.0").write_bytes(b"ELFpayload")
    (target / "libwebp.so.7").write_bytes(b"libwebp.so.7.2.0")
    archive = _shared_setup_7(tmp_path)

    with zipfile.ZipFile(archive) as zf:
        _safe_extractall(zf, target)

    assert (target / "libwebp.so.7").is_symlink()
    assert (target / "libwebp.so.7").read_bytes() == b"ELFpayload"


def test_safe_extractall_survives_a_hand_repaired_install(tmp_path):
    target = _shared_setup_2(tmp_path)
    (target / "libwebp.so.7.2.0").write_bytes(b"ELFpayload")
    (target / "libwebp.so.7").symlink_to("libwebp.so.7.2.0")
    archive = _shared_setup_7(tmp_path)

    with zipfile.ZipFile(archive) as zf:
        _safe_extractall(zf, target)

    real = target / "libwebp.so.7.2.0"
    assert not real.is_symlink()
    assert real.read_bytes() == b"ELFpayload"
    assert (target / "libwebp.so.7").read_bytes() == b"ELFpayload"


def test_safe_extractall_falls_back_when_symlinks_are_unavailable(tmp_path, monkeypatch):
    # Windows outside developer mode cannot create symlinks; the install must still finish flattened.
    target = tmp_path / "install"
    target.mkdir()
    archive = _shared_setup_7(tmp_path)

    def _no_symlinks(self, *args, **kwargs):
        raise OSError(1314, "A required privilege is not held by the client")

    monkeypatch.setattr(Path, "symlink_to", _no_symlinks)
    monkeypatch.setattr(sdmod.sys, "platform", "win32")
    with zipfile.ZipFile(archive) as zf:
        _safe_extractall(zf, target)

    flattened = target / "libwebp.so.7"
    assert not flattened.is_symlink()
    assert flattened.read_bytes() == b"libwebp.so.7.2.0"
    assert (target / "libwebp.so.7.2.0").read_bytes() == b"ELFpayload"


def test_safe_extractall_refuses_to_flatten_when_a_unix_host_rejects_symlinks(
    tmp_path, monkeypatch
):
    # Off Windows, refuse before extractall: a flattened link is the "file too short" install of #9268.
    target = tmp_path / "install"
    target.mkdir()
    (target / _CLI).write_bytes(b"\x7fELF old working")
    archive = tmp_path / "libs.zip"
    with zipfile.ZipFile(archive, "w") as zf:
        zf.writestr(_CLI, b"\x7fELF replacement")
        zf.writestr("libwebp.so.7.2.0", b"ELFpayload")
        _link_member(zf, "libwebp.so.7", "libwebp.so.7.2.0")

    def _no_symlinks(self, *args, **kwargs):
        raise OSError(1, "Operation not permitted")

    monkeypatch.setattr(Path, "symlink_to", _no_symlinks)
    monkeypatch.setattr(sdmod.sys, "platform", "linux")
    with zipfile.ZipFile(archive) as zf:
        with pytest.raises(RuntimeError, match = "cannot store symlinks"):
            _safe_extractall(zf, target)
    assert not (target / "libwebp.so.7").exists()
    assert not (target / "libwebp.so.7.2.0").exists()
    assert (target / _CLI).read_bytes() == b"\x7fELF old working"


def test_safe_extractall_rejects_a_member_with_a_parent_component(tmp_path):
    # extractall drops ".." instead of cancelling the prior component, so "a/../victim" is "a/victim".
    target = _shared_setup_2(tmp_path)
    outside = tmp_path / "outside"
    outside.mkdir()
    (outside / "victim").write_bytes(b"untouched")
    (target / "a").symlink_to(outside)
    archive = tmp_path / "slip.zip"
    with zipfile.ZipFile(archive, "w") as zf:
        zf.writestr("a/../victim", b"pwned")
    with zipfile.ZipFile(archive) as zf:
        with pytest.raises(RuntimeError, match = "unsafe path"):
            _safe_extractall(zf, target)
    assert (outside / "victim").read_bytes() == b"untouched"


def test_safe_extractall_rejects_a_cycle_closed_through_link_parents(tmp_path):
    # a -> b/x and b -> a/y form a cycle only once b's prefix is followed through the archive.
    target = tmp_path / "install"
    target.mkdir()
    archive = tmp_path / "cycle.zip"
    with zipfile.ZipFile(archive, "w") as zf:
        _link_member(zf, "a", "b/x")
        _link_member(zf, "b", "a/y")
    _shared_setup_13(archive, target)


def test_safe_extractall_rejects_a_link_that_descends_through_itself(tmp_path):
    # a -> a/x never reaches a second node, but resolving it loops (ELOOP).
    target = tmp_path / "install"
    target.mkdir()
    archive = tmp_path / "loop.zip"
    with zipfile.ZipFile(archive, "w") as zf:
        _link_member(zf, "libz.so", "libz.so/inner")
    _shared_setup_13(archive, target)


def test_safe_extractall_extracts_normal_members(tmp_path):
    target = tmp_path / "install"
    target.mkdir()
    archive = tmp_path / "ok.zip"
    with zipfile.ZipFile(archive, "w") as zf:
        zf.writestr(f"build/bin/{_CLI}", b"ok")
    with zipfile.ZipFile(archive) as zf:
        _safe_extractall(zf, target)
    assert (target / "build" / "bin" / _CLI).read_bytes() == b"ok"


def test_find_sd_cpp_binary_honors_studio_home(tmp_path, monkeypatch):
    from core.inference import sd_cpp_engine as eng

    monkeypatch.delenv("SD_CLI_PATH", raising = False)
    monkeypatch.delenv("UNSLOTH_SD_CPP_PATH", raising = False)
    studio_home = tmp_path / "studio_root"
    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(studio_home))
    binary = studio_home / "stable-diffusion.cpp" / "build" / "bin" / _CLI
    binary.parent.mkdir(parents = True)
    binary.write_bytes(b"x")
    assert eng.find_sd_cpp_binary() == str(binary)


def test_managed_root_is_under_the_studio_home_like_every_other_component(tmp_path, monkeypatch):
    """sd.cpp installs under the Unsloth home like other components, not in the home's parent."""
    from core.inference import sd_cpp_engine as eng

    studio_home = tmp_path / "sxs" / "studio_a"
    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(studio_home))
    monkeypatch.delenv("STUDIO_HOME", raising = False)
    assert default_install_dir() == studio_home / "stable-diffusion.cpp"
    # The installer and the engine must agree, or one installs where the other never looks.
    assert eng.managed_install_root() == default_install_dir()


def test_a_relative_studio_home_does_not_put_the_install_in_the_working_directory(
    tmp_path, monkeypatch
):
    """A relative UNSLOTH_STUDIO_HOME must not collapse the managed root to `./stable-diffusion.cpp`."""
    from core.inference import sd_cpp_engine as eng

    monkeypatch.chdir(tmp_path)
    (tmp_path / "stable-diffusion.cpp").mkdir()
    (tmp_path / "stable-diffusion.cpp" / "README.md").write_text("someone else's checkout")
    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", "relative_home")
    monkeypatch.delenv("STUDIO_HOME", raising = False)

    for root in (default_install_dir(), eng.managed_install_root()):
        assert root.is_absolute(), "a relative home must not leave the root relative"
        assert root == (tmp_path / "relative_home" / "stable-diffusion.cpp").resolve()
        assert root != (tmp_path / "stable-diffusion.cpp").resolve()


def test_the_legacy_sibling_tree_is_adopted_only_when_it_carries_the_marker(tmp_path, monkeypatch):
    """A legacy sibling tree is adopted only with the ownership marker; an unmarked match may be a clone."""
    from core.inference import sd_cpp_engine as eng

    monkeypatch.delenv("SD_CLI_PATH", raising = False)
    monkeypatch.delenv("UNSLOTH_SD_CPP_PATH", raising = False)
    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path / "studio"))
    sibling = tmp_path / "stable-diffusion.cpp"
    binary = sibling / "build" / "bin" / _CLI
    binary.parent.mkdir(parents = True)
    binary.write_bytes(b"x")

    assert eng.legacy_sibling_install_root() is None
    assert eng.find_sd_cpp_binary() is None
    assert eng.is_managed_binary(str(binary)) is False

    (sibling / eng.OWNER_MARKER).touch()
    assert eng.legacy_sibling_install_root() == sibling
    assert eng.find_sd_cpp_binary() == str(binary)
    assert eng.is_managed_binary(str(binary)) is True


def test_the_legacy_default_studio_home_keeps_its_install_dir(tmp_path, monkeypatch):
    """``UNSLOTH_STUDIO_HOME=~/.unsloth/studio`` is the documented default, not a custom home:
    it must keep resolving to ``~/.unsloth/stable-diffusion.cpp`` rather than moving the tree to
    ``~/.unsloth/studio/stable-diffusion.cpp`` and orphaning every existing install."""
    from core.inference import sd_cpp_engine as eng

    fake_home = tmp_path / "home"
    (fake_home / ".unsloth" / "studio").mkdir(parents = True)
    monkeypatch.setattr(Path, "home", staticmethod(lambda: fake_home))
    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(fake_home / ".unsloth" / "studio"))
    monkeypatch.delenv("STUDIO_HOME", raising = False)
    expected = fake_home / ".unsloth" / "stable-diffusion.cpp"
    assert default_install_dir() == expected
    assert eng.managed_install_root() == expected


# Read the shipped DEFAULT_TAG; a hardcoded copy goes stale the moment it moves.
_TAG = DEFAULT_TAG
# Exactly what the mirror's CI publishes; the CUDA leg is best effort and may be absent.
_MIRROR_ASSETS = [
    f"sd-{_TAG}-bin-Darwin-macOS-arm64.zip",
    f"sd-{_TAG}-bin-Darwin-macOS-x86_64.zip",
    # Listed before the plain build, as a real release sorts them; exposes position-based picking.
    f"sd-{_TAG}-bin-Linux-Ubuntu-22.04-x86_64-cuda12.zip",
    f"sd-{_TAG}-bin-Linux-Ubuntu-22.04-x86_64.zip",
    f"sd-{_TAG}-bin-Linux-Ubuntu-24.04-aarch64.zip",
    f"sd-{_TAG}-bin-win-cpu-x64.zip",
]


def _mresolve(
    system,
    machine,
    accelerator = "auto",
):
    return resolve_release_asset(
        _MIRROR_ASSETS, system = system, machine = machine, accelerator = accelerator
    )


def test_default_repo_is_the_unsloth_mirror():
    assert sdmod.DEFAULT_REPO == "unslothai/stable-diffusion.cpp"
    assert sdmod.UPSTREAM_FALLBACK_REPO == "leejet/stable-diffusion.cpp"


def test_mirror_matrix_resolves_every_cpu_apple_host():
    assert _mresolve("Darwin", "arm64") == f"sd-{_TAG}-bin-Darwin-macOS-arm64.zip"
    assert _mresolve("Darwin", "x86_64") == f"sd-{_TAG}-bin-Darwin-macOS-x86_64.zip"
    # WSL reports as Linux x86_64, so this also covers WSL.
    assert _mresolve("Linux", "x86_64") == f"sd-{_TAG}-bin-Linux-Ubuntu-22.04-x86_64.zip"
    assert _mresolve("Linux", "aarch64") == f"sd-{_TAG}-bin-Linux-Ubuntu-24.04-aarch64.zip"
    assert _mresolve("Windows", "AMD64") == f"sd-{_TAG}-bin-win-cpu-x64.zip"
    assert _mresolve("Windows", "AMD64", "cpu") == f"sd-{_TAG}-bin-win-cpu-x64.zip"


def test_mirror_linux_cuda_resolves_the_cuda_bundle():
    """Linux CUDA hosts get the CUDA bundle: without it MiniMax-H3 GGUF ran on the CPU, because
    video.py falls back to the CPU prebuilt whenever the accelerated one cannot be resolved."""
    assert (
        _mresolve("Linux", "x86_64", "cuda")
        == f"sd-{_TAG}-bin-Linux-Ubuntu-22.04-x86_64-cuda12.zip"
    )


def test_mirror_linux_auto_still_takes_the_plain_cpu_build():
    """The CUDA bundle ships the CUDA runtime and is roughly 25x the size of the CPU one. A host
    that did not ask for a GPU build must not be handed it by accident."""
    assert _mresolve("Linux", "x86_64") == f"sd-{_TAG}-bin-Linux-Ubuntu-22.04-x86_64.zip"
    assert _mresolve("Linux", "x86_64", "cpu") == f"sd-{_TAG}-bin-Linux-Ubuntu-22.04-x86_64.zip"


def test_mirror_linux_cuda_refuses_a_release_without_one():
    """CUDA leg is best effort, so a release may lack it; return None so the caller falls back,
    since a CPU build would keep the GPU device and run sd-cli on the CPU."""
    without = [a for a in _MIRROR_ASSETS if "cuda" not in a]
    assert (
        resolve_release_asset(without, system = "Linux", machine = "x86_64", accelerator = "cuda") is None
    )


def test_upstream_tag_drops_the_mirror_fork_suffix():
    """A mirror release built on an upstream one is that tag plus "-u<fork sha>", and only the
    base half exists upstream. The suffix has to come off before the fallback asks for it."""
    assert upstream_tag_for("master-813-bfbef5b-u13b9d92") == "master-813-bfbef5b"
    assert upstream_tag_for("master-813-bfbef5b-u0665242") == "master-813-bfbef5b"
    assert upstream_tag_for("master-809-eb7f35c") == "master-809-eb7f35c"
    assert upstream_tag_for("v1.2.3-ubuntu") == "v1.2.3-ubuntu"
    assert upstream_tag_for(None) is None


def test_shipped_pin_translates_to_a_plain_upstream_tag():
    """Guards the pin itself: whatever DEFAULT_TAG becomes, the string handed upstream must not
    still carry a fork suffix, or the fallback is asking for a release that cannot exist."""
    assert re.search(r"-u[0-9a-f]{7,}$", upstream_tag_for(DEFAULT_TAG)) is None


def test_upstream_fallback_asks_for_the_translated_pin_not_latest(monkeypatch):
    """Upstream fallback must ask for the translated pin's tag, not an unpinned latest release."""
    monkeypatch.delenv("UNSLOTH_SD_CPP_REPO", raising = False)
    monkeypatch.setenv("UNSLOTH_SD_CPP_TAG", "master-813-bfbef5b-u13b9d92")
    monkeypatch.setattr(sdmod.platform, "system", lambda: "Linux")
    monkeypatch.setattr(sdmod.platform, "machine", lambda: "x86_64")
    seen = []

    def fake_fetch(
        tag = None,
        *,
        repo = None,
        token = None,
        timeout = 30.0,
        allow_latest = True,
    ):
        seen.append((repo, tag))
        if repo == sdmod.UPSTREAM_FALLBACK_REPO and tag == "master-813-bfbef5b":
            return {
                "tag_name": tag,
                "assets": [{"name": "sd-master-bfbef5b-bin-Linux-Ubuntu-24.04-x86_64-vulkan.zip"}],
            }
        if repo == sdmod.DEFAULT_REPO and tag == "master-813-bfbef5b-u13b9d92":
            return {
                "tag_name": tag,
                "assets": [{"name": f"sd-{tag}-bin-Linux-Ubuntu-22.04-x86_64.zip"}],
            }
        raise urllib.error.HTTPError(f"https://api/{repo}", 404, "not found", None, None)

    monkeypatch.setattr(sdmod, "_fetch_release", fake_fetch)
    repo, release, chosen = sdmod._resolve_with_fallback("vulkan", None)
    assert repo == sdmod.UPSTREAM_FALLBACK_REPO
    assert release["tag_name"] == "master-813-bfbef5b"
    assert chosen.endswith("-vulkan.zip")
    assert (sdmod.UPSTREAM_FALLBACK_REPO, "master-813-bfbef5b-u13b9d92") not in seen
    assert not any(tag is None for _repo_name, tag in seen)


def test_the_shipped_pin_falls_back_to_an_upstream_release_that_runs_qwen_image_2_1(monkeypatch):
    """#12470: the previous pin's upstream base (master-813) predated Qwen-Image-2.1, so hosts the mirror skips got a build the router refuses."""
    monkeypatch.delenv("UNSLOTH_SD_CPP_REPO", raising = False)
    monkeypatch.delenv("UNSLOTH_SD_CPP_TAG", raising = False)
    monkeypatch.setattr(sdmod.platform, "system", lambda: "Windows")
    monkeypatch.setattr(sdmod.platform, "machine", lambda: "AMD64")
    seen = []

    def fake_fetch(
        tag = None,
        *,
        repo = None,
        token = None,
        timeout = 30.0,
        allow_latest = True,
    ):
        seen.append((repo, tag))
        if repo == sdmod.DEFAULT_REPO and tag == DEFAULT_TAG:
            return {"tag_name": tag, "assets": [{"name": f"sd-{tag}-bin-win-cpu-x64.zip"}]}
        if repo == sdmod.UPSTREAM_FALLBACK_REPO and tag:
            short = tag.rsplit("-", 1)[-1]
            return {
                "tag_name": tag,
                "assets": [{"name": f"sd-master-{short}-bin-win-cuda12-x64.zip"}],
            }
        raise urllib.error.HTTPError(f"https://api/{repo}", 404, "not found", None, None)

    monkeypatch.setattr(sdmod, "_fetch_release", fake_fetch)
    repo, release, chosen = sdmod._resolve_with_fallback("cuda", None)
    assert repo == sdmod.UPSTREAM_FALLBACK_REPO
    assert chosen.endswith("-win-cuda12-x64.zip")
    assert release["tag_name"] == upstream_tag_for(DEFAULT_TAG)
    # The pin must reach master-975: MOSS-Image landed there, after FLUX.3 at master-968.
    assert int(release["tag_name"].split("-")[1]) >= 975


# ── mirror -> upstream fallback in install() ─────────────────────────────────


def _stub_two_repos(monkeypatch, *, mirror_serves, upstream_serves, zip_bytes, digest):
    """Stub _fetch_release to serve (or 404) per repo, so install()'s mirror->upstream
    fallback can be exercised without network. Host pinned to Linux x86_64."""
    monkeypatch.delenv("UNSLOTH_SD_CPP_REPO", raising = False)
    monkeypatch.delenv("UNSLOTH_SD_CPP_TAG", raising = False)
    mirror_name = f"sd-{_TAG}-bin-Linux-Ubuntu-22.04-x86_64.zip"
    upstream_name = "sd-master-741-484baa4-bin-Linux-Ubuntu-24.04-x86_64.zip"

    def _rel(name):
        return {
            "tag_name": _TAG,
            "assets": [
                {
                    "name": name,
                    "browser_download_url": f"https://example.invalid/{name}",
                    "digest": digest,
                }
            ],
        }

    def fake_fetch(
        tag = None,
        *,
        repo = None,
        token = None,
        timeout = 30.0,
        allow_latest = True,
    ):
        r = repo or sdmod.DEFAULT_REPO
        if r == sdmod.DEFAULT_REPO:
            if mirror_serves:
                return _rel(mirror_name)
            raise urllib.error.HTTPError(f"https://api/{r}", 404, "not found", None, None)
        if upstream_serves:
            return _rel(upstream_name)
        raise urllib.error.HTTPError(f"https://api/{r}", 404, "not found", None, None)

    monkeypatch.setattr(sdmod, "_fetch_release", fake_fetch)
    monkeypatch.setattr(sdmod, "_download", lambda url, dest, **k: dest.write_bytes(zip_bytes))
    monkeypatch.setattr(sdmod.platform, "system", lambda: "Linux")
    monkeypatch.setattr(sdmod.platform, "machine", lambda: "x86_64")
    return mirror_name, upstream_name


def test_install_uses_mirror_when_available(tmp_path, monkeypatch, capsys):
    zb = _zip_with_sd_cli()
    _stub_two_repos(
        monkeypatch,
        mirror_serves = True,
        upstream_serves = True,
        zip_bytes = zb,
        digest = "sha256:" + hashlib.sha256(zb).hexdigest(),
    )
    sd_cli = install(install_dir = tmp_path)
    assert sd_cli.name == _CLI and sd_cli.is_file()
    assert "unslothai/stable-diffusion.cpp" in capsys.readouterr().out


def test_install_falls_back_to_upstream_when_mirror_missing(tmp_path, monkeypatch, capsys):
    _shared_setup_5(monkeypatch)
    sd_cli = install(install_dir = tmp_path)
    assert sd_cli.name == _CLI and sd_cli.is_file()
    captured = capsys.readouterr()
    # The repo-fallback diagnostic goes to stderr so --print-asset's stdout stays one asset line; the install note stays on stdout.
    assert "falling back to leejet/stable-diffusion.cpp" in captured.err
    assert "source leejet/stable-diffusion.cpp" in captured.out


def test_the_shipped_pin_is_mirror_only(tmp_path, monkeypatch):
    """The shipped pin is mirror-only (H3 patch set); fail loudly if it becomes a plain upstream tag."""
    assert sdmod.is_mirror_only_tag(DEFAULT_TAG)
    assert not sdmod.is_mirror_only_tag("master-813-bfbef5b")
    assert not sdmod.is_mirror_only_tag("")
    assert not sdmod.is_mirror_only_tag(None)


def test_a_mirror_only_pin_is_never_requested_upstream(tmp_path, monkeypatch):
    """A mirror-only pin is never requested upstream as -u<id>, a guaranteed 404; it maps to the release."""
    _shared_setup_5(monkeypatch)
    asked = []
    real = sdmod._fetch_release
    monkeypatch.setattr(
        sdmod,
        "_fetch_release",
        lambda tag = None, **kw: (asked.append((kw.get("repo"), tag)), real(tag, **kw))[1],
    )
    install(install_dir = tmp_path)
    assert (sdmod.UPSTREAM_FALLBACK_REPO, DEFAULT_TAG) not in asked
    upstream_pin = sdmod.upstream_tag_for(DEFAULT_TAG)
    assert upstream_pin != DEFAULT_TAG
    assert (sdmod.UPSTREAM_FALLBACK_REPO, upstream_pin) in asked
    assert (sdmod.UPSTREAM_FALLBACK_REPO, None) not in asked


def test_falling_back_off_a_mirror_only_pin_warns_about_h3(tmp_path, monkeypatch, capsys):
    """Falling back off a mirror-only pin must warn about H3 specifically."""
    _shared_setup_5(monkeypatch)
    install(install_dir = tmp_path)
    err = capsys.readouterr().err
    assert "falling back to leejet/stable-diffusion.cpp" in err
    assert "lacks the MiniMax-H3 fixes" in err


def test_install_errors_when_neither_source_serves(tmp_path, monkeypatch):
    _stub_two_repos(
        monkeypatch, mirror_serves = False, upstream_serves = False, zip_bytes = b"", digest = ""
    )
    with pytest.raises(RuntimeError, match = "No prebuilt sd-cli"):
        install(install_dir = tmp_path)


def test_mirror_windows_gpu_accel_is_no_match_not_cpu():
    # The mirror ships only a CPU win zip; an explicit GPU accelerator returns None (upstream fallback).
    for accel in ("cuda", "vulkan", "rocm"):
        assert _mresolve("Windows", "AMD64", accel) is None
    assert _mresolve("Windows", "AMD64", "cpu") == f"sd-{_TAG}-bin-win-cpu-x64.zip"


def test_mirror_linux_gpu_accel_is_no_match_not_cpu():
    for accel in ("vulkan", "rocm"):
        assert _mresolve("Linux", "x86_64", accel) is None
    assert _mresolve("Linux", "x86_64", "cpu") == f"sd-{_TAG}-bin-Linux-Ubuntu-22.04-x86_64.zip"


def test_upstream_full_matrix_still_resolves_gpu_accel():
    assert _resolve("Windows", "AMD64", "cuda") == "sd-master-8caa3f9-bin-win-cuda12-x64.zip"
    assert _resolve("Linux", "x86_64", "vulkan").endswith("x86_64-vulkan.zip")
    assert "rocm" in _resolve("Linux", "x86_64", "rocm")


def test_explicit_repo_override_equal_to_default_suppresses_fallback(tmp_path, monkeypatch):
    _stub_two_repos(
        monkeypatch, mirror_serves = False, upstream_serves = True, zip_bytes = b"", digest = ""
    )
    monkeypatch.setenv("UNSLOTH_SD_CPP_REPO", sdmod.DEFAULT_REPO)
    with pytest.raises(RuntimeError, match = "No prebuilt sd-cli"):
        install(install_dir = tmp_path)


def test_pinned_tag_prefers_upstream_pin_over_mirror_latest(tmp_path, monkeypatch, capsys):
    # The mirror lacks the pinned tag but has a newer latest; the pinned upstream build must win (reproducibility).
    monkeypatch.delenv("UNSLOTH_SD_CPP_REPO", raising = False)
    monkeypatch.setenv("UNSLOTH_SD_CPP_TAG", "master-999-pinned")
    zb = _zip_with_sd_cli()
    digest = "sha256:" + hashlib.sha256(zb).hexdigest()

    def _rel(name, tag):
        return {
            "tag_name": tag,
            "assets": [
                {
                    "name": name,
                    "browser_download_url": f"https://example.invalid/{name}",
                    "digest": digest,
                }
            ],
        }

    mirror_latest = "sd-master-000-latest-bin-Linux-Ubuntu-22.04-x86_64.zip"
    upstream_pinned = "sd-master-999-pinned-bin-Linux-Ubuntu-24.04-x86_64.zip"

    def fake_fetch(
        tag = None,
        *,
        repo = None,
        token = None,
        timeout = 30.0,
        allow_latest = True,
    ):
        r = repo or sdmod.DEFAULT_REPO
        if r == sdmod.DEFAULT_REPO:
            if tag == "master-999-pinned":
                if not allow_latest:
                    return None
                return _rel(mirror_latest, "master-000-latest")
            return _rel(mirror_latest, "master-000-latest")
        if tag == "master-999-pinned":
            return _rel(upstream_pinned, "master-999-pinned")
        return _rel(upstream_pinned, "master-999-pinned")

    monkeypatch.setattr(sdmod, "_fetch_release", fake_fetch)
    monkeypatch.setattr(sdmod, "_download", lambda url, dest, **k: dest.write_bytes(zb))
    monkeypatch.setattr(sdmod.platform, "system", lambda: "Linux")
    monkeypatch.setattr(sdmod.platform, "machine", lambda: "x86_64")

    install(install_dir = tmp_path)
    out = capsys.readouterr().out
    assert "source leejet/stable-diffusion.cpp release master-999-pinned" in out


def test_print_asset_uses_upstream_fallback(monkeypatch, capsys):
    monkeypatch.delenv("UNSLOTH_SD_CPP_REPO", raising = False)
    monkeypatch.delenv("UNSLOTH_SD_CPP_TAG", raising = False)

    def fake_fetch(
        tag = None,
        *,
        repo = None,
        token = None,
        timeout = 30.0,
        allow_latest = True,
    ):
        r = repo or sdmod.DEFAULT_REPO
        if r == sdmod.DEFAULT_REPO:
            return {"tag_name": _TAG, "assets": [{"name": n} for n in _MIRROR_ASSETS]}
        return {"tag_name": "master-8caa3f9", "assets": [{"name": n} for n in _ASSETS]}

    monkeypatch.setattr(sdmod, "_fetch_release", fake_fetch)
    monkeypatch.setattr(sdmod.platform, "system", lambda: "Linux")
    monkeypatch.setattr(sdmod.platform, "machine", lambda: "x86_64")
    rc = sdmod.main(["--print-asset", "--accelerator", "vulkan"])
    out = capsys.readouterr().out
    assert rc == 0
    assert "vulkan" in out and "no matching prebuilt" not in out


def test_unrunnable_managed_binary_is_removed_so_it_reinstalls(monkeypatch, tmp_path):
    # The finder only checks is_file(), so an interrupted extraction needs a runnable probe.
    import core.inference.sd_cpp_backend as bk
    import core.inference.sd_cpp_engine as eng

    root = tmp_path / "sd-home" / "stable-diffusion.cpp"
    root.mkdir(parents = True)
    # install() writes the ownership marker BEFORE extracting, so a real interrupted extraction always leaves one.
    (root / ".unsloth-studio-owned").touch()
    managed = root / _CLI
    managed.write_bytes(b"truncated")
    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path / "sd-home" / "studio"))
    assert eng.is_managed_binary(str(managed)) is True

    monkeypatch.setattr(
        bk, "find_sd_cpp_binary", lambda: str(managed) if managed.exists() else None
    )
    monkeypatch.setattr(bk, "_server_binary_runnable", lambda *_a, **_k: False)
    installs: list = []

    def _install(**kwargs):
        installs.append(kwargs)
        managed.write_bytes(b"good")
        return managed

    import sys
    import types

    stub = types.ModuleType("install_sd_cpp_prebuilt")
    stub.install = _install
    monkeypatch.setitem(sys.modules, "install_sd_cpp_prebuilt", stub)

    out = bk.ensure_sd_cpp_binary(accelerator = "cpu")
    assert installs, "the unusable managed copy must trigger a reinstall"
    assert out == str(managed)


def test_an_unrunnable_user_supplied_binary_is_never_deleted(monkeypatch, tmp_path):
    # SD_CLI_PATH / PATH / an in-tree build belong to the user: report them and let the router's probe refuse, never remove them.
    import core.inference.sd_cpp_backend as bk

    outside = tmp_path / "mine" / _CLI
    outside.parent.mkdir(parents = True)
    outside.write_bytes(b"truncated")
    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path / "elsewhere" / "studio"))
    monkeypatch.setattr(bk, "find_sd_cpp_binary", lambda: str(outside))
    monkeypatch.setattr(bk, "_server_binary_runnable", lambda *_a, **_k: False)

    assert bk.ensure_sd_cpp_binary(accelerator = "cpu") == str(outside)
    assert outside.exists(), "a user-supplied binary must survive"


def test_unrunnable_binary_in_an_unmarked_root_is_kept_because_install_would_refuse(
    monkeypatch, tmp_path
):
    # install() refuses an unmarked non-empty target, so a binary there must be left in place.
    import types

    import core.inference.sd_cpp_backend as bk
    import core.inference.sd_cpp_engine as eng

    root = tmp_path / "sd-home" / "stable-diffusion.cpp" / "sd-bin"
    root.mkdir(parents = True)
    server = root / _SERVER
    server.write_bytes(b"truncated")
    (root / _CLI).write_bytes(b"truncated")
    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path / "sd-home" / "studio"))
    assert eng.is_managed_binary(str(server)) is False

    monkeypatch.setattr(
        bk, "find_sd_server_binary", lambda: str(server) if server.exists() else None
    )
    monkeypatch.setattr(bk, "_server_binary_runnable", lambda *_a, **_k: False)

    def _refuse(**_kwargs):
        raise RuntimeError("sd.cpp install target already exists and is not an Unsloth-managed dir")

    stub = types.ModuleType("install_sd_cpp_prebuilt")
    stub.install = _refuse
    monkeypatch.setitem(sys.modules, "install_sd_cpp_prebuilt", stub)

    assert bk.ensure_sd_server_binary(accelerator = "cpu") == str(server)
    assert server.is_file(), "an unmarked binary the installer cannot replace must survive"


def test_the_repair_only_deletes_what_the_installer_may_reinstall(monkeypatch, tmp_path):
    import types

    import core.inference.sd_cpp_backend as bk

    root = tmp_path / "sd-home" / "stable-diffusion.cpp"
    (root / "sd-bin").mkdir(parents = True)
    (root / ".unsloth-studio-owned").touch()
    server = root / "sd-bin" / _SERVER
    server.write_bytes(b"truncated")
    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path / "sd-home" / "studio"))

    monkeypatch.setattr(
        bk, "find_sd_server_binary", lambda: str(server) if server.exists() else None
    )
    monkeypatch.setattr(bk, "_server_binary_runnable", lambda *_a, **_k: False)
    installs: list = []

    def _install(**kwargs):
        installs.append(kwargs)
        server.write_bytes(b"good")
        return server

    stub = types.ModuleType("install_sd_cpp_prebuilt")
    stub.install = _install
    monkeypatch.setitem(sys.modules, "install_sd_cpp_prebuilt", stub)

    assert bk.ensure_sd_server_binary(accelerator = "cpu") == str(server)
    assert installs, "a marked (reclaimable) tree must still be repaired"


def test_a_reinstall_over_an_owned_root_keeps_the_repair_loop_closed(tmp_path, monkeypatch):
    import core.inference.sd_cpp_engine as eng

    zb = _zip_with_sd_cli()
    _stub_release(monkeypatch, zip_bytes = zb, digest = "sha256:" + hashlib.sha256(zb).hexdigest())
    target = tmp_path / "sd-home" / "stable-diffusion.cpp"
    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path / "sd-home" / "studio"))

    sd_cli = install(install_dir = target)
    assert (target / ".unsloth-studio-owned").is_file()
    assert eng.is_managed_binary(str(sd_cli)) is True


def test_install_records_the_accelerator_it_installed(tmp_path, monkeypatch):
    """The record is what lets a later ensure_* tell a CPU bundle from a GPU one."""
    zb = _zip_with_sd_cli()
    _stub_release(monkeypatch, zip_bytes = zb, digest = "sha256:" + hashlib.sha256(zb).hexdigest())
    target = tmp_path / "sd-home" / "stable-diffusion.cpp"
    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path / "sd-home" / "studio"))

    install(install_dir = target)
    assert sdmod.installed_accelerator(target) == "cpu"
    assert sdmod.accelerator_class("auto") == sdmod.accelerator_class("cpu") == "cpu"
    assert sdmod.accelerator_class("CUDA") == "cuda"
    assert sdmod.installed_accelerator(tmp_path / "nothing-here") is None


def _managed_tree(
    tmp_path,
    monkeypatch,
    accelerator = None,
):
    """An Unsloth-owned install tree, optionally carrying an install record."""
    root = tmp_path / "sd-home" / "stable-diffusion.cpp"
    (root / "sd-bin").mkdir(parents = True)
    (root / ".unsloth-studio-owned").touch()
    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path / "sd-home" / "studio"))
    if accelerator is not None:
        sdmod._write_install_record(root, accelerator = accelerator, repo = "r", tag = "t")
    return root


def test_a_cpu_install_is_reinstalled_when_cuda_is_requested(tmp_path, monkeypatch):
    """A CUDA host holding a CPU bundle must reinstall: ensure_* accepted any runnable binary."""
    bk, root, server = _shared_setup_1(monkeypatch, tmp_path)
    installs: list = []

    def _install(**kwargs):
        installs.append(kwargs)
        server.write_bytes(b"cuda-build")
        sdmod._write_install_record(root, accelerator = kwargs["accelerator"], repo = "r", tag = "t")
        return root / "sd-bin" / _CLI

    monkeypatch.setattr(sdmod, "install", _install)

    assert bk.ensure_sd_server_binary(accelerator = "cuda") == str(server)
    assert [k["accelerator"] for k in installs] == ["cuda"], "the CUDA build must be installed"
    assert server.read_bytes() == b"cuda-build"
    assert bk.ensure_sd_server_binary(accelerator = "cuda") == str(server)
    assert len(installs) == 1


def test_a_legacy_sibling_install_is_read_from_its_own_root(tmp_path, monkeypatch):
    """The accelerator record is read from the tree the binary sits in."""
    import core.inference.sd_cpp_backend as bk

    home = tmp_path / "sd-home" / "studio"
    home.mkdir(parents = True)
    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(home))
    legacy = tmp_path / "sd-home" / "stable-diffusion.cpp"
    (legacy / "sd-bin").mkdir(parents = True)
    (legacy / ".unsloth-studio-owned").touch()
    sdmod._write_install_record(legacy, accelerator = "cuda", repo = "r", tag = "t")
    sdmod._INSTALLED_ACCELERATOR_MEMO.clear()  # the record must be read off disk, not memoised

    server = legacy / "sd-bin" / _SERVER
    server.write_bytes(b"cuda-build")
    monkeypatch.setattr(bk, "find_sd_server_binary", lambda: str(server))
    monkeypatch.setattr(bk, "_server_binary_runnable", lambda *_a, **_k: True)
    monkeypatch.setattr(bk, "_failed_accelerator_upgrades", set())
    installs: list = []
    monkeypatch.setattr(sdmod, "install", lambda **kw: installs.append(kw))

    assert bk.ensure_sd_server_binary(accelerator = "cuda") == str(server)
    assert (
        installs == []
    ), "the CUDA build recorded in the legacy root is already what was asked for"


def test_asking_for_the_cpu_build_never_reinstalls(tmp_path, monkeypatch):
    """Only an upgrade reinstalls. A CPU/auto request must reuse whatever is there, including an
    install predating the record, or every CPU host would re-download on its next load."""
    import core.inference.sd_cpp_backend as bk

    root = _managed_tree(tmp_path, monkeypatch, accelerator = None)
    server = root / "sd-bin" / _SERVER
    server.write_bytes(b"cpu-build")
    cli = root / "sd-bin" / _CLI
    cli.write_bytes(b"cpu-build")
    monkeypatch.setattr(bk, "find_sd_server_binary", lambda: str(server))
    monkeypatch.setattr(bk, "find_sd_cpp_binary", lambda: str(cli))
    monkeypatch.setattr(bk, "_server_binary_runnable", lambda *_a, **_k: True)
    monkeypatch.setattr(bk, "_failed_accelerator_upgrades", set())

    def _install(**_kwargs):
        raise AssertionError("a CPU request must not reinstall")

    monkeypatch.setattr(sdmod, "install", _install)
    assert bk.ensure_sd_server_binary(accelerator = "cpu") == str(server)
    assert bk.ensure_sd_cpp_binary(accelerator = "auto") == str(cli)


def test_a_user_supplied_binary_is_never_reinstalled_over_on_an_accelerator_change(
    tmp_path, monkeypatch
):
    """An unmarked root is the user's own build. install() would refuse it anyway, so attempting
    the upgrade would only cost a download and end with no binary at all."""
    import core.inference.sd_cpp_backend as bk

    root = tmp_path / "sd-home" / "stable-diffusion.cpp"
    (root / "sd-bin").mkdir(parents = True)
    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path / "sd-home" / "studio"))
    server = root / "sd-bin" / _SERVER
    server.write_bytes(b"users-own-build")
    monkeypatch.setattr(bk, "find_sd_server_binary", lambda: str(server))
    monkeypatch.setattr(bk, "_server_binary_runnable", lambda *_a, **_k: True)
    monkeypatch.setattr(bk, "_failed_accelerator_upgrades", set())

    def _install(**_kwargs):
        raise AssertionError("an unmarked (user-owned) root must not be reinstalled over")

    monkeypatch.setattr(sdmod, "install", _install)
    assert bk.ensure_sd_server_binary(accelerator = "cuda") == str(server)


def test_a_failed_upgrade_keeps_the_working_binary_and_stops_retrying(tmp_path, monkeypatch):
    """A host with no asset for the requested accelerator must keep the binary it has (returning
    None would drop native inference entirely) and must not re-resolve on every later load."""
    bk, root, server = _shared_setup_1(monkeypatch, tmp_path)
    attempts: list = []

    def _install(**kwargs):
        attempts.append(kwargs)
        raise RuntimeError("No prebuilt sd-cli for this host")

    monkeypatch.setattr(sdmod, "install", _install)

    assert bk.ensure_sd_server_binary(accelerator = "vulkan") == str(server)
    assert bk.ensure_sd_server_binary(accelerator = "vulkan") == str(server)
    assert len(attempts) == 1, "the hopeless upgrade must be attempted once, not once per load"
    assert server.read_bytes() == b"cpu-build"


def test_the_upgrade_waits_for_the_resident_server_to_stop(tmp_path, monkeypatch):
    """The install must wait for the resident sd-server to stop (ETXTBSY, Windows lock)."""
    bk, root, server = _shared_setup_1(monkeypatch, tmp_path)
    _shared_setup_4(bk, monkeypatch)
    installs: list = []

    def _install(**kwargs):
        installs.append(kwargs)
        server.write_bytes(b"cuda-build")
        sdmod._write_install_record(root, accelerator = kwargs["accelerator"], repo = "r", tag = "t")
        return root / "sd-bin" / _CLI

    monkeypatch.setattr(sdmod, "install", _install)

    backend = bk.SdCppDiffusionBackend()
    backend._state = types.SimpleNamespace(server = object())
    mode, resolved, _engine = backend._resolve_backend()
    assert mode == "server" and resolved == str(server)
    assert installs == [], "no install may run while the server holds its own executable"
    assert server.read_bytes() == b"cpu-build"

    backend._state = None
    upgraded = backend._upgrade_server_after_teardown(str(server))
    assert [k["accelerator"] for k in installs] == ["cuda"]
    assert upgraded == str(server) and server.read_bytes() == b"cuda-build"
    assert backend._upgrade_server_after_teardown(str(server)) == str(server)
    assert len(installs) == 1


def test_a_failed_post_teardown_upgrade_keeps_the_existing_server(tmp_path, monkeypatch):
    """An upgrade may never cost the load the binary it already had."""
    bk, root, server = _shared_setup_1(monkeypatch, tmp_path)
    _shared_setup_4(bk, monkeypatch)

    def _boom(**_kwargs):
        raise RuntimeError("no prebuilt for this host")

    monkeypatch.setattr(sdmod, "install", _boom)

    backend = bk.SdCppDiffusionBackend()
    backend._state = None
    assert backend._upgrade_server_after_teardown(str(server)) == str(server)
    assert server.read_bytes() == b"cpu-build"


def test_a_recorded_gpu_install_is_replaced_when_the_cpu_build_is_wanted(tmp_path, monkeypatch):
    """Only a recorded accelerator mismatch reinstalls; a GPU install is replaced when CPU is wanted."""
    bk, root, server = _shared_setup_9(monkeypatch, tmp_path)
    monkeypatch.setattr(bk, "find_sd_server_binary", lambda: str(server))
    monkeypatch.setattr(bk, "_server_binary_runnable", lambda *_a, **_k: True)
    monkeypatch.setattr(bk, "_failed_accelerator_upgrades", set())
    installs: list = []

    def _install(**kwargs):
        installs.append(kwargs)
        server.write_bytes(b"cpu-build")
        sdmod._write_install_record(root, accelerator = kwargs["accelerator"], repo = "r", tag = "t")
        return root / "sd-bin" / _CLI

    monkeypatch.setattr(sdmod, "install", _install)

    assert bk.ensure_sd_server_binary(accelerator = "cpu") == str(server)
    assert [k["accelerator"] for k in installs] == ["cpu"]
    assert server.read_bytes() == b"cpu-build"
    assert bk.ensure_sd_server_binary(accelerator = "cpu") == str(server)
    assert len(installs) == 1


def test_the_upgrade_waits_for_an_active_one_shot_generation(tmp_path, monkeypatch):
    """A one-shot load holds the managed tree, so the upgrade defers until teardown."""
    bk, root, server = _shared_setup_1(monkeypatch, tmp_path)
    _shared_setup_4(bk, monkeypatch)
    installs: list = []

    def _install(**kwargs):
        installs.append(kwargs)
        server.write_bytes(b"cuda-build")
        sdmod._write_install_record(root, accelerator = kwargs["accelerator"], repo = "r", tag = "t")
        return root / "sd-bin" / _CLI

    monkeypatch.setattr(sdmod, "install", _install)

    backend = bk.SdCppDiffusionBackend()
    backend._state = types.SimpleNamespace(server = None)
    backend._active_generate_cancel = threading.Event()
    mode, resolved, _engine = backend._resolve_backend()
    assert mode == "server" and resolved == str(server)
    assert installs == [], "no install may run while a one-shot sd-cli is executing"
    assert server.read_bytes() == b"cpu-build"
    assert backend._deferred_accelerator_install is True

    backend._state = None
    backend._active_generate_cancel = None
    assert backend._upgrade_server_after_teardown(str(server)) == str(server)
    assert [k["accelerator"] for k in installs] == ["cuda"]
    assert server.read_bytes() == b"cuda-build"


def test_an_idle_backend_installs_the_matching_build_immediately(tmp_path, monkeypatch):
    """The deferral is only for a tree in use: with nothing running, resolving installs at once."""
    bk, root, server = _shared_setup_1(monkeypatch, tmp_path)
    _shared_setup_4(bk, monkeypatch)
    installs: list = []

    def _install(**kwargs):
        installs.append(kwargs)
        server.write_bytes(b"cuda-build")
        sdmod._write_install_record(root, accelerator = kwargs["accelerator"], repo = "r", tag = "t")
        return root / "sd-bin" / _CLI

    monkeypatch.setattr(sdmod, "install", _install)

    backend = bk.SdCppDiffusionBackend()
    mode, resolved, _engine = backend._resolve_backend()
    assert mode == "server" and resolved == str(server)
    assert [k["accelerator"] for k in installs] == ["cuda"]
    assert backend._deferred_accelerator_install is False


def test_the_router_entry_point_cannot_replace_a_running_server(tmp_path, monkeypatch):
    """The refusal lives in _accelerator_changed, which the router entry point skips."""
    bk, root, server = _shared_setup_1(monkeypatch, tmp_path)
    installs: list = []

    def _install(**kwargs):
        installs.append(kwargs)
        server.write_bytes(b"cuda-build")
        sdmod._write_install_record(root, accelerator = kwargs["accelerator"], repo = "r", tag = "t")
        return root / "sd-bin" / _CLI

    monkeypatch.setattr(sdmod, "install", _install)

    resident = bk.SdCppDiffusionBackend()
    resident._state = types.SimpleNamespace(server = object())
    monkeypatch.setattr(bk, "_sd_cpp_backend", resident)

    assert bk.ensure_sd_server_binary(accelerator = "cuda") == str(server)
    assert installs == [], "the running server's file may not be overwritten"
    assert server.read_bytes() == b"cpu-build"

    monkeypatch.setattr(bk, "_sd_cpp_backend", None)
    assert bk.ensure_sd_server_binary(accelerator = "cuda") == str(server)
    assert [k["accelerator"] for k in installs] == ["cuda"]


def test_the_one_shot_fallback_keeps_the_requested_accelerator(tmp_path, monkeypatch):
    """`_resolve_engine` fallback must keep the requested accelerator, not default to cpu."""
    import core.inference.sd_cpp_backend as bk

    root = _managed_tree(tmp_path, monkeypatch, accelerator = "cuda")
    cli = root / "sd-bin" / _CLI
    cli.write_bytes(b"cuda-build")
    monkeypatch.setattr(bk, "find_sd_cpp_binary", lambda: str(cli))
    monkeypatch.setattr(bk, "_server_binary_runnable", lambda *_a, **_k: True)
    monkeypatch.setattr(bk, "_failed_accelerator_upgrades", set())
    _shared_setup_4(bk, monkeypatch)
    monkeypatch.setattr(
        bk,
        "SdCppEngine",
        lambda binary: types.SimpleNamespace(
            binary = binary, is_available = lambda: True, version = lambda: "x"
        ),
    )

    def _install(**kwargs):
        raise AssertionError(f"no reinstall may happen here (asked for {kwargs['accelerator']})")

    monkeypatch.setattr(sdmod, "install", _install)

    backend = bk.SdCppDiffusionBackend()
    assert backend._resolve_engine().binary == str(cli)
    assert cli.read_bytes() == b"cuda-build"


def test_a_serverless_deferred_install_still_lands_after_teardown(tmp_path, monkeypatch):
    """Gating the retry on mode == "server" skipped the sd-cli install a serverless load needs."""
    bk, cli, root = _shared_setup_8(monkeypatch, tmp_path)
    cli.write_bytes(b"cpu-build")
    monkeypatch.setattr(bk, "find_sd_server_binary", lambda: None)
    monkeypatch.setattr(bk, "find_sd_cpp_binary", lambda: str(cli))
    monkeypatch.setattr(bk, "_server_binary_runnable", lambda *_a, **_k: True)
    monkeypatch.setattr(bk, "_failed_accelerator_upgrades", set())
    _shared_setup_4(bk, monkeypatch)
    installs: list = []

    def _install(**kwargs):
        installs.append(kwargs)
        cli.write_bytes(b"cuda-build")
        sdmod._write_install_record(root, accelerator = kwargs["accelerator"], repo = "r", tag = "t")
        return cli

    monkeypatch.setattr(sdmod, "install", _install)

    backend = bk.SdCppDiffusionBackend()
    backend._state = types.SimpleNamespace(server = None)
    backend._active_generate_cancel = threading.Event()
    mode, server_binary, _engine = backend._resolve_backend()
    assert mode == "oneshot" and server_binary is None
    assert installs == [] and backend._deferred_accelerator_install is True

    backend._state = None
    backend._active_generate_cancel = None
    assert backend._upgrade_server_after_teardown(None) is None
    assert [k["accelerator"] for k in installs] == ["cuda"], "the sd-cli still has to be upgraded"
    assert cli.read_bytes() == b"cuda-build"

    assert backend._upgrade_server_after_teardown(None) is None
    assert len(installs) == 1


def test_a_server_still_starting_also_holds_the_tree(tmp_path, monkeypatch):
    """A server still starting holds the tree via `_pending_server`."""
    bk, root, server = _shared_setup_1(monkeypatch, tmp_path)
    installs: list = []

    def _install(**kwargs):
        installs.append(kwargs)
        server.write_bytes(b"cuda-build")
        sdmod._write_install_record(root, accelerator = kwargs["accelerator"], repo = "r", tag = "t")
        return root / "sd-bin" / _CLI

    monkeypatch.setattr(sdmod, "install", _install)

    starting = bk.SdCppDiffusionBackend()
    starting._state = None
    starting._pending_server = object()
    monkeypatch.setattr(bk, "_sd_cpp_backend", starting)

    assert bk.ensure_sd_server_binary(accelerator = "cuda") == str(server)
    assert installs == [], "the starting server's file may not be overwritten"
    assert server.read_bytes() == b"cpu-build"

    starting._pending_server = None
    assert bk.ensure_sd_server_binary(accelerator = "cuda") == str(server)
    assert [k["accelerator"] for k in installs] == ["cuda"]


def test_a_serverless_install_is_not_replaced_under_a_running_cli(tmp_path, monkeypatch):
    """The gap a mismatch-only guard leaves: on a legacy install with no sd-server,
    find_sd_server_binary returns None, so _accelerator_changed is never consulted and the install
    runs unconditionally. The router calls this directly with installs enabled, so a one-shot
    sd-cli mid-generation would have the tree extracted over it."""
    bk, cli, root = _shared_setup_8(monkeypatch, tmp_path)
    cli.write_bytes(b"cpu-build")
    monkeypatch.setattr(bk, "find_sd_server_binary", lambda: None)
    monkeypatch.setattr(bk, "find_sd_cpp_binary", lambda: str(cli))
    monkeypatch.setattr(bk, "_server_binary_runnable", lambda *_a, **_k: True)
    monkeypatch.setattr(bk, "_failed_accelerator_upgrades", set())
    installs: list = []

    def _install(**kwargs):
        installs.append(kwargs)
        cli.write_bytes(b"cuda-build")
        sdmod._write_install_record(root, accelerator = kwargs["accelerator"], repo = "r", tag = "t")
        return cli

    monkeypatch.setattr(sdmod, "install", _install)

    generating = bk.SdCppDiffusionBackend()
    generating._active_generate_cancel = threading.Event()
    monkeypatch.setattr(bk, "_sd_cpp_backend", generating)

    assert bk.ensure_sd_server_binary(accelerator = "cuda") is None
    assert bk.ensure_sd_cpp_binary(accelerator = "cuda") == str(cli)
    assert installs == [], "no extraction over a running sd-cli"
    assert cli.read_bytes() == b"cpu-build"

    monkeypatch.setattr(bk, "_sd_cpp_backend", None)
    bk.ensure_sd_server_binary(accelerator = "cuda")
    assert [k["accelerator"] for k in installs] == ["cuda"]


def test_the_tree_stays_in_use_until_a_stopping_server_is_gone(tmp_path, monkeypatch):
    """The tree stays in use while a stopping server is still running."""
    import core.inference.sd_cpp_backend as bk

    backend = bk.SdCppDiffusionBackend()
    seen: list = []

    class _SlowServer:
        def stop(self):
            seen.append(bk._tree_in_use(backend))

    backend._stop_server(_SlowServer())
    assert seen == [True], "the tree must read busy until stop() returns"
    assert bk._tree_in_use(backend) is False
    assert backend._stopping_servers == 0

    class _BadServer:
        def stop(self):
            raise RuntimeError("terminate failed")

    backend._stop_server(_BadServer())
    assert backend._stopping_servers == 0 and bk._tree_in_use(backend) is False


def test_a_failed_server_upgrade_is_not_retried_by_the_cli_probe(tmp_path, monkeypatch):
    """A failed server upgrade left no record, so the CLI probe re-downloaded the same bundle."""
    bk, cli, root = _shared_setup_8(monkeypatch, tmp_path)
    cli.write_bytes(b"cpu-build")
    monkeypatch.setattr(bk, "find_sd_server_binary", lambda: None)
    monkeypatch.setattr(bk, "find_sd_cpp_binary", lambda: str(cli))
    monkeypatch.setattr(bk, "_server_binary_runnable", lambda *_a, **_k: True)
    monkeypatch.setattr(bk, "_failed_accelerator_upgrades", set())
    monkeypatch.setattr(bk, "_sd_cpp_backend", None)
    attempts: list = []

    def _boom(**kwargs):
        attempts.append(kwargs["accelerator"])
        raise RuntimeError("no cuda asset for this host")

    monkeypatch.setattr(sdmod, "install", _boom)

    assert bk.ensure_sd_server_binary(accelerator = "cuda") is None
    assert bk.ensure_sd_cpp_binary(accelerator = "cuda") == str(cli)
    assert attempts == ["cuda"], "the same bundle must not be resolved twice in one selection"


def test_a_bundle_drops_the_binaries_it_did_not_supply(tmp_path, monkeypatch):
    """Extraction merges, so drop binaries the bundle did not supply, or stale build/bin copies win."""
    target = tmp_path / "sd"
    suffix = ".exe" if sys.platform == "win32" else ""
    old_dir = target / "build" / "bin"
    old_dir.mkdir(parents = True)
    (old_dir / f"sd-cli{suffix}").write_bytes(b"old-cpu-cli")
    (old_dir / f"sd-server{suffix}").write_bytes(b"old-cpu-server")
    new_dir = target / "sd-bundle-cuda12" / "bin"
    new_dir.mkdir(parents = True)
    (new_dir / f"sd-cli{suffix}").write_bytes(b"new-cuda-cli")

    buf = io.BytesIO()
    with zipfile.ZipFile(buf, "w") as zf:
        zf.writestr(f"sd-bundle-cuda12/bin/sd-cli{suffix}", "new")
    buf.seek(0)
    with zipfile.ZipFile(buf) as zf:
        supplied = sdmod._archive_binary_paths(zf, target)

    sdmod._discard_superseded_binaries(target, supplied)
    assert not (old_dir / f"sd-cli{suffix}").exists()
    assert not (old_dir / f"sd-server{suffix}").exists()
    assert (new_dir / f"sd-cli{suffix}").read_bytes() == b"new-cuda-cli"


def test_a_bundle_keeps_every_binary_it_wrote(tmp_path):
    """Sweep keys on the archive's member list; deleting a just-extracted copy breaks installs."""
    target = tmp_path / "sd"
    suffix = ".exe" if sys.platform == "win32" else ""
    d = target / "bin"
    d.mkdir(parents = True)
    (d / f"sd-cli{suffix}").write_bytes(b"new")
    (d / f"sd-server{suffix}").write_bytes(b"new")

    buf = io.BytesIO()
    with zipfile.ZipFile(buf, "w") as zf:
        zf.writestr(f"bin/sd-cli{suffix}", "new")
        zf.writestr(f"bin/sd-server{suffix}", "new")
    buf.seek(0)
    with zipfile.ZipFile(buf) as zf:
        supplied = sdmod._archive_binary_paths(zf, target)

    sdmod._discard_superseded_binaries(target, supplied)
    assert (d / f"sd-cli{suffix}").exists() and (d / f"sd-server{suffix}").exists()


def test_a_superseded_binary_that_cannot_be_removed_fails_the_install(tmp_path, monkeypatch):
    """A leftover binary is still RUNNABLE, so no downstream probe repairs it, and a record naming
    the new accelerator would make _accelerator_changed trust it forever. Withhold both."""
    target = tmp_path / "sd"
    target.mkdir()
    suffix = ".exe" if sys.platform == "win32" else ""
    (target / f"sd-server{suffix}").write_bytes(b"old-cpu-server")

    def _no_unlink(self, *a, **k):
        raise OSError("permission denied")

    monkeypatch.setattr(Path, "unlink", _no_unlink)
    with pytest.raises(sdmod.SupersededBinaryError) as exc:
        sdmod._discard_superseded_binaries(target, set())
    assert "superseded binary" in str(exc.value)


def test_a_bundle_with_no_cli_is_refused_before_anything_is_swept(tmp_path, monkeypatch, capsys):
    """A bundle with no CLI is refused before the sweep, so the working binary survives."""
    buf = io.BytesIO()
    with zipfile.ZipFile(buf, "w") as zf:
        zf.writestr(f"build/bin/{_SERVER}", b"#!/bin/sh\necho sd-server\n")
    zb = buf.getvalue()
    _stub_release(monkeypatch, zip_bytes = zb, digest = "sha256:" + hashlib.sha256(zb).hexdigest())

    target = tmp_path / "sd"
    (target / "build" / "bin").mkdir(parents = True)
    working = target / "build" / "bin" / _CLI
    working.write_bytes(b"old-but-working")
    (target / ".unsloth-studio-owned").touch()

    with pytest.raises(RuntimeError) as exc:
        install(install_dir = target)
    assert "no sd-cli" in str(exc.value)
    assert working.read_bytes() == b"old-but-working"
    assert "removed a superseded binary" not in capsys.readouterr().out


def test_an_unreadable_record_does_not_retire_the_memo(tmp_path, monkeypatch):
    """An unreadable record does not retire the memo."""
    root = _shared_setup_10(tmp_path)

    real_open = builtins.open

    def _readonly_record(
        file,
        mode = "r",
        *a,
        **k,
    ):
        if str(file).endswith(sdmod.INSTALL_RECORD) and "w" in mode:
            raise OSError("permission denied")
        return real_open(file, mode, *a, **k)

    monkeypatch.setattr(builtins, "open", _readonly_record)
    sdmod._write_install_record(root, accelerator = "cuda", repo = "r", tag = "t")
    monkeypatch.setattr(builtins, "open", real_open)
    assert sdmod.installed_accelerator(root) == "cuda"

    def _unreadable(
        file,
        mode = "r",
        *a,
        **k,
    ):
        if str(file).endswith(sdmod.INSTALL_RECORD):
            raise PermissionError("the file is open in another process")
        return real_open(file, mode, *a, **k)

    monkeypatch.setattr(builtins, "open", _unreadable)
    assert sdmod.installed_accelerator(root) == "cuda"
    monkeypatch.setattr(builtins, "open", real_open)
    assert sdmod.installed_accelerator(root) == "cuda"
    assert str(root) in sdmod._INSTALLED_ACCELERATOR_MEMO


def test_an_external_record_update_retires_the_memo(tmp_path, monkeypatch):
    """The memo covers only a record it could not replace; once rewritten by anyone, the file wins."""
    root = _shared_setup_10(tmp_path)

    real_open = builtins.open

    def _readonly_record(
        file,
        mode = "r",
        *a,
        **k,
    ):
        if str(file).endswith(sdmod.INSTALL_RECORD) and "w" in mode:
            raise OSError("permission denied")
        return real_open(file, mode, *a, **k)

    monkeypatch.setattr(builtins, "open", _readonly_record)
    sdmod._write_install_record(root, accelerator = "cuda", repo = "r", tag = "t")
    monkeypatch.setattr(builtins, "open", real_open)
    assert sdmod.installed_accelerator(root) == "cuda"

    with open(root / sdmod.INSTALL_RECORD, "w", encoding = "utf-8") as f:
        json.dump({"accelerator": "vulkan", "repo": "r", "tag": "newer"}, f)
    assert sdmod.installed_accelerator(root) == "vulkan"
    assert str(root) not in sdmod._INSTALLED_ACCELERATOR_MEMO


def test_a_successful_record_write_retires_an_earlier_memo(tmp_path, monkeypatch):
    """A memo from a failed write must not outlive the write that succeeds after it."""
    root = tmp_path / "sd"
    root.mkdir()
    sdmod._INSTALLED_ACCELERATOR_MEMO[str(root)] = ("cuda", "")
    sdmod._write_install_record(root, accelerator = "cpu", repo = "r", tag = "t")
    assert str(root) not in sdmod._INSTALLED_ACCELERATOR_MEMO
    assert sdmod.installed_accelerator(root) == "cpu"


def test_the_stop_is_reserved_before_the_server_is_unpublished(tmp_path, monkeypatch):
    """Claim the count in the same lock that clears _state/_pending_server, or the tree looks idle."""
    import core.inference.sd_cpp_backend as bk

    backend = bk.SdCppDiffusionBackend()
    seen: list = []

    class _Server:
        def stop(self):
            seen.append(bk._tree_in_use(backend))

        def is_alive(self):
            return True

    server = _Server()
    backend._state = types.SimpleNamespace(server = server, mode = "server")
    monkeypatch.setattr(backend, "status", lambda: {"loaded": False})

    backend.unload()
    assert seen == [True], "the tree must still read busy while the old server is going down"
    assert backend._stopping_servers == 0 and bk._tree_in_use(backend) is False


def test_a_failed_start_does_not_block_its_own_cli_fallback(tmp_path, monkeypatch):
    """A stopped server left in _pending_server makes the tree look busy and disables the CLI fallback."""
    import core.inference.sd_cpp_backend as bk

    backend = bk.SdCppDiffusionBackend()
    server = object()
    backend._pending_server = server
    assert bk._tree_in_use(backend) is True
    with backend._lock:
        if backend._pending_server is server:
            backend._pending_server = None
    assert bk._tree_in_use(backend) is False


def test_an_unwritable_record_does_not_cost_the_install_or_repeat_it(tmp_path, monkeypatch):
    """An unwritable record does not fail the install; the accelerator is remembered for this process."""
    root = tmp_path / "sd"
    root.mkdir()
    (root / sdmod.INSTALL_RECORD).mkdir()
    sdmod._INSTALLED_ACCELERATOR_MEMO.clear()
    sdmod._INSTALLED_SHIPS_SERVER_MEMO.clear()

    sdmod._write_install_record(root, accelerator = "cuda", repo = "r", tag = "t")
    assert sdmod.read_install_record(root) == {}
    assert sdmod.installed_accelerator(root) == "cuda"


def test_a_stale_unwritable_record_does_not_outrank_what_was_just_installed(tmp_path, monkeypatch):
    """A readable but unreplaceable old record keeps answering cpu; the newer install must win."""
    root = _shared_setup_10(tmp_path)
    sdmod._INSTALLED_SHIPS_SERVER_MEMO.clear()

    real_open = builtins.open

    def _readonly_record(
        file,
        mode = "r",
        *a,
        **k,
    ):
        if str(file).endswith(sdmod.INSTALL_RECORD) and "w" in mode:
            raise OSError("permission denied")
        return real_open(file, mode, *a, **k)

    monkeypatch.setattr(builtins, "open", _readonly_record)
    sdmod._write_install_record(root, accelerator = "cuda", repo = "r", tag = "t")
    monkeypatch.setattr(builtins, "open", real_open)

    assert sdmod.read_install_record(root)["accelerator"] == "cpu"
    assert sdmod.installed_accelerator(root) == "cuda"


def test_a_generation_cannot_start_inside_the_install_window(tmp_path, monkeypatch):
    """Admission and install are one decision, held across the install window."""
    bk, root, server = _shared_setup_1(monkeypatch, tmp_path)
    monkeypatch.setattr(bk, "_sd_cpp_backend", None)

    started = threading.Event()
    release = threading.Event()
    admitted_during_install: list = []

    def _slow_install(**kwargs):
        started.set()
        release.wait(5)
        server.write_bytes(b"cuda-build")
        sdmod._write_install_record(root, accelerator = kwargs["accelerator"], repo = "r", tag = "t")
        return root / "sd-bin" / _CLI

    monkeypatch.setattr(sdmod, "install", _slow_install)

    installer = threading.Thread(
        target = lambda: bk.ensure_sd_server_binary(accelerator = "cuda"), daemon = True
    )
    installer.start()
    assert started.wait(5), "the install did not start"

    def _try_generate():
        with bk._tree_reader(str(server)):
            admitted_during_install.append(bk._tree_installing)

    generator = threading.Thread(target = _try_generate, daemon = True)
    generator.start()
    generator.join(1.0)
    assert (
        generator.is_alive()
    ), "a generation must not be admitted while the tree is being replaced"
    assert admitted_during_install == []

    release.set()
    installer.join(5)
    generator.join(5)
    assert not generator.is_alive(), "the generation must be admitted once the install is done"
    assert admitted_during_install == [False]
    assert server.read_bytes() == b"cuda-build"


def test_an_install_stands_down_while_a_generation_is_running(tmp_path, monkeypatch):
    """The other direction of the same handshake, so the two can never interleave."""
    bk, root, server = _shared_setup_1(monkeypatch, tmp_path)
    monkeypatch.setattr(bk, "_sd_cpp_backend", None)
    monkeypatch.setattr(
        sdmod, "install", lambda **_k: pytest.fail("no install while a generation is running")
    )

    with bk._tree_reader(str(server)):
        assert bk.ensure_sd_server_binary(accelerator = "cuda") == str(server)
        assert server.read_bytes() == b"cpu-build"


def test_an_unmanaged_binary_never_waits_for_a_managed_install(tmp_path, monkeypatch):
    """An sd-cli from SD_CLI_PATH / UNSLOTH_SD_CPP_PATH / an in-tree build / PATH is one the
    installer cannot replace, so an install in flight is nothing to it. Claiming for it would stall
    the generation behind an unrelated multi-GB download for the whole timeout."""
    import core.inference.sd_cpp_backend as bk

    _managed_tree(tmp_path, monkeypatch)
    outside = tmp_path / "mine" / _CLI
    outside.parent.mkdir(parents = True)
    outside.write_bytes(b"my own build")

    monkeypatch.setattr(bk, "_tree_installing", True)
    monkeypatch.setattr(bk, "_TREE_WAIT_TIMEOUT_S", 0.2)
    with bk._tree_reader(str(outside)):
        pass
    assert bk._tree_readers == 0


def test_a_reader_is_never_admitted_when_the_install_wait_times_out(tmp_path, monkeypatch):
    """wait_for returns False on a timeout while _tree_installing is still true. Ignoring that and
    admitting anyway recreates the overwrite/ETXTBSY race this admission control exists for."""
    import core.inference.sd_cpp_backend as bk

    root = _managed_tree(tmp_path, monkeypatch)
    managed = root / "sd-bin" / _CLI
    managed.write_bytes(b"managed")

    monkeypatch.setattr(bk, "_tree_installing", True)
    monkeypatch.setattr(bk, "_TREE_WAIT_TIMEOUT_S", 0.2)
    with pytest.raises(RuntimeError) as exc:
        with bk._tree_reader(str(managed)):
            pytest.fail("a generation must not run against binaries an install still holds")
    assert "still replacing its binaries" in str(exc.value)
    assert bk._tree_readers == 0


def test_an_incomplete_tree_replacement_is_retried_not_memoised(tmp_path, monkeypatch):
    """_discard_superseded_binaries withholds the record so the NEXT load retries the sweep.
    Recording the accelerator as a failed upgrade defeats exactly that: _accelerator_changed then
    suppresses the mismatch for the rest of the process and the mixed tree is served forever."""
    bk, cli, root = _shared_setup_8(monkeypatch, tmp_path)
    cli.write_bytes(b"old-cpu-cli")
    monkeypatch.setattr(bk, "find_sd_cpp_binary", lambda: str(cli))
    monkeypatch.setattr(bk, "_usable_or_discard_managed", lambda *_a, **_k: True)
    monkeypatch.setattr(bk, "_failed_accelerator_upgrades", set())
    monkeypatch.setattr(bk, "_sd_cpp_backend", None)

    def _install_that_cannot_finish_the_swap(**_kwargs):
        raise sdmod.SupersededBinaryError("could not remove the superseded binary /x/sd-cli")

    monkeypatch.setattr(sdmod, "install", _install_that_cannot_finish_the_swap)
    assert bk.ensure_sd_cpp_binary(accelerator = "cuda") == str(cli)
    assert bk._failed_accelerator_upgrades == set()
    assert bk._accelerator_changed(str(cli), "cuda") is True

    monkeypatch.setattr(sdmod, "install", lambda **_k: (_ for _ in ()).throw(RuntimeError("404")))
    assert bk.ensure_sd_cpp_binary(accelerator = "cuda") == str(cli)
    assert bk._failed_accelerator_upgrades == {"cuda"}


def test_a_generation_re_resolves_the_cli_the_install_moved(tmp_path, monkeypatch):
    """An install landing during the wait can sweep the resolved sd-cli, so resolve it again."""
    import core.inference.sd_cpp_backend as bk
    from core.inference.sd_cpp_engine import SdCppEngine

    root = _managed_tree(tmp_path, monkeypatch)
    new, old = _shared_setup_11(root)
    new.write_bytes(b"new-cuda-cli")

    backend = bk.SdCppDiffusionBackend()
    backend._engine = SdCppEngine(binary = str(old))
    monkeypatch.setattr(bk, "find_sd_cpp_binary", lambda: str(new))
    monkeypatch.setattr(bk, "_usable_or_discard_managed", lambda *_a, **_k: True)
    monkeypatch.setattr(bk, "_install_allowed", lambda: False)

    old.unlink()
    with bk._tree_reader(str(old)):
        engine = backend._resolve_engine()
    assert engine.binary == str(new)
    assert backend._engine.binary == str(new)


def test_a_partial_sweep_never_returns_the_file_it_deleted(tmp_path, monkeypatch):
    """_discard_superseded_binaries takes sd-cli before sd-server, so it can remove the old CLI and
    then raise on the old server. The fallback resolved before the install then names a file that
    is gone, and native routing fails on a path nothing can execute."""
    import core.inference.sd_cpp_backend as bk

    root = _managed_tree(tmp_path, monkeypatch, accelerator = "cpu")
    new, old = _shared_setup_11(root)

    resolved = {"path": str(old)}
    monkeypatch.setattr(bk, "find_sd_cpp_binary", lambda: resolved["path"])
    monkeypatch.setattr(bk, "_usable_or_discard_managed", lambda *_a, **_k: True)
    monkeypatch.setattr(bk, "_failed_accelerator_upgrades", set())
    monkeypatch.setattr(bk, "_sd_cpp_backend", None)

    def _sweep_gets_part_way(**_kwargs):
        old.unlink()
        new.write_bytes(b"new-cuda-cli")
        resolved["path"] = str(new)
        raise sdmod.SupersededBinaryError("could not remove the superseded binary sd-server")

    monkeypatch.setattr(sdmod, "install", _sweep_gets_part_way)
    got = bk.ensure_sd_cpp_binary(accelerator = "cuda")
    assert got == str(new), "must not hand back the copy the sweep deleted"
    assert Path(got).is_file()
    assert bk._failed_accelerator_upgrades == set()


def test_a_re_found_cli_goes_through_the_usability_gate(tmp_path, monkeypatch):
    """The partial-sweep raise happens BEFORE install()'s _make_executable, so on POSIX a freshly
    extracted copy has no execute bit, and find_sd_cpp_binary only checks that the path is a file.
    Handing that back gives the next load a binary that cannot launch."""
    import core.inference.sd_cpp_backend as bk

    root = _managed_tree(tmp_path, monkeypatch, accelerator = "cpu")
    new, old = _shared_setup_11(root)

    resolved = {"path": str(old)}
    monkeypatch.setattr(bk, "find_sd_cpp_binary", lambda: resolved["path"])
    monkeypatch.setattr(bk, "_failed_accelerator_upgrades", set())
    monkeypatch.setattr(bk, "_sd_cpp_backend", None)
    monkeypatch.setattr(bk, "_server_binary_runnable", lambda binary: binary == str(old))

    def _sweep_gets_part_way(**_kwargs):
        old.unlink()
        new.write_bytes(b"new-cuda-cli")
        resolved["path"] = str(new)
        raise sdmod.SupersededBinaryError("could not remove the superseded binary sd-server")

    monkeypatch.setattr(sdmod, "install", _sweep_gets_part_way)
    assert bk.ensure_sd_cpp_binary(accelerator = "cuda") is None
    assert not new.exists()
    assert bk._failed_accelerator_upgrades == set()


def test_a_cancelled_request_leaves_the_install_wait(tmp_path, monkeypatch):
    """Nothing notifies the condition on cancel, so the wait re-checks instead of blocking once."""
    import core.inference.sd_cpp_backend as bk

    root = _managed_tree(tmp_path, monkeypatch)
    managed = root / "sd-bin" / _CLI
    managed.write_bytes(b"managed")

    monkeypatch.setattr(bk, "_tree_installing", True)
    monkeypatch.setattr(bk, "_TREE_WAIT_TICK_S", 0.02)
    cancel = threading.Event()
    threading.Timer(0.1, cancel.set).start()

    started = time.monotonic()
    with pytest.raises(RuntimeError) as exc:
        with bk._tree_reader(str(managed), cancel):
            pytest.fail("a cancelled request must not be admitted either")
    assert time.monotonic() - started < 30
    assert "cancel" in str(exc.value).lower()
    assert bk._tree_readers == 0


def test_the_cuda_runtime_is_fetched_before_anything_is_swept(tmp_path, monkeypatch, capsys):
    """Fetching cudart first avoids a post-sweep failure that is memoised with paths already gone."""
    order: list[str] = []
    zb = _zip_with_sd_cli()
    _stub_release(monkeypatch, zip_bytes = zb, digest = "sha256:" + hashlib.sha256(zb).hexdigest())

    real_sweep = sdmod._discard_superseded_binaries
    monkeypatch.setattr(
        sdmod,
        "_discard_superseded_binaries",
        lambda root, supplied: (order.append("sweep"), real_sweep(root, supplied))[1],
    )
    monkeypatch.setattr(
        sdmod,
        "_maybe_fetch_windows_cudart",
        lambda *_a, **_k: order.append("cudart"),
    )
    install(install_dir = tmp_path)
    assert order == ["cudart", "sweep"]


def test_a_failure_after_the_sweep_is_an_incomplete_replacement(tmp_path, monkeypatch):
    """Everything from the sweep onwards leaves a tree that is a mixture of two bundles. Reported
    as anything else, ensure_* memoises the accelerator and suppresses the retry that repairs it."""
    zb = _zip_with_sd_cli()
    _stub_release(monkeypatch, zip_bytes = zb, digest = "sha256:" + hashlib.sha256(zb).hexdigest())

    def _boom(_root, _supplied):
        raise OSError("the filesystem went away mid-sweep")

    monkeypatch.setattr(sdmod, "_discard_superseded_binaries", _boom)
    with pytest.raises(sdmod.SupersededBinaryError) as exc:
        install(install_dir = tmp_path)
    assert "part way through a replacement" in str(exc.value)


def test_a_failure_finalising_the_new_tree_is_an_incomplete_replacement(tmp_path, monkeypatch):
    """A chmod or locate failure after the sweep leaves a mixed tree; as an ordinary error it
    memoises the accelerator and returns a path the sweep may have removed."""
    zb = _zip_with_sd_cli()
    _stub_release(monkeypatch, zip_bytes = zb, digest = "sha256:" + hashlib.sha256(zb).hexdigest())

    def _chmod_fails(_path):
        raise OSError("read-only filesystem")

    monkeypatch.setattr(sdmod, "_make_executable", _chmod_fails)
    with pytest.raises(sdmod.SupersededBinaryError) as exc:
        install(install_dir = tmp_path)
    assert "part way through a replacement" in str(exc.value)


def test_a_failure_before_the_sweep_is_an_ordinary_install_failure(tmp_path, monkeypatch):
    """The other side of the boundary: nothing has been removed yet, so this really is "this
    accelerator is unavailable" and memoising it is right."""
    zb = _zip_with_sd_cli()
    _stub_release(monkeypatch, zip_bytes = zb, digest = "sha256:" + hashlib.sha256(zb).hexdigest())
    _shared_setup_6(monkeypatch)
    with pytest.raises(RuntimeError) as exc:
        install(install_dir = tmp_path)
    assert not isinstance(exc.value, sdmod.SupersededBinaryError)
    assert "cudart 404" in str(exc.value)


def _owned_tree_holding(tmp_path, rel: str) -> Path:
    """An Unsloth-owned install dir already carrying a previous bundle's sd-cli at ``rel``."""
    (tmp_path / ".unsloth-studio-owned").touch()
    old = tmp_path / rel
    old.parent.mkdir(parents = True, exist_ok = True)
    old.write_bytes(b"the previous build")
    return old


def test_an_upgrade_is_a_replacement_from_the_extract_on(tmp_path, monkeypatch):
    """An upgrade is a replacement from the extract on, not an ordinary failure to memoise."""
    zb = _zip_with_sd_cli()
    _stub_release(monkeypatch, zip_bytes = zb, digest = "sha256:" + hashlib.sha256(zb).hexdigest())
    _owned_tree_holding(tmp_path, f"build/bin/{_CLI}")
    _shared_setup_6(monkeypatch)
    with pytest.raises(sdmod.SupersededBinaryError) as exc:
        install(install_dir = tmp_path)
    assert "part way through a replacement" in str(exc.value)
    assert "cudart 404" in str(exc.value)


def test_a_different_layout_upgrade_is_a_replacement_too(tmp_path, monkeypatch):
    """A different-layout upgrade is a replacement too; build/bin outranks the versioned directory."""
    zb = _zip_with_sd_cli()
    _stub_release(monkeypatch, zip_bytes = zb, digest = "sha256:" + hashlib.sha256(zb).hexdigest())
    old = _owned_tree_holding(tmp_path, f"sd-master-old/bin/{_CLI}")
    _shared_setup_6(monkeypatch)
    with pytest.raises(sdmod.SupersededBinaryError) as exc:
        install(install_dir = tmp_path)
    assert "part way through a replacement" in str(exc.value)
    assert old.read_bytes() == b"the previous build"
    assert (tmp_path / "build" / "bin" / _CLI).is_file()


def test_a_first_install_failing_before_the_sweep_is_an_ordinary_failure(tmp_path, monkeypatch):
    """The other side of it: an empty target has nothing for the new copy to compete with, so no
    lookup can resolve a half-finished binary and "this accelerator is unavailable" is the true
    answer. Memoising it is what stops every later load re-downloading the same failing bundle."""
    zb = _zip_with_sd_cli()
    _stub_release(monkeypatch, zip_bytes = zb, digest = "sha256:" + hashlib.sha256(zb).hexdigest())
    (tmp_path / ".unsloth-studio-owned").touch()
    _shared_setup_6(monkeypatch)
    with pytest.raises(RuntimeError) as exc:
        install(install_dir = tmp_path)
    assert not isinstance(exc.value, sdmod.SupersededBinaryError)
    assert "cudart 404" in str(exc.value)


def _server_load_backend(tmp_path, monkeypatch, root, server, on_fetch):
    """Drives the _server_load_backend helper with the download stubbed."""
    import core.inference.sd_cpp_backend as bk
    from core.inference.diffusion_families import detect_family

    monkeypatch.setattr(bk, "find_sd_server_binary", lambda: str(server))
    monkeypatch.setattr(bk, "_server_binary_runnable", lambda *_a, **_k: True)
    monkeypatch.setattr(bk, "_failed_accelerator_upgrades", set())
    monkeypatch.setattr(bk, "_install_allowed", lambda: False)
    monkeypatch.setattr(bk, "_sd_cpp_backend", None)
    monkeypatch.setattr(
        bk,
        "resolve_diffusion_device_target",
        lambda: types.SimpleNamespace(backend = "cuda", device = "cuda"),
    )
    started: list = []

    class _Server:
        def __init__(self, binary):
            self.binary = binary
            started.append(binary)

        def start(self, *_a, **_k):
            return None

        def stop(self):
            return None

    monkeypatch.setattr(bk, "SdCppServer", _Server)

    fam = detect_family("z-image")
    backend = bk.SdCppDiffusionBackend()
    monkeypatch.setattr(backend, "_asset_specs", lambda *a, **k: [])
    monkeypatch.setattr(backend, "_set_expected_bytes", lambda *a, **k: None)

    def _fetch(*_a, **_k):
        on_fetch()
        return {"diffusion_model": "/m/z.gguf"}

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

    def _run():
        backend._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,
        )

    return backend, started, _run


def test_a_same_path_accelerator_swap_is_refused_before_the_server_starts(tmp_path, monkeypatch):
    """A same-path accelerator swap is refused before the server starts; existence is not identity."""
    root = _managed_tree(tmp_path, monkeypatch, accelerator = "cuda")
    server = root / "sd-bin" / _SERVER
    server.write_bytes(b"cuda-build")

    def _an_h3_load_installs_the_cpu_fallback():
        server.write_bytes(b"cpu-build")
        sdmod._write_install_record(root, accelerator = "cpu", repo = "r", tag = "t")

    backend, started, run = _server_load_backend(
        tmp_path, monkeypatch, root, server, _an_h3_load_installs_the_cpu_fallback
    )
    run()

    assert started == [], "a CPU server may not be started for a load that committed CUDA"
    assert backend._state is None
    assert backend._pending_server is None
    err = backend.load_progress()["error"] or ""
    assert "different accelerator" in err


def test_an_untouched_tree_still_starts_the_server_after_the_download(tmp_path, monkeypatch):
    """The other side of it: nothing replaced the binary, so the re-validation must be invisible.
    A load refused because the tree merely stayed the same would take the server away entirely."""
    root = _managed_tree(tmp_path, monkeypatch, accelerator = "cuda")
    server = root / "sd-bin" / _SERVER
    server.write_bytes(b"cuda-build")

    backend, started, run = _server_load_backend(tmp_path, monkeypatch, root, server, lambda: None)
    run()

    assert started == [str(server)]
    assert backend._state is not None and backend._state.mode == "server"
    assert backend.load_progress()["error"] is None


def test_a_started_server_holds_the_tree_until_state_is_published(tmp_path, monkeypatch):
    """A started server holds the tree until `_state` is published, under one lock."""
    bk, root, server = _shared_setup_9(monkeypatch, tmp_path)

    backend, started, run = _server_load_backend(tmp_path, monkeypatch, root, server, lambda: None)
    # _default_threads() is sampled at server.start() and at the _SdState commit, bracketing the window.
    seen: list[bool] = []
    real_threads = bk._default_threads
    monkeypatch.setattr(
        bk,
        "_default_threads",
        lambda: (seen.append(bk._tree_in_use(backend)), real_threads())[1],
    )
    run()

    assert started == [str(server)]
    assert backend._state is not None and backend._state.server is not None
    assert backend._pending_server is None
    assert len(seen) >= 2 and all(seen), "the tree read as idle while the server was running"


def test_a_superseded_load_unpublishes_the_server_it_stops(tmp_path, monkeypatch):
    """The other end of holding it longer: a load that finds itself superseded must still take the
    started server back out. Left published it reads as "the managed tree is busy" for the rest of
    the process and no install can ever run again."""
    bk, root, server = _shared_setup_9(monkeypatch, tmp_path)

    backend, started, run = _server_load_backend(tmp_path, monkeypatch, root, server, lambda: None)
    real_threads = bk._default_threads

    def _supersede_mid_commit():
        backend._load_token = 2
        return real_threads()

    monkeypatch.setattr(bk, "_default_threads", _supersede_mid_commit)
    run()

    assert started == [str(server)]
    assert backend._state is None
    assert backend._pending_server is None
    assert backend._stopping_servers == 0
    assert not bk._tree_in_use(backend)


def test_the_legacy_lookup_uses_the_lexical_parent_of_a_symlinked_home(tmp_path, monkeypatch):
    """An older build's tree sits beside the link, so the lexical parent of a symlinked home is used."""
    import core.inference.sd_cpp_engine as eng

    target = tmp_path / "elsewhere" / "studio"
    target.mkdir(parents = True)
    home = tmp_path / "studio-home"
    home.symlink_to(target, target_is_directory = True)
    legacy = tmp_path / "stable-diffusion.cpp"
    legacy.mkdir()
    (legacy / ".unsloth-studio-owned").touch()
    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(home))

    assert not (tmp_path / "elsewhere" / "stable-diffusion.cpp").exists()
    assert eng.legacy_sibling_install_root() == legacy


def test_a_serverless_install_does_not_fall_back_to_the_legacy_server(tmp_path, monkeypatch):
    """A serverless install must not reuse the legacy sd-server, built for another accelerator."""
    bk, home, legacy = _shared_setup_3(monkeypatch, tmp_path)
    sdmod._INSTALLED_ACCELERATOR_MEMO.clear()
    sdmod._INSTALLED_SHIPS_SERVER_MEMO.clear()
    old_server = legacy / "sd-bin" / _SERVER
    old_server.write_bytes(b"cpu-build")

    monkeypatch.setattr(bk, "find_sd_server_binary", lambda: str(old_server))
    monkeypatch.setattr(bk, "_server_binary_runnable", lambda *_a, **_k: True)
    monkeypatch.setattr(bk, "_failed_accelerator_upgrades", set())
    monkeypatch.setattr(sdmod, "install", lambda **_kw: None)

    assert bk.ensure_sd_server_binary(accelerator = "cuda") is None


def test_a_serverless_install_is_not_downloaded_again_on_every_later_load(tmp_path, monkeypatch):
    """A serverless install is not downloaded again on every load."""
    bk, home, legacy = _shared_setup_3(monkeypatch, tmp_path)
    old_server = legacy / "sd-bin" / _SERVER
    old_server.write_bytes(b"cpu-build")
    current = home / "stable-diffusion.cpp"
    current.mkdir()
    (current / ".unsloth-studio-owned").touch()
    sdmod._write_install_record(current, accelerator = "cuda", repo = "r", tag = "t", ships_server = False)
    sdmod._INSTALLED_ACCELERATOR_MEMO.clear()
    sdmod._INSTALLED_SHIPS_SERVER_MEMO.clear()

    installs: list[dict] = []
    monkeypatch.setattr(bk, "find_sd_server_binary", lambda: str(old_server))
    monkeypatch.setattr(bk, "_server_binary_runnable", lambda *_a, **_k: True)
    monkeypatch.setattr(bk, "_failed_accelerator_upgrades", set())
    monkeypatch.setattr(sdmod, "install", lambda **kw: installs.append(kw))

    assert bk.ensure_sd_server_binary(accelerator = "cuda") is None
    assert installs == []
    assert bk.ensure_sd_server_binary(accelerator = "cuda", allow_install = False) is None
    # _accelerator_changed reports "unchanged" while the managed tree is busy.
    monkeypatch.setattr(bk, "_managed_tree_in_use", lambda: True)
    assert bk.ensure_sd_server_binary(accelerator = "cuda") is None
    assert installs == []


def test_an_old_pin_legacy_server_is_not_reinstalled_over_a_serverless_current_pin(
    tmp_path, monkeypatch
):
    """A legacy server for the RIGHT accelerator but an older pin is superseded once the current root holds the
    current pin's serverless bundle: not handed back after the upgrade, and not reinstalled on every later load."""
    bk, home, legacy = _shared_setup_3(monkeypatch, tmp_path)
    monkeypatch.delenv("UNSLOTH_SD_CPP_TAG", raising = False)
    monkeypatch.delenv("UNSLOTH_SD_CPP_AUTO_UPGRADE", raising = False)
    old_server = legacy / "sd-bin" / _SERVER
    old_server.write_bytes(b"old-pin-build")
    (legacy / sdmod.INSTALL_RECORD).write_text(
        json.dumps({"accelerator": "cuda", "repo": "r", "tag": "master-1-0000000-u0000000"}),
        encoding = "utf-8",
    )
    current = home / "stable-diffusion.cpp"
    current.mkdir()
    (current / ".unsloth-studio-owned").touch()
    sdmod._INSTALLED_ACCELERATOR_MEMO.clear()
    sdmod._INSTALLED_SHIPS_SERVER_MEMO.clear()

    installs: list[dict] = []

    def _install(**kw):
        installs.append(kw)
        sdmod._write_install_record(
            current, accelerator = "cuda", repo = "r", tag = "t", ships_server = False
        )

    monkeypatch.setattr(bk, "find_sd_server_binary", lambda: str(old_server))
    monkeypatch.setattr(bk, "_server_binary_runnable", lambda *_a, **_k: True)
    monkeypatch.setattr(bk, "_failed_accelerator_upgrades", set())
    monkeypatch.setattr(bk, "_failed_pin_upgrades", set())
    monkeypatch.setattr(sdmod, "install", _install)

    assert bk.ensure_sd_server_binary(accelerator = "cuda") is None
    assert bk.ensure_sd_server_binary(accelerator = "cuda") is None
    assert len(installs) == 1


def test_a_matching_legacy_server_is_still_preferred_over_the_one_shot_cli(tmp_path, monkeypatch):
    """A matching legacy server must win: the one-shot CLI reloads the model on every generation."""
    bk, home, legacy = _shared_setup_3(monkeypatch, tmp_path)
    server = legacy / "sd-bin" / _SERVER
    server.write_bytes(b"cpu-build")
    current = home / "stable-diffusion.cpp"
    current.mkdir()
    (current / ".unsloth-studio-owned").touch()
    sdmod._write_install_record(current, accelerator = "cpu", repo = "r", tag = "t", ships_server = False)
    sdmod._INSTALLED_ACCELERATOR_MEMO.clear()
    sdmod._INSTALLED_SHIPS_SERVER_MEMO.clear()

    monkeypatch.setattr(bk, "find_sd_server_binary", lambda: str(server))
    monkeypatch.setattr(bk, "_server_binary_runnable", lambda *_a, **_k: True)
    monkeypatch.setattr(bk, "_failed_accelerator_upgrades", set())

    assert bk.ensure_sd_server_binary(accelerator = "cpu") == str(server)


def test_a_deleted_server_still_reinstalls_rather_than_reading_as_serverless(tmp_path, monkeypatch):
    """Missing sd-server proves nothing; only a record saying none shipped blocks reinstall."""
    bk, home, legacy = _shared_setup_3(monkeypatch, tmp_path)
    old_server = legacy / "sd-bin" / _SERVER
    old_server.write_bytes(b"cpu-build")
    current = home / "stable-diffusion.cpp"
    current.mkdir()
    (current / ".unsloth-studio-owned").touch()
    sdmod._write_install_record(current, accelerator = "cuda", repo = "r", tag = "t")
    sdmod._INSTALLED_ACCELERATOR_MEMO.clear()
    sdmod._INSTALLED_SHIPS_SERVER_MEMO.clear()
    assert sdmod.installed_ships_server(current) is None

    installs: list[dict] = []
    monkeypatch.setattr(bk, "find_sd_server_binary", lambda: str(old_server))
    monkeypatch.setattr(bk, "_server_binary_runnable", lambda *_a, **_k: True)
    monkeypatch.setattr(bk, "_failed_accelerator_upgrades", set())
    monkeypatch.setattr(sdmod, "install", lambda **kw: installs.append(kw))

    bk.ensure_sd_server_binary(accelerator = "cuda")
    assert [kw["accelerator"] for kw in installs] == ["cuda"]


def test_install_records_that_the_bundle_shipped_no_server(tmp_path, monkeypatch):
    """The capability comes off the archive member list during install(), so a later load reads it
    as fact. Without it, "no sd-server in the tree" is indistinguishable from one that was deleted
    and the reinstall that would repair it gets suppressed."""
    zb = _zip_with_sd_cli()
    _stub_release(monkeypatch, zip_bytes = zb, digest = "sha256:" + hashlib.sha256(zb).hexdigest())
    install(install_dir = tmp_path)
    assert sdmod.installed_ships_server(tmp_path) is False


def test_install_records_that_the_bundle_shipped_a_server(tmp_path, monkeypatch):
    buf = io.BytesIO()
    with zipfile.ZipFile(buf, "w") as zf:
        zf.writestr(f"build/bin/{_CLI}", b"#!/bin/sh\necho sd-cli\n")
        zf.writestr(f"build/bin/{_SERVER}", b"#!/bin/sh\necho sd-server\n")
    zb = buf.getvalue()
    _stub_release(monkeypatch, zip_bytes = zb, digest = "sha256:" + hashlib.sha256(zb).hexdigest())
    install(install_dir = tmp_path)
    assert sdmod.installed_ships_server(tmp_path) is True


def test_an_unwritable_record_still_remembers_the_server_capability(tmp_path):
    """Server capability must be memoised with the accelerator, or serverless installs look capable."""
    root = tmp_path / "sd"
    root.mkdir()
    (root / sdmod.INSTALL_RECORD).mkdir()
    sdmod._INSTALLED_ACCELERATOR_MEMO.clear()
    sdmod._INSTALLED_SHIPS_SERVER_MEMO.clear()

    sdmod._write_install_record(root, accelerator = "cuda", repo = "r", tag = "t", ships_server = False)
    assert sdmod.read_install_record(root) == {}
    assert sdmod.installed_accelerator(root) == "cuda"
    assert sdmod.installed_ships_server(root) is False


def test_a_stale_record_does_not_outrank_the_server_capability_just_installed(tmp_path):
    """An older record claiming a server must not outrank a just-installed bundle without one."""
    root = tmp_path / "sd"
    root.mkdir()
    with open(root / sdmod.INSTALL_RECORD, "w", encoding = "utf-8") as f:
        json.dump({"accelerator": "cpu", "repo": "r", "tag": "old", "ships_server": True}, f)
    sdmod._INSTALLED_SHIPS_SERVER_MEMO.clear()
    sdmod._INSTALLED_SHIPS_SERVER_MEMO[str(root)] = False
    assert sdmod.installed_ships_server(root) is False


def test_the_install_record_remembers_whether_the_bundle_shipped_a_server(tmp_path):
    """Read off the archive member list at install time, so no later load has to guess."""
    root = tmp_path / "sd"
    root.mkdir()
    sdmod._write_install_record(root, accelerator = "cpu", repo = "r", tag = "t")
    assert sdmod.installed_ships_server(root) is None
    sdmod._write_install_record(root, accelerator = "cpu", repo = "r", tag = "t", ships_server = True)
    assert sdmod.installed_ships_server(root) is True
    sdmod._write_install_record(root, accelerator = "cpu", repo = "r", tag = "t", ships_server = False)
    assert sdmod.installed_ships_server(root) is False
    assert sdmod.installed_accelerator(root) == "cpu"


def _reinstall_twice(tmp_path):
    """The same archive extracted twice into one root, which is what install() does."""
    target = tmp_path / "install"
    target.mkdir()
    archive = tmp_path / "symlink.zip"
    with zipfile.ZipFile(archive, "w") as zf:
        zf.writestr("build/bin/libfoo.so.1", b"ELF")
        _link_member(zf, "build/bin/libfoo.so", "libfoo.so.1")
    for _ in range(2):
        with zipfile.ZipFile(archive) as zf:
            _safe_extractall(zf, target)
    return target


def test_safe_extractall_restores_symlink_members_on_reinstall(tmp_path):
    # install() merges rather than wipes, so the same archive lands on the links it already wrote.
    if not _can_create_symlinks(tmp_path):
        pytest.skip("symlink creation needs privilege on this host (Windows non-dev-mode)")
    target = _reinstall_twice(tmp_path)
    link = target / "build" / "bin" / "libfoo.so"
    assert link.is_symlink()
    assert link.readlink() == Path("libfoo.so.1")
    assert (target / "build" / "bin" / "libfoo.so.1").read_bytes() == b"ELF"


def test_safe_extractall_reinstall_is_idempotent_without_symlink_privilege(tmp_path):
    # The only half a Windows non-dev-mode host can run: reinstalling over a flattened copy.
    if _can_create_symlinks(tmp_path):
        pytest.skip("this host can create symlinks, so the flattening fallback is not in play")
    target = _reinstall_twice(tmp_path)
    flattened = target / "build" / "bin" / "libfoo.so"
    assert not flattened.is_symlink()
    assert flattened.read_bytes() == b"libfoo.so.1"
    assert (target / "build" / "bin" / "libfoo.so.1").read_bytes() == b"ELF"


def test_safe_extractall_replaces_stale_symlink_with_regular_member(tmp_path):
    # The mirror ships copies where upstream ships links; extractall would write through a stale link.
    target = tmp_path / "install"
    target.mkdir()
    old_archive = tmp_path / "old.zip"
    with zipfile.ZipFile(old_archive, "w") as zf:
        zf.writestr("build/bin/libfoo.so.1", b"OLD")
        _link_member(zf, "build/bin/libfoo.so", "libfoo.so.1")
    with zipfile.ZipFile(old_archive) as zf:
        _safe_extractall(zf, target)

    new_archive = tmp_path / "new.zip"
    with zipfile.ZipFile(new_archive, "w") as zf:
        zf.writestr("build/bin/libfoo.so.1", b"TARGET")
        zf.writestr("build/bin/libfoo.so", b"NEW")
    with zipfile.ZipFile(new_archive) as zf:
        _safe_extractall(zf, target)

    assert not (target / "build" / "bin" / "libfoo.so").is_symlink()
    assert (target / "build" / "bin" / "libfoo.so").read_bytes() == b"NEW"
    assert (target / "build" / "bin" / "libfoo.so.1").read_bytes() == b"TARGET"


def test_safe_extractall_rejects_symlink_escaping_target(tmp_path):
    target = tmp_path / "install"
    target.mkdir()
    archive = tmp_path / "symlink-escape.zip"
    with zipfile.ZipFile(archive, "w") as zf:
        _link_member(zf, "build/bin/escape.so", "../../../escape.txt")
    with zipfile.ZipFile(archive) as zf:
        with pytest.raises(RuntimeError, match = "unsafe symlink"):
            _safe_extractall(zf, target)
    assert not (tmp_path / "escape.txt").exists()


@pytest.mark.parametrize(
    ("status", "remaining", "body", "throttled"),
    [
        (403, "0", b"", True),
        (429, "4998", b"", True),
        (403, "4998", b'{"message": "secondary rate limit"}', True),
        (403, "4998", b'{"message": "Resource not accessible"}', False),
    ],
)
def test_a_rate_limit_stops_the_fallback_ladder(
    monkeypatch, capsys, status, remaining, body, throttled
):
    import email.message

    seen = []
    headers = email.message.Message()
    headers["X-RateLimit-Remaining"] = remaining

    def fake_fetch(
        tag,
        *,
        repo,
        token,
        timeout = 30.0,
        allow_latest = True,
    ):
        seen.append(repo)
        raise urllib.error.HTTPError(
            f"https://api/{repo}", status, "refused", headers, io.BytesIO(body)
        )

    monkeypatch.delenv("GH_TOKEN", raising = False)
    monkeypatch.delenv("GITHUB_TOKEN", raising = False)
    monkeypatch.setattr(sdmod, "_fetch_release", fake_fetch)
    if not throttled:
        assert sdmod._resolve_with_fallback("auto", None)[2] is None
        assert len(seen) > 1
        return
    with pytest.raises(sdmod.GitHubRateLimited, match = "rate limiting.*GH_TOKEN"):
        sdmod._resolve_with_fallback("auto", None)
    assert len(seen) == 1
    assert sdmod.main(["--print-asset"]) == 2
    assert "rate limiting" in capsys.readouterr().err