cctally 1.7.3 → 1.8.0

package/bin/cctally

@@ -210,6 +210,43 @@ PUBLIC_REPO = "omrikais/cctally"
 #
 # Spec: docs/superpowers/specs/2026-05-13-bin-cctally-split-design.md §6.3-6.4
 
+# === _cctally_core: leaf kernel (MUST load first; sibling imports
+# `from _cctally_core import …` depend on this being in sys.modules
+# before any other sibling's module body runs). Spec
+# 2026-05-17-cctally-core-kernel-extraction.md §2.5. ===
+_cctally_core = _load_sibling("_cctally_core")
+
+# Eager re-exports for the 24 kernel symbols. Preserves
+# `cctally.<name>` attribute access AND `ns["<name>"]` dict-subscript
+# paths used heavily by tests (e.g. ns["open_db"]() in 125+ sites).
+# Don't add to PEP 562 __getattr__ registry — eager binding is the
+# whole point.
+eprint = _cctally_core.eprint
+now_utc_iso = _cctally_core.now_utc_iso
+parse_iso_datetime = _cctally_core.parse_iso_datetime
+parse_date_str = _cctally_core.parse_date_str
+format_local_iso = _cctally_core.format_local_iso
+_iso_to_epoch = _cctally_core._iso_to_epoch
+_format_short_duration = _cctally_core._format_short_duration
+_normalize_week_boundary_dt = _cctally_core._normalize_week_boundary_dt
+_now_utc = _cctally_core._now_utc
+_command_as_of = _cctally_core._command_as_of
+get_week_start_name = _cctally_core.get_week_start_name
+compute_week_bounds = _cctally_core.compute_week_bounds
+WEEKDAY_MAP = _cctally_core.WEEKDAY_MAP
+DEFAULT_WEEK_START = _cctally_core.DEFAULT_WEEK_START
+ensure_dirs = _cctally_core.ensure_dirs
+_AlertsConfigError = _cctally_core._AlertsConfigError
+_ALERTS_CONFIG_VALID_KEYS = _cctally_core._ALERTS_CONFIG_VALID_KEYS
+_validate_threshold_list = _cctally_core._validate_threshold_list
+_get_alerts_config = _cctally_core._get_alerts_config
+open_db = _cctally_core.open_db
+WeekRef = _cctally_core.WeekRef
+_canonicalize_optional_iso = _cctally_core._canonicalize_optional_iso
+make_week_ref = _cctally_core.make_week_ref
+_get_latest_row_for_week = _cctally_core._get_latest_row_for_week
+get_latest_usage_for_week = _cctally_core.get_latest_usage_for_week
+
 _lib_semver = _load_sibling("_lib_semver")
 _SEMVER_NUM = _lib_semver._SEMVER_NUM
 _SEMVER_RE = _lib_semver._SEMVER_RE
@@ -308,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
@@ -2195,9 +2246,6 @@ def _migrate_legacy_data_dir() -> None:
     )
 
 
-DEFAULT_WEEK_START = "monday"
-
-
 def _get_claude_data_dirs() -> list[pathlib.Path]:
     """Return Claude Code data directories containing a projects/ subdir."""
     env_val = os.environ.get("CLAUDE_CONFIG_DIR", "").strip()
@@ -2352,79 +2400,6 @@ def _resolve_primary_model_for_block(
 
 
 
-WEEKDAY_MAP = {
-    "monday": 0,
-    "tuesday": 1,
-    "wednesday": 2,
-    "thursday": 3,
-    "friday": 4,
-    "saturday": 5,
-    "sunday": 6,
-}
-
-_DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
-
-
-def eprint(*args: Any) -> None:
-    print(*args, file=sys.stderr)
-
-
-def now_utc_iso(now_utc: dt.datetime | None = None) -> str:
-    """Return a UTC-ISO 'Z'-suffixed timestamp with seconds precision.
-
-    When ``now_utc`` is omitted (the default), reads wall-clock — existing
-    behavior, preserved byte-for-byte for all existing callers. When a
-    tz-aware UTC datetime is supplied (typically via ``_command_as_of()``),
-    it is used verbatim so callers that honor ``CCTALLY_AS_OF`` get a
-    stable, caller-pinned timestamp.
-    """
-    value = now_utc if now_utc is not None else dt.datetime.now(dt.timezone.utc)
-    return (
-        value.astimezone(dt.timezone.utc)
-        .replace(microsecond=0)
-        .isoformat()
-        .replace("+00:00", "Z")
-    )
-
-
-def _iso_to_epoch(s: str) -> int:
-    """Parse an ISO-8601 timestamp and return Unix epoch seconds.
-
-    Naive ISO strings (no timezone) are treated as UTC, matching the
-    statusline-command.sh ``_iso_to_epoch`` helper. ``Z`` suffix is
-    handled by mapping to ``+00:00`` since ``datetime.fromisoformat``
-    accepts ``Z`` natively from Python 3.11.
-    """
-    s = s.strip()
-    if s.endswith("Z"):
-        s = s[:-1] + "+00:00"
-    parsed = dt.datetime.fromisoformat(s)
-    if parsed.tzinfo is None:
-        parsed = parsed.replace(tzinfo=dt.timezone.utc)
-    return int(parsed.timestamp())
-
-
-def _format_short_duration(seconds: int) -> str:
-    """Format a duration as a short top-two-units string.
-
-    Examples: ``6d 4h``, ``2h 15m``, ``2h``, ``45m``, ``30s``, ``0s``.
-    Mirrors the shape used by ``~/.claude/statusline-command.sh``'s
-    format_duration helper. Negative inputs clamp to ``0s``.
-    """
-    s = max(0, int(seconds))
-    if s >= 86400:
-        days = s // 86400
-        hours = (s % 86400) // 3600
-        return f"{days}d {hours}h" if hours else f"{days}d"
-    if s >= 3600:
-        hours = s // 3600
-        minutes = (s % 3600) // 60
-        return f"{hours}h {minutes}m" if minutes else f"{hours}h"
-    if s >= 60:
-        return f"{s // 60}m"
-    return f"{s}s"
-
-
 def _read_keychain_oauth_blob() -> str | None:
     """Read the Claude Code keychain entry on macOS via `security`.
 
@@ -2557,96 +2532,6 @@ def _select_last_known_snapshot() -> dict | None:
     }
 
 
-def ensure_dirs() -> None:
-    APP_DIR.mkdir(parents=True, exist_ok=True)
-    LOG_DIR.mkdir(parents=True, exist_ok=True)
-
-
-
-
-class _AlertsConfigError(ValueError):
-    """Raised by _get_alerts_config on invalid alerts block."""
-
-
-_ALERTS_CONFIG_VALID_KEYS = {"enabled", "weekly_thresholds", "five_hour_thresholds"}
-
-
-def _validate_threshold_list(name: str, value: object) -> "list[int]":
-    """Validate one of the alerts threshold lists.
-
-    Rules: non-empty list of plain ints (NOT bools — `bool` is an `int`
-    subclass), each in [1, 100], strictly increasing (no duplicates).
-    Error messages mention `alerts.<name>` so users can locate the
-    offending key in their config.json.
-    """
-    if not isinstance(value, list):
-        raise _AlertsConfigError(f"alerts.{name} must be a list of integers")
-    if len(value) == 0:
-        raise _AlertsConfigError(
-            f"alerts.{name} must not be empty (disable alerts via alerts.enabled=false)"
-        )
-    out: "list[int]" = []
-    prev = -1
-    seen: "set[int]" = set()
-    for item in value:
-        if not isinstance(item, int) or isinstance(item, bool):
-            raise _AlertsConfigError(
-                f"alerts.{name} items must be integers, got {type(item).__name__}: {item!r}"
-            )
-        if item < 1 or item > 100:
-            raise _AlertsConfigError(
-                f"alerts.{name} items must be in [1, 100], got {item}"
-            )
-        if item in seen:
-            raise _AlertsConfigError(
-                f"alerts.{name} contains duplicate value {item}"
-            )
-        if item <= prev:
-            raise _AlertsConfigError(
-                f"alerts.{name} must be strictly increasing, got {prev} then {item}"
-            )
-        seen.add(item)
-        prev = item
-        out.append(item)
-    return out
-
-
-def _get_alerts_config(cfg: "dict | None") -> dict:
-    """Return the validated alerts block. Raises _AlertsConfigError on failure.
-
-    Defaults applied at read time so future default-tuning takes effect
-    for users who never customized. Unknown sub-keys under `alerts.*`
-    emit a one-line warn-and-ignore (mirrors the `display.tz` posture
-    for forward compatibility).
-    """
-    block = (cfg or {}).get("alerts", {}) or {}
-    if not isinstance(block, dict):
-        raise _AlertsConfigError("alerts must be an object")
-    # warn-and-ignore unknown keys (forward compat; matches display.tz posture)
-    for k in block.keys():
-        if k not in _ALERTS_CONFIG_VALID_KEYS:
-            print(
-                f"warning: ignoring unknown alerts config key: {k}",
-                file=sys.stderr,
-            )
-    enabled = block.get("enabled", False)
-    if not isinstance(enabled, bool):
-        raise _AlertsConfigError(
-            f"alerts.enabled must be a JSON boolean, got {type(enabled).__name__}: {enabled!r}"
-        )
-    weekly = _validate_threshold_list(
-        "weekly_thresholds", block.get("weekly_thresholds", [90, 95])
-    )
-    five_hour = _validate_threshold_list(
-        "five_hour_thresholds", block.get("five_hour_thresholds", [90, 95])
-    )
-    return {
-        "enabled": enabled,
-        "weekly_thresholds": weekly,
-        "five_hour_thresholds": five_hour,
-    }
-
-
 def _normalize_alerts_enabled_value(raw: str) -> bool:
     """Normalize a CLI string value to a JSON bool. Raises ValueError on unknown.
 
@@ -2724,60 +2609,6 @@ ORIGINAL_ENTRYPOINT: "str | None" = None
 _UPDATE_WORKER: "UpdateWorker | None" = None
 
 
-def get_week_start_name(config: dict[str, Any], override: str | None = None) -> str:
-    if override:
-        name = override.strip().lower()
-    else:
-        name = str(config.get("collector", {}).get("week_start", DEFAULT_WEEK_START)).strip().lower()
-    if name not in WEEKDAY_MAP:
-        raise ValueError(
-            f"Invalid week start '{name}'. Allowed: {', '.join(WEEKDAY_MAP.keys())}"
-        )
-    return name
-
-
-def compute_week_bounds(anchor_dt: dt.datetime, week_start_name: str) -> tuple[dt.date, dt.date]:
-    start_idx = WEEKDAY_MAP[week_start_name]
-    # internal fallback: host-local intentional
-    local_anchor = anchor_dt.astimezone()
-    local_date = local_anchor.date()
-    diff = (local_date.weekday() - start_idx) % 7
-    start = local_date - dt.timedelta(days=diff)
-    end = start + dt.timedelta(days=6)
-    return start, end
-
-
-def parse_date_str(value: str, label: str) -> dt.date:
-    s = value.strip()
-    if not _DATE_RE.match(s):
-        raise ValueError(f"{label} must be YYYY-MM-DD")
-    return dt.date.fromisoformat(s)
-
-
-def parse_iso_datetime(value: str, label: str) -> dt.datetime:
-    s = value.strip()
-    if not s:
-        raise ValueError(f"{label} must be a non-empty ISO datetime")
-    try:
-        parsed = dt.datetime.fromisoformat(s.replace("Z", "+00:00"))
-    except ValueError as exc:
-        raise ValueError(f"{label} must be ISO datetime") from exc
-
-    if parsed.tzinfo is None:
-        # internal fallback: host-local intentional
-        local_tz = dt.datetime.now().astimezone().tzinfo
-        parsed = parsed.replace(tzinfo=local_tz)
-    # internal fallback: host-local intentional
-    return parsed.astimezone()
-
-
-def format_local_iso(d: dt.date, end_of_day: bool) -> str:
-    t = dt.time(23, 59, 59) if end_of_day else dt.time(0, 0, 0)
-    # internal fallback: host-local intentional
-    local_dt = dt.datetime.combine(d, t).astimezone()
-    return local_dt.isoformat(timespec="seconds")
-
-
 def _parse_iso_datetime_optional(value: Any) -> dt.datetime | None:
     if not isinstance(value, str) or not value.strip():
         return None
@@ -3652,489 +3483,6 @@ def _trend_row_recency_seconds(row: dict[str, Any]) -> float:
     return 0.0
 
 
-def _normalize_week_boundary_dt(value: dt.datetime) -> dt.datetime:
-    """
-    Normalize known Anthropic boundary jitter.
-
-    Anthropic resets are always on hour boundaries. Relative reset text
-    ("in XX hr YY min") produces minute-level drift on every capture, and
-    the UI occasionally alternates between HH:00 and HH-1:59 for the same
-    logical reset.
-
-    Canonicalization: round to the nearest hour.
-    - minutes 0..29 -> HH:00
-    - minutes 30..59 -> (HH+1):00
-    """
-    normalized = value.replace(second=0, microsecond=0)
-    if normalized.minute >= 30:
-        normalized = (normalized + dt.timedelta(hours=1)).replace(
-            minute=0,
-            second=0,
-            microsecond=0,
-        )
-    elif normalized.minute > 0:
-        normalized = normalized.replace(
-            minute=0,
-            second=0,
-            microsecond=0,
-        )
-    return normalized
-
-
-def open_db() -> sqlite3.Connection:
-    ensure_dirs()
-    conn = sqlite3.connect(DB_PATH)
-    conn.row_factory = sqlite3.Row
-    conn.execute("PRAGMA journal_mode=WAL")
-    conn.execute("PRAGMA synchronous=NORMAL")
-    conn.execute(
-        """
-        CREATE TABLE IF NOT EXISTS weekly_usage_snapshots (
-            id INTEGER PRIMARY KEY AUTOINCREMENT,
-            captured_at_utc TEXT NOT NULL,
-            week_start_date TEXT NOT NULL,
-            week_end_date TEXT NOT NULL,
-            week_start_at TEXT,
-            week_end_at TEXT,
-            weekly_percent REAL NOT NULL,
-            page_url TEXT,
-            source TEXT NOT NULL DEFAULT 'userscript',
-            payload_json TEXT NOT NULL
-        )
-        """
-    )
-    conn.execute(
-        """
-        CREATE INDEX IF NOT EXISTS idx_usage_week_time
-        ON weekly_usage_snapshots(week_start_date, captured_at_utc DESC, id DESC)
-        """
-    )
-    conn.execute(
-        """
-        CREATE TABLE IF NOT EXISTS weekly_cost_snapshots (
-            id INTEGER PRIMARY KEY AUTOINCREMENT,
-            captured_at_utc TEXT NOT NULL,
-            week_start_date TEXT NOT NULL,
-            week_end_date TEXT NOT NULL,
-            week_start_at TEXT,
-            week_end_at TEXT,
-            range_start_iso TEXT,
-            range_end_iso TEXT,
-            cost_usd REAL NOT NULL,
-            source TEXT NOT NULL DEFAULT 'cctally-range-cost',
-            mode TEXT NOT NULL DEFAULT 'auto',
-            project TEXT
-        )
-        """
-    )
-    conn.execute(
-        """
-        CREATE INDEX IF NOT EXISTS idx_cost_week_time
-        ON weekly_cost_snapshots(week_start_date, captured_at_utc DESC, id DESC)
-        """
-    )
-
-    add_column_if_missing(conn, "weekly_usage_snapshots", "week_start_at", "TEXT")
-    add_column_if_missing(conn, "weekly_usage_snapshots", "week_end_at", "TEXT")
-    add_column_if_missing(conn, "weekly_usage_snapshots", "five_hour_percent", "REAL")
-    add_column_if_missing(conn, "weekly_usage_snapshots", "five_hour_resets_at", "TEXT")
-    # five_hour_window_key — canonical (10-min-floored epoch) key for
-    # jitter-tolerant equality. Anthropic's status-line API jitters
-    # rate_limits.5h.resets_at by ~seconds within the same physical 5h
-    # window; joining on the raw ISO string treats each jittered fetch as
-    # a new window, escaping the monotonic clamp at cmd_record_usage.
-    # Backfill is RESUMABLE: Python's sqlite3 auto-commits DDL,
-    # so a process killed mid-loop would leave the column added with NULL
-    # keys for unprocessed rows. The gating below detects that partial
-    # state on the next open_db() call (`five_hour_resets_at IS NOT NULL
-    # AND five_hour_window_key IS NULL`) and completes the backfill, so
-    # the original Bug B can't silently re-emerge for half-migrated rows.
-    needs_5h_key_backfill = add_column_if_missing(
-        conn, "weekly_usage_snapshots", "five_hour_window_key", "INTEGER"
-    )
-    if not needs_5h_key_backfill and conn.execute(
-        "SELECT 1 FROM weekly_usage_snapshots "
-        "WHERE five_hour_resets_at IS NOT NULL "
-        "  AND five_hour_window_key IS NULL "
-        "LIMIT 1"
-    ).fetchone() is not None:
-        needs_5h_key_backfill = True
-
-    if needs_5h_key_backfill:
-        backfill_rows = conn.execute(
-            "SELECT id, five_hour_resets_at FROM weekly_usage_snapshots "
-            "WHERE five_hour_resets_at IS NOT NULL "
-            "  AND five_hour_window_key IS NULL"
-        ).fetchall()
-        for row in backfill_rows:
-            try:
-                iso = row[1]
-                d = parse_iso_datetime(iso, "five_hour_resets_at backfill")
-                epoch = int(d.timestamp())
-                key = _canonical_5h_window_key(epoch)
-                conn.execute(
-                    "UPDATE weekly_usage_snapshots "
-                    "SET five_hour_window_key = ? WHERE id = ?",
-                    (key, row[0]),
-                )
-            except (ValueError, TypeError) as exc:
-                eprint(f"[migration] skipped row {row[0]}: {exc}")
-        conn.execute(
-            "CREATE INDEX IF NOT EXISTS idx_weekly_usage_snapshots_5h_window_key "
-            "ON weekly_usage_snapshots(five_hour_window_key)"
-        )
-        conn.commit()
-
-    add_column_if_missing(conn, "weekly_cost_snapshots", "week_start_at", "TEXT")
-    add_column_if_missing(conn, "weekly_cost_snapshots", "week_end_at", "TEXT")
-    add_column_if_missing(conn, "weekly_cost_snapshots", "range_start_iso", "TEXT")
-    add_column_if_missing(conn, "weekly_cost_snapshots", "range_end_iso", "TEXT")
-
-    conn.execute(
-        """
-        CREATE INDEX IF NOT EXISTS idx_usage_week_start_at_time
-        ON weekly_usage_snapshots(week_start_at, captured_at_utc DESC, id DESC)
-        """
-    )
-    conn.execute(
-        """
-        CREATE INDEX IF NOT EXISTS idx_cost_week_start_at_time
-        ON weekly_cost_snapshots(week_start_at, captured_at_utc DESC, id DESC)
-        """
-    )
-
-    conn.execute(
-        """
-        CREATE TABLE IF NOT EXISTS percent_milestones (
-            id INTEGER PRIMARY KEY AUTOINCREMENT,
-            captured_at_utc TEXT NOT NULL,
-            week_start_date TEXT NOT NULL,
-            week_end_date TEXT NOT NULL,
-            week_start_at TEXT,
-            week_end_at TEXT,
-            percent_threshold INTEGER NOT NULL,
-            cumulative_cost_usd REAL NOT NULL,
-            marginal_cost_usd REAL,
-            usage_snapshot_id INTEGER NOT NULL,
-            cost_snapshot_id INTEGER NOT NULL,
-            reset_event_id INTEGER NOT NULL DEFAULT 0,
-            UNIQUE(week_start_date, percent_threshold, reset_event_id)
-        )
-        """
-    )
-
-    add_column_if_missing(conn, "percent_milestones", "five_hour_percent_at_crossing", "REAL")
-    # reset_event_id: segment column added by migration 005. Fresh-install
-    # DBs get it via the live CREATE TABLE above + the dispatcher
-    # fast-stamps the migration. Existing pre-005 DBs trip the migration's
-    # rename-recreate-copy idiom (handler in _cctally_db.py); the handler's
-    # fast-path probe stamps the marker when the column is already present
-    # (covers the corner case where a partially-upgraded DB has the column
-    # but not the new UNIQUE — re-run is safe).
-
-    # alerted_at: populated by the alert-dispatch path when a milestone-INSERT
-    # row's threshold matches the user's configured alerts.weekly_thresholds /
-    # alerts.five_hour_thresholds (and alerts.enabled is true). NULL means
-    # "alerts were disabled at the moment of crossing OR the threshold wasn't
-    # in the configured list" — never "alert delivery failed" (dispatch is
-    # best-effort and write-once forward-only). The matching ALTER for
-    # `five_hour_milestones` lives right after that table's CREATE block
-    # below, since the table doesn't exist yet at this point in `open_db()`.
-    add_column_if_missing(conn, "percent_milestones", "alerted_at", "TEXT")
-
-    # Mid-week reset events: when Anthropic advances `rate_limits.seven_day.
-    # resets_at` before the previously-declared reset actually fires (i.e.,
-    # gives the user a fresh weekly window before the old one naturally
-    # expired), we record one row here so display + cost layers can treat
-    # the effective reset moment as the old week's end AND the new week's
-    # start — preventing the API's -7d-derived new week from overlapping
-    # the old week. Inserted by cmd_record_usage on detection; read by
-    # _apply_reset_events_to_weekrefs and the cost live-recompute path.
-    conn.execute(
-        """
-        CREATE TABLE IF NOT EXISTS week_reset_events (
-            id INTEGER PRIMARY KEY AUTOINCREMENT,
-            detected_at_utc        TEXT NOT NULL,
-            old_week_end_at        TEXT NOT NULL,
-            new_week_end_at        TEXT NOT NULL,
-            effective_reset_at_utc TEXT NOT NULL,
-            UNIQUE(old_week_end_at, new_week_end_at)
-        )
-        """
-    )
-    _backfill_week_reset_events(conn)
-
-    # ── five_hour_reset_events (Anthropic-issued in-place 5h credits) ──
-    # Parallel concept to ``week_reset_events`` for the 5h dimension; lives
-    # adjacent in ``_apply_schema`` because the two carry the same kind of
-    # signal at different cadences. Diverges from weekly in that the payload
-    # is the *percent values* (prior + post) rather than boundary keys,
-    # because the 5h variant has a stable ``five_hour_window_key`` and only
-    # the percent moves. See spec
-    # docs/superpowers/specs/2026-05-16-5h-in-place-credit-detection.md §3.1
-    # for rationale.
-    #
-    # UNIQUE(five_hour_window_key, effective_reset_at_utc) — supports stacked
-    # credits across DISTINCT 10-min slots inside one block (see spec §2.3
-    # "Bounded stacked-credit resolution" for the cap statement: ~30 distinct
-    # slots per 5h block when floor matches ``_canonical_5h_window_key``'s
-    # 600-second floor; same-slot collisions silently absorbed by
-    # INSERT OR IGNORE — an intentional cap, not a bug).
-    #
-    # No FK per CLAUDE.md gotcha: FKs in this codebase are documentation-only
-    # (``PRAGMA foreign_keys`` not enabled). ``five_hour_window_key`` provides
-    # the join key without a formal FK.
-    #
-    # No ``_backfill_five_hour_reset_events`` call follows (forward-only ship
-    # per spec Q5; historical backfill deferred to a future issue).
-    conn.execute(
-        """
-        CREATE TABLE IF NOT EXISTS five_hour_reset_events (
-            id                     INTEGER PRIMARY KEY AUTOINCREMENT,
-            detected_at_utc        TEXT NOT NULL,
-            five_hour_window_key   INTEGER NOT NULL,
-            prior_percent          REAL NOT NULL,
-            post_percent           REAL NOT NULL,
-            effective_reset_at_utc TEXT NOT NULL,
-            UNIQUE(five_hour_window_key, effective_reset_at_utc)
-        )
-        """
-    )
-
-    # ── five_hour_blocks (rollup, one row per API-anchored 5h block) ──
-    conn.execute(
-        """
-        CREATE TABLE IF NOT EXISTS five_hour_blocks (
-            id                            INTEGER PRIMARY KEY AUTOINCREMENT,
-            five_hour_window_key          INTEGER NOT NULL UNIQUE,
-            five_hour_resets_at           TEXT    NOT NULL,
-            block_start_at                TEXT    NOT NULL,
-            first_observed_at_utc         TEXT    NOT NULL,
-            last_observed_at_utc          TEXT    NOT NULL,
-            final_five_hour_percent       REAL    NOT NULL,
-            seven_day_pct_at_block_start  REAL,
-            seven_day_pct_at_block_end    REAL,
-            crossed_seven_day_reset       INTEGER NOT NULL DEFAULT 0,
-            total_input_tokens            INTEGER NOT NULL DEFAULT 0,
-            total_output_tokens           INTEGER NOT NULL DEFAULT 0,
-            total_cache_create_tokens     INTEGER NOT NULL DEFAULT 0,
-            total_cache_read_tokens       INTEGER NOT NULL DEFAULT 0,
-            total_cost_usd                REAL    NOT NULL DEFAULT 0,
-            is_closed                     INTEGER NOT NULL DEFAULT 0,
-            created_at_utc                TEXT    NOT NULL,
-            last_updated_at_utc           TEXT    NOT NULL
-        )
-        """
-    )
-    conn.execute(
-        """
-        CREATE INDEX IF NOT EXISTS idx_five_hour_blocks_block_start
-        ON five_hour_blocks(block_start_at DESC)
-        """
-    )
-
-    # ── five_hour_milestones (per-percent crossings inside a 5h block) ──
-    conn.execute(
-        """
-        CREATE TABLE IF NOT EXISTS five_hour_milestones (
-            id                          INTEGER PRIMARY KEY AUTOINCREMENT,
-            block_id                    INTEGER NOT NULL,
-            five_hour_window_key        INTEGER NOT NULL,
-            percent_threshold           INTEGER NOT NULL,
-            captured_at_utc             TEXT    NOT NULL,
-            usage_snapshot_id           INTEGER NOT NULL,
-            block_input_tokens          INTEGER NOT NULL DEFAULT 0,
-            block_output_tokens         INTEGER NOT NULL DEFAULT 0,
-            block_cache_create_tokens   INTEGER NOT NULL DEFAULT 0,
-            block_cache_read_tokens     INTEGER NOT NULL DEFAULT 0,
-            block_cost_usd              REAL    NOT NULL DEFAULT 0,
-            marginal_cost_usd           REAL,
-            seven_day_pct_at_crossing   REAL,
-            reset_event_id              INTEGER NOT NULL DEFAULT 0,
-            UNIQUE(five_hour_window_key, percent_threshold, reset_event_id),
-            FOREIGN KEY (block_id) REFERENCES five_hour_blocks(id)
-        )
-        """
-    )
-    conn.execute(
-        """
-        CREATE INDEX IF NOT EXISTS idx_five_hour_milestones_block
-        ON five_hour_milestones(block_id)
-        """
-    )
-
-    # alerted_at: see the matching ALTER on `percent_milestones` above for
-    # rationale. Same write-once forward-only semantics: the alert-dispatch
-    # path stamps this column on milestone-INSERT rows whose threshold
-    # matches the user's configured `alerts.five_hour_thresholds`. NULL =
-    # "alerts disabled at moment of crossing OR threshold not configured"
-    # — never "delivery failed".
-    add_column_if_missing(conn, "five_hour_milestones", "alerted_at", "TEXT")
-
-    # reset_event_id: segment column added by migration 006. Fresh-install
-    # DBs get it via the live CREATE TABLE above + the dispatcher fast-stamps
-    # the migration marker (the live DDL must carry the column AND the 3-col
-    # UNIQUE for fast-stamp to be safe — see spec §3.2). Existing pre-006
-    # DBs trip the migration's rename-recreate-copy idiom (handler in
-    # bin/_cctally_db.py); the handler's fast-path probe stamps the marker
-    # when the column is already present (covers the corner case where a
-    # partially-upgraded DB has the column but not the new UNIQUE — re-run
-    # is safe). Mirrors weekly migration 005 / `percent_milestones`.
-
-    # ── five_hour_block_models (per-(block, model) rollup-child) ──
-    # MUST be created BEFORE the parent-backfill gate below, because
-    # _backfill_five_hour_blocks writes into this table on the fresh-install
-    # path. UNIQUE keyed on (five_hour_window_key, model) — durable across
-    # parent rebuilds. Live writes use DELETE WHERE five_hour_window_key = ?.
-    conn.execute(
-        """
-        CREATE TABLE IF NOT EXISTS five_hour_block_models (
-            id                          INTEGER PRIMARY KEY AUTOINCREMENT,
-            block_id                    INTEGER NOT NULL,
-            five_hour_window_key        INTEGER NOT NULL,
-            model                       TEXT    NOT NULL,
-            input_tokens                INTEGER NOT NULL DEFAULT 0,
-            output_tokens               INTEGER NOT NULL DEFAULT 0,
-            cache_create_tokens         INTEGER NOT NULL DEFAULT 0,
-            cache_read_tokens           INTEGER NOT NULL DEFAULT 0,
-            cost_usd                    REAL    NOT NULL DEFAULT 0,
-            entry_count                 INTEGER NOT NULL DEFAULT 0,
-            UNIQUE(five_hour_window_key, model),
-            FOREIGN KEY (block_id) REFERENCES five_hour_blocks(id)
-        )
-        """
-    )
-    conn.execute(
-        """
-        CREATE INDEX IF NOT EXISTS idx_five_hour_block_models_block
-        ON five_hour_block_models(block_id)
-        """
-    )
-    conn.execute(
-        """
-        CREATE INDEX IF NOT EXISTS idx_five_hour_block_models_window
-        ON five_hour_block_models(five_hour_window_key)
-        """
-    )
-
-    # ── five_hour_block_projects (per-(block, project_path) rollup-child) ──
-    # NULL session_files.project_path → '(unknown)' sentinel at write time,
-    # keeping reconcile invariant SUM(child.cost) == parent.total intact.
-    conn.execute(
-        """
-        CREATE TABLE IF NOT EXISTS five_hour_block_projects (
-            id                          INTEGER PRIMARY KEY AUTOINCREMENT,
-            block_id                    INTEGER NOT NULL,
-            five_hour_window_key        INTEGER NOT NULL,
-            project_path                TEXT    NOT NULL,
-            input_tokens                INTEGER NOT NULL DEFAULT 0,
-            output_tokens               INTEGER NOT NULL DEFAULT 0,
-            cache_create_tokens         INTEGER NOT NULL DEFAULT 0,
-            cache_read_tokens           INTEGER NOT NULL DEFAULT 0,
-            cost_usd                    REAL    NOT NULL DEFAULT 0,
-            entry_count                 INTEGER NOT NULL DEFAULT 0,
-            UNIQUE(five_hour_window_key, project_path),
-            FOREIGN KEY (block_id) REFERENCES five_hour_blocks(id)
-        )
-        """
-    )
-    conn.execute(
-        """
-        CREATE INDEX IF NOT EXISTS idx_five_hour_block_projects_block
-        ON five_hour_block_projects(block_id)
-        """
-    )
-    conn.execute(
-        """
-        CREATE INDEX IF NOT EXISTS idx_five_hour_block_projects_window
-        ON five_hour_block_projects(five_hour_window_key)
-        """
-    )
-
-    # Migration framework dispatcher. Replaces the prior inline gate stack
-    # (has_blocks + _migration_done) with the framework's _run_pending_-
-    # migrations entry point. See spec §2.3, §5.2 + the migration handlers
-    # decorated with @stats_migration further down in this file.
-    #
-    # MUST run BEFORE any DDL or write that touches `schema_migrations`
-    # (Codex P1 #1 fix on c3625ee + e7fdcc8): the dispatcher's fresh-install
-    # detection snapshots `schema_migrations`'s existence in sqlite_master
-    # BEFORE its own CREATE TABLE IF NOT EXISTS. Pre-creating the table
-    # earlier in open_db() (or letting `_backfill_five_hour_blocks` insert
-    # markers first) flips that snapshot to True on a brand-new DB and
-    # dead-codes the stamp-only fast path. The dispatcher is now the sole
-    # creator of `schema_migrations` + `schema_migrations_skipped`.
-    _run_pending_migrations(
-        conn, registry=_STATS_MIGRATIONS, db_label="stats.db",
-    )
-
-    # One-time historical backfill of five_hour_blocks (rollup only;
-    # milestones are forward-only per spec §4.3 / [Write-once milestones]).
-    # Idempotent via UNIQUE(five_hour_window_key) + INSERT OR IGNORE.
-    # Runs AFTER the dispatcher so `schema_migrations` exists for the
-    # marker INSERTs inside the backfill body, and so any fresh-install
-    # stamp-only path the dispatcher took above is already committed.
-    existing = conn.execute(
-        "SELECT 1 FROM five_hour_blocks LIMIT 1"
-    ).fetchone()
-    has_snapshots = conn.execute(
-        "SELECT 1 FROM weekly_usage_snapshots "
-        "WHERE five_hour_window_key IS NOT NULL "
-        "  AND five_hour_percent     IS NOT NULL "
-        "LIMIT 1"
-    ).fetchone()
-    if not existing and has_snapshots:
-        inserted = _backfill_five_hour_blocks(conn)
-        # Re-run the 5h dedup migration AFTER backfill creates parents.
-        # The dispatcher above ran while five_hour_blocks was empty, so
-        # the dedup handler no-op'd and stamped its marker. Snapshot
-        # keys can carry jitter beyond the 600s canonical floor (the
-        # 003_* migration handles up to 1800s grouping), so the
-        # backfill's `DISTINCT five_hour_window_key` over those keys
-        # can produce duplicate parent rows for one physical 5h
-        # window. Without this re-invocation those duplicates persist
-        # forever — the marker says it ran. Handler owns its own
-        # BEGIN/COMMIT and is idempotent (no groups → no-op).
-        #
-        # Honor `db skip` here as well: if the operator marked 003 as
-        # skipped (e.g., poison pill on their machine), we must NOT
-        # back-door run the handler. Duplicates introduced by the
-        # backfill will persist until they `db unskip` — which is the
-        # explicit choice the skip records. Failure path mirrors the
-        # dispatcher's contract: route through _log_migration_error so
-        # the next interactive command renders the banner, and clear
-        # the log entry on success so the banner auto-dismisses.
-        if inserted > 0:
-            target_name = "003_merge_5h_block_duplicates_v1"
-            try:
-                skipped = {
-                    row[0] for row in conn.execute(
-                        "SELECT name FROM schema_migrations_skipped"
-                    ).fetchall()
-                }
-            except sqlite3.OperationalError:
-                skipped = set()
-            if target_name not in skipped:
-                for _m in _STATS_MIGRATIONS:
-                    if _m.name == target_name:
-                        qualified = f"stats.db:{target_name}"
-                        try:
-                            _m.handler(conn)
-                            _clear_migration_error_log_entries(qualified)
-                        except Exception as exc:
-                            _log_migration_error(
-                                name=qualified,
-                                exc=exc,
-                                tb=traceback.format_exc(),
-                            )
-                            eprint(f"[migration {qualified}] failed: {exc}")
-                        break
-
-    conn.commit()
-    return conn
-
-
-
 @dataclass
 class CacheModelBreakdown:
     model_name: str
@@ -4637,85 +3985,6 @@ def compute_week_cost(
     )
 
 
-def _canonicalize_optional_iso(value: str | None, label: str) -> str | None:
-    if value is None:
-        return None
-    s = value.strip()
-    if s == "":
-        return None
-    normalized = _normalize_week_boundary_dt(parse_iso_datetime(s, label)).astimezone(dt.timezone.utc)
-    return normalized.isoformat(timespec="seconds")
-
-
-@dataclass(frozen=True)
-class WeekRef:
-    week_start: dt.date
-    week_end: dt.date | None
-    week_start_at: str | None
-    week_end_at: str | None
-    key: str
-
-
-def make_week_ref(
-    week_start_date: str,
-    week_end_date: str | None,
-    week_start_at: str | None = None,
-    week_end_at: str | None = None,
-) -> WeekRef:
-    week_start = dt.date.fromisoformat(week_start_date)
-    week_end = dt.date.fromisoformat(week_end_date) if week_end_date else None
-    start_at = _canonicalize_optional_iso(week_start_at, "weekStartAt")
-    end_at = _canonicalize_optional_iso(week_end_at, "weekEndAt")
-
-    return WeekRef(
-        week_start=week_start,
-        week_end=week_end,
-        week_start_at=start_at,
-        week_end_at=end_at,
-        key=week_start.isoformat(),
-    )
-
-
-def _get_latest_row_for_week(
-    conn: sqlite3.Connection,
-    table_name: str,
-    week_ref: WeekRef,
-    as_of_utc: str | None = None,
-) -> sqlite3.Row | None:
-    if as_of_utc is None:
-        return conn.execute(
-            f"""
-            SELECT *
-            FROM {table_name}
-            WHERE week_start_date = ?
-            ORDER BY captured_at_utc DESC, id DESC
-            LIMIT 1
-            """,
-            (week_ref.week_start.isoformat(),),
-        ).fetchone()
-    return conn.execute(
-        f"""
-        SELECT *
-        FROM {table_name}
-        WHERE week_start_date = ?
-          AND captured_at_utc <= ?
-        ORDER BY captured_at_utc DESC, id DESC
-        LIMIT 1
-        """,
-        (week_ref.week_start.isoformat(), as_of_utc),
-    ).fetchone()
-
-
-def get_latest_usage_for_week(
-    conn: sqlite3.Connection,
-    week_ref: WeekRef,
-    as_of_utc: str | None = None,
-) -> sqlite3.Row | None:
-    return _get_latest_row_for_week(
-        conn, "weekly_usage_snapshots", week_ref, as_of_utc=as_of_utc,
-    )
-
-
 def get_latest_cost_for_week(conn: sqlite3.Connection, week_ref: WeekRef) -> sqlite3.Row | None:
     return _get_latest_row_for_week(conn, "weekly_cost_snapshots", week_ref)
 
@@ -5532,6 +4801,18 @@ def _load_recorded_five_hour_windows(
                     else:
                         d = d.astimezone(dt.timezone.utc)
                     credit_moments.append(d)
+                # Issue #44: the inner-loop break below latches onto the
+                # first credit in [next_bs, rs]. With two credits inside
+                # the same pre-credit canonical 5h window, the wrong one
+                # (the later one) wins when SQLite returns rows in
+                # insertion order rather than time order — collapsing
+                # two distinct truncated anchors onto the same floored
+                # bucket and silently dropping one via override-map
+                # overwrite. Sort once so the break consistently picks
+                # the EARLIEST credit, which is the one that actually
+                # ended the earlier block (its floor equals the next
+                # block's block_start_at by construction).
+                credit_moments.sort()
             except sqlite3.DatabaseError:
                 credit_moments = []
     except (sqlite3.DatabaseError, OSError):
@@ -5955,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
@@ -5974,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,
@@ -6024,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
@@ -6039,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,
@@ -6104,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
@@ -6128,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
@@ -6161,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,
@@ -6406,46 +5695,6 @@ def cmd_codex_session(args: argparse.Namespace) -> int:
     return 0
 
 
-def _command_as_of() -> dt.datetime:
-    """Testing hook: CCTALLY_AS_OF env var overrides wall-clock `now` for
-    time-dependent commands. Shared by cmd_project, cmd_weekly,
-    cmd_cache_report, cmd_codex_weekly, cmd_diff (and any future
-    time-dependent command). Format: ISO-8601 with Z or explicit tz offset.
-    """
-    override = os.environ.get("CCTALLY_AS_OF")
-    if override:
-        override = override.strip()
-        if override.endswith("Z"):
-            override = override[:-1] + "+00:00"
-        return dt.datetime.fromisoformat(override).astimezone(dt.timezone.utc)
-    return dt.datetime.now(dt.timezone.utc)
-
-
-def _now_utc() -> dt.datetime:
-    """UTC now, with CCTALLY_AS_OF env override for fixture-stability.
-
-    Single time source for the `update` subcommand and its supporting
-    state machine (TTL gates, ``remind_after.until_utc`` comparisons,
-    log timestamps, install-method detection cache). Mirrors the
-    documented CCTALLY_AS_OF precedent (see CLAUDE.md — `project` has
-    a hidden `CCTALLY_AS_OF` env hook, and `_command_as_of` /
-    `_share_now_utc` reuse it for `weekly`/`forecast`/share-render).
-    Accepts ISO-8601 with `Z` or explicit offset; result is always
-    tz-aware UTC.
-
-    Raises ValueError on malformed CCTALLY_AS_OF — deliberate fail-loud
-    for the dev hook so fixture authors notice typos immediately rather
-    than silently falling back to wall-clock time.
-    """
-    override = os.environ.get("CCTALLY_AS_OF")
-    if override:
-        override = override.strip()
-        if override.endswith("Z"):
-            override = override[:-1] + "+00:00"
-        return dt.datetime.fromisoformat(override).astimezone(dt.timezone.utc)
-    return dt.datetime.now(dt.timezone.utc)
-
-
 def _load_week_snapshots(
     since: dt.datetime, until: dt.datetime
 ) -> dict[dt.datetime, float]:
@@ -7279,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
@@ -7313,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,
@@ -8647,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,
@@ -8663,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
 
@@ -8824,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,
@@ -13056,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,
@@ -13067,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 = (
@@ -13091,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")
@@ -13109,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": (
@@ -13140,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}"),
     )
@@ -13172,7 +12442,7 @@ def _build_report_snapshot(
 
 
 def _build_daily_snapshot(
-    rows: list["BucketUsage"],
+    view: "DailyView",
     *,
     period_start: dt.datetime,
     period_end: dt.datetime,
@@ -13183,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`):
@@ -13199,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 = (
@@ -13217,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 = []
@@ -13287,7 +12558,7 @@ def _build_daily_snapshot(
 
 
 def _build_monthly_snapshot(
-    rows: list["BucketUsage"],
+    view: "MonthlyView",
     *,
     period_start: dt.datetime,
     period_end: dt.datetime,
@@ -13298,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`):
@@ -13313,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"),
@@ -13398,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,
@@ -13411,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` /
@@ -13444,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"),
@@ -14119,7 +13393,7 @@ def _session_disambiguate_labels(
 
 
 def _build_session_snapshot(
-    sessions: list["ClaudeSessionUsage"],
+    view: "SessionsView",
     *,
     period_start: dt.datetime,
     period_end: dt.datetime,
@@ -14132,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
@@ -14161,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.
@@ -14193,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.