cctally 1.117.0 → 1.118.0

package/bin/_cctally_five_hour.py

@@ -44,8 +44,10 @@ import sqlite3
 import sys
 from dataclasses import dataclass
 
+import _cctally_core  # `weekly_held_exclusion`: the held-column guard (#836)
 import _lib_accounts  # pure stdlib kernel; UNATTRIBUTED sentinel (#341)
 import _lib_rebuild_progress  # #997 D9 progress ticks (stdlib only)
+import _lib_stats_content_revision  # #1050 identical child-set check
 from _lib_five_hour import latest_five_hour_reading
 from _cctally_core import _command_as_of, eprint, now_utc_iso, open_db, parse_iso_datetime
 
@@ -1086,13 +1088,57 @@ def _credit_aware_block_weekly_axes(conn, block, *, now_utc, cache=None):
             block.get("seven_day_pct_at_block_end"))
 
 
+def _weekly_retired_sql(conn, alias: str) -> "str | None":
+    """The suppression-retired predicate over ``alias``, or None on a store
+    without the held column (#836, spec 5.4).
+
+    A held WRITE stores ``"weeklyObservationHeld": true`` in ``payload_json``
+    beside its effective basis value (`_cctally_record`, the held branch of
+    the snapshot write). A weekly credit's cleanup instead turns an UNHELD row,
+    whose payload never carried that marker, into a held one and leaves its
+    stale `weekly_percent` in place (`_delete_doomed_snapshot_rows`, replay
+    `_cctally_journal._retire_weekly_effects`). The marker therefore separates
+    the two exactly. A store without the column cannot hold a held row, the
+    reason `_cctally_core.weekly_held_exclusion` omits its own predicate there.
+    """
+    if not _cctally_core.weekly_held_exclusion(conn):
+        return None
+    return (f"({alias}.weekly_observation_held = 1 AND "
+            f"json_extract({alias}.payload_json, '$.weeklyObservationHeld') "
+            f"IS NOT 1)")
+
+
+def effective_weekly_value_sql(conn, alias: str = "s") -> str:
+    """The joined snapshot's EFFECTIVE weekly value (#836, spec 5.4): NULL for
+    a suppression-retired row, its stored `weekly_percent` otherwise. A
+    clamped held write and a genuine climb-back keep their values; no
+    percentage band is involved."""
+    retired = _weekly_retired_sql(conn, alias)
+    if retired is None:
+        return f"{alias}.weekly_percent"
+    return f"CASE WHEN {retired} THEN NULL ELSE {alias}.weekly_percent END"
+
+
+def weekly_join_unavailable_sql(conn, alias: str = "s") -> str:
+    """A five-hour milestone's effective weekly join is UNAVAILABLE (#836,
+    spec 5.4): the joined snapshot is absent — deleted, or the ``0`` sentinel
+    `trg_usage_snapshot_suppression` writes — or suppression-retired. The
+    shared predicate of the detail stamp and the dashboard's retired-join
+    signature leg, over a ``LEFT JOIN`` aliased ``alias``."""
+    retired = _weekly_retired_sql(conn, alias)
+    if retired is None:
+        return f"({alias}.id IS NULL)"
+    return f"({alias}.id IS NULL OR {retired})"
+
+
 #: The six `five_hour_milestones` columns every surface already published, plus
-#: the joined EFFECTIVE weekly value. Ordering is `captured_at_utc, id` — spec
-#: §5.2's merged-stream order, which post-credit threshold repeats depend on.
+#: the joined EFFECTIVE weekly value (`effective_weekly_value_sql`, filled in
+#: as ``{effective}``). Ordering is `captured_at_utc, id` — spec §5.2's
+#: merged-stream order, which post-credit threshold repeats depend on.
 _FIVE_HOUR_MILESTONE_SQL = """
     SELECT m.percent_threshold, m.captured_at_utc, m.block_cost_usd,
            m.marginal_cost_usd, m.seven_day_pct_at_crossing, m.reset_event_id,
-           s.weekly_percent AS effective_seven_day_pct_at_crossing
+           {effective} AS effective_seven_day_pct_at_crossing
       FROM five_hour_milestones m
       LEFT JOIN weekly_usage_snapshots s ON s.id = m.usage_snapshot_id
      WHERE {selector}
@@ -1139,6 +1185,12 @@ def _load_five_hour_milestones(
     store is corrected by `db rederive`'s reviewed `retract`. A missing joined
     snapshot still publishes None and never falls back to the raw value.
 
+    **A suppression-retired snapshot publishes None** (#836, spec 5.4). The
+    fold rejected its weekly value, and the cleanup kept the row only for its
+    five-hour evidence; its provenance is exact (no held-write marker on a
+    held row), so this is not the withdrawn band. See
+    `effective_weekly_value_sql`.
+
     SELECTOR. Exactly one of `block_id` or `five_hour_window_key` must be given.
     `block_id` is the precise form — `five_hour_milestones.block_id` names one
     block outright. The pair form filters on the window key AND the account,
@@ -1166,7 +1218,9 @@ def _load_five_hour_milestones(
             selector += " AND m.account_key = ?"
             params += (account_key,)
     rows = conn.execute(
-        _FIVE_HOUR_MILESTONE_SQL.format(selector=selector), params,
+        _FIVE_HOUR_MILESTONE_SQL.format(
+            selector=selector,
+            effective=effective_weekly_value_sql(conn, "s")), params,
     ).fetchall()
     out: list[dict] = []
     for r in rows:
@@ -1981,60 +2035,76 @@ def project_open_block_end(
         ),
     )
     # Replace-all children, keyed on the window (not block_id) so an orphan
-    # child of an earlier parent rebuild is cleaned up as well.
+    # child of an earlier parent rebuild is cleaned up as well. An identical
+    # stored set is left in place (#1050): a DELETE and re-INSERT of the same
+    # rows would advance the content revision with nothing changed.
     block_id = int(current["id"])
-    conn.execute(
-        "DELETE FROM five_hour_block_models "
-        "WHERE five_hour_window_key = ? AND account_key = ?",
-        (window_key, account_key),
-    )
-    if totals.get("by_model"):
-        conn.executemany(
-            """
-            INSERT INTO five_hour_block_models (
-              block_id, five_hour_window_key, model,
-              input_tokens, output_tokens,
-              cache_create_tokens, cache_read_tokens,
-              cost_usd, entry_count, account_key
-            )
-            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-            """,
-            [
-                (
-                    block_id, window_key, model,
-                    b["input_tokens"], b["output_tokens"],
-                    b["cache_create_tokens"], b["cache_read_tokens"],
-                    b["cost_usd"], b["entry_count"], account_key,
-                )
-                for model, b in totals["by_model"].items()
-            ],
+    model_rows = _open_block_child_rows(
+        block_id, window_key, account_key, "model", totals.get("by_model"))
+    if not _lib_stats_content_revision.child_set_unchanged(
+            conn, "five_hour_block_models", five_hour_window_key=window_key,
+            account_key=account_key, replacement=model_rows):
+        conn.execute(
+            "DELETE FROM five_hour_block_models "
+            "WHERE five_hour_window_key = ? AND account_key = ?",
+            (window_key, account_key),
         )
-    conn.execute(
-        "DELETE FROM five_hour_block_projects "
-        "WHERE five_hour_window_key = ? AND account_key = ?",
-        (window_key, account_key),
-    )
-    if totals.get("by_project"):
-        conn.executemany(
-            """
-            INSERT INTO five_hour_block_projects (
-              block_id, five_hour_window_key, project_path,
-              input_tokens, output_tokens,
-              cache_create_tokens, cache_read_tokens,
-              cost_usd, entry_count, account_key
-            )
-            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-            """,
-            [
-                (
-                    block_id, window_key, project_path,
-                    b["input_tokens"], b["output_tokens"],
-                    b["cache_create_tokens"], b["cache_read_tokens"],
-                    b["cost_usd"], b["entry_count"], account_key,
+        if model_rows:
+            conn.executemany(
+                """
+                INSERT INTO five_hour_block_models (
+                  block_id, five_hour_window_key, model,
+                  input_tokens, output_tokens,
+                  cache_create_tokens, cache_read_tokens,
+                  cost_usd, entry_count, account_key
                 )
-                for project_path, b in totals["by_project"].items()
-            ],
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                [tuple(row.values()) for row in model_rows],
+            )
+    project_rows = _open_block_child_rows(
+        block_id, window_key, account_key, "project_path",
+        totals.get("by_project"))
+    if not _lib_stats_content_revision.child_set_unchanged(
+            conn, "five_hour_block_projects", five_hour_window_key=window_key,
+            account_key=account_key, replacement=project_rows):
+        conn.execute(
+            "DELETE FROM five_hour_block_projects "
+            "WHERE five_hour_window_key = ? AND account_key = ?",
+            (window_key, account_key),
         )
+        if project_rows:
+            conn.executemany(
+                """
+                INSERT INTO five_hour_block_projects (
+                  block_id, five_hour_window_key, project_path,
+                  input_tokens, output_tokens,
+                  cache_create_tokens, cache_read_tokens,
+                  cost_usd, entry_count, account_key
+                )
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                [tuple(row.values()) for row in project_rows],
+            )
+
+
+def _open_block_child_rows(block_id, window_key, account_key, label,
+                           breakdown) -> "list[dict]":
+    """One open block's child rows from a `_compute_block_totals` breakdown,
+    as column → value mappings in the INSERT's column order."""
+    return [
+        {
+            "block_id": block_id, "five_hour_window_key": window_key,
+            label: name,
+            "input_tokens": b["input_tokens"],
+            "output_tokens": b["output_tokens"],
+            "cache_create_tokens": b["cache_create_tokens"],
+            "cache_read_tokens": b["cache_read_tokens"],
+            "cost_usd": b["cost_usd"], "entry_count": b["entry_count"],
+            "account_key": account_key,
+        }
+        for name, b in (breakdown or {}).items()
+    ]
 
 
 def _materialize_open_candidate(conn, key, acct, start_row) -> int:

package/bin/_cctally_forecast.py

@@ -52,6 +52,12 @@ from _cctally_core import (
     _BudgetConfigError, _get_budget_config,
     BUDGET_PERIODS as _CCTALLY_BUDGET_PERIODS,
 )
+# #836: the decorated Current Week's owner and cycle identity read the reset
+# chokepoint and the held-column guard directly; neither is ns-patched.
+from _cctally_core import (
+    _canonicalize_optional_iso, _latest_reset_event_for_end,
+    weekly_held_exclusion,
+)
 
 import importlib.util as _ilu
 
@@ -129,15 +135,19 @@ def _resolve_forecast_now(as_of: str | None) -> dt.datetime:
 
 
 def _shape_week_samples(rows, *, include_held: bool,
-                        include_account: bool = False) -> list:
+                        include_account: bool = False,
+                        include_journal_id: bool = False) -> list:
     """Turn snapshot rows into the sample tuples `_fetch_current_week_snapshots`
     returns. Both of that function's row-fetch legs go through here so the two
     cannot drift on the tuple width.
 
     `rows` are `(captured_at_utc, weekly_percent, five_hour_percent,
-    weekly_observation_held[, account_key])`. The held flag is appended only
-    for a held-inclusive read, and the account only for an explicit identity
-    read. Existing consumers keep the historical three- or four-field shape.
+    weekly_observation_held[, account_key][, journal_id])`. The held flag is
+    appended only for a held-inclusive read, the account only for an explicit
+    identity read, and the row's `journal_id` (#1018 twin spec 5.3: the
+    displayed row's originating observation) only when asked for, after
+    every other field. Existing consumers keep the historical three- or
+    four-field shape.
     """
     out = []
     for row in rows:
@@ -150,6 +160,8 @@ def _shape_week_samples(rows, *, include_held: bool,
             sample = sample + (int(row[3] or 0),)
         if include_account:
             sample = sample + (row[4],)
+        if include_journal_id:
+            sample = sample + (row[5 if include_account else 4],)
         out.append(sample)
     return out
 
@@ -177,7 +189,8 @@ def _fetch_current_week_snapshots(conn: sqlite3.Connection, now_utc: dt.datetime
                                   *, account_key: "str | None" = None,
                                   include_held: bool = False,
                                   include_account: bool = False,
-                                  include_scope: bool = False):
+                                  include_scope: bool = False,
+                                  include_journal_id: bool = False):
     """Return (week_start_at, week_end_at, list[(captured_at, percent, five_hr)])
     for the subscription week containing `now_utc`, or None if no snapshot
     exists for the current week.
@@ -235,6 +248,12 @@ def _fetch_current_week_snapshots(conn: sqlite3.Connection, now_utc: dt.datetime
     reading the five-hour axis selects its reading under exactly this scope
     rather than from the newest sample, which a retired replica or a
     weekly-only reading leaves without a five-hour value.
+
+    ``include_journal_id`` (#1018 twin spec 5.3) appends each row's
+    `journal_id` as the LAST sample field, after the held flag and the
+    account, so the Current Week card can resolve its displayed row's
+    originating observation. Every other caller keeps its tuple width, and
+    the trailing SQL row id ordering is unchanged.
     """
     # #341: optional account scoping — same predicate on every leg so the whole
     # window resolution stays consistent (a real key or the `unattributed`
@@ -248,6 +267,8 @@ def _fetch_current_week_snapshots(conn: sqlite3.Connection, now_utc: dt.datetime
     # The TUI's multi-account card needs the physical owner of the sample it
     # actually displays. Keep the historical sample shape for every other read.
     _owner_column = ", account_key" if include_account else ""
+    if include_journal_id:
+        _owner_column += ", journal_id"
     _sample_order = " ASC, id ASC" if include_account else " ASC"
     candidates = conn.execute(
         "SELECT week_start_at, week_end_at, week_start_date, MAX(captured_at_utc) AS latest_cap "
@@ -304,7 +325,8 @@ def _fetch_current_week_snapshots(conn: sqlite3.Connection, now_utc: dt.datetime
             (drow[0],) + _acct_p,
         ).fetchall()
         samples = _shape_week_samples(rows, include_held=include_held,
-                                      include_account=include_account)
+                                      include_account=include_account,
+                                      include_journal_id=include_journal_id)
         samples = [s for s in samples if s[0] <= now_utc]
         if include_scope:
             return week_start_at, week_end_at, samples, (drow[0], None)
@@ -337,7 +359,8 @@ def _fetch_current_week_snapshots(conn: sqlite3.Connection, now_utc: dt.datetime
         tuple(matching_texts) + (chosen_date,) + _acct_p,
     ), by_id=include_account)
     samples = _shape_week_samples(rows, include_held=include_held,
-                                  include_account=include_account)
+                                  include_account=include_account,
+                                  include_journal_id=include_journal_id)
     samples = [s for s in samples if s[0] <= now_utc]
     if include_scope:
         return (week_start_at, week_end_at, samples,
@@ -389,6 +412,277 @@ def _apply_midweek_reset_override(
     return week_start_at, samples
 
 
+# === #836: the decorated Current Week — one owner, one cycle identity =======
+#
+# On a store with more than one REAL Claude account (`provider_is_decorated`)
+# the Current Week card, its weekly milestones and the history index's current
+# entry describe ONE account: the owner of the newest non-held weekly sample at
+# the build's as-of instant (#839's contract, spec 5.2). The merged reads above
+# stay unchanged for every undecorated store and every other caller.
+
+#: Every subscription window that can contain an instant starts no more than
+#: seven days (plus host-offset slack on `week_start_date`) before it, so this
+#: leading `week_start_date` bound keeps every candidate read an
+#: `idx_usage_week_time` range rather than a scan of the whole history.
+_CLAUDE_CYCLE_CANDIDATE_DAYS = 8
+
+
+@dataclass(frozen=True)
+class ClaudeCycleScope:
+    """The decorated Current Week's cycle identity (#836, spec 5.2 step 2).
+
+    Resolved once per build by `_claude_current_cycle_scope` and shared by the
+    card, the weekly milestones and the scoped history index, so the three
+    readers of one cycle cannot choose it differently.
+
+    ``account_key``: the owner. ``as_of_utc``: the build instant (ISO-8601
+    ``Z``); reset events are admitted only at or before it.
+    ``week_start_date``: the storage key milestones are recorded under.
+    ``week_start_at``: the owner's stored boundary text (``None`` on the
+    date-only leg). ``week_end_at``: the canonical end
+    (`_canonicalize_optional_iso`, the `week_reset_events.new_week_end_at`
+    form; ``None`` on the date-only leg). ``effective_start_at``: the week
+    start, or the active reset's effective instant when later (ISO-8601 ``Z``;
+    ``None`` on the date-only leg). ``reset_event_id``: the active reset's id
+    (the milestone segment), ``0`` when none.
+    """
+    account_key: str
+    as_of_utc: str
+    week_start_date: str
+    week_start_at: "str | None"
+    week_end_at: "str | None"
+    effective_start_at: "str | None"
+    reset_event_id: int
+
+
+def _claude_newest_weekly_sample(conn, now_utc: dt.datetime, *,
+                                 account_key: "str | None" = None):
+    """The newest non-held weekly sample captured at or before ``now_utc``
+    among windows containing it, or ``None`` (#836, spec 5.2 step 1).
+
+    Only non-held rows take part, so a newer held row of another account (a
+    copy of an older weekly value under a newer capture) never chooses the
+    window — the defect of the held-inclusive ``MAX(captured_at_utc)`` window
+    choice in `_fetch_current_week_snapshots` (spec D-C). Captures after
+    ``now_utc`` never participate. Boundaryful windows
+    (``[week_start_at, week_end_at)`` containing ``now_utc``) are preferred;
+    when none qualifies, the date-only leg (``week_start_date`` .. 
+    ``week_end_date`` containing today's host-local date) applies, as in
+    `_fetch_current_week_snapshots`. Ties break by ``(captured_at_utc, id)``.
+
+    Returns a dict of the row's identity and boundary columns plus
+    ``boundaryful``: whether the CHOSEN row carries both parseable bounds,
+    never which pool it came from. On the window's end date, after its reset
+    instant and before any next-window sample, a bounded row reaches the
+    date-only pool; its scope is still built from its own bounds, so the
+    account's own reset stays in effect (#836 review F1).
+    """
+    floor_date = (now_utc.astimezone(dt.timezone.utc).date()
+                  - dt.timedelta(days=_CLAUDE_CYCLE_CANDIDATE_DAYS)).isoformat()
+    acct_pred = "" if account_key is None else " AND account_key = ?"
+    acct_p: tuple = () if account_key is None else (account_key,)
+    rows = conn.execute(
+        "SELECT id, account_key, week_start_date, week_end_date, "
+        "       week_start_at, week_end_at, captured_at_utc "
+        "FROM weekly_usage_snapshots "
+        "WHERE week_start_date >= ?" + acct_pred
+        + weekly_held_exclusion(conn),
+        (floor_date,) + acct_p,
+    ).fetchall()
+    # internal fallback: host-local intentional (the date-only leg's day,
+    # matching `_fetch_current_week_snapshots`)
+    today_local = now_utc.astimezone().date().isoformat()
+    boundaryful = []
+    date_only = []
+    for r in rows:
+        try:
+            cap = parse_iso_datetime(r[6], "captured_at_utc")
+        except (TypeError, ValueError):
+            continue
+        if cap > now_utc:
+            continue
+        rank = (cap, int(r[0]))
+        try:
+            ws = parse_iso_datetime(r[4], "week_start_at") if r[4] else None
+            we = parse_iso_datetime(r[5], "week_end_at") if r[5] else None
+        except ValueError:
+            ws = we = None
+        bounded = ws is not None and we is not None
+        if bounded and ws <= now_utc < we:
+            boundaryful.append((rank, r, True))
+        elif (r[2] is not None and r[3] is not None
+              and r[2] <= today_local <= r[3]):
+            date_only.append((rank, r, bounded))
+    pool = boundaryful or date_only
+    if not pool:
+        return None
+    _rank, r, bounded = max(pool, key=lambda item: item[0])
+    return {
+        "id": int(r[0]),
+        "account_key": r[1],
+        "week_start_date": r[2],
+        "week_end_date": r[3],
+        "week_start_at": r[4],
+        "week_end_at": r[5],
+        "captured_at_utc": r[6],
+        "boundaryful": bounded,
+    }
+
+
+def _claude_select_current_owner(conn, now_utc: dt.datetime) -> "str | None":
+    """The displayed account: the owner of the newest non-held weekly sample
+    at ``now_utc`` (#836, spec 5.2 step 1), or ``None`` when there is none."""
+    sample = _claude_newest_weekly_sample(conn, now_utc)
+    return None if sample is None else sample["account_key"]
+
+
+def _claude_current_cycle_scope(conn, now_utc: dt.datetime, *,
+                                account_key: str) -> "ClaudeCycleScope | None":
+    """``account_key``'s current cycle identity at ``now_utc`` (#836, spec 5.2
+    step 2), or ``None`` when the account has no eligible non-held sample.
+
+    The window is the one holding the account's newest eligible non-held
+    sample. The active reset is `_latest_reset_event_for_end` for the
+    canonical end, scoped to the account and admitted only at or before
+    ``now_utc`` — the #750 S3 chokepoint's effective-instant order — so another
+    account's credit never re-anchors this cycle (spec D-A) and a reset that
+    takes effect later does not cut it yet. The effective start is that
+    reset's instant exactly when the history index cuts the account's storage
+    bucket there (`_claude_reset_cuts_cycle`, the one rule both use) — which
+    can be EARLIER than the nominal week start after a same-date early
+    re-anchor (#836 review F7). The date-only leg has no end text, so it
+    carries no reset.
+    """
+    sample = _claude_newest_weekly_sample(conn, now_utc, account_key=account_key)
+    if sample is None:
+        return None
+    as_of = _iso_z(now_utc)
+    if not sample["boundaryful"]:
+        return ClaudeCycleScope(
+            account_key=account_key, as_of_utc=as_of,
+            week_start_date=sample["week_start_date"],
+            week_start_at=None, week_end_at=None, effective_start_at=None,
+            reset_event_id=0)
+    week_start = parse_iso_datetime(sample["week_start_at"], "week_start_at")
+    canon_end = _canonicalize_optional_iso(sample["week_end_at"],
+                                           "claude.cycle.end")
+    effective_start = week_start
+    reset_event_id = 0
+    if canon_end:
+        event = _latest_reset_event_for_end(
+            conn, canon_end, account_key=account_key, as_of_utc=as_of)
+        if event is not None:
+            reset_event_id = int(event["id"])
+            if event["effective_reset_at_utc"]:
+                try:
+                    reset_dt = parse_iso_datetime(
+                        event["effective_reset_at_utc"], "reset_event.effective")
+                except ValueError:
+                    reset_dt = None
+                if reset_dt is not None:
+                    import _cctally_milestone_history as _mhist
+                    outer = _mhist._claude_storage_boundaries(
+                        conn, sample["week_start_date"],
+                        account_key=account_key)
+                    if _mhist._claude_reset_cuts_cycle(outer, reset_dt):
+                        effective_start = reset_dt
+    return ClaudeCycleScope(
+        account_key=account_key, as_of_utc=as_of,
+        week_start_date=sample["week_start_date"],
+        week_start_at=sample["week_start_at"],
+        week_end_at=canon_end,
+        effective_start_at=_iso_z(effective_start),
+        reset_event_id=reset_event_id)
+
+
+def _claude_cycle_scope_samples(conn, scope: ClaudeCycleScope,
+                                now_utc: dt.datetime, *,
+                                include_journal_id: bool = False):
+    """The decorated card's held-inclusive samples for ``scope`` (#836).
+
+    The shape of ``_fetch_current_week_snapshots(include_held=True,
+    include_account=True, include_scope=True)`` — ``(week_start_at,
+    week_end_at, samples, week_scope)`` — restricted to the scope's account and
+    window, so the card reads the window its owner was chosen in rather than
+    one `_fetch_current_week_snapshots` would choose by its held-inclusive
+    ``MAX(captured_at_utc)``. ``week_start_at`` is the NOMINAL start; the
+    caller filters from ``scope.effective_start_at``. Samples are filtered to
+    ``captured_at <= now_utc``. Returns ``None`` when the window cannot be
+    resolved. ``include_journal_id`` appends each row's `journal_id` as the
+    last sample field (#1018 twin spec 5.3).
+    """
+    _jid = ", journal_id" if include_journal_id else ""
+    floor_date = (now_utc.astimezone(dt.timezone.utc).date()
+                  - dt.timedelta(days=_CLAUDE_CYCLE_CANDIDATE_DAYS)).isoformat()
+    if scope.week_start_at is None:
+        drow = conn.execute(
+            "SELECT week_end_date FROM weekly_usage_snapshots "
+            "WHERE week_start_date = ? AND account_key = ? "
+            "AND week_end_date IS NOT NULL "
+            "ORDER BY captured_at_utc DESC, id DESC LIMIT 1",
+            (scope.week_start_date, scope.account_key),
+        ).fetchone()
+        if drow is None:
+            return None
+        # internal fallback: host-local intentional (the date-only leg)
+        local_tz = dt.datetime.now().astimezone().tzinfo
+        ws_date = dt.date.fromisoformat(scope.week_start_date)
+        we_date = dt.date.fromisoformat(drow[0])
+        week_start_at = dt.datetime.combine(
+            ws_date, dt.time(0, 0), local_tz).astimezone(dt.timezone.utc)
+        week_end_at = dt.datetime.combine(
+            we_date + dt.timedelta(days=1), dt.time(0, 0),
+            local_tz).astimezone(dt.timezone.utc)
+        rows = conn.execute(
+            "SELECT captured_at_utc, weekly_percent, five_hour_percent, "
+            "       weekly_observation_held, account_key" + _jid + " "
+            "FROM weekly_usage_snapshots "
+            "WHERE week_start_date = ? AND account_key = ? "
+            "ORDER BY captured_at_utc ASC, id ASC",
+            (scope.week_start_date, scope.account_key),
+        ).fetchall()
+        samples = _shape_week_samples(rows, include_held=True,
+                                      include_account=True,
+                                      include_journal_id=include_journal_id)
+        samples = [s for s in samples if s[0] <= now_utc]
+        return (week_start_at, week_end_at, samples,
+                (scope.week_start_date, None))
+    week_start_at = parse_iso_datetime(scope.week_start_at, "week_start_at")
+    week_end_at = parse_iso_datetime(scope.week_end_at, "week_end_at")
+    # Every textual spelling of the same start instant, as the merged read
+    # gathers them for an upgrade-in-progress window.
+    matching_texts: list[str] = []
+    for (text,) in conn.execute(
+            "SELECT DISTINCT week_start_at FROM weekly_usage_snapshots "
+            "WHERE week_start_date >= ? AND account_key = ? "
+            "AND week_start_at IS NOT NULL AND week_end_at IS NOT NULL",
+            (floor_date, scope.account_key)).fetchall():
+        try:
+            if parse_iso_datetime(text, "week_start_at") == week_start_at:
+                matching_texts.append(text)
+        except ValueError:
+            continue
+    if scope.week_start_at not in matching_texts:
+        matching_texts.append(scope.week_start_at)
+    matching_texts.sort()
+    placeholders = ",".join("?" * len(matching_texts))
+    rows = _week_rows_by_capture(conn.execute(
+        f"SELECT captured_at_utc, weekly_percent, five_hour_percent, "
+        f"       weekly_observation_held, account_key{_jid}, id "
+        f"FROM weekly_usage_snapshots "
+        f"WHERE (week_start_at IN ({placeholders}) "
+        f"       OR (week_start_at IS NULL AND week_start_date = ?)) "
+        f"  AND account_key = ?",
+        tuple(matching_texts) + (scope.week_start_date, scope.account_key),
+    ), by_id=True)
+    samples = _shape_week_samples(rows, include_held=True,
+                                  include_account=True,
+                                  include_journal_id=include_journal_id)
+    samples = [s for s in samples if s[0] <= now_utc]
+    return (week_start_at, week_end_at, samples,
+            (scope.week_start_date, tuple(matching_texts)))
+
+
 def _current_week_five_hour_percent(conn, now_utc, week_scope, *,
                                     account_key, week_start_at,
                                     week_start_before_override):