cctally 1.7.3 → 1.8.0

package/bin/_cctally_dashboard.py

@@ -251,121 +251,55 @@ def _cctally():
     return sys.modules["cctally"]
 
 
+# === Honest imports from extracted homes ===================================
+# Spec 2026-05-17-cctally-core-kernel-extraction.md §3.3: kernel symbols
+# import from _cctally_core; already-decentralized buckets (X = _lib_*,
+# Y = _cctally_*) import from their natural home. These bypass the
+# legacy shim pattern entirely.
+from _cctally_core import (
+    eprint,
+    now_utc_iso,
+    parse_iso_datetime,
+    _now_utc,
+    _command_as_of,
+    open_db,
+    get_latest_usage_for_week,
+    make_week_ref,
+    _get_alerts_config,
+    _AlertsConfigError,
+)
+from _lib_display_tz import (
+    format_display_dt,
+    resolve_display_tz,
+    normalize_display_tz_value,
+    _compute_display_block,
+)
+from _lib_aggregators import _aggregate_daily, _aggregate_monthly, _aggregate_weekly
+from _lib_pricing import _calculate_entry_cost, _chip_for_model, _short_model_name
+from _lib_five_hour import _canonical_5h_window_key
+from _lib_subscription_weeks import _compute_subscription_weeks
+from _lib_blocks import _group_entries_into_blocks
+from _cctally_config import save_config, _load_config_unlocked
+from _cctally_db import _render_migration_error_banner
+from _cctally_cache import get_entries
+
+
 # === Module-level back-ref shims for helpers that STAY in bin/cctally ======
 # Each shim resolves ``sys.modules['cctally'].X`` at CALL TIME (not bind
 # time), so monkeypatches on cctally's namespace propagate into the moved
-# code unchanged. Mirrors the precedent established in
-# ``bin/_cctally_record.py`` (34 shims), ``bin/_cctally_cache.py``
-# (4 shims), ``bin/_cctally_db.py`` (4 shims), and
-# ``bin/_cctally_update.py`` (8 shims).
-def eprint(*args, **kwargs):
-    return sys.modules["cctally"].eprint(*args, **kwargs)
-
-
-def now_utc_iso(*args, **kwargs):
-    return sys.modules["cctally"].now_utc_iso(*args, **kwargs)
-
-
-def parse_iso_datetime(*args, **kwargs):
-    return sys.modules["cctally"].parse_iso_datetime(*args, **kwargs)
-
-
-def _now_utc(*args, **kwargs):
-    return sys.modules["cctally"]._now_utc(*args, **kwargs)
-
-
-def _command_as_of(*args, **kwargs):
-    return sys.modules["cctally"]._command_as_of(*args, **kwargs)
-
-
+# code unchanged. `load_config` and `get_claude_session_entries` STAY as
+# shims even though their natural homes are decentralized (_cctally_config
+# / _cctally_cache) — tests monkeypatch them via `ns["X"]` (21 sites total,
+# audited 2026-05-17); direct imports would silently bypass the patches.
+# See spec §3.5 (carve-out) and §3.7 (stays-on-shim allowlist).
 def load_config(*args, **kwargs):
     return sys.modules["cctally"].load_config(*args, **kwargs)
 
 
-def save_config(*args, **kwargs):
-    return sys.modules["cctally"].save_config(*args, **kwargs)
-
-
-def open_db(*args, **kwargs):
-    return sys.modules["cctally"].open_db(*args, **kwargs)
-
-
-def get_entries(*args, **kwargs):
-    return sys.modules["cctally"].get_entries(*args, **kwargs)
-
-
 def get_claude_session_entries(*args, **kwargs):
     return sys.modules["cctally"].get_claude_session_entries(*args, **kwargs)
 
 
-def get_latest_usage_for_week(*args, **kwargs):
-    return sys.modules["cctally"].get_latest_usage_for_week(*args, **kwargs)
-
-
-def make_week_ref(*args, **kwargs):
-    return sys.modules["cctally"].make_week_ref(*args, **kwargs)
-
-
-def format_display_dt(*args, **kwargs):
-    return sys.modules["cctally"].format_display_dt(*args, **kwargs)
-
-
-def resolve_display_tz(*args, **kwargs):
-    return sys.modules["cctally"].resolve_display_tz(*args, **kwargs)
-
-
-def normalize_display_tz_value(*args, **kwargs):
-    return sys.modules["cctally"].normalize_display_tz_value(*args, **kwargs)
-
-
-def _compute_display_block(*args, **kwargs):
-    return sys.modules["cctally"]._compute_display_block(*args, **kwargs)
-
-
-def _render_migration_error_banner(*args, **kwargs):
-    return sys.modules["cctally"]._render_migration_error_banner(*args, **kwargs)
-
-
-def _aggregate_daily(*args, **kwargs):
-    return sys.modules["cctally"]._aggregate_daily(*args, **kwargs)
-
-
-def _aggregate_monthly(*args, **kwargs):
-    return sys.modules["cctally"]._aggregate_monthly(*args, **kwargs)
-
-
-def _aggregate_weekly(*args, **kwargs):
-    return sys.modules["cctally"]._aggregate_weekly(*args, **kwargs)
-
-
-def _calculate_entry_cost(*args, **kwargs):
-    return sys.modules["cctally"]._calculate_entry_cost(*args, **kwargs)
-
-
-def _canonical_5h_window_key(*args, **kwargs):
-    return sys.modules["cctally"]._canonical_5h_window_key(*args, **kwargs)
-
-
-def _chip_for_model(*args, **kwargs):
-    return sys.modules["cctally"]._chip_for_model(*args, **kwargs)
-
-
-def _short_model_name(*args, **kwargs):
-    return sys.modules["cctally"]._short_model_name(*args, **kwargs)
-
-
-def _compute_subscription_weeks(*args, **kwargs):
-    return sys.modules["cctally"]._compute_subscription_weeks(*args, **kwargs)
-
-
-def _group_entries_into_blocks(*args, **kwargs):
-    return sys.modules["cctally"]._group_entries_into_blocks(*args, **kwargs)
-
-
-def _get_alerts_config(*args, **kwargs):
-    return sys.modules["cctally"]._get_alerts_config(*args, **kwargs)
-
-
 def _warn_alerts_bad_config_once(*args, **kwargs):
     return sys.modules["cctally"]._warn_alerts_bad_config_once(*args, **kwargs)
 
@@ -402,10 +336,6 @@ def doctor_gather_state(*args, **kwargs):
     return sys.modules["cctally"].doctor_gather_state(*args, **kwargs)
 
 
-def _load_config_unlocked(*args, **kwargs):
-    return sys.modules["cctally"]._load_config_unlocked(*args, **kwargs)
-
-
 def _apply_display_tz_override(*args, **kwargs):
     return sys.modules["cctally"]._apply_display_tz_override(*args, **kwargs)
 
@@ -1789,10 +1719,14 @@ def _dashboard_build_monthly_periods(conn: "sqlite3.Connection",
                                      display_tz: "ZoneInfo | None" = None) -> "list[MonthlyPeriodRow]":
     """Latest n calendar months as MonthlyPeriodRow, newest-first.
 
-    Builds via `_aggregate_monthly` over the trailing window
-    [now_utc - n calendar months, now_utc]. Bucketing and `is_current`
-    label both follow `display_tz` so users on a non-host display zone
-    see months grouped consistently with the rest of the UI.
+    Thin wrapper around ``build_monthly_view`` (spec §6.2). The view
+    owns the aggregator call, boundary-spillover drop, delta_cost_pct
+    derivation, and ``is_current`` flagging — this function just
+    fetches the trailing window of entries and returns ``view.rows``.
+
+    The sync thread separately captures ``view.total_cost_usd`` /
+    ``view.total_tokens`` for the envelope; see
+    ``_tui_build_snapshot`` and ``DataSnapshot.monthly_total_*``.
     """
     # Compute window start = first day of the month that is (n - 1) months
     # before the current month. _aggregate_monthly walks all entries and
@@ -1811,44 +1745,10 @@ def _dashboard_build_monthly_periods(conn: "sqlite3.Connection",
     range_end = now_utc
 
     entries = get_entries(range_start, range_end, skip_sync=skip_sync)
-    buckets = _aggregate_monthly(entries, mode="auto", tz=display_tz)
-    # Reverse for newest-first AND cap to n BEFORE the delta loop. In tzs
-    # west of UTC, `range_start` (UTC midnight on the 1st) lands in the
-    # PREVIOUS local month, so entries in the boundary window get bucketed
-    # as a (n+1)th `'YYYY-MM'` row. Slicing here drops that partial bucket,
-    # which (a) keeps the visible history at the requested length and
-    # (b) makes the oldest visible row's delta `None` (prev = None) rather
-    # than a wildly wrong delta vs. a few-hour spillover bucket.
-    buckets = list(reversed(buckets))[:n]
-    rows: list[MonthlyPeriodRow] = []
-    # `_aggregate_monthly` keys buckets by `display_tz` (or local-tz when
-    # unset) month. Mirror that here so `is_current` matches even when
-    # now_utc straddles a tz month boundary (e.g. 23:30 UTC on the last
-    # of the month in a UTC+1 zone).
-    cur_label = (
-        now_utc.astimezone(display_tz) if display_tz is not None
-        # internal fallback: host-local intentional
-        else now_utc.astimezone()
-    ).strftime("%Y-%m")
-    for i, b in enumerate(buckets):
-        # b.bucket is the YYYY-MM string for monthly aggregation.
-        prev = buckets[i + 1] if i + 1 < len(buckets) else None
-        delta = None
-        if prev is not None and prev.cost_usd > 0:
-            delta = (b.cost_usd - prev.cost_usd) / prev.cost_usd
-        rows.append(MonthlyPeriodRow(
-            label=b.bucket,
-            cost_usd=b.cost_usd,
-            total_tokens=b.total_tokens,
-            input_tokens=b.input_tokens,
-            output_tokens=b.output_tokens,
-            cache_creation_tokens=b.cache_creation_tokens,
-            cache_read_tokens=b.cache_read_tokens,
-            delta_cost_pct=delta,
-            is_current=(b.bucket == cur_label),
-            models=_model_breakdowns_to_models(b.model_breakdowns, b.cost_usd),
-        ))
-    return rows
+    c = _cctally()
+    view = c.build_monthly_view(entries, now_utc=now_utc, n=n,
+                                 display_tz=display_tz)
+    return list(view.rows)
 
 
 def _dashboard_build_weekly_periods(conn: "sqlite3.Connection",
@@ -1857,10 +1757,15 @@ def _dashboard_build_weekly_periods(conn: "sqlite3.Connection",
                                     skip_sync: bool = False) -> "list[WeeklyPeriodRow]":
     """Latest n subscription weeks as WeeklyPeriodRow, newest-first.
 
-    Mirrors the bucket+overlay path used by `cmd_weekly`, scoped to a
-    trailing 84-day window (12 weeks plus slack). Boundaries come from
-    `_compute_subscription_weeks`; usage % comes from
-    `weekly_usage_snapshots` via `get_latest_usage_for_week`.
+    Thin builder-using prelude + Bug-K pre-credit synthesis on top of
+    ``view.rows``. ``build_weekly_view`` (in ``bin/_lib_view_models.py``)
+    owns the bucket+overlay walk — this function calls it, swaps two
+    presentation fields (``label`` ← ``display_start_date`` for post-
+    early-reset weeks; ``is_current`` ← SubWeek-containing-now_utc with
+    snapshot fallback so the "Now" pill tracks wall time), layers Bug-K
+    pre-credit synthesized rows over the natural rows, then recomputes
+    ``delta_cost_pct`` newest-first so the synthesized rows participate
+    in the deltas.
 
     Note: weekly bucketing intentionally does NOT take ``display_tz`` —
     SubWeek bucket keys come from server-anchored stored anchors and the
@@ -1878,10 +1783,6 @@ def _dashboard_build_weekly_periods(conn: "sqlite3.Connection",
         parse_iso_datetime(weeks[0].start_ts, "week_start_at"),
     )
     entries = get_entries(fetch_start, range_end, skip_sync=skip_sync)
-    buckets = _aggregate_weekly(entries, weeks)
-    if not buckets:
-        return []
-
     as_of_utc = (
         range_end.astimezone(dt.timezone.utc)
         .replace(microsecond=0)
@@ -1889,6 +1790,15 @@ def _dashboard_build_weekly_periods(conn: "sqlite3.Connection",
         .replace("+00:00", "Z")
     )
 
+    # Builder prelude: produce the natural newest-first rows + overlay.
+    c = _cctally()
+    view = c.build_weekly_view(
+        conn, entries, weeks=weeks, now_utc=now_utc,
+        display_tz=None, as_of_utc=as_of_utc,
+    )
+    if not view.rows:
+        return []
+
     # Prefer the SubWeek that actually contains `now_utc` so the "Now" pill
     # tracks wall time even when `weekly_usage_snapshots` is stale (e.g.,
     # status line hasn't fired yet this week but cost entries already exist).
@@ -1913,47 +1823,36 @@ def _dashboard_build_weekly_periods(conn: "sqlite3.Connection",
         else:
             cur_week_start = max(weeks, key=lambda w: w.start_date).start_date.isoformat()
 
+    # SubWeek lookup by (start_ts, end_ts) — the builder identifies each row
+    # by these ISO strings on ``WeeklyPeriodRow``, which match SubWeek 1:1
+    # post _aggregate_weekly invariant.
+    sw_by_window = {(w.start_ts, w.end_ts): w for w in weeks}
+
+    # Convert builder rows (newest-first) → oldest-first so the existing
+    # Bug-K insertion logic (oldest-first indices) stays unchanged. Override
+    # the two presentation fields that diverge between CLI/share (which use
+    # ``start_date`` + "now in window" semantics) and the dashboard panel
+    # (which uses ``display_start_date`` + "current SubWeek" semantics).
     rows_oldest_first: list[WeeklyPeriodRow] = []
-    for bucket in buckets:
-        sw = next(w for w in weeks if w.start_date.isoformat() == bucket.bucket)
-        # Label = MM-DD of the week's display_start_date — for non-reset
-        # weeks this equals start_date; for post-early-reset weeks the
-        # post-processor shifts it forward to the effective reset moment
-        # so the user sees the date the week actually began (04-23 vs the
-        # API-derived backdated 04-18).
-        label = sw.display_start_date.strftime("%m-%d")
-        ref = make_week_ref(
-            week_start_date=sw.start_date.isoformat(),
-            week_end_date=sw.end_date.isoformat(),
-            week_start_at=sw.start_ts,
-            week_end_at=sw.end_ts,
-        )
-        usage_row = get_latest_usage_for_week(conn, ref, as_of_utc=as_of_utc)
-        used_pct = None
-        dpp = None
-        if usage_row is not None and usage_row["weekly_percent"] is not None:
-            used_pct = float(usage_row["weekly_percent"])
-            dpp = (bucket.cost_usd / used_pct) if used_pct > 0 else None
-        rows_oldest_first.append(WeeklyPeriodRow(
-            label=label,
-            cost_usd=bucket.cost_usd,
-            total_tokens=bucket.total_tokens,
-            input_tokens=bucket.input_tokens,
-            output_tokens=bucket.output_tokens,
-            cache_creation_tokens=bucket.cache_creation_tokens,
-            cache_read_tokens=bucket.cache_read_tokens,
-            used_pct=used_pct,
-            dollar_per_pct=dpp,
-            delta_cost_pct=None,  # filled below in newest-first pass
+    for r in reversed(view.rows):
+        sw = sw_by_window.get((r.week_start_at, r.week_end_at))
+        if sw is not None:
+            # Label = MM-DD of the week's display_start_date — for non-reset
+            # weeks this equals start_date; for post-early-reset weeks the
+            # post-processor shifts it forward to the effective reset moment
+            # so the user sees the date the week actually began (04-23 vs the
+            # API-derived backdated 04-18).
+            r.label = sw.display_start_date.strftime("%m-%d")
             # is_current keys on start_date (the bucket / lookup key) on both
             # sides of the comparison; display_start_date may diverge for
             # reset-event weeks but that is intentional — display vs. lookup
             # are kept separate.
-            is_current=(sw.start_date.isoformat() == cur_week_start),
-            models=_model_breakdowns_to_models(bucket.model_breakdowns, bucket.cost_usd),
-            week_start_at=sw.start_ts,
-            week_end_at=sw.end_ts,
-        ))
+            r.is_current = (sw.start_date.isoformat() == cur_week_start)
+        # delta_cost_pct: builder computed it in asc order; reset and
+        # recompute newest-first below AFTER Bug-K rows merge in, so the
+        # synthesized rows participate in the deltas.
+        r.delta_cost_pct = None
+        rows_oldest_first.append(r)
 
     # Bug K (v1.7.2 round-5): synthesize a pre-credit segment row for
     # each in-place credit event. Without this the credited week shows
@@ -2320,27 +2219,51 @@ def _dashboard_build_daily_panel(conn: "sqlite3.Connection",
                                   display_tz: "ZoneInfo | None" = None) -> "list[DailyPanelRow]":
     """Latest n display-tz dates as DailyPanelRow, newest-first.
 
-    Mirrors `_dashboard_build_monthly_periods`: walks a wide trailing
-    window, runs `_aggregate_daily`, reverses to newest-first, caps to
-    `n`, then computes intensity buckets in-place. Bucketing and the
-    `is_today` reference both follow `display_tz` so users on a
-    non-host display zone see days grouped consistently with the rest
-    of the UI.
+    Two-layer composition (spec §4.4, §6.1):
+
+    1. ``build_daily_view`` (in ``bin/_lib_view_models.py``) is the
+       data plane — gap-free rows + totals derived from the
+       aggregator output.
+    2. This function is the presentation adapter — materializes the
+       contiguous N-day calendar window (gap days as zero-cost rows
+       so the heatmap shows them as faded cells), fills the
+       presentation-only ``label`` (``MM-DD``) and
+       ``intensity_bucket`` (quintile via
+       ``_compute_intensity_buckets``) fields.
+
+    Bucketing and the ``is_today`` reference both follow
+    ``display_tz`` so users on a non-host display zone see days
+    grouped consistently with the rest of the UI.
+
+    Sync-thread totals: the caller sums over the materialized rows
+    this function returns and stashes the result on
+    ``DataSnapshot.daily_total_cost_usd`` / ``daily_total_tokens`` for
+    the envelope adapter. Sum-over-visible-rows preserves the
+    structural-equality invariant the dashboard footer reads
+    (`total === rows.reduce(...)`); gap days carry ``cost_usd=0.0`` /
+    ``total_tokens=0`` so the sum stays gap-free semantically. Doing
+    it at the sync-thread site keeps this function's return type
+    stable (preserving the dashboard / TUI / test fixture monkeypatch
+    surface that consumes a plain ``list[DailyPanelRow]``).
     """
     # Wide trailing window — n days of slack on either side keeps it
     # forgiving of tz boundary issues.
     range_start = now_utc - dt.timedelta(days=n + 1)
     range_end = now_utc
     entries = get_entries(range_start, range_end, skip_sync=skip_sync)
-    buckets = _aggregate_daily(entries, mode="auto", tz=display_tz)
-    if not buckets:
+
+    c = _cctally()
+    view = c.build_daily_view(entries, now_utc=now_utc,
+                              display_tz=display_tz)
+    if not view.rows:
         return []
 
-    # Materialize the full n-day calendar window so gap days render as
-    # zero-cost h0 cells (and today always appears, even on idle days).
-    # _aggregate_daily only emits buckets for dates with entries, so we
-    # overlay them onto a contiguous newest-first range.
-    buckets_by_date = {b.bucket: b for b in buckets}
+    # Materialize the contiguous N-day window. ``view.rows`` is gap-free
+    # (newest-first) and carries the data-plane fields; the adapter
+    # overlays it onto the calendar window and fills the presentation-
+    # only ``label`` / ``intensity_bucket`` (which the builder left at
+    # dataclass defaults per spec §4.4).
+    rows_by_date = {r.date: r for r in view.rows}
     today_local = (
         now_utc.astimezone(display_tz) if display_tz is not None
         # internal fallback: host-local intentional
@@ -2351,28 +2274,12 @@ def _dashboard_build_daily_panel(conn: "sqlite3.Connection",
     for i in range(n):
         d = today_local - dt.timedelta(days=i)
         date_str = d.isoformat()
-        b = buckets_by_date.get(date_str)
-        if b is not None:
-            # cache_read / (input + cache_creation + cache_read) — same ratio
-            # used by Block / Session / TuiSession dashboard surfaces. Do NOT
-            # switch to the diff-metrics formula (cache_read / (cache_read +
-            # input)) without aligning all dashboard surfaces.
-            denom = b.input_tokens + b.cache_creation_tokens + b.cache_read_tokens
-            cache_hit = (b.cache_read_tokens / denom * 100.0) if denom > 0 else None
-            rows.append(DailyPanelRow(
-                date=date_str,
-                label=date_str[5:],  # YYYY-MM-DD → MM-DD
-                cost_usd=b.cost_usd,
-                is_today=(d == today_local),
-                intensity_bucket=0,  # set by _compute_intensity_buckets below
-                models=_model_breakdowns_to_models(b.model_breakdowns, b.cost_usd),
-                input_tokens=b.input_tokens,
-                output_tokens=b.output_tokens,
-                cache_creation_tokens=b.cache_creation_tokens,
-                cache_read_tokens=b.cache_read_tokens,
-                total_tokens=b.total_tokens,
-                cache_hit_pct=cache_hit,
-            ))
+        existing = rows_by_date.get(date_str)
+        if existing is not None:
+            # Use the view-model row but fill the presentation-only
+            # ``label`` (intensity_bucket is set by
+            # ``_compute_intensity_buckets`` below).
+            rows.append(dataclasses.replace(existing, label=date_str[5:]))
         else:
             # Zero-cost gap day: tokens default to 0, cache_hit_pct to None
             # (avoids /0 and signals 'no data' cleanly to the modal tile).
@@ -2947,8 +2854,28 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
     # can distinguish "loading / not synced yet" (null parent) from
     # "synced + no data" (empty rows). For Weekly/Monthly, sync always
     # builds the rows list (even if empty), so we always emit the object.
-    weekly_env = {"rows": [_weekly_row_to_dict(r) for r in snap.weekly_periods]}
-    monthly_env = {"rows": [_monthly_row_to_dict(r) for r in snap.monthly_periods]}
+    weekly_env = {
+        "rows": [_weekly_row_to_dict(r) for r in snap.weekly_periods],
+        # View-model unification (Bundle 1; spec §6.6): pre-computed
+        # totals. Sourced from sum-over-visible-rows in the sync thread
+        # (``_tui_build_snapshot``) so the footer total is structurally
+        # equal to the React panel's ``rows.reduce(...)``. The earlier
+        # ``build_weekly_view``-sourced totals undercounted Bug-K
+        # pre-credit synthesized rows on credit weeks; the regression is
+        # captured by
+        # ``test_weekly_envelope_total_matches_sum_of_visible_rows``.
+        "total_cost_usd": snap.weekly_total_cost_usd,
+        "total_tokens":   snap.weekly_total_tokens,
+    }
+    monthly_env = {
+        "rows": [_monthly_row_to_dict(r) for r in snap.monthly_periods],
+        # View-model unification (Bundle 1; spec §6.6): pre-computed
+        # totals via sum-over-visible-rows so the React MonthlyPanel's
+        # smoking-gun ``rows.reduce(...)`` collapses to a single envelope
+        # read with the structural-equality invariant preserved.
+        "total_cost_usd": snap.monthly_total_cost_usd,
+        "total_tokens":   snap.monthly_total_tokens,
+    }
 
     blocks_env = {"rows": [_blocks_row_to_dict(r) for r in snap.blocks_panel]}
 
@@ -2968,6 +2895,15 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
         "rows":                [_daily_row_to_dict(r) for r in daily_rows],
         "quantile_thresholds": daily_thresholds,
         "peak":                daily_peak,
+        # View-model unification (Bundle 1; spec §6.6): pre-computed
+        # totals via sum-over-visible-rows in the sync thread. Gap days
+        # carry ``cost_usd=0.0`` and ``total_tokens=0`` so summing the
+        # materialized panel rows preserves the gap-free semantics. The
+        # React panel's `rows.reduce(...)` collapses to a single
+        # envelope read with the structural-equality invariant
+        # preserved.
+        "total_cost_usd":      snap.daily_total_cost_usd,
+        "total_tokens":        snap.daily_total_tokens,
     }
 
     # ---- threshold-actions T5: alerts envelope + settings mirror ----
@@ -2987,7 +2923,7 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
     alerts_array = list(getattr(snap, "alerts", []) or [])
     try:
         _alerts_cfg = _get_alerts_config(load_config())
-    except sys.modules["cctally"]._AlertsConfigError as exc:
+    except _AlertsConfigError as exc:
         _warn_alerts_bad_config_once(exc)
         _alerts_cfg = {
             "enabled": False,
@@ -3169,6 +3105,12 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
                     }
                     for w in (snap.weekly_history or [])
                 ],
+                # View-model unification (Bundle 1; spec §6.6): the
+                # pre-computed 3-sample $/% mean. TrendPanel can stop
+                # re-deriving the panel-average; TrendModal's median
+                # over trend.history is out of scope for this refactor
+                # (separate dataset, separate follow-up).
+                "avg_dollars_per_pct": snap.trend_avg_dollars_per_pct,
             },
 
         "weekly":  weekly_env,
@@ -3782,7 +3724,7 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 # save_config has not yet been called).
                 try:
                     _get_alerts_config(merged)
-                except sys.modules["cctally"]._AlertsConfigError as exc:
+                except _AlertsConfigError as exc:
                     self._respond_json(400, {"error": str(exc)})
                     return
 

package/bin/_cctally_db.py

@@ -71,35 +71,32 @@ def _cctally():
     return sys.modules["cctally"]
 
 
-# Module-level back-ref shims for the four callables most heavily used
-# across migration handlers + cmd_db_* renderers. Each shim resolves
-# `sys.modules['cctally'].X` at CALL TIME (not bind time), so
-# monkeypatches on cctally's namespace propagate into the moved code
-# unchanged. This lets the moved function bodies stay byte-identical
-# at every bare-name call site (`now_utc_iso(...)`,
-# `parse_iso_datetime(...)`, etc.) without requiring per-function
-# `c = _cctally()` boilerplate or `c.X` rewrites at every call site.
+# === Honest imports from extracted homes ===================================
+# Spec 2026-05-17-cctally-core-kernel-extraction.md §3.3: kernel symbols
+# import from _cctally_core. The legacy shim functions for these names
+# are deleted.
+from _cctally_core import (
+    eprint,
+    now_utc_iso,
+    parse_iso_datetime,
+)
+
+
+# Module-level back-ref shim for the one Z-high callable that STAYS in
+# bin/cctally. Resolves `sys.modules['cctally'].X` at CALL TIME (not
+# bind time), so monkeypatches on cctally's namespace propagate into the
+# moved code unchanged. `_compute_block_totals` is Z-high (reaches into
+# _cctally_cache via get_claude_session_entries) and is explicitly listed
+# in spec §3.7's stays-on-shim allowlist.
 #
 # Path constants and rarer helpers (`MIGRATION_ERROR_LOG_PATH`,
 # `LOG_DIR`, `DB_PATH`, `CACHE_DB_PATH`, `format_local_iso`) are
 # accessed via the standard `c = _cctally()` + `c.X` pattern instead
 # (call-time lookup so fixture-HOME redirects propagate).
-def now_utc_iso(*args, **kwargs):
-    return sys.modules["cctally"].now_utc_iso(*args, **kwargs)
-
-
-def parse_iso_datetime(*args, **kwargs):
-    return sys.modules["cctally"].parse_iso_datetime(*args, **kwargs)
-
-
 def _compute_block_totals(*args, **kwargs):
     return sys.modules["cctally"]._compute_block_totals(*args, **kwargs)
 
 
-def eprint(*args, **kwargs):
-    return sys.modules["cctally"].eprint(*args, **kwargs)
-
-
 # === BEGIN MOVED REGIONS ===
 # Regions below are inserted verbatim from bin/cctally. Bare-name
 # references to `now_utc_iso(...)`, `parse_iso_datetime(...)`,
@@ -1598,6 +1595,78 @@ def _migration_five_hour_milestones_reset_event_id(conn: sqlite3.Connection) ->
         raise
 
 
+@stats_migration("007_observed_pre_credit_pct")
+def _migration_observed_pre_credit_pct(conn: sqlite3.Connection) -> None:
+    """Add ``observed_pre_credit_pct`` to ``week_reset_events`` so the
+    race-defensive cleanup DELETE in the in-place weekly credit branch
+    has a durable record of the pre-credit baseline we observed at
+    write time — independent of how the upstream claude-statusline
+    tool rounds replays.
+
+    Today statusline replays cctally's ``hwm-7d`` value byte-identically,
+    so the existing strict ``round(.,1)`` equality predicate is sound.
+    Future-proofs against rounding drift: if Anthropic ever rounds the
+    ``--percent`` payload differently from the OAuth API used by
+    record-usage, or if statusline grows its own coarser rounding, a
+    replay at e.g. 67.5 against a stored prior_pct = 67.4 would slip
+    past strict equality and then dominate the reset-aware clamp's
+    MAX over the post-credit segment. With the value stamped on the
+    event row, the cleanup predicate widens to a 1.0pp tolerance band
+    (issue #45) — wide enough to absorb single-digit drift, narrow
+    enough that legitimate post-credit observations (≥25pp away by
+    the in-place credit detection threshold's hypothesis) stay.
+
+    Backfill: NULL on existing rows. NULL is legacy / never-stamped;
+    the live cleanup's bind still uses the current tick's in-scope
+    ``prior_pct`` (the value we just observed and would have stamped),
+    so the cleanup remains correct on the very tick that writes the
+    row. The stored value matters for future tooling that may re-run
+    cleanup against an already-written event row.
+
+    Companion live-path edits land in:
+      - bin/cctally — CREATE TABLE adds the column for fresh installs.
+      - bin/_cctally_record.py — in-place credit INSERT stamps
+        ``observed_pre_credit_pct = prior_pct``; race-defensive DELETE
+        switches from ``round(weekly_percent,1) = round(?,1)`` to
+        ``ABS(weekly_percent - ?) < 1.0``.
+
+    Idempotent: a second invocation finds the column already present
+    and returns. Empty-column fast path: when the live CREATE TABLE
+    already carries the column (fresh install), stamp the marker and
+    return without an ALTER. Simple ADD COLUMN — no UNIQUE constraint
+    change, so no rename-recreate-copy needed (contrast migrations
+    005 / 006).
+    """
+    cols = {
+        str(r[1])
+        for r in conn.execute("PRAGMA table_info(week_reset_events)").fetchall()
+    }
+    if "observed_pre_credit_pct" in cols:
+        conn.execute(
+            "INSERT OR IGNORE INTO schema_migrations (name, applied_at_utc) "
+            "VALUES (?, ?)",
+            ("007_observed_pre_credit_pct", now_utc_iso()),
+        )
+        conn.commit()
+        return
+
+    conn.execute("BEGIN")
+    try:
+        conn.execute(
+            "ALTER TABLE week_reset_events "
+            "ADD COLUMN observed_pre_credit_pct REAL"
+        )
+        conn.execute(
+            "INSERT OR IGNORE INTO schema_migrations (name, applied_at_utc) "
+            "VALUES (?, ?)",
+            ("007_observed_pre_credit_pct", now_utc_iso()),
+        )
+        conn.commit()
+    except Exception:
+        conn.rollback()
+        raise
+
+
 # === Region 8: Test-only migration registration (was bin/cctally:12086-12140) ===
 
 # ──────────────────────────────────────────────────────────────────────