cctally 1.10.3 → 1.11.1

package/bin/_cctally_dashboard.py

@@ -256,6 +256,7 @@ def _cctally():
 # import from _cctally_core; already-decentralized buckets (X = _lib_*,
 # Y = _cctally_*) import from their natural home. These bypass the
 # legacy shim pattern entirely.
+import _cctally_core
 from _cctally_core import (
     eprint,
     now_utc_iso,
@@ -380,6 +381,81 @@ def _validate_update_check_ttl_hours_value(*args, **kwargs):
     return sys.modules["cctally"]._validate_update_check_ttl_hours_value(*args, **kwargs)
 
 
+# === Cache-report settings validator (spec 2026-05-21 §6) ================
+# Validates the optional ``config.json:cache_report`` block. Strict in
+# v1: only ``anomaly_threshold_pp`` is settable, must be a plain int in
+# ``[1, 100]`` (bool / float / string rejected — bool because it's an
+# int subclass in Python and quietly accepting ``true`` for a numeric
+# field is exactly the trip-up ``_validate_update_check_ttl_hours_value``
+# protects against). HTTP write path raises ``_CacheReportConfigError``
+# → ``_handle_post_settings`` maps to HTTP 400 + ``{error, field}``
+# (matches the existing handler convention at lines 4587-4602; spec
+# explicitly says 400, NOT 422).
+
+@dataclass(frozen=True)
+class _CacheReportSettings:
+    anomaly_threshold_pp: int
+
+
+class _CacheReportConfigError(Exception):
+    """Validation error for the ``cache_report`` config block.
+
+    ``field`` carries the offending key path (``anomaly_threshold_pp`` or
+    the unknown-key name) so the JSON 400 response can surface it.
+    """
+    def __init__(self, message: str, *, field: str | None = None):
+        super().__init__(message)
+        self.field = field
+
+
+_CACHE_REPORT_ALLOWED_KEYS = frozenset({"anomaly_threshold_pp"})
+
+
+def _validate_cache_report_settings(block: dict) -> dict:
+    """Validate a ``cache_report`` config block.
+
+    Pure function. Raises ``_CacheReportConfigError`` on invalid input;
+    returns a dict containing ONLY the keys that were present in the
+    input (validated). Callers merge the result into the existing
+    persisted block instead of replacing it wholesale — this mirrors
+    the ``update.check`` partial-PUT pattern at
+    ``_handle_post_settings`` (~line 5277) and prevents a combined save
+    that omits ``anomaly_threshold_pp`` from clobbering a previously
+    persisted user value with the default.
+
+    v1 only accepts ``anomaly_threshold_pp`` — ``anomaly_window_days``
+    stays hardcoded at 14 (spec §6.1; F10 from spec §10 tracks adding
+    a configurable baseline window along with the UI-copy work).
+    """
+    if not isinstance(block, dict):
+        raise _CacheReportConfigError(
+            "cache_report must be an object", field="cache_report",
+        )
+    for key in block:
+        if key not in _CACHE_REPORT_ALLOWED_KEYS:
+            raise _CacheReportConfigError(
+                f"unknown key in cache_report block: {key!r}",
+                field=key,
+            )
+    validated: dict = {}
+    if "anomaly_threshold_pp" in block:
+        threshold = block["anomaly_threshold_pp"]
+        # bool is an int subclass — reject it explicitly (mirrors the
+        # update.check.ttl_hours precedent).
+        if isinstance(threshold, bool) or not isinstance(threshold, int):
+            raise _CacheReportConfigError(
+                "anomaly_threshold_pp must be an integer",
+                field="anomaly_threshold_pp",
+            )
+        if threshold < 1 or threshold > 100:
+            raise _CacheReportConfigError(
+                "anomaly_threshold_pp must be in [1, 100]",
+                field="anomaly_threshold_pp",
+            )
+        validated["anomaly_threshold_pp"] = threshold
+    return validated
+
+
 def _config_known_value(*args, **kwargs):
     return sys.modules["cctally"]._config_known_value(*args, **kwargs)
 
@@ -1674,6 +1750,461 @@ def _build_projects_share_panel_data(options: dict,
 
 
 
+# === Cache-report envelope dataclasses (spec 2026-05-21) =================
+# Snake_case fields are emitted verbatim into the SSE envelope so the React
+# store can read ``state.cache_report.<field>`` without a key-transform pass
+# (the envelope is intentionally snake_case end-to-end; see
+# ``dashboard/web/src/types/envelope.ts:189``). Built by
+# ``build_cache_report_snapshot()`` and shipped on the existing 5-minute
+# sync cadence — no separate ``/api/cache-report`` endpoint.
+
+# Hardcoded for v1; F10 tracks lifting via cache_report.anomaly_window_days config.
+CACHE_REPORT_WINDOW_DAYS = 14
+# Two concepts that happen to share a value today: the data window the
+# panel renders vs. the baseline window the anomaly classifier reads
+# back over. Split so F10 can lift the latter without dragging the
+# former along.
+CACHE_REPORT_ANOMALY_WINDOW_DAYS = 14
+
+@dataclass(frozen=True)
+class CacheReportDailyRow:
+    date: str  # YYYY-MM-DD in display tz
+    cache_hit_percent: float
+    input_tokens: int
+    output_tokens: int
+    cache_creation_tokens: int
+    cache_read_tokens: int
+    saved_usd: float
+    wasted_usd: float
+    net_usd: float
+    anomaly_triggered: bool
+    anomaly_reasons: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class CacheReportBreakdownRow:
+    """One row of the by-project / by-model breakdown sub-cards."""
+    key: str
+    cache_hit_percent: float
+    net_usd: float
+
+
+@dataclass(frozen=True)
+class CacheReportTodaySpotlight:
+    """Today's spotlight card: hit %, baseline-median, Δ vs baseline,
+    cumulative net / saved / wasted, anomaly state, and the count of
+    baseline daily rows so the React panel can gate the
+    "Building baseline · N/5 days" insufficient-baseline state."""
+    date: str
+    cache_hit_percent: float
+    baseline_median_percent: float | None
+    delta_pp: float | None
+    net_usd: float
+    saved_usd: float
+    wasted_usd: float
+    anomaly_triggered: bool
+    anomaly_reasons: tuple[str, ...]
+    baseline_daily_row_count: int
+
+
+def _cache_report_snapshot_to_dict(cr: "CacheReportSnapshot | None") -> "dict | None":
+    """Serialize a ``CacheReportSnapshot`` to the SSE envelope dict.
+
+    Returns ``None`` when the snapshot is ``None`` (first tick before
+    sync, or sub-build failure recorded on ``last_sync_error``). Snake-
+    case keys throughout — the envelope is intentionally snake_case end
+    -to-end per ``envelope.ts:189`` (no ``to_camel`` pass). Tuples are
+    flattened to lists for JSON palatability.
+    """
+    if cr is None:
+        return None
+    return {
+        "window_days": cr.window_days,
+        "anomaly_threshold_pp": cr.anomaly_threshold_pp,
+        "anomaly_window_days": cr.anomaly_window_days,
+        "today": {
+            "date": cr.today.date,
+            "cache_hit_percent": cr.today.cache_hit_percent,
+            "baseline_median_percent": cr.today.baseline_median_percent,
+            "delta_pp": cr.today.delta_pp,
+            "net_usd": cr.today.net_usd,
+            "saved_usd": cr.today.saved_usd,
+            "wasted_usd": cr.today.wasted_usd,
+            "anomaly_triggered": cr.today.anomaly_triggered,
+            "anomaly_reasons": list(cr.today.anomaly_reasons),
+            "baseline_daily_row_count": cr.today.baseline_daily_row_count,
+        },
+        "days": [
+            {
+                "date": d.date,
+                "cache_hit_percent": d.cache_hit_percent,
+                "input_tokens": d.input_tokens,
+                "output_tokens": d.output_tokens,
+                "cache_creation_tokens": d.cache_creation_tokens,
+                "cache_read_tokens": d.cache_read_tokens,
+                "saved_usd": d.saved_usd,
+                "wasted_usd": d.wasted_usd,
+                "net_usd": d.net_usd,
+                "anomaly_triggered": d.anomaly_triggered,
+                "anomaly_reasons": list(d.anomaly_reasons),
+            }
+            for d in cr.days
+        ],
+        "by_project": [
+            {
+                "key": b.key,
+                "cache_hit_percent": b.cache_hit_percent,
+                "net_usd": b.net_usd,
+            }
+            for b in cr.by_project
+        ],
+        "by_model": [
+            {
+                "key": b.key,
+                "cache_hit_percent": b.cache_hit_percent,
+                "net_usd": b.net_usd,
+            }
+            for b in cr.by_model
+        ],
+        "seven_day_net_usd": cr.seven_day_net_usd,
+        "seven_day_anomaly_count": cr.seven_day_anomaly_count,
+        "fourteen_day_counterfactual_usd": cr.fourteen_day_counterfactual_usd,
+        "fourteen_day_efficiency_ratio": cr.fourteen_day_efficiency_ratio,
+        "is_empty": cr.is_empty,
+    }
+
+
+@dataclass(frozen=True)
+class CacheReportSnapshot:
+    """The complete cache-report envelope block.
+
+    ``days`` is newest-first, length ``≤ window_days``. ``by_project`` /
+    ``by_model`` are sorted by ``abs(net_usd)`` descending and capped at
+    6 entries (top 5 + ``(other)``). ``window_days`` is hardcoded at 14
+    in v1; ``anomaly_threshold_pp`` is read from
+    ``config.json:cache_report.anomaly_threshold_pp`` (default 15) via
+    the dashboard sync thread.
+    """
+    window_days: int
+    anomaly_threshold_pp: int
+    anomaly_window_days: int
+    today: CacheReportTodaySpotlight
+    days: tuple[CacheReportDailyRow, ...]
+    by_project: tuple[CacheReportBreakdownRow, ...]
+    by_model: tuple[CacheReportBreakdownRow, ...]
+    seven_day_net_usd: float
+    seven_day_anomaly_count: int
+    fourteen_day_counterfactual_usd: float
+    fourteen_day_efficiency_ratio: float
+    is_empty: bool
+
+
+# === Cache-report snapshot builder (spec 2026-05-21 §5.2) ================
+# Adapter from the I/O layer (``get_claude_session_entries`` +
+# ``CLAUDE_MODEL_PRICING`` + ``_calculate_entry_cost``) into the kernel's
+# pure ``_build_cache_report`` orchestrator. By-project + by-model
+# breakdowns dedup through the kernel's ``_aggregate_cache_breakdown``
+# (one path, one ``<synthetic>`` filter rule) so the two axes can't
+# silently disagree on token totals when a session has both real and
+# synthetic entries on the same project.
+
+def _cache_report_load_kernel():
+    """Lazy-load ``_cctally_cache_report`` via the cctally ``_load_sibling``
+    bridge so monkeypatch-driven test reloads of cctally see the same
+    kernel module instance (matches the late-load pattern used by share /
+    doctor helpers in this file)."""
+    return sys.modules["cctally"]._load_sibling("_cctally_cache_report")
+
+
+def build_cache_report_snapshot(
+    *,
+    now_utc: dt.datetime,
+    anomaly_threshold_pp: int,
+    anomaly_window_days: int,
+    display_tz: "ZoneInfo | None",
+    skip_sync: bool = False,
+) -> CacheReportSnapshot:
+    """Build the ``cache_report`` envelope field from the session-entry cache.
+
+    Pulls entries via ``get_claude_session_entries`` (uses the cache when
+    warm, falls back to direct-JSONL parse on cache miss / lock
+    contention — same chain the CLI uses). Delegates aggregation +
+    anomaly classification to ``_cctally_cache_report._build_cache_report``;
+    shapes the result into a frozen ``CacheReportSnapshot``.
+
+    ``window_days`` is hardcoded at 14 in v1 (spec §6.1 hardcodes
+    ``anomaly_window_days`` too; ``anomaly_threshold_pp`` is the only
+    user-configurable knob). F10 from spec §10 tracks making the window
+    configurable, plus the UI-copy work it'd require.
+    """
+    crk = _cache_report_load_kernel()
+    cctally_ns = sys.modules["cctally"]
+
+    window_days = CACHE_REPORT_WINDOW_DAYS  # v1: hardcoded per spec §6.1.
+    since = now_utc - dt.timedelta(days=window_days)
+
+    entries = list(
+        get_claude_session_entries(since, now_utc, project=None, skip_sync=skip_sync)
+    )
+
+    today_iso = now_utc.astimezone(
+        display_tz if display_tz is not None else dt.timezone.utc
+    ).strftime("%Y-%m-%d")
+
+    if not entries:
+        empty_today = CacheReportTodaySpotlight(
+            date=today_iso,
+            cache_hit_percent=0.0,
+            baseline_median_percent=None,
+            delta_pp=None,
+            net_usd=0.0, saved_usd=0.0, wasted_usd=0.0,
+            anomaly_triggered=False,
+            anomaly_reasons=(),
+            baseline_daily_row_count=0,
+        )
+        return CacheReportSnapshot(
+            window_days=window_days,
+            anomaly_threshold_pp=anomaly_threshold_pp,
+            anomaly_window_days=anomaly_window_days,
+            today=empty_today,
+            days=(), by_project=(), by_model=(),
+            seven_day_net_usd=0.0,
+            seven_day_anomaly_count=0,
+            fourteen_day_counterfactual_usd=0.0,
+            fourteen_day_efficiency_ratio=0.0,
+            is_empty=True,
+        )
+
+    pricing = cctally_ns.CLAUDE_MODEL_PRICING
+
+    # Day-mode kernel expects entries with a ``usage`` dict (matches
+    # ``UsageEntry``). ``get_claude_session_entries`` returns flat
+    # ``_JoinedClaudeEntry`` objects, so wrap each into the right shape
+    # before passing to the kernel. SimpleNamespace keeps the wrapper
+    # pure-Python and avoids a new dataclass type just for the bridge.
+    from types import SimpleNamespace as _NS
+    day_entries = [
+        _NS(
+            timestamp=e.timestamp,
+            model=e.model,
+            cost_usd=e.cost_usd,
+            usage={
+                "input_tokens": e.input_tokens,
+                "output_tokens": e.output_tokens,
+                "cache_creation_input_tokens": e.cache_creation_tokens,
+                "cache_read_input_tokens": e.cache_read_tokens,
+            },
+        )
+        for e in entries
+    ]
+
+    result = crk._build_cache_report(
+        day_entries,
+        now_utc=now_utc,
+        window_days=window_days,
+        anomaly_threshold_pp=anomaly_threshold_pp,
+        anomaly_window_days=anomaly_window_days,
+        display_tz=display_tz,
+        pricing=pricing,
+        mode="day",
+        cost_calculator=_calculate_entry_cost,
+    )
+
+    # Pick out today's row (if any) and the baseline-daily-row count for
+    # the spotlight. The spotlight median is computed against ALL rows
+    # except today (cross-row reference; mirrors what the panel's
+    # "Δ vs 14d median" label means). The median itself rides back on
+    # ``result.today_baseline_median`` (EFF-3 — kernel computes it once
+    # alongside the anomaly classifier so we don't re-walk the same
+    # row set here).
+    today_row = next((r for r in result.rows if r.date == today_iso), None)
+    other_rows = [r for r in result.rows if r.date != today_iso]
+    baseline_median = result.today_baseline_median
+
+    baseline_daily_row_count = len(other_rows)
+
+    # ``delta_pp`` sign convention (spec §4.2): "signed; negative = today
+    # below median" → ``delta = today − baseline``. The empty-day branch
+    # uses today_hit_pct = 0.0 so the formula degenerates to
+    # ``0.0 − baseline_median``, which IS what users expect (a flat-zero
+    # today read against a healthy 60% baseline yields delta=-60pp).
+    today_hit_pct = today_row.cache_hit_percent if today_row is not None else 0.0
+    delta_pp = (
+        None if baseline_median is None
+        else today_hit_pct - baseline_median
+    )
+
+    if today_row is None:
+        today_spotlight = CacheReportTodaySpotlight(
+            date=today_iso,
+            cache_hit_percent=0.0,
+            baseline_median_percent=baseline_median,
+            delta_pp=delta_pp,
+            net_usd=0.0, saved_usd=0.0, wasted_usd=0.0,
+            anomaly_triggered=False,
+            anomaly_reasons=(),
+            baseline_daily_row_count=baseline_daily_row_count,
+        )
+    else:
+        today_spotlight = CacheReportTodaySpotlight(
+            date=today_iso,
+            cache_hit_percent=today_row.cache_hit_percent,
+            baseline_median_percent=baseline_median,
+            delta_pp=delta_pp,
+            net_usd=today_row.net_usd,
+            saved_usd=today_row.saved_usd,
+            wasted_usd=today_row.wasted_usd,
+            anomaly_triggered=today_row.anomaly_triggered,
+            anomaly_reasons=tuple(today_row.anomaly_reasons),
+            baseline_daily_row_count=baseline_daily_row_count,
+        )
+
+    # Daily rows — newest first, capped at ``window_days``.
+    #
+    # Slice cap (spec §4.2 — "length up to ``window_days``"): the kernel's
+    # ``since = now_utc - timedelta(days=window_days)`` rolling window
+    # straddles midnight in any non-UTC ``display_tz`` (and in fact even
+    # in UTC, since ``now_utc - 14d`` and ``now_utc`` flank the same
+    # wall-clock minute on different calendar dates), so the kernel can
+    # emit ``window_days + 1`` distinct calendar-date buckets. Capping
+    # here (and not in the kernel) keeps the kernel agnostic of the
+    # envelope's hard ceiling while honoring the contract every TS /
+    # React consumer relies on (the sparkline ladder is hard-sized to
+    # ``window_days`` points). Regression:
+    # ``test_build_cache_report_snapshot_days_bounded_by_window``.
+    #
+    # Synthetic-today insertion: if the trailing window has older activity
+    # but no entries for the current display-tz day, the kernel emits a
+    # rows[] list whose newest row is yesterday (or older). Both React
+    # consumers (``CacheSparkline`` and ``CacheNetBars``) treat the
+    # rightmost element of ``days`` as "Today" purely positionally
+    # (``ordered.length - 1`` / ``isLast ? 'Today'``), so without an
+    # explicit today bucket they would mis-label the older row as Today.
+    # Insert a zero-valued CacheReportDailyRow at position 0 (newest)
+    # whenever ``today_row is None``. The zero values mirror the
+    # ``today_spotlight`` synthesized above (kept in lock-step), and
+    # contribute 0 to ``seven_day_*`` / ``fourteen_day_*`` rollups so
+    # the rollup math stays untouched.
+    raw_days_newest_first = sorted(
+        result.rows, key=lambda r: r.date or "", reverse=True,
+    )
+    days_newest_first: list = []
+    if today_row is None:
+        # Build a zero-valued synthetic today row mirroring today_spotlight.
+        days_newest_first.append(
+            CacheReportDailyRow(
+                date=today_iso,
+                cache_hit_percent=0.0,
+                input_tokens=0,
+                output_tokens=0,
+                cache_creation_tokens=0,
+                cache_read_tokens=0,
+                saved_usd=0.0,
+                wasted_usd=0.0,
+                net_usd=0.0,
+                anomaly_triggered=False,
+                anomaly_reasons=(),
+            )
+        )
+    days_newest_first.extend(
+        CacheReportDailyRow(
+            date=r.date or "",
+            cache_hit_percent=r.cache_hit_percent,
+            input_tokens=r.input_tokens,
+            output_tokens=r.output_tokens,
+            cache_creation_tokens=r.cache_creation_tokens,
+            cache_read_tokens=r.cache_read_tokens,
+            saved_usd=r.saved_usd,
+            wasted_usd=r.wasted_usd,
+            net_usd=r.net_usd,
+            anomaly_triggered=r.anomaly_triggered,
+            anomaly_reasons=tuple(r.anomaly_reasons),
+        )
+        for r in raw_days_newest_first
+    )
+    days = tuple(days_newest_first[:window_days])
+
+    # By-project + by-model breakdowns are window-wide aggregates (not
+    # today-only) so the panel can surface the project / model carrying
+    # the bulk of net savings across the trailing 14d. by-project walks
+    # raw entries (project_path is per-entry, not on the day-model
+    # buckets); by-model folds the per-row ``model_breakdowns`` already
+    # produced by day-mode, which avoids re-running the tiered-pricing
+    # math per entry. Both paths apply the same ``<synthetic>`` filter so
+    # the axes can't silently disagree on token totals.
+    #
+    # Constrain both axes to the SAME calendar dates as ``days``: the
+    # kernel's rolling window can emit ``window_days + 1`` distinct
+    # display-tz buckets (see the slice-cap comment above), and ``days``
+    # drops the oldest. Without the same drop here the by-project /
+    # by-model cards would silently include the clipped 15th day and
+    # their net totals stop reconciling against the visible table /
+    # CacheNetBars in the modal. The filter mirrors the kernel's
+    # bucket-key derivation (``entry.timestamp.astimezone(tz)``) so a
+    # cache entry and its corresponding day row always agree on which
+    # bucket they belong to.
+    kept_dates = frozenset(r.date for r in days if r.date)
+    bucket_tz = display_tz if display_tz is not None else dt.timezone.utc
+    entries_in_window = [
+        e for e in entries
+        if e.timestamp.astimezone(bucket_tz).strftime("%Y-%m-%d") in kept_dates
+    ]
+    rows_in_window = [r for r in result.rows if r.date in kept_dates]
+    by_project_rows = crk._aggregate_cache_breakdown(
+        entries_in_window,
+        key_fn=lambda e: (getattr(e, "project_path", None) or "(unknown)"),
+        pricing=pricing,
+        skip_synthetic=True,
+    )
+    by_model_rows = crk._aggregate_cache_breakdown_from_rows(
+        rows_in_window,
+        skip_synthetic=True,
+    )
+    by_project = tuple(
+        CacheReportBreakdownRow(
+            key=r.key, cache_hit_percent=r.cache_hit_percent, net_usd=r.net_usd,
+        )
+        for r in by_project_rows
+    )
+    by_model = tuple(
+        CacheReportBreakdownRow(
+            key=r.key, cache_hit_percent=r.cache_hit_percent, net_usd=r.net_usd,
+        )
+        for r in by_model_rows
+    )
+
+    # 7-day rollup: today + 6 prior. Walk by string date; ``days_newest_first``
+    # is already in the right order.
+    seven_day_rows = days[:7]
+    seven_day_net_usd = sum(r.net_usd for r in seven_day_rows)
+    seven_day_anomaly_count = sum(
+        1 for r in seven_day_rows if r.anomaly_triggered
+    )
+
+    # 14-day counterfactual: sum(saved_usd) across the window.
+    fourteen_day_counterfactual_usd = sum(r.saved_usd for r in days)
+    fourteen_day_wasted_usd = sum(r.wasted_usd for r in days)
+    denom = fourteen_day_counterfactual_usd + abs(fourteen_day_wasted_usd)
+    fourteen_day_efficiency_ratio = (
+        (fourteen_day_counterfactual_usd / denom) if denom > 1e-9 else 0.0
+    )
+
+    return CacheReportSnapshot(
+        window_days=window_days,
+        anomaly_threshold_pp=anomaly_threshold_pp,
+        anomaly_window_days=anomaly_window_days,
+        today=today_spotlight,
+        days=days,
+        by_project=by_project,
+        by_model=by_model,
+        seven_day_net_usd=seven_day_net_usd,
+        seven_day_anomaly_count=seven_day_anomaly_count,
+        fourteen_day_counterfactual_usd=fourteen_day_counterfactual_usd,
+        fourteen_day_efficiency_ratio=fourteen_day_efficiency_ratio,
+        is_empty=False,
+    )
+
+
 # === Dashboard server core: _SnapshotRef + SSEHub + envelope builders =====
 # Pre-extract location: bin/cctally L16265.
 
@@ -4237,6 +4768,17 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
         # panel-empty state in that case.
         "projects":         getattr(snap, "projects_envelope", None),
 
+        # Cache-report panel + modal envelope block (spec
+        # 2026-05-21-cache-report-panel-design.md §4.2). Snake_case
+        # keys throughout — the envelope is intentionally snake_case
+        # end-to-end (envelope.ts:189). ``None`` on first tick before
+        # sync completes; the client renders the panel-empty state in
+        # that case. envelope_version stays at 2 (additive optional
+        # field, matches the update? / doctor? precedent).
+        "cache_report":     _cache_report_snapshot_to_dict(
+            getattr(snap, "cache_report", None)
+        ),
+
         # threshold-actions T5: see prelude above for rationale.
         "alerts":           alerts_array,
         "alerts_settings":  alerts_settings,
@@ -4583,10 +5125,10 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         """Persist a settings update and trigger an immediate SSE broadcast.
 
         Body shape: ``{"display"?: {"tz": "..."}, "alerts"?: {...},
-        "update"?: {"check"?: {"enabled"?: bool, "ttl_hours"?: int}}}``
-        — every top-level key is optional; any subset may be sent
-        together (combined save). Unknown top-level keys are rejected
-        with 400.
+        "update"?: {"check"?: {"enabled"?: bool, "ttl_hours"?: int}},
+        "cache_report"?: {"anomaly_threshold_pp"?: int}}`` — every
+        top-level key is optional; any subset may be sent together
+        (combined save). Unknown top-level keys are rejected with 400.
 
         Per-block validation:
           * ``display.tz`` — "local", "utc", or a valid IANA zone (via
@@ -4600,6 +5142,11 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             ``[1, 720]``; 400 on out-of-range or non-int. Bool is rejected
             (Python ``True`` is an int subclass, so a permissive check
             would silently accept ``true`` for a numeric field).
+          * ``cache_report.anomaly_threshold_pp`` — JSON int (NOT bool /
+            float / string), in ``[1, 100]``; 400 with
+            ``{error, field: "anomaly_threshold_pp"}`` on out-of-range
+            or non-int. Spec §6.1 hardcodes ``anomaly_window_days``;
+            F10 tracks lifting that.
 
         Atomic merged write: if all touched blocks validate, the merged
         config is persisted in a single ``save_config`` call inside the
@@ -4651,7 +5198,7 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             return
 
         # Reject unknown top-level keys (forward-compat hygiene).
-        allowed_top_keys = {"display", "alerts", "update"}
+        allowed_top_keys = {"display", "alerts", "update", "cache_report"}
         for k in payload.keys():
             if k not in allowed_top_keys:
                 self._respond_json(
@@ -4664,16 +5211,49 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             "display" not in payload
             and "alerts" not in payload
             and "update" not in payload
+            and "cache_report" not in payload
         ):
             self._respond_json(
                 400,
                 {"error": (
                     "body must contain at least one of: "
-                    "display, alerts, update"
+                    "display, alerts, update, cache_report"
                 )},
             )
             return
 
+        # Pre-validate cache_report block (spec 2026-05-21 §6.2). Outside
+        # the config_writer_lock so a 400 short-circuit doesn't take the
+        # lock unnecessarily. Returns HTTP 400 (NOT 422) on validation
+        # error — matches the convention every other block here uses.
+        #
+        # Validator returns a dict of ONLY the keys present in the input
+        # (partial-PUT semantics, mirroring the ``update.check`` block
+        # at ~line 5277). The handler below merges this into the
+        # existing persisted ``cache_report`` block so a combined save
+        # that omits ``anomaly_threshold_pp`` does not clobber the
+        # user's persisted threshold with the default.
+        cache_report_validated: "dict | None" = None
+        if "cache_report" in payload:
+            cache_report_block = payload["cache_report"]
+            if not isinstance(cache_report_block, dict):
+                self._respond_json(
+                    400,
+                    {"error": "cache_report must be an object",
+                     "field": "cache_report"},
+                )
+                return
+            try:
+                cache_report_validated = _validate_cache_report_settings(
+                    cache_report_block
+                )
+            except _CacheReportConfigError as exc:
+                self._respond_json(
+                    400,
+                    {"error": str(exc), "field": exc.field or "cache_report"},
+                )
+                return
+
         # Pre-validate display block (outside the config_writer_lock so a
         # 400 short-circuit doesn't take the lock unnecessarily).
         display_canonical: "str | None" = None
@@ -4861,6 +5441,28 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 merged_update["check"] = merged_check
                 merged["update"] = merged_update
 
+            if cache_report_validated is not None:
+                # Same hand-edited-junk guard as alerts / update: a non
+                # -dict ``cache_report`` block in config.json should
+                # surface as a recoverable 400, not a 500.
+                existing_cr = merged.get("cache_report")
+                if existing_cr is not None and not isinstance(existing_cr, dict):
+                    self._respond_json(
+                        400, {"error": "cache_report must be an object",
+                              "field": "cache_report"}
+                    )
+                    return
+                # Partial-PUT merge: preserve keys the request didn't
+                # touch (mirrors the update.check block at ~line 5371).
+                # Becomes load-bearing once F10 lifts
+                # ``anomaly_window_days`` to config — until then it
+                # still defends a combined save (e.g. display + empty
+                # cache_report) from clobbering ``anomaly_threshold_pp``
+                # with the default.
+                merged_cr = dict(existing_cr or {})
+                merged_cr.update(cache_report_validated)
+                merged["cache_report"] = merged_cr
+
             save_config(merged)
 
         # Build the response: subset of touched blocks.
@@ -4884,6 +5486,18 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                     ),
                 }
             }
+        if cache_report_validated is not None:
+            # Echo the full cooked block (resolved defaults included) so
+            # the dashboard composer can repaint without a follow-up GET
+            # — mirrors the update.check echo at ~line 5402. Read from
+            # the merged cache_report we just wrote; fall back to the
+            # documented default when neither the request nor the
+            # persisted config carries an explicit value.
+            persisted_cr = merged.get("cache_report") or {}
+            stored_threshold = persisted_cr.get("anomaly_threshold_pp", 15)
+            out["cache_report"] = {
+                "anomaly_threshold_pp": stored_threshold,
+            }
         out["saved_at"] = (
             dt.datetime.now(dt.timezone.utc)
             .strftime("%Y-%m-%dT%H:%M:%SZ")
@@ -5935,7 +6549,7 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 c = _cctally()
                 conn.execute(
                     "ATTACH DATABASE ? AS cache_db",
-                    (str(c.CACHE_DB_PATH),),
+                    (str(_cctally_core.CACHE_DB_PATH),),
                 )
                 conn.execute(
                     "CREATE TEMP VIEW IF NOT EXISTS session_entries AS "