fix: enforce LRU eviction for _cache_locate_site_class (fixes #1276)

The _cache_locate_site_class dict could grow without bound because the
existing _LOCATE_SITE_CLASS_CACHE_MAXSIZE constant was never enforced
with true LRU semantics on cache hits.

Changes:
- Replace plain dict with collections.OrderedDict for insertion-order
  tracking plus O(1) move_to_end.
- On cache hit, call move_to_end(key) to promote the entry to
  most-recently-used, ensuring frequently accessed entries survive
  eviction.
- Eviction (already present as FIFO) now correctly evicts the
  *least*-recently-used entry thanks to OrderedDict ordering.
- Add test_locate_site_class_cache_lru_eviction() to verify:
  - Cache size never exceeds maxsize
  - Recently accessed keys survive eviction (LRU promotion)
  - Least-recently-used keys are evicted first

This is consistent with the lru_cache pattern used for _cached_snp_calls
and the prior fix for unbounded caching in veff.py (#1189).

Author: khushthecoder

malariagen_data/anoph/snp_data.py

@@ -1,4 +1,5 @@
 import warnings
+from collections import OrderedDict
 from functools import lru_cache
 from typing import Any, Dict, List, Optional, Tuple, Union
 
@@ -75,7 +76,9 @@ def __init__(
             base_params.site_mask, zarr.hierarchy.Group
         ] = dict()
         self._cache_site_annotations: Optional[zarr.hierarchy.Group] = None
-        self._cache_locate_site_class: Dict[Tuple[Any, ...], np.ndarray] = dict()
+        self._cache_locate_site_class: OrderedDict[
+            Tuple[Any, ...], np.ndarray
+        ] = OrderedDict()
 
         # Create the SNP-calls cache as a per-instance lru_cache wrapping the
         # bound method.  Storing it on the instance (rather than using a
@@ -798,6 +801,9 @@ def _locate_site_class(
 
         try:
             loc_ann = self._cache_locate_site_class[cache_key]
+            # Promote to most-recently-used so the LRU eviction below
+            # always removes the *least*-recently-used entry.
+            self._cache_locate_site_class.move_to_end(cache_key)
 
         except KeyError as exc:
             # Access site annotations data.
@@ -943,9 +949,10 @@ def _locate_site_class(
 
             self._cache_locate_site_class[cache_key] = loc_ann
 
-            # Evict the oldest entry when the cache exceeds its size limit.
-            # Plain dicts preserve insertion order (Python 3.7+), so the first
-            # key is always the oldest.
+            # Evict the least-recently-used entry when the cache exceeds its
+            # size limit.  Because the cache is an OrderedDict and both hits
+            # (move_to_end above) and inserts append to the right, the first
+            # key is always the *least*-recently-used entry.
             while len(self._cache_locate_site_class) > _LOCATE_SITE_CLASS_CACHE_MAXSIZE:
                 oldest = next(iter(self._cache_locate_site_class))
                 del self._cache_locate_site_class[oldest]

tests/anoph/test_snp_data.py

@@ -973,6 +973,64 @@ def test_locate_site_class_cache_is_bounded(ag3_sim_api: AnophelesSnpData):
     assert len(ag3_sim_api._cache_locate_site_class) <= _LOCATE_SITE_CLASS_CACHE_MAXSIZE
 
 
+def test_locate_site_class_cache_lru_eviction(ag3_sim_api: AnophelesSnpData):
+    """Verify true LRU semantics: recently *accessed* entries survive eviction,
+    while least-recently-used entries are evicted first."""
+    from collections import OrderedDict
+
+    from malariagen_data.anoph.snp_data import _LOCATE_SITE_CLASS_CACHE_MAXSIZE
+
+    cache = ag3_sim_api._cache_locate_site_class
+
+    # Start from a clean cache.
+    cache.clear()
+    assert isinstance(cache, OrderedDict)
+
+    maxsize = _LOCATE_SITE_CLASS_CACHE_MAXSIZE  # 64
+
+    # --- Phase 1: fill the cache to exactly maxsize ---
+    dummy = np.array([True, False])
+    for i in range(maxsize):
+        key = (f"contig_{i}", f"mask_{i}", f"class_{i}")
+        cache[key] = dummy
+    assert len(cache) == maxsize
+
+    # Remember the first key inserted (the oldest / least-recently-used).
+    first_key = ("contig_0", "mask_0", "class_0")
+    assert first_key in cache
+
+    # --- Phase 2: simulate an access (LRU promotion) on the first key ---
+    # move_to_end makes it the most-recently-used entry.
+    cache.move_to_end(first_key)
+
+    # Insert one more entry, exceeding maxsize.
+    overflow_key = ("overflow", "mask", "class")
+    cache[overflow_key] = dummy
+
+    # Evict to maintain the bound (same logic as _locate_site_class).
+    while len(cache) > maxsize:
+        oldest = next(iter(cache))
+        del cache[oldest]
+
+    # The first key should STILL be present because it was promoted.
+    assert (
+        first_key in cache
+    ), "LRU promotion via move_to_end must keep recently accessed entries alive"
+
+    # The second key ("contig_1", ...) — which was never re-accessed —
+    # should have been evicted as the new least-recently-used entry.
+    second_key = ("contig_1", "mask_1", "class_1")
+    assert (
+        second_key not in cache
+    ), "The least-recently-used entry should be evicted when cache exceeds maxsize"
+
+    # The overflow key should be present (it was just inserted).
+    assert overflow_key in cache
+
+    # Cache size must remain bounded.
+    assert len(cache) == maxsize
+
+
 def test_snp_calls_cache_is_per_instance(ag3_sim_api: AnophelesSnpData):
     """_cached_snp_calls must be a per-instance lru_cache, not a class-level one.