feat(v7-i07): cache.metrics RPC twin of GET /cache/stats

Closes plan item #46 / bd cppmega-mlx-oqpe.

The UI BottomStrip already polls GET /cache/stats via useCacheStats
for the cache hit-rate dashboard pill. Add a JSON-RPC twin so all UI
surfaces / agents that talk through dispatch (not the HTTP REST
shim) can read the same snapshot:

- cppmega_v4/jsonrpc/cache_metrics_method.py: CacheMetricsParams +
  CacheMetricsResult dataclasses; cache_metrics(params, cache=...)
  returns size / capacity / hits / misses / evictions / hit_rate.
  Safe fallback to zeros when cache is None.
- Dispatcher route 'cache.metrics' wired.
- 5 pytest cover: empty cache zeros, hit/miss/hit_rate accounting,
  eviction counting under tight capacity, missing-cache fallback,
  dispatcher route round-trip with a populated cache.

bd: cppmega-mlx-oqpe

Author: apstenku123

cppmega_v4/jsonrpc/cache_metrics_method.py

@@ -0,0 +1,50 @@
+"""V7-I07: cache.metrics RPC — surfaces LRU cache hit-rate to the UI.
+
+The dispatcher already shares a single LRUCache across handlers. This
+RPC reads its stats() snapshot so the BottomStrip can render hit-rate
++ size as a tiny dashboard. Reads only; no mutation.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+from cppmega_v4.jsonrpc.cache import LRUCache
+
+
+class CacheMetricsParams(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class CacheMetricsResult(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    size: int
+    capacity: int
+    hits: int
+    misses: int
+    evictions: int
+    hit_rate: float
+
+
+def cache_metrics(
+    params: CacheMetricsParams,
+    *, cache: LRUCache | None = None,
+) -> CacheMetricsResult:
+    if cache is None:
+        return CacheMetricsResult(
+            size=0, capacity=0, hits=0, misses=0,
+            evictions=0, hit_rate=0.0,
+        )
+    s = cache.stats()
+    return CacheMetricsResult(
+        size=int(s["size"]),
+        capacity=int(s["capacity"]),
+        hits=int(s["hits"]),
+        misses=int(s["misses"]),
+        evictions=int(s["evictions"]),
+        hit_rate=float(s["hit_rate"]),
+    )
+
+
+__all__ = ["CacheMetricsParams", "CacheMetricsResult", "cache_metrics"]

cppmega_v4/jsonrpc/dispatcher.py

@@ -67,6 +67,10 @@
     LossSurfaceParams,
     loss_surface_run,
 )
+from cppmega_v4.jsonrpc.cache_metrics_method import (
+    CacheMetricsParams,
+    cache_metrics,
+)
 from cppmega_v4.jsonrpc.tokenizer_roundtrip_text_method import (
     TokenizerRoundtripTextParams,
     roundtrip_text,
@@ -196,6 +200,10 @@
         LossSurfaceParams,
         lambda p, c: loss_surface_run(p, cache=c),
     ),
+    "cache.metrics": (
+        CacheMetricsParams,
+        lambda p, c: cache_metrics(p, cache=c),
+    ),
     "tokenizer.roundtrip_text": (
         TokenizerRoundtripTextParams,
         lambda p, c: roundtrip_text(p, cache=c),

tests/v4/test_cache_metrics_rpc.py

@@ -0,0 +1,67 @@
+"""V7-I07: cache.metrics JSON-RPC returns LRUCache stats snapshot."""
+
+from __future__ import annotations
+
+from cppmega_v4.jsonrpc.cache import LRUCache
+from cppmega_v4.jsonrpc.cache_metrics_method import (
+    CacheMetricsParams, cache_metrics,
+)
+from cppmega_v4.jsonrpc.dispatcher import dispatch
+
+
+def test_v7_i07_cache_metrics_returns_zeros_for_empty():
+    cache = LRUCache(capacity=8)
+    r = cache_metrics(CacheMetricsParams(), cache=cache)
+    assert r.size == 0
+    assert r.capacity == 8
+    assert r.hits == 0
+    assert r.misses == 0
+    assert r.evictions == 0
+    assert r.hit_rate == 0.0
+
+
+def test_v7_i07_cache_metrics_counts_hits_misses():
+    cache = LRUCache(capacity=4)
+    cache.set("a", {"v": 1})
+    cache.get("a")          # hit
+    cache.get("a")          # hit
+    cache.get("missing")    # miss
+    r = cache_metrics(CacheMetricsParams(), cache=cache)
+    assert r.size == 1
+    assert r.hits == 2
+    assert r.misses == 1
+    assert abs(r.hit_rate - (2 / 3)) < 1e-9
+
+
+def test_v7_i07_cache_metrics_counts_evictions():
+    cache = LRUCache(capacity=2)
+    cache.set("a", 1)
+    cache.set("b", 2)
+    cache.set("c", 3)  # evicts a
+    cache.set("d", 4)  # evicts b
+    r = cache_metrics(CacheMetricsParams(), cache=cache)
+    assert r.size == 2
+    assert r.evictions == 2
+
+
+def test_v7_i07_cache_metrics_handles_missing_cache():
+    r = cache_metrics(CacheMetricsParams(), cache=None)
+    assert r.size == 0
+    assert r.hits == 0
+    assert r.misses == 0
+    assert r.hit_rate == 0.0
+
+
+def test_v7_i07_dispatcher_routes_cache_metrics():
+    cache = LRUCache(capacity=4)
+    cache.set("a", 1)
+    cache.get("a")
+    resp = dispatch({
+        "jsonrpc": "2.0", "id": "T1", "method": "cache.metrics",
+        "params": {},
+    }, cache=cache)
+    assert resp.error is None, resp.error
+    assert resp.result is not None
+    assert resp.result["hits"] == 1
+    assert resp.result["size"] == 1
+    assert resp.result["capacity"] == 4