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.

72.1 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


import os
import sys
from pathlib import Path

import pytest

from utils import cache_inventory
from utils.cache_inventory import (
    CACHE_KEYS,
    CachePurgeRefused,
    assert_purgeable_root,
    cache_inventory as build_inventory,
    definition_for,
    describe_cache,
    empty_cache_root,
    purge_caches,
)


def _write(path: Path, text: str = "x") -> Path:
    path.parent.mkdir(parents = True, exist_ok = True)
    path.write_text(text, encoding = "utf-8")
    return path


@pytest.fixture
def isolated_caches(tmp_path, monkeypatch):
    "Isolate every cache resolver from host data."
    from utils import cache_cleanup, hf_cache_settings

    hf_home = tmp_path / "hf"
    (hf_home / "hub").mkdir(parents = True)
    (hf_home / "xet").mkdir()
    paths = hf_cache_settings.HuggingFaceCachePaths(
        hf_home, hf_home / "hub", hf_home / "xet", "studio"
    )
    monkeypatch.setattr(hf_cache_settings, "get_hf_cache_paths", lambda: paths)
    monkeypatch.setattr(hf_cache_settings, "known_hf_cache_homes", lambda: [hf_home])
    monkeypatch.setattr(hf_cache_settings, "known_hf_hub_caches", lambda: [hf_home / "hub"])
    monkeypatch.setattr(cache_cleanup, "_cleanable_cache_dirs", lambda: [])
    monkeypatch.setenv("HOME", str(tmp_path))
    monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path / "xdg"))
    for key in ("HF_HOME", "HF_HUB_CACHE", "HUGGINGFACE_HUB_CACHE"):
        monkeypatch.delenv(key, raising = False)
    for key, name in (
        ("HF_DATASETS_CACHE", "hf/datasets"),
        ("HF_ASSETS_CACHE", "hf/assets"),
        ("HF_XET_CACHE", "hf/xet"),
        ("UV_CACHE_DIR", "uv"),
        ("PIP_CACHE_DIR", "pip"),
        ("TORCHINDUCTOR_CACHE_DIR", "inductor"),
        ("TORCH_EXTENSIONS_DIR", "torchext"),
        ("TRITON_CACHE_DIR", "triton"),
        ("CUDA_CACHE_PATH", "cuda"),
        ("NUMBA_CACHE_DIR", "numba"),
        ("VLLM_CACHE_ROOT", "vllm"),
        ("npm_config_cache", "npm"),
        ("BUN_INSTALL_CACHE_DIR", "bun"),
    ):
        monkeypatch.setenv(key, str(tmp_path / name))
    monkeypatch.delenv("MPLCONFIGDIR", raising = False)
    monkeypatch.setattr(cache_inventory, "_size_cache", {})
    monkeypatch.setattr(cache_inventory, "_size_epochs", {})
    return hf_home


def test_a_cache_is_sized_from_its_own_bytes(tmp_path, monkeypatch, isolated_caches):
    root = tmp_path / "uv"
    _write(root / "a.bin", "a" * 100)
    _write(root / "nested" / "b.bin", "b" * 50)
    entry = describe_cache(definition_for("uv"))
    assert entry["present"] is True
    assert entry["size_bytes"] == 150
    assert entry["entry_count"] == 2
    assert entry["purgeable"] is True


def test_sizing_does_not_follow_a_symlink_out_of_the_cache(tmp_path, isolated_caches):
    outside = tmp_path / "outside"
    _write(outside / "big.bin", "z" * 4096)
    root = tmp_path / "uv"
    root.mkdir()
    (root / "escape").symlink_to(outside, target_is_directory = True)
    _write(root / "real.bin", "r" * 10)
    entry = describe_cache(definition_for("uv"))
    assert entry["size_bytes"] == 10


def test_hardlinked_blobs_are_counted_once(tmp_path, isolated_caches):
    root = tmp_path / "uv"
    blob = _write(root / "blobs" / "sha", "q" * 500)
    (root / "snapshots").mkdir()
    os.link(blob, root / "snapshots" / "model.bin")
    entry = describe_cache(definition_for("uv"))
    assert entry["size_bytes"] == 500


def test_an_absent_cache_reports_no_paths(tmp_path, isolated_caches):
    entry = describe_cache(definition_for("bun"))
    assert entry["present"] is False
    assert entry["paths"] == []
    assert entry["size_bytes"] == 0


def test_the_inventory_totals_exclude_the_opt_in_caches(tmp_path, isolated_caches):
    _write(tmp_path / "uv" / "a.bin", "a" * 100)
    _write(isolated_caches / "hub" / "models--x" / "w.bin", "m" * 900)
    inventory = build_inventory(refresh = True)
    by_key = {entry["key"]: entry for entry in inventory["caches"]}
    assert by_key["hf_hub"]["opt_in"] is True
    assert by_key["hf_hub"]["size_bytes"] == 900
    assert inventory["total_bytes"] == 1000
    assert inventory["reclaimable_bytes"] == 100


def test_every_key_the_api_exposes_has_a_definition():
    assert len(CACHE_KEYS) == len(set(CACHE_KEYS))
    for key in CACHE_KEYS:
        assert definition_for(key).key == key


@pytest.mark.parametrize("raw", ["/", "/home", os.path.expanduser("~")])
def test_a_root_at_or_near_the_filesystem_root_is_refused(raw):
    with pytest.raises(CachePurgeRefused):
        assert_purgeable_root(Path(raw))


def test_a_shallow_root_is_refused_even_when_nothing_protects_it(tmp_path):
    shallow = Path(*tmp_path.parts[:2])
    if not shallow.is_dir() or shallow.is_symlink() or len(shallow.parts) != 2:
        pytest.skip(f"no shallow non-symlink directory to test with ({shallow})")
    with pytest.raises(CachePurgeRefused) as excinfo:
        assert_purgeable_root(shallow, protected = set(), trees = set())
    assert "too close to the filesystem root" in str(excinfo.value)


def test_a_relative_root_is_refused():
    with pytest.raises(CachePurgeRefused):
        assert_purgeable_root(Path("relative/cache"))


def test_a_root_holding_studio_data_is_refused(tmp_path, monkeypatch):
    from utils.paths.storage_roots import studio_root

    home = studio_root()
    home.mkdir(parents = True, exist_ok = True)
    _write(home / "studio.db", "sqlite")
    with pytest.raises(CachePurgeRefused) as excinfo:
        assert_purgeable_root(home)
    assert "protected" in str(excinfo.value)


def test_a_root_inside_the_projects_folder_is_refused(tmp_path, monkeypatch):
    projects = tmp_path / "Projects"
    (projects / "my-run" / "cache").mkdir(parents = True)
    monkeypatch.setenv("UNSLOTH_STUDIO_PROJECTS_HOME", str(projects))
    with pytest.raises(CachePurgeRefused) as excinfo:
        assert_purgeable_root(projects / "my-run" / "cache")
    assert "protected folder" in str(excinfo.value)


def test_a_symlinked_cache_root_is_refused(tmp_path):
    target = tmp_path / "somewhere" / "deep"
    target.mkdir(parents = True)
    link = tmp_path / "link"
    link.symlink_to(target, target_is_directory = True)
    with pytest.raises(CachePurgeRefused) as excinfo:
        assert_purgeable_root(link)
    assert "symlink" in str(excinfo.value)


def test_the_purge_api_takes_keys_and_never_a_path():
    from routes.settings import CachePurgePayload

    assert set(CachePurgePayload.model_fields) == {"keys"}
    with pytest.raises(ValueError) as excinfo:
        purge_caches(["/"])
    assert "Unknown cache key" in str(excinfo.value)
    with pytest.raises(ValueError):
        purge_caches([os.path.expanduser("~")])
    with pytest.raises(ValueError):
        purge_caches(["../../etc"])


def test_an_unknown_key_deletes_nothing_from_the_valid_ones(tmp_path, isolated_caches):
    kept = _write(tmp_path / "uv" / "a.bin", "a" * 100)
    with pytest.raises(ValueError):
        purge_caches(["uv", "not_a_cache"])
    assert kept.exists()


def test_a_purge_empties_the_root_without_removing_it(tmp_path, isolated_caches):
    root = tmp_path / "uv"
    _write(root / "a.bin", "a" * 100)
    _write(root / "sub" / "b.bin", "b" * 20)
    result = purge_caches(["uv"])
    assert root.is_dir()
    assert list(root.iterdir()) == []
    assert result["freed_bytes"] == 120
    assert result["results"][0]["errors"] == []


def test_a_symlink_inside_the_cache_is_unlinked_and_never_followed(tmp_path, isolated_caches):
    outside = tmp_path / "precious"
    kept_file = _write(outside / "model.safetensors", "weights")
    root = tmp_path / "uv"
    root.mkdir()
    (root / "escape").symlink_to(outside, target_is_directory = True)
    (root / "escape-file").symlink_to(kept_file)
    purge_caches(["uv"])
    assert kept_file.exists()
    assert outside.is_dir()
    assert not (root / "escape").exists()
    assert not (root / "escape").is_symlink()
    assert not (root / "escape-file").is_symlink()


def test_a_purge_leaves_the_database_models_projects_and_token_alone(
    tmp_path, monkeypatch, isolated_caches
):
    from utils.paths.storage_roots import studio_root

    home = studio_root()
    home.mkdir(parents = True, exist_ok = True)
    database = _write(home / "studio.db", "sqlite")
    chat_history = _write(home / "chat" / "thread.json", "hello")
    token = _write(isolated_caches / "token", "hf_secret")
    model = _write(isolated_caches / "hub" / "models--unsloth--x" / "blobs" / "abc", "weights" * 10)
    projects = tmp_path / "Projects"
    monkeypatch.setenv("UNSLOTH_STUDIO_PROJECTS_HOME", str(projects))
    project_file = _write(projects / "run" / "adapter.safetensors", "lora")
    dataset = _write(tmp_path / "hf" / "datasets" / "ds" / "data.arrow", "rows")
    cache_file = _write(tmp_path / "uv" / "wheel.whl", "cached")

    bulk = [key for key in CACHE_KEYS if not definition_for(key).opt_in]
    purge_caches(bulk)

    assert not cache_file.exists()
    for survivor in (database, chat_history, token, model, project_file, dataset):
        assert survivor.exists(), f"{survivor} was deleted by a cache purge"


def test_clearing_the_hub_cache_is_asked_for_by_itself(tmp_path, isolated_caches):
    token = _write(isolated_caches / "token", "hf_secret")
    blob = _write(isolated_caches / "hub" / "models--x" / "blobs" / "abc", "weights")
    purge_caches(["hf_hub"])
    assert not blob.exists()
    assert (isolated_caches / "hub").is_dir()
    assert token.exists()


def test_a_refused_root_reports_itself_and_deletes_nothing(tmp_path, monkeypatch, isolated_caches):
    outputs = tmp_path / "outputs"
    monkeypatch.setattr(
        cache_inventory,
        "protected_trees",
        lambda: {Path(os.path.realpath(outputs))},
    )
    kept = _write(outputs / "triton" / "kernel.cubin", "compiled")
    monkeypatch.setenv("TRITON_CACHE_DIR", str(outputs / "triton"))
    entry = describe_cache(definition_for("triton"))
    assert entry["purgeable"] is False
    assert "protected folder" in entry["blocked_reason"]
    result = purge_caches(["triton"])
    assert kept.exists()
    assert result["freed_bytes"] == 0
    assert result["results"][0]["errors"]


@pytest.fixture
def only_the_configured_compiled_cache(monkeypatch, tmp_path):
    from utils import cache_cleanup
    monkeypatch.setattr(cache_cleanup, "_CACHE_DIRS", [])
    monkeypatch.chdir(tmp_path)


def test_the_compiled_cache_is_cleared_through_the_module_that_owns_it(
    tmp_path, monkeypatch, only_the_configured_compiled_cache
):
    from utils import cache_cleanup

    compiled = tmp_path / "compiled_cache"
    compiled.mkdir()
    (compiled / cache_cleanup.CACHE_MARKER).touch()
    generated = _write(compiled / "unsloth_compiled_module_llama.py", "compiled" * 10)
    monkeypatch.setenv("UNSLOTH_COMPILE_LOCATION", str(compiled))

    entry = describe_cache(definition_for("unsloth_compiled"))
    assert entry["present"] is True
    assert entry["size_bytes"] >= 80

    result = purge_caches(["unsloth_compiled"])
    assert result["results"][0]["errors"] == []
    assert not generated.exists()
    assert (compiled / cache_cleanup.CACHE_MARKER).is_file()


def test_a_shared_compiled_cache_only_loses_the_generated_modules(
    tmp_path, monkeypatch, only_the_configured_compiled_cache
):
    shared = tmp_path / "somebody-elses-folder"
    shared.mkdir()
    generated = _write(shared / "unsloth_compiled_module_llama.py", "compiled")
    mine = _write(shared / "my_notes.py", "print('hello')")
    monkeypatch.setenv("UNSLOTH_COMPILE_LOCATION", str(shared))

    purge_caches(["unsloth_compiled"])
    assert not generated.exists()
    assert mine.exists()


def test_a_pattern_limited_root_keeps_the_files_that_are_not_cache(tmp_path, monkeypatch):
    config_dir = tmp_path / "mplconfig"
    monkeypatch.setenv("MPLCONFIGDIR", str(config_dir))
    style = _write(config_dir / "matplotlibrc", "font.size: 12")
    fontlist = _write(config_dir / "fontlist-v390.json", "{}")
    empty_cache_root(config_dir, patterns = cache_inventory.MATPLOTLIB_PATTERNS)
    assert style.exists()
    assert not fontlist.exists()


def test_the_root_of_a_purged_cache_is_never_the_deletion_target(tmp_path, isolated_caches):
    root = tmp_path / "uv"
    _write(root / "a.bin", "a")
    before = root.stat().st_ino
    purge_caches(["uv"])
    assert root.is_dir()
    assert root.stat().st_ino == before


def test_a_purge_forgets_the_size_it_measured_before_it(tmp_path, isolated_caches):
    _write(tmp_path / "uv" / "a.bin", "a" * 100)
    assert build_inventory()["total_bytes"] == 100
    result = purge_caches(["uv"])
    assert result["inventory"]["total_bytes"] == 0
    assert build_inventory()["total_bytes"] == 0


def test_the_compiled_cache_is_never_swept_up_by_a_bulk_purge():
    definition = definition_for("unsloth_compiled")
    assert definition.opt_in is True

    inventory = build_inventory()
    bulk = {
        entry["key"]
        for entry in inventory["caches"]
        if entry["present"] and entry["purgeable"] and not entry["opt_in"]
    }
    assert "unsloth_compiled" not in bulk

    entry = next(e for e in inventory["caches"] if e["key"] == "unsloth_compiled")
    assert entry["opt_in"] is True


def test_a_junctioned_cache_root_is_refused_like_a_symlink(tmp_path, monkeypatch):
    target = tmp_path / "somewhere" / "deep"
    target.mkdir(parents = True)
    kept = _write(target / "not-a-cache.txt", "mine")
    junction = tmp_path / "cache"
    junction.mkdir()

    # isjunction is always False on POSIX, so the platform test is what matters.
    monkeypatch.setattr(os.path, "isjunction", lambda path: Path(path) == junction, raising = False)
    assert not junction.is_symlink()

    with pytest.raises(CachePurgeRefused) as excinfo:
        assert_purgeable_root(junction)
    assert "junction" in str(excinfo.value)
    assert kept.exists()


def test_a_bulk_clear_cannot_reach_an_opt_in_cache_nested_in_another_root(
    tmp_path, monkeypatch, isolated_caches
):
    uv = tmp_path / "uv"
    datasets = uv / "hf-datasets"
    _write(uv / "wheels" / "wheel.whl", "w" * 10)
    dataset_file = _write(datasets / "squad" / "data.arrow", "d" * 10)
    monkeypatch.setenv("HF_DATASETS_CACHE", str(datasets))

    described = describe_cache(definition_for("uv"))
    assert described["purgeable"] is False
    assert "opt-in cache" in (described["blocked_reason"] or "")

    result = purge_caches(["uv"])
    assert dataset_file.exists()
    assert result["freed_bytes"] == 0

    purge_caches(["hf_datasets"])
    assert not dataset_file.exists()


def test_an_explicit_hub_cache_outside_a_hub_folder_stays_clearable(
    tmp_path, monkeypatch, isolated_caches
):
    from utils import hf_cache_settings

    hub = tmp_path / "hf-cache"
    _write(hub / "models--org--model" / "blob", "m" * 10)
    paths = hf_cache_settings.HuggingFaceCachePaths(
        hub, hub, tmp_path / "xet", "environment", "HF_HUB_CACHE"
    )
    monkeypatch.setattr(hf_cache_settings, "get_hf_cache_paths", lambda: paths)
    monkeypatch.setattr(hf_cache_settings, "known_hf_hub_caches", lambda: [hub])

    described = describe_cache(definition_for("hf_hub"))
    assert described["purgeable"] is True, described["blocked_reason"]

    with pytest.raises(CachePurgeRefused):
        assert_purgeable_root(isolated_caches)


@pytest.mark.parametrize("shared_blob", [False, True])
def test_an_active_hub_nested_in_a_remembered_hub_stays_clearable(
    tmp_path, monkeypatch, isolated_caches, shared_blob
):
    from utils import hf_cache_settings

    old_hub = isolated_caches / "hub"
    active = old_hub / "new-downloads"
    old_blob = _write(old_hub / "models--test--old" / "blobs" / "weights", "o" * 256)
    active_blob = _write(active / "models--test--active" / "blobs" / "weights", "a" * 128)
    if shared_blob:
        os.link(active_blob, old_blob.parent / "shared")
    paths = hf_cache_settings.HuggingFaceCachePaths(
        active, active, isolated_caches / "xet", "environment", "HF_HUB_CACHE"
    )
    monkeypatch.setattr(hf_cache_settings, "get_hf_cache_paths", lambda: paths)
    monkeypatch.setattr(hf_cache_settings, "known_hf_hub_caches", lambda: [active, old_hub])

    described = describe_cache(definition_for("hf_hub"))
    assert described["purgeable"] is True, described["blocked_reason"]
    assert described["size_bytes"] == 384
    assert described["clear_size_bytes"] == (0 if shared_blob else 128)
    assert described["clear_entry_count"] == 1

    rows = {row["name"]: row for row in cache_inventory.cache_breakdown("hf_hub")["entries"]}
    assert set(rows) == {"models--test--old", "models--test--active"}
    assert rows["models--test--active"]["size_bytes"] == 128
    assert rows["models--test--active"]["cache_path"] == str(
        (active / "models--test--active").resolve()
    )

    purge_caches(["hf_hub"])
    assert not active_blob.exists()
    assert old_blob.exists()


@pytest.mark.parametrize("depth", [1, 3])
def test_a_nested_hub_breakdown_walks_each_active_directory_once(
    monkeypatch, isolated_caches, depth
):
    from utils import hf_cache_settings

    old_hub = isolated_caches / "hub"
    active = old_hub.joinpath(*(["nested"] * depth))
    blob = _write(active / "models--test--active" / "blobs" / "weights", "a" * 128)
    paths = hf_cache_settings.HuggingFaceCachePaths(
        active, active, isolated_caches / "xet", "environment", "HF_HUB_CACHE"
    )
    monkeypatch.setattr(hf_cache_settings, "get_hf_cache_paths", lambda: paths)
    monkeypatch.setattr(hf_cache_settings, "known_hf_hub_caches", lambda: [active, old_hub])
    scandir = os.scandir
    visits = []

    def tracked_scandir(path):
        visits.append(Path(path))
        return scandir(path)

    monkeypatch.setattr(cache_inventory.os, "scandir", tracked_scandir)
    rows = cache_inventory.cache_breakdown("hf_hub")["entries"]
    assert visits.count(blob.parent) == 1
    assert sum(row["size_bytes"] for row in rows) == 128
    assert any(row.get("repo_id") == "test/active" for row in rows)


def test_a_growing_nested_hub_does_not_offer_more_bytes_than_it_measured(
    monkeypatch, isolated_caches
):
    from utils import hf_cache_settings

    old_hub = isolated_caches / "hub"
    active = old_hub / "new-downloads"
    _write(old_hub / "models--test--old" / "blobs" / "weights", "o" * 256)
    active_blob = _write(active / "models--test--active" / "blobs" / "weights", "a" * 128)
    paths = hf_cache_settings.HuggingFaceCachePaths(
        active, active, isolated_caches / "xet", "environment", "HF_HUB_CACHE"
    )
    monkeypatch.setattr(hf_cache_settings, "get_hf_cache_paths", lambda: paths)
    monkeypatch.setattr(hf_cache_settings, "known_hf_hub_caches", lambda: [active, old_hub])
    measure = cache_inventory._measure_root
    scandir = os.scandir
    visits = []

    def tracked_scandir(path):
        visits.append(Path(path))
        return scandir(path)

    def grow_after_measure(root, **kwargs):
        result = measure(root, **kwargs)
        if root == old_hub:
            active_blob.write_text("a" * 1024, encoding = "utf-8")
        return result

    monkeypatch.setattr(cache_inventory, "_measure_root", grow_after_measure)
    monkeypatch.setattr(cache_inventory.os, "scandir", tracked_scandir)
    described = describe_cache(definition_for("hf_hub"))
    assert described["size_bytes"] == 384
    assert described["clear_size_bytes"] == 128
    assert visits.count(active_blob.parent) == 1


def test_the_inductor_cache_follows_the_account_name_torch_uses(
    tmp_path, monkeypatch, isolated_caches
):
    import tempfile

    monkeypatch.delenv("TORCHINDUCTOR_CACHE_DIR", raising = False)
    monkeypatch.delenv("USER", raising = False)
    monkeypatch.delenv("USERNAME", raising = False)
    monkeypatch.setenv("LOGNAME", "root")
    monkeypatch.setattr(tempfile, "gettempdir", lambda: str(tmp_path))
    root = tmp_path / "torchinductor_root"
    _write(root / "fxgraph" / "entry.bin", "c" * 20)

    entry = describe_cache(definition_for("torch_inductor"))
    assert entry["paths"] == [str(root)]
    assert entry["size_bytes"] == 20


@pytest.mark.parametrize("platform", ["linux", "darwin", "win32"])
def test_the_vllm_cache_is_vllms_own_default_on_every_platform(
    tmp_path, monkeypatch, isolated_caches, platform
):
    import sys as _sys

    monkeypatch.delenv("VLLM_CACHE_ROOT", raising = False)
    monkeypatch.delenv("XDG_CACHE_HOME", raising = False)
    monkeypatch.setattr(_sys, "platform", platform)
    assert cache_inventory._vllm_dirs() == [tmp_path / ".cache" / "vllm"]


def test_the_vllm_cache_honours_xdg_because_vllm_does(tmp_path, monkeypatch, isolated_caches):
    monkeypatch.delenv("VLLM_CACHE_ROOT", raising = False)
    monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path / "xdg"))
    assert cache_inventory._vllm_dirs() == [tmp_path / "xdg" / "vllm"]


def test_a_refused_root_is_never_walked(tmp_path, monkeypatch, isolated_caches):
    outputs = tmp_path / "outputs"
    monkeypatch.setattr(
        cache_inventory, "protected_trees", lambda: {Path(os.path.realpath(outputs))}
    )
    _write(outputs / "triton" / "kernel.cubin", "compiled" * 100)
    monkeypatch.setenv("TRITON_CACHE_DIR", str(outputs / "triton"))

    walked = []
    measure = cache_inventory._measure_root
    monkeypatch.setattr(
        cache_inventory,
        "_measure_root",
        lambda root, **kwargs: (walked.append(root), measure(root, **kwargs))[1],
    )

    entry = describe_cache(definition_for("triton"))
    assert entry["purgeable"] is False
    assert walked == []
    assert entry["size_bytes"] == 0


def test_a_cache_anywhere_under_the_documents_folder_is_refused(
    tmp_path, monkeypatch, isolated_caches
):
    from utils.paths import storage_roots

    documents = tmp_path / "Documents"
    kept = _write(documents / "archive" / "taxes.pdf", "mine")
    monkeypatch.setattr(storage_roots, "documents_root", lambda: documents)
    monkeypatch.setenv("UV_CACHE_DIR", str(documents / "archive"))

    entry = describe_cache(definition_for("uv"))
    assert entry["purgeable"] is False
    assert "protected folder" in (entry["blocked_reason"] or "")
    purge_caches(["uv"])
    assert kept.exists()


def test_a_junction_inside_a_cache_is_not_walked(tmp_path, monkeypatch, isolated_caches):
    root = tmp_path / "uv"
    _write(root / "real.bin", "r" * 10)
    _write(root / "wheels" / "junction" / "elsewhere.bin", "z" * 4096)
    monkeypatch.setattr(cache_inventory, "_is_junction", lambda path: Path(path).name == "junction")

    entry = describe_cache(definition_for("uv"))
    assert entry["size_bytes"] == 10


def test_a_compiled_cache_that_survives_the_clear_says_so(
    tmp_path, monkeypatch, only_the_configured_compiled_cache
):
    from utils import cache_cleanup

    compiled = tmp_path / "compiled_cache"
    compiled.mkdir()
    (compiled / cache_cleanup.CACHE_MARKER).touch()
    survivor = _write(compiled / "unsloth_compiled_module_llama.py", "compiled" * 10)
    monkeypatch.setenv("UNSLOTH_COMPILE_LOCATION", str(compiled))
    monkeypatch.setattr(cache_cleanup, "clear_unsloth_compiled_cache", lambda *a, **k: None)

    result = purge_caches(["unsloth_compiled"])["results"][0]
    assert survivor.exists()
    assert result["removed_entries"] == 0
    assert result["errors"]


def test_purging_a_hub_cache_invalidates_the_hugging_face_scans(tmp_path, isolated_caches):
    from hub.utils import inventory_scan

    _write(isolated_caches / "hub" / "models--org--model" / "blob", "m" * 10)
    before = inventory_scan.hf_cache_scans_epoch()
    purge_caches(["hf_hub"])
    assert inventory_scan.hf_cache_scans_epoch() > before

    steady = inventory_scan.hf_cache_scans_epoch()
    _write(tmp_path / "uv" / "wheel.whl", "w" * 10)
    purge_caches(["uv"])
    assert inventory_scan.hf_cache_scans_epoch() == steady


def test_a_pattern_limited_cache_nested_in_another_root_is_sheltered(
    tmp_path, monkeypatch, isolated_caches
):
    uv = tmp_path / "uv"
    config = uv / "matplotlib"
    _write(uv / "wheels" / "wheel.whl", "w" * 10)
    kept = _write(config / "matplotlibrc", "backend: Agg")
    fonts = _write(config / "fontlist-v390.json", "[]" * 10)
    monkeypatch.setenv("MPLCONFIGDIR", str(config))

    described = describe_cache(definition_for("uv"))
    assert described["purgeable"] is False
    assert "matplotlib cache" in (described["blocked_reason"] or "")
    result = purge_caches(["uv"])
    assert kept.exists()
    assert result["freed_bytes"] == 0

    purge_caches(["matplotlib"])
    assert kept.exists()
    assert not fonts.exists()


def test_a_cache_home_left_behind_is_protected_but_never_purged(
    tmp_path, monkeypatch, isolated_caches
):
    from utils import hf_cache_settings

    previous = tmp_path / "old-home"
    theirs = _write(previous / "assets" / "someone-elses.bin", "d" * 10)
    _write(previous / "hub" / "models--org--model" / "blob", "m" * 10)
    mine = _write(isolated_caches / "assets" / "asset.bin", "a" * 10)
    monkeypatch.setattr(
        hf_cache_settings, "known_hf_cache_homes", lambda: [isolated_caches, previous]
    )
    monkeypatch.setattr(
        hf_cache_settings,
        "known_hf_hub_caches",
        lambda: [isolated_caches / "hub", previous / "hub"],
    )
    monkeypatch.delenv("HF_ASSETS_CACHE", raising = False)
    monkeypatch.setenv("HF_HOME", str(isolated_caches))

    assets = describe_cache(definition_for("hf_assets"))
    assert assets["paths"] == [str(isolated_caches / "assets")]
    hub = describe_cache(definition_for("hf_hub"))
    assert hub["paths"] == [str(isolated_caches / "hub")]

    purge_caches(["hf_assets", "hf_hub"])
    assert not mine.exists()
    assert theirs.exists()

    with pytest.raises(CachePurgeRefused):
        assert_purgeable_root(previous)


def test_the_pip_cache_is_the_one_pip_reports(tmp_path, monkeypatch, isolated_caches):
    import subprocess as real_subprocess

    from utils import cache_inventory as module

    configured = tmp_path / "corp-pip-cache"
    _write(configured / "wheels" / "cached.whl", "p" * 40)
    monkeypatch.delenv("PIP_CACHE_DIR", raising = False)
    monkeypatch.setattr(module, "_probed_cache_dirs", {})
    monkeypatch.setattr(
        module.subprocess,
        "run",
        lambda *a, **k: real_subprocess.CompletedProcess(a[0], 0, f"{configured}\n", ""),
    )

    entry = describe_cache(definition_for("pip"))
    assert entry["paths"] == [str(configured)]
    assert entry["size_bytes"] == 40


def test_the_pip_probe_runs_once_and_survives_a_failure(tmp_path, monkeypatch, isolated_caches):
    from utils import cache_inventory as module

    calls = []
    monkeypatch.delenv("PIP_CACHE_DIR", raising = False)
    monkeypatch.setattr(module, "_probed_cache_dirs", {})

    def explode(*args, **kwargs):
        calls.append(args)
        raise OSError("no pip here")

    monkeypatch.setattr(module.subprocess, "run", explode)
    probe = ["python", "-m", "pip", "cache", "dir"]
    assert module._probe_tool_cache_dir("pip", probe) is None
    assert module._probe_tool_cache_dir("pip", probe) is None
    assert len(calls) == 1
    assert module._pip_dirs() == [tmp_path / "xdg" / "pip"]


def test_the_child_caches_follow_the_real_home_not_the_displayed_one(
    tmp_path, monkeypatch, isolated_caches
):
    from utils import hf_cache_settings

    project = tmp_path / "project"
    hub = project / "hub"
    hub.mkdir(parents = True)
    theirs = _write(project / "assets" / "not-a-cache.bin", "d" * 10)
    real_home = tmp_path / "xdg" / "huggingface"
    mine = _write(real_home / "assets" / "asset.bin", "a" * 10)

    paths = hf_cache_settings.HuggingFaceCachePaths(
        project, hub, real_home / "xet", "environment", "HF_HUB_CACHE"
    )
    monkeypatch.setattr(hf_cache_settings, "get_hf_cache_paths", lambda: paths)
    monkeypatch.setattr(hf_cache_settings, "_EXPLICIT_CACHE_ENV", {"HF_HUB_CACHE": str(hub)})
    monkeypatch.delenv("HF_ASSETS_CACHE", raising = False)
    monkeypatch.setenv("HF_HOME", str(real_home))

    entry = describe_cache(definition_for("hf_assets"))
    assert entry["paths"] == [str(real_home / "assets")]
    purge_caches(["hf_assets"])
    assert theirs.exists()
    assert not mine.exists()


def test_a_measurement_that_began_before_a_purge_is_not_remembered(
    tmp_path, monkeypatch, isolated_caches
):
    root = tmp_path / "uv"
    _write(root / "wheel.whl", "w" * 100)
    definition = definition_for("uv")
    real_describe = cache_inventory.describe_cache
    before_the_purge = real_describe(definition)
    assert before_the_purge["size_bytes"] == 100

    def measure_then_purge(_definition):
        for child in root.iterdir():
            child.unlink()
        cache_inventory.invalidate_cache_size("uv")
        return before_the_purge

    monkeypatch.setattr(cache_inventory, "describe_cache", measure_then_purge)
    assert cache_inventory._described(definition, refresh = True)["size_bytes"] == 100
    monkeypatch.setattr(cache_inventory, "describe_cache", real_describe)
    assert cache_inventory._described(definition, refresh = False)["size_bytes"] == 0


def test_the_pip_probe_asks_the_child_for_utf8(tmp_path, monkeypatch, isolated_caches):
    import subprocess as real_subprocess

    from utils import cache_inventory as module

    seen = {}
    configured = tmp_path / "caché-pip"
    _write(configured / "wheels" / "cached.whl", "p" * 40)
    monkeypatch.delenv("PIP_CACHE_DIR", raising = False)
    monkeypatch.setattr(module, "_probed_cache_dirs", {})

    def record(*args, **kwargs):
        seen.update(kwargs)
        return real_subprocess.CompletedProcess(args[0], 0, f"{configured}\n", "")

    monkeypatch.setattr(module.subprocess, "run", record)
    entry = describe_cache(definition_for("pip"))

    assert entry["paths"] == [str(configured)]
    assert seen["encoding"] == "utf-8"
    assert seen["env"]["PYTHONIOENCODING"] == "utf-8"


def test_a_scoped_dataset_fallback_override_is_not_a_purge_root(
    tmp_path, monkeypatch, isolated_caches
):
    from utils.paths import storage_roots

    studio_cache = tmp_path / "studio-cache"
    fallback = studio_cache / "hf-datasets"
    in_flight = _write(fallback / "squad" / "data.arrow", "d" * 10)
    stable = _write(isolated_caches / "datasets" / "cached.arrow", "s" * 10)
    monkeypatch.setattr(storage_roots, "cache_root", lambda: studio_cache)
    monkeypatch.setenv("HF_HOME", str(isolated_caches))
    monkeypatch.setenv("HF_DATASETS_CACHE", str(fallback))

    entry = describe_cache(definition_for("hf_datasets"))
    assert entry["paths"] == [str(isolated_caches / "datasets")]
    purge_caches(["hf_datasets"])
    assert in_flight.exists()
    assert not stable.exists()


@pytest.mark.parametrize(
    "platform,name,expected,patterned",
    [
        ("linux", "posix", ".cache/matplotlib", False),
        ("darwin", "posix", ".matplotlib", True),
        ("win32", "nt", ".matplotlib", True),
    ],
)
def test_the_matplotlib_cache_is_where_matplotlib_puts_it(
    tmp_path, monkeypatch, isolated_caches, platform, name, expected, patterned
):
    import sys as _sys

    from utils import cache_inventory as module

    monkeypatch.delenv("MPLCONFIGDIR", raising = False)
    monkeypatch.delenv("XDG_CACHE_HOME", raising = False)
    monkeypatch.setattr(_sys, "platform", platform)
    monkeypatch.setattr(module, "_is_windows", lambda: name == "nt")
    (tmp_path / ".matplotlib").mkdir(exist_ok = True)

    assert module._matplotlib_dirs() == [tmp_path / expected]
    assert (module._matplotlib_patterns() is not None) is patterned


def test_the_cuda_cache_is_roaming_appdata_on_windows(tmp_path, monkeypatch, isolated_caches):
    import sys as _sys

    from utils import cache_inventory as module

    monkeypatch.delenv("CUDA_CACHE_PATH", raising = False)
    monkeypatch.setattr(module, "_is_windows", lambda: True)
    monkeypatch.setenv("APPDATA", str(tmp_path / "AppData" / "Roaming"))
    monkeypatch.setenv("LOCALAPPDATA", str(tmp_path / "AppData" / "Local"))
    assert module._cuda_dirs() == [tmp_path / "AppData" / "Roaming" / "NVIDIA" / "ComputeCache"]

    monkeypatch.setattr(module, "_is_windows", lambda: False)
    monkeypatch.setattr(_sys, "platform", "darwin")
    assert module._cuda_dirs() == [
        tmp_path / "Library" / "Application Support" / "NVIDIA" / "ComputeCache"
    ]


def test_numbas_user_wide_fallback_cache_is_reported(tmp_path, monkeypatch, isolated_caches):
    monkeypatch.delenv("NUMBA_CACHE_DIR", raising = False)
    root = tmp_path / "xdg" / "numba"
    _write(root / "somemodule.nbi", "n" * 30)

    entry = describe_cache(definition_for("numba"))
    assert entry["paths"] == [str(root)]
    assert entry["size_bytes"] == 30


def test_the_studio_executables_directory_is_refused(tmp_path, monkeypatch, isolated_caches):
    from utils.paths import storage_roots

    studio = tmp_path / "studio"
    binaries = studio / "bin"
    shim = _write(binaries / "unsloth", "#!/bin/sh")
    monkeypatch.setattr(storage_roots, "studio_bin_root", lambda: binaries)
    monkeypatch.setenv("UV_CACHE_DIR", str(binaries))

    entry = describe_cache(definition_for("uv"))
    assert entry["purgeable"] is False
    purge_caches(["uv"])
    assert shim.exists()

    monkeypatch.setenv("UV_CACHE_DIR", str(binaries / "vendor"))
    (binaries / "vendor").mkdir()
    with pytest.raises(CachePurgeRefused):
        assert_purgeable_root(binaries / "vendor")


def test_the_npm_cache_follows_npmrc(tmp_path, monkeypatch, isolated_caches):
    import shutil as real_shutil
    import subprocess as real_subprocess

    from utils import cache_inventory as module

    configured = tmp_path / "corp-npm"
    _write(configured / "_cacache" / "index-v5" / "entry", "n" * 25)
    for key in ("npm_config_cache", "NPM_CONFIG_CACHE"):
        monkeypatch.delenv(key, raising = False)
    monkeypatch.setattr(module, "_probed_cache_dirs", {})
    monkeypatch.setattr(real_shutil, "which", lambda name, **kw: "/usr/bin/npm")
    monkeypatch.setattr(
        module.subprocess,
        "run",
        lambda *a, **k: real_subprocess.CompletedProcess(a[0], 0, f"{configured}\n", ""),
    )

    entry = describe_cache(definition_for("npm"))
    assert entry["paths"] == [str(configured / "_cacache")]
    assert entry["size_bytes"] == 25


def test_a_probe_that_answers_with_a_relative_path_is_ignored(monkeypatch, isolated_caches):
    import subprocess as real_subprocess

    from utils import cache_inventory as module

    monkeypatch.setattr(module, "_probed_cache_dirs", {})
    monkeypatch.setattr(
        module.subprocess,
        "run",
        lambda *a, **k: real_subprocess.CompletedProcess(a[0], 0, "undefined\n", ""),
    )
    assert module._probe_tool_cache_dir("npm", ["npm", "config", "get", "cache"]) is None


def test_the_recorded_install_uv_cache_is_reported(tmp_path, monkeypatch, isolated_caches):
    from utils.paths import storage_roots

    studio_cache = tmp_path / "studio-cache"
    seeded = studio_cache / "uv"
    warm = tmp_path / "warm-uv"
    _write(seeded / "seeded.whl", "s" * 10)
    _write(warm / "archive-v0" / "big.whl", "w" * 900)
    monkeypatch.setattr(storage_roots, "cache_root", lambda: studio_cache)
    (studio_cache / "uv-cache-dir").write_text(f"{warm}\n", encoding = "utf-8")
    monkeypatch.setenv("UV_CACHE_DIR", str(seeded))

    entry = describe_cache(definition_for("uv"))
    assert entry["paths"] == [str(seeded), str(warm)]
    assert entry["size_bytes"] == 910
    purge_caches(["uv"])
    assert not (warm / "archive-v0").exists()
    assert seeded.is_dir()


def test_a_blank_or_missing_uv_marker_adds_nothing(tmp_path, monkeypatch, isolated_caches):
    from utils import cache_inventory as module
    from utils.paths import storage_roots

    studio_cache = tmp_path / "studio-cache"
    studio_cache.mkdir()
    monkeypatch.setattr(storage_roots, "cache_root", lambda: studio_cache)
    assert module._recorded_uv_cache() is None
    (studio_cache / "uv-cache-dir").write_text("   \n", encoding = "utf-8")
    assert module._recorded_uv_cache() is None


def test_the_studio_temporary_workspace_is_refused(tmp_path, monkeypatch, isolated_caches):
    from utils.paths import storage_roots

    workspace = tmp_path / "unsloth-studio"
    in_use = _write(workspace / "decode" / "clip.wav", "a" * 10)
    monkeypatch.setattr(storage_roots, "tmp_root", lambda: workspace)
    monkeypatch.setenv("UV_CACHE_DIR", str(workspace / "decode"))

    entry = describe_cache(definition_for("uv"))
    assert entry["purgeable"] is False
    purge_caches(["uv"])
    assert in_use.exists()
    with pytest.raises(CachePurgeRefused):
        assert_purgeable_root(workspace)


def test_two_cold_probes_do_not_race_into_the_fallback(tmp_path, monkeypatch, isolated_caches):
    import subprocess as real_subprocess
    import threading

    from utils import cache_inventory as module

    configured = tmp_path / "corp-pip"
    configured.mkdir()
    monkeypatch.delenv("PIP_CACHE_DIR", raising = False)
    monkeypatch.setattr(module, "_probed_cache_dirs", {})
    started = threading.Event()
    release = threading.Event()

    def slow(*args, **kwargs):
        started.set()
        release.wait(5)
        return real_subprocess.CompletedProcess(args[0], 0, f"{configured}\n", "")

    monkeypatch.setattr(module.subprocess, "run", slow)
    answers: list = []
    first = threading.Thread(target = lambda: answers.append(module._pip_dirs()))
    first.start()
    assert started.wait(5)
    second = threading.Thread(target = lambda: answers.append(module._pip_dirs()))
    second.start()
    release.set()
    first.join(10)
    second.join(10)

    assert answers == [[configured], [configured]]


def test_the_inductor_row_ignores_the_diffusion_override(tmp_path, monkeypatch, isolated_caches):
    import getpass
    import tempfile

    from utils import cache_inventory as module

    diffusion = tmp_path / "diffusion_compile_cache"
    per_model = diffusion / "abc123" / "inductor"
    transient = _write(per_model / "graph.bin", "d" * 50)
    monkeypatch.setattr(tempfile, "gettempdir", lambda: str(tmp_path))
    stable = tmp_path / f"torchinductor_{getpass.getuser()}"
    _write(stable / "fx.bin", "s" * 10)
    monkeypatch.setattr(
        module, "_diffusion_compile_root", lambda: Path(os.path.realpath(diffusion))
    )
    monkeypatch.setenv("TORCHINDUCTOR_CACHE_DIR", str(per_model))

    entry = describe_cache(definition_for("torch_inductor"))
    assert entry["paths"] == [str(stable)]
    purge_caches(["torch_inductor"])
    assert transient.exists()

    elsewhere = tmp_path / "my-inductor"
    _write(elsewhere / "fx.bin", "e" * 10)
    monkeypatch.setenv("TORCHINDUCTOR_CACHE_DIR", str(elsewhere))
    assert describe_cache(definition_for("torch_inductor"))["paths"] == [str(elsewhere)]


def test_a_configured_token_path_is_protected(tmp_path, monkeypatch, isolated_caches):
    assets = tmp_path / "mnt-hf"
    token = _write(assets / "token", "hf_secret")
    _write(assets / "blob", "a" * 10)
    monkeypatch.setenv("HF_ASSETS_CACHE", str(assets))
    monkeypatch.setenv("HF_TOKEN_PATH", str(token))

    entry = describe_cache(definition_for("hf_assets"))
    assert entry["purgeable"] is False
    purge_caches(["hf_assets"])
    assert token.read_text(encoding = "utf-8") == "hf_secret"


def test_a_purge_waits_for_the_downloads_writing_into_the_cache(
    tmp_path, monkeypatch, isolated_caches
):
    from utils import cache_inventory as module

    blob = _write(isolated_caches / "hub" / "models--org--model" / "blob", "m" * 10)
    monkeypatch.setattr(
        module,
        "_reserve_downloads",
        lambda key: ([], "Cancel it.") if key == "hf_hub" else ([], None),
    )
    result = purge_caches(["hf_hub"])["results"][0]
    assert blob.exists()
    assert result["freed_bytes"] == 0
    assert result["errors"] == ["Cancel it."]


def test_the_hub_cache_is_reserved_in_both_registries(monkeypatch):
    from hub.utils import download_registry
    from utils import cache_inventory as module

    class _Registry:
        def __init__(self, free = True):
            self.free = free
            self.held = 0

        def begin_cache_purge(self):
            if not self.free:
                return False
            self.held += 1
            return True

        def end_cache_purge(self):
            self.held -= 1

    models, datasets = _Registry(), _Registry()
    monkeypatch.setattr(download_registry, "get_models_registry", lambda: models)
    monkeypatch.setattr(download_registry, "get_datasets_registry", lambda: datasets)
    from hub.services.datasets import downloads as dataset_downloads

    monkeypatch.setattr(dataset_downloads, "begin_cache_purge", datasets.begin_cache_purge)
    monkeypatch.setattr(dataset_downloads, "end_cache_purge", datasets.end_cache_purge)

    reserved, busy = module._reserve_downloads("hf_hub")
    assert busy is None
    assert (models.held, datasets.held) == (1, 1)
    module._release_downloads(reserved)
    assert (models.held, datasets.held) == (0, 0)

    datasets.free = False
    reserved, busy = module._reserve_downloads("hf_hub")
    assert busy is not None
    assert (models.held, datasets.held) == (0, 0)

    assert module._reserve_downloads("uv") == ([], None)


def test_one_blocked_root_does_not_put_the_others_out_of_reach(
    tmp_path, monkeypatch, isolated_caches
):
    from utils.paths import storage_roots

    studio_cache = tmp_path / "studio-cache"
    good = studio_cache / "uv"
    documents = tmp_path / "Documents"
    blocked = documents / "uv-cache"
    wheel = _write(good / "wheel.whl", "w" * 40)
    theirs = _write(blocked / "taxes.pdf", "mine")
    monkeypatch.setattr(storage_roots, "cache_root", lambda: studio_cache)
    monkeypatch.setattr(storage_roots, "documents_root", lambda: documents)
    (studio_cache / "uv-cache-dir").write_text(f"{blocked}\n", encoding = "utf-8")
    monkeypatch.setenv("UV_CACHE_DIR", str(good))

    entry = describe_cache(definition_for("uv"))
    assert entry["purgeable"] is True
    assert "protected folder" in (entry["blocked_reason"] or "")
    assert entry["size_bytes"] == 40
    purge_caches(["uv"])
    assert not wheel.exists()
    assert theirs.exists()


def test_two_cold_reads_of_one_cache_walk_it_once(tmp_path, monkeypatch, isolated_caches):
    import threading

    from utils import cache_inventory as module

    _write(tmp_path / "uv" / "wheel.whl", "w" * 10)
    definition = definition_for("uv")
    walks: list = []
    started = threading.Event()
    release = threading.Event()
    real_describe = cache_inventory.describe_cache

    def slow(target):
        walks.append(target.key)
        started.set()
        release.wait(5)
        return real_describe(target)

    monkeypatch.setattr(cache_inventory, "describe_cache", slow)
    answers: list = []
    first = threading.Thread(
        target = lambda: answers.append(module._described(definition, refresh = False))
    )
    first.start()
    assert started.wait(5)
    second = threading.Thread(
        target = lambda: answers.append(module._described(definition, refresh = False))
    )
    second.start()
    release.set()
    first.join(10)
    second.join(10)

    assert walks == ["uv"]
    assert [answer["size_bytes"] for answer in answers] == [10, 10]


def test_a_forced_read_does_not_take_a_walk_that_began_before_it(
    tmp_path, monkeypatch, isolated_caches
):
    import threading

    from utils import cache_inventory as module

    root = tmp_path / "uv"
    _write(root / "wheel.whl", "w" * 100)
    definition = definition_for("uv")
    walks: list = []
    started = threading.Event()
    release = threading.Event()
    real_describe = cache_inventory.describe_cache

    def slow(target):
        walks.append(len(walks))
        if not walks[-1]:
            started.set()
            release.wait(5)
        return real_describe(target)

    monkeypatch.setattr(cache_inventory, "describe_cache", slow)
    sizes: list = []
    first = threading.Thread(
        target = lambda: sizes.append(module._described(definition, refresh = False))
    )
    first.start()
    assert started.wait(5)
    for child in root.iterdir():
        child.unlink()
    forced = threading.Thread(
        target = lambda: sizes.append(module._described(definition, refresh = True))
    )
    forced.start()
    release.set()
    first.join(10)
    forced.join(10)

    assert len(walks) == 2
    assert sizes[-1]["size_bytes"] == 0


def test_the_child_caches_ignore_a_studio_selected_models_folder(
    tmp_path, monkeypatch, isolated_caches
):
    from utils import hf_cache_settings

    chosen = tmp_path / "MyModels"
    (chosen / "hub").mkdir(parents = True)
    theirs = _write(chosen / "assets" / "not-a-cache.bin", "d" * 10)
    real_home = tmp_path / "default-hf"
    mine = _write(real_home / "assets" / "asset.bin", "a" * 10)

    paths = hf_cache_settings.HuggingFaceCachePaths(
        chosen, chosen / "hub", real_home / "xet", "studio"
    )
    monkeypatch.setattr(hf_cache_settings, "get_hf_cache_paths", lambda: paths)
    monkeypatch.delenv("HF_ASSETS_CACHE", raising = False)
    monkeypatch.setenv("HF_HOME", str(real_home))

    entry = describe_cache(definition_for("hf_assets"))
    assert entry["paths"] == [str(real_home / "assets")]
    purge_caches(["hf_assets"])
    assert theirs.exists()
    assert not mine.exists()


def test_the_npx_cache_is_cleared_with_the_package_cache(tmp_path, monkeypatch, isolated_caches):
    npm = tmp_path / "npm"
    package = _write(npm / "_cacache" / "index-v5" / "entry", "c" * 20)
    executable = _write(npm / "_npx" / "abc123" / "node_modules" / "server.js", "x" * 30)
    logs = _write(npm / "_logs" / "debug.log", "l" * 5)
    monkeypatch.setenv("npm_config_cache", str(npm))

    entry = describe_cache(definition_for("npm"))
    assert entry["paths"] == [str(npm / "_cacache"), str(npm / "_npx")]
    assert entry["size_bytes"] == 50
    purge_caches(["npm"])
    assert not package.exists()
    assert not executable.exists()
    assert logs.exists()


def test_a_purge_holds_the_registry_against_a_download_claimed_after_the_check(tmp_path):
    from hub.utils.download_registry import DownloadRegistry

    registry = DownloadRegistry()
    assert registry.begin_cache_purge() is True
    claimed, state = registry.claim_repository_owner("org/model", object())
    assert claimed is False
    assert state == "deleting"

    assert registry.begin_cache_purge() is True
    registry.end_cache_purge()
    assert registry.claim_repository_owner("org/model", object())[0] is False
    registry.end_cache_purge()
    assert registry.claim_repository_owner("org/model", object())[0] is True

    assert registry.begin_cache_purge() is False


def test_the_xet_cache_is_reserved_like_the_hub(monkeypatch):
    from hub.utils import download_registry
    from utils import cache_inventory as module

    class _Registry:
        def __init__(self):
            self.held = 0

        def begin_cache_purge(self):
            self.held += 1
            return True

        def end_cache_purge(self):
            self.held -= 1

    models, datasets = _Registry(), _Registry()
    monkeypatch.setattr(download_registry, "get_models_registry", lambda: models)
    monkeypatch.setattr(download_registry, "get_datasets_registry", lambda: datasets)
    from hub.services.datasets import downloads as dataset_downloads

    monkeypatch.setattr(dataset_downloads, "begin_cache_purge", datasets.begin_cache_purge)
    monkeypatch.setattr(dataset_downloads, "end_cache_purge", datasets.end_cache_purge)

    reserved, busy = module._reserve_downloads("hf_xet")
    assert busy is None
    assert (models.held, datasets.held) == (1, 1)
    module._release_downloads(reserved)


def test_a_repository_delete_and_a_whole_cache_purge_exclude_each_other():
    from hub.utils.download_registry import DownloadRegistry

    registry = DownloadRegistry()
    assert registry.begin_delete("org/model") is True
    assert registry.begin_cache_purge() is False
    registry.end_delete("org/model")

    assert registry.begin_cache_purge() is True
    assert registry.begin_delete("org/model") is False
    registry.end_cache_purge()
    assert registry.begin_delete("org/model") is True


def test_a_running_training_job_holds_off_the_model_cache_clears(
    tmp_path, monkeypatch, isolated_caches
):
    import core.training as training_module
    from utils import cache_inventory as module

    blob = _write(isolated_caches / "hub" / "models--org--model" / "blob", "m" * 10)
    wheel = _write(tmp_path / "uv" / "wheel.whl", "w" * 10)

    class _Backend:
        active = True

        def is_training_active(self):
            return self.active

    backend = _Backend()
    monkeypatch.setattr(training_module, "get_training_backend", lambda: backend, raising = False)

    result = purge_caches(["hf_hub"])["results"][0]
    assert blob.exists()
    assert result["errors"] == ["Stop the training run before clearing this cache."]
    for key in ("hf_xet", "hf_datasets"):
        assert module._training_refusal(key) is not None
    assert module._training_refusal("uv") is None
    purge_caches(["uv"])
    assert not wheel.exists()

    backend.active = False
    purge_caches(["hf_hub"])
    assert not blob.exists()


def test_the_torch_extensions_cache_repeats_the_name_on_windows(
    tmp_path, monkeypatch, isolated_caches
):
    from utils import cache_inventory as module

    monkeypatch.delenv("TORCH_EXTENSIONS_DIR", raising = False)
    monkeypatch.setattr(module, "_is_windows", lambda: True)
    monkeypatch.setenv("LOCALAPPDATA", str(tmp_path / "Local"))
    assert module._torch_extensions_dirs() == [
        tmp_path / "Local" / "torch_extensions" / "torch_extensions" / "Cache"
    ]

    monkeypatch.setattr(module, "_is_windows", lambda: False)
    monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path / "xdg"))
    assert module._torch_extensions_dirs() == [tmp_path / "xdg" / "torch_extensions"]


def test_a_diffusion_run_holds_off_the_model_cache_clears(monkeypatch):
    import core.training as training_module
    from core.training import diffusion_training_service
    from utils import cache_inventory as module

    class _Idle:
        def is_training_active(self):
            return False

    class _Busy:
        def is_active(self):
            return True

    monkeypatch.setattr(training_module, "get_training_backend", lambda: _Idle(), raising = False)
    monkeypatch.setattr(
        diffusion_training_service, "get_diffusion_training_service", lambda: _Busy()
    )
    for key in ("hf_hub", "hf_xet", "hf_datasets"):
        assert module._training_refusal(key) is not None
    assert module._training_refusal("uv") is None


def test_a_compiled_cache_the_clear_would_refuse_says_so_on_the_row(
    tmp_path, monkeypatch, only_the_configured_compiled_cache
):
    from utils import cache_cleanup
    from utils.paths import storage_roots

    documents = tmp_path / "Documents"
    compiled = documents / "checkout" / "unsloth_compiled_cache"
    compiled.mkdir(parents = True)
    (compiled / cache_cleanup.CACHE_MARKER).touch()
    generated = _write(compiled / "unsloth_compiled_module_llama.py", "compiled" * 10)
    monkeypatch.setattr(storage_roots, "documents_root", lambda: documents)
    monkeypatch.setenv("UNSLOTH_COMPILE_LOCATION", str(compiled))

    entry = describe_cache(definition_for("unsloth_compiled"))
    assert entry["purgeable"] is False
    assert "protected folder" in (entry["blocked_reason"] or "")
    assert entry["size_bytes"] == 0
    result = purge_caches(["unsloth_compiled"])["results"][0]
    assert generated.exists()
    assert result["errors"]


def test_moving_the_models_folder_forgets_the_old_roots_sizes(
    tmp_path, monkeypatch, isolated_caches
):
    from utils import cache_inventory as module

    _write(tmp_path / "hub" / "blob", "b" * 40)
    definition = definition_for("hf_hub")
    monkeypatch.setattr(
        cache_inventory, "describe_cache", lambda target: {"key": target.key, "size_bytes": 40}
    )
    assert module._described(definition, refresh = False)["size_bytes"] == 40

    monkeypatch.setattr(
        cache_inventory, "describe_cache", lambda target: {"key": target.key, "size_bytes": 7}
    )
    assert module._described(definition, refresh = False)["size_bytes"] == 40, "memo not warm"

    module.invalidate_hf_rooted_sizes()
    assert module._described(definition, refresh = False)["size_bytes"] == 7


def test_setting_the_cache_home_invalidates_the_inventory(monkeypatch):
    import hub.utils.hf_cache_state as hf_cache_state
    import hub.utils.inventory_scan as inventory_scan
    import storage.studio_db as studio_db
    from utils import cache_inventory as module
    from utils import hf_cache_settings

    called: list = []
    monkeypatch.setattr(module, "invalidate_hf_rooted_sizes", lambda: called.append("sizes"))
    monkeypatch.setattr(hf_cache_settings, "_environment_paths", lambda: None)
    monkeypatch.setattr(hf_cache_settings, "_stored_cache_home", lambda: None)
    monkeypatch.setattr(hf_cache_settings, "_stored_history", lambda: [])
    monkeypatch.setattr(studio_db, "upsert_app_settings", lambda _values: None)
    monkeypatch.setattr(inventory_scan, "invalidate_hf_cache_scans", lambda: None)
    monkeypatch.setattr(hf_cache_state, "invalidate_partial_resumability", lambda: None)

    hf_cache_settings.set_hf_cache_home(None)
    assert called == ["sizes"]


def test_bytes_still_linked_from_outside_are_not_called_reclaimable(tmp_path, isolated_caches):
    root = tmp_path / "uv"
    shared = _write(root / "archive" / "wheel.so", "w" * 800)
    venv = tmp_path / "venv" / "lib"
    venv.mkdir(parents = True)
    os.link(shared, venv / "wheel.so")
    _write(root / "archive" / "own.bin", "o" * 20)

    entry = describe_cache(definition_for("uv"))

    assert entry["size_bytes"] == 20


def test_a_purge_reports_only_the_bytes_it_actually_freed(tmp_path, isolated_caches):
    root = tmp_path / "uv"
    shared = _write(root / "archive" / "wheel.so", "w" * 800)
    venv = tmp_path / "venv" / "lib"
    venv.mkdir(parents = True)
    os.link(shared, venv / "wheel.so")
    _write(root / "archive" / "own.bin", "o" * 20)

    outcome = empty_cache_root(root)

    assert outcome.errors == []
    assert outcome.freed_bytes == 20
    assert (venv / "wheel.so").read_text(encoding = "utf-8") == "w" * 800


def test_a_whole_hub_clear_waits_for_a_loaded_model(monkeypatch, isolated_caches):
    import hub.services.models.deletion as deletion

    monkeypatch.setattr(
        deletion, "any_model_load_blocks_cache_clear", lambda: "Unload the model before clearing"
    )
    result = cache_inventory.purge_cache("hf_hub")

    assert result["errors"] == ["Unload the model before clearing"]
    assert result["freed_bytes"] == 0


def _idle_dictation(monkeypatch, **state):
    from core.inference import stt_registry

    resident = {"model": None, "engine": None, "device": None, "loading": False}
    resident.update(state)
    monkeypatch.setattr(stt_registry, "resident", lambda: resident)


def test_a_whole_hub_clear_waits_for_a_loaded_dictation_model(monkeypatch):
    from hub.services.models.deletion import any_model_load_blocks_cache_clear
    _idle_dictation(monkeypatch, model = "openai/whisper-large-v3", engine = "transformers")

    assert any_model_load_blocks_cache_clear() == (
        "Unload the dictation model before clearing the model cache"
    )


def test_a_whole_hub_clear_waits_for_a_loading_dictation_model(monkeypatch):
    from hub.services.models.deletion import any_model_load_blocks_cache_clear
    _idle_dictation(monkeypatch, loading = True)

    assert any_model_load_blocks_cache_clear() == (
        "A dictation model load is using the cache; wait for it to finish"
    )


def test_idle_dictation_does_not_block_a_hub_clear(monkeypatch):
    "An idle sidecar is the negative control for guards that refuse every clear."
    from hub.services.models.deletion import any_model_load_blocks_cache_clear

    _idle_dictation(monkeypatch)

    assert any_model_load_blocks_cache_clear() is None


def test_an_unreachable_dictation_probe_does_not_block_a_hub_clear(monkeypatch):
    from core.inference import stt_registry
    from hub.services.models.deletion import any_model_load_blocks_cache_clear

    def _raise():
        raise RuntimeError("sidecar wedged")

    monkeypatch.setattr(stt_registry, "resident", _raise)

    assert any_model_load_blocks_cache_clear() is None


def test_a_whole_hub_clear_waits_for_a_chat_load_that_has_not_spawned_yet(monkeypatch):
    from core.inference import llama_cpp
    from hub.services.models.deletion import any_model_load_blocks_cache_clear

    _idle_dictation(monkeypatch)
    monkeypatch.setattr(llama_cpp, "chat_load_active", lambda: True)

    assert any_model_load_blocks_cache_clear() == (
        "A model load is using the cache; wait for it to finish"
    )


def test_a_whole_hub_clear_waits_for_a_draining_image_load(monkeypatch):
    import types

    from hub.services.models.deletion import any_model_load_blocks_cache_clear

    _idle_dictation(monkeypatch)
    draining = types.SimpleNamespace(
        status = lambda: {"loaded": False},
        loaded_repo_ids = tuple,
        loading_repo_ids = tuple,
        draining_repo_ids = lambda: ("black-forest-labs/FLUX.2-klein-4B",),
    )
    router = types.ModuleType("core.inference.diffusion_engine_router")
    router.get_active_diffusion_engine = lambda: draining
    monkeypatch.setitem(sys.modules, "core.inference.diffusion_engine_router", router)

    assert any_model_load_blocks_cache_clear() == (
        "An Images model load is still unwinding; wait for it to finish"
    )


def test_an_unverifiable_load_state_refuses_rather_than_clears(monkeypatch, isolated_caches):
    import hub.services.models.deletion as deletion

    def _raise():
        raise RuntimeError("backend wedged")

    monkeypatch.setattr(deletion, "any_model_load_blocks_cache_clear", _raise)
    result = cache_inventory.purge_cache("hf_hub")

    assert result["errors"] and "Could not verify" in result["errors"][0]


def test_a_cache_the_environment_is_symlinked_into_is_not_offered(
    tmp_path, monkeypatch, isolated_caches
):
    _write(tmp_path / "uv" / "archive" / "pkg" / "__init__.py", "x")
    site = tmp_path / "site-packages"
    site.mkdir()
    (site / "pkg").symlink_to(tmp_path / "uv" / "archive" / "pkg", target_is_directory = True)
    import sysconfig

    monkeypatch.setattr(sysconfig, "get_paths", lambda *a, **k: {"purelib": str(site)})

    entry = describe_cache(definition_for("uv"))
    assert entry["purgeable"] is False
    assert "symlinked" in (entry["blocked_reason"] or "")

    result = cache_inventory.purge_cache("uv")
    assert result["errors"] and "symlinked" in result["errors"][0]
    assert (tmp_path / "uv" / "archive" / "pkg" / "__init__.py").exists()


def test_the_declared_link_mode_alone_is_enough_to_refuse(tmp_path, monkeypatch, isolated_caches):
    _write(tmp_path / "uv" / "a.bin", "a" * 10)
    monkeypatch.setenv("UV_LINK_MODE", "symlink")

    entry = describe_cache(definition_for("uv"))

    assert entry["purgeable"] is False
    assert "link packages" in (entry["blocked_reason"] or "")


def test_an_ordinary_uv_cache_is_still_offered(tmp_path, isolated_caches):
    _write(tmp_path / "uv" / "a.bin", "a" * 10)

    entry = describe_cache(definition_for("uv"))

    assert entry["purgeable"] is True
    assert entry["blocked_reason"] is None


def test_a_partial_purge_reports_only_what_it_actually_removed(tmp_path, isolated_caches):
    root = tmp_path / "uv"
    _write(root / "tree" / "gone.bin", "g" * 100)
    stubborn = root / "tree" / "stays"
    _write(stubborn / "kept.bin", "k" * 40)
    stubborn.chmod(0o500)
    try:
        outcome = empty_cache_root(root)
    finally:
        stubborn.chmod(0o700)

    assert outcome.errors, "the removal was expected to fail partway"
    assert (stubborn / "kept.bin").exists()
    assert outcome.freed_bytes == 100


def test_a_curated_dataset_import_holds_off_a_model_cache_clear():
    from hub.utils.download_registry import get_datasets_registry

    registry = get_datasets_registry()
    owner = object()
    granted, _ = registry.claim_repository_owner("some/curated-set", owner)
    assert granted
    try:
        assert registry.begin_cache_purge() is False
    finally:
        registry.release_repository_owner("some/curated-set", owner)
    assert registry.begin_cache_purge() is True
    registry.end_cache_purge()


def test_the_import_route_takes_that_claim_and_gives_it_back():
    "Inspect the route as source because executing its import requires a real dataset and network."
    import ast
    import inspect

    import routes.training as training

    source = inspect.getsource(training)
    tree = ast.parse(source)
    calls = {
        node.func.attr
        for node in ast.walk(tree)
        if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute)
    }
    assert "claim_repository_owner" in calls
    assert "release_repository_owner" in calls
    start = source.index("claim_repository_owner")
    tail = source[start:]
    assert "finally:" in tail[: tail.index("release_repository_owner")]


def test_every_account_dataset_registry_is_reserved_by_a_purge(monkeypatch):
    from hub.services.datasets import downloads as dataset_downloads
    from hub.utils import download_registry

    other = download_registry.DownloadRegistry()
    monkeypatch.setitem(dataset_downloads._account_registries, "account-2", other)

    granted, _ = other.claim_repository_owner("some/set", object())
    assert granted

    assert (
        dataset_downloads.begin_cache_purge() is False
    ), "the purge was granted while another account's dataset download held its own registry"


def test_a_registry_created_during_a_purge_is_born_reserved(monkeypatch):
    from hub.services.datasets import downloads as dataset_downloads
    from hub.utils import download_registry

    monkeypatch.setattr(dataset_downloads, "_account_registries", {})
    assert dataset_downloads.begin_cache_purge() is True
    try:
        fresh = download_registry.DownloadRegistry()
        for _ in range(dataset_downloads._purging):
            fresh.begin_cache_purge()
        assert fresh.claim_repository_owner("late/set", object()) == (False, "deleting")
    finally:
        dataset_downloads.end_cache_purge()


def test_hf_occupancy_is_measured_even_when_documents_clear_is_forbidden(
    tmp_path, monkeypatch, isolated_caches
):
    hub = isolated_caches / "hub"
    _write(hub / "models--org--model" / "blobs" / "weights", "x" * 123)
    monkeypatch.setattr(cache_inventory, "protected_trees", lambda: {isolated_caches})
    entry = describe_cache(definition_for("hf_hub"))
    assert entry["size_bytes"] == 123
    assert entry["purgeable"] is False
    assert entry["clear_size_bytes"] == 0
    assert "protected folder" in entry["blocked_reason"]
    assert (hub / "models--org--model" / "blobs" / "weights").exists()


def test_hf_history_counts_storage_without_widening_clear(tmp_path, monkeypatch, isolated_caches):
    from utils import hf_cache_settings

    active = isolated_caches / "hub"
    previous = tmp_path / "previous" / "hub"
    mine = _write(active / "models--org--active" / "blobs" / "weight", "a" * 15)
    kept = _write(previous / "models--org--old" / "blobs" / "weight", "b" * 27)
    monkeypatch.setattr(
        hf_cache_settings, "known_hf_hub_caches", lambda: [active, previous, active]
    )
    entry = describe_cache(definition_for("hf_hub"))
    assert entry["size_bytes"] == 42
    assert entry["clear_size_bytes"] == 15
    assert entry["paths"] == [str(active)]
    assert len(entry["measured_paths"]) == 2
    purge_caches(["hf_hub"])
    assert not mine.exists()
    assert kept.exists()


def test_hf_breakdown_is_on_demand_and_includes_incomplete_blobs(
    tmp_path, monkeypatch, isolated_caches
):
    hub = isolated_caches / "hub"
    _write(hub / "models--org--model" / "blobs" / "weight.incomplete", "a" * 120)
    _write(hub / "datasets--org--data" / "snapshots" / "revision" / "data.json", "b" * 25)
    called = []
    original = cache_inventory.cache_breakdown
    monkeypatch.setattr(
        cache_inventory, "cache_breakdown", lambda key: (called.append(key), original(key))[1]
    )
    describe_cache(definition_for("hf_hub"))
    assert called == []
    entries = cache_inventory.cache_breakdown("hf_hub")["entries"]
    assert [entry["size_bytes"] for entry in entries] == [120, 25]
    assert entries[0]["name"] == "models--org--model"
    with pytest.raises(ValueError):
        cache_inventory.cache_breakdown("../outside")


def test_hf_measurement_does_not_walk_a_protected_root(tmp_path, monkeypatch, isolated_caches):
    from utils import hf_cache_settings

    monkeypatch.setattr(hf_cache_settings, "known_hf_hub_caches", lambda: [tmp_path])
    monkeypatch.setattr(cache_inventory, "protected_paths", lambda: {tmp_path})
    walked = []
    monkeypatch.setattr(
        cache_inventory, "_measure_root", lambda root, **kwargs: (walked.append(root) or 0, 0)
    )
    describe_cache(definition_for("hf_hub"))
    assert tmp_path not in walked


def test_hf_shared_file_occupies_space_even_when_clear_cannot_reclaim_it(tmp_path, isolated_caches):
    cached = _write(isolated_caches / "hub" / "models--org--shared" / "blobs" / "weight", "w" * 800)
    os.link(cached, tmp_path / "installed-weight")

    entry = describe_cache(definition_for("hf_hub"))
    assert entry["size_bytes"] == 800
    assert entry["clear_size_bytes"] == 0
    assert cache_inventory.cache_breakdown("hf_hub")["entries"][0]["size_bytes"] == 800


def test_hf_history_deduplicates_shared_inodes_and_walks_each_root_once(
    tmp_path, monkeypatch, isolated_caches
):
    from utils import hf_cache_settings

    active = isolated_caches / "hub"
    previous = tmp_path / "old" / "hub"
    shared = _write(active / "models--org--shared" / "blobs" / "weight", "w" * 800)
    previous_blob = previous / "models--org--copy" / "blobs" / "weight"
    previous_blob.parent.mkdir(parents = True)
    os.link(shared, previous_blob)
    _write(active / "models--org--unique" / "blobs" / "weight", "u" * 25)
    monkeypatch.setattr(hf_cache_settings, "known_hf_hub_caches", lambda: [active, previous])
    walked = []
    measure = cache_inventory._measure_root
    monkeypatch.setattr(
        cache_inventory,
        "_measure_root",
        lambda root, **kwargs: (walked.append(root), measure(root, **kwargs))[1],
    )

    entry = describe_cache(definition_for("hf_hub"))
    assert entry["size_bytes"] == 825
    assert entry["clear_size_bytes"] == 25
    assert walked.count(active) == walked.count(previous) == 1
    breakdown = cache_inventory.cache_breakdown("hf_hub")["entries"]
    assert sum(row["size_bytes"] for row in breakdown) == 825
    purge_caches(["hf_hub"])
    assert previous_blob.read_text(encoding = "utf-8") == "w" * 800


def test_empty_active_hf_cache_has_no_clearable_entries_despite_history(
    tmp_path, monkeypatch, isolated_caches
):
    from utils import hf_cache_settings

    previous = tmp_path / "old" / "hub"
    _write(previous / "models--org--old" / "blobs" / "weight", "w" * 80)
    monkeypatch.setattr(
        hf_cache_settings, "known_hf_hub_caches", lambda: [isolated_caches / "hub", previous]
    )
    entry = describe_cache(definition_for("hf_hub"))
    assert entry["size_bytes"] == 80
    assert entry["entry_count"] == 1
    assert entry["clear_entry_count"] == 0
    assert entry["clear_size_bytes"] == 0


def test_system_cache_accounting_matches_system_volume_when_studio_is_elsewhere(
    tmp_path, monkeypatch
):
    from types import SimpleNamespace
    from utils.paths import storage_roots

    system = Path(os.path.abspath(os.sep))
    studio = tmp_path / "studio-on-another-disk"
    real_stat = Path.stat

    def stat(path, *args, **kwargs):
        if path == system:
            return SimpleNamespace(st_dev = 1)
        if path == studio:
            return SimpleNamespace(st_dev = 2)
        return real_stat(path, *args, **kwargs)

    with monkeypatch.context() as patch:
        patch.setattr(Path, "stat", stat)
        patch.setattr(storage_roots, "studio_root", lambda: studio)
        assert cache_inventory._system_disk_device() == 1

    ledger = cache_inventory._OccupancyLedger()
    ledger.add(SimpleNamespace(st_dev = 1, st_ino = 10, st_size = 100), system / "old-model")
    ledger.add(SimpleNamespace(st_dev = 2, st_ino = 20, st_size = 200), studio / "new-model")
    monkeypatch.setattr(cache_inventory, "_system_disk_device", lambda: 1)
    monkeypatch.setattr(
        cache_inventory.shutil,
        "disk_usage",
        lambda path: SimpleNamespace(total = 1000 if Path(path) == system else 2000, free = 100),
    )
    assert cache_inventory._system_disk_occupancy(ledger) == 100


def test_distinct_device_ids_in_the_same_pool_still_count_as_system_storage(tmp_path, monkeypatch):
    from types import SimpleNamespace

    system = Path(os.path.abspath(os.sep))
    ledger = cache_inventory._OccupancyLedger()
    ledger.add(SimpleNamespace(st_dev = 1, st_ino = 10, st_size = 100), system / "cached")
    ledger.add(SimpleNamespace(st_dev = 2, st_ino = 20, st_size = 200), tmp_path / "data" / "cached")
    ledger.add(SimpleNamespace(st_dev = 3, st_ino = 30, st_size = 300), tmp_path / "unknown" / "cached")
    monkeypatch.setattr(cache_inventory, "_system_disk_device", lambda: 1)

    def usage(path):
        if Path(path) == tmp_path / "unknown":
            raise PermissionError("unreadable device")
        return SimpleNamespace(total = 10**12, free = 10**11 - (1024 if Path(path) != system else 0))

    monkeypatch.setattr(cache_inventory.shutil, "disk_usage", usage)
    assert cache_inventory._system_disk_occupancy(ledger) == 300


def test_hf_model_breakdown_actions_name_one_exact_known_cache_copy(
    tmp_path, monkeypatch, isolated_caches
):
    from utils import hf_cache_settings
    from hub.utils.hf_cache_state import scoped_delete_root

    active = isolated_caches / "hub"
    old = tmp_path / "previous" / "hub"
    for root in (active, old):
        _write(root / "models--Org--Model" / "blobs" / "weight", "model")
    _write(active / "models--gpt2" / "blobs" / "weight", "standalone")
    monkeypatch.setattr(hf_cache_settings, "known_hf_hub_caches", lambda: [active, old])

    rows = cache_inventory.cache_breakdown("hf_hub")["entries"]
    copies = [row for row in rows if row.get("repo_id") == "Org/Model"]
    assert len(copies) == 2
    assert {row["cache_path"] for row in copies} == {
        str(root / "models--Org--Model") for root in (active, old)
    }
    for row in rows:
        assert row["delete_allowed"] is True
        assert row["repo_type"] == "model"
        assert row["cache_path"] == row["path"]
        assert (
            scoped_delete_root("model", row["repo_id"], row["cache_path"])
            == Path(row["cache_path"]).parent
        )


@pytest.mark.parametrize(
    "name",
    [
        ".locks",
        "datasets--Org--Data",
        "spaces--Org--Space",
        "models--",
        "models----Model",
        "models--Org--Model--nested",
        "models--Org--bad..name",
        "models--Org--Model.git",
    ],
)
def test_hf_breakdown_never_offers_model_actions_for_non_model_or_malformed_rows(
    tmp_path, isolated_caches, name
):
    _write(isolated_caches / "hub" / name / "data", "cache")
    row = cache_inventory.cache_breakdown("hf_hub")["entries"][0]
    assert row["delete_allowed"] is False
    assert "repo_id" not in row and "cache_path" not in row


def test_hf_breakdown_does_not_turn_a_model_shaped_file_into_a_delete_action(isolated_caches):
    _write(isolated_caches / "hub" / "models--Org--File", "not a repository directory")
    row = cache_inventory.cache_breakdown("hf_hub")["entries"][0]
    assert row["delete_allowed"] is False


def test_hf_breakdown_actions_are_confined_to_hub_approved_roots(
    tmp_path, monkeypatch, isolated_caches
):
    outside = tmp_path / "not-a-known-cache"
    _write(outside / "models--Org--Model" / "blobs" / "weight", "unrelated")
    monkeypatch.setattr(cache_inventory, "_measurement_roots", lambda _definition: [outside])
    row = cache_inventory.cache_breakdown("hf_hub")["entries"][0]
    assert row["delete_allowed"] is False
    assert "cache_path" not in row


def test_hf_breakdown_does_not_offer_model_actions_inside_xet_cache(isolated_caches):
    _write(isolated_caches / "xet" / "models--Org--Model" / "data", "xet")
    row = cache_inventory.cache_breakdown("hf_xet")["entries"][0]
    assert row["delete_allowed"] is False


@pytest.mark.parametrize("link_kind", ["symlink", "junction"])
def test_model_action_identity_refuses_links_even_to_valid_named_directories(
    tmp_path, monkeypatch, isolated_caches, link_kind
):
    from types import SimpleNamespace

    root = isolated_caches / "hub"
    directory = root / "models--Org--Model"
    directory.mkdir()
    entry = SimpleNamespace(
        name = directory.name,
        path = str(directory),
        is_symlink = lambda: link_kind == "symlink",
        is_dir = lambda **_kwargs: True,
    )
    monkeypatch.setattr(cache_inventory, "_is_junction", lambda _path: link_kind == "junction")
    assert cache_inventory._model_cache_action(root, entry) == {"delete_allowed": False}