feat(v7-i07): LRU cache stats — evictions + hit_rate dashboard

Closes V7-I07 (cppmega-mlx-zat0): operators had no way to see if the
JsonRPC LRU cache was helping or thrashing. Stats now expose:

  - hits          (incremented on get-key-present)
  - misses        (incremented on get-key-absent)
  - evictions     (incremented when set() bumps the oldest entry
                    out under the capacity bound) — NEW
  - hit_rate      = hits / (hits + misses), 0.0 when no traffic — NEW
  - size, capacity (existing)

Server /cache/stats GET annotation widened to dict[str, int | float]
so FastAPI accepts the float hit_rate field.

Tests (tests/v4/test_cache_stats.py): 5/5 —
  * Initial stats shape includes all six fields.
  * Repeat get on the same key bumps hits; missing key bumps misses;
    hit_rate = 2/3 after 2 hits + 1 miss.
  * Capacity-2 cache with 4 inserts → 2 evictions.
  * clear() resets all counters to 0.
  * FastAPI /cache/stats endpoint returns all six keys.
- Full cache + jsonrpc regression: 118/118 passing.

Author: apstenku123

cppmega_v4/jsonrpc/cache.py

@@ -84,6 +84,9 @@ def __init__(self, capacity: int = DEFAULT_CAPACITY) -> None:
         self._lock = Lock()
         self._hits = 0
         self._misses = 0
+        # V7-I07: count entries evicted by LRU bound (oldest popped
+        # to make room for newer set()).
+        self._evictions = 0
 
     @property
     def capacity(self) -> int:
@@ -121,18 +124,23 @@ def set(self, key: str, value: Any) -> None:
             self._data[key] = snapshot
             if len(self._data) > self._capacity:
                 self._data.popitem(last=False)
+                self._evictions += 1
 
     def clear(self) -> None:
         with self._lock:
             self._data.clear()
             self._hits = 0
             self._misses = 0
+            self._evictions = 0
 
-    def stats(self) -> dict[str, int]:
+    def stats(self) -> dict[str, int | float]:
         with self._lock:
+            total = self._hits + self._misses
             return {
                 "size": len(self._data),
                 "capacity": self._capacity,
                 "hits": self._hits,
                 "misses": self._misses,
+                "evictions": self._evictions,
+                "hit_rate": (self._hits / total) if total > 0 else 0.0,
             }

cppmega_v4/jsonrpc/server.py

@@ -63,7 +63,7 @@ def methods() -> dict[str, list[str]]:
         return {"methods": sorted(METHOD_REGISTRY)}
 
     @app.get("/cache/stats")
-    def cache_stats() -> dict[str, int]:
+    def cache_stats() -> dict[str, int | float]:
         return cache.stats()
 
     @app.post("/cache/clear")

tests/v4/test_cache_stats.py

@@ -0,0 +1,79 @@
+"""V7-I07: LRUCache exposes hits/misses/evictions/hit_rate."""
+
+from __future__ import annotations
+
+from cppmega_v4.jsonrpc.cache import LRUCache
+
+
+def test_v7_i07_stats_initial_shape():
+    c = LRUCache(capacity=4)
+    s = c.stats()
+    for k in ("size", "capacity", "hits", "misses",
+              "evictions", "hit_rate"):
+        assert k in s
+    assert s["capacity"] == 4
+    assert s["size"] == 0
+    assert s["hits"] == 0
+    assert s["misses"] == 0
+    assert s["evictions"] == 0
+    assert s["hit_rate"] == 0.0
+
+
+def test_v7_i07_hits_increment_on_repeat_get():
+    c = LRUCache(capacity=4)
+    c.set("k1", {"v": 1})
+    # First get → hit.
+    assert c.get("k1") is not None
+    assert c.stats()["hits"] == 1
+    # Second get → hit again.
+    assert c.get("k1") is not None
+    assert c.stats()["hits"] == 2
+    # Missing key → miss.
+    assert c.get("k_other") is None
+    assert c.stats()["misses"] == 1
+    s = c.stats()
+    # 2 hits / (2 + 1) = 0.6667
+    assert abs(s["hit_rate"] - 2 / 3) < 1e-6
+
+
+def test_v7_i07_evictions_increment_when_capacity_exceeded():
+    c = LRUCache(capacity=2)
+    c.set("a", 1)
+    c.set("b", 2)
+    assert c.stats()["evictions"] == 0
+    c.set("c", 3)  # bumps 'a' out
+    assert c.stats()["evictions"] == 1
+    c.set("d", 4)  # bumps 'b' out
+    assert c.stats()["evictions"] == 2
+    assert c.stats()["size"] == 2
+
+
+def test_v7_i07_clear_resets_counters():
+    c = LRUCache(capacity=2)
+    c.set("a", 1)
+    c.get("a")
+    c.get("nothing")
+    c.set("b", 2)
+    c.set("c", 3)
+    assert c.stats()["evictions"] >= 1
+    c.clear()
+    s = c.stats()
+    assert s["hits"] == 0
+    assert s["misses"] == 0
+    assert s["evictions"] == 0
+    assert s["size"] == 0
+
+
+def test_v7_i07_http_cache_stats_endpoint_contains_v7_fields():
+    """Sanity that the FastAPI /cache/stats hook returns the V7 keys."""
+    from fastapi.testclient import TestClient
+    from cppmega_v4.jsonrpc.server import create_app
+
+    app = create_app()
+    client = TestClient(app)
+    r = client.get("/cache/stats")
+    assert r.status_code == 200
+    body = r.json()
+    for k in ("hits", "misses", "evictions", "hit_rate",
+              "size", "capacity"):
+        assert k in body, f"missing {k} in /cache/stats response"