tnfr 6.0.0__py3-none-any.whl → 7.0.0__py3-none-any.whl

tnfr/utils/cache.py

@@ -1,15 +1,19 @@
-"""Core caching utilities shared across TNFR helpers.
+"""Cache infrastructure primitives and graph-level helpers for TNFR.
 
 This module consolidates structural cache helpers that previously lived in
-``tnfr.helpers.cache_utils`` and ``tnfr.helpers.edge_cache``.  The functions
-exposed here are responsible for maintaining deterministic node digests,
-scoped graph caches guarded by locks, and version counters that keep edge
-artifacts in sync with ΔNFR driven updates.
+legacy helper modules and are now exposed under :mod:`tnfr.utils`. The
+functions exposed here are responsible for maintaining deterministic node
+digests, scoped graph caches guarded by locks, and version counters that keep
+edge artifacts in sync with ΔNFR driven updates.
 """
 
 from __future__ import annotations
 
+from abc import ABC, abstractmethod
 import hashlib
+import logging
+import pickle
+import shelve
 import threading
 from collections import defaultdict
 from collections.abc import (
@@ -21,22 +25,33 @@ from collections.abc import (
     MutableMapping,
 )
 from contextlib import contextmanager
+from dataclasses import dataclass, field
 from functools import lru_cache
-from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, TypeVar, cast
+from time import perf_counter
+from typing import TYPE_CHECKING, Any, Generic, TypeVar, cast
 
-from cachetools import LRUCache
 import networkx as nx
+from cachetools import LRUCache
 
-from ..cache import CacheCapacityConfig, CacheManager, InstrumentedLRUCache
-from ..types import GraphLike, NodeId, TNFRGraph, TimingContext
+from ..locking import get_lock
+from ..types import GraphLike, NodeId, TimingContext, TNFRGraph
 from .graph import get_graph, mark_dnfr_prep_dirty
-from .init import get_logger, get_numpy
-from .io import json_dumps
 
+K = TypeVar("K", bound=Hashable)
+V = TypeVar("V")
 T = TypeVar("T")
 
 __all__ = (
+    "CacheLayer",
+    "CacheManager",
+    "CacheCapacityConfig",
+    "CacheStatistics",
+    "InstrumentedLRUCache",
+    "ManagedLRUCache",
+    "MappingCacheLayer",
+    "RedisCacheLayer",
+    "ShelveCacheLayer",
+    "prune_lock_mapping",
     "EdgeCacheManager",
     "NODE_SET_CHECKSUM_KEY",
     "cached_node_list",
@@ -54,15 +69,1163 @@ __all__ = (
     "configure_graph_cache_limits",
     "DNFR_PREP_STATE_KEY",
     "DnfrPrepState",
+    "build_cache_manager",
+    "configure_global_cache_layers",
+    "reset_global_cache_manager",
+    "_GRAPH_CACHE_LAYERS_KEY",
+    "_SeedHashCache",
+    "ScopedCounterCache",
+    "DnfrCache",
+    "new_dnfr_cache",
 )
 
-if TYPE_CHECKING:  # pragma: no cover - typing aide
-    from ..dynamics.dnfr import DnfrCache
+@dataclass(frozen=True)
+class CacheCapacityConfig:
+    """Configuration snapshot for cache capacity policies."""
+
+    default_capacity: int | None
+    overrides: dict[str, int | None]
+
+
+@dataclass(frozen=True)
+class CacheStatistics:
+    """Immutable snapshot of cache telemetry counters."""
+
+    hits: int = 0
+    misses: int = 0
+    evictions: int = 0
+    total_time: float = 0.0
+    timings: int = 0
+
+    def merge(self, other: CacheStatistics) -> CacheStatistics:
+        """Return aggregated metrics combining ``self`` and ``other``."""
+
+        return CacheStatistics(
+            hits=self.hits + other.hits,
+            misses=self.misses + other.misses,
+            evictions=self.evictions + other.evictions,
+            total_time=self.total_time + other.total_time,
+            timings=self.timings + other.timings,
+        )
+
+
+@dataclass
+class DnfrCache:
+    idx: dict[Any, int]
+    theta: list[float]
+    epi: list[float]
+    vf: list[float]
+    cos_theta: list[float]
+    sin_theta: list[float]
+    neighbor_x: list[float]
+    neighbor_y: list[float]
+    neighbor_epi_sum: list[float]
+    neighbor_vf_sum: list[float]
+    neighbor_count: list[float]
+    neighbor_deg_sum: list[float] | None
+    th_bar: list[float] | None = None
+    epi_bar: list[float] | None = None
+    vf_bar: list[float] | None = None
+    deg_bar: list[float] | None = None
+    degs: dict[Any, float] | None = None
+    deg_list: list[float] | None = None
+    theta_np: Any | None = None
+    epi_np: Any | None = None
+    vf_np: Any | None = None
+    cos_theta_np: Any | None = None
+    sin_theta_np: Any | None = None
+    deg_array: Any | None = None
+    edge_src: Any | None = None
+    edge_dst: Any | None = None
+    checksum: Any | None = None
+    neighbor_x_np: Any | None = None
+    neighbor_y_np: Any | None = None
+    neighbor_epi_sum_np: Any | None = None
+    neighbor_vf_sum_np: Any | None = None
+    neighbor_count_np: Any | None = None
+    neighbor_deg_sum_np: Any | None = None
+    th_bar_np: Any | None = None
+    epi_bar_np: Any | None = None
+    vf_bar_np: Any | None = None
+    deg_bar_np: Any | None = None
+    grad_phase_np: Any | None = None
+    grad_epi_np: Any | None = None
+    grad_vf_np: Any | None = None
+    grad_topo_np: Any | None = None
+    grad_total_np: Any | None = None
+    dense_components_np: Any | None = None
+    dense_accum_np: Any | None = None
+    dense_degree_np: Any | None = None
+    neighbor_accum_np: Any | None = None
+    neighbor_inv_count_np: Any | None = None
+    neighbor_cos_avg_np: Any | None = None
+    neighbor_sin_avg_np: Any | None = None
+    neighbor_mean_tmp_np: Any | None = None
+    neighbor_mean_length_np: Any | None = None
+    edge_signature: Any | None = None
+    neighbor_accum_signature: Any | None = None
+    neighbor_edge_values_np: Any | None = None
+
+
+def new_dnfr_cache() -> DnfrCache:
+    """Return an empty :class:`DnfrCache` prepared for ΔNFR orchestration."""
+
+    return DnfrCache(
+        idx={},
+        theta=[],
+        epi=[],
+        vf=[],
+        cos_theta=[],
+        sin_theta=[],
+        neighbor_x=[],
+        neighbor_y=[],
+        neighbor_epi_sum=[],
+        neighbor_vf_sum=[],
+        neighbor_count=[],
+        neighbor_deg_sum=[],
+    )
+
+
+@dataclass
+class _CacheMetrics:
+    hits: int = 0
+    misses: int = 0
+    evictions: int = 0
+    total_time: float = 0.0
+    timings: int = 0
+    lock: threading.Lock = field(default_factory=threading.Lock, repr=False)
+
+    def snapshot(self) -> CacheStatistics:
+        return CacheStatistics(
+            hits=self.hits,
+            misses=self.misses,
+            evictions=self.evictions,
+            total_time=self.total_time,
+            timings=self.timings,
+        )
+
+
+@dataclass
+class _CacheEntry:
+    factory: Callable[[], Any]
+    lock: threading.Lock
+    reset: Callable[[Any], Any] | None = None
+    encoder: Callable[[Any], Any] | None = None
+    decoder: Callable[[Any], Any] | None = None
+
+
+class CacheLayer(ABC):
+    """Abstract interface implemented by storage backends orchestrated by :class:`CacheManager`."""
+
+    @abstractmethod
+    def load(self, name: str) -> Any:
+        """Return the stored payload for ``name`` or raise :class:`KeyError`."""
+
+    @abstractmethod
+    def store(self, name: str, value: Any) -> None:
+        """Persist ``value`` under ``name``."""
+
+    @abstractmethod
+    def delete(self, name: str) -> None:
+        """Remove ``name`` from the backend if present."""
+
+    @abstractmethod
+    def clear(self) -> None:
+        """Remove every entry maintained by the layer."""
+
+    def close(self) -> None:  # pragma: no cover - optional hook
+        """Release resources held by the backend."""
+
+
+class MappingCacheLayer(CacheLayer):
+    """In-memory cache layer backed by a mutable mapping."""
+
+    def __init__(self, storage: MutableMapping[str, Any] | None = None) -> None:
+        self._storage: MutableMapping[str, Any] = {} if storage is None else storage
+        self._lock = threading.RLock()
+
+    @property
+    def storage(self) -> MutableMapping[str, Any]:
+        """Return the mapping used to store cache entries."""
+
+        return self._storage
+
+    def load(self, name: str) -> Any:
+        with self._lock:
+            if name not in self._storage:
+                raise KeyError(name)
+            return self._storage[name]
+
+    def store(self, name: str, value: Any) -> None:
+        with self._lock:
+            self._storage[name] = value
+
+    def delete(self, name: str) -> None:
+        with self._lock:
+            self._storage.pop(name, None)
+
+    def clear(self) -> None:
+        with self._lock:
+            self._storage.clear()
+
+
+class ShelveCacheLayer(CacheLayer):
+    """Persistent cache layer backed by :mod:`shelve`."""
+
+    def __init__(
+        self,
+        path: str,
+        *,
+        flag: str = "c",
+        protocol: int | None = None,
+        writeback: bool = False,
+    ) -> None:
+        self._path = path
+        self._flag = flag
+        self._protocol = pickle.HIGHEST_PROTOCOL if protocol is None else protocol
+        self._shelf = shelve.open(path, flag=flag, protocol=self._protocol, writeback=writeback)
+        self._lock = threading.RLock()
+
+    def load(self, name: str) -> Any:
+        with self._lock:
+            if name not in self._shelf:
+                raise KeyError(name)
+            return self._shelf[name]
+
+    def store(self, name: str, value: Any) -> None:
+        with self._lock:
+            self._shelf[name] = value
+            self._shelf.sync()
+
+    def delete(self, name: str) -> None:
+        with self._lock:
+            try:
+                del self._shelf[name]
+            except KeyError:
+                return
+            self._shelf.sync()
+
+    def clear(self) -> None:
+        with self._lock:
+            self._shelf.clear()
+            self._shelf.sync()
+
+    def close(self) -> None:  # pragma: no cover - exercised indirectly
+        with self._lock:
+            self._shelf.close()
+
+
+class RedisCacheLayer(CacheLayer):
+    """Distributed cache layer backed by a Redis client."""
+
+    def __init__(self, client: Any | None = None, *, namespace: str = "tnfr:cache") -> None:
+        if client is None:
+            try:  # pragma: no cover - import guarded for optional dependency
+                import redis  # type: ignore
+            except Exception as exc:  # pragma: no cover - defensive import
+                raise RuntimeError("redis-py is required to initialise RedisCacheLayer") from exc
+            client = redis.Redis()
+        self._client = client
+        self._namespace = namespace.rstrip(":") or "tnfr:cache"
+        self._lock = threading.RLock()
+
+    def _format_key(self, name: str) -> str:
+        return f"{self._namespace}:{name}"
+
+    def load(self, name: str) -> Any:
+        key = self._format_key(name)
+        with self._lock:
+            value = self._client.get(key)
+        if value is None:
+            raise KeyError(name)
+        if isinstance(value, (bytes, bytearray, memoryview)):
+            return pickle.loads(bytes(value))
+        return value
+
+    def store(self, name: str, value: Any) -> None:
+        key = self._format_key(name)
+        payload = value
+        if not isinstance(value, (bytes, bytearray, memoryview)):
+            payload = pickle.dumps(value, protocol=pickle.HIGHEST_PROTOCOL)
+        with self._lock:
+            self._client.set(key, payload)
+
+    def delete(self, name: str) -> None:
+        key = self._format_key(name)
+        with self._lock:
+            self._client.delete(key)
+
+    def clear(self) -> None:
+        pattern = f"{self._namespace}:*"
+        with self._lock:
+            if hasattr(self._client, "scan_iter"):
+                keys = list(self._client.scan_iter(match=pattern))
+            elif hasattr(self._client, "keys"):
+                keys = list(self._client.keys(pattern))
+            else:  # pragma: no cover - extremely defensive
+                keys = []
+            if keys:
+                self._client.delete(*keys)
+
+
+class CacheManager:
+    """Coordinate named caches guarded by per-entry locks."""
+
+    _MISSING = object()
+
+    def __init__(
+        self,
+        storage: MutableMapping[str, Any] | None = None,
+        *,
+        default_capacity: int | None = None,
+        overrides: Mapping[str, int | None] | None = None,
+        layers: Iterable[CacheLayer] | None = None,
+    ) -> None:
+        mapping_layer = MappingCacheLayer(storage)
+        extra_layers: tuple[CacheLayer, ...]
+        if layers is None:
+            extra_layers = ()
+        else:
+            extra_layers = tuple(layers)
+            for layer in extra_layers:
+                if not isinstance(layer, CacheLayer):  # pragma: no cover - defensive typing
+                    raise TypeError(f"unsupported cache layer type: {type(layer)!r}")
+        self._layers: tuple[CacheLayer, ...] = (mapping_layer, *extra_layers)
+        self._storage_layer = mapping_layer
+        self._storage: MutableMapping[str, Any] = mapping_layer.storage
+        self._entries: dict[str, _CacheEntry] = {}
+        self._registry_lock = threading.RLock()
+        self._default_capacity = self._normalise_capacity(default_capacity)
+        self._capacity_overrides: dict[str, int | None] = {}
+        self._metrics: dict[str, _CacheMetrics] = {}
+        self._metrics_publishers: list[Callable[[str, CacheStatistics], None]] = []
+        if overrides:
+            self.configure(overrides=overrides)
+
+    @staticmethod
+    def _normalise_capacity(value: int | None) -> int | None:
+        if value is None:
+            return None
+        size = int(value)
+        if size < 0:
+            raise ValueError("capacity must be non-negative or None")
+        return size
+
+    def register(
+        self,
+        name: str,
+        factory: Callable[[], Any],
+        *,
+        lock_factory: Callable[[], threading.Lock | threading.RLock] | None = None,
+        reset: Callable[[Any], Any] | None = None,
+        create: bool = True,
+        encoder: Callable[[Any], Any] | None = None,
+        decoder: Callable[[Any], Any] | None = None,
+    ) -> None:
+        """Register ``name`` with ``factory`` and optional lifecycle hooks."""
+
+        if lock_factory is None:
+            lock_factory = threading.RLock
+        with self._registry_lock:
+            entry = self._entries.get(name)
+            if entry is None:
+                entry = _CacheEntry(
+                    factory=factory,
+                    lock=lock_factory(),
+                    reset=reset,
+                    encoder=encoder,
+                    decoder=decoder,
+                )
+                self._entries[name] = entry
+            else:
+                # Update hooks when re-registering the same cache name.
+                entry.factory = factory
+                entry.reset = reset
+                entry.encoder = encoder
+                entry.decoder = decoder
+            self._ensure_metrics(name)
+        if create:
+            self.get(name)
+
+    def configure(
+        self,
+        *,
+        default_capacity: int | None | object = _MISSING,
+        overrides: Mapping[str, int | None] | None = None,
+        replace_overrides: bool = False,
+    ) -> None:
+        """Update the cache capacity policy shared by registered entries."""
+
+        with self._registry_lock:
+            if default_capacity is not self._MISSING:
+                self._default_capacity = self._normalise_capacity(
+                    default_capacity if default_capacity is not None else None
+                )
+            if overrides is not None:
+                if replace_overrides:
+                    self._capacity_overrides.clear()
+                for key, value in overrides.items():
+                    self._capacity_overrides[key] = self._normalise_capacity(value)
+
+    def configure_from_mapping(self, config: Mapping[str, Any]) -> None:
+        """Load configuration produced by :meth:`export_config`."""
+
+        default = config.get("default_capacity", self._MISSING)
+        overrides = config.get("overrides")
+        overrides_mapping: Mapping[str, int | None] | None
+        overrides_mapping = overrides if isinstance(overrides, Mapping) else None
+        self.configure(default_capacity=default, overrides=overrides_mapping)
+
+    def export_config(self) -> CacheCapacityConfig:
+        """Return a copy of the current capacity configuration."""
+
+        with self._registry_lock:
+            return CacheCapacityConfig(
+                default_capacity=self._default_capacity,
+                overrides=dict(self._capacity_overrides),
+            )
+
+    def get_capacity(
+        self,
+        name: str,
+        *,
+        requested: int | None = None,
+        fallback: int | None = None,
+        use_default: bool = True,
+    ) -> int | None:
+        """Return capacity for ``name`` considering overrides and defaults."""
+
+        with self._registry_lock:
+            override = self._capacity_overrides.get(name, self._MISSING)
+            default = self._default_capacity
+        if override is not self._MISSING:
+            return override
+        values: tuple[int | None, ...]
+        if use_default:
+            values = (requested, default, fallback)
+        else:
+            values = (requested, fallback)
+        for value in values:
+            if value is self._MISSING:
+                continue
+            normalised = self._normalise_capacity(value)
+            if normalised is not None:
+                return normalised
+        return None
+
+    def has_override(self, name: str) -> bool:
+        """Return ``True`` if ``name`` has an explicit capacity override."""
+
+        with self._registry_lock:
+            return name in self._capacity_overrides
+
+    def get_lock(self, name: str) -> threading.Lock | threading.RLock:
+        """Return the lock guarding cache ``name`` for external coordination."""
+
+        entry = self._entries.get(name)
+        if entry is None:
+            raise KeyError(name)
+        return entry.lock
+
+    def names(self) -> Iterator[str]:
+        """Iterate over registered cache names."""
+
+        with self._registry_lock:
+            return iter(tuple(self._entries))
+
+    def get(self, name: str, *, create: bool = True) -> Any:
+        """Return cache ``name`` creating it on demand when ``create`` is true."""
+
+        entry = self._entries.get(name)
+        if entry is None:
+            raise KeyError(name)
+        with entry.lock:
+            value = self._load_from_layers(name, entry)
+            if create and value is None:
+                value = entry.factory()
+                self._persist_layers(name, entry, value)
+            return value
+
+    def peek(self, name: str) -> Any:
+        """Return cache ``name`` without creating a missing entry."""
+
+        entry = self._entries.get(name)
+        if entry is None:
+            raise KeyError(name)
+        with entry.lock:
+            return self._load_from_layers(name, entry)
+
+    def store(self, name: str, value: Any) -> None:
+        """Replace the stored value for cache ``name`` with ``value``."""
+
+        entry = self._entries.get(name)
+        if entry is None:
+            raise KeyError(name)
+        with entry.lock:
+            self._persist_layers(name, entry, value)
+
+    def update(
+        self,
+        name: str,
+        updater: Callable[[Any], Any],
+        *,
+        create: bool = True,
+    ) -> Any:
+        """Apply ``updater`` to cache ``name`` storing the resulting value."""
+
+        entry = self._entries.get(name)
+        if entry is None:
+            raise KeyError(name)
+        with entry.lock:
+            current = self._load_from_layers(name, entry)
+            if create and current is None:
+                current = entry.factory()
+            new_value = updater(current)
+            self._persist_layers(name, entry, new_value)
+            return new_value
+
+    def clear(self, name: str | None = None) -> None:
+        """Reset caches either selectively or for every registered name."""
+
+        if name is not None:
+            names = (name,)
+        else:
+            with self._registry_lock:
+                names = tuple(self._entries)
+        for cache_name in names:
+            entry = self._entries.get(cache_name)
+            if entry is None:
+                continue
+            with entry.lock:
+                current = self._load_from_layers(cache_name, entry)
+                new_value = None
+                if entry.reset is not None:
+                    try:
+                        new_value = entry.reset(current)
+                    except Exception:  # pragma: no cover - defensive logging
+                        _logger.exception("cache reset failed for %s", cache_name)
+                if new_value is None:
+                    try:
+                        new_value = entry.factory()
+                    except Exception:
+                        self._delete_from_layers(cache_name)
+                        continue
+                self._persist_layers(cache_name, entry, new_value)
+
+    # ------------------------------------------------------------------
+    # Layer orchestration helpers
+
+    def _encode_value(self, entry: _CacheEntry, value: Any) -> Any:
+        encoder = entry.encoder
+        if encoder is None:
+            return value
+        return encoder(value)
+
+    def _decode_value(self, entry: _CacheEntry, payload: Any) -> Any:
+        decoder = entry.decoder
+        if decoder is None:
+            return payload
+        return decoder(payload)
+
+    def _store_layer(self, name: str, entry: _CacheEntry, value: Any, *, layer_index: int) -> None:
+        layer = self._layers[layer_index]
+        if layer_index == 0:
+            payload = value
+        else:
+            try:
+                payload = self._encode_value(entry, value)
+            except Exception:  # pragma: no cover - defensive logging
+                _logger.exception("cache encoding failed for %s", name)
+                return
+        try:
+            layer.store(name, payload)
+        except Exception:  # pragma: no cover - defensive logging
+            _logger.exception(
+                "cache layer store failed for %s on %s", name, layer.__class__.__name__
+            )
+
+    def _persist_layers(self, name: str, entry: _CacheEntry, value: Any) -> None:
+        for index in range(len(self._layers)):
+            self._store_layer(name, entry, value, layer_index=index)
+
+    def _delete_from_layers(self, name: str) -> None:
+        for layer in self._layers:
+            try:
+                layer.delete(name)
+            except KeyError:
+                continue
+            except Exception:  # pragma: no cover - defensive logging
+                _logger.exception(
+                    "cache layer delete failed for %s on %s", name, layer.__class__.__name__
+                )
+
+    def _load_from_layers(self, name: str, entry: _CacheEntry) -> Any:
+        # Primary in-memory layer first for fast-path lookups.
+        try:
+            value = self._layers[0].load(name)
+        except KeyError:
+            value = None
+        except Exception:  # pragma: no cover - defensive logging
+            _logger.exception(
+                "cache layer load failed for %s on %s", name, self._layers[0].__class__.__name__
+            )
+            value = None
+        if value is not None:
+            return value
+
+        # Fall back to slower layers and hydrate preceding caches on success.
+        for index in range(1, len(self._layers)):
+            layer = self._layers[index]
+            try:
+                payload = layer.load(name)
+            except KeyError:
+                continue
+            except Exception:  # pragma: no cover - defensive logging
+                _logger.exception(
+                    "cache layer load failed for %s on %s", name, layer.__class__.__name__
+                )
+                continue
+            try:
+                value = self._decode_value(entry, payload)
+            except Exception:  # pragma: no cover - defensive logging
+                _logger.exception("cache decoding failed for %s", name)
+                continue
+            if value is None:
+                continue
+            for prev_index in range(index):
+                self._store_layer(name, entry, value, layer_index=prev_index)
+            return value
+        return None
+
+    # ------------------------------------------------------------------
+    # Metrics helpers
+
+    def _ensure_metrics(self, name: str) -> _CacheMetrics:
+        metrics = self._metrics.get(name)
+        if metrics is None:
+            with self._registry_lock:
+                metrics = self._metrics.get(name)
+                if metrics is None:
+                    metrics = _CacheMetrics()
+                    self._metrics[name] = metrics
+        return metrics
+
+    def increment_hit(
+        self,
+        name: str,
+        *,
+        amount: int = 1,
+        duration: float | None = None,
+    ) -> None:
+        """Increase cache hit counters for ``name`` (optionally logging latency)."""
+
+        metrics = self._ensure_metrics(name)
+        with metrics.lock:
+            metrics.hits += int(amount)
+            if duration is not None:
+                metrics.total_time += float(duration)
+                metrics.timings += 1
+
+    def increment_miss(
+        self,
+        name: str,
+        *,
+        amount: int = 1,
+        duration: float | None = None,
+    ) -> None:
+        """Increase cache miss counters for ``name`` (optionally logging latency)."""
+
+        metrics = self._ensure_metrics(name)
+        with metrics.lock:
+            metrics.misses += int(amount)
+            if duration is not None:
+                metrics.total_time += float(duration)
+                metrics.timings += 1
+
+    def increment_eviction(self, name: str, *, amount: int = 1) -> None:
+        """Increase eviction count for cache ``name``."""
+
+        metrics = self._ensure_metrics(name)
+        with metrics.lock:
+            metrics.evictions += int(amount)
+
+    def record_timing(self, name: str, duration: float) -> None:
+        """Accumulate ``duration`` into latency telemetry for ``name``."""
+
+        metrics = self._ensure_metrics(name)
+        with metrics.lock:
+            metrics.total_time += float(duration)
+            metrics.timings += 1
+
+    @contextmanager
+    def timer(self, name: str) -> TimingContext:
+        """Context manager recording execution time for ``name``."""
+
+        start = perf_counter()
+        try:
+            yield
+        finally:
+            self.record_timing(name, perf_counter() - start)
+
+    def get_metrics(self, name: str) -> CacheStatistics:
+        """Return a snapshot of telemetry collected for cache ``name``."""
+
+        metrics = self._metrics.get(name)
+        if metrics is None:
+            return CacheStatistics()
+        with metrics.lock:
+            return metrics.snapshot()
+
+    def iter_metrics(self) -> Iterator[tuple[str, CacheStatistics]]:
+        """Yield ``(name, stats)`` pairs for every cache with telemetry."""
+
+        with self._registry_lock:
+            items = tuple(self._metrics.items())
+        for name, metrics in items:
+            with metrics.lock:
+                yield name, metrics.snapshot()
+
+    def aggregate_metrics(self) -> CacheStatistics:
+        """Return aggregated telemetry statistics across all caches."""
+
+        aggregate = CacheStatistics()
+        for _, stats in self.iter_metrics():
+            aggregate = aggregate.merge(stats)
+        return aggregate
+
+    def register_metrics_publisher(
+        self, publisher: Callable[[str, CacheStatistics], None]
+    ) -> None:
+        """Register ``publisher`` to receive metrics snapshots on demand."""
+
+        with self._registry_lock:
+            self._metrics_publishers.append(publisher)
+
+    def publish_metrics(
+        self,
+        *,
+        publisher: Callable[[str, CacheStatistics], None] | None = None,
+    ) -> None:
+        """Send cached telemetry to ``publisher`` or all registered publishers."""
+
+        if publisher is None:
+            with self._registry_lock:
+                publishers = tuple(self._metrics_publishers)
+        else:
+            publishers = (publisher,)
+        if not publishers:
+            return
+        snapshot = tuple(self.iter_metrics())
+        for emit in publishers:
+            for name, stats in snapshot:
+                try:
+                    emit(name, stats)
+                except Exception:  # pragma: no cover - defensive logging
+                    _logger.exception("Cache metrics publisher failed for %s", name)
+
+    def log_metrics(self, logger: logging.Logger, *, level: int = logging.INFO) -> None:
+        """Emit cache metrics using ``logger`` for telemetry hooks."""
+
+        for name, stats in self.iter_metrics():
+            logger.log(
+                level,
+                "cache=%s hits=%d misses=%d evictions=%d timings=%d total_time=%.6f",
+                name,
+                stats.hits,
+                stats.misses,
+                stats.evictions,
+                stats.timings,
+                stats.total_time,
+            )
+
+
+try:
+    from .init import get_logger as _get_logger
+except ImportError:  # pragma: no cover - circular bootstrap fallback
+
+    def _get_logger(name: str) -> logging.Logger:
+        return logging.getLogger(name)
+
+_logger = _get_logger(__name__)
+get_logger = _get_logger
+
+
+def _normalise_callbacks(
+    callbacks: Iterable[Callable[[K, V], None]] | Callable[[K, V], None] | None,
+) -> tuple[Callable[[K, V], None], ...]:
+    if callbacks is None:
+        return ()
+    if callable(callbacks):
+        return (callbacks,)
+    return tuple(callbacks)
+
+
+def prune_lock_mapping(
+    cache: Mapping[K, Any] | MutableMapping[K, Any] | None,
+    locks: MutableMapping[K, Any] | None,
+) -> None:
+    """Drop lock entries not present in ``cache``."""
+
+    if locks is None:
+        return
+    if cache is None:
+        cache_keys: set[K] = set()
+    else:
+        cache_keys = set(cache.keys())
+    for key in list(locks.keys()):
+        if key not in cache_keys:
+            locks.pop(key, None)
+
+
+class InstrumentedLRUCache(MutableMapping[K, V], Generic[K, V]):
+    """LRU cache wrapper that synchronises telemetry, callbacks and locks.
+
+    The wrapper owns an internal :class:`cachetools.LRUCache` instance and
+    forwards all read operations to it. Mutating operations are instrumented to
+    update :class:`CacheManager` metrics, execute registered callbacks and keep
+    an optional lock mapping aligned with the stored keys. Telemetry callbacks
+    always execute before eviction callbacks, preserving the registration order
+    for deterministic side effects.
+
+    Callbacks can be extended or replaced after construction via
+    :meth:`set_telemetry_callbacks` and :meth:`set_eviction_callbacks`. When
+    ``append`` is ``False`` (default) the provided callbacks replace the
+    existing sequence; otherwise they are appended at the end while keeping the
+    previous ordering intact.
+    """
+
+    _MISSING = object()
+
+    def __init__(
+        self,
+        maxsize: int,
+        *,
+        manager: CacheManager | None = None,
+        metrics_key: str | None = None,
+        telemetry_callbacks: (
+            Iterable[Callable[[K, V], None]] | Callable[[K, V], None] | None
+        ) = None,
+        eviction_callbacks: (
+            Iterable[Callable[[K, V], None]] | Callable[[K, V], None] | None
+        ) = None,
+        locks: MutableMapping[K, Any] | None = None,
+        getsizeof: Callable[[V], int] | None = None,
+        count_overwrite_hit: bool = True,
+    ) -> None:
+        self._cache: LRUCache[K, V] = LRUCache(maxsize, getsizeof=getsizeof)
+        original_popitem = self._cache.popitem
+
+        def _instrumented_popitem() -> tuple[K, V]:
+            key, value = original_popitem()
+            self._dispatch_removal(key, value)
+            return key, value
+
+        self._cache.popitem = _instrumented_popitem  # type: ignore[assignment]
+        self._manager = manager
+        self._metrics_key = metrics_key
+        self._locks = locks
+        self._count_overwrite_hit = bool(count_overwrite_hit)
+        self._telemetry_callbacks: list[Callable[[K, V], None]]
+        self._telemetry_callbacks = list(_normalise_callbacks(telemetry_callbacks))
+        self._eviction_callbacks: list[Callable[[K, V], None]]
+        self._eviction_callbacks = list(_normalise_callbacks(eviction_callbacks))
+
+    # ------------------------------------------------------------------
+    # Callback registration helpers
+
+    @property
+    def telemetry_callbacks(self) -> tuple[Callable[[K, V], None], ...]:
+        """Return currently registered telemetry callbacks."""
+
+        return tuple(self._telemetry_callbacks)
+
+    @property
+    def eviction_callbacks(self) -> tuple[Callable[[K, V], None], ...]:
+        """Return currently registered eviction callbacks."""
+
+        return tuple(self._eviction_callbacks)
+
+    def set_telemetry_callbacks(
+        self,
+        callbacks: Iterable[Callable[[K, V], None]] | Callable[[K, V], None] | None,
+        *,
+        append: bool = False,
+    ) -> None:
+        """Update telemetry callbacks executed on removals.
+
+        When ``append`` is ``True`` the provided callbacks are added to the end
+        of the execution chain while preserving relative order. Otherwise, the
+        previous callbacks are replaced.
+        """
+
+        new_callbacks = list(_normalise_callbacks(callbacks))
+        if append:
+            self._telemetry_callbacks.extend(new_callbacks)
+        else:
+            self._telemetry_callbacks = new_callbacks
+
+    def set_eviction_callbacks(
+        self,
+        callbacks: Iterable[Callable[[K, V], None]] | Callable[[K, V], None] | None,
+        *,
+        append: bool = False,
+    ) -> None:
+        """Update eviction callbacks executed on removals.
+
+        Behaviour matches :meth:`set_telemetry_callbacks`.
+        """
+
+        new_callbacks = list(_normalise_callbacks(callbacks))
+        if append:
+            self._eviction_callbacks.extend(new_callbacks)
+        else:
+            self._eviction_callbacks = new_callbacks
+
+    # ------------------------------------------------------------------
+    # MutableMapping interface
+
+    def __getitem__(self, key: K) -> V:
+        """Return the cached value for ``key``."""
+
+        return self._cache[key]
+
+    def __setitem__(self, key: K, value: V) -> None:
+        """Store ``value`` under ``key`` updating telemetry accordingly."""
+
+        exists = key in self._cache
+        self._cache[key] = value
+        if exists:
+            if self._count_overwrite_hit:
+                self._record_hit(1)
+        else:
+            self._record_miss(1)
+
+    def __delitem__(self, key: K) -> None:
+        """Remove ``key`` from the cache and dispatch removal callbacks."""
+
+        try:
+            value = self._cache[key]
+        except KeyError:
+            self._record_miss(1)
+            raise
+        del self._cache[key]
+        self._dispatch_removal(key, value, hits=1)
+
+    def __iter__(self) -> Iterator[K]:
+        """Iterate over cached keys in eviction order."""
+
+        return iter(self._cache)
+
+    def __len__(self) -> int:
+        """Return the number of cached entries."""
+
+        return len(self._cache)
+
+    def __contains__(self, key: object) -> bool:
+        """Return ``True`` when ``key`` is stored in the cache."""
+
+        return key in self._cache
+
+    def __repr__(self) -> str:  # pragma: no cover - debugging helper
+        """Return a debug representation including the underlying cache."""
+
+        return f"{self.__class__.__name__}({self._cache!r})"
+
+    # ------------------------------------------------------------------
+    # Cache helpers
+
+    @property
+    def maxsize(self) -> int:
+        """Return the configured maximum cache size."""
+
+        return self._cache.maxsize
+
+    @property
+    def currsize(self) -> int:
+        """Return the current weighted size reported by :mod:`cachetools`."""
+
+        return self._cache.currsize
+
+    def get(self, key: K, default: V | None = None) -> V | None:
+        """Return ``key`` if present, otherwise ``default``."""
+
+        return self._cache.get(key, default)
+
+    def pop(self, key: K, default: Any = _MISSING) -> V:
+        """Remove ``key`` returning its value or ``default`` when provided."""
+
+        try:
+            value = self._cache[key]
+        except KeyError:
+            self._record_miss(1)
+            if default is self._MISSING:
+                raise
+            return cast(V, default)
+        del self._cache[key]
+        self._dispatch_removal(key, value, hits=1)
+        return value
+
+    def popitem(self) -> tuple[K, V]:
+        """Remove and return the LRU entry ensuring instrumentation fires."""
+
+        return self._cache.popitem()
+
+    def clear(self) -> None:  # type: ignore[override]
+        """Evict every entry while keeping telemetry and locks consistent."""
+
+        while True:
+            try:
+                self.popitem()
+            except KeyError:
+                break
+        if self._locks is not None:
+            try:
+                self._locks.clear()
+            except Exception:  # pragma: no cover - defensive logging
+                _logger.exception("lock cleanup failed during cache clear")
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+
+    def _record_hit(self, amount: int) -> None:
+        if amount and self._manager is not None and self._metrics_key is not None:
+            self._manager.increment_hit(self._metrics_key, amount=amount)
+
+    def _record_miss(self, amount: int) -> None:
+        if amount and self._manager is not None and self._metrics_key is not None:
+            self._manager.increment_miss(self._metrics_key, amount=amount)
+
+    def _record_eviction(self, amount: int) -> None:
+        if amount and self._manager is not None and self._metrics_key is not None:
+            self._manager.increment_eviction(self._metrics_key, amount=amount)
+
+    def _dispatch_removal(
+        self,
+        key: K,
+        value: V,
+        *,
+        hits: int = 0,
+        misses: int = 0,
+        eviction_amount: int = 1,
+        purge_lock: bool = True,
+    ) -> None:
+        if hits:
+            self._record_hit(hits)
+        if misses:
+            self._record_miss(misses)
+        if eviction_amount:
+            self._record_eviction(eviction_amount)
+        self._emit_callbacks(self._telemetry_callbacks, key, value, "telemetry")
+        self._emit_callbacks(self._eviction_callbacks, key, value, "eviction")
+        if purge_lock:
+            self._purge_lock(key)
+
+    def _emit_callbacks(
+        self,
+        callbacks: Iterable[Callable[[K, V], None]],
+        key: K,
+        value: V,
+        kind: str,
+    ) -> None:
+        for callback in callbacks:
+            try:
+                callback(key, value)
+            except Exception:  # pragma: no cover - defensive logging
+                _logger.exception("%s callback failed for %r", kind, key)
+
+    def _purge_lock(self, key: K) -> None:
+        if self._locks is None:
+            return
+        try:
+            self._locks.pop(key, None)
+        except Exception:  # pragma: no cover - defensive logging
+            _logger.exception("lock cleanup failed for %r", key)
+
+
+class ManagedLRUCache(LRUCache[K, V]):
+    """LRU cache wrapper with telemetry hooks and lock synchronisation."""
+
+    def __init__(
+        self,
+        maxsize: int,
+        *,
+        manager: CacheManager | None = None,
+        metrics_key: str | None = None,
+        eviction_callbacks: (
+            Iterable[Callable[[K, V], None]] | Callable[[K, V], None] | None
+        ) = None,
+        telemetry_callbacks: (
+            Iterable[Callable[[K, V], None]] | Callable[[K, V], None] | None
+        ) = None,
+        locks: MutableMapping[K, Any] | None = None,
+    ) -> None:
+        super().__init__(maxsize)
+        self._manager = manager
+        self._metrics_key = metrics_key
+        self._locks = locks
+        self._eviction_callbacks = _normalise_callbacks(eviction_callbacks)
+        self._telemetry_callbacks = _normalise_callbacks(telemetry_callbacks)
+
+    def popitem(self) -> tuple[K, V]:  # type: ignore[override]
+        """Evict the LRU entry while updating telemetry and lock state."""
+
+        key, value = super().popitem()
+        if self._locks is not None:
+            try:
+                self._locks.pop(key, None)
+            except Exception:  # pragma: no cover - defensive logging
+                _logger.exception("lock cleanup failed for %r", key)
+        if self._manager is not None and self._metrics_key is not None:
+            self._manager.increment_eviction(self._metrics_key)
+        for callback in self._telemetry_callbacks:
+            try:
+                callback(key, value)
+            except Exception:  # pragma: no cover - defensive logging
+                _logger.exception("telemetry callback failed for %r", key)
+        for callback in self._eviction_callbacks:
+            try:
+                callback(key, value)
+            except Exception:  # pragma: no cover - defensive logging
+                _logger.exception("eviction callback failed for %r", key)
+        return key, value
+
+
+@dataclass
+class _SeedCacheState:
+    """Container tracking the state for :class:`_SeedHashCache`."""
+
+    cache: InstrumentedLRUCache[tuple[int, int], int] | None
+    maxsize: int
+
+
+@dataclass
+class _CounterState(Generic[K]):
+    """State bundle used by :class:`ScopedCounterCache`."""
+
+    cache: InstrumentedLRUCache[K, int]
+    locks: dict[K, threading.RLock]
+    max_entries: int
 
 # Key used to store the node set checksum in a graph's ``graph`` attribute.
 NODE_SET_CHECKSUM_KEY = "_node_set_checksum_cache"
 
-logger = get_logger(__name__)
+logger = _logger
+
+# Helper to avoid importing ``tnfr.utils.init`` at module import time and keep
+# circular dependencies at bay while still reusing the canonical numpy loader.
+def _require_numpy():
+    from .init import get_numpy
+
+    return get_numpy()
+
+
+# Graph key storing per-graph layer configuration overrides.
+_GRAPH_CACHE_LAYERS_KEY = "_tnfr_cache_layers"
+
+# Process-wide configuration for shared cache layers (Shelve/Redis).
+_GLOBAL_CACHE_LAYER_CONFIG: dict[str, dict[str, Any]] = {}
+_GLOBAL_CACHE_LOCK = threading.RLock()
+_GLOBAL_CACHE_MANAGER: CacheManager | None = None
 
 # Keys of cache entries dependent on the edge version. Any change to the edge
 # set requires these to be dropped to avoid stale data.
@@ -86,6 +1249,8 @@ def increment_graph_version(graph: Any, key: str) -> int:
 def stable_json(obj: Any) -> str:
     """Return a JSON string with deterministic ordering for ``obj``."""
 
+    from .io import json_dumps
+
     return json_dumps(
         obj,
         sort_keys=True,
@@ -112,15 +1277,199 @@ def clear_node_repr_cache() -> None:
     _node_repr_digest.cache_clear()
 
 
+def configure_global_cache_layers(
+    *,
+    shelve: Mapping[str, Any] | None = None,
+    redis: Mapping[str, Any] | None = None,
+    replace: bool = False,
+) -> None:
+    """Update process-wide cache layer configuration.
+
+    Parameters mirror the per-layer specifications accepted via graph metadata.
+    Passing ``replace=True`` clears previous settings before applying new ones.
+    Providing ``None`` for a layer while ``replace`` is true removes that layer
+    from the configuration.
+    """
+
+    global _GLOBAL_CACHE_MANAGER
+    with _GLOBAL_CACHE_LOCK:
+        manager = _GLOBAL_CACHE_MANAGER
+        _GLOBAL_CACHE_MANAGER = None
+        if replace:
+            _GLOBAL_CACHE_LAYER_CONFIG.clear()
+        if shelve is not None:
+            _GLOBAL_CACHE_LAYER_CONFIG["shelve"] = dict(shelve)
+        elif replace:
+            _GLOBAL_CACHE_LAYER_CONFIG.pop("shelve", None)
+        if redis is not None:
+            _GLOBAL_CACHE_LAYER_CONFIG["redis"] = dict(redis)
+        elif replace:
+            _GLOBAL_CACHE_LAYER_CONFIG.pop("redis", None)
+    _close_cache_layers(manager)
+
+
+def _resolve_layer_config(
+    graph: MutableMapping[str, Any] | None,
+) -> dict[str, dict[str, Any]]:
+    resolved: dict[str, dict[str, Any]] = {}
+    with _GLOBAL_CACHE_LOCK:
+        for name, spec in _GLOBAL_CACHE_LAYER_CONFIG.items():
+            resolved[name] = dict(spec)
+    if graph is not None:
+        overrides = graph.get(_GRAPH_CACHE_LAYERS_KEY)
+        if isinstance(overrides, Mapping):
+            for name in ("shelve", "redis"):
+                layer_spec = overrides.get(name)
+                if isinstance(layer_spec, Mapping):
+                    resolved[name] = dict(layer_spec)
+                elif layer_spec is None:
+                    resolved.pop(name, None)
+    return resolved
+
+
+def _build_shelve_layer(spec: Mapping[str, Any]) -> ShelveCacheLayer | None:
+    path = spec.get("path")
+    if not path:
+        return None
+    flag = spec.get("flag", "c")
+    protocol = spec.get("protocol")
+    writeback = bool(spec.get("writeback", False))
+    try:
+        proto_arg = None if protocol is None else int(protocol)
+    except (TypeError, ValueError):
+        logger.warning("Invalid shelve protocol %r; falling back to default", protocol)
+        proto_arg = None
+    try:
+        return ShelveCacheLayer(
+            str(path),
+            flag=str(flag),
+            protocol=proto_arg,
+            writeback=writeback,
+        )
+    except Exception:  # pragma: no cover - defensive logging
+        logger.exception("Failed to initialise ShelveCacheLayer for path %r", path)
+        return None
+
+
+def _build_redis_layer(spec: Mapping[str, Any]) -> RedisCacheLayer | None:
+    enabled = spec.get("enabled", True)
+    if not enabled:
+        return None
+    namespace = spec.get("namespace")
+    client = spec.get("client")
+    if client is None:
+        factory = spec.get("client_factory")
+        if callable(factory):
+            try:
+                client = factory()
+            except Exception:  # pragma: no cover - defensive logging
+                logger.exception("Redis cache client factory failed")
+                return None
+        else:
+            kwargs = spec.get("client_kwargs")
+            if isinstance(kwargs, Mapping):
+                try:  # pragma: no cover - optional dependency
+                    import redis  # type: ignore
+                except Exception:  # pragma: no cover - defensive logging
+                    logger.exception("redis-py is required to build the configured Redis client")
+                    return None
+                try:
+                    client = redis.Redis(**dict(kwargs))
+                except Exception:  # pragma: no cover - defensive logging
+                    logger.exception("Failed to initialise redis client with %r", kwargs)
+                    return None
+    try:
+        if namespace is None:
+            return RedisCacheLayer(client=client)
+        return RedisCacheLayer(client=client, namespace=str(namespace))
+    except Exception:  # pragma: no cover - defensive logging
+        logger.exception("Failed to initialise RedisCacheLayer")
+        return None
+
+
+def _build_cache_layers(config: Mapping[str, dict[str, Any]]) -> tuple[CacheLayer, ...]:
+    layers: list[CacheLayer] = []
+    shelve_spec = config.get("shelve")
+    if isinstance(shelve_spec, Mapping):
+        layer = _build_shelve_layer(shelve_spec)
+        if layer is not None:
+            layers.append(layer)
+    redis_spec = config.get("redis")
+    if isinstance(redis_spec, Mapping):
+        layer = _build_redis_layer(redis_spec)
+        if layer is not None:
+            layers.append(layer)
+    return tuple(layers)
+
+
+def _close_cache_layers(manager: CacheManager | None) -> None:
+    if manager is None:
+        return
+    layers = getattr(manager, "_layers", ())
+    for layer in layers:
+        close = getattr(layer, "close", None)
+        if callable(close):
+            try:
+                close()
+            except Exception:  # pragma: no cover - defensive logging
+                logger.exception(
+                    "Cache layer close failed for %s", layer.__class__.__name__
+                )
+
+
+def reset_global_cache_manager() -> None:
+    """Dispose the shared cache manager and close attached layers."""
+
+    global _GLOBAL_CACHE_MANAGER
+    with _GLOBAL_CACHE_LOCK:
+        manager = _GLOBAL_CACHE_MANAGER
+        _GLOBAL_CACHE_MANAGER = None
+    _close_cache_layers(manager)
+
+
+def build_cache_manager(
+    *,
+    graph: MutableMapping[str, Any] | None = None,
+    storage: MutableMapping[str, Any] | None = None,
+    default_capacity: int | None = None,
+    overrides: Mapping[str, int | None] | None = None,
+) -> CacheManager:
+    """Construct a :class:`CacheManager` honouring configured cache layers."""
+
+    global _GLOBAL_CACHE_MANAGER
+    if graph is None:
+        with _GLOBAL_CACHE_LOCK:
+            manager = _GLOBAL_CACHE_MANAGER
+        if manager is not None:
+            return manager
+
+    layers = _build_cache_layers(_resolve_layer_config(graph))
+    manager = CacheManager(
+        storage,
+        default_capacity=default_capacity,
+        overrides=overrides,
+        layers=layers,
+    )
+
+    if graph is None:
+        with _GLOBAL_CACHE_LOCK:
+            global_manager = _GLOBAL_CACHE_MANAGER
+            if global_manager is None:
+                _GLOBAL_CACHE_MANAGER = manager
+                return manager
+        _close_cache_layers(manager)
+        return global_manager
+
+    return manager
+
+
 def _node_repr(n: Any) -> str:
     """Stable representation for node hashing and sorting."""
 
     return _node_repr_digest(n)[0]
 
 
-def _iter_node_digests(
-    nodes: Iterable[Any], *, presorted: bool
-) -> Iterable[bytes]:
+def _iter_node_digests(nodes: Iterable[Any], *, presorted: bool) -> Iterable[bytes]:
     """Yield node digests in a deterministic order."""
 
     if presorted:
@@ -174,9 +1523,7 @@ def node_set_checksum(
 
     graph = get_graph(G)
     if nodes is None:
-        return _node_set_checksum_no_nodes(
-            G, graph, presorted=presorted, store=store
-        )
+        return _node_set_checksum_no_nodes(G, graph, presorted=presorted, store=store)
 
     hasher = hashlib.blake2b(digest_size=16)
     for digest in _iter_node_digests(nodes, presorted=presorted):
@@ -366,6 +1713,7 @@ class EdgeCacheState:
     cache: MutableMapping[Hashable, Any]
     locks: defaultdict[Hashable, threading.RLock]
     max_entries: int | None
+    dirty: bool = False
 
 
 _GRAPH_CACHE_MANAGER_KEY = "_tnfr_cache_manager"
@@ -377,32 +1725,11 @@ DNFR_PREP_STATE_KEY = "_dnfr_prep_state"
 class DnfrPrepState:
     """State container coordinating ΔNFR preparation caches."""
 
-    cache: "DnfrCache"
+    cache: DnfrCache
     cache_lock: threading.RLock
     vector_lock: threading.RLock
 
 
-def _new_dnfr_cache() -> "DnfrCache":
-    """Return an empty :class:`~tnfr.dynamics.dnfr.DnfrCache` instance."""
-
-    from ..dynamics.dnfr import DnfrCache
-
-    return DnfrCache(
-        idx={},
-        theta=[],
-        epi=[],
-        vf=[],
-        cos_theta=[],
-        sin_theta=[],
-        neighbor_x=[],
-        neighbor_y=[],
-        neighbor_epi_sum=[],
-        neighbor_vf_sum=[],
-        neighbor_count=[],
-        neighbor_deg_sum=[],
-    )
-
-
 def _build_dnfr_prep_state(
     graph: MutableMapping[str, Any],
     previous: DnfrPrepState | None = None,
@@ -418,7 +1745,7 @@ def _build_dnfr_prep_state(
         cache_lock = threading.RLock()
         vector_lock = threading.RLock()
     state = DnfrPrepState(
-        cache=_new_dnfr_cache(),
+        cache=new_dnfr_cache(),
         cache_lock=cache_lock,
         vector_lock=vector_lock,
     )
@@ -435,11 +1762,7 @@ def _coerce_dnfr_state(
     if isinstance(current, DnfrPrepState):
         graph["_dnfr_prep_cache"] = current.cache
         return current
-    try:
-        from ..dynamics.dnfr import DnfrCache
-    except Exception:  # pragma: no cover - defensive import
-        DnfrCache = None  # type: ignore[assignment]
-    if DnfrCache is not None and isinstance(current, DnfrCache):
+    if isinstance(current, DnfrCache):
         state = DnfrPrepState(
             cache=current,
             cache_lock=threading.RLock(),
@@ -453,11 +1776,12 @@ def _coerce_dnfr_state(
 def _graph_cache_manager(graph: MutableMapping[str, Any]) -> CacheManager:
     manager = graph.get(_GRAPH_CACHE_MANAGER_KEY)
     if not isinstance(manager, CacheManager):
-        manager = CacheManager(default_capacity=128)
+        manager = build_cache_manager(graph=graph, default_capacity=128)
         graph[_GRAPH_CACHE_MANAGER_KEY] = manager
     config = graph.get(_GRAPH_CACHE_CONFIG_KEY)
     if isinstance(config, dict):
         manager.configure_from_mapping(config)
+
     def _dnfr_factory() -> DnfrPrepState:
         return _build_dnfr_prep_state(graph)
 
@@ -510,10 +1834,33 @@ class EdgeCacheManager:
     def __init__(self, graph: MutableMapping[str, Any]) -> None:
         self.graph: MutableMapping[str, Any] = graph
         self._manager = _graph_cache_manager(graph)
+
+        def _encode_state(state: EdgeCacheState) -> Mapping[str, Any]:
+            if not isinstance(state, EdgeCacheState):
+                raise TypeError("EdgeCacheState expected")
+            return {
+                "max_entries": state.max_entries,
+                "entries": list(state.cache.items()),
+            }
+
+        def _decode_state(payload: Any) -> EdgeCacheState:
+            if isinstance(payload, EdgeCacheState):
+                return payload
+            if not isinstance(payload, Mapping):
+                raise TypeError("invalid edge cache payload")
+            max_entries = payload.get("max_entries")
+            state = self._build_state(max_entries)
+            for key, value in payload.get("entries", []):
+                state.cache[key] = value
+            state.dirty = False
+            return state
+
         self._manager.register(
             self._STATE_KEY,
             self._default_state,
             reset=self._reset_state,
+            encoder=_encode_state,
+            decoder=_decode_state,
         )
 
     def record_hit(self) -> None:
@@ -570,13 +1917,15 @@ class EdgeCacheManager:
             locks=locks,
             count_overwrite_hit=False,
         )
+        state = EdgeCacheState(cache=cache, locks=locks, max_entries=max_entries)
 
         def _on_eviction(key: Hashable, _: Any) -> None:
             self.record_eviction(track_metrics=False)
             locks.pop(key, None)
+            state.dirty = True
 
         cache.set_eviction_callbacks(_on_eviction)
-        return EdgeCacheState(cache=cache, locks=locks, max_entries=max_entries)
+        return state
 
     def _ensure_state(
         self, state: EdgeCacheState | None, max_entries: int | None | object
@@ -593,6 +1942,7 @@ class EdgeCacheManager:
     def _reset_state(self, state: EdgeCacheState | None) -> EdgeCacheState:
         if isinstance(state, EdgeCacheState):
             state.cache.clear()
+            state.dirty = False
             return state
         return self._build_state(None)
 
@@ -601,25 +1951,28 @@ class EdgeCacheManager:
         max_entries: int | None | object,
         *,
         create: bool = True,
-    ) -> tuple[
-        MutableMapping[Hashable, Any] | None,
-        dict[Hashable, threading.RLock]
-        | defaultdict[Hashable, threading.RLock]
-        | None,
-    ]:
-        """Return the cache and lock mapping for the manager's graph."""
+    ) -> EdgeCacheState | None:
+        """Return the cache state for the manager's graph."""
 
         if not create:
             state = self._manager.peek(self._STATE_KEY)
-            if isinstance(state, EdgeCacheState):
-                return state.cache, state.locks
-            return None, None
+            return state if isinstance(state, EdgeCacheState) else None
 
         state = self._manager.update(
             self._STATE_KEY,
             lambda current: self._ensure_state(current, max_entries),
         )
-        return state.cache, state.locks
+        if not isinstance(state, EdgeCacheState):
+            raise RuntimeError("edge cache state failed to initialise")
+        return state
+
+    def flush_state(self, state: EdgeCacheState) -> None:
+        """Persist ``state`` through the configured cache layers when dirty."""
+
+        if not isinstance(state, EdgeCacheState) or not state.dirty:
+            return
+        self._manager.store(self._STATE_KEY, state)
+        state.dirty = False
 
     def clear(self) -> None:
         """Reset cached data managed by this instance."""
@@ -646,7 +1999,12 @@ def edge_version_cache(
     if resolved == 0:
         return builder()
 
-    cache, locks = manager.get_cache(resolved)
+    state = manager.get_cache(resolved)
+    if state is None:
+        return builder()
+
+    cache = state.cache
+    locks = state.locks
     edge_version = get_graph_version(graph, "_edge_version")
     lock = locks[key]
 
@@ -663,6 +2021,7 @@ def edge_version_cache(
         logger.exception("edge_version_cache builder failed for %r: %s", key, exc)
         raise
     else:
+        result = value
         with lock:
             entry = cache.get(key)
             if entry is not None:
@@ -673,7 +2032,11 @@ def edge_version_cache(
                     return cached_value
                 manager.record_eviction()
             cache[key] = (edge_version, value)
-            return value
+            state.dirty = True
+            result = value
+    if state.dirty:
+        manager.flush_state(state)
+    return result
 
 
 def cached_nodes_and_A(
@@ -711,7 +2074,7 @@ def cached_nodes_and_A(
     graph["_dnfr_nodes_checksum"] = checksum
 
     def builder() -> tuple[tuple[Any, ...], Any]:
-        np = get_numpy()
+        np = _require_numpy()
         if np is None or prefer_sparse:
             return nodes, None
         A = nx.to_numpy_array(G, nodelist=nodes, weight=None, dtype=float)
@@ -753,3 +2116,280 @@ def edge_version_update(G: TNFRGraph) -> Iterator[None]:
         yield
     finally:
         increment_edge_version(G)
+
+
+class _SeedHashCache(MutableMapping[tuple[int, int], int]):
+    """Mutable mapping proxy exposing a configurable LRU cache."""
+
+    def __init__(
+        self,
+        *,
+        manager: CacheManager | None = None,
+        state_key: str = "seed_hash_cache",
+        default_maxsize: int = 128,
+    ) -> None:
+        self._default_maxsize = int(default_maxsize)
+        self._manager = manager or build_cache_manager(
+            default_capacity=self._default_maxsize
+        )
+        self._state_key = state_key
+        if not self._manager.has_override(self._state_key):
+            self._manager.configure(
+                overrides={self._state_key: self._default_maxsize}
+            )
+        self._manager.register(
+            self._state_key,
+            self._create_state,
+            reset=self._reset_state,
+        )
+
+    def _resolved_size(self, requested: int | None = None) -> int:
+        size = self._manager.get_capacity(
+            self._state_key,
+            requested=requested,
+            fallback=self._default_maxsize,
+        )
+        if size is None:
+            return 0
+        return int(size)
+
+    def _create_state(self) -> _SeedCacheState:
+        size = self._resolved_size()
+        if size <= 0:
+            return _SeedCacheState(cache=None, maxsize=0)
+        return _SeedCacheState(
+            cache=InstrumentedLRUCache(
+                size,
+                manager=self._manager,
+                metrics_key=self._state_key,
+            ),
+            maxsize=size,
+        )
+
+    def _reset_state(self, state: _SeedCacheState | None) -> _SeedCacheState:
+        return self._create_state()
+
+    def _get_state(self, *, create: bool = True) -> _SeedCacheState | None:
+        state = self._manager.get(self._state_key, create=create)
+        if state is None:
+            return None
+        if not isinstance(state, _SeedCacheState):
+            state = self._create_state()
+            self._manager.store(self._state_key, state)
+        return state
+
+    def configure(self, maxsize: int) -> None:
+        size = int(maxsize)
+        if size < 0:
+            raise ValueError("maxsize must be non-negative")
+        self._manager.configure(overrides={self._state_key: size})
+        self._manager.update(self._state_key, lambda _: self._create_state())
+
+    def __getitem__(self, key: tuple[int, int]) -> int:
+        state = self._get_state()
+        if state is None or state.cache is None:
+            raise KeyError(key)
+        value = state.cache[key]
+        self._manager.increment_hit(self._state_key)
+        return value
+
+    def __setitem__(self, key: tuple[int, int], value: int) -> None:
+        state = self._get_state()
+        if state is not None and state.cache is not None:
+            state.cache[key] = value
+
+    def __delitem__(self, key: tuple[int, int]) -> None:
+        state = self._get_state()
+        if state is None or state.cache is None:
+            raise KeyError(key)
+        del state.cache[key]
+
+    def __iter__(self) -> Iterator[tuple[int, int]]:
+        state = self._get_state(create=False)
+        if state is None or state.cache is None:
+            return iter(())
+        return iter(state.cache)
+
+    def __len__(self) -> int:
+        state = self._get_state(create=False)
+        if state is None or state.cache is None:
+            return 0
+        return len(state.cache)
+
+    def clear(self) -> None:  # type: ignore[override]
+        self._manager.clear(self._state_key)
+
+    @property
+    def maxsize(self) -> int:
+        state = self._get_state()
+        return 0 if state is None else state.maxsize
+
+    @property
+    def enabled(self) -> bool:
+        state = self._get_state(create=False)
+        return bool(state and state.cache is not None)
+
+    @property
+    def data(self) -> InstrumentedLRUCache[tuple[int, int], int] | None:
+        """Expose the underlying cache for diagnostics/tests."""
+
+        state = self._get_state(create=False)
+        return None if state is None else state.cache
+
+
+class ScopedCounterCache(Generic[K]):
+    """Thread-safe LRU cache storing monotonic counters by ``key``."""
+
+    def __init__(
+        self,
+        name: str,
+        max_entries: int | None = None,
+        *,
+        manager: CacheManager | None = None,
+        default_max_entries: int = 128,
+    ) -> None:
+        self._name = name
+        self._state_key = f"scoped_counter:{name}"
+        self._default_max_entries = int(default_max_entries)
+        requested = None if max_entries is None else int(max_entries)
+        if requested is not None and requested < 0:
+            raise ValueError("max_entries must be non-negative")
+        self._manager = manager or build_cache_manager(
+            default_capacity=self._default_max_entries
+        )
+        if not self._manager.has_override(self._state_key):
+            fallback = requested
+            if fallback is None:
+                fallback = self._default_max_entries
+            self._manager.configure(overrides={self._state_key: fallback})
+        elif requested is not None:
+            self._manager.configure(overrides={self._state_key: requested})
+        self._manager.register(
+            self._state_key,
+            self._create_state,
+            lock_factory=lambda: get_lock(name),
+            reset=self._reset_state,
+        )
+
+    def _resolved_entries(self, requested: int | None = None) -> int:
+        size = self._manager.get_capacity(
+            self._state_key,
+            requested=requested,
+            fallback=self._default_max_entries,
+        )
+        if size is None:
+            return 0
+        return int(size)
+
+    def _create_state(self, requested: int | None = None) -> _CounterState[K]:
+        size = self._resolved_entries(requested)
+        locks: dict[K, threading.RLock] = {}
+        return _CounterState(
+            cache=InstrumentedLRUCache(
+                size,
+                manager=self._manager,
+                metrics_key=self._state_key,
+                locks=locks,
+            ),
+            locks=locks,
+            max_entries=size,
+        )
+
+    def _reset_state(self, state: _CounterState[K] | None) -> _CounterState[K]:
+        return self._create_state()
+
+    def _get_state(self) -> _CounterState[K]:
+        state = self._manager.get(self._state_key)
+        if not isinstance(state, _CounterState):
+            state = self._create_state(0)
+            self._manager.store(self._state_key, state)
+        return state
+
+    @property
+    def lock(self) -> threading.Lock | threading.RLock:
+        """Return the lock guarding access to the underlying cache."""
+
+        return self._manager.get_lock(self._state_key)
+
+    @property
+    def max_entries(self) -> int:
+        """Return the configured maximum number of cached entries."""
+
+        return self._get_state().max_entries
+
+    @property
+    def cache(self) -> InstrumentedLRUCache[K, int]:
+        """Expose the instrumented cache for inspection."""
+
+        return self._get_state().cache
+
+    @property
+    def locks(self) -> dict[K, threading.RLock]:
+        """Return the mapping of per-key locks tracked by the cache."""
+
+        return self._get_state().locks
+
+    def configure(self, *, force: bool = False, max_entries: int | None = None) -> None:
+        """Resize or reset the cache keeping previous settings."""
+
+        if max_entries is None:
+            size = self._resolved_entries()
+            update_policy = False
+        else:
+            size = int(max_entries)
+            if size < 0:
+                raise ValueError("max_entries must be non-negative")
+            update_policy = True
+
+        def _update(state: _CounterState[K] | None) -> _CounterState[K]:
+            if (
+                not isinstance(state, _CounterState)
+                or force
+                or state.max_entries != size
+            ):
+                locks: dict[K, threading.RLock] = {}
+                return _CounterState(
+                    cache=InstrumentedLRUCache(
+                        size,
+                        manager=self._manager,
+                        metrics_key=self._state_key,
+                        locks=locks,
+                    ),
+                    locks=locks,
+                    max_entries=size,
+                )
+            return cast(_CounterState[K], state)
+
+        if update_policy:
+            self._manager.configure(overrides={self._state_key: size})
+        self._manager.update(self._state_key, _update)
+
+    def clear(self) -> None:
+        """Clear stored counters preserving ``max_entries``."""
+
+        self.configure(force=True)
+
+    def bump(self, key: K) -> int:
+        """Return current counter for ``key`` and increment it atomically."""
+
+        result: dict[str, Any] = {}
+
+        def _update(state: _CounterState[K] | None) -> _CounterState[K]:
+            if not isinstance(state, _CounterState):
+                state = self._create_state(0)
+            cache = state.cache
+            locks = state.locks
+            if key not in locks:
+                locks[key] = threading.RLock()
+            value = int(cache.get(key, 0))
+            cache[key] = value + 1
+            result["value"] = value
+            return state
+
+        self._manager.update(self._state_key, _update)
+        return int(result.get("value", 0))
+
+    def __len__(self) -> int:
+        """Return the number of tracked counters."""
+
+        return len(self.cache)