cctally 1.7.4 → 1.8.0

package/bin/cctally

@@ -345,6 +345,20 @@ _aggregate_codex_sessions = _lib_aggregators._aggregate_codex_sessions
 _session_path_parts = _lib_aggregators._session_path_parts
 _aggregate_claude_sessions = _lib_aggregators._aggregate_claude_sessions
 
+# View-model kernel — per-domain frozen dataclasses + builders.
+# Spec: docs/superpowers/specs/2026-05-17-view-model-unification-design.md.
+_lib_view_models = _load_sibling("_lib_view_models")
+DailyView = _lib_view_models.DailyView
+build_daily_view = _lib_view_models.build_daily_view
+MonthlyView = _lib_view_models.MonthlyView
+build_monthly_view = _lib_view_models.build_monthly_view
+WeeklyView = _lib_view_models.WeeklyView
+build_weekly_view = _lib_view_models.build_weekly_view
+TrendView = _lib_view_models.TrendView
+build_trend_view = _lib_view_models.build_trend_view
+SessionsView = _lib_view_models.SessionsView
+build_sessions_view = _lib_view_models.build_sessions_view
+
 _lib_render = _load_sibling("_lib_render")
 _CODEX_MONTHS = _lib_render._CODEX_MONTHS
 _render_blocks_table = _lib_render._render_blocks_table
@@ -5222,8 +5236,19 @@ def cmd_daily(args: argparse.Namespace) -> int:
     # Collect entries.
     all_entries = get_entries(range_start, range_end)
 
-    # Aggregate by display-tz date (Q5/F6: day boundary follows display.tz).
-    days = _aggregate_daily(all_entries, mode="auto", tz=tz)
+    # Build the unified daily view (spec §5.1: gap-free; the dashboard
+    # heatmap's contiguous-window materialization stays at the dashboard
+    # envelope adapter so CLI byte-stability is preserved). Consume
+    # `view.aggregated` (BucketUsage tuple) for the CLI renderers — the
+    # JSON shape's `bucket` / `model_breakdowns` / `models: list[str]`
+    # fields live on BucketUsage, not on DailyPanelRow. The builder's
+    # `_aggregate_daily` call is the same one we used inline.
+    view = build_daily_view(all_entries, now_utc=_command_as_of(),
+                            display_tz=tz)
+    # `_aggregate_daily` returned ascending order; build_daily_view stores
+    # `aggregated` newest-first. CLI's default order is ascending, so
+    # re-reverse to match the prior on-the-wire shape.
+    days = list(reversed(view.aggregated))
 
     # Shareable-reports gate: --format short-circuits the JSON / table
     # dispatch via `_share_render_and_emit`. The mutex in
@@ -5241,7 +5266,7 @@ def cmd_daily(args: argparse.Namespace) -> int:
         # subcommands (cmd_report's --detail, etc.).
         display_tz_str = _share_display_tz_label(tz)
         snap = _build_daily_snapshot(
-            days,
+            view,
             period_start=range_start,
             period_end=range_end,
             display_tz=display_tz_str,
@@ -5291,7 +5316,18 @@ def cmd_monthly(args: argparse.Namespace) -> int:
 
     all_entries = get_entries(range_start, range_end)
 
-    months = _aggregate_monthly(all_entries, mode="auto", tz=tz)
+    # Build the unified monthly view (spec §5.2: drops boundary-spillover
+    # bucket; computes delta_cost_pct internally). Consume
+    # `view.aggregated` (BucketUsage tuple, newest-first) for CLI byte-
+    # stability — `_bucket_to_json` reads BucketUsage fields not present
+    # on MonthlyPeriodRow.
+    #
+    # Pass a large `n` so the CLI's `--since`/`--until` window controls
+    # how many months render (the dashboard caps at n=12; CLI doesn't).
+    view = build_monthly_view(all_entries, now_utc=_command_as_of(),
+                              n=10**6, display_tz=tz)
+    # The view stores `aggregated` newest-first; CLI default is asc.
+    months = list(reversed(view.aggregated))
 
     # Shareable-reports gate: --format short-circuits the JSON / table
     # dispatch via `_share_render_and_emit`. The mutex in
@@ -5306,7 +5342,7 @@ def cmd_monthly(args: argparse.Namespace) -> int:
         # share spec scope). Same convention as cmd_daily / cmd_report.
         display_tz_str = _share_display_tz_label(tz)
         snap = _build_monthly_snapshot(
-            months,
+            view,
             period_start=range_start,
             period_end=range_end,
             display_tz=display_tz_str,
@@ -5371,15 +5407,7 @@ def cmd_weekly(args: argparse.Namespace) -> int:
     else:
         fetch_start = range_start
     all_entries = get_entries(fetch_start, range_end)
-    buckets = _aggregate_weekly(all_entries, weeks)
-
-    # Align overlay (used_pct, $/1%) to the same order as `buckets`.
-    # `buckets` may be a subset of `weeks` (weeks with no entries are
-    # dropped by _aggregate_weekly), so we look up each bucket's SubWeek
-    # by `start_date.isoformat()` — the invariant enforced by
-    # _aggregate_weekly is that every emitted bucket key maps to exactly
-    # one SubWeek in `weeks`.
-    #
+
     # Bound the usage-snapshot lookup to `<= range_end` so historical
     # `--until <past date>` queries pick the usage% that was current at
     # the end of the requested window rather than the globally latest
@@ -5395,25 +5423,19 @@ def cmd_weekly(args: argparse.Namespace) -> int:
         .isoformat()
         .replace("+00:00", "Z")
     )
-    overlay: list[tuple[float | None, float | None]] = []
-    for bucket in buckets:
-        sw = next(w for w in weeks if w.start_date.isoformat() == bucket.bucket)
-        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,
-        )
-        row = get_latest_usage_for_week(conn, ref, as_of_utc=as_of_utc)
-        # `weekly_usage_snapshots.weekly_percent` is NOT NULL per schema,
-        # but we still guard against missing rows (no snapshot captured
-        # yet for the week).
-        if row is not None and row["weekly_percent"] is not None:
-            pct = float(row["weekly_percent"])
-            dpc = (bucket.cost_usd / pct) if pct > 0 else None
-            overlay.append((pct, dpc))
-        else:
-            overlay.append((None, None))
+
+    # Build the unified weekly view (spec §5.3): runs _aggregate_weekly,
+    # overlays weekly_usage_snapshots per WeekRef. view.aggregated is
+    # the BucketUsage tuple newest-first; view.overlay is the parallel
+    # (used_pct, dollar_per_pct) tuple. We reverse both for CLI's
+    # default asc rendering so the existing renderer's len-equality
+    # assertions stay aligned.
+    view = build_weekly_view(
+        conn, all_entries, weeks=weeks, now_utc=now_utc,
+        display_tz=args._resolved_tz, as_of_utc=as_of_utc,
+    )
+    buckets = list(reversed(view.aggregated))
+    overlay = list(reversed(view.overlay))
 
     # Shareable-reports gate: --format short-circuits the JSON / table
     # dispatch via `_share_render_and_emit`. The mutex in
@@ -5428,7 +5450,7 @@ def cmd_weekly(args: argparse.Namespace) -> int:
     if getattr(args, "format", None):
         display_tz_str = _share_display_tz_label(args._resolved_tz)
         snap = _build_weekly_snapshot(
-            buckets, overlay,
+            view,
             period_start=range_start,
             period_end=range_end,
             display_tz=display_tz_str,
@@ -6506,7 +6528,20 @@ def cmd_session(args: argparse.Namespace) -> int:
     range_start, range_end = range
 
     entries = get_claude_session_entries(range_start, range_end)
-    sessions = _aggregate_claude_sessions(entries)
+    # Unified view-model kernel (spec §6.5). `limit=None` keeps the
+    # full aggregator output — `cctally session` has no `--limit` flag
+    # and emits every session in the requested range. `view.aggregated`
+    # is the `list[ClaudeSessionUsage]` shape the legacy CLI / share
+    # renderers consume (table, --json, share-snapshot); `view.rows`
+    # is the typed `TuiSessionRow` tuple reserved for the TUI /
+    # dashboard wiring in Task 15 / 16. Keeping both shapes parallel
+    # at the builder preserves the resumed-session merge invariant
+    # documented in CLAUDE.md (one sessionId across multiple JSONL
+    # files collapses to ONE entry in BOTH tuples).
+    view = build_sessions_view(
+        entries, now_utc=_command_as_of(), limit=None, display_tz=tz,
+    )
+    sessions = list(view.aggregated)
 
     # Shareable-reports gate: --format short-circuits the JSON / table
     # dispatch via `_share_render_and_emit`. The mutex in
@@ -6540,7 +6575,7 @@ def cmd_session(args: argparse.Namespace) -> int:
         # cmd_daily / cmd_project.
         display_tz_str = _share_display_tz_label(tz)
         snap = _build_session_snapshot(
-            sessions,
+            view,
             period_start=range_start,
             period_end=range_end,
             display_tz=display_tz_str,
@@ -7874,7 +7909,7 @@ def cmd_report(args: argparse.Namespace) -> int:
                     we_d + dt.timedelta(days=1), dt.time.min, tzinfo=local_tz
                 )
                 snap = _build_report_snapshot(
-                    [],
+                    TrendView(),
                     period_start=ws_dt,
                     period_end=we_dt,
                     display_tz=display_tz_str,
@@ -7890,124 +7925,113 @@ def cmd_report(args: argparse.Namespace) -> int:
                 print("No data yet. Add record-usage to your status line script (see record-usage --help).")
             return 0
 
-        trend: list[dict[str, Any]] = []
-        current_row: dict[str, Any] | None = None
-
-        # Resolve oauth_usage cfg once -- it's loop-invariant across all
-        # trend rows. Falls back to defaults on config validation error.
-        try:
-            _fresh_cfg = _get_oauth_usage_config(config)
-        except OauthUsageConfigError:
-            _fresh_cfg = _get_oauth_usage_config({})
-
-        # Build a set of week_start_date keys that occur MORE THAN ONCE
-        # in `weeks` — these are credited weeks (round-3, Bug B) where
-        # `_apply_reset_events_to_weekrefs` synthesized a pre-credit
-        # ref alongside the post-credit ref. Both refs share
-        # `week_start_date` so the default
-        # ``get_latest_usage_for_week(conn, ref)`` returns the SAME row
-        # (the most recent snapshot in the whole week) for both,
-        # collapsing the pre-credit row's `weeklyPercent` to the
-        # post-credit value. For those keys ONLY, pin `as_of_utc` to
-        # the ref's `week_end_at` so each segment renders its own
-        # latest snapshot. Non-credit weeks (single ref per key) keep
-        # the legacy unfiltered lookup so test fixtures that seed
-        # snapshots OUTSIDE the API-derived week window (e.g.
-        # `test_report_freshness`) keep finding their rows.
-        _split_keys = {
-            r.week_start.isoformat()
-            for r in weeks
-            if sum(
-                1 for x in weeks
-                if x.week_start.isoformat() == r.week_start.isoformat()
-            ) > 1
-        }
-
-        for week_ref in weeks:
-            key = week_ref.week_start.isoformat()
-            usage = get_latest_usage_for_week(
-                conn,
-                week_ref,
-                as_of_utc=(
-                    week_ref.week_end_at if key in _split_keys else None
-                ),
+        # Build the unified trend view (spec §5.4). `build_trend_view`
+        # owns the per-row construction, including:
+        # - get_latest_usage_for_week with split-key as_of_utc pinning
+        #   for credited weeks (Bug D / round-3 Bug B parity)
+        # - _week_ref_has_reset_event → _compute_cost_for_weekref bypass
+        #   for reset-affected weeks
+        # - freshness sub-dict derivation
+        # - 3-sample-rule average
+        # Note: build_trend_view returns rows oldest-first (chronological);
+        # cmd_report's JSON contract is newest-first to mirror
+        # get_recent_weeks's order — we reverse below.
+        view = build_trend_view(conn, now_utc=_command_as_of(), n=args.weeks,
+                                 display_tz=tz)
+        # Serialize TuiTrendRow → today's camelCase keys. Order:
+        # newest-first (matches the prior cmd_report behavior).
+        # Map week_start_date → original WeekRef ISO strings so the
+        # JSON serialization preserves the snapshot-stored tz format
+        # (`+00:00` for UTC-anchored weeks) — TuiTrendRow's datetime
+        # form re-localizes via parse_iso_datetime, which would emit
+        # `+03:00` on a UTC+3 host and break byte-stability.
+        #
+        # Index by ``(week_start_date_iso, week_start_at_utc_instant)``
+        # so ``_row_to_dict`` resolves a row's original WeekRef ISO
+        # strings in O(1) — credited weeks share ``week_start_date`` so
+        # the UTC-instant disambiguates them. The lookup key matches the
+        # row-side derivation in ``_row_to_dict`` (UTC instant from the
+        # parsed datetime).
+        week_iso_by_key: dict[tuple[str, dt.datetime],
+                              tuple[str | None, str | None]] = {}
+        for wr in weeks:
+            if wr.week_start_at is None:
+                continue
+            try:
+                wr_utc = parse_iso_datetime(
+                    wr.week_start_at, "wr.week_start_at",
+                ).astimezone(dt.timezone.utc)
+            except ValueError:
+                continue
+            week_iso_by_key[(wr.week_start.isoformat(), wr_utc)] = (
+                wr.week_start_at,
+                wr.week_end_at,
             )
 
-            # For weeks touched by a reset event, the cached
-            # weekly_cost_snapshots row covers the API-derived range (which
-            # extends past the reset into the NEW week or starts days
-            # BEFORE the reset in the new week). Bypass the cache and live-
-            # compute from session_entries over the effective range that
-            # _apply_reset_events_to_weekrefs baked into the ref. Normal
-            # weeks still hit the cache — zero perf change for the common
-            # path. `cost_captured_at` is pinned to the usage snapshot's
-            # captured time (not wall-clock `now_utc`): `_trend_row_recency_
-            # seconds` ranks the trend table by the freshest-data timestamp,
-            # and if every reset-affected week reported wall-clock now the
-            # oldest such week would sort like the newest and the current
-            # subscription week could slide below historical rows.
-            cost: sqlite3.Row | None = None
-            usage_captured_at = usage["captured_at_utc"] if usage else None
-            if _week_ref_has_reset_event(conn, week_ref):
-                cost_usd = _compute_cost_for_weekref(week_ref)
-                cost_captured_at = usage_captured_at if cost_usd is not None else None
-                range_start_iso = week_ref.week_start_at
-                range_end_iso = week_ref.week_end_at
-            else:
-                cost = get_latest_cost_for_week(conn, week_ref)
-                cost_usd = float(cost["cost_usd"]) if cost else None
-                cost_captured_at = cost["captured_at_utc"] if cost else None
-                range_start_iso = cost["range_start_iso"] if cost and cost["range_start_iso"] else None
-                range_end_iso = cost["range_end_iso"] if cost and cost["range_end_iso"] else None
-
-            percent = float(usage["weekly_percent"]) if usage else None
-            ratio = (cost_usd / percent) if (cost_usd is not None and percent and percent > 0) else None
-            usage_captured_dt = _parse_iso_datetime_optional(usage_captured_at)
-            cost_captured_dt = _parse_iso_datetime_optional(cost_captured_at)
-
-            as_of_dt: dt.datetime | None = None
-            if usage_captured_dt and cost_captured_dt:
-                as_of_dt = usage_captured_dt if usage_captured_dt >= cost_captured_dt else cost_captured_dt
-            else:
-                as_of_dt = usage_captured_dt or cost_captured_dt
-            as_of = as_of_dt.isoformat(timespec="seconds") if as_of_dt else None
-
-            row = {
-                "weekStartDate": week_ref.week_start.isoformat(),
-                "weekEndDate": week_ref.week_end.isoformat() if week_ref.week_end else None,
-                "weekStartAt": week_ref.week_start_at,
-                "weekEndAt": week_ref.week_end_at,
-                "weeklyPercent": percent,
-                "weeklyCostUSD": round(cost_usd, 9) if cost_usd is not None else None,
-                "dollarsPerPercent": round(ratio, 9) if ratio is not None else None,
-                "usageCapturedAt": usage_captured_at,
-                "costCapturedAt": cost_captured_at,
-                "asOf": as_of,
-                "rangeStartIso": range_start_iso,
-                "rangeEndIso": range_end_iso,
+        def _row_to_dict(r):
+            # Match this row's WeekRef by (week_start_date, UTC instant
+            # of parsed week_start_at) — credited weeks share
+            # week_start_date so we disambiguate via the UTC instant.
+            wsd_str = (
+                r.week_start_date.isoformat() if r.week_start_date else None
+            )
+            ws_at = ws_at_end = None
+            if wsd_str is not None and r.week_start_at is not None:
+                r_utc = r.week_start_at.astimezone(dt.timezone.utc)
+                hit = week_iso_by_key.get((wsd_str, r_utc))
+                if hit is not None:
+                    ws_at, ws_at_end = hit
+
+            d: dict[str, Any] = {
+                "weekStartDate": wsd_str,
+                "weekEndDate": (
+                    r.week_end_date.isoformat() if r.week_end_date else None
+                ),
+                "weekStartAt": ws_at,
+                "weekEndAt": ws_at_end,
+                "weeklyPercent": r.used_pct,
+                "weeklyCostUSD": (
+                    round(r.weekly_cost_usd, 9)
+                    if r.weekly_cost_usd is not None else None
+                ),
+                "dollarsPerPercent": (
+                    round(r.dollars_per_percent, 9)
+                    if r.dollars_per_percent is not None else None
+                ),
+                "usageCapturedAt": r.usage_captured_at,
+                "costCapturedAt": r.cost_captured_at,
+                "asOf": r.as_of,
+                "rangeStartIso": r.range_start_iso,
+                "rangeEndIso": r.range_end_iso,
             }
-            if usage_captured_at:
-                age_s = _seconds_since_iso(usage_captured_at)
-                if age_s is not None and age_s <= 86400:
-                    row["freshness"] = {
-                        "label": _freshness_label(age_s, _fresh_cfg),
-                        "captured_at": usage_captured_at,
-                        "age_seconds": int(age_s),
-                    }
+            if r.freshness:
+                d["freshness"] = r.freshness
+            return d
+
+        # view.rows is oldest-first; reverse for cmd_report's newest-first
+        # JSON contract. Also need WeekRef-based current_row matching —
+        # use weekRef key + week_start_at to disambiguate credited weeks.
+        # We re-walk the original `weeks` list to map (key, week_start_at)
+        # → the corresponding dict row.
+        trend: list[dict[str, Any]] = []
+        current_row: dict[str, Any] | None = None
+        # `view.rows` order = chrono asc (oldest first). Build trend in
+        # the reverse order (newest first) to match the historical
+        # cmd_report contract.
+        # The view's TuiTrendRow doesn't carry WeekRef.key directly; we
+        # use (week_start_date, week_start_at) for the match — week_start_at
+        # in TuiTrendRow is a parsed datetime, and current_ref carries
+        # ISO strings.
+        for r in reversed(view.rows):
+            row = _row_to_dict(r)
             trend.append(row)
-            # Bug D (v1.7.2 round-4): for credited weeks `weeks` contains
-            # TWO refs sharing `key` (pre-credit + post-credit segments).
-            # `current_ref` was routed through
-            # `_apply_reset_events_to_weekrefs` above so its
-            # `week_start_at` reflects the post-credit segment's effective
-            # start (or the original start for non-credit weeks). Match on
-            # BOTH `key` AND `week_start_at` so the pre-credit ref doesn't
-            # overwrite the post-credit row's selection on the second
-            # iteration (last-write-wins on key-only equality picked the
-            # wrong row on the user's live data).
+            # Match against current_ref. Compare by week_start ISO date
+            # AND week_start_at ISO string.
+            week_start_at_iso = row["weekStartAt"]
             if (
-                week_ref.key == current_ref.key
-                and week_ref.week_start_at == current_ref.week_start_at
+                r.week_start_date is not None
+                and r.week_start_date.isoformat() == current_ref.key
+                and week_start_at_iso == current_ref.week_start_at
             ):
                 current_row = row
 
@@ -8051,17 +8075,28 @@ def cmd_report(args: argparse.Namespace) -> int:
             # detail isn't in the share spec scope). Same convention applies
             # to other share-enabled subcommands (cmd_daily's --breakdown,
             # etc.).
-            ordered_trend = list(reversed(trend))
-            if ordered_trend:
-                first_wsd = ordered_trend[0].get("weekStartDate")
-                last_wed = ordered_trend[-1].get("weekEndDate") or ordered_trend[-1].get("weekStartDate")
+            #
+            # `view.rows` is already chronological (oldest-first), the
+            # order the chart needs. period_start / period_end derived
+            # from the view's oldest / newest rows.
+            if view.rows:
+                first_r = view.rows[0]
+                last_r = view.rows[-1]
+                first_wsd = (
+                    first_r.week_start_date.isoformat()
+                    if first_r.week_start_date else None
+                )
+                last_wed = (
+                    last_r.week_end_date.isoformat()
+                    if last_r.week_end_date else first_wsd
+                )
                 period_start = _share_parse_date_to_dt(first_wsd, tz)
                 period_end = _share_parse_date_to_dt(last_wed, tz)
             else:
                 period_start = period_end = _share_now_utc()
             display_tz_str = _share_display_tz_label(tz)
             snap = _build_report_snapshot(
-                ordered_trend,
+                view,
                 period_start=period_start,
                 period_end=period_end,
                 display_tz=display_tz_str,
@@ -12283,7 +12318,7 @@ def _share_display_tz_label(tz: "ZoneInfo | None") -> str:
 
 
 def _build_report_snapshot(
-    rows: list[dict[str, object]],
+    view: "TrendView",
     *,
     period_start: dt.datetime,
     period_end: dt.datetime,
@@ -12294,21 +12329,23 @@ def _build_report_snapshot(
 ) -> "ShareSnapshot":
     """Build a ShareSnapshot for `cctally report`.
 
-    `rows` is the in-memory `trend` list produced by `cmd_report` — a list
-    of dicts keyed in the existing JSON-shape camelCase
-    (`weekStartDate`, `weeklyPercent`, `weeklyCostUSD`, `dollarsPerPercent`).
-    The plan's snake_case keys (`week_start_date`, `used_pct`, `cost_usd`,
-    `dollar_per_pct`) are NOT the actual `cmd_report` data shape — see
-    Implementor 7 commit body for the deviation.
+    Consumes the unified TrendView (spec §6.4). `view.rows` is the
+    chronological (oldest-first) TuiTrendRow tuple — exactly the order
+    the chart needs (BarChart polyline trends left→right with time);
+    no reversal needed.
 
-    Caller MUST pass `rows` in chronological order (oldest first) so the
-    chart line trends left→right with time. `cmd_report`'s native `trend`
-    is newest-first; the gate site reverses before calling.
+    The earlier camelCase-dict workaround (recorded in the commit body
+    of Implementor 7 of the share-v2 work) is obsolete: `TuiTrendRow`
+    now carries 10 nullable extended fields (spec §4.1) and is the
+    single typed shape that flows through both CLI report and share
+    builders. Cmd_report's JSON serialization happens at the gate site
+    (camelCase mapping done in cmd_report); this function reads
+    attributes directly from the typed row.
 
-    `theme` and `reveal_projects` flow into the subtitle directly so the
-    builder owns the canonical subtitle shape — no post-build re-stamp at
-    the gate site. The forward-reference return type matches the kernel's
-    lazy-import boundary.
+    `theme` and `reveal_projects` flow into the subtitle directly so
+    the builder owns the canonical subtitle shape — no post-build
+    re-stamp at the gate site. The forward-reference return type
+    matches the kernel's lazy-import boundary.
     """
     _lib_share = _share_load_lib()
     columns = (
@@ -12318,12 +12355,11 @@ def _build_report_snapshot(
         _lib_share.ColumnSpec(key="dpp", label="$ / %", align="right",
                               emphasis=True),
     )
+    rows = view.rows  # oldest-first; matches chart's left→right walk.
     snap_rows: list = []
     chart_pts: list = []
     for i, r in enumerate(rows):
-        wsd = r.get("weekStartDate")
-        # `weekStartDate` is sourced from `week_ref.week_start.isoformat()`
-        # — guaranteed `str`. Empty / unparseable falls back to em-dash.
+        wsd = r.week_start_date.isoformat() if r.week_start_date else None
         if isinstance(wsd, str) and wsd:
             try:
                 week_label = dt.date.fromisoformat(wsd).strftime("%b %d")
@@ -12336,9 +12372,9 @@ def _build_report_snapshot(
         # share artifact follows the same convention. Coercing None to
         # 0.0 would render `$0.00` / `0.0%` — indistinguishable from a
         # genuine zero, and would skew the avg / chart.
-        used_pct_raw = r.get("weeklyPercent")
-        cost_raw = r.get("weeklyCostUSD")
-        dpp_raw = r.get("dollarsPerPercent")
+        used_pct_raw = r.used_pct
+        cost_raw = r.weekly_cost_usd
+        dpp_raw = r.dollars_per_percent
         snap_rows.append(_lib_share.Row(cells={
             "week": _lib_share.TextCell(week_label),
             "used": (
@@ -12367,10 +12403,17 @@ def _build_report_snapshot(
         _lib_share.LineChart(points=tuple(chart_pts), y_label="$ / %")
         if len(chart_pts) >= 3 else None
     )
-    avg_dpp = (
-        sum(p.y_value for p in chart_pts) / len(chart_pts)
-        if chart_pts else 0.0
-    )
+    # Source the avg from the view (3-sample rule). Falls back to a
+    # length-based average over the chart points for the <3-sample case
+    # so the Totalled cell always renders something concrete; preserves
+    # the prior $0.00 sentinel on empty data.
+    if view.avg_dollars_per_pct is not None:
+        avg_dpp = view.avg_dollars_per_pct
+    else:
+        avg_dpp = (
+            sum(p.y_value for p in chart_pts) / len(chart_pts)
+            if chart_pts else 0.0
+        )
     totals = (
         _lib_share.Totalled(label="Avg $/%", value=f"${avg_dpp:,.2f}"),
     )
@@ -12399,7 +12442,7 @@ def _build_report_snapshot(
 
 
 def _build_daily_snapshot(
-    rows: list["BucketUsage"],
+    view: "DailyView",
     *,
     period_start: dt.datetime,
     period_end: dt.datetime,
@@ -12410,10 +12453,11 @@ def _build_daily_snapshot(
 ) -> "ShareSnapshot":
     """Build a ShareSnapshot for `cctally daily`.
 
-    `rows` is the in-memory `BucketUsage` list produced by `_aggregate_daily`
-    inside `cmd_daily`. Each bucket has: `bucket` (YYYY-MM-DD date string),
-    `cost_usd`, `model_breakdowns` (list[dict] sorted by cost desc; first
-    entry is the top model).
+    Consumes the unified DailyView (spec §6.1). `view.aggregated` is
+    the gap-free BucketUsage tuple in newest-first order; we reverse
+    here so BarChart bars render left-to-right chronologically.
+    `view.total_cost_usd` is the pre-computed sum (replacing the
+    prior inline re-totaling).
 
     Deviations from the plan sketch (which assumed dict rows with keys
     `date` / `cost_usd` / `pct_of_week` / `top_model`):
@@ -12426,13 +12470,11 @@ def _build_daily_snapshot(
     - `top_model` is the first entry of `model_breakdowns` (sorted by cost
       desc per upstream ccusage parity); empty → "—".
 
-    Caller MUST pass `rows` in chronological order so the BarChart bars
-    line up left-to-right with time. `_aggregate_daily` already returns
-    asc; the gate site re-sorts after `args.order == "desc"` was applied.
-
-    `theme` and `reveal_projects` flow into the subtitle directly so the
-    builder owns the canonical subtitle shape — no post-build re-stamp at
-    the gate site.
+    `period_start` / `period_end` / `display_tz` are passed by the
+    caller (they reflect the CLI's `--since` / `--until` window which
+    may extend past the data window). `theme` and `reveal_projects`
+    flow into the subtitle directly so the builder owns the canonical
+    subtitle shape — no post-build re-stamp at the gate site.
     """
     _lib_share = _share_load_lib()
     columns = (
@@ -12444,9 +12486,11 @@ def _build_daily_snapshot(
         _lib_share.ColumnSpec(key="top_model", label="Top Model",
                               align="left"),
     )
-    total_cost = 0.0
-    for r in rows:
-        total_cost += float(getattr(r, "cost_usd", 0.0) or 0.0)
+    # Caller MUST pass rows in chronological order so the BarChart bars
+    # line up left-to-right with time. view.aggregated is newest-first
+    # (matches dashboard convention); reverse for chronological iteration.
+    rows = list(reversed(view.aggregated))
+    total_cost = view.total_cost_usd
 
     snap_rows: list = []
     chart_pts: list = []
@@ -12514,7 +12558,7 @@ def _build_daily_snapshot(
 
 
 def _build_monthly_snapshot(
-    rows: list["BucketUsage"],
+    view: "MonthlyView",
     *,
     period_start: dt.datetime,
     period_end: dt.datetime,
@@ -12525,9 +12569,9 @@ def _build_monthly_snapshot(
 ) -> "ShareSnapshot":
     """Build a ShareSnapshot for `cctally monthly`.
 
-    `rows` is the in-memory `BucketUsage` list produced by `_aggregate_monthly`
-    inside `cmd_monthly`. Each bucket has: `bucket` (YYYY-MM string),
-    `cost_usd`, and `model_breakdowns` (list[dict] sorted by cost desc).
+    Consumes the unified MonthlyView (spec §6.2). `view.aggregated` is
+    the gap-free BucketUsage tuple in newest-first order; we reverse
+    so BarChart bars render left-to-right chronologically.
 
     Deviations from the plan sketch (which assumed dict rows with keys
     `month` / `cost_usd` / `sessions`):
@@ -12540,14 +12584,15 @@ def _build_monthly_snapshot(
     - `Δ vs prior` is computed on `cost_usd` between consecutive ASC-sorted
       months, matching the plan's intent.
 
-    Caller MUST pass `rows` in chronological order so the BarChart bars line
-    up left-to-right with time. `_aggregate_monthly` already returns asc;
-    the gate site fires before the `--order desc` reversal in `cmd_monthly`.
-
-    `theme` and `reveal_projects` flow into the subtitle directly so the
-    builder owns the canonical subtitle shape — no post-build re-stamp at
-    the gate site.
+    `period_start` / `period_end` / `display_tz` are passed by the
+    caller (the CLI's `--since` / `--until` window may extend past
+    the data window). `theme` / `reveal_projects` flow into the
+    subtitle directly so the builder owns the canonical subtitle
+    shape — no post-build re-stamp at the gate site.
     """
+    # Caller MUST pass rows in chronological order so the BarChart bars
+    # line up left-to-right with time. view.aggregated is newest-first.
+    rows = list(reversed(view.aggregated))
     _lib_share = _share_load_lib()
     columns = (
         _lib_share.ColumnSpec(key="month", label="Month", align="left"),
@@ -12625,8 +12670,7 @@ def _build_monthly_snapshot(
 
 
 def _build_weekly_snapshot(
-    rows: list["BucketUsage"],
-    overlay: list[tuple[float | None, float | None]],
+    view: "WeeklyView",
     *,
     period_start: dt.datetime,
     period_end: dt.datetime,
@@ -12638,16 +12682,19 @@ def _build_weekly_snapshot(
 ) -> "ShareSnapshot":
     """Build a ShareSnapshot for `cctally weekly`.
 
-    `rows` is the in-memory `BucketUsage` list produced by `_aggregate_weekly`
-    inside `cmd_weekly`; each bucket carries `bucket` (week_start_date as
-    "YYYY-MM-DD"), `cost_usd`, `total_tokens`, and `model_breakdowns`
-    (list[dict] sorted by cost desc, each `{modelName, ..., cost}`).
+    Consumes the unified WeeklyView (spec §6.3). `view.aggregated` is
+    the gap-free BucketUsage tuple newest-first; `view.overlay` is the
+    parallel `(used_pct, dollars_per_pct)` tuple. We reverse both for
+    chronological iteration so BarChart bars render left-to-right
+    with time.
 
-    `overlay` is the parallel list of `(used_pct, dollars_per_pct)` tuples
-    computed by `cmd_weekly` from `weekly_usage_snapshots`. Either component
-    may be `None` for a week that has no captured snapshot yet — surfaces
-    in the snapshot row as a `0.0` PercentCell so the column stays aligned
-    (matching the table renderer's "no data → 0%" behavior).
+    Each bucket carries `bucket` (week_start_date as "YYYY-MM-DD"),
+    `cost_usd`, `total_tokens`, and `model_breakdowns` (list[dict]
+    sorted by cost desc, each `{modelName, ..., cost}`). Either
+    overlay component may be `None` for a week with no captured
+    snapshot — surfaces in the snapshot row as a `0.0` PercentCell so
+    the column stays aligned (matching the table renderer's "no data
+    → 0%" behavior).
 
     Deviations from the plan sketch (which assumed dict rows with keys
     `week_start_date` / `used_pct` / `cost_usd` / `sessions` /
@@ -12671,14 +12718,14 @@ def _build_weekly_snapshot(
     All model-axis iteration uses a single sorted list (`all_model_keys`)
     so column / stack ordering is deterministic across runs.
 
-    Caller MUST pass `rows` (and `overlay` aligned to it) in chronological
-    order so the BarChart bars line up left-to-right with time. The gate
-    site fires BEFORE the `--order desc` reversal in `cmd_weekly`.
-
     `theme` and `reveal_projects` flow into the subtitle directly so the
     builder owns the canonical subtitle shape — no post-build re-stamp at
     the gate site.
     """
+    # view.aggregated / view.overlay are newest-first; reverse for asc
+    # so BarChart bars are chronological.
+    rows = list(reversed(view.aggregated))
+    overlay = list(reversed(view.overlay))
     _lib_share = _share_load_lib()
     columns_list: list = [
         _lib_share.ColumnSpec(key="week", label="Week Start", align="left"),
@@ -13346,7 +13393,7 @@ def _session_disambiguate_labels(
 
 
 def _build_session_snapshot(
-    sessions: list["ClaudeSessionUsage"],
+    view: "SessionsView",
     *,
     period_start: dt.datetime,
     period_end: dt.datetime,
@@ -13359,11 +13406,17 @@ def _build_session_snapshot(
 ) -> "ShareSnapshot":
     """Build a ShareSnapshot for `cctally session`.
 
-    `sessions` is the in-memory `ClaudeSessionUsage` list produced by
-    `_aggregate_claude_sessions` inside `cmd_session`. Each session has:
-    `session_id` (UUID), `project_path` (filesystem path), `cost_usd`,
-    `last_activity` (`dt.datetime`), `models` (first-seen-order
-    `list[str]`), and the token aggregates.
+    Consumes the unified ``SessionsView`` (spec §6.5). ``view.aggregated``
+    is the ``ClaudeSessionUsage`` tuple — the shape this builder needs
+    for ``source_paths`` / ``model_breakdowns`` / ``last_activity``
+    (fields ``view.rows`` / ``TuiSessionRow`` doesn't carry). The
+    in-memory shape is unchanged at the read boundary — only the
+    parameter container differs.
+
+    Each ``ClaudeSessionUsage`` has: ``session_id`` (UUID),
+    ``project_path`` (filesystem path), ``cost_usd``,
+    ``last_activity`` (``dt.datetime``), ``models`` (first-seen-order
+    ``list[str]``), and the token aggregates.
 
     Privacy invariant (Section 8.4 / Section 5.3): the builder populates
     `ProjectCell.label`, `ChartPoint.project_label`, and
@@ -13388,12 +13441,14 @@ def _build_session_snapshot(
       not present on session data) to suffix `" (parent)"` on
       collisions before the scrubber runs.
 
-    Caller MUST pass `sessions` already sorted in the desired order;
-    the builder re-sorts internally by descending cost so the chart's
-    HBar bars rank consistently with the anonymization-mapping
-    (`_build_anon_mapping` also sorts by descending cost) — keeping
-    `project-1` aligned with the highest-cost bar in the chart even
-    when the user asked for `--order asc`.
+    Caller MUST pass ``view`` whose ``aggregated`` tuple is already
+    sorted in the desired order (``cmd_session`` keeps the
+    aggregator's descending-by-last_activity sort); the builder
+    re-sorts internally by descending cost so the chart's HBar bars
+    rank consistently with the anonymization-mapping
+    (``_build_anon_mapping`` also sorts by descending cost) — keeping
+    ``project-1`` aligned with the highest-cost bar in the chart even
+    when the user asked for ``--order asc``.
 
     `top_n`, when set (must be `>= 1`; caller validates), truncates
     BOTH the table rows and the chart points to the top-N by cost.
@@ -13420,7 +13475,8 @@ def _build_session_snapshot(
     # Sort by descending cost so the snapshot's chart-order matches the
     # `_build_anon_mapping` sort key (also descending cost).
     sorted_sessions = sorted(
-        sessions, key=lambda s: -float(getattr(s, "cost_usd", 0.0) or 0.0)
+        view.aggregated,
+        key=lambda s: -float(getattr(s, "cost_usd", 0.0) or 0.0),
     )
     # Apply --top-n truncation (caller validated >= 1). Truncation status
     # gates the title shape below.