cctally 1.89.2 → 1.90.1

package/bin/_lib_cache_report.py

@@ -115,9 +115,42 @@ CACHE_REPORT_MIN_BASELINE_DAYS = 5
 CACHE_REPORT_MIN_BASELINE_SESSIONS = 10
 
 
-# Literal alias mirroring TS `CacheAnomalyReason` at
-# dashboard/web/src/types/envelope.ts:71 — keeps the two surfaces in
-# lockstep so a typo on either side fails type-check.
+# Anomaly-threshold bounds and default. #443 S3 F17: four sites used to
+# decide independently what `cache_report.anomaly_threshold_pp` means —
+# the Claude read path, the Codex read path, the persistence gate, and
+# the client form. The three Python sites now resolve through here; the
+# TypeScript form's bounds are pinned by
+# tests/test_cache_report_constant_parity.py.
+CACHE_REPORT_DEFAULT_THRESHOLD_PP = 15
+CACHE_REPORT_THRESHOLD_MIN_PP = 1
+CACHE_REPORT_THRESHOLD_MAX_PP = 100
+
+
+def cache_report_threshold_is_valid(raw: object) -> bool:
+    """True when ``raw`` is an in-range int. ``bool`` is not an int here."""
+    return (
+        isinstance(raw, int)
+        and not isinstance(raw, bool)
+        and CACHE_REPORT_THRESHOLD_MIN_PP <= raw <= CACHE_REPORT_THRESHOLD_MAX_PP
+    )
+
+
+def resolve_cache_report_threshold(raw: object) -> int:
+    """Read-path resolution: strict and silent.
+
+    Anything not an in-range int resolves to the default. Callers run
+    inside the per-tick dashboard build loop, so this never warns.
+    """
+    if cache_report_threshold_is_valid(raw):
+        return int(raw)
+    return CACHE_REPORT_DEFAULT_THRESHOLD_PP
+
+
+# Mirrored in TypeScript as the `CacheAnomalyReason` union in
+# dashboard/web/src/types/envelope.ts. The two are kept in lockstep by
+# test_ts_anomaly_reason_union_matches_the_python_literal in
+# tests/test_cache_report_constant_parity.py — NOT by type-check: a
+# Literal-only change on this side compiles fine on both.
 CacheAnomalyReason = Literal["net_negative", "cache_drop"]
 # Every predicate _classify_anomalies can run, in reason-append order. The
 # TypeScript mirror is CACHE_ANOMALY_PREDICATES in cacheReportVerdict.ts.
@@ -219,6 +252,14 @@ class _Bucket:
     zero. The breakdown aggregator only populates the token + cache-$
     fields (``output_tokens`` / ``cost`` stay zero); that's fine — the
     by-project / by-model paths don't surface them.
+
+    The three cache-dollar totals are NOT accumulated with ``+=``.
+    Producers append each addend via ``add_cache_dollars`` and call
+    ``resolve_cache_dollars`` once (#443 S3 F20/F21): a left-to-right
+    float fold over near-cancelling addends is order-dependent, and
+    ``net_usd`` feeds the strict ``< 0`` ``net_negative`` predicate, so
+    entry order alone could flip an anomaly verdict. The token and
+    ``cost`` accumulators stay ``+=`` — ints, or a float no verdict reads.
     """
     input_tokens: int = 0
     output_tokens: int = 0
@@ -228,6 +269,21 @@ class _Bucket:
     saved_usd: float = 0.0
     wasted_usd: float = 0.0
     net_usd: float = 0.0
+    saved_parts: list[float] = field(default_factory=list)
+    wasted_parts: list[float] = field(default_factory=list)
+    net_parts: list[float] = field(default_factory=list)
+
+    def add_cache_dollars(self, saved: float, wasted: float, net: float) -> None:
+        """Retain one addend triple; nothing is folded until resolve."""
+        self.saved_parts.append(saved)
+        self.wasted_parts.append(wasted)
+        self.net_parts.append(net)
+
+    def resolve_cache_dollars(self) -> None:
+        """Collapse the retained addends into order-independent totals."""
+        self.saved_usd = stable_sum(self.saved_parts)
+        self.wasted_usd = stable_sum(self.wasted_parts)
+        self.net_usd = stable_sum(self.net_parts)
 
 
 @dataclass(frozen=True)
@@ -462,9 +518,7 @@ def _aggregate_cache_by_day(
         b.cache_creation_tokens += create_tok
         b.cache_read_tokens += read_tok
         b.cost += cost
-        b.saved_usd += saved
-        b.wasted_usd += wasted
-        b.net_usd += net
+        b.add_cache_dollars(saved, wasted, net)
 
     result: list[CacheRow] = []
     for day_key in sorted(day_model_buckets.keys()):
@@ -472,6 +526,7 @@ def _aggregate_cache_by_day(
         row = CacheRow(date=day_key)
         for model_name in sorted(models.keys()):
             b = models[model_name]
+            b.resolve_cache_dollars()
             mb = CacheModelBreakdown(
                 model_name=model_name,
                 input_tokens=b.input_tokens,
@@ -492,9 +547,12 @@ def _aggregate_cache_by_day(
             row.cache_creation_tokens += mb.cache_creation_tokens
             row.cache_read_tokens += mb.cache_read_tokens
             row.cost += mb.cost
-            row.saved_usd += mb.saved_usd
-            row.wasted_usd += mb.wasted_usd
-            row.net_usd += mb.net_usd
+        # #443 S3 F21: the model-to-row fold, stably summed. Both layers,
+        # or neither works — the order-dependence originates one layer
+        # below, in the same-model entry fold above.
+        row.saved_usd = stable_sum(mb.saved_usd for mb in row.model_breakdowns)
+        row.wasted_usd = stable_sum(mb.wasted_usd for mb in row.model_breakdowns)
+        row.net_usd = stable_sum(mb.net_usd for mb in row.model_breakdowns)
         result.append(row)
     return result
 
@@ -632,9 +690,7 @@ def _aggregate_cache_by_session(
                 cache_1h_tokens=getattr(entry, "cache_1h_tokens", None),
                 speed=getattr(entry, "speed", None),
             )
-            mb_raw.saved_usd += saved
-            mb_raw.wasted_usd += wasted
-            mb_raw.net_usd += net
+            mb_raw.add_cache_dollars(saved, wasted, net)
 
         row = CacheRow(
             session_id=sid,
@@ -644,6 +700,7 @@ def _aggregate_cache_by_session(
         )
         for model_name in sorted(model_buckets.keys()):
             mb_raw = model_buckets[model_name]
+            mb_raw.resolve_cache_dollars()
             mb = CacheModelBreakdown(
                 model_name=model_name,
                 input_tokens=mb_raw.input_tokens,
@@ -666,9 +723,10 @@ def _aggregate_cache_by_session(
             row.cache_creation_tokens += mb.cache_creation_tokens
             row.cache_read_tokens += mb.cache_read_tokens
             row.cost += mb.cost
-            row.saved_usd += mb.saved_usd
-            row.wasted_usd += mb.wasted_usd
-            row.net_usd += mb.net_usd
+        # #443 S3 F21 — the model-to-row fold; see the day aggregator.
+        row.saved_usd = stable_sum(mb.saved_usd for mb in row.model_breakdowns)
+        row.wasted_usd = stable_sum(mb.wasted_usd for mb in row.model_breakdowns)
+        row.net_usd = stable_sum(mb.net_usd for mb in row.model_breakdowns)
         result.append(row)
 
     # Initial ordering descending by last_activity; the CLI's
@@ -693,6 +751,13 @@ def _row_anchor(r: CacheRow) -> dt.datetime | None:
     gives the correct offset for the given date — avoids DST drift on
     dates that straddle a DST boundary. Mirrors the idiom in
     ``_parse_cli_date_range``.
+
+    Since #443 S3 F22 the BASELINE only reaches this for session rows:
+    daily windowing compares calendar dates directly, precisely because
+    a per-date correct offset and an elapsed ``timedelta(days=N)`` bound
+    disagree across a transition. The daily branch stays as the shared
+    definition of "where a daily row sits in time" — it is what
+    ``_sort_cache_rows``'s tiebreaker mirrors.
     """
     if r.last_activity is not None:
         return r.last_activity
@@ -702,45 +767,82 @@ def _row_anchor(r: CacheRow) -> dt.datetime | None:
     return None
 
 
-def _compute_baseline_median(
+def _baseline_samples(
     rows: list[CacheRow],
     *,
-    anchor: dt.datetime,
     window_days: int,
-    min_samples: int,
+    anchor: dt.datetime | None = None,
+    anchor_date: dt.date | None = None,
     exclude_row: CacheRow | None = None,
     is_session_mode: bool = False,
-) -> float | None:
-    """Median ``cache_hit_percent`` across rows whose anchor falls in
-    ``[anchor − window_days, anchor − upper_offset]``.
-
-    Returns ``None`` when fewer than ``min_samples`` rows qualify. The
-    upper offset is ``1s`` in session mode (recent sessions stay
-    eligible even when they collide on the second) and ``1d`` in daily
-    mode (yesterday IS in the baseline but today is excluded).
-
-    ``exclude_row`` lets the per-row classifier skip the focal row when
-    computing the baseline median for that row — without this, a row's
-    own hit % would self-include in its baseline. Callers passing the
-    cross-row "median over the whole window" (e.g. the dashboard
-    spotlight) leave ``exclude_row=None``.
-    """
-    import statistics
+) -> list[float]:
+    """Every ``cache_hit_percent`` admitted to the baseline window.
 
-    upper_offset = (
-        dt.timedelta(seconds=1) if is_session_mode else dt.timedelta(days=1)
-    )
-    lower_bound = anchor - dt.timedelta(days=window_days)
-    upper_bound = anchor - upper_offset
+    ONE definition of the population, so a published sample count and the
+    median cannot disagree (#443 S3 F22).
+
+    ``exclude_row`` lets the per-row classifier skip the focal row —
+    without it, a row's own hit % would self-include in its baseline.
+    Callers wanting the cross-row "median over the whole window" (the
+    dashboard spotlight) leave it ``None``.
+    """
     values: list[float] = []
+    if is_session_mode:
+        # Session anchors are real timestamps, so elapsed-time windowing
+        # is correct here. The upper offset is 1s rather than 1d so
+        # recent sessions stay eligible even when they collide on the
+        # second.
+        if anchor is None:
+            raise ValueError("session mode requires an anchor instant")
+        lower = anchor - dt.timedelta(days=window_days)
+        upper = anchor - dt.timedelta(seconds=1)
+        for r in rows:
+            if exclude_row is not None and r is exclude_row:
+                continue
+            ra = _row_anchor(r)
+            if ra is not None and lower <= ra <= upper:
+                values.append(r.cache_hit_percent)
+        return values
+
+    # Daily mode compares CALENDAR DATES. Daily anchors are date
+    # midnights that follow DST, so an elapsed ``timedelta(days=N)`` bound
+    # excluded a row exactly N calendar days old whenever the UTC offset
+    # changed inside the window — the row landed one hour outside and the
+    # panel then read "baseline sufficient" from a count the median did
+    # not share (#443 S3 F22). ``anchor_date - 1`` is the upper bound
+    # because yesterday IS in the baseline but today is excluded.
+    if anchor_date is None:
+        raise ValueError("daily mode requires an anchor_date")
+    lower_date = anchor_date - dt.timedelta(days=window_days)
+    upper_date = anchor_date - dt.timedelta(days=1)
     for r in rows:
         if exclude_row is not None and r is exclude_row:
             continue
-        ra = _row_anchor(r)
-        if ra is None:
+        if not r.date:
             continue
-        if lower_bound <= ra <= upper_bound:
+        rd = dt.date.fromisoformat(r.date)
+        if lower_date <= rd <= upper_date:
             values.append(r.cache_hit_percent)
+    return values
+
+
+def _compute_baseline_median(
+    rows: list[CacheRow],
+    *,
+    window_days: int,
+    min_samples: int,
+    anchor: dt.datetime | None = None,
+    anchor_date: dt.date | None = None,
+    exclude_row: CacheRow | None = None,
+    is_session_mode: bool = False,
+) -> float | None:
+    """Median over ``_baseline_samples``; ``None`` below ``min_samples``."""
+    import statistics
+
+    values = _baseline_samples(
+        rows, window_days=window_days, anchor=anchor, anchor_date=anchor_date,
+        exclude_row=exclude_row, is_session_mode=is_session_mode,
+    )
     if len(values) < min_samples:
         return None
     return statistics.median(values)
@@ -787,8 +889,11 @@ def _classify_anomalies(
         else CACHE_REPORT_MIN_BASELINE_DAYS
     )
 
-    # Pre-compute anchors once to avoid O(n²·datetime-parse) overhead.
-    anchors: list[dt.datetime | None] = [_row_anchor(r) for r in rows]
+    # Session-mode only: the daily path anchors on the row's own date
+    # string instead (#443 S3 F22), so it has nothing to pre-compute.
+    anchors: list[dt.datetime | None] = (
+        [_row_anchor(r) for r in rows] if is_session_mode else []
+    )
 
     for i, row in enumerate(rows):
         reasons: list[CacheAnomalyReason] = []
@@ -802,13 +907,20 @@ def _classify_anomalies(
             unevaluated.append("net_negative")
 
         # Trigger 2: cache_drop (requires baseline).
-        anchor = anchors[i]
         median = None
-        if anchor is not None:
+        if is_session_mode:
+            anchor = anchors[i]
+            if anchor is not None:
+                median = _compute_baseline_median(
+                    rows, anchor=anchor,
+                    window_days=window_days, min_samples=min_baseline,
+                    exclude_row=row, is_session_mode=True,
+                )
+        elif row.date:
             median = _compute_baseline_median(
-                rows, anchor=anchor,
+                rows, anchor_date=dt.date.fromisoformat(row.date),
                 window_days=window_days, min_samples=min_baseline,
-                exclude_row=row, is_session_mode=is_session_mode,
+                exclude_row=row, is_session_mode=False,
             )
         if median is None:
             unevaluated.append("cache_drop")
@@ -921,12 +1033,11 @@ def _aggregate_cache_breakdown(
                 cache_1h_tokens=getattr(e, "cache_1h_tokens", None),
                 speed=getattr(e, "speed", None),
             )
-        b.saved_usd += saved
-        b.wasted_usd += wasted
-        b.net_usd += net
+        b.add_cache_dollars(saved, wasted, net)
 
     out: list[CacheBreakdownRow] = []
     for key, b in buckets.items():
+        b.resolve_cache_dollars()   # #443 S3 F21 — the per-entry fold.
         out.append(CacheBreakdownRow(
             key=key,
             cache_hit_percent=_compute_cache_hit_percent(
@@ -972,10 +1083,13 @@ def _aggregate_cache_breakdown_from_rows(
             b.input_tokens += mb.input_tokens
             b.cache_creation_tokens += mb.cache_creation_tokens
             b.cache_read_tokens += mb.cache_read_tokens
-            b.net_usd += mb.net_usd
+            # #443 S3 F21 — the cross-row model fold, retained then
+            # stably summed below.
+            b.add_cache_dollars(mb.saved_usd, mb.wasted_usd, mb.net_usd)
 
     out: list[CacheBreakdownRow] = []
     for key, b in buckets.items():
+        b.resolve_cache_dollars()
         out.append(CacheBreakdownRow(
             key=key,
             cache_hit_percent=_compute_cache_hit_percent(
@@ -1319,8 +1433,14 @@ class _CacheReportResult:
     "other" rows (excluding today's row) over the trailing
     ``anomaly_window_days`` — populated in day mode only (session mode
     has no equivalent "today" concept). Surfaced here so the dashboard
-    snapshot builder can read it without re-running
-    ``_compute_baseline_median`` over the same data (EFF-3).
+    snapshot builder can read it without re-running the baseline over the
+    same data (EFF-3).
+
+    ``today_baseline_sample_count`` is how many rows that median was
+    taken over. Both publishers used to count every non-today row instead,
+    unbounded by the baseline window, so the count could report a
+    sufficient baseline while the median was absent (#443 S3 F22). Derived
+    from one population here so the two cannot diverge again.
     """
     rows: list[CacheRow]
     mode: Literal["day", "session"]
@@ -1329,6 +1449,7 @@ class _CacheReportResult:
     anomaly_window_days: int
     display_tz_key: str | None
     today_baseline_median: float | None = None
+    today_baseline_sample_count: int = 0
 
 
 def _aggregate_cache_report_rows(
@@ -1397,30 +1518,37 @@ def classify_and_summarize(
     )
 
     # EFF-3: surface today's baseline median directly on the result so
-    # the dashboard snapshot builder doesn't have to re-run
-    # _compute_baseline_median over the same row set. Day-mode only —
-    # session mode has no equivalent "today" anchor concept. Anchor
-    # construction mirrors the pre-EFF-3 adapter byte-for-byte —
-    # the strptime + astimezone(display_tz_or_UTC) pair treats the
-    # naive parsed datetime as host-local before shifting, which IS
-    # the prior contract; do not change without re-verifying the
-    # dashboard envelope's today.baseline_median_percent stays stable
-    # against the existing golden fixtures.
+    # the dashboard snapshot builder doesn't have to re-run the baseline
+    # over the same row set. Day-mode only — session mode has no
+    # equivalent "today" concept.
+    #
+    # One current day per invocation (#443 S3 F23): ``today_iso`` resolves
+    # through the SAME ``_resolve_bucket_tz`` the row keys were bucketed by,
+    # so the focal day cannot name a date the rows are not keyed by. It
+    # previously fell back to UTC while bucketing fell back to host-local,
+    # which diverged on every non-UTC host.
+    #
+    # One baseline population per invocation (#443 S3 F22): the published
+    # sample count is derived from the samples the median was taken over,
+    # so "count says the baseline is sufficient, median says it is absent"
+    # is unrepresentable rather than merely absent.
     today_baseline_median: float | None = None
+    today_baseline_sample_count = 0
     if mode == "day":
         today_iso = now_utc.astimezone(
-            display_tz if display_tz is not None else dt.timezone.utc
+            _resolve_bucket_tz(display_tz)
         ).strftime("%Y-%m-%d")
-        today_anchor = dt.datetime.strptime(today_iso, "%Y-%m-%d").astimezone(
-            display_tz if display_tz is not None else dt.timezone.utc
-        )
         other_rows = [r for r in rows if r.date != today_iso]
-        today_baseline_median = _compute_baseline_median(
+        samples = _baseline_samples(
             other_rows,
-            anchor=today_anchor,
+            anchor_date=dt.date.fromisoformat(today_iso),
             window_days=anomaly_window_days,
-            min_samples=CACHE_REPORT_MIN_BASELINE_DAYS,
+            is_session_mode=False,
         )
+        today_baseline_sample_count = len(samples)
+        if len(samples) >= CACHE_REPORT_MIN_BASELINE_DAYS:
+            import statistics
+            today_baseline_median = statistics.median(samples)
 
     return _CacheReportResult(
         rows=rows,
@@ -1430,6 +1558,7 @@ def classify_and_summarize(
         anomaly_window_days=anomaly_window_days,
         display_tz_key=display_tz.key if display_tz is not None else None,
         today_baseline_median=today_baseline_median,
+        today_baseline_sample_count=today_baseline_sample_count,
     )
 
 

package/bin/_lib_cache_report_wire.py

@@ -0,0 +1,184 @@
+"""The one builder for every cache-report envelope block.
+
+Before #443 S2 this dict was hand-built at three sites — the Claude
+serializer and both returns of the Codex wire — with nothing enforcing a
+shared key set, which is how the Codex empty return and its populated
+return drifted apart (#443 F18).
+
+Provider parameterization resolves exactly four things and nothing else:
+the percent key(s), whether the not-applicable metadata is emitted, the
+applicable predicate set, and the reason text. Everything else is
+provider-independent by construction.
+
+Every field this module adds for Codex is OPTIONAL and CODEX-ONLY.
+Absence carries the Claude meaning. That is what keeps the Claude
+serializer byte-identical and the dashboard goldens' Claude blocks
+unmoved, which is the safety property the F18 refactor rests on.
+"""
+
+CLAUDE_PREDICATES = ("net_negative", "cache_drop")
+CODEX_PREDICATES = ("cache_drop",)
+
+# Every predicate any provider can carry. Claude happens to span all of
+# them today, but the filter below must key on THIS, not on
+# CLAUDE_PREDICATES: if Claude's set ever shrank, another provider's set
+# could become a superset of it and the filter would silently degrade to a
+# no-op for that provider — a filter that discards nothing, which is the
+# exact failure `filter_inapplicable` exists to prevent.
+ALL_PREDICATES = tuple(
+    dict.fromkeys(CLAUDE_PREDICATES + CODEX_PREDICATES)
+)
+
+# Codex figures that are structurally absent rather than unmeasured.
+# OpenAI charges no cache-write premium, so there is nothing to waste and
+# therefore no ratio of saved to wasted. The VALUES stay numeric through
+# the transition release (a pre-S2 tab calls .toFixed on the first and
+# Math.round on the second); this map is the authoritative signal a
+# current client renders from.
+#
+# Switching these to None, removing the transitional `cache_hit_percent`
+# in _percent, and bumping SOURCE_SCHEMA_VERSION to 4 are ONE release's
+# work, tracked in cctally-dev#465. Doing any of them alone reintroduces
+# the stale-tab crash this retention exists to avoid.
+CODEX_NOT_APPLICABLE = {
+    "wasted_usd": "OpenAI charges no cache-write premium, so Codex has no wasted-cache figure.",
+    "fourteen_day_efficiency_ratio": "Efficiency compares saved against wasted, and Codex has no wasted-cache figure.",
+}
+
+_PREDICATES = {"claude": CLAUDE_PREDICATES, "codex": CODEX_PREDICATES}
+
+
+def applicable_predicates(provider):
+    """Return the anomaly predicates that can apply to ``provider``."""
+    try:
+        return _PREDICATES[provider]
+    except KeyError:
+        raise ValueError(f"unknown cache-report provider: {provider!r}") from None
+
+
+def filter_inapplicable(provider, row):
+    """Drop predicates that do not apply to ``provider`` and re-derive.
+
+    Filtering is an ACTIVE step, not an assumption. Today no Codex row can
+    carry `net_negative` — saved is floored at zero and wasted is
+    hard-zero — but that is a property of how entries are built, not of
+    this builder, and a test that only observed the absence would pass
+    over a builder that discards nothing.
+
+    `anomaly_triggered` is RECOMPUTED from the surviving reasons rather
+    than carried through: keeping a True flag whose only reason was
+    filtered away would publish a verdict with nothing behind it.
+    """
+    applicable = set(applicable_predicates(provider))
+    if applicable.issuperset(ALL_PREDICATES):
+        return row
+    out = dict(row)
+    out["anomaly_reasons"] = [r for r in row["anomaly_reasons"] if r in applicable]
+    out["anomaly_unevaluated"] = [
+        r for r in row["anomaly_unevaluated"] if r in applicable
+    ]
+    out["anomaly_triggered"] = bool(out["anomaly_reasons"])
+    return out
+
+
+def _percent(provider, row):
+    """Emit the percent key(s) for one row-shaped mapping.
+
+    Codex dual-publishes: `cached_input_percent` is authoritative and
+    `cache_hit_percent` carries the identical value for one release, so a
+    tab that spans a `cctally update` keeps reading a true number instead
+    of `Math.floor(NaN)`.
+    """
+    value = row["cache_hit_percent"]
+    if provider == "codex":
+        return {"cached_input_percent": value, "cache_hit_percent": value}
+    return {"cache_hit_percent": value}
+
+
+def _today_block(provider, today):
+    today = filter_inapplicable(provider, today)
+    block = {"date": today["date"]}
+    block.update(_percent(provider, today))
+    block.update({
+        "baseline_median_percent": today["baseline_median_percent"],
+        "delta_pp": today["delta_pp"],
+        "net_usd": today["net_usd"],
+        "saved_usd": today["saved_usd"],
+        "wasted_usd": today["wasted_usd"],
+        "anomaly_triggered": today["anomaly_triggered"],
+        "anomaly_reasons": list(today["anomaly_reasons"]),
+        "baseline_daily_row_count": today["baseline_daily_row_count"],
+        "anomaly_unevaluated": list(today["anomaly_unevaluated"]),
+        "observed": today["observed"],
+    })
+    return block
+
+
+def _day_block(provider, d):
+    d = filter_inapplicable(provider, d)
+    block = {"date": d["date"]}
+    block.update(_percent(provider, d))
+    block.update({
+        "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"]),
+        "anomaly_unevaluated": list(d["anomaly_unevaluated"]),
+        "observed": d["observed"],
+    })
+    return block
+
+
+def _breakdown_block(provider, b):
+    block = {"key": b["key"]}
+    block.update(_percent(provider, b))
+    block["net_usd"] = b["net_usd"]
+    return block
+
+
+def build_cache_report_wire(
+    *, provider, window_days, anomaly_threshold_pp, anomaly_window_days,
+    today, days, by_project, by_model, seven_day_net_usd,
+    seven_day_anomaly_count, fourteen_day_counterfactual_usd,
+    fourteen_day_efficiency_ratio, is_empty,
+):
+    """Serialize one cache-report block for ``provider``.
+
+    ``days`` MUST arrive newest-first and already capped at
+    ``window_days`` — the Codex ``seven_day_anomaly_count`` reconciliation
+    below slices ``[:7]`` positionally, so an oldest-first caller would get
+    a wrong count with no error raised.
+    """
+    applicable_predicates(provider)  # validates
+    day_blocks = [_day_block(provider, d) for d in days]
+    out = {
+        "window_days": window_days,
+        "anomaly_threshold_pp": anomaly_threshold_pp,
+        "anomaly_window_days": anomaly_window_days,
+        "today": _today_block(provider, today),
+        "days": day_blocks,
+        "by_project": [_breakdown_block(provider, b) for b in by_project],
+        "by_model": [_breakdown_block(provider, b) for b in 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": is_empty,
+    }
+    if provider == "codex":
+        out["not_applicable"] = dict(CODEX_NOT_APPLICABLE)
+        out["anomaly_predicates"] = list(CODEX_PREDICATES)
+        # The caller counted anomalies BEFORE inapplicable predicates were
+        # dropped, so its number can outlive every verdict behind it.
+        # Reconciled only where the filter can actually change something:
+        # on Claude the filter is the identity, and re-deriving there
+        # would risk moving a value the byte-stability pin protects.
+        out["seven_day_anomaly_count"] = sum(
+            bool(block["anomaly_triggered"]) for block in day_blocks[:7]
+        )
+    return out

package/bin/cctally

@@ -967,6 +967,7 @@ ProdMigrationRefused = _cctally_db.ProdMigrationRefused
 StatsDbCorruptError = _cctally_db.StatsDbCorruptError
 StatsDbMaintenanceError = _cctally_db.StatsDbMaintenanceError
 StatsEpochMismatchError = _cctally_db.StatsEpochMismatchError
+StatsEpochRebuildDeferred = _cctally_db.StatsEpochRebuildDeferred
 _is_sqlite_corruption_error = _cctally_db._is_sqlite_corruption_error
 _stats_corruption_guidance = _cctally_db._stats_corruption_guidance
 _STATS_MIGRATIONS = _cctally_db._STATS_MIGRATIONS
@@ -988,6 +989,14 @@ _reconcile_durable_applied_migration_errors = (
 )
 _render_migration_error_banner = _cctally_db._render_migration_error_banner
 _BANNER_SUPPRESSED_COMMANDS = _cctally_db._BANNER_SUPPRESSED_COMMANDS
+
+# Readable wrong-epoch stats indexes are converged only by this dedicated
+# hidden worker. Core imports the same module at call time, so parser dispatch,
+# ordinary open deferral, and the worker share one scheduler state.
+_cctally_store = _load_sibling("_cctally_store")
+cmd_stats_epoch_rebuild_internal = (
+    _cctally_store.cmd_stats_epoch_rebuild_internal
+)
 _print_migration_error_banner_if_needed = _cctally_db._print_migration_error_banner_if_needed
 cmd_db_status = _cctally_db.cmd_db_status
 _db_status_for = _cctally_db._db_status_for
@@ -3341,6 +3350,9 @@ def main(argv: list[str] | None = None) -> int:
         # generic DatabaseError so it never renders as a raw traceback.
         eprint(f"cctally: {exc}")
         return 3
+    except StatsEpochRebuildDeferred as exc:
+        eprint(f"cctally: {exc}")
+        return 3
     except AccountAttributionUnavailable as exc:
         # #341: a `--account`-scoped entry read hit a query-time cache degrade
         # (open failure / concurrent ingest) that would drop the account
@@ -3460,8 +3472,8 @@ def _post_command_update_hooks(command: str | None, args) -> None:
         # still cctally-dev at this point). Same rationale class as doctor.
         return
     if command in ("_update-check", "_telemetry-beat", "_codex-quota-verify",
-                   "_codex-replay-drain"):
-        # All four hidden workers are detached and have already done their one job
+                   "_stats-epoch-rebuild", "_codex-replay-drain"):
+        # All five hidden workers are detached and have already done their one job
         # in their own command handler; none must re-enter this hook.
         # Without the guard the ``_update-check`` worker would fall through to
         # the telemetry gate below and (throttle-bounded) spawn a