cctally 1.97.0 → 1.99.0

package/bin/_cctally_dashboard.py

@@ -262,6 +262,7 @@ from __future__ import annotations
 
 import argparse
 import bisect
+import copy
 import contextlib
 import dataclasses
 import datetime as dt
@@ -383,7 +384,14 @@ from _lib_display_tz import (
     normalize_display_tz_value,
     _compute_display_block,
 )
-from _lib_aggregators import _aggregate_daily, _aggregate_monthly, _aggregate_weekly
+from _lib_aggregators import (
+    _aggregate_daily,
+    _aggregate_monthly,
+    _aggregate_weekly,
+    _new_bucket_acc,
+    _fold_entry,
+    _finalize_bucket,
+)
 from _lib_fmt import stable_sum
 from _lib_pricing import (_calculate_entry_cost, _chip_for_model,
                           _short_model_name, claude_usage_dict)
@@ -1019,17 +1027,128 @@ def _claude_project_key_for_path(snapshot, project_path: object) -> str | None:
     return None
 
 
+def _claude_aggregate_project_rows(snapshot) -> "tuple":
+    """The published bounded project rows, or an empty tuple.
+
+    They live on the frozen source bundle rather than on the legacy envelope,
+    and a provider whose bounded fold failed publishes none.
+    """
+    bundle = getattr(snapshot, "source_bundle", None)
+    try:
+        data = bundle.sources["claude"].data
+    except (AttributeError, KeyError, TypeError):
+        return ()
+    if not isinstance(data, Mapping):
+        return ()
+    projects = data.get("projects")
+    aggregate = projects.get("aggregate") if isinstance(projects, Mapping) else None
+    rows = aggregate.get("rows") if isinstance(aggregate, Mapping) else None
+    return tuple(rows) if isinstance(rows, (list, tuple)) else ()
+
+
+# The window sizes `GET /api/source/<source>/project/<key>?weeks=N` accepts.
+PROJECT_WINDOW_WEEKS_CHOICES = (1, 4, 8, 12)
+
+
+def resolve_aggregate_project_window_weeks(
+    requested: int, *, shared_start_at: object, current_week_start_at: object,
+) -> int:
+    """The drill window a row published by the All ranking must resolve with.
+
+    The two windows are anchored differently and one does not contain the
+    other. The ranking is ``n`` calendar days ending today. The drill is
+    ``weeks_back`` weeks anchored at the CURRENT MONDAY —
+    ``[cw_start - 7 * (weeks_back - 1), cw_start + 7)`` — so at the default four
+    weeks it reaches twenty-one days before that Monday, which is twenty-one to
+    twenty-seven days before today. Against a thirty-day ranking that leaves up
+    to nine days at the start of the ranking window ranked and undrillable: a
+    row published at a real dollar figure opens a modal reporting
+    ``window_cost_usd: 0.0`` and no sessions.
+
+    So the window is the SMALLEST accepted choice whose span reaches the
+    resolved shared start, and never narrower than the caller asked for. When
+    NO accepted choice reaches it — a shared start further back than twelve
+    weeks before the current Monday — the widest choice is returned instead,
+    which is the closest the accepted set can come rather than a span that
+    reaches. It is not silent either way: ``window_weeks`` is in the payload
+    and the detail states the resolved span it covered, so a window that falls
+    short says so rather than implying it reached. When either bound is
+    unresolvable the caller's value stands, because guessing a wider window
+    over an unknown range would state a span nothing established.
+
+    Pure. ``_build_claude_source_detail`` supplies the two bounds.
+    """
+    if not isinstance(shared_start_at, str) or not isinstance(
+        current_week_start_at, str,
+    ):
+        return requested
+    try:
+        shared_start = parse_iso_datetime(
+            shared_start_at, "aggregates.range.start_at",
+        )
+        cw_start = parse_iso_datetime(
+            current_week_start_at, "projects.current_week.week_start_at",
+        )
+    except ValueError:
+        return requested
+    covering = [
+        weeks for weeks in PROJECT_WINDOW_WEEKS_CHOICES
+        if cw_start - dt.timedelta(days=7 * (weeks - 1)) <= shared_start
+    ]
+    if not covering:
+        return max(PROJECT_WINDOW_WEEKS_CHOICES[-1], requested)
+    return max(min(covering), requested)
+
+
+def _published_aggregate_start_at(snapshot) -> object:
+    """``sources.all.data.aggregates.range.start_at``, or ``None``."""
+    bundle = getattr(snapshot, "source_bundle", None)
+    try:
+        data = bundle.sources["all"].data
+    except (AttributeError, KeyError, TypeError):
+        return None
+    if not isinstance(data, Mapping):
+        return None
+    aggregates = data.get("aggregates")
+    published = (
+        aggregates.get("range") if isinstance(aggregates, Mapping) else None
+    )
+    return published.get("start_at") if isinstance(published, Mapping) else None
+
+
+def _project_window_weeks_for_key(snapshot, key: str, requested: int) -> int:
+    """Widen the drill window for a key the All ranking published.
+
+    A key absent from the published aggregate rows was not ranked over the
+    shared range, so nothing about that range describes it and the caller's
+    window stands unchanged.
+    """
+    if not any(
+        isinstance(row, Mapping) and row.get("key") == key
+        for row in _claude_aggregate_project_rows(snapshot)
+    ):
+        return requested
+    env = getattr(snapshot, "projects_envelope", None)
+    current = env.get("current_week") if isinstance(env, Mapping) else None
+    return resolve_aggregate_project_window_weeks(
+        requested,
+        shared_start_at=_published_aggregate_start_at(snapshot),
+        current_week_start_at=(
+            current.get("week_start_at") if isinstance(current, Mapping) else None
+        ),
+    )
+
+
 def _claude_project_key_for_source_key(snapshot, key: str) -> str | None:
     env = getattr(snapshot, "projects_envelope", None)
-    if not isinstance(env, Mapping):
-        return None
     candidates: list[object] = []
-    current = env.get("current_week")
-    if isinstance(current, Mapping):
-        candidates.extend(current.get("rows") or ())
-    trend = env.get("trend")
-    if isinstance(trend, Mapping):
-        candidates.extend(trend.get("projects") or ())
+    if isinstance(env, Mapping):
+        current = env.get("current_week")
+        if isinstance(current, Mapping):
+            candidates.extend(current.get("rows") or ())
+        trend = env.get("trend")
+        if isinstance(trend, Mapping):
+            candidates.extend(trend.get("projects") or ())
     for row in candidates:
         if not isinstance(row, Mapping):
             continue
@@ -1038,6 +1157,16 @@ def _claude_project_key_for_source_key(snapshot, key: str) -> str | None:
             dashboard_resource_key("project", "claude", project_key) == key
         ):
             return project_key
+    # #556 S2 remediation: there is deliberately NO fallback to the published
+    # aggregate rows here. A retained bundle outlives the per-tick envelope
+    # rebuild, so its labels can be stale, and `_project_detail_for_window`
+    # resolves whatever this returns against the CURRENT envelope. Labels are
+    # population-sensitive, so a stale label either misses there anyway — the
+    # same 404, reached one step later — or names a DIFFERENT bucket and serves
+    # another project's sessions under this key. A guarded fallback would be
+    # dead code besides: the aggregate key is minted from its label by the same
+    # rule the loop above inverts, so any label the current envelope still
+    # carries has already matched.
     return None
 
 
@@ -1094,6 +1223,13 @@ def _build_claude_source_detail(
         project_key = _claude_project_key_for_source_key(snapshot, key)
         if project_key is None:
             raise SourceResourceNotFound()
+        # #556 S2 remediation: a row the All ranking published states a figure
+        # over the shared range, so its detail has to reach that range. The
+        # default four-week drill is anchored at the current Monday and misses
+        # up to nine days at the start of a thirty-day ranking.
+        window_weeks = _project_window_weeks_for_key(
+            snapshot, key, window_weeks,
+        )
         conn = open_db()
         try:
             conn.execute("ATTACH DATABASE ? AS cache_db", (str(_cctally_core.CACHE_DB_PATH),))
@@ -2976,6 +3112,87 @@ def _group_a_daily_buckets(now_utc, *, n, display_tz):
         cache_conn.close()
 
 
+def materialise_daily_calendar(
+    view_rows,
+    *,
+    now_utc: "dt.datetime",
+    n: int = 30,
+    display_tz: "ZoneInfo | None" = None,
+) -> "list[DailyPanelRow]":
+    """Materialize the contiguous ``n``-day calendar. Pure, no I/O.
+
+    ``view_rows`` is ``build_daily_view``'s gap-free newest-first row sequence,
+    which carries the data-plane fields and leaves ``label`` and
+    ``intensity_bucket`` at dataclass defaults (spec §4.4). This adapter
+    overlays those rows onto the calendar window, adds a zero-cost row for
+    every gap day so the heatmap shows a faded cell, and fills the two
+    presentation-only fields.
+
+    #556 S2 §6.3a extracted this from ``_dashboard_build_daily_panel``, which
+    opens its own connection through Group A or ``get_entries`` and cannot be
+    called from the pinned source-bundle fold. Unlike that function, this one
+    emits a COMPLETE shape for an empty provider rather than nothing: under All
+    an empty provider is a zero leg, and a zero leg still has a shape, so the
+    client never needs a second source for the calendar it renders.
+    """
+    rows_by_date = {r.date: r for r in (view_rows or ())}
+    today_local = (
+        now_utc.astimezone(display_tz) if display_tz is not None
+        # internal fallback: host-local intentional
+        else now_utc.astimezone()
+    ).date()
+
+    rows: list[DailyPanelRow] = []
+    for i in range(n):
+        d = today_local - dt.timedelta(days=i)
+        date_str = d.isoformat()
+        existing = rows_by_date.get(date_str)
+        if existing is not None:
+            # Use the view-model row but fill the presentation-only
+            # ``label`` (intensity_bucket is set by
+            # ``_compute_intensity_buckets`` below).
+            rows.append(dataclasses.replace(existing, label=date_str[5:]))
+        else:
+            # Zero-cost gap day: tokens default to 0, cache_hit_pct to None
+            # (avoids /0 and signals 'no data' cleanly to the modal tile).
+            rows.append(DailyPanelRow(
+                date=date_str,
+                label=date_str[5:],
+                cost_usd=0.0,
+                is_today=(d == today_local),
+                intensity_bucket=0,
+                models=[],
+            ))
+
+    _compute_intensity_buckets(rows)
+    return rows
+
+
+def daily_panel_row_to_wire(row: "DailyPanelRow") -> dict:
+    """One wire shape for a daily row, whichever sibling published it.
+
+    ``snapshot_to_envelope``'s ``_daily_row_to_dict`` delegates here, so the
+    All-only ``periods.daily_aggregate.rows`` sibling and the legacy
+    ``periods.daily.rows`` cannot drift into two shapes the client would have
+    to tell apart.
+    """
+    return {
+        "date":             row.date,
+        "label":            row.label,
+        "cost_usd":         row.cost_usd,
+        "is_today":         row.is_today,
+        "intensity_bucket": row.intensity_bucket,
+        "models":           list(row.models),
+        # ---- v2.3 additions ----
+        "input_tokens":          row.input_tokens,
+        "output_tokens":         row.output_tokens,
+        "cache_creation_tokens": row.cache_creation_tokens,
+        "cache_read_tokens":     row.cache_read_tokens,
+        "total_tokens":          row.total_tokens,
+        "cache_hit_pct":         row.cache_hit_pct,
+    }
+
+
 def _dashboard_build_daily_panel(conn: "sqlite3.Connection",
                                   now_utc: "dt.datetime",
                                   *,
@@ -3050,42 +3267,13 @@ def _dashboard_build_daily_panel(conn: "sqlite3.Connection",
     if not view.rows:
         return []
 
-    # Materialize the contiguous N-day window. ``view.rows`` is gap-free
-    # (newest-first) and carries the data-plane fields; the adapter
-    # overlays it onto the calendar window and fills the presentation-
-    # only ``label`` / ``intensity_bucket`` (which the builder left at
-    # dataclass defaults per spec §4.4).
-    rows_by_date = {r.date: r for r in view.rows}
-    today_local = (
-        now_utc.astimezone(display_tz) if display_tz is not None
-        # internal fallback: host-local intentional
-        else now_utc.astimezone()
-    ).date()
-
-    rows: list[DailyPanelRow] = []
-    for i in range(n):
-        d = today_local - dt.timedelta(days=i)
-        date_str = d.isoformat()
-        existing = rows_by_date.get(date_str)
-        if existing is not None:
-            # Use the view-model row but fill the presentation-only
-            # ``label`` (intensity_bucket is set by
-            # ``_compute_intensity_buckets`` below).
-            rows.append(dataclasses.replace(existing, label=date_str[5:]))
-        else:
-            # Zero-cost gap day: tokens default to 0, cache_hit_pct to None
-            # (avoids /0 and signals 'no data' cleanly to the modal tile).
-            rows.append(DailyPanelRow(
-                date=date_str,
-                label=date_str[5:],
-                cost_usd=0.0,
-                is_today=(d == today_local),
-                intensity_bucket=0,
-                models=[],
-            ))
-
-    _compute_intensity_buckets(rows)
-    return rows
+    # Materialize the contiguous N-day window. #556 S2 §6.3a extracted the
+    # block below into ``materialise_daily_calendar`` so the All-only Claude
+    # daily leg can reach it without this function's I/O; the Claude tab's
+    # behaviour is unchanged, including the empty-provider early return above.
+    return materialise_daily_calendar(
+        view.rows, now_utc=now_utc, n=n, display_tz=display_tz,
+    )
 
 
 # --- Projects panel / modal (spec 2026-05-19-projects-panel-design.md) ------
@@ -3217,6 +3405,250 @@ def _projects_iter_session_entries(conn: "sqlite3.Connection",
         yield row
 
 
+# === #556 S2 — the shared cross-provider aggregate range (spec §3.2, §3.4) ===
+#
+# One UTC interval, resolved once per tick and passed immutably to both Claude
+# folds. Membership is ``shared_start <= parsed_timestamp < shared_end_exclusive``
+# enforced on PARSED datetimes with microseconds preserved.
+#
+# ``_projects_iter_session_entries`` deliberately cannot serve this read. It
+# implements an inclusive ``[since, until]`` query, truncates both bounds to
+# whole seconds and spells them with a ``Z`` suffix, and compares with ``<=``.
+# Production ingestion writes ``timestamp.astimezone(utc).isoformat()``
+# (``bin/_cctally_cache.py``), so a stored value keeps its ``+00:00`` offset and
+# its microseconds. SQLite compares that TEXT column lexically, and ``+`` (0x2B)
+# sorts BELOW ``Z`` (0x5A) — so an entry exactly at the lower bound would be
+# dropped, while an entry inside the closing second would be admitted past the
+# exclusive upper bound. This iterator therefore uses the SQL predicate only as
+# an outward-widened CANDIDATE filter and enforces the real comparison in Python.
+#
+# The published range's `kind` and `label` are NOT declared here. They live once,
+# beside the canonicaliser that emits them, as `AGGREGATE_RANGE_KIND` and
+# `AGGREGATE_RANGE_LABEL` in `bin/_lib_dashboard_sources.py`.
+
+
+def resolve_shared_range(daily_panel, *, now_utc, display_tz, n: int = 30):
+    """Return ``(shared_start, shared_end_exclusive)`` for the All aggregates.
+
+    ``shared_start`` is the earliest day of the already-built ``n``-day daily
+    panel, taken at midnight in the resolved display timezone.
+    ``shared_end_exclusive`` is ``now_utc + 1 microsecond``, which is the bound
+    the Codex projects read already applies, so the Codex tab stays
+    byte-stable.
+
+    BOTH branches floor to display-timezone midnight, and the fallback branch
+    resolves the same calendar day the panel branch would have named **provided
+    the panel is exactly ``n`` contiguous days ending today**. Every production
+    panel has that shape (``materialise_daily_calendar`` gap-fills a contiguous
+    calendar), so the two branches agree there. They do NOT agree in general: a
+    caller that hands in a sparse or shorter panel gets that panel's own oldest
+    day from the first branch and ``today - (n - 1) days`` from the fallback.
+    Two separate defects require the flooring, and neither is visible with a
+    pinned bound:
+
+    1. The start is folded into version material at DAY granularity
+       (``aggregate_scope_identity``), while ``compose_all_aggregates`` compares
+       the two providers' carriers on the exact canonical string. A start that
+       moves within a day therefore passes the reuse gate for an unchanged
+       provider while a rebuilt provider records the newer instant, and the two
+       carriers then disagree. The old fallback, ``now_utc - 30 days``, is a
+       microsecond-precise instant that advances on every tick, so on a
+       Claude-inactive, Codex-active install every tick withheld both
+       aggregates as ``retained_range_mismatch`` and published no range at all.
+    2. ``daily_aggregate.rows`` is ``n`` CALENDAR days ending today
+       (``materialise_daily_calendar``). A rolling ``n * 24h`` fallback started
+       part-way through a further day, so the published range stated a span the
+       row table did not cover.
+    """
+    now_utc = now_utc.astimezone(dt.timezone.utc)
+    if daily_panel:
+        # The panel is newest-first, so the oldest of its FIRST `n` rows is the
+        # `n`-day floor. Reading `daily_panel[-1]` unconditionally ignored `n`,
+        # so a caller asking for a shorter window than the panel it passed got
+        # the panel's full extent from this branch and the shorter window from
+        # the fallback — two branches describing different spans under one
+        # parameter.
+        earliest_day = dt.date.fromisoformat(
+            daily_panel[min(max(n, 1), len(daily_panel)) - 1].date,
+        )
+    else:
+        today_local = (
+            now_utc.astimezone(display_tz) if display_tz is not None
+            # internal fallback: host-local intentional
+            else now_utc.astimezone()
+        ).date()
+        earliest_day = today_local - dt.timedelta(days=n - 1)
+    if display_tz is not None:
+        start = dt.datetime.combine(
+            earliest_day, dt.time.min, tzinfo=display_tz,
+        ).astimezone(dt.timezone.utc)
+    else:
+        # internal fallback: host-local intentional
+        start = dt.datetime.combine(
+            earliest_day, dt.time.min,
+        ).astimezone(dt.timezone.utc)
+    return start, now_utc + dt.timedelta(microseconds=1)
+
+
+def _shared_range_candidate_bounds(start, end_exclusive):
+    """Whole-second SQL bounds widened OUTWARD on both ends.
+
+    One second of slack in each direction is what makes the candidate set a
+    strict superset regardless of how a stored timestamp spells its offset
+    (``+00:00`` or ``Z``) or whether it carries a fractional part.
+    """
+    low = start.astimezone(dt.timezone.utc).replace(
+        microsecond=0,
+    ) - dt.timedelta(seconds=1)
+    high = end_exclusive.astimezone(dt.timezone.utc).replace(
+        microsecond=0,
+    ) + dt.timedelta(seconds=1)
+    return low.isoformat(), high.isoformat()
+
+
+def iter_shared_range_entries(conn, *, start, end_exclusive):
+    """Yield ``session_entries`` rows inside ``[start, end_exclusive)``.
+
+    Column order matches ``_projects_iter_session_entries`` exactly, so
+    ``_fold_projects_entry``'s per-row arithmetic consumes these rows unchanged
+    (spec §3.4 — reuse the arithmetic, not the week-bucket gate).
+
+    Two stages: an indexed candidate ``SELECT`` over widened whole-second
+    bounds, then the authoritative half-open comparison on parsed datetimes.
+    """
+    since_iso, until_iso = _shared_range_candidate_bounds(start, end_exclusive)
+    cur = conn.execute(
+        "SELECT e.id, e.timestamp_utc, e.model, e.input_tokens, "
+        "       e.output_tokens, e.cache_create_tokens, e.cache_read_tokens, "
+        "       e.cost_usd_raw, e.source_path, "
+        "       sf.session_id, sf.project_path, "
+        "       e.cache_create_1h_tokens, e.speed "
+        "FROM session_entries e "
+        "LEFT JOIN session_files sf ON sf.path = e.source_path "
+        "WHERE e.timestamp_utc >= ? AND e.timestamp_utc <= ? "
+        "ORDER BY e.timestamp_utc ASC, e.id ASC",
+        (since_iso, until_iso),
+    )
+    for row in cur:
+        ts = parse_iso_datetime(row[1], "session_entries.timestamp_utc")
+        if start <= ts < end_exclusive:
+            yield row
+
+
+def _shared_range_row_to_usage_entry(row):
+    """Rebuild the ``UsageEntry`` the daily aggregator consumes.
+
+    Field-for-field identical to ``_cctally_cache.iter_entries``, including
+    ``datetime.fromisoformat`` rather than ``parse_iso_datetime`` — the daily
+    aggregate has to reproduce what the legacy daily panel would compute over
+    the same rows, so this construction must not diverge from that one.
+    """
+    (_entry_id, ts_iso, model, input_tok, output_tok,
+     cache_create, cache_read, cost_raw, source_path,
+     _session_id, _project_path, cache_1h, speed) = row
+    return _cctally().UsageEntry(
+        timestamp=dt.datetime.fromisoformat(ts_iso),
+        model=model,
+        usage=claude_usage_dict(   # #195 chokepoint
+            input_tokens=input_tok,
+            output_tokens=output_tok,
+            cache_creation_tokens=cache_create,
+            cache_read_tokens=cache_read,
+            cache_1h_tokens=cache_1h,
+            speed=speed,
+        ),
+        cost_usd=cost_raw,
+        source_path=source_path,
+    )
+
+
+def _fold_prepared_daily_entries(
+    accumulators, entries, *, display_tz=None, mode: str = "auto",
+):
+    """Append prepared entries through the canonical daily fold primitive."""
+    for entry in entries:
+        if entry.model == "<synthetic>":
+            continue
+        key = entry.timestamp.astimezone(display_tz).strftime("%Y-%m-%d")
+        accumulator = accumulators.get(key)
+        if accumulator is None:
+            accumulator = _new_bucket_acc()
+            accumulators[key] = accumulator
+        _fold_entry(accumulator, entry, mode)
+
+
+def _finalize_daily_accumulators(accumulators):
+    return [
+        _finalize_bucket(key, accumulators[key])
+        for key in sorted(accumulators)
+    ]
+
+
+def fold_daily_over_range(
+    rows, *, display_tz=None, mode: str = "auto", prepared_entries=None,
+):
+    """Fold the shared candidate stream into per-day ``BucketUsage``.
+
+    Consumes the SAME already-materialised sequence the projects fold reads
+    (spec §3.4 — one candidate read, two folds). ``_aggregate_daily`` skips
+    ``<synthetic>`` rows itself, so both folds share that policy.
+    """
+    entries = (
+        prepared_entries
+        if prepared_entries is not None and mode == "auto"
+        else [_shared_range_row_to_usage_entry(row) for row in rows]
+    )
+    return _aggregate_daily(entries, mode=mode, tz=display_tz)
+
+
+def build_daily_aggregate_rows(
+    rows,
+    *,
+    now_utc: "dt.datetime",
+    display_tz=None,
+    n: int = 30,
+    mode: str = "auto",
+    prepared_entries=None,
+) -> "list[DailyPanelRow]":
+    """The complete canonical thirty-day shape for the All Daily aggregate.
+
+    Pure apart from the caller's already-completed read. Folds the shared
+    candidate stream, runs it through the same ``build_daily_view`` data plane
+    the legacy panel uses, then materializes the contiguous calendar — so an
+    empty Claude provider still publishes a full zero-cost shape (§6.3a).
+    """
+    buckets = fold_daily_over_range(
+        rows,
+        display_tz=display_tz,
+        mode=mode,
+        prepared_entries=prepared_entries,
+    )
+    return _build_daily_aggregate_rows_from_buckets(
+        buckets,
+        now_utc=now_utc,
+        display_tz=display_tz,
+        n=n,
+        mode=mode,
+    )
+
+
+def _build_daily_aggregate_rows_from_buckets(
+    buckets,
+    *,
+    now_utc,
+    display_tz=None,
+    n: int = 30,
+    mode: str = "auto",
+):
+    view = _cctally().build_daily_view(
+        (), now_utc=now_utc, display_tz=display_tz, mode=mode,
+        aggregated_override=buckets,
+    )
+    return materialise_daily_calendar(
+        view.rows, now_utc=now_utc, n=n, display_tz=display_tz,
+    )
+
+
 class _ProjWeekBucket(NamedTuple):
     """One (bucket_path, week) immutable aggregate for the projects-envelope
     per-week cache (#269 §14 Win 2).
@@ -3248,7 +3680,8 @@ def _fold_projects_entry(
     row: tuple,
     *,
     resolver_cache: dict,
-    week_start: "dt.datetime",
+    week_start: "dt.datetime | None",
+    prepared_daily_entries: "list | None" = None,
 ) -> "float | None":
     """Fold ONE ``_projects_iter_session_entries`` row onto ``mut`` (the shared
     per-row body, #271 §20 Codex-P1a).
@@ -3267,6 +3700,13 @@ def _fold_projects_entry(
     order-safe for the warm append because every delta row sorts strictly after
     ``tail`` (#271 §20), so a delta row is never the first-seen of a bucket that
     already exists in ``mut``.
+
+    ``week_start=None`` (#556 S2 §3.4) disables ONLY the week-bucket gate, for
+    the range-native fold that ranks projects over one absolute interval. Every
+    other caller passes a real week start and is byte-unchanged. The gate is the
+    single line below; the cost, identity, session and first/last-seen
+    arithmetic beneath it is what both callers share, and sharing it is what
+    keeps the dashboard reconcilable with the CLI.
     """
     c = _cctally()
     (entry_id, ts_iso, model, input_tok, output_tok,
@@ -3275,21 +3715,32 @@ def _fold_projects_entry(
     if model == "<synthetic>":
         return None
     ts = parse_iso_datetime(ts_iso, "session_entries.timestamp_utc")
-    if _projects_week_start_monday_utc(ts) != week_start:
+    if week_start is not None and _projects_week_start_monday_utc(ts) != week_start:
         return None
+    usage = claude_usage_dict(   # #195 chokepoint
+        input_tokens=input_tok,
+        output_tokens=output_tok,
+        cache_creation_tokens=cache_create,
+        cache_read_tokens=cache_read,
+        cache_1h_tokens=cache_1h,
+        speed=speed,
+    )
     entry_cost = _calculate_entry_cost(
         model,
-        claude_usage_dict(   # #195 chokepoint
-            input_tokens=input_tok,
-            output_tokens=output_tok,
-            cache_creation_tokens=cache_create,
-            cache_read_tokens=cache_read,
-            cache_1h_tokens=cache_1h,
-            speed=speed,
-        ),
+        usage,
         mode="auto",
         cost_usd=cost_raw,
     )
+    if prepared_daily_entries is not None:
+        # #567: preserve the canonical daily entry and aggregator while
+        # handing off the effective cost this pass already computed.
+        prepared_daily_entries.append(c.UsageEntry(
+            timestamp=dt.datetime.fromisoformat(ts_iso),
+            model=model,
+            usage=usage,
+            cost_usd=entry_cost,
+            source_path=source_path,
+        ))
     pkey = c._resolve_project_key(project_path, "git-root", resolver_cache)
     bp = pkey.bucket_path
     a = mut.get(bp)
@@ -3316,6 +3767,460 @@ def _fold_projects_entry(
     return entry_cost
 
 
+def fold_projects_over_range(
+    rows, *, resolver_cache=None, prepared_daily_entries=None,
+) -> "dict[str, dict]":
+    """Fold an ALREADY-MATERIALISED candidate stream into per-bucket totals.
+
+    #556 S2 §3.4. Takes rows rather than a connection because one candidate read
+    serves both All-only Claude folds: reopening or rescanning would price the
+    same thirty-day population twice and extend the pinned cache snapshot's
+    WAL-holding lifetime for no gain.
+
+    Returns the RAW ``mut`` shape ``_fold_projects_entry`` maintains —
+    ``{bucket_path: {"cost_usd", "sessions" (a set), "first_seen", "last_seen",
+    "first_order", "first_id", "first_key" (the ``ProjectKey``)}}``. The
+    ``ProjectKey`` is retained deliberately: §3.8 disambiguates labels over
+    exactly this bounded population, and the legacy builder's collision-safe
+    label has already been replaced by an opaque key by the time the source
+    bundle sees ``claude_data``, so there is nothing left to capture there.
+
+    No ``attributed_pct`` is computed. Weekly quota attribution divides by a
+    subscription week's total (``_build_projects_envelope`` does it later), which
+    is not meaningful for an absolute-range ranking.
+    """
+    mut: "dict[str, dict]" = {}
+    cache = {} if resolver_cache is None else resolver_cache
+    for row in rows:
+        _fold_projects_entry(
+            mut,
+            row,
+            resolver_cache=cache,
+            week_start=None,
+            prepared_daily_entries=prepared_daily_entries,
+        )
+    return mut
+
+
+def legacy_project_labels(projects_envelope: object) -> "dict[str, str]":
+    """``bucket_path`` -> legacy display key, over the two published collections.
+
+    These are exactly the collections ``_project_detail_for_window`` resolves a
+    requested display key against (`current_week.rows`, then `trend.projects`),
+    so this is the population in which agreement between the aggregate identity
+    and the legacy one is both possible and useful. A bucket outside it cannot
+    be served by the drill-down under either label.
+
+    Pure; the caller supplies the envelope the sync thread already built.
+    """
+    mapped: "dict[str, str]" = {}
+    env = projects_envelope if isinstance(projects_envelope, Mapping) else {}
+    current = env.get("current_week")
+    trend = env.get("trend")
+    collections = (
+        (current.get("rows") if isinstance(current, Mapping) else None),
+        (trend.get("projects") if isinstance(trend, Mapping) else None),
+    )
+    for collection in collections:
+        for row in collection or ():
+            if not isinstance(row, Mapping):
+                continue
+            bucket_path = row.get("bucket_path")
+            display_key = row.get("key")
+            if isinstance(bucket_path, str) and bucket_path and (
+                isinstance(display_key, str) and display_key
+            ):
+                mapped.setdefault(bucket_path, display_key)
+    return mapped
+
+
+def build_project_aggregate_rows(
+    rows,
+    *,
+    resolver_cache=None,
+    legacy_labels=None,
+    prepared_daily_entries=None,
+) -> "list[dict]":
+    """Published `providers.claude.projects.aggregate.rows` (spec §3.5.1).
+
+    Folds the shared candidate stream, labels each bucket, and publishes it as
+    ``{key, label, source, cost_usd, sessions_count, drillable}``.
+
+    **The label is the legacy display key wherever the legacy population knows
+    the bucket, and the bounded disambiguated label otherwise.** The opaque key
+    is minted from whichever label is published, through the same rule the
+    legacy Claude project rows use (``dashboard_resource_key("project",
+    "claude", <display key>)``).
+
+    **The published population is not the routable one, and each row says
+    which it is in.** The legacy population is not a superset of the bounded
+    one on either axis. It is not a superset in COST, because ``trend_projects``
+    skips a bucket whose cost is 0.0 across every trend week and
+    ``current_week.rows`` carries only buckets with a current-week entry. It is
+    not a superset in TIME either: the envelope walks
+    ``[weeks_full[0], cw_start + 7d]`` and drops any entry whose
+    Monday-anchored week falls outside ``weeks_full``, so an entry after the
+    current week's nominal end is invisible to it while this fold correctly
+    reaches ``now``. ``tests/fixtures/dashboard/tz-override`` is that shape: one
+    priced project at exactly ``now``, published in the aggregate and absent
+    from both legacy collections.
+
+    Filtering the published rows to the legacy population would drop that real
+    row rather than fix it, and widening ``_build_projects_envelope``'s window
+    is out of scope here because the Claude tab and the reconcile harness both
+    read it. So the gap is resolved at the SEAM instead: ``drillable`` states,
+    per row, whether the drill-down can reach that bucket, computed from the
+    same collections ``_claude_project_key_for_source_key`` searches. A
+    ``False`` row keeps its rank, its label and its cost — the ranking stays
+    complete — and the client renders it without a drill affordance rather
+    than offering an interaction that 404s.
+
+    ``drillable`` is exactly ``bucket_path in legacy_labels``. That is the
+    condition under which the published label IS a legacy display key, so the
+    minted opaque key is the one the route inverts. Deliberately NOT "the
+    published label happens to appear among the legacy display keys": for a
+    bucket the legacy population does not carry, a bounded label that collided
+    with some OTHER bucket's legacy key would resolve, and serve that other
+    project's sessions under this row's identity. A mis-route is worse than a
+    withheld drill, so the predicate names the bucket, not the string.
+
+    The split is what makes the aggregate rows ROUTABLE. Labels are
+    population-sensitive by design (`bin/_cctally_project.py`), so
+    disambiguating over the bounded thirty-day population and over the legacy
+    twelve-week one can produce different overrides for the same project — a
+    project sharing a basename with an older root forces an override in one
+    population and not in the other. Two labels means two opaque keys, and the
+    drill-down resolves the requested key against the LEGACY display keys
+    (`_claude_project_key_for_source_key` -> `_project_detail_for_window`), so
+    a bounded-only key 404s even for a project both collections know.
+    Preferring the legacy key where one exists makes the two identities agree
+    by construction, and it does not weaken §9.2's twin-pair requirement:
+    the legacy population disambiguates that pair too, so the two rows keep
+    distinct labels and distinct identities.
+
+    ``legacy_labels`` is ``{bucket_path: display_key}`` from
+    ``legacy_project_labels``. A bucket it does not carry falls back to the
+    bounded disambiguated label. ``None`` means "no legacy population was
+    supplied" and is NOT a production path: production withholds the aggregate
+    when no envelope was built (`_tui_build_claude_aggregates`), because
+    publishing rows against an unknown routable population is the silent
+    identity change this rule exists to prevent. It is kept for kernel callers
+    that fold a store with no envelope beside it.
+
+    No ``attributed_pct``: quota attribution divides by a subscription week's
+    total and means nothing over an absolute range. No ``bucket_path``, git
+    root or raw source path — opaque keys stay non-reversible.
+    """
+    folded = fold_projects_over_range(
+        rows,
+        resolver_cache=resolver_cache,
+        prepared_daily_entries=prepared_daily_entries,
+    )
+    return _project_aggregate_rows_from_folded(folded, legacy_labels)
+
+
+def _project_aggregate_rows_from_folded(folded, legacy_labels):
+    """Finalize cached/raw project accumulators into the public row shape."""
+    c = _cctally()
+    bucket_paths_sorted = sorted(folded)
+    augmented_by_idx = c._project_disambiguate_labels(
+        [{"key": folded[bp]["first_key"]} for bp in bucket_paths_sorted],
+    )
+    legacy = legacy_labels if isinstance(legacy_labels, Mapping) else {}
+    published: "list[dict]" = []
+    for idx, bucket_path in enumerate(bucket_paths_sorted):
+        accumulator = folded[bucket_path]
+        legacy_label = legacy.get(bucket_path)
+        label = legacy_label or augmented_by_idx.get(
+            idx, accumulator["first_key"].display_key,
+        )
+        published.append({
+            "key": dashboard_resource_key("project", "claude", label),
+            "label": label,
+            "source": "claude",
+            # Whether `GET /api/source/claude/project/<key>` can resolve this
+            # row. See the docstring: the predicate names the BUCKET, so a
+            # bounded label that collides with an unrelated legacy key never
+            # advertises a drill that would serve the wrong project.
+            "drillable": legacy_label is not None,
+            # NOT rounded, for the same reason `current_week.rows` is not:
+            # `round(..., 6)` introduces ~1e-6 error that breaks the 1e-9
+            # reconcile tolerance.
+            "cost_usd": accumulator["cost_usd"],
+            "sessions_count": len(accumulator["sessions"]),
+        })
+    # Desc by cost, ties broken by label so the ranking is byte-stable.
+    published.sort(key=lambda row: (-row["cost_usd"], row["label"]))
+    return published
+
+
+_CLAUDE_RANGE_AGGREGATE_MEMO: dict[str, object] = {"state": None}
+
+
+def reset_claude_range_aggregate_memo() -> None:
+    """Drop the process-local #567 range-fold accumulator."""
+    _CLAUDE_RANGE_AGGREGATE_MEMO["state"] = None
+
+
+def _shared_range_store_identity(conn):
+    for _seq, name, path in conn.execute("PRAGMA database_list"):
+        if name == "main":
+            if not path:
+                return (f":memory:{id(conn)}", None, None)
+            try:
+                stat = os.stat(path)
+            except OSError:
+                return (str(path), None, None)
+            return (str(path), int(stat.st_dev), int(stat.st_ino))
+    return f":connection:{id(conn)}"
+
+
+def _shared_range_entry_signature(conn) -> tuple[int, int]:
+    max_id = int(conn.execute(
+        "SELECT COALESCE(MAX(id), 0) FROM main.session_entries"
+    ).fetchone()[0])
+    try:
+        max_seq = int(conn.execute(
+            "SELECT COALESCE(MAX(mutation_seq), 0) FROM main.session_entries"
+        ).fetchone()[0])
+    except sqlite3.OperationalError:
+        max_seq = 0
+    return max_id, max_seq
+
+
+def _shared_range_session_files_signature(conn) -> tuple[int, int]:
+    """Cheap identity signal for lazy session/project metadata backfills."""
+    try:
+        row = conn.execute(
+            "SELECT COUNT(*), COALESCE(MAX(rowid), 0) FROM session_files"
+        ).fetchone()
+    except sqlite3.Error:
+        return (0, 0)
+    return int(row[0]), int(row[1])
+
+
+def _shared_range_entries_after_id(conn, after_id: int):
+    """Yield appended rows in canonical timestamp/id fold order."""
+    cur = conn.execute(
+        "SELECT e.id, e.timestamp_utc, e.model, e.input_tokens, "
+        "       e.output_tokens, e.cache_create_tokens, e.cache_read_tokens, "
+        "       e.cost_usd_raw, e.source_path, "
+        "       sf.session_id, sf.project_path, "
+        "       e.cache_create_1h_tokens, e.speed "
+        "FROM session_entries e "
+        "LEFT JOIN session_files sf ON sf.path = e.source_path "
+        "WHERE e.id > ? "
+        "ORDER BY e.timestamp_utc ASC, e.id ASC",
+        (after_id,),
+    )
+    yield from cur
+
+
+def _shared_range_prior_row_mutated(
+    conn, *, after_seq: int, through_id: int,
+) -> bool:
+    try:
+        row = conn.execute(
+            "SELECT 1 FROM main.session_entries "
+            "WHERE mutation_seq > ? AND id <= ? LIMIT 1",
+            (after_seq, through_id),
+        ).fetchone()
+    except sqlite3.OperationalError:
+        return True
+    return row is not None
+
+
+def _shared_range_cache_base(
+    conn, *, shared_start, display_tz, generation: int,
+):
+    tz_key = getattr(display_tz, "key", None)
+    if tz_key is None:
+        tz_key = str(display_tz) if display_tz is not None else "local"
+    return (
+        _shared_range_store_identity(conn),
+        shared_start.astimezone(dt.timezone.utc).isoformat(),
+        tz_key,
+        int(generation),
+        _shared_range_session_files_signature(conn),
+        int(conn.execute(
+            "SELECT COALESCE(MIN(id), 0) FROM main.session_entries"
+        ).fetchone()[0]),
+    )
+
+
+def _shared_range_cache_payload(
+    state,
+    *,
+    legacy_labels,
+    now_utc,
+    display_tz,
+):
+    project_rows = _project_aggregate_rows_from_folded(
+        state["project_mut"], legacy_labels,
+    )
+    daily_buckets = _finalize_daily_accumulators(state["daily_accumulators"])
+    daily_rows = _build_daily_aggregate_rows_from_buckets(
+        daily_buckets, now_utc=now_utc, display_tz=display_tz,
+    )
+    c = _cctally()
+    return {
+        "projects": project_rows,
+        "daily": [c.daily_panel_row_to_wire(row) for row in daily_rows],
+    }
+
+
+def build_cached_claude_range_aggregates(
+    conn,
+    *,
+    shared_start,
+    shared_end_exclusive,
+    now_utc,
+    display_tz,
+    legacy_labels,
+    max_entry_id: "int | None" = None,
+    entry_mutation_seq: "int | None" = None,
+    generation: int = 0,
+):
+    """Build or increment the one-snapshot Claude range folds (#567).
+
+    Pure appends are folded onto the cached raw accumulators.  A shifted range
+    floor, backwards clock, generation or session-file identity change,
+    non-monotone signature, or an id-stable mutation of an already-folded row
+    falls back to one full ordered pass.  The cache stores no public labels, so
+    the current legacy population is reapplied on every publication.
+    """
+    if max_entry_id is None or entry_mutation_seq is None:
+        observed_id, observed_seq = _shared_range_entry_signature(conn)
+        if max_entry_id is None:
+            max_entry_id = observed_id
+        if entry_mutation_seq is None:
+            entry_mutation_seq = observed_seq
+    max_entry_id = int(max_entry_id)
+    entry_mutation_seq = int(entry_mutation_seq)
+    base = _shared_range_cache_base(
+        conn,
+        shared_start=shared_start,
+        display_tz=display_tz,
+        generation=generation,
+    )
+    prior = _CLAUDE_RANGE_AGGREGATE_MEMO.get("state")
+    state = None
+    if isinstance(prior, dict) and prior.get("base") == base:
+        monotone = (
+            max_entry_id >= prior["max_entry_id"]
+            and entry_mutation_seq >= prior["entry_mutation_seq"]
+            and shared_end_exclusive >= prior["end_exclusive"]
+        )
+        old_row_changed = (
+            entry_mutation_seq != prior["entry_mutation_seq"]
+            and _shared_range_prior_row_mutated(
+                conn,
+                after_seq=prior["entry_mutation_seq"],
+                through_id=prior["max_entry_id"],
+            )
+        )
+        if monotone and not old_row_changed:
+            project_mut = copy.deepcopy(prior["project_mut"])
+            daily_accumulators = copy.deepcopy(prior["daily_accumulators"])
+            resolver_cache = dict(prior["resolver_cache"])
+            delta_by_id = {}
+            for row in _shared_range_entries_after_id(
+                conn, prior["max_entry_id"],
+            ):
+                ts = parse_iso_datetime(
+                    row[1], "session_entries.timestamp_utc",
+                )
+                if shared_start <= ts < shared_end_exclusive:
+                    delta_by_id[row[0]] = row
+            if shared_end_exclusive > prior["end_exclusive"]:
+                for row in iter_shared_range_entries(
+                    conn,
+                    start=prior["end_exclusive"],
+                    end_exclusive=shared_end_exclusive,
+                ):
+                    if row[0] <= prior["max_entry_id"]:
+                        delta_by_id[row[0]] = row
+            delta_rows = sorted(
+                delta_by_id.values(),
+                key=lambda row: (row[1], row[0]),
+            )
+            prior_tail = prior["tail"]
+            if prior_tail is None or all(
+                (row[1], row[0]) > prior_tail
+                for row in delta_rows
+                if row[2] != "<synthetic>"
+            ):
+                prepared = []
+                for row in delta_rows:
+                    _fold_projects_entry(
+                        project_mut,
+                        row,
+                        resolver_cache=resolver_cache,
+                        week_start=None,
+                        prepared_daily_entries=prepared,
+                    )
+                _fold_prepared_daily_entries(
+                    daily_accumulators,
+                    prepared,
+                    display_tz=display_tz,
+                )
+                tail = prior_tail
+                real_delta = [
+                    row for row in delta_rows if row[2] != "<synthetic>"
+                ]
+                if real_delta:
+                    last = real_delta[-1]
+                    tail = (last[1], last[0])
+                state = {
+                    "base": base,
+                    "max_entry_id": max_entry_id,
+                    "entry_mutation_seq": entry_mutation_seq,
+                    "end_exclusive": shared_end_exclusive,
+                    "tail": tail,
+                    "project_mut": project_mut,
+                    "daily_accumulators": daily_accumulators,
+                    "resolver_cache": resolver_cache,
+                }
+    if state is None:
+        rows = tuple(iter_shared_range_entries(
+            conn, start=shared_start, end_exclusive=shared_end_exclusive,
+        ))
+        prepared = []
+        resolver_cache = {}
+        project_mut = fold_projects_over_range(
+            rows,
+            resolver_cache=resolver_cache,
+            prepared_daily_entries=prepared,
+        )
+        daily_accumulators = {}
+        _fold_prepared_daily_entries(
+            daily_accumulators, prepared, display_tz=display_tz,
+        )
+        real_rows = [row for row in rows if row[2] != "<synthetic>"]
+        tail = None
+        if real_rows:
+            last = real_rows[-1]
+            tail = (last[1], last[0])
+        state = {
+            "base": base,
+            "max_entry_id": max_entry_id,
+            "entry_mutation_seq": entry_mutation_seq,
+            "end_exclusive": shared_end_exclusive,
+            "tail": tail,
+            "project_mut": project_mut,
+            "daily_accumulators": daily_accumulators,
+            "resolver_cache": resolver_cache,
+        }
+    payload = _shared_range_cache_payload(
+        state,
+        legacy_labels=legacy_labels,
+        now_utc=now_utc,
+        display_tz=display_tz,
+    )
+    _CLAUDE_RANGE_AGGREGATE_MEMO["state"] = state
+    return payload
+
+
 def _aggregate_projects_week_raw(
     conn: "sqlite3.Connection",
     *,