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

tnfr/cache.py

@@ -1,578 +1,732 @@
-"""Core caching utilities shared across TNFR helpers.
-
-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.
-"""
+"""Central cache registry infrastructure for TNFR services."""
 
 from __future__ import annotations
 
-import hashlib
+import logging
 import threading
-from collections import defaultdict
-from collections.abc import Callable, Hashable, Iterable
+from collections.abc import Iterable
 from contextlib import contextmanager
-from functools import lru_cache
-from dataclasses import dataclass
-from typing import Any, TypeVar
+from dataclasses import dataclass, field
+from time import perf_counter
+from typing import Any, Callable, Generic, Hashable, Iterator, Mapping, MutableMapping, TypeVar, cast
 
 from cachetools import LRUCache
-import networkx as nx  # type: ignore[import-untyped]
-
-from .graph_utils import get_graph, mark_dnfr_prep_dirty
-from .import_utils import get_numpy
-from .json_utils import json_dumps
-from .logging_utils import get_logger
-
-T = TypeVar("T")
-
-__all__ = (
-    "EdgeCacheManager",
-    "LockAwareLRUCache",
-    "NODE_SET_CHECKSUM_KEY",
-    "cached_node_list",
-    "cached_nodes_and_A",
-    "clear_node_repr_cache",
-    "edge_version_cache",
-    "edge_version_update",
-    "ensure_node_index_map",
-    "ensure_node_offset_map",
-    "get_graph_version",
-    "increment_edge_version",
-    "increment_graph_version",
-    "node_set_checksum",
-    "stable_json",
-)
-
-# 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__)
-
-# Keys of cache entries dependent on the edge version. Any change to the edge
-# set requires these to be dropped to avoid stale data.
-EDGE_VERSION_CACHE_KEYS = ("_trig_version",)
-
-
-class LockAwareLRUCache(LRUCache[Hashable, Any]):
-    """``LRUCache`` that drops per-key locks when evicting items."""
-
-    def __init__(self, maxsize: int, locks: dict[Hashable, threading.RLock]):
-        super().__init__(maxsize)
-        self._locks: dict[Hashable, threading.RLock] = locks
-
-    def popitem(self) -> tuple[Hashable, Any]:  # type: ignore[override]
-        key, value = super().popitem()
-        self._locks.pop(key, None)
-        return key, value
-
-
-def _ensure_graph_entry(
-    graph: Any,
-    key: str,
-    factory: Callable[[], T],
-    validator: Callable[[Any], bool],
-) -> T:
-    """Return a validated entry from ``graph`` or create one when missing."""
-
-    value = graph.get(key)
-    if not validator(value):
-        value = factory()
-        graph[key] = value
-    return value
-
-
-def _ensure_lock_mapping(
-    graph: Any,
-    key: str,
-    *,
-    lock_factory: Callable[[], threading.RLock] = threading.RLock,
-) -> defaultdict[Hashable, threading.RLock]:
-    """Ensure ``graph`` holds a ``defaultdict`` of locks under ``key``."""
-
-    return _ensure_graph_entry(
-        graph,
-        key,
-        factory=lambda: defaultdict(lock_factory),
-        validator=lambda value: isinstance(value, defaultdict)
-        and value.default_factory is lock_factory,
-    )
-
-
-def _prune_locks(
-    cache: dict[Hashable, Any] | LRUCache[Hashable, Any] | None,
-    locks: dict[Hashable, threading.RLock]
-    | defaultdict[Hashable, threading.RLock]
-    | None,
-) -> None:
-    """Drop locks with no corresponding cache entry."""
-
-    if not isinstance(locks, dict):
-        return
-    cache_keys = cache.keys() if isinstance(cache, dict) else ()
-    for key in list(locks.keys()):
-        if key not in cache_keys:
-            locks.pop(key, None)
-
-
-def get_graph_version(graph: Any, key: str, default: int = 0) -> int:
-    """Return integer version stored in ``graph`` under ``key``."""
-
-    return int(graph.get(key, default))
-
-
-def increment_graph_version(graph: Any, key: str) -> int:
-    """Increment and store a version counter in ``graph`` under ``key``."""
 
-    version = get_graph_version(graph, key) + 1
-    graph[key] = version
-    return version
+from .types import TimingContext
 
+__all__ = [
+    "CacheManager",
+    "CacheCapacityConfig",
+    "CacheStatistics",
+    "InstrumentedLRUCache",
+    "ManagedLRUCache",
+    "prune_lock_mapping",
+]
 
-def stable_json(obj: Any) -> str:
-    """Return a JSON string with deterministic ordering for ``obj``."""
 
-    return json_dumps(
-        obj,
-        sort_keys=True,
-        ensure_ascii=False,
-        to_bytes=False,
-    )
+K = TypeVar("K", bound=Hashable)
+V = TypeVar("V")
 
+_logger = logging.getLogger(__name__)
 
-@lru_cache(maxsize=1024)
-def _node_repr_digest(obj: Any) -> tuple[str, bytes]:
-    """Return cached stable representation and digest for ``obj``."""
 
-    try:
-        repr_ = stable_json(obj)
-    except TypeError:
-        repr_ = repr(obj)
-    digest = hashlib.blake2b(repr_.encode("utf-8"), digest_size=16).digest()
-    return repr_, digest
+@dataclass(frozen=True)
+class CacheCapacityConfig:
+    """Configuration snapshot for cache capacity policies."""
 
+    default_capacity: int | None
+    overrides: dict[str, int | None]
 
-def clear_node_repr_cache() -> None:
-    """Clear cached node representations used for checksums."""
 
-    _node_repr_digest.cache_clear()
+@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 _node_repr(n: Any) -> str:
-    """Stable representation for node hashing and sorting."""
-
-    return _node_repr_digest(n)[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,
+        )
 
-def _iter_node_digests(
-    nodes: Iterable[Any], *, presorted: bool
-) -> Iterable[bytes]:
-    """Yield node digests in a deterministic order."""
 
-    if presorted:
-        for node in nodes:
-            yield _node_repr_digest(node)[1]
-    else:
-        for _, digest in sorted(
-            (_node_repr_digest(n) for n in nodes), key=lambda x: x[0]
-        ):
-            yield digest
-
-
-def _node_set_checksum_no_nodes(
-    G: nx.Graph,
-    graph: Any,
-    *,
-    presorted: bool,
-    store: bool,
-) -> str:
-    """Checksum helper when no explicit node set is provided."""
-
-    nodes_view = G.nodes()
-    current_nodes = frozenset(nodes_view)
-    cached = graph.get(NODE_SET_CHECKSUM_KEY)
-    if cached and len(cached) == 3 and cached[2] == current_nodes:
-        return cached[1]
-
-    hasher = hashlib.blake2b(digest_size=16)
-    for digest in _iter_node_digests(nodes_view, presorted=presorted):
-        hasher.update(digest)
-
-    checksum = hasher.hexdigest()
-    if store:
-        token = checksum[:16]
-        if cached and cached[0] == token:
-            return cached[1]
-        graph[NODE_SET_CHECKSUM_KEY] = (token, checksum, current_nodes)
-    else:
-        graph.pop(NODE_SET_CHECKSUM_KEY, None)
-    return checksum
-
-
-def node_set_checksum(
-    G: nx.Graph,
-    nodes: Iterable[Any] | None = None,
-    *,
-    presorted: bool = False,
-    store: bool = True,
-) -> str:
-    """Return a BLAKE2b checksum of ``G``'s node set."""
-
-    graph = get_graph(G)
-    if nodes is None:
-        return _node_set_checksum_no_nodes(
-            G, graph, presorted=presorted, store=store
+@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,
         )
 
-    hasher = hashlib.blake2b(digest_size=16)
-    for digest in _iter_node_digests(nodes, presorted=presorted):
-        hasher.update(digest)
-
-    checksum = hasher.hexdigest()
-    if store:
-        token = checksum[:16]
-        cached = graph.get(NODE_SET_CHECKSUM_KEY)
-        if cached and cached[0] == token:
-            return cached[1]
-        graph[NODE_SET_CHECKSUM_KEY] = (token, checksum)
-    else:
-        graph.pop(NODE_SET_CHECKSUM_KEY, None)
-    return checksum
 
+@dataclass
+class _CacheEntry:
+    factory: Callable[[], Any]
+    lock: threading.Lock
+    reset: Callable[[Any], Any] | None = None
 
-@dataclass(slots=True)
-class NodeCache:
-    """Container for cached node data."""
 
-    checksum: str
-    nodes: tuple[Any, ...]
-    sorted_nodes: tuple[Any, ...] | None = None
-    idx: dict[Any, int] | None = None
-    offset: dict[Any, int] | None = None
+class CacheManager:
+    """Coordinate named caches guarded by per-entry locks."""
 
-    @property
-    def n(self) -> int:
-        return len(self.nodes)
+    _MISSING = object()
 
+    def __init__(
+        self,
+        storage: MutableMapping[str, Any] | None = None,
+        *,
+        default_capacity: int | None = None,
+        overrides: Mapping[str, int | None] | None = None,
+    ) -> None:
+        self._storage: MutableMapping[str, Any]
+        if storage is None:
+            self._storage = {}
+        else:
+            self._storage = 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,
+    ) -> 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)
+                self._entries[name] = entry
+            else:
+                # Update hooks when re-registering the same cache name.
+                entry.factory = factory
+                entry.reset = reset
+            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 _update_node_cache(
-    graph: Any,
-    nodes: tuple[Any, ...],
-    key: str,
-    *,
-    checksum: str,
-    sorted_nodes: tuple[Any, ...] | None = None,
-) -> None:
-    """Store ``nodes`` and ``checksum`` in ``graph`` under ``key``."""
-
-    graph[f"{key}_cache"] = NodeCache(
-        checksum=checksum, nodes=nodes, sorted_nodes=sorted_nodes
-    )
-    graph[f"{key}_checksum"] = checksum
-
-
-def _refresh_node_list_cache(
-    G: nx.Graph,
-    graph: Any,
-    *,
-    sort_nodes: bool,
-    current_n: int,
-) -> tuple[Any, ...]:
-    """Refresh the cached node list and return the nodes."""
-
-    nodes = tuple(G.nodes())
-    checksum = node_set_checksum(G, nodes, store=True)
-    sorted_nodes = tuple(sorted(nodes, key=_node_repr)) if sort_nodes else None
-    _update_node_cache(
-        graph,
-        nodes,
-        "_node_list",
-        checksum=checksum,
-        sorted_nodes=sorted_nodes,
-    )
-    graph["_node_list_len"] = current_n
-    return nodes
-
-
-def _reuse_node_list_cache(
-    graph: Any,
-    cache: NodeCache,
-    nodes: tuple[Any, ...],
-    sorted_nodes: tuple[Any, ...] | None,
-    *,
-    sort_nodes: bool,
-    new_checksum: str | None,
-) -> None:
-    """Reuse existing node cache and record its checksum if missing."""
-
-    checksum = cache.checksum if new_checksum is None else new_checksum
-    if sort_nodes and sorted_nodes is None:
-        sorted_nodes = tuple(sorted(nodes, key=_node_repr))
-    _update_node_cache(
-        graph,
-        nodes,
-        "_node_list",
-        checksum=checksum,
-        sorted_nodes=sorted_nodes,
-    )
-
-
-def _cache_node_list(G: nx.Graph) -> tuple[Any, ...]:
-    """Cache and return the tuple of nodes for ``G``."""
-
-    graph = get_graph(G)
-    cache: NodeCache | None = graph.get("_node_list_cache")
-    nodes = cache.nodes if cache else None
-    sorted_nodes = cache.sorted_nodes if cache else None
-    stored_len = graph.get("_node_list_len")
-    current_n = G.number_of_nodes()
-    dirty = bool(graph.pop("_node_list_dirty", False))
-
-    invalid = nodes is None or stored_len != current_n or dirty
-    new_checksum: str | None = None
-
-    if not invalid and cache:
-        new_checksum = node_set_checksum(G)
-        invalid = cache.checksum != new_checksum
-
-    sort_nodes = bool(graph.get("SORT_NODES", False))
-
-    if invalid:
-        nodes = _refresh_node_list_cache(
-            G, graph, sort_nodes=sort_nodes, current_n=current_n
-        )
-    elif cache and "_node_list_checksum" not in graph:
-        _reuse_node_list_cache(
-            graph,
-            cache,
-            nodes,
-            sorted_nodes,
-            sort_nodes=sort_nodes,
-            new_checksum=new_checksum,
-        )
-    else:
-        if sort_nodes and sorted_nodes is None and cache is not None:
-            cache.sorted_nodes = tuple(sorted(nodes, key=_node_repr))
-    return nodes
+    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:
+        entry = self._entries.get(name)
+        if entry is None:
+            raise KeyError(name)
+        return entry.lock
+
+    def names(self) -> Iterator[str]:
+        with self._registry_lock:
+            return iter(tuple(self._entries))
+
+    def get(self, name: str, *, create: bool = True) -> Any:
+        entry = self._entries.get(name)
+        if entry is None:
+            raise KeyError(name)
+        with entry.lock:
+            value = self._storage.get(name)
+            if create and value is None:
+                value = entry.factory()
+                self._storage[name] = value
+            return value
 
+    def peek(self, name: str) -> Any:
+        return self.get(name, create=False)
 
-def cached_node_list(G: nx.Graph) -> tuple[Any, ...]:
-    """Public wrapper returning the cached node tuple for ``G``."""
+    def store(self, name: str, value: Any) -> None:
+        entry = self._entries.get(name)
+        if entry is None:
+            raise KeyError(name)
+        with entry.lock:
+            self._storage[name] = value
 
-    return _cache_node_list(G)
+    def update(
+        self,
+        name: str,
+        updater: Callable[[Any], Any],
+        *,
+        create: bool = True,
+    ) -> Any:
+        entry = self._entries.get(name)
+        if entry is None:
+            raise KeyError(name)
+        with entry.lock:
+            current = self._storage.get(name)
+            if create and current is None:
+                current = entry.factory()
+            new_value = updater(current)
+            self._storage[name] = new_value
+            return new_value
+
+    def clear(self, name: str | None = None) -> None:
+        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._storage.get(cache_name)
+                new_value = None
+                if entry.reset is not None:
+                    new_value = entry.reset(current)
+                if new_value is None:
+                    try:
+                        new_value = entry.factory()
+                    except Exception:
+                        self._storage.pop(cache_name, None)
+                        continue
+                self._storage[cache_name] = new_value
+
+    # ------------------------------------------------------------------
+    # 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:
+        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:
+        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:
+        metrics = self._ensure_metrics(name)
+        with metrics.lock:
+            metrics.evictions += int(amount)
+
+    def record_timing(self, name: str, duration: float) -> None:
+        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:
+        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]]:
+        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:
+        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:
+        with self._registry_lock:
+            self._metrics_publishers.append(publisher)
+
+    def publish_metrics(
+        self,
+        *,
+        publisher: Callable[[str, CacheStatistics], None] | None = None,
+    ) -> None:
+        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
+                    logging.getLogger(__name__).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,
+            )
 
 
-def _ensure_node_map(
-    G,
-    *,
-    attrs: tuple[str, ...],
-    sort: bool = False,
-) -> dict[Any, int]:
-    """Return cached node-to-index/offset mappings stored on ``NodeCache``."""
+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)
 
-    graph = G.graph
-    _cache_node_list(G)
-    cache: NodeCache = graph["_node_list_cache"]
 
-    missing = [attr for attr in attrs if getattr(cache, attr) is None]
-    if missing:
-        if sort:
-            nodes = cache.sorted_nodes
-            if nodes is None:
-                nodes = cache.sorted_nodes = tuple(
-                    sorted(cache.nodes, key=_node_repr)
-                )
-        else:
-            nodes = cache.nodes
-        mappings: dict[str, dict[Any, int]] = {attr: {} for attr in missing}
-        for idx, node in enumerate(nodes):
-            for attr in missing:
-                mappings[attr][node] = idx
-        for attr in missing:
-            setattr(cache, attr, mappings[attr])
-    return getattr(cache, attrs[0])
+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)
 
-def ensure_node_index_map(G) -> dict[Any, int]:
-    """Return cached node-to-index mapping for ``G``."""
 
-    return _ensure_node_map(G, attrs=("idx",), sort=False)
+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.
 
-def ensure_node_offset_map(G) -> dict[Any, int]:
-    """Return cached node-to-offset mapping for ``G``."""
+    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.
+    """
 
-    sort = bool(G.graph.get("SORT_NODES", False))
-    return _ensure_node_map(G, attrs=("offset",), sort=sort)
+    _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
 
-class EdgeCacheManager:
-    """Coordinate cache storage and per-key locks for edge version caches."""
+    @property
+    def telemetry_callbacks(self) -> tuple[Callable[[K, V], None], ...]:
+        """Return currently registered telemetry callbacks."""
 
-    _LOCK = threading.RLock()
+        return tuple(self._telemetry_callbacks)
 
-    def __init__(self, graph: Any) -> None:
-        self.graph = graph
-        self.cache_key = "_edge_version_cache"
-        self.locks_key = "_edge_version_cache_locks"
+    @property
+    def eviction_callbacks(self) -> tuple[Callable[[K, V], None], ...]:
+        """Return currently registered eviction callbacks."""
 
-    def _validator(self, max_entries: int | None) -> Callable[[Any], bool]:
-        if max_entries is None:
-            return lambda value: value is not None and not isinstance(value, LRUCache)
-        return lambda value: isinstance(value, LRUCache) and value.maxsize == max_entries
+        return tuple(self._eviction_callbacks)
 
-    def _factory(
-        self,
-        max_entries: int | None,
-        locks: dict[Hashable, threading.RLock]
-        | defaultdict[Hashable, threading.RLock],
-    ) -> dict[Hashable, Any] | LRUCache[Hashable, Any]:
-        if max_entries:
-            return LockAwareLRUCache(max_entries, locks)  # type: ignore[arg-type]
-        return {}
-
-    def get_cache(
+    def set_telemetry_callbacks(
         self,
-        max_entries: int | None,
-        *,
-        create: bool = True,
-    ) -> tuple[
-        dict[Hashable, Any] | LRUCache[Hashable, Any] | None,
-        dict[Hashable, threading.RLock]
-        | defaultdict[Hashable, threading.RLock]
+        callbacks: Iterable[Callable[[K, V], None]]
+        | Callable[[K, V], None]
         | None,
-    ]:
-        """Return the cache and lock mapping for the manager's graph."""
-
-        with self._LOCK:
-            if not create:
-                cache = self.graph.get(self.cache_key)
-                locks = self.graph.get(self.locks_key)
-                return cache, locks
-
-            locks = _ensure_lock_mapping(self.graph, self.locks_key)
-            cache = _ensure_graph_entry(
-                self.graph,
-                self.cache_key,
-                factory=lambda: self._factory(max_entries, locks),
-                validator=self._validator(max_entries),
-            )
-            if max_entries is None:
-                _prune_locks(cache, locks)
-            return cache, locks
-
-
-def edge_version_cache(
-    G: Any,
-    key: Hashable,
-    builder: Callable[[], T],
-    *,
-    max_entries: int | None = 128,
-) -> T:
-    """Return cached ``builder`` output tied to the edge version of ``G``."""
-
-    if max_entries is not None:
-        max_entries = int(max_entries)
-        if max_entries < 0:
-            raise ValueError("max_entries must be non-negative or None")
-    if max_entries is not None and max_entries == 0:
-        return builder()
-
-    graph = get_graph(G)
-    manager = graph.get("_edge_cache_manager")  # type: ignore[assignment]
-    if not isinstance(manager, EdgeCacheManager) or manager.graph is not graph:
-        manager = EdgeCacheManager(graph)
-        graph["_edge_cache_manager"] = manager
-
-    cache, locks = manager.get_cache(max_entries)
-    edge_version = get_graph_version(graph, "_edge_version")
-    lock = locks[key]
-
-    with lock:
-        entry = cache.get(key)
-        if entry is not None and entry[0] == edge_version:
-            return entry[1]
-
-    try:
-        value = builder()
-    except (RuntimeError, ValueError) as exc:  # pragma: no cover - logging side effect
-        logger.exception("edge_version_cache builder failed for %r: %s", key, exc)
-        raise
-    else:
-        with lock:
-            entry = cache.get(key)
-            if entry is not None and entry[0] == edge_version:
-                return entry[1]
-            cache[key] = (edge_version, value)
-            return value
-
-
-def cached_nodes_and_A(
-    G: nx.Graph, *, cache_size: int | None = 1, require_numpy: bool = False
-) -> tuple[tuple[Any, ...], Any]:
-    """Return cached nodes tuple and adjacency matrix for ``G``."""
-
-    nodes = cached_node_list(G)
-    graph = G.graph
+        *,
+        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
 
-    checksum = getattr(graph.get("_node_list_cache"), "checksum", None)
-    if checksum is None:
-        checksum = graph.get("_node_list_checksum")
-    if checksum is None:
-        node_set_cache = graph.get(NODE_SET_CHECKSUM_KEY)
-        if isinstance(node_set_cache, tuple) and len(node_set_cache) >= 2:
-            checksum = node_set_cache[1]
-    if checksum is None:
-        checksum = ""
+    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.
 
-    key = f"_dnfr_{len(nodes)}_{checksum}"
-    graph["_dnfr_nodes_checksum"] = checksum
+        Behaviour matches :meth:`set_telemetry_callbacks`.
+        """
 
-    def builder() -> tuple[tuple[Any, ...], Any]:
-        np = get_numpy()
-        if np is None:
-            return nodes, None
-        A = nx.to_numpy_array(G, nodelist=nodes, weight=None, dtype=float)
-        return nodes, A
+        new_callbacks = list(_normalise_callbacks(callbacks))
+        if append:
+            self._eviction_callbacks.extend(new_callbacks)
+        else:
+            self._eviction_callbacks = new_callbacks
 
-    nodes, A = edge_version_cache(G, key, builder, max_entries=cache_size)
+    # ------------------------------------------------------------------
+    # MutableMapping interface
 
-    if require_numpy and A is None:
-        raise RuntimeError("NumPy is required for adjacency caching")
+    def __getitem__(self, key: K) -> V:
+        return self._cache[key]
 
-    return nodes, A
+    def __setitem__(self, key: K, value: V) -> None:
+        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:
+        try:
+            value = self._cache[key]
+        except KeyError:
+            self._record_miss(1)
+            raise
+        del self._cache[key]
+        self._dispatch_removal(key, value, hits=1)
 
-def _reset_edge_caches(graph: Any, G: Any) -> None:
-    """Clear caches affected by edge updates."""
+    def __iter__(self) -> Iterator[K]:
+        return iter(self._cache)
 
-    cache, locks = EdgeCacheManager(graph).get_cache(None, create=False)
-    if isinstance(cache, (dict, LRUCache)):
-        cache.clear()
-    if isinstance(locks, dict):
-        locks.clear()
-    mark_dnfr_prep_dirty(G)
-    clear_node_repr_cache()
-    for key in EDGE_VERSION_CACHE_KEYS:
-        graph.pop(key, None)
+    def __len__(self) -> int:
+        return len(self._cache)
 
+    def __contains__(self, key: object) -> bool:
+        return key in self._cache
 
-def increment_edge_version(G: Any) -> None:
-    """Increment the edge version counter in ``G.graph``."""
+    def __repr__(self) -> str:  # pragma: no cover - debugging helper
+        return f"{self.__class__.__name__}({self._cache!r})"
 
-    graph = get_graph(G)
-    increment_graph_version(graph, "_edge_version")
-    _reset_edge_caches(graph, G)
+    # ------------------------------------------------------------------
+    # Cache helpers
 
+    @property
+    def maxsize(self) -> int:
+        return self._cache.maxsize
 
-@contextmanager
-def edge_version_update(G: Any):
-    """Scope a batch of edge mutations."""
+    @property
+    def currsize(self) -> int:
+        return self._cache.currsize
+
+    def get(self, key: K, default: V | None = None) -> V | None:
+        return self._cache.get(key, default)
+
+    def pop(self, key: K, default: Any = _MISSING) -> V:
+        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]:
+        return self._cache.popitem()
+
+    def clear(self) -> None:  # type: ignore[override]
+        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)
 
-    increment_edge_version(G)
-    try:
-        yield
-    finally:
-        increment_edge_version(G)
+    def popitem(self) -> tuple[K, V]:  # type: ignore[override]
+        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