step 2: add thread safe state commands and cache model

tests/test_cache.py

@@ -2,7 +2,15 @@ from __future__ import annotations
 
 from pathlib import Path
 
-from dpg_map.cache import CacheStats, DiskCacheConfig, MemoryCacheConfig
+from dpg_map.cache import (
+    CacheStats,
+    DiskCacheConfig,
+    DiskCacheMetadata,
+    MemoryCacheConfig,
+    plan_disk_prune,
+    tile_cache_path,
+    write_disk_metadata,
+)
 
 
 def test_cache_stats_dataclass_construction() -> None:
@@ -29,3 +37,32 @@ def test_initial_cache_config_dataclasses() -> None:
 
     assert memory_config.max_tiles == 512
     assert disk_config.max_bytes == 2_000_000_000
+
+
+def test_disk_cache_path_generation(tmp_path: Path) -> None:
+    path = tile_cache_path(tmp_path, "osm", 4, 8, 9, "jpg")
+
+    assert path == tmp_path / "osm" / "4" / "8" / "9.jpg"
+
+
+def test_disk_cache_prune_ordering(tmp_path: Path) -> None:
+    first = tile_cache_path(tmp_path, "osm", 1, 1, 1)
+    second = tile_cache_path(tmp_path, "osm", 1, 1, 2)
+    protected = tile_cache_path(tmp_path, "osm", 1, 1, 3)
+
+    for path, accessed_at in [(first, 1.0), (second, 2.0), (protected, 0.0)]:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_bytes(b"abcde")
+        write_disk_metadata(
+            path.with_suffix(".json"),
+            DiskCacheMetadata(
+                url=str(path),
+                downloaded_at=accessed_at,
+                last_accessed_at=accessed_at,
+                size_bytes=5,
+            ),
+        )
+
+    planned = plan_disk_prune(tmp_path, 5, protected_paths={protected})
+
+    assert planned == [first, second]