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.

Studio: reuse each repo's partial verdict in the local model listing (#16199)

Daniel Hanea69b9cf24e9
diff --git a/studio/backend/core/inference/local_model_resolver.py b/studio/backend/core/inference/local_model_resolver.py
index 24916fd7afe..7d9722bb98d 100644
--- a/studio/backend/core/inference/local_model_resolver.py
+++ b/studio/backend/core/inference/local_model_resolver.py
@@ -1024,6 +1024,9 @@ def index_generation() -> int:
def invalidate_index(*, additions_only: bool = False) -> None:
"""Additions-only keeps known hits served during rebuild; any other invalidation revokes trust."""
global _scan, _warm_pending, _generation
+ if not additions_only:
+ from hub.utils import partial_verdict_cache
+ partial_verdict_cache.invalidate()
with _lock:
now = time.monotonic()
_generation += 1
diff --git a/studio/backend/hub/utils/inventory_scan.py b/studio/backend/hub/utils/inventory_scan.py
index 16431c3a02f..7a83ae829a1 100644
--- a/studio/backend/hub/utils/inventory_scan.py
+++ b/studio/backend/hub/utils/inventory_scan.py
@@ -38,6 +38,7 @@ from hub.utils.hf_tokens import (
from hub.utils.host_paths import scrub_paths, short_path_for_log
from hub.utils.state_dir import RepoType
+from hub.utils import partial_verdict_cache
from hub.utils.hf_cache_state import (
has_incomplete_blobs,
hf_cache_roots,
@@ -101,6 +102,7 @@ def invalidate_hf_cache_scans(*, sizes: bool = True) -> None:
_hf_cache_scans_cached_at = 0.0
_hf_cache_scans_epoch += 1
invalidate_scan_memos()
+ partial_verdict_cache.invalidate()
# Settings may answer a slow cache from its last walk; a download or delete must not show the old size.
if sizes:
try:
@@ -1801,6 +1803,23 @@ def is_gguf_repo_partial(
return has_broken and not has_clean
+def repo_listing_partial(
+ repo_id: str,
+ repo_cache_dir: Path,
+ *,
+ variant_state = None,
+) -> bool:
+ """``is_snapshot_partial`` or ``is_gguf_repo_partial``, reused while the repo and Hub state are unchanged."""
+
+ def compute() -> bool:
+ return is_snapshot_partial(
+ "model", repo_id, repo_cache_dir, variant_state = variant_state
+ ) or is_gguf_repo_partial(repo_id, repo_cache_dir, variant_state = variant_state)
+
+ key = ("listing", repo_id, variant_state is None, is_snapshot_partial, is_gguf_repo_partial)
+ return partial_verdict_cache.cached_verdict(key, repo_cache_dir, compute)
+
+
def partial_transport_for(
repo_type: RepoType,
repo_id: str,
diff --git a/studio/backend/hub/utils/partial_verdict_cache.py b/studio/backend/hub/utils/partial_verdict_cache.py
new file mode 100644
index 00000000000..f50a9e5bd82
--- /dev/null
+++ b/studio/backend/hub/utils/partial_verdict_cache.py
@@ -0,0 +1,319 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Per-repo partial verdict of the local model listing, kept across requests.
+
+Every writer of what the verdict reads (huggingface_hub, the Studio download worker, a delete)
+creates, renames or unlinks a directory entry, so a verdict is kept with stats of: the repo dir,
+``snapshots/``, ``blobs/``, ``refs/`` and every snapshot subdir; every file under ``refs/`` and in a
+snapshot, and link targets outside ``blobs/`` (rewritable in place); shared-store blobs and their dir;
+and a per-scan token over the whole Hub state tree. Nothing is stored on a non-ENOENT stat error, a
+too-recent timestamp, a signature moved during compute, an invalidation meanwhile, or a linked
+directory. Linux local filesystems that move directory mtimes only; entries expire after a minute.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import threading
+import time
+from collections import OrderedDict
+from pathlib import Path
+from typing import Callable, Hashable, NamedTuple, Optional
+
+from utils.scan_memo import memoized, scan_memo_active
+
+_MAX_ENTRIES = 4096
+# A change inside this window of the signature can share its timestamp (coarse clocks, FAT 2 s).
+_RACY_NS = 3_000_000_000
+# Bounds a wrong verdict from a transient OSError (EMFILE, EIO) the checks swallow.
+_MAX_AGE_NS = 60_000_000_000
+_ABSENT_ERRNOS = frozenset({2, 20}) # ENOENT, ENOTDIR
+# Local filesystems whose directory mtime moves on every create, rename and unlink in it.
+_TRUSTED_FS_TYPES = frozenset(
+ {
+ "ext2",
+ "ext3",
+ "ext4",
+ "xfs",
+ "btrfs",
+ "zfs",
+ "f2fs",
+ "bcachefs",
+ "jfs",
+ "nilfs2",
+ "reiserfs",
+ "tmpfs",
+ "ramfs",
+ "overlay",
+ }
+)
+
+_lock = threading.Lock()
+_entries: "OrderedDict[Hashable, _Entry]" = OrderedDict()
+_generation = 0
+_last_token: Optional[tuple] = None
+
+
+class _Unstable(Exception):
+ """A stat failed for a reason other than absence; nothing is cached or served."""
+
+
+class _Entry(NamedTuple):
+ verdict: bool
+ token: tuple
+ dirs: tuple
+ files: tuple
+ signature: tuple
+ stored_ns: int
+
+
+def enabled() -> bool:
+ return sys.platform.startswith("linux")
+
+
+def _mount_fs_types() -> dict[tuple[int, int], set[str]]:
+ types: dict[tuple[int, int], set[str]] = {}
+ with open("/proc/self/mountinfo", encoding = "utf-8", errors = "replace") as handle:
+ for line in handle:
+ fields = line.split()
+ try:
+ major, minor = fields[2].split(":")
+ fs_type = fields[fields.index("-", 6) + 1]
+ except (IndexError, ValueError):
+ continue
+ types.setdefault((int(major), int(minor)), set()).add(fs_type)
+ return types
+
+
+def _trusted_devices(devices: set[int]) -> bool:
+ """Whether every device is a mount of a trusted filesystem, read once per scan."""
+ try:
+ types = memoized(("partial_verdict_mount_types",), _mount_fs_types)
+ except (OSError, ValueError):
+ return False
+ for dev in devices:
+ found = types.get((os.major(dev), os.minor(dev)))
+ # A device mounted twice with different types, or not listed at all, is not vouched for.
+ if not found or len(found) != 1 or not found <= _TRUSTED_FS_TYPES:
+ return False
+ return True
+
+
+def _devices(stats) -> set[int]:
+ return {s[0] for s in stats if s is not None}
+
+
+def invalidate() -> None:
+ global _generation
+ with _lock:
+ _generation += 1
+ _entries.clear()
+
+
+def _stat(path: str) -> Optional[tuple]:
+ try:
+ st = os.stat(path)
+ except OSError as exc:
+ if exc.errno in _ABSENT_ERRNOS:
+ return None
+ raise _Unstable from exc
+ except ValueError as exc:
+ raise _Unstable from exc
+ return (st.st_dev, st.st_ino, st.st_mode, st.st_size, st.st_mtime_ns, st.st_ctime_ns)
+
+
+def _scandir(path: str) -> list:
+ try:
+ with os.scandir(path) as it:
+ return list(it)
+ except OSError as exc:
+ if exc.errno in _ABSENT_ERRNOS:
+ return []
+ raise _Unstable from exc
+
+
+def _newest(stats) -> int:
+ return max((max(s[4], s[5]) for s in stats if s is not None), default = 0)
+
+
+def _compute_token() -> Optional[tuple]:
+ from hub.utils import state_dir
+
+ try:
+ from utils.hf_cache_settings import get_hf_cache_paths
+ configured = os.fspath(get_hf_cache_paths().hub_cache)
+ except Exception:
+ configured = None
+ try:
+ root = state_dir.state_root()
+ if root is None:
+ return None
+ items = []
+ pending = [os.path.join(os.fspath(root), name) for name in ("manifests", "cancelled")]
+ while pending:
+ directory = pending.pop()
+ items.append((directory, _stat(directory)))
+ for entry in _scandir(directory):
+ if entry.is_dir(follow_symlinks = False):
+ pending.append(entry.path)
+ else:
+ items.append((entry.path, _stat(entry.path)))
+ hub_real = os.path.realpath(configured) if configured else None
+ except (_Unstable, OSError):
+ return None
+ items.sort()
+ return (os.fspath(root), configured, hub_real, tuple(items))
+
+
+def scan_token() -> Optional[tuple]:
+ """The Hub state token for this scan, taken once; call it before the state is first read."""
+ if not enabled() or not scan_memo_active():
+ return None
+ return memoized(("partial_verdict_token",), _scan_token_uncached)
+
+
+def _scan_token_uncached() -> Optional[tuple]:
+ global _last_token
+ start_ns = time.time_ns()
+ token = _compute_token()
+ if token is None:
+ return None
+ stats = [stat for _path, stat in token[3]]
+ # Too fresh, or untrusted directory mtimes: this scan neither stores nor serves.
+ if _newest(stats) > start_ns - _RACY_NS or not _trusted_devices(_devices(stats)):
+ return None
+ with _lock:
+ # Interned, so entries compare by identity.
+ if token == _last_token:
+ return _last_token
+ _last_token = token
+ return token
+
+
+def _walk_repo(repo_dir: str) -> Optional[tuple[tuple, tuple]]:
+ """Directories and files whose stats decide the verdict; None when the layout cannot be vouched for."""
+ blobs = os.path.join(repo_dir, "blobs")
+ snapshots = os.path.join(repo_dir, "snapshots")
+ refs = os.path.join(repo_dir, "refs")
+ # Snapshot links resolve from where snapshots/ really is, so a linked one points them at blobs this walk would not stat.
+ if os.path.islink(snapshots):
+ return None
+ dirs = [repo_dir, snapshots, blobs, refs]
+ files: list[str] = []
+ pending = [refs]
+ while pending:
+ directory = pending.pop()
+ for entry in _scandir(directory):
+ if entry.is_symlink():
+ return None
+ if entry.is_dir(follow_symlinks = False):
+ dirs.append(entry.path)
+ pending.append(entry.path)
+ else:
+ files.append(entry.path)
+ blob_entries: Optional[dict[str, os.DirEntry]] = None
+ blobs_real: Optional[str] = None
+ linked_blobs: set[str] = set()
+ for snapshot in _scandir(snapshots):
+ if snapshot.is_symlink():
+ return None
+ if not snapshot.is_dir(follow_symlinks = False):
+ files.append(snapshot.path)
+ continue
+ dirs.append(snapshot.path)
+ pending = [snapshot.path]
+ while pending:
+ directory = pending.pop()
+ for entry in _scandir(directory):
+ if entry.is_symlink():
+ try:
+ target = os.readlink(entry.path)
+ except OSError:
+ raise _Unstable from None
+ target = os.path.normpath(os.path.join(directory, target))
+ parent = os.path.dirname(target)
+ if parent == blobs:
+ if blob_entries is None:
+ # One listing answers every link; an absent name is a broken link.
+ blob_entries = {blob.name: blob for blob in _scandir(blobs)}
+ blob = blob_entries.get(os.path.basename(target))
+ if blob is None or blob.path in linked_blobs:
+ continue
+ if blob.is_symlink():
+ # Shared store (<hub>/blobs/<xx>/<xet hash>), sweepable from another repo; resolved from the real blobs/.
+ linked_blobs.add(blob.path)
+ try:
+ shared = os.readlink(blob.path)
+ except OSError:
+ raise _Unstable from None
+ if blobs_real is None:
+ blobs_real = os.path.realpath(blobs)
+ shared = os.path.normpath(os.path.join(blobs_real, shared))
+ if os.path.islink(shared) or os.path.isdir(shared):
+ return None
+ dirs.append(os.path.dirname(shared))
+ files.append(shared)
+ elif blob.is_dir(follow_symlinks = False):
+ return None
+ else:
+ if os.path.islink(target) or os.path.isdir(target):
+ return None
+ dirs.append(parent)
+ files.append(target)
+ elif entry.is_dir(follow_symlinks = False):
+ dirs.append(entry.path)
+ pending.append(entry.path)
+ else:
+ files.append(entry.path)
+ return tuple(dict.fromkeys(dirs)), tuple(dict.fromkeys(files))
+
+
+def _signature(dirs: tuple, files: tuple) -> tuple:
+ return tuple(_stat(p) for p in dirs) + tuple(_stat(p) for p in files)
+
+
+def cached_verdict(key: Hashable, repo_dir: Path, compute: Callable[[], bool]) -> bool:
+ """compute()'s verdict for *repo_dir*, reused while nothing it reads has changed."""
+ token = scan_token()
+ if token is None:
+ return compute()
+ repo = os.path.normpath(os.fspath(repo_dir))
+ key = (key, repo)
+ now = time.time_ns()
+ with _lock:
+ entry = _entries.get(key)
+ generation = _generation
+ if entry is not None and entry.token is token and now - entry.stored_ns < _MAX_AGE_NS:
+ try:
+ if _signature(entry.dirs, entry.files) == entry.signature:
+ with _lock:
+ if key in _entries:
+ _entries.move_to_end(key)
+ return entry.verdict
+ except _Unstable:
+ return compute()
+ try:
+ walked = _walk_repo(repo)
+ before = _signature(*walked) if walked is not None else None
+ except _Unstable:
+ walked = before = None
+ verdict = compute()
+ if walked is None or before is None or _newest(before) > now - _RACY_NS:
+ return verdict
+ if not _trusted_devices(_devices(before)):
+ return verdict
+ try:
+ if _signature(*walked) != before:
+ return verdict
+ except _Unstable:
+ return verdict
+ with _lock:
+ if generation != _generation:
+ return verdict
+ _entries[key] = _Entry(verdict, token, walked[0], walked[1], before, now)
+ _entries.move_to_end(key)
+ while len(_entries) > _MAX_ENTRIES:
+ _entries.popitem(last = False)
+ return verdict
diff --git a/studio/backend/routes/models.py b/studio/backend/routes/models.py
index ebb52794eaf..0b670310242 100644
--- a/studio/backend/routes/models.py
+++ b/studio/backend/routes/models.py
@@ -616,10 +616,7 @@ def _scan_hf_cache(
if variant_states is not None
else None
)
- partial = hf_cache_scan.is_snapshot_partial(
- "model", model_id, repo_dir, variant_state = variant_state
- )
- partial = partial or hf_cache_scan.is_gguf_repo_partial(
+ partial = hf_cache_scan.repo_listing_partial(
model_id, repo_dir, variant_state = variant_state
)
@@ -981,7 +978,10 @@ def collect_local_models(
except OSError:
continue
try:
- from hub.utils import download_manifest
+ from hub.utils import download_manifest, partial_verdict_cache
+
+ # Taken before the index reads the Hub state, so a write in between misses next time.
+ partial_verdict_cache.scan_token()
variant_states = download_manifest.build_variant_state_index(
state_repositories,
active_hub_cache = hf_cache_dir,
diff --git a/studio/backend/tests/test_local_models_partial_verdict_cache.py b/studio/backend/tests/test_local_models_partial_verdict_cache.py
new file mode 100644
index 00000000000..cdd7b676ca5
--- /dev/null
+++ b/studio/backend/tests/test_local_models_partial_verdict_cache.py
@@ -0,0 +1,497 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""/api/models/local keeps each repo's partial verdict across requests, keyed on the stats of the
+directories and files the verdict reads. The listing must equal an uncached one after every
+download-shaped mutation, and a repeat request must not rerun the partial checks."""
+
+from __future__ import annotations
+
+import asyncio
+import errno
+import hashlib
+import json
+import os
+import shutil
+import sys
+import threading
+import time
+from pathlib import Path
+
+import pytest
+
+import routes.models as models_route
+from hub.utils import download_manifest, inventory_scan, partial_verdict_cache
+
+pytestmark = pytest.mark.skipif(
+ not sys.platform.startswith("linux"), reason = "the verdict cache is Linux only"
+)
+
+_REAL_TRUSTED_DEVICES = partial_verdict_cache._trusted_devices
+_CONFIG = json.dumps({"architectures": ["LlamaForCausalLM"], "model_type": "llama"})
+
+
[email protected](autouse = True)
+def _fresh_cache(monkeypatch):
+ partial_verdict_cache.invalidate()
+ # Fixture files are seconds old at most; production refuses to vouch for those.
+ monkeypatch.setattr(partial_verdict_cache, "_RACY_NS", 0)
+ # Whatever filesystem the test tmp dir sits on.
+ monkeypatch.setattr(partial_verdict_cache, "_trusted_devices", lambda devices: True)
+ yield
+ partial_verdict_cache.invalidate()
+
+
+def _settle() -> None:
+ """Let the next write land on a later timestamp than the last stored signature."""
+ time.sleep(0.03)
+
+
+def _blob(repo: Path, body: bytes) -> str:
+ digest = hashlib.sha256(body).hexdigest()
+ (repo / "blobs").mkdir(exist_ok = True)
+ (repo / "blobs" / digest).write_bytes(body)
+ return digest
+
+
+def _link(repo: Path, rev: str, name: str, digest: str) -> None:
+ target = repo / "snapshots" / rev / name
+ target.parent.mkdir(parents = True, exist_ok = True)
+ depth = len(Path(name).parts)
+ target.symlink_to(Path(*([".."] * (depth + 1)), "blobs", digest))
+
+
+def _hf_repo(hub: Path, repo_id: str, rev: str, files: dict[str, bytes]) -> Path:
+ repo = hub / f"models--{repo_id.replace('/', '--')}"
+ (repo / "refs").mkdir(parents = True, exist_ok = True)
+ (repo / "refs" / "main").write_text(rev, encoding = "utf-8")
+ (repo / "snapshots" / rev).mkdir(parents = True, exist_ok = True)
+ for name, body in files.items():
+ _link(repo, rev, name, _blob(repo, body))
+ return repo
+
+
+_REV1 = "a" * 40
+_REV2 = "b" * 40
+
+
+def hub(monkeypatch, tmp_path):
+ active = tmp_path / "hub"
+ active.mkdir()
+ monkeypatch.setattr(models_route, "_resolve_hf_cache_dir", lambda: active)
+ monkeypatch.setattr("utils.paths.legacy_hf_cache_dir", lambda: tmp_path / "legacy")
+ monkeypatch.setattr("utils.paths.hf_default_cache_dir", lambda: tmp_path / "default")
+ monkeypatch.setattr("utils.paths.lmstudio_model_dirs", lambda: [])
+ monkeypatch.setattr("utils.paths.hermes_model_dirs", lambda: [])
+ monkeypatch.setattr("utils.paths.ollama_model_dirs", lambda: [])
+ monkeypatch.setattr("utils.paths.omlx_model_dirs", lambda: [])
+ monkeypatch.setattr("utils.hf_cache_settings.known_hf_hub_caches", lambda: [active])
+ monkeypatch.setattr("storage.studio_db.list_scan_folders", lambda: [])
+ _hf_repo(
+ active,
+ "org/chat",
+ _REV1,
+ {"config.json": _CONFIG.encode(), "model.safetensors": b"\0" * 64},
+ )
+ _hf_repo(active, "org/tiny-GGUF", _REV1, {"tiny-Q8_0.gguf": b"GGUF" + b"\0" * 60})
+ _hf_repo(
+ active,
+ "org/other",
+ _REV1,
+ {"config.json": _CONFIG.encode(), "model.safetensors": b"\1" * 64},
+ )
+ return active
+
+
+def _scan(models_root: Path) -> list[dict]:
+ rows = asyncio.run(models_route._shared_compat_local_inventory_scan(models_root))
+ return [row.model_dump(mode = "json") for row in rows]
+
+
+def _uncached_scan(models_root: Path, monkeypatch) -> list[dict]:
+ with monkeypatch.context() as m:
+ m.setattr(partial_verdict_cache, "enabled", lambda: False)
+ return _scan(models_root)
+
+
+def _partial(rows: list[dict], model_id: str) -> bool:
+ return next(row for row in rows if row["model_id"] == model_id)["partial"]
+
+
+def _check(models_root: Path, monkeypatch) -> list[dict]:
+ """A cached listing (filled by a first scan, then served) equals an uncached one."""
+ first = _scan(models_root)
+ second = _scan(models_root)
+ reference = _uncached_scan(models_root, monkeypatch)
+ assert first == second == reference
+ return second
+
+
+def test_listing_matches_an_uncached_listing_through_a_download(hub, tmp_path, monkeypatch):
+ models = tmp_path / "models"
+ repo = hub / "models--org--chat"
+ flips: list[bool] = []
+
+ def step(expect: bool) -> None:
+ _settle()
+ rows = _check(models, monkeypatch)
+ assert _partial(rows, "org/chat") is expect
+ assert _partial(rows, "org/other") is False
+ flips.append(expect)
+
+ step(False)
+ # A download starts: its partial blob appears.
+ body = b"\2" * 128
+ digest = hashlib.sha256(body).hexdigest()
+ partial = repo / "blobs" / f"{digest}.incomplete"
+ partial.write_bytes(body[:16])
+ step(True)
+ # It grows in place (no directory entry changes).
+ with partial.open("ab") as handle:
+ handle.write(body[16:64])
+ step(True)
+ # It completes: renamed into place and linked from the snapshot.
+ with partial.open("ab") as handle:
+ handle.write(body[64:])
+ os.replace(partial, repo / "blobs" / digest)
+ _link(repo, _REV1, "extra.safetensors", digest)
+ step(False)
+ # Cancel marker written, then cleared.
+ assert download_manifest.write_cancel_marker("model", "org/chat", None, hub_cache = hub)
+ step(True)
+ download_manifest.clear_cancel_marker("model", "org/chat", None, hub_cache = hub)
+ step(False)
+ # A link repointed at a blob that is not there.
+ link = repo / "snapshots" / _REV1 / "model.safetensors"
+ link.unlink()
+ link.symlink_to(Path("..", "..", "blobs", "0" * 64))
+ step(True)
+ link.unlink()
+ _link(repo, _REV1, "model.safetensors", _blob(repo, b"\0" * 64))
+ step(False)
+ # A repo manifest whose shard is short on disk, then satisfied.
+ expected = [
+ download_manifest.ExpectedFile(path = "config.json", size = len(_CONFIG)),
+ download_manifest.ExpectedFile(path = "model-2.safetensors", size = 32),
+ ]
+ assert download_manifest.write_manifest(
+ "model", "org/chat", None, expected, "http", hub_cache = hub
+ )
+ step(True)
+ _link(repo, _REV1, "model-2.safetensors", _blob(repo, b"\3" * 32))
+ step(False)
+ assert download_manifest.delete_manifest("model", "org/chat", None, hub_cache = hub) is not False
+ step(False)
+ # refs/main rewritten in place (same size) to a commit with no snapshot yet.
+ (repo / "refs" / "main").write_text(_REV2, encoding = "utf-8")
+ _check(models, monkeypatch)
+ # The new snapshot lands.
+ _link(repo, _REV2, "config.json", _blob(repo, _CONFIG.encode()))
+ _link(repo, _REV2, "model.safetensors", _blob(repo, b"\0" * 64))
+ step(False)
+ # The repo is removed.
+ _settle()
+ shutil.rmtree(repo)
+ rows = _check(models, monkeypatch)
+ assert "org/chat" not in {row["model_id"] for row in rows}
+ assert True in flips and False in flips
+
+
+def test_gguf_variant_partial_then_complete(hub, tmp_path, monkeypatch):
+ models = tmp_path / "models"
+ repo = hub / "models--org--tiny-GGUF"
+ _settle()
+ assert _partial(_check(models, monkeypatch), "org/tiny-GGUF") is False
+ # Studio starts a second quant and is cancelled before its file lands.
+ expected = [download_manifest.ExpectedFile(path = "tiny-Q4_K_M.gguf", size = 40)]
+ assert download_manifest.write_manifest(
+ "model", "org/tiny-GGUF", "Q4_K_M", expected, "xet", hub_cache = hub
+ )
+ assert download_manifest.write_cancel_marker("model", "org/tiny-GGUF", "Q4_K_M", hub_cache = hub)
+ _settle()
+ rows = _check(models, monkeypatch)
+ # Q8_0 is whole, so the row stays chattable.
+ assert _partial(rows, "org/tiny-GGUF") is False
+ # The whole quant goes away: only the broken one is left.
+ (repo / "snapshots" / _REV1 / "tiny-Q8_0.gguf").unlink()
+ _settle()
+ assert _partial(_check(models, monkeypatch), "org/tiny-GGUF") is True
+ # The quant completes.
+ download_manifest.clear_cancel_marker("model", "org/tiny-GGUF", "Q4_K_M", hub_cache = hub)
+ _link(repo, _REV1, "tiny-Q4_K_M.gguf", _blob(repo, b"GGUF" + b"\4" * 36))
+ _settle()
+ assert _partial(_check(models, monkeypatch), "org/tiny-GGUF") is False
+
+
+def test_repeat_scan_does_not_rerun_the_partial_checks(hub, tmp_path, monkeypatch):
+ calls: list[str] = []
+ real_snapshot = inventory_scan.is_snapshot_partial
+ real_gguf = inventory_scan.is_gguf_repo_partial
+
+ def snapshot(*args, **kwargs):
+ calls.append("snapshot")
+ return real_snapshot(*args, **kwargs)
+
+ def gguf(*args, **kwargs):
+ calls.append("gguf")
+ return real_gguf(*args, **kwargs)
+
+ monkeypatch.setattr(inventory_scan, "is_snapshot_partial", snapshot)
+ monkeypatch.setattr(inventory_scan, "is_gguf_repo_partial", gguf)
+ _settle()
+ first = _scan(tmp_path / "models")
+ assert calls.count("snapshot") == 3
+ calls.clear()
+ assert _scan(tmp_path / "models") == first
+ assert calls == []
+ # One repo changes: only it is judged again.
+ _settle()
+ (hub / "models--org--chat" / "blobs" / "f.incomplete").write_bytes(b"x")
+ third = _scan(tmp_path / "models")
+ assert calls.count("snapshot") == 1
+ assert _partial(third, "org/chat") is True
+
+
+def test_concurrent_listings_and_writers_settle_on_the_uncached_answer(hub, tmp_path, monkeypatch):
+ models = tmp_path / "models"
+ repo = hub / "models--org--chat"
+ stop = threading.Event()
+ errors: list[BaseException] = []
+
+ def writer() -> None:
+ partial = repo / "blobs" / "c0ffee.incomplete"
+ index = 0
+ while not stop.is_set():
+ try:
+ if index % 2:
+ partial.write_bytes(b"x")
+ download_manifest.write_cancel_marker("model", "org/other", None, hub_cache = hub)
+ else:
+ partial.unlink(missing_ok = True)
+ download_manifest.clear_cancel_marker("model", "org/other", None, hub_cache = hub)
+ except BaseException as exc: # noqa: BLE001 - surfaced below
+ errors.append(exc)
+ return
+ index += 1
+ time.sleep(0.002)
+
+ def lister() -> None:
+ try:
+ for _ in range(6):
+ _scan(models)
+ except BaseException as exc: # noqa: BLE001 - surfaced below
+ errors.append(exc)
+
+ threads = [threading.Thread(target = writer)] + [
+ threading.Thread(target = lister) for _ in range(4)
+ ]
+ for thread in threads:
+ thread.start()
+ for thread in threads[1:]:
+ thread.join()
+ stop.set()
+ threads[0].join()
+ assert not errors
+ _settle()
+ assert _scan(models) == _uncached_scan(models, monkeypatch)
+ for state in (True, False):
+ _settle()
+ if state:
+ (repo / "blobs" / "c0ffee.incomplete").write_bytes(b"x")
+ else:
+ (repo / "blobs" / "c0ffee.incomplete").unlink(missing_ok = True)
+ rows = _check(models, monkeypatch)
+ assert _partial(rows, "org/chat") is state
+
+
+def test_fresh_timestamps_are_not_cached(hub, tmp_path, monkeypatch):
+ monkeypatch.setattr(partial_verdict_cache, "_RACY_NS", 3_000_000_000)
+ _scan(tmp_path / "models")
+ assert len(partial_verdict_cache._entries) == 0
+
+
+def test_a_failed_stat_is_never_cached_or_served(hub, tmp_path, monkeypatch):
+ _settle()
+ _scan(tmp_path / "models")
+ assert len(partial_verdict_cache._entries) == 3
+ loop = tmp_path / "loop"
+ loop.symlink_to(loop)
+ with pytest.raises(partial_verdict_cache._Unstable):
+ partial_verdict_cache._stat(os.fspath(loop))
+ assert partial_verdict_cache._stat(os.fspath(tmp_path / "absent")) is None
+ blobs = os.fspath(hub / "models--org--chat" / "blobs")
+ real_stat = partial_verdict_cache._stat
+
+ def failing_stat(path):
+ if path == blobs:
+ # What _stat makes of an EIO / EACCES / EMFILE: anything but "absent".
+ raise partial_verdict_cache._Unstable from OSError(errno.EIO, "I/O error", path)
+ return real_stat(path)
+
+ monkeypatch.setattr(partial_verdict_cache, "_stat", failing_stat)
+ calls: list[str] = []
+ real_snapshot = inventory_scan.is_snapshot_partial
+
+ def snapshot(*args, **kwargs):
+ calls.append(args[1])
+ return real_snapshot(*args, **kwargs)
+
+ monkeypatch.setattr(inventory_scan, "is_snapshot_partial", snapshot)
+ partial_verdict_cache.invalidate()
+ _scan(tmp_path / "models")
+ # The unreadable repo is judged and not stored; the others are stored.
+ assert "org/chat" in calls
+ assert len(partial_verdict_cache._entries) == 2
+ calls.clear()
+ _scan(tmp_path / "models")
+ assert calls == ["org/chat"]
+
+
+def test_invalidation_drops_every_verdict(hub, tmp_path):
+ _settle()
+ _scan(tmp_path / "models")
+ assert partial_verdict_cache._entries
+ inventory_scan.invalidate_hf_cache_scans()
+ assert not partial_verdict_cache._entries
+ _scan(tmp_path / "models")
+ from core.inference.local_model_resolver import invalidate_index
+
+ invalidate_index()
+ assert not partial_verdict_cache._entries
+
+
+def test_a_linked_directory_in_a_snapshot_is_not_cached(hub, tmp_path):
+ outside = tmp_path / "outside"
+ outside.mkdir()
+ (hub / "models--org--chat" / "snapshots" / _REV1 / "extra").symlink_to(
+ outside, target_is_directory = True
+ )
+ _settle()
+ _scan(tmp_path / "models")
+ keys = {key[1] for key in partial_verdict_cache._entries}
+ assert os.fspath(hub / "models--org--chat") not in keys
+ assert os.fspath(hub / "models--org--other") in keys
+
+
+def test_a_link_to_a_directory_in_blobs_is_not_cached(hub, tmp_path):
+ repo = hub / "models--org--other"
+ (repo / "blobs" / "d").mkdir()
+ _link(repo, _REV1, "nested", "d")
+ _settle()
+ _scan(tmp_path / "models")
+ keys = {key[1] for key in partial_verdict_cache._entries}
+ assert os.fspath(repo) not in keys
+ assert os.fspath(hub / "models--org--chat") in keys
+
+
+def test_a_linked_snapshots_dir_tracks_the_blobs_its_links_reach(hub, tmp_path, monkeypatch):
+ """Relative snapshot links resolve from where snapshots/ really is, not from the repo dir."""
+ models = tmp_path / "models"
+ elsewhere = _hf_repo(
+ tmp_path / "elsewhere",
+ "org/moved",
+ _REV1,
+ {"config.json": _CONFIG.encode(), "model.safetensors": b"\5" * 64},
+ )
+ repo = hub / "models--org--moved"
+ (repo / "refs").mkdir(parents = True)
+ (repo / "refs" / "main").write_text(_REV1, encoding = "utf-8")
+ (repo / "blobs").mkdir()
+ (repo / "snapshots").symlink_to(elsewhere / "snapshots", target_is_directory = True)
+ _settle()
+ rows = _check(models, monkeypatch)
+ assert _partial(rows, "org/moved") is False
+ # The blob the links really reach goes away; nothing under the repo dir itself changes.
+ _settle()
+ (elsewhere / "blobs" / hashlib.sha256(b"\5" * 64).hexdigest()).unlink()
+ rows = _check(models, monkeypatch)
+ assert _partial(rows, "org/moved") is True
+
+
+def _share_blobs(hub: Path, repo: Path) -> list[Path]:
+ """huggingface_hub's shared store: each repo blob becomes a relative link to <hub>/blobs/<xx>/<hash>."""
+ stored = []
+ for blob in sorted((repo / "blobs").iterdir()):
+ target = hub / "blobs" / blob.name[:2] / blob.name
+ target.parent.mkdir(parents = True, exist_ok = True)
+ os.replace(blob, target)
+ blob.symlink_to(Path("..", "..", "blobs", blob.name[:2], blob.name))
+ stored.append(target)
+ return stored
+
+
+def test_shared_store_blobs_are_cached_and_tracked(hub, tmp_path, monkeypatch):
+ models = tmp_path / "models"
+ stored = _share_blobs(hub, hub / "models--org--chat")
+ _settle()
+ rows = _check(models, monkeypatch)
+ assert _partial(rows, "org/chat") is False
+ keys = {key[1] for key in partial_verdict_cache._entries}
+ assert os.fspath(hub / "models--org--chat") in keys
+ # Another repo's delete sweeps a store file: the link chain now dangles.
+ _settle()
+ weight = next(p for p in stored if p.name == hashlib.sha256(b"\0" * 64).hexdigest())
+ weight.unlink()
+ rows = _check(models, monkeypatch)
+ assert _partial(rows, "org/chat") is True
+ # Published again in place.
+ _settle()
+ weight.write_bytes(b"\0" * 64)
+ rows = _check(models, monkeypatch)
+ assert _partial(rows, "org/chat") is False
+
+
+def test_shared_store_blobs_resolve_from_the_real_repo_dir(hub, tmp_path, monkeypatch):
+ """A repo dir linked in from another disk: its blob links reach that disk's store, not the hub's."""
+ models = tmp_path / "models"
+ disk = tmp_path / "disk2"
+ disk.mkdir()
+ real_repo = disk / "models--org--chat"
+ os.replace(hub / "models--org--chat", real_repo)
+ (hub / "models--org--chat").symlink_to(real_repo, target_is_directory = True)
+ stored = _share_blobs(disk, real_repo)
+ # A same-named decoy in the hub's own store, which the links do not reach.
+ for path in stored:
+ decoy = hub / "blobs" / path.parent.name / path.name
+ decoy.parent.mkdir(parents = True, exist_ok = True)
+ decoy.write_bytes(path.read_bytes())
+ _settle()
+ rows = _check(models, monkeypatch)
+ assert _partial(rows, "org/chat") is False
+ _settle()
+ next(p for p in stored if p.name == hashlib.sha256(b"\0" * 64).hexdigest()).unlink()
+ rows = _check(models, monkeypatch)
+ assert _partial(rows, "org/chat") is True
+
+
+def test_cache_is_bounded(hub, tmp_path, monkeypatch):
+ monkeypatch.setattr(partial_verdict_cache, "_MAX_ENTRIES", 2)
+ _settle()
+ _scan(tmp_path / "models")
+ assert len(partial_verdict_cache._entries) == 2
+
+
+def test_only_trusted_filesystems_are_cached(hub, tmp_path, monkeypatch):
+ monkeypatch.setattr(partial_verdict_cache, "_trusted_devices", _REAL_TRUSTED_DEVICES)
+ real = partial_verdict_cache._mount_fs_types
+ dev = os.stat(hub).st_dev
+ key = (os.major(dev), os.minor(dev))
+ for fs_type, cached in (
+ ("vfat", False),
+ ("fuse.rclone", False),
+ ("nfs4", False),
+ ("ext4", True),
+ ):
+ partial_verdict_cache.invalidate()
+
+ def types(fs_type = fs_type):
+ found = real()
+ found[key] = {fs_type}
+ return found
+
+ with monkeypatch.context() as m:
+ m.setattr(partial_verdict_cache, "_mount_fs_types", types)
+ _settle()
+ _scan(tmp_path / "models")
+ assert bool(partial_verdict_cache._entries) is cached, fs_type
diff --git a/studio/backend/tests/test_partial_verdict_cache_off_linux.py b/studio/backend/tests/test_partial_verdict_cache_off_linux.py
new file mode 100644
index 00000000000..df15d58ccbb
--- /dev/null
+++ b/studio/backend/tests/test_partial_verdict_cache_off_linux.py
@@ -0,0 +1,31 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Runs on every platform: off Linux the partial verdict cache stays out of the way."""
+
+from __future__ import annotations
+
+import sys
+
+from hub.utils import partial_verdict_cache
+from utils.scan_memo import scan_memo
+
+
+def test_enabled_only_on_linux():
+ assert partial_verdict_cache.enabled() is sys.platform.startswith("linux")
+
+
+def test_when_disabled_every_call_computes_and_nothing_is_stored(tmp_path, monkeypatch):
+ monkeypatch.setattr(partial_verdict_cache, "enabled", lambda: False)
+ partial_verdict_cache.invalidate()
+ calls = []
+
+ def compute():
+ calls.append(1)
+ return len(calls) % 2 == 0
+
+ with scan_memo():
+ answers = [partial_verdict_cache.cached_verdict("k", tmp_path, compute) for _ in range(4)]
+ assert answers == [False, True, False, True]
+ assert len(calls) == 4
+ assert not partial_verdict_cache._entries