superlocalmemory 3.6.8 → 3.6.10

package/src/superlocalmemory/optimize/cache/manager.py

@@ -2,12 +2,17 @@
 
 from __future__ import annotations
 
+import hashlib as _hashlib
+import json as _json_mod
 import logging
 import threading
 import time
 from abc import ABC, abstractmethod
 from typing import Any, Callable
 
+# C-08: precomputed hash for the common "default" tenant — avoids sha256 on every request
+_DEFAULT_TENANT_HASH: str = _hashlib.sha256(b"default").hexdigest()
+
 from superlocalmemory.optimize.cache.exact import ExactCache
 from superlocalmemory.optimize.cache.invalidation import InvalidationEngine
 from superlocalmemory.optimize.cache.key_builder import CacheConfig, KeyBuilder
@@ -230,6 +235,26 @@ class CacheManager:
                 ttl_seconds=0,
             )
         self._metrics.exact_misses += 1
+
+        # C-01: semantic fallback on exact miss (only when explicitly enabled)
+        if self._semantic.is_enabled():
+            try:
+                sem_result = self._semantic.lookup(req, tenant_id, None)
+                if sem_result is not None:
+                    self._metrics.semantic_hits += 1
+                    if isinstance(sem_result, CachedResponse):
+                        return sem_result
+                    # VCacheSemantic may return a response dict — wrap it
+                    return CachedResponse(
+                        hit=True,
+                        data=_json_mod.dumps(sem_result, ensure_ascii=False).encode(),
+                        cache_key=key,
+                        ttl_seconds=0,
+                    )
+            except Exception as exc:
+                logger.warning("SemanticTier.lookup raised (fail-open): %s", exc)
+            self._metrics.semantic_misses += 1
+
         # Return miss WITH the key so callers can use it for cache storage.
         return CachedResponse(hit=False, data=None, cache_key=key, ttl_seconds=0)
 
@@ -258,6 +283,13 @@ class CacheManager:
         self._invalidation.register(key, tenant_id, tags)
         self._metrics.sets += 1
 
+        # C-02: index in semantic tier after exact write (fail-open)
+        if self._semantic.is_enabled():
+            try:
+                self._semantic.index_entry(req, tenant_id, None, response_dict)
+            except Exception as exc:
+                logger.warning("SemanticTier.index_entry raised (fail-open): %s", exc)
+
     # ---- CacheHook protocol implementation (INTERFACE-CONTRACT §3) ----
 
     def check(self, req: ProxyRequest) -> "CachedResponse | None":
@@ -269,7 +301,7 @@ class CacheManager:
         cache-miss result.
         """
         try:
-            result = self.get(req, tenant_id="default")
+            result = self.get(req, tenant_id=_DEFAULT_TENANT_HASH)
             if result is not None and not result.hit:
                 MetricsCollector.get_instance().on_miss()
             return result
@@ -280,21 +312,51 @@ class CacheManager:
     def store(self, req: ProxyRequest, resp: ProviderResponse) -> None:
         """CacheHook.store() — persist response; fail-open on error."""
         try:
-            self.set(req, resp, tenant_id="default")
+            self.set(req, resp, tenant_id=_DEFAULT_TENANT_HASH)
         except Exception as exc:
             logger.warning("CacheManager.store raised (fail-open): %s", exc)
 
     def on_hit(self, req: ProxyRequest, resp: bytes, tokens_saved: int) -> None:
         """CacheHook.on_hit() — forward token savings to MetricsCollector.
-        
-        Contract §7: cache skip saves BOTH input+output tokens (whole call avoided).
-        tokens_saved = input tokens saved (from request).
-        Output tokens estimated from response body size (~4 bytes per token).
+
+        M-01: compute input tokens from request body when caller passes 0.
+        M-02: parse real output tokens from cached response usage field.
+        All counts are estimates for display — not billing-accurate.
         """
+        import json as _json
+
+        # M-01: estimate input tokens from message content
+        if tokens_saved == 0 and isinstance(req, ProxyRequest):
+            try:
+                body = req.body or {}
+                total_chars = 0
+                for m in (body.get("messages") or []):
+                    c = m.get("content", "")
+                    if isinstance(c, str):
+                        total_chars += len(c)
+                    elif isinstance(c, list):
+                        for blk in c:
+                            if isinstance(blk, dict):
+                                total_chars += len(blk.get("text", "") or "")
+                total_chars += len(body.get("system", "") or "")
+                tokens_saved = max(0, total_chars // 4)
+            except Exception:
+                pass
+
+        # M-02: parse real output tokens from stored response
         output_tokens = 0
         if resp:
-            # Rough estimate: 4 bytes per token for English text
-            output_tokens = len(resp) // 4
+            try:
+                data = _json.loads(resp)
+                usage = data.get("usage") or {}
+                output_tokens = (
+                    usage.get("output_tokens")
+                    or usage.get("completion_tokens")
+                    or 0
+                )
+            except Exception:
+                output_tokens = len(resp) // 4  # fallback byte-estimate
+
         MetricsCollector.get_instance().on_hit(
             tokens_saved_input=tokens_saved,
             tokens_saved_output=output_tokens,

package/src/superlocalmemory/optimize/cache/semantic.py

@@ -294,7 +294,8 @@ class VCacheSemantic(SemanticTier):
         # Step 5: vCache exploit/explore (MLE τ̂ via record_outcome updates)
         record = self._boundary_store.get(best_entry_id)
         delta = float(getattr(cfg, "semantic_error_target", _DEFAULT_ERROR_TARGET))
-        if record.should_explore(best_score, delta=delta):
+        sem_return_threshold = float(getattr(cfg, "semantic_return_threshold", _DEFAULT_RETURN_THRESHOLD))
+        if record.should_explore(best_score, delta=delta, return_threshold=sem_return_threshold):
             logger.debug(
                 "VCacheSemantic: explore (score=%.4f entry=%s t_hat=%.4f)",
                 best_score, best_entry_id, record.t_hat,
@@ -363,11 +364,11 @@ class VCacheSemantic(SemanticTier):
                     self._index[tenant_id] = []
                 return
             entries: list[tuple[str, str, np.ndarray]] = []
-            for entry_id, blob in rows:
+            for entry_id, blob, ctx_fp in rows:  # C-10: unpack persisted context_fp
                 try:
                     v = np.frombuffer(blob, dtype=np.float32).copy()
                     if v.shape[0] == _EMBED_DIM:
-                        entries.append((entry_id, "", v))
+                        entries.append((entry_id, ctx_fp, v))
                 except Exception:
                     continue
             with self._index_lock:
@@ -422,13 +423,17 @@ class VCacheSemantic(SemanticTier):
             )
             return
 
-        # Store vector in DB
+        # Store vector in DB — C-10: persist context_fp alongside the vector
         vec_bytes = vec.tobytes()
         self._db.vec_add(
             entry_id=entry_id,
             tenant_id=tenant_id,
             vector=vec_bytes,
-            meta={"model": "nomic-ai/nomic-embed-text-v1.5", "dim": _EMBED_DIM},
+            meta={
+                "model": "nomic-ai/nomic-embed-text-v1.5",
+                "dim": _EMBED_DIM,
+                "context_fp": context_fp,
+            },
         )
 
         # Initialize boundary record if new

package/src/superlocalmemory/optimize/compress/prose_llmlingua.py

@@ -32,16 +32,10 @@ class LLMLinguaCompressor:
 
     def __init__(
         self,
-        model_name: str = _MODEL_BERT,
+        model_name: str = _MODEL_XLM,
         device_map: str = "cpu",
         rate: float = _DEFAULT_RATE,
     ) -> None:
-        import os
-        if os.environ.get("SLM_DISABLE_HF_DOWNLOAD", "0") == "1":
-            raise ImportError(
-                "LLMLingua-2 model download blocked: SLM_DISABLE_HF_DOWNLOAD=1. "
-                "Set compress_llmlingua_allow_download=true in optimize.json."
-            )
         try:
             from llmlingua import PromptCompressor  # type: ignore[import]
         except ImportError as e:

package/src/superlocalmemory/optimize/compress/router.py

@@ -26,7 +26,6 @@ from superlocalmemory.optimize.config.store import ConfigStore
 logger = logging.getLogger("slm.optimize.compress.router")
 
 _MIN_CHARS_FOR_COMPRESSION: int = 500
-_MIN_RATIO_STRUCTURED: float = 0.60
 
 
 class CompressRouter:
@@ -50,8 +49,6 @@ class CompressRouter:
         return cls._instance
 
     def __init__(self) -> None:
-        self._json_compressor: "JSONCompressor | None" = None
-        self._code_compressor: "CodeCompressor | None" = None
         self._llmlingua_compressor: "LLMLinguaCompressor | None" = None
         self._ccr_store: "CCRStore | None" = None
         self._aligner: "CacheAligner | None" = None
@@ -103,12 +100,17 @@ class CompressRouter:
                 tenant_id="default",
             )
 
-            if tokens_after >= tokens_before:
-                return req  # no improvement
-
+            # S-01/Stage-9 fix: build new_bytes BEFORE the improvement guard.
+            # Layer 1 normalization saves characters (not word-count tokens), so
+            # tokens_after == tokens_before for "normalize" strategy. Checking byte
+            # length of the serialized body correctly detects Layer 1 savings.
             body["messages"] = new_messages
             new_bytes = json.dumps(body, ensure_ascii=False, separators=(",", ":")).encode()
 
+            bytes_saved = len(req.body_bytes) - len(new_bytes)
+            if bytes_saved <= 0 and tokens_after >= tokens_before:
+                return req  # neither bytes nor tokens improved
+
             # CONTRACT §3: fire on_compress metrics callback
             lossy = strategy == "llmlingua2_prose"
             self.on_compress(tokens_before, tokens_after, lossy)
@@ -160,7 +162,12 @@ class CompressRouter:
         primary_strategy = "none"
         new_messages: list[dict[str, Any]] = []
 
-        protect_indices = set(range(max(0, len(messages) - protect_recent), len(messages)))
+        # K-05: protect last N *user* turns, not last N messages of any role
+        user_indices = [i for i, m in enumerate(messages) if m.get("role") == "user"]
+        protect_indices: set[int] = set(user_indices[-protect_recent:]) if protect_recent > 0 else set()
+        # Always protect the very last message (current turn, any role)
+        if messages:
+            protect_indices.add(len(messages) - 1)
 
         for idx, msg in enumerate(messages):
             role = msg.get("role", "")
@@ -248,96 +255,77 @@ class CompressRouter:
     ) -> tuple[str, int, int, str]:
         tokens_before = _token_estimate(text)
 
-        # JSON detection
+        if len(text) < _MIN_CHARS_FOR_COMPRESSION:
+            return text, tokens_before, tokens_before, "none"
+
+        # K-01/K-02/K-03: NEVER compress structured content (JSON or code)
         stripped = text.strip()
         if stripped.startswith(("{", "[")):
+            # PERF-02: for large content, structural bracket-match avoids O(n) json.loads().
+            # Conservative: matching outer brackets → treat as JSON and skip compression.
+            # K-01 mandate is safety-first: false-positive (non-JSON treated as JSON) is
+            # safe; false-negative (JSON compressed) would be a correctness violation.
+            _last = stripped[-1] if stripped else ""
+            if len(stripped) > 8192 and (
+                (stripped[0] == "{" and _last == "}") or (stripped[0] == "[" and _last == "]")
+            ):
+                return text, tokens_before, tokens_before, "none"  # large JSON → passthrough
             try:
-                parsed = json.loads(stripped)
-                compressor = self._get_json_compressor()
-                compressed = compressor.compress(parsed)
-                tokens_after = _token_estimate_structured(compressed)
-                tokens_before_adj = _token_estimate_structured(text)
-                ratio = tokens_after / tokens_before_adj if tokens_before_adj else 1.0
-                if ratio < _MIN_RATIO_STRUCTURED:
-                    # B-03: store-before-compress
-                    ccr_id = self._ccr_store_original(text.encode(), model, tenant_id)
-                    if ccr_id:
-                        try:
-                            obj = json.loads(compressed)
-                            if isinstance(obj, dict):
-                                obj["__slm_ccr__"] = ccr_id
-                                compressed = json.dumps(obj, ensure_ascii=False, separators=(",", ":"))
-                            elif isinstance(obj, list):
-                                # RB-02: list-root embedding
-                                wrapper = {"__slm_ccr__": ccr_id, "__slm_data__": obj}
-                                compressed = json.dumps(wrapper, ensure_ascii=False, separators=(",", ":"))
-                        except Exception:
-                            pass
-                        self._ccr_update_compressed(ccr_id, compressed.encode())
-                    logger.debug("[%s] JSON compressed %.2f ratio ccr_id=%s", request_id, ratio, ccr_id)
-                    return compressed, tokens_before_adj, tokens_after, "extractive_json"
-                return text, tokens_before, tokens_before, "none"
-            except (json.JSONDecodeError, Exception):
-                pass
-
-        # Code detection
-        lang = _detect_language(text)
-        if lang is not None:
-            compressor = self._get_code_compressor()
-            # RB-03: compress first, compute ratio, then store CCR only if beneficial
-            compressed_probe = compressor.compress(text, language=lang, ccr_id="")
-            tokens_after = _token_estimate(compressed_probe)
-            ratio = tokens_after / tokens_before if tokens_before else 1.0
-            if ratio < _MIN_RATIO_STRUCTURED:
-                # B-03: store-before-compress
-                ccr_id = self._ccr_store_original(text.encode(), model, tenant_id)
-                compressed = compressor.compress(text, language=lang, ccr_id=ccr_id)
-                if ccr_id:
-                    self._ccr_update_compressed(ccr_id, compressed.encode())
-                logger.debug("[%s] Code compressed lang=%s ratio=%.2f ccr_id=%s",
-                             request_id, lang, ratio, ccr_id)
-                return compressed, tokens_before, tokens_after, "extractive_code"
-            return text, tokens_before, tokens_before, "none"
+                json.loads(stripped)
+                return text, tokens_before, tokens_before, "none"  # valid JSON → passthrough
+            except json.JSONDecodeError:
+                pass  # not valid JSON — treat as prose
+            except Exception as exc:
+                logger.warning("compress: unexpected error probing JSON content: %s", exc)
+
+        if _detect_language(text) is not None:
+            return text, tokens_before, tokens_before, "none"  # code → passthrough
+
+        # Layer 1 — lossless whitespace normalization (always-on, safe)
+        normalized = self._normalize_whitespace(text)
+        tokens_after_l1 = _token_estimate(normalized)
 
-        # Prose: only if aggressive mode AND compress_prose is enabled
-        # (Phase 3 — opt-in prose tier; off by default; gated by config
-        # field compress_prose added in LLD-04 INTERFACE-CONTRACT v2.)
+        # Layer 2 — LLMLingua-2 prose compression (aggressive + opt-in only)
         cfg = self._get_config()
         prose_enabled = bool(getattr(cfg, "compress_prose", False))
-        if aggressive and prose_enabled:
+        if aggressive and prose_enabled:  # pragma: no cover — LLMLingua optional dep
             compressor = self._get_llmlingua_compressor()
             if compressor is not None:
-                # B-03: store-before-compress
+                # B-03: store original BEFORE lossy compression
                 ccr_id = self._ccr_store_original(text.encode(), model, tenant_id)
-                compressed = compressor.compress(text)
+                compressed = compressor.compress(normalized)
                 if ccr_id:
                     self._ccr_update_compressed(ccr_id, compressed.encode())
-                tokens_after = _token_estimate(compressed)
-                logger.info(
-                    "[%s] LLMLingua-2 prose compressed rate=%.2f ccr_id=%s (LOSSY)",
-                    request_id,
-                    tokens_after / tokens_before if tokens_before else 1.0,
-                    ccr_id,
-                )
-                return compressed, tokens_before, tokens_after, "llmlingua2_prose"
+                tokens_after_l2 = _token_estimate(compressed)
+                if tokens_after_l2 < tokens_before:
+                    logger.info(
+                        "[%s] LLMLingua-2 prose compressed rate=%.2f ccr_id=%s (LOSSY)",
+                        request_id,
+                        tokens_after_l2 / tokens_before if tokens_before else 1.0,
+                        ccr_id,
+                    )
+                    return compressed, tokens_before, tokens_after_l2, "llmlingua2_prose"
 
-        return text, tokens_before, tokens_before, "none"
+        # S-01 fix: compare character length, not word count.
+        # _token_estimate() is word-count — whitespace normalization saves characters/bytes
+        # but never removes words, so token counts are identical before and after Layer 1.
+        # Character comparison correctly detects when normalization reduced the body size.
+        if len(normalized) < len(text):
+            return normalized, tokens_before, tokens_after_l1, "normalize"
 
-    # ── Lazy loaders ─────────────────────────────────────────────────────
+        return text, tokens_before, tokens_before, "none"
 
-    def _get_json_compressor(self) -> "JSONCompressor":
-        if self._json_compressor is None:
-            from superlocalmemory.optimize.compress.extractive_json import JSONCompressor
-            self._json_compressor = JSONCompressor()
-        return self._json_compressor
+    @staticmethod
+    def _normalize_whitespace(text: str) -> str:
+        """Layer 1 lossless: collapse excess blank lines, strip trailing spaces per line."""
+        import re
+        text = re.sub(r"\n{3,}", "\n\n", text)
+        lines = [line.rstrip() for line in text.split("\n")]
+        return "\n".join(lines)
 
-    def _get_code_compressor(self) -> "CodeCompressor":
-        if self._code_compressor is None:
-            from superlocalmemory.optimize.compress.extractive_code import CodeCompressor
-            self._code_compressor = CodeCompressor()
-        return self._code_compressor
+    # ── Lazy loaders ─────────────────────────────────────────────────────
 
-    def _get_llmlingua_compressor(self) -> "LLMLinguaCompressor | None":
+    def _get_llmlingua_compressor(self) -> "LLMLinguaCompressor | None":  # pragma: no cover
         if self._llmlingua_compressor is None:
             try:
                 from superlocalmemory.optimize.compress.prose_llmlingua import LLMLinguaCompressor
@@ -396,21 +384,32 @@ class CompressRouter:
             return CompressTextResult(
                 compressed_text=compressed, strategy=strat,
                 tokens_before=tb, tokens_after=ta,
+                lossy=strat == "llmlingua2_prose",
             )
         except Exception as exc:
             logger.debug("compress_text failed (non-fatal): %s", exc)
+            t = _token_estimate(text)
             return CompressTextResult(
                 compressed_text=text, strategy="none",
-                tokens_before=len(text.split()), tokens_after=len(text.split()),
+                tokens_before=t, tokens_after=t,
+                lossy=False,
             )
 
 
 @dataclass
 class CompressTextResult:
+    """Result of a compress_text() call.
+
+    UX-02 note: lossy=True only when strategy="llmlingua2_prose" (Layer 2).
+    In the default install (LLMLingua optional dep not installed), lossy is
+    always False — install `llmlingua>=0.2.0` and set compress_prose=True +
+    compress_mode="aggressive" to activate lossy compression.
+    """
     compressed_text: str
-    strategy: str  # "extractive_json" | "extractive_code" | "llmlingua2_prose" | "none"
+    strategy: str  # "normalize" | "llmlingua2_prose" | "none"
     tokens_before: int
     tokens_after: int
+    lossy: bool = False  # K-10: True only for llmlingua2_prose (Layer 2)
 
 
 # ── Module-level helpers ──────────────────────────────────────────────────────
@@ -419,10 +418,6 @@ def _token_estimate(text: str) -> int:
     return len(text.split()) if text else 0
 
 
-def _token_estimate_structured(text: str) -> int:
-    return max(1, len(text) // 4) if text else 0
-
-
 def _msg_has_tool_result(msg: dict) -> bool:
     """B-09: Detect historical tool_result blocks in messages."""
     content = msg.get("content", "")

package/src/superlocalmemory/optimize/config/__init__.py

@@ -24,6 +24,22 @@ def load_optimize_config() -> OptimizeConfig:
     return get_optimize_config()
 
 
+def get_shared_store() -> "ConfigStore":
+    """Return the process-wide ConfigStore singleton, creating it on first use.
+
+    This is the SINGLE instance the daemon, the /api/optimize routes, the proxy
+    hook-reload callback, and the hot-reload watchdog must all share so that a UI
+    config change reaches the live proxy (fixes W-02 hot-reload + W-05 fresh-store
+    -per-request). The daemon calls this at startup, registers a change callback,
+    and starts the watchdog.
+    """
+    global _store
+    if _store is None:
+        from superlocalmemory.optimize.config.store import ConfigStore
+        _store = ConfigStore()
+    return _store
+
+
 def _set_config_store(store: "ConfigStore") -> None:
     global _store
     _store = store

package/src/superlocalmemory/optimize/config/defaults.py

@@ -23,15 +23,10 @@ DEFAULT_OPTIMIZE_CONFIG = OptimizeConfig(
     semantic_boundary_floor=0.85,
     semantic_pad_latency_ms=0.0,
     semantic_centroid_min_similarity=0.85,
-    compress_enabled=True,
+    compress_enabled=False,
     compress_mode="safe",
-    compress_code=True,
-    compress_json=True,
     compress_prose=False,
-    compress_ccr=True,
-    compress_align=True,
     compress_protect_recent=4,
-    compress_llmlingua_allow_download=False,
     ttl_seconds=86400,
     ttl=TTLConfig(),
     providers={

package/src/superlocalmemory/optimize/config/schema.py

@@ -89,15 +89,10 @@ class OptimizeConfig:
     semantic_centroid_min_similarity: float = 0.85
 
     # Compress
-    compress_enabled: bool = True
+    compress_enabled: bool = False
     compress_mode: str = "safe"
-    compress_code: bool = True
-    compress_json: bool = True
     compress_prose: bool = False
-    compress_ccr: bool = True
-    compress_align: bool = True
     compress_protect_recent: int = 4
-    compress_llmlingua_allow_download: bool = False
 
     # TTL + providers + pricing
     ttl_seconds: int = 86400
@@ -182,17 +177,10 @@ class OptimizeConfig:
             semantic_centroid_min_similarity=float(
                 d.get("semantic_centroid_min_similarity", 0.85)
             ),
-            compress_enabled=bool(d.get("compress_enabled", True)),
+            compress_enabled=bool(d.get("compress_enabled", False)),
             compress_mode=str(d.get("compress_mode", "safe")),
-            compress_code=bool(d.get("compress_code", True)),
-            compress_json=bool(d.get("compress_json", True)),
             compress_prose=bool(d.get("compress_prose", False)),
-            compress_ccr=bool(d.get("compress_ccr", True)),
-            compress_align=bool(d.get("compress_align", True)),
             compress_protect_recent=int(d.get("compress_protect_recent", 4)),
-            compress_llmlingua_allow_download=bool(
-                d.get("compress_llmlingua_allow_download", False)
-            ),
             ttl_seconds=int(d.get("ttl_seconds", 86400)),
             providers=providers,
             pricing=dict(d.get("pricing", {})),
@@ -230,13 +218,8 @@ class OptimizeConfig:
             "semantic_centroid_min_similarity": self.semantic_centroid_min_similarity,
             "compress_enabled": self.compress_enabled,
             "compress_mode": self.compress_mode,
-            "compress_code": self.compress_code,
-            "compress_json": self.compress_json,
             "compress_prose": self.compress_prose,
-            "compress_ccr": self.compress_ccr,
-            "compress_align": self.compress_align,
             "compress_protect_recent": self.compress_protect_recent,
-            "compress_llmlingua_allow_download": self.compress_llmlingua_allow_download,
             "ttl_seconds": self.ttl_seconds,
             "providers": {k: v.as_dict() for k, v in self.providers.items()},
             "pricing": self.pricing,

package/src/superlocalmemory/optimize/config/store.py

@@ -74,7 +74,13 @@ class ConfigStore:
             return self._current_config
 
     def save(self, config: OptimizeConfig) -> None:
-        """Write config to optimize.json with version bump."""
+        """Write config to optimize.json with version bump.
+
+        Fires registered change callbacks immediately after a successful write
+        (outside the lock) so a UI/CLI save reaches the live proxy without
+        waiting for the 2s watchdog poll. The watchdog skips this write via
+        ``_saved_by_self`` so callbacks fire exactly once.
+        """
         config.validate()
         with self._lock:
             new_version = self._version + 1
@@ -93,6 +99,14 @@ class ConfigStore:
                 self._version = new_version
             finally:
                 self._saved_by_self = False
+            callbacks = list(self._change_callbacks)
+        # Fire callbacks OUTSIDE the lock — a callback may rebuild proxy hooks
+        # or call back into get(); keeping them off the lock avoids contention.
+        for cb in callbacks:
+            try:
+                cb(new_cfg)
+            except Exception as exc:
+                logger.warning("ConfigStore save callback error: %s", exc)
 
     def start_watchdog(self) -> None:
         """Start the background hot-reload watchdog thread.

package/src/superlocalmemory/optimize/metrics/counters.py

@@ -24,7 +24,7 @@ class MetricsCollector:
     Hook binding (from INTERFACE-CONTRACT §3):
         on_hit(tokens_saved_input, tokens_saved_output):  cache hit
         on_miss():                                         cache miss
-        on_compress(bytes_original, bytes_after):          compress ran
+        on_compress(tokens_before, tokens_after):          compress ran (word-count proxy)
         on_eviction():                                     entry expired/evicted
     """
 
@@ -69,20 +69,28 @@ class MetricsCollector:
         with self._data_lock:
             self._misses += 1
 
-    def on_compress(self, bytes_original: int, bytes_after: int) -> None:
-        """Record a compression run with byte counts."""
+    def on_compress(self, tokens_before: int, tokens_after: int) -> None:
+        """Record a compression run. Arguments are word-count proxy estimates from _token_estimate().
+
+        M-03: consistent naming — these are token estimates, not byte counts.
+        Stored in compress_bytes_original/after fields for DB schema compat; unit is word-count.
+        """
         with self._data_lock:
             self._compress_runs += 1
-            self._compress_bytes_original += max(0, bytes_original)
-            self._compress_bytes_after += max(0, bytes_after)
-            saved_tokens = max(0, bytes_original - bytes_after)
-            self._tokens_saved_compress += saved_tokens
+            self._compress_bytes_original += max(0, tokens_before)
+            self._compress_bytes_after += max(0, tokens_after)
+            self._tokens_saved_compress += max(0, tokens_before - tokens_after)
 
     def on_eviction(self) -> None:
         """Record an eviction."""
         with self._data_lock:
             self._evictions += 1
 
+    def increment_skipped_temperature(self) -> None:
+        """C-04: record a cache skip due to non-zero temperature."""
+        with self._data_lock:
+            self._calls_skipped += 1
+
     def record_latency(self, ms: float) -> None:
         """Record latency overhead in milliseconds."""
         if ms < 0: