cctally 1.60.0 → 1.62.0

package/bin/_lib_cache_report.py

@@ -17,7 +17,7 @@ from __future__ import annotations
 
 import datetime as dt
 from dataclasses import dataclass, field
-from typing import Any, Callable, Iterable, Literal, Optional
+from typing import Any, Callable, Iterable, Literal, NamedTuple, Optional
 from zoneinfo import ZoneInfo
 
 
@@ -175,6 +175,23 @@ class _Bucket:
     net_usd: float = 0.0
 
 
+@dataclass(frozen=True)
+class _ProjectPartial:
+    """One (day, project) net-$/token partial — a frozen cache primitive (#272 §4).
+
+    Produced by ``aggregate_by_day_project`` and combined across days by
+    ``combine_day_project_partials``. ``net_usd`` is a ``stable_sum`` over
+    that (day, project) group's per-entry nets (order-independent); the
+    token components are associative int sums. Frozen so a cached day
+    (§5) can hold a tuple of these without any risk of tick-to-tick
+    mutation (F7).
+    """
+    net_usd: float
+    input_tokens: int
+    cache_creation_tokens: int
+    cache_read_tokens: int
+
+
 def _compute_cache_hit_percent(
     input_tokens: int,
     cache_creation_tokens: int,
@@ -696,6 +713,41 @@ def _classify_anomalies(
 # Window-wide breakdown aggregator (by-project / by-model dedup)
 # ---------------------------------------------------------------------------
 
+def _finalize_breakdown_rows(
+    rows: list["CacheBreakdownRow"],
+    *,
+    top_n: int = 5,
+    other_label: str = "(other)",
+) -> tuple["CacheBreakdownRow", ...]:
+    """Sort by ``abs(net_usd)`` desc, keep ``top_n``, fold the tail into ``(other)``.
+
+    Shared by ``_aggregate_cache_breakdown``,
+    ``_aggregate_cache_breakdown_from_rows``, and
+    ``combine_day_project_partials`` (#272 §4) so the sort / top-N /
+    ``(other)`` contract lives in one place. Byte-identical to the prior
+    inline tail: the ``(other)`` net is a ``stable_sum`` over the tail's
+    per-row nets and its ``cache_hit_percent`` is the true aggregate over
+    the tail's summed token components (EFF-4).
+    """
+    rows.sort(key=lambda r: abs(r.net_usd), reverse=True)
+    if len(rows) <= top_n:
+        return tuple(rows)
+    head = rows[:top_n]
+    tail = rows[top_n:]
+    other_net = stable_sum(r.net_usd for r in tail)
+    tail_input = sum(r.input_tokens for r in tail)
+    tail_creation = sum(r.cache_creation_tokens for r in tail)
+    tail_read = sum(r.cache_read_tokens for r in tail)
+    other_pct = _compute_cache_hit_percent(tail_input, tail_creation, tail_read)
+    head.append(CacheBreakdownRow(
+        key=other_label, cache_hit_percent=other_pct, net_usd=other_net,
+        input_tokens=tail_input,
+        cache_creation_tokens=tail_creation,
+        cache_read_tokens=tail_read,
+    ))
+    return tuple(head)
+
+
 def _aggregate_cache_breakdown(
     entries: Iterable,
     *,
@@ -762,26 +814,7 @@ def _aggregate_cache_breakdown(
             cache_creation_tokens=b.cache_creation_tokens,
             cache_read_tokens=b.cache_read_tokens,
         ))
-    out.sort(key=lambda r: abs(r.net_usd), reverse=True)
-    if len(out) <= top_n:
-        return tuple(out)
-    head = out[:top_n]
-    tail = out[top_n:]
-    other_net = stable_sum(r.net_usd for r in tail)
-    # True aggregate hit % over the tail buckets — sum directly from the
-    # CacheBreakdownRow token fields (EFF-4 — avoids the previous triple
-    # walk over ``buckets.items()``).
-    tail_input = sum(r.input_tokens for r in tail)
-    tail_creation = sum(r.cache_creation_tokens for r in tail)
-    tail_read = sum(r.cache_read_tokens for r in tail)
-    other_pct = _compute_cache_hit_percent(tail_input, tail_creation, tail_read)
-    head.append(CacheBreakdownRow(
-        key=other_label, cache_hit_percent=other_pct, net_usd=other_net,
-        input_tokens=tail_input,
-        cache_creation_tokens=tail_creation,
-        cache_read_tokens=tail_read,
-    ))
-    return tuple(head)
+    return _finalize_breakdown_rows(out, top_n=top_n, other_label=other_label)
 
 
 def _aggregate_cache_breakdown_from_rows(
@@ -830,23 +863,317 @@ def _aggregate_cache_breakdown_from_rows(
             cache_creation_tokens=b.cache_creation_tokens,
             cache_read_tokens=b.cache_read_tokens,
         ))
-    out.sort(key=lambda r: abs(r.net_usd), reverse=True)
-    if len(out) <= top_n:
-        return tuple(out)
-    head = out[:top_n]
-    tail = out[top_n:]
-    other_net = stable_sum(r.net_usd for r in tail)
-    tail_input = sum(r.input_tokens for r in tail)
-    tail_creation = sum(r.cache_creation_tokens for r in tail)
-    tail_read = sum(r.cache_read_tokens for r in tail)
-    other_pct = _compute_cache_hit_percent(tail_input, tail_creation, tail_read)
-    head.append(CacheBreakdownRow(
-        key=other_label, cache_hit_percent=other_pct, net_usd=other_net,
-        input_tokens=tail_input,
-        cache_creation_tokens=tail_creation,
-        cache_read_tokens=tail_read,
-    ))
-    return tuple(head)
+    return _finalize_breakdown_rows(out, top_n=top_n, other_label=other_label)
+
+
+# ---------------------------------------------------------------------------
+# Two-level by_project fold (grouping-invariant; dashboard-only) — #272 §4
+# ---------------------------------------------------------------------------
+
+def aggregate_by_day_project(
+    entries: "Iterable",
+    *,
+    display_tz: "ZoneInfo | None",
+    pricing: dict,
+    skip_synthetic: bool = True,
+) -> "dict[str, dict[str, _ProjectPartial]]":
+    """Per-(display-tz day, project) net-$/token partials (#272 §4).
+
+    Groups RAW entries (each carrying ``.project_path`` / ``.model`` /
+    ``.cache_*`` / ``.input_tokens`` / ``.timestamp``) by (day, project).
+    The per-(day, project) ``net_usd`` is a ``stable_sum`` over that
+    group's per-entry nets so it is order-independent
+    (``get_claude_session_entries`` orders by ``timestamp_utc`` only, with
+    no ``id`` tiebreak). Token components are associative int sums. Drops
+    ``<synthetic>``-model entries when ``skip_synthetic`` (matches the
+    by_project contract; the day-row ``model_breakdowns`` deliberately keep
+    ``<synthetic>``). Day key uses ``_resolve_bucket_tz(display_tz)`` —
+    identical to ``_aggregate_cache_by_day``, so keys align with
+    ``CacheRow.date`` / the builder's ``kept_dates``.
+    """
+    tz = _resolve_bucket_tz(display_tz)
+    nets: dict[tuple[str, str], list[float]] = {}
+    toks: dict[tuple[str, str], list[int]] = {}  # [input, creation, read]
+    for e in entries:
+        model = getattr(e, "model", "")
+        if skip_synthetic and model == "<synthetic>":
+            continue
+        day_key = e.timestamp.astimezone(tz).strftime("%Y-%m-%d")
+        proj = getattr(e, "project_path", None) or "(unknown)"
+        k = (day_key, proj)
+        create_tok = getattr(e, "cache_creation_tokens", 0)
+        read_tok = getattr(e, "cache_read_tokens", 0)
+        _s, _w, net = _compute_entry_cache_dollars(
+            model, create_tok, read_tok, pricing=pricing,
+        )
+        nets.setdefault(k, []).append(net)
+        t = toks.setdefault(k, [0, 0, 0])
+        t[0] += getattr(e, "input_tokens", 0)
+        t[1] += create_tok
+        t[2] += read_tok
+    out: dict[str, dict[str, _ProjectPartial]] = {}
+    for (day_key, proj), net_list in nets.items():
+        t = toks[(day_key, proj)]
+        out.setdefault(day_key, {})[proj] = _ProjectPartial(
+            net_usd=stable_sum(net_list),
+            input_tokens=t[0],
+            cache_creation_tokens=t[1],
+            cache_read_tokens=t[2],
+        )
+    return out
+
+
+def combine_day_project_partials(
+    partials_by_date: "dict[str, dict[str, _ProjectPartial]]",
+    *,
+    top_n: int = 5,
+    other_label: str = "(other)",
+) -> tuple["CacheBreakdownRow", ...]:
+    """Combine per-(day, project) partials into the window by_project rows (#272 §4).
+
+    Per project: ``stable_sum`` its day-partials' ``net_usd`` across the
+    given dates (byte-identical whether the dates come from a fresh
+    full-window fold or a per-day cache), int-sum its token components,
+    compute ``cache_hit_percent`` once, then the shared top-N / ``(other)``
+    fold. Dates are iterated in sorted order so the by_project map's
+    insertion order is deterministic (warm == cold); with order-independent
+    partials this only affects exact-``abs(net)`` tie ordering, which the
+    stable sort then resolves identically on both paths.
+    """
+    net_lists: dict[str, list[float]] = {}
+    tok: dict[str, list[int]] = {}  # [input, creation, read]
+    for day_key in sorted(partials_by_date):
+        for proj, p in partials_by_date[day_key].items():
+            net_lists.setdefault(proj, []).append(p.net_usd)
+            t = tok.setdefault(proj, [0, 0, 0])
+            t[0] += p.input_tokens
+            t[1] += p.cache_creation_tokens
+            t[2] += p.cache_read_tokens
+    rows: list[CacheBreakdownRow] = []
+    for proj, nets in net_lists.items():
+        t = tok[proj]
+        rows.append(CacheBreakdownRow(
+            key=proj,
+            cache_hit_percent=_compute_cache_hit_percent(t[0], t[1], t[2]),
+            net_usd=stable_sum(nets),
+            input_tokens=t[0],
+            cache_creation_tokens=t[1],
+            cache_read_tokens=t[2],
+        ))
+    return _finalize_breakdown_rows(rows, top_n=top_n, other_label=other_label)
+
+
+# ---------------------------------------------------------------------------
+# Frozen per-day cached unit + build / reconstruct helpers (#272 §5)
+# ---------------------------------------------------------------------------
+
+class _FrozenModelBreakdown(NamedTuple):
+    """Immutable mirror of ``CacheModelBreakdown`` (#272 §5, Codex-4).
+
+    ``CacheModelBreakdown`` is a *mutable* dataclass; a cached day must hold
+    its per-model children as frozen primitives so nothing reachable from a
+    published ``DataSnapshot`` is ever mutated tick-to-tick (F7). Field names
+    and order mirror ``CacheModelBreakdown`` EXACTLY (``:79``) so
+    ``reconstruct_cache_row`` can rebuild an equal mutable child by keyword.
+    """
+    model_name: str
+    input_tokens: int
+    output_tokens: int
+    cache_creation_tokens: int
+    cache_read_tokens: int
+    cache_hit_percent: float
+    cost: float
+    saved_usd: float
+    wasted_usd: float
+    net_usd: float
+
+
+@dataclass(frozen=True)
+class CachedCacheReportDay:
+    """One CLOSED day's raw aggregate + per-project partials, frozen (#272 §5).
+
+    Pre-classification: it carries NO ``anomaly_*`` state — those are
+    populated on a freshly reconstructed mutable ``CacheRow`` each tick
+    (``reconstruct_cache_row``), so nothing cached is ever mutated (F7).
+
+    Fields are the non-anomaly day-mode ``CacheRow`` scalars (``:113``) —
+    ``cache_hit_percent`` is a snapshot of the row's derived property (the
+    reconstructed row recomputes it from tokens, so it is informational
+    here) — plus:
+      - ``model_breakdowns``: a tuple of ``_FrozenModelBreakdown`` KEEPING
+        ``<synthetic>`` (the day-row contract; by_model applies its own
+        ``skip_synthetic`` at fold time).
+      - ``project_partials``: a tuple of ``(project_key, _ProjectPartial)``
+        pairs (``skip_synthetic=True`` — the by_project restitch input, §4).
+
+    Day-mode only: the session-mode ``CacheRow`` fields (``session_id`` /
+    ``project_path`` / ``last_activity`` / ``source_paths``) are never
+    populated by ``_aggregate_cache_by_day`` (they stay at their defaults),
+    so they are not stored; ``reconstruct_cache_row`` leaves them at the
+    ``CacheRow`` defaults, which the round-trip equality test confirms.
+
+    ``is_empty`` is a trailing sentinel flag (default ``False``): a genuinely
+    activity-free CLOSED day never appears in ``build_cached_days`` output
+    (that only emits days with entries), so the builder stores an
+    ``empty_cached_day`` sentinel for it — registering the quiet day as a
+    cache HIT (mirroring ``projects_env_week_put`` storing a computed-empty
+    week) so a weekend/vacation gap day can't permanently defeat ``have_all``.
+    The warm restitch SKIPS ``is_empty`` days entirely: they contribute no
+    ``CacheRow`` and no by_project partials, so a sentinel is byte-identical
+    to from-scratch (which never emits a row for a day with no entries).
+    """
+    date: str
+    cache_hit_percent: float
+    input_tokens: int
+    output_tokens: int
+    cache_creation_tokens: int
+    cache_read_tokens: int
+    cost: float
+    saved_usd: float
+    wasted_usd: float
+    net_usd: float
+    model_breakdowns: tuple  # tuple[_FrozenModelBreakdown, ...]
+    project_partials: tuple   # tuple[tuple[str, _ProjectPartial], ...]
+    is_empty: bool = False    # sentinel for an activity-free CLOSED day (§P1 fix)
+
+
+def empty_cached_day(date: str) -> "CachedCacheReportDay":
+    """A sentinel ``CachedCacheReportDay`` for an activity-free CLOSED date (#272 P1).
+
+    An all-zero unit with empty ``model_breakdowns`` / ``project_partials``
+    tuples and ``is_empty=True``. The builder stores one of these for every
+    needed closed date the per-day fold produced no row for, so
+    ``have_all`` (which gates the warm today-only-fetch path) sees a quiet day
+    as present instead of a perpetual miss — the exact hit-registration
+    ``projects_env_week_put`` does for a computed-empty week. The warm
+    reconstruct / by_project restitch skip ``is_empty`` days, so the sentinel
+    is byte-identical to from-scratch.
+    """
+    return CachedCacheReportDay(
+        date=date,
+        cache_hit_percent=0.0,
+        input_tokens=0,
+        output_tokens=0,
+        cache_creation_tokens=0,
+        cache_read_tokens=0,
+        cost=0.0,
+        saved_usd=0.0,
+        wasted_usd=0.0,
+        net_usd=0.0,
+        model_breakdowns=(),
+        project_partials=(),
+        is_empty=True,
+    )
+
+
+def build_cached_days(
+    day_entries: Iterable,
+    raw_entries: Iterable,
+    *,
+    display_tz: ZoneInfo | None,
+    pricing: dict,
+    cost_calculator: Callable[[str, dict, str, Optional[float]], float],
+) -> "dict[str, CachedCacheReportDay]":
+    """Per-day frozen aggregates + project partials for the whole input (#272 §5).
+
+    Runs ``_aggregate_cache_by_day(day_entries, ...)`` for the day rows and
+    ``aggregate_by_day_project(raw_entries, ...)`` for the per-project
+    partials, then zips them per display-tz date into a
+    ``CachedCacheReportDay``. Both aggregators bucket via
+    ``_resolve_bucket_tz(display_tz)``, so their date keys align.
+
+    ``day_entries`` are the ``SimpleNamespace`` wrappers (``.usage`` dict,
+    no ``.project_path``); ``raw_entries`` are the raw joined entries
+    (flat ``.project_path`` / ``.cache_*`` / ``.input_tokens``). The day
+    rows are stored pre-classification (no ``anomaly_*``); the caller
+    reconstructs mutable rows and classifies fresh each tick.
+    """
+    rows = _aggregate_cache_by_day(
+        day_entries,
+        display_tz=display_tz, pricing=pricing,
+        cost_calculator=cost_calculator,
+    )
+    partials = aggregate_by_day_project(
+        raw_entries, display_tz=display_tz, pricing=pricing, skip_synthetic=True,
+    )
+    out: dict[str, CachedCacheReportDay] = {}
+    for r in rows:
+        mbs = tuple(
+            _FrozenModelBreakdown(
+                model_name=mb.model_name,
+                input_tokens=mb.input_tokens,
+                output_tokens=mb.output_tokens,
+                cache_creation_tokens=mb.cache_creation_tokens,
+                cache_read_tokens=mb.cache_read_tokens,
+                cache_hit_percent=mb.cache_hit_percent,
+                cost=mb.cost,
+                saved_usd=mb.saved_usd,
+                wasted_usd=mb.wasted_usd,
+                net_usd=mb.net_usd,
+            )
+            for mb in r.model_breakdowns
+        )
+        pp = tuple(sorted((partials.get(r.date, {}) or {}).items()))
+        out[r.date] = CachedCacheReportDay(
+            date=r.date,
+            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,
+            cost=r.cost,
+            saved_usd=r.saved_usd,
+            wasted_usd=r.wasted_usd,
+            net_usd=r.net_usd,
+            model_breakdowns=mbs,
+            project_partials=pp,
+        )
+    return out
+
+
+def reconstruct_cache_row(cached: "CachedCacheReportDay") -> CacheRow:
+    """A fresh MUTABLE ``CacheRow`` from a frozen cached day (#272 §5, F7).
+
+    Rebuilds a brand-new mutable ``CacheRow`` (+ mutable
+    ``CacheModelBreakdown`` children) equal to the original
+    ``_aggregate_cache_by_day`` row modulo the anomaly fields, which are
+    cleared so ``_classify_anomalies`` can repopulate them each tick over a
+    row it fully owns. NOTHING reachable from ``cached`` is aliased — the
+    frozen unit is never mutated.
+
+    ``cache_hit_percent`` is a read-only *property* on ``CacheRow`` (derived
+    from the token counters), so it is NOT assigned here; setting the tokens
+    makes the property recompute the stored value. The session-mode fields
+    (``session_id`` / ``project_path`` / ``last_activity`` / ``source_paths``)
+    stay at the ``CacheRow`` defaults — day-mode rows never carry them.
+    """
+    row = CacheRow(date=cached.date)
+    row.input_tokens = cached.input_tokens
+    row.output_tokens = cached.output_tokens
+    row.cache_creation_tokens = cached.cache_creation_tokens
+    row.cache_read_tokens = cached.cache_read_tokens
+    row.cost = cached.cost
+    row.saved_usd = cached.saved_usd
+    row.wasted_usd = cached.wasted_usd
+    row.net_usd = cached.net_usd
+    row.model_breakdowns = [
+        CacheModelBreakdown(
+            model_name=m.model_name,
+            input_tokens=m.input_tokens,
+            output_tokens=m.output_tokens,
+            cache_creation_tokens=m.cache_creation_tokens,
+            cache_read_tokens=m.cache_read_tokens,
+            cache_hit_percent=m.cache_hit_percent,
+            cost=m.cost,
+            saved_usd=m.saved_usd,
+            wasted_usd=m.wasted_usd,
+            net_usd=m.net_usd,
+        )
+        for m in cached.model_breakdowns
+    ]
+    row.anomaly_reasons = []
+    row.anomaly_triggered = False
+    return row
 
 
 # ---------------------------------------------------------------------------
@@ -879,56 +1206,64 @@ class _CacheReportResult:
     today_baseline_median: float | None = None
 
 
-def _build_cache_report(
+def _aggregate_cache_report_rows(
     entries: Iterable,
     *,
-    now_utc: dt.datetime,
-    window_days: int,
-    anomaly_threshold_pp: int,
-    anomaly_window_days: int,
     display_tz: ZoneInfo | None,
     pricing: dict,
     cost_calculator: Callable[[str, dict, str, Optional[float]], float],
     mode: Literal["day", "session"] = "day",
     project_decoder: Callable[[str], str] | None = None,
-    anomaly_enabled: bool = True,
-) -> _CacheReportResult:
-    """Top-level orchestrator: aggregate + classify anomalies.
-
-    Returns a ``_CacheReportResult`` that both the CLI renderer and the
-    dashboard snapshot builder consume. Pure-function — no I/O, no
-    logging, no environment reads. Callers (CLI / dashboard) own all
-    I/O via the ``entries`` iterable + the ``cost_calculator`` /
-    ``project_decoder`` injections.
-
-    ``mode="day"`` buckets entries by display-tz calendar date;
-    ``mode="session"`` buckets by Claude ``sessionId`` (resume-merged
-    across JSONL files). Session mode requires ``project_decoder`` (the
-    CLI passes its ``_decode_escaped_cwd``-backed shim); day mode
-    ignores it.
-
-    The ``since`` window for both modes is ``now_utc − window_days``;
-    the kernel trusts callers to pre-filter via their own query
-    (``get_entries`` / ``get_claude_session_entries``).
+) -> list[CacheRow]:
+    """The aggregate half of ``_build_cache_report`` (#272 §6).
+
+    Buckets ``entries`` into ``CacheRow``s — by display-tz calendar date
+    (``mode="day"``) or by Claude ``sessionId`` (``mode="session"``,
+    resume-merged; requires ``project_decoder``). Split out so the
+    dashboard cache path (§6) can run the aggregate over a mix of
+    cached + freshly-fetched entries and then classify separately, while
+    the classify phase (``classify_and_summarize``) re-runs fresh each
+    tick. Byte-identical to the inline aggregate it replaced.
     """
     if mode == "day":
-        rows = _aggregate_cache_by_day(
+        return _aggregate_cache_by_day(
             entries,
             display_tz=display_tz, pricing=pricing,
             cost_calculator=cost_calculator,
         )
-    elif mode == "session":
+    if mode == "session":
         if project_decoder is None:
             raise ValueError("session mode requires project_decoder")
-        rows = _aggregate_cache_by_session(
+        return _aggregate_cache_by_session(
             entries,
             pricing=pricing,
             cost_calculator=cost_calculator,
             project_decoder=project_decoder,
         ).rows
-    else:
-        raise ValueError(f"unknown mode: {mode!r}")
+    raise ValueError(f"unknown mode: {mode!r}")
+
 
+def classify_and_summarize(
+    rows: list[CacheRow],
+    *,
+    now_utc: dt.datetime,
+    window_days: int,
+    anomaly_threshold_pp: int,
+    anomaly_window_days: int,
+    display_tz: ZoneInfo | None,
+    mode: Literal["day", "session"] = "day",
+    anomaly_enabled: bool = True,
+) -> _CacheReportResult:
+    """The classify + summarize half of ``_build_cache_report`` (#272 §6).
+
+    Mutates ``rows`` in place (``_classify_anomalies``), computes the
+    day-mode ``today_baseline_median`` (EFF-3), and packages the
+    ``_CacheReportResult``. Split out so the dashboard cache path (§6)
+    can re-run this cross-row pass every tick over freshly reconstructed
+    rows (the cached day aggregates carry no anomaly state), while the
+    per-day aggregates are served from cache. Byte-identical to the
+    inline classify half it replaced.
+    """
     _classify_anomalies(
         rows,
         threshold_pp=anomaly_threshold_pp,
@@ -971,3 +1306,56 @@ def _build_cache_report(
         display_tz_key=display_tz.key if display_tz is not None else None,
         today_baseline_median=today_baseline_median,
     )
+
+
+def _build_cache_report(
+    entries: Iterable,
+    *,
+    now_utc: dt.datetime,
+    window_days: int,
+    anomaly_threshold_pp: int,
+    anomaly_window_days: int,
+    display_tz: ZoneInfo | None,
+    pricing: dict,
+    cost_calculator: Callable[[str, dict, str, Optional[float]], float],
+    mode: Literal["day", "session"] = "day",
+    project_decoder: Callable[[str], str] | None = None,
+    anomaly_enabled: bool = True,
+) -> _CacheReportResult:
+    """Top-level orchestrator: aggregate + classify anomalies.
+
+    Returns a ``_CacheReportResult`` that both the CLI renderer and the
+    dashboard snapshot builder consume. Pure-function — no I/O, no
+    logging, no environment reads. Callers (CLI / dashboard) own all
+    I/O via the ``entries`` iterable + the ``cost_calculator`` /
+    ``project_decoder`` injections.
+
+    ``mode="day"`` buckets entries by display-tz calendar date;
+    ``mode="session"`` buckets by Claude ``sessionId`` (resume-merged
+    across JSONL files). Session mode requires ``project_decoder`` (the
+    CLI passes its ``_decode_escaped_cwd``-backed shim); day mode
+    ignores it.
+
+    The ``since`` window for both modes is ``now_utc − window_days``;
+    the kernel trusts callers to pre-filter via their own query
+    (``get_entries`` / ``get_claude_session_entries``). Composed (#272
+    §6) from ``_aggregate_cache_report_rows`` + ``classify_and_summarize``
+    — the CLI keeps this one-shot orchestrator; the dashboard cache path
+    calls the two halves directly so it can memoize the aggregate.
+    """
+    rows = _aggregate_cache_report_rows(
+        entries,
+        display_tz=display_tz, pricing=pricing,
+        cost_calculator=cost_calculator,
+        mode=mode, project_decoder=project_decoder,
+    )
+    return classify_and_summarize(
+        rows,
+        now_utc=now_utc,
+        window_days=window_days,
+        anomaly_threshold_pp=anomaly_threshold_pp,
+        anomaly_window_days=anomaly_window_days,
+        display_tz=display_tz,
+        mode=mode,
+        anomaly_enabled=anomaly_enabled,
+    )

package/bin/_lib_doctor.py

@@ -164,6 +164,11 @@ class DoctorState:
     conv_sessions_rollup_count: Optional[int] = None
     conv_messages_distinct_sessions: Optional[int] = None
     conv_rollup_sync_in_progress: bool = False
+    # Preview channel (CCTALLY_CHANNEL=preview): "preview" when the binary runs
+    # under the preview channel, else "prod". Populated by `doctor_gather_state`
+    # from the env; surfaced in the install.mode check. Defaulted (placed last)
+    # so existing constructors stay valid and the prod path is unchanged.
+    channel: str = "prod"
 
 
 @dataclasses.dataclass(frozen=True)
@@ -359,6 +364,10 @@ def _check_install_dev_mode(s: DoctorState) -> CheckResult:
         summary = "DEV (git checkout, custom data dir via CCTALLY_DATA_DIR)"
     else:
         summary = "installed"
+    # Preview channel (CCTALLY_CHANNEL=preview): note the channel in the
+    # summary. Gated → prod (channel="prod") summary is unchanged.
+    if s.channel == "preview":
+        summary += " · channel: preview"
     return CheckResult(
         id="install.mode", title="Mode",
         severity="ok", summary=summary, remediation=None,
@@ -366,6 +375,7 @@ def _check_install_dev_mode(s: DoctorState) -> CheckResult:
             "dev_mode": s.dev_mode,
             "is_dev_checkout": s.is_dev_checkout,
             "app_dir": s.app_dir,
+            "channel": s.channel,
         },
     )
 

package/bin/_lib_pricing.py

@@ -67,7 +67,30 @@ LITELLM_PRICES_URL = (
 # or an intentionally-omitted in-scope model ({"model","reason"} — no field).
 # Guarded by `stale_allowlist_entries` (tests/test_pricing_check.py): an entry
 # that no longer corresponds to a real divergence fails the suite.
-PRICING_DRIFT_ALLOWLIST: list[dict] = []
+#
+# claude-sonnet-5 (#274): LiteLLM tracks the $2/$10-per-MTok *introductory* rate
+# (in effect through 2026-08-31); we deliberately embed the durable *standard*
+# $3/$15 rate because the table is date-blind and the promo expires soon (see
+# the CLAUDE_MODEL_PRICING note below). The non-vacuity guard forces these four
+# entries out once LiteLLM reverts to the standard rate post-cutover.
+PRICING_DRIFT_ALLOWLIST: list[dict] = [
+    {
+        "model": "claude-sonnet-5",
+        "field": field,
+        "reason": (
+            "LiteLLM tracks the claude-sonnet-5 introductory rate "
+            "($2/$10 per MTok, through 2026-08-31); we deliberately embed the "
+            "durable standard $3/$15 rate (the table is date-blind). Remove "
+            "once LiteLLM reverts post-cutover (#274)."
+        ),
+    }
+    for field in (
+        "input_cost_per_token",
+        "output_cost_per_token",
+        "cache_creation_input_token_cost",
+        "cache_read_input_token_cost",
+    )
+]
 
 # Anthropic API pricing snapshot:
 # - Source: https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json
@@ -79,9 +102,13 @@ PRICING_DRIFT_ALLOWLIST: list[dict] = []
 #   2026-07-01: added claude-sonnet-5 ($3/$15 per MTok; 1M context, flat-rate
 #   across the full window — no long-context premium, same shape as
 #   claude-sonnet-4-6). Embedded the STANDARD rate, not the $2/$10 introductory
-#   rate in effect through 2026-08-31, to match what LiteLLM will publish and
-#   the durable post-cutover price. LiteLLM has no sonnet-5 entry yet, so the
-#   table is ahead_of_litellm (not a drift finding).
+#   rate in effect through 2026-08-31, because the table is date-blind and
+#   $3/$15 is the durable post-cutover price.
+#   2026-07-06 (#274): LiteLLM published a sonnet-5 entry at the $2/$10
+#   introductory rate, so the deliberate standard-rate choice now surfaces as
+#   value_drift on all four cost fields. Suppressed via PRICING_DRIFT_ALLOWLIST
+#   above (the non-vacuity guard forces removal once LiteLLM reverts to the
+#   standard rate after 2026-08-31).
 CLAUDE_MODEL_PRICING: dict[str, dict[str, Any]] = {
     "claude-3-5-haiku-20241022": {
         "input_cost_per_token": 8e-07,