feat(models): hf cache mirror (hardlink blobs, preserve snapshot symlinks, copy refs)

models.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 
 import os
 from dataclasses import dataclass, field
+from pathlib import Path
 from typing import Any
 
 # Avoid importing torch at module load — keeps `import models` fast in CI.
@@ -94,3 +95,54 @@ def build_diffsynth_configs(
         DSConfig(model_id=c.model_id, origin_file_pattern=c.origin_file_pattern, **(vram_cfg or {}))
         for c in configs
     ]
+
+
+def mirror_preload_hf_cache(src_root: Path | str, dst_root: Path | str) -> None:
+    """Mirror a read-only HF cache tree (preload_from_hub) into a writable tree.
+
+    - ``blobs/<sha>`` files -> **hardlinked** (zero-copy, shared inode).
+    - ``snapshots/<commit>/...`` symlinks -> **preserved** with original relative target.
+    - ``refs/<branch>`` files -> **byte-copied** (HF lib overwrites on etag check).
+    - Directories -> ``mkdir`` so the runtime user owns them.
+
+    Falls back to ``symlink`` when ``os.link()`` raises EXDEV (cross-device).
+    """
+    import errno
+    import shutil
+
+    src_root = Path(src_root)
+    dst_root = Path(dst_root)
+
+    if not (src_root / "hub").exists():
+        return  # nothing preloaded -- no-op
+
+    for src_dir, _, files in os.walk(src_root / "hub"):
+        rel = Path(src_dir).relative_to(src_root)
+        dst_dir = dst_root / rel
+        dst_dir.mkdir(parents=True, exist_ok=True)
+
+        for name in files:
+            src_path = Path(src_dir) / name
+            dst_path = dst_dir / name
+            if dst_path.exists():
+                continue
+
+            # Refs get byte-copied
+            if "refs/" in str(rel).replace("\\", "/"):
+                shutil.copy2(src_path, dst_path)
+                continue
+
+            # Symlinks (snapshot files) preserve their relative target
+            if src_path.is_symlink():
+                target = os.readlink(src_path)
+                dst_path.symlink_to(target)
+                continue
+
+            # Regular files (blobs) hardlink with EXDEV fallback
+            try:
+                os.link(src_path, dst_path)
+            except OSError as e:
+                if e.errno == errno.EXDEV:
+                    dst_path.symlink_to(src_path)
+                else:
+                    raise

tests/test_models.py

@@ -36,3 +36,55 @@ def test_vram_limit_for_mps_is_unified_memory_aware():
 
 def test_vram_limit_for_cpu_is_zero():
     assert models.vram_limit_for("cpu", free_gb=64.0) == 0.0
+
+
+def test_mirror_hardlinks_blobs(tmp_path):
+    """Blobs (content-addressed files) get hardlinked into the mirror."""
+    src = tmp_path / "src" / "hub"
+    dst = tmp_path / "rw"
+    blob_dir = src / "blobs"
+    blob_dir.mkdir(parents=True)
+    blob = blob_dir / "abcdef"
+    blob.write_bytes(b"hello")
+
+    models.mirror_preload_hf_cache(src.parent, dst)
+
+    mirrored = dst / "hub" / "blobs" / "abcdef"
+    assert mirrored.exists()
+    assert mirrored.stat().st_ino == blob.stat().st_ino, "should be hardlinked"
+
+
+def test_mirror_preserves_snapshot_symlinks(tmp_path):
+    """Snapshot symlinks point at relative blob paths -- preserve as-is."""
+    src = tmp_path / "src" / "hub"
+    dst = tmp_path / "rw"
+    (src / "blobs").mkdir(parents=True)
+    blob = src / "blobs" / "abc"
+    blob.write_bytes(b"content")
+    snap_dir = src / "snapshots" / "v1"
+    snap_dir.mkdir(parents=True)
+    link = snap_dir / "model.safetensors"
+    link.symlink_to("../../blobs/abc")
+
+    models.mirror_preload_hf_cache(src.parent, dst)
+
+    mirrored_link = dst / "hub" / "snapshots" / "v1" / "model.safetensors"
+    assert mirrored_link.is_symlink()
+    target = os.readlink(mirrored_link)
+    assert target == "../../blobs/abc"
+
+
+def test_mirror_byte_copies_refs(tmp_path):
+    """Refs are rewritten by HF lib on etag; must be a real copy, not hardlink."""
+    src = tmp_path / "src" / "hub"
+    dst = tmp_path / "rw"
+    refs_dir = src / "refs" / "main"
+    refs_dir.mkdir(parents=True)
+    ref = refs_dir / "v1"
+    ref.write_text("commit-sha\n")
+
+    models.mirror_preload_hf_cache(src.parent, dst)
+
+    mirrored_ref = dst / "hub" / "refs" / "main" / "v1"
+    assert mirrored_ref.read_text() == "commit-sha\n"
+    assert mirrored_ref.stat().st_ino != ref.stat().st_ino, "must be a real copy"