cctally 1.105.0 → 1.106.0

package/bin/_cctally_dashboard_envelope.py

@@ -1326,6 +1326,30 @@ def _forecast_quota_envelope(fc, cw, rate_change):
     }
 
 
+def _trend_withheld_key(row) -> dict:
+    """The `dollar_per_pct_withheld` key for one trend row, or no key at all.
+
+    #703 + #707 §6.3. `build_trend_view` resolves the cause per week, and both
+    trend arrays feed a `$/1%` column — ``weeks`` the panel's, ``history`` the
+    modal's. Without the cause the column renders the em-dash that reads as "no
+    usage recorded", which is a different and wrong statement about a week that
+    holds a credit.
+
+    The key is OMITTED rather than published as null when nothing is withheld,
+    the way the session rows' ``title`` key is. The client's
+    ``withheldDollarPerPctLabel`` treats an absent key and a null one
+    identically, a week that withholds nothing is the overwhelming majority,
+    and publishing the null on all twenty rows of the two arrays would move
+    every committed dashboard golden and the corpus-wide envelope oracle to
+    carry a value no consumer can distinguish from its absence.
+
+    ``getattr`` tolerates the minimal trend shapes — SimpleNamespace test rows,
+    older fixtures — that the sibling ``cost_usd`` key already tolerates.
+    """
+    cause = getattr(row, "dpp_withheld_cause", None)
+    return {} if cause is None else {"dollar_per_pct_withheld": cause}
+
+
 def _header_rate_and_delta(current_rate, current_week_start, trend):
     """`(dollar_per_pct, vs_last_week_delta)` from ONE current operand.
 
@@ -1595,22 +1619,39 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
     week_lbl: "str | None" = None
     reset_at_utc: "dt.datetime | None" = None
     week_start_at_utc: "dt.datetime | None" = None
+    nominal_week_start_at_utc: "dt.datetime | None" = None
     if cw is not None:
         ws = getattr(cw, "week_start_at", None)
         we = getattr(cw, "week_end_at", None)
+        # #703 + #707 §6.1/§6.4 — the LABEL names the week, not the credit.
+        # `week_start_at` is the rate anchor and moves to the credit instant on
+        # a credited week, which is intended for the `$/1%` numerator and wrong
+        # for the window a person is shown: a credit moves no boundary.
+        # Labelling from it made the hero read `WEEK USAGE · Apr 16–Apr 20` over
+        # a week running Apr 13–Apr 20, over milestone rows dated before Apr 16,
+        # and against the credit tooltip's own promise that the week keeps its
+        # own boundaries.
+        #
+        # `displayed_week_start_at` falls back to the rate anchor, so legacy and
+        # fixture snapshots that construct `TuiCurrentWeek` without the field
+        # render exactly what they rendered before.
+        from _lib_view_models import displayed_week_start_at
+        ws_label = displayed_week_start_at(cw)
         # Full window "Apr 13–20" so the dashboard matches the TUI/report
         # headers and doesn't hide month crossings (e.g. "Apr 27–May 03").
         # En-dash U+2013 matches the TUI format at cmd_tui.
-        if ws is not None and we is not None:
+        if ws_label is not None and we is not None:
             week_lbl = (
-                f"{format_display_dt(ws, resolved_tz_obj, fmt='%b %d', suffix=False)}"
+                f"{format_display_dt(ws_label, resolved_tz_obj, fmt='%b %d', suffix=False)}"
                 f"–"
                 f"{format_display_dt(we, resolved_tz_obj, fmt='%b %d', suffix=False)}"
             )
-        elif ws is not None:
-            week_lbl = format_display_dt(ws, resolved_tz_obj, fmt='%b %d', suffix=False)
+        elif ws_label is not None:
+            week_lbl = format_display_dt(
+                ws_label, resolved_tz_obj, fmt='%b %d', suffix=False)
         reset_at_utc = we
         week_start_at_utc = ws
+        nominal_week_start_at_utc = ws_label
 
     # Header forecast_pct should match the projection that drove the
     # verdict pill next to it. The View (issue #57) carries the
@@ -1648,6 +1689,13 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
             "models":                 list(r.models),
             "week_start_at":          r.week_start_at,
             "week_end_at":            r.week_end_at,
+            # #703 + #707 §6.4/§6.6: additive, so no `schemaVersion` bump. The
+            # week no longer splits, so `credited` is what explains a low
+            # percent late in a heavy week; the withheld cause distinguishes
+            # "the epoch supports no divisor" from "no usage recorded", which a
+            # bare null cannot.
+            "credited":               r.credited,
+            "dollar_per_pct_withheld": r.dollar_per_pct_withheld_cause,
         }
 
     def _monthly_row_to_dict(r: "MonthlyPeriodRow") -> dict:
@@ -2045,13 +2093,32 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
                 # serializing, the same way `five_hour_block` does.
                 "total_tokens":             getattr(cw, "total_tokens", 0),
                 "dollar_per_pct":           cw.dollars_per_percent,
-                # #556 S1 §3.5 — the effective cycle start, the companion of
-                # the already-published `reset_at_utc` end. Composition needs
-                # BOTH bounds to label the Claude leg's period, and the source
-                # version needs them to detect a nominal rollover (§3.6).
-                # Effective, not nominal: `_tui_build_current_week` stores this
-                # AFTER `_apply_midweek_reset_override`.
+                # #703 + #707 §6.3 — why the ratio above is null on a credited
+                # week. Additive and optional, the same shape the weekly rows
+                # publish, so the two surfaces on one screen state one cause.
+                # Without it the hero rendered `$0.000` beside `spent $0.00`,
+                # which is the misleading figure the withholding rule exists to
+                # replace. `getattr` keeps legacy fixture modules that construct
+                # `TuiCurrentWeek` without the field serializing.
+                "dollar_per_pct_withheld":  getattr(
+                    cw, "dpp_withheld_cause", None),
+                # #556 S1 §3.5/§3.6 — the RATE cycle start, the companion of
+                # the already-published `reset_at_utc` end.
+                # `_tui_build_current_week` stores this AFTER
+                # `_apply_midweek_reset_override`, so on a credited week it is
+                # the credit instant. The source version detects a nominal
+                # rollover from it (§3.6), and the Projects panel and its drill
+                # anchor their grid on it (#620).
                 "week_start_at":            _iso_z(week_start_at_utc),
+                # #703 + #707 §6.2 — the week's OWN start, which is the range
+                # `spent_usd` above covers. Published because composition labels
+                # the Claude leg's period over exactly the spend that leg
+                # reports, and `week_start_at` stopped being that bound when
+                # spend moved back to the full week: a leg built from it named a
+                # four-day window `Claude subscription week` and reported a full
+                # week's spend inside it. Additive and optional, so an older
+                # client and an older reader both keep working.
+                "nominal_week_start_at":    _iso_z(nominal_week_start_at_utc),
                 "reset_at_utc":             _iso_z(reset_at_utc),
                 "reset_in_sec":
                     None if reset_at_utc is None
@@ -2137,6 +2204,7 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
                         # that predate this nullable field. ``None`` when the
                         # week has no cost snapshot.
                         "cost_usd":       round(_wc, 4) if (_wc := getattr(w, "weekly_cost_usd", None)) is not None else None,
+                        **_trend_withheld_key(w),
                     }
                     for w in snap.trend
                 ],
@@ -2151,6 +2219,7 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
                         # #264 S3: additive weekly cost (see weeks[] above; same
                         # getattr tolerance for minimal/older trend shapes).
                         "cost_usd":       round(_wc, 4) if (_wc := getattr(w, "weekly_cost_usd", None)) is not None else None,
+                        **_trend_withheld_key(w),
                     }
                     for w in (snap.weekly_history or [])
                 ],

package/bin/_cctally_dashboard_share.py

@@ -720,7 +720,13 @@ def _build_current_week_share_panel_data(options: dict,
             "week_start_date":    _share_now_utc().strftime("%Y-%m-%d"),
             "display_tz":         options.get("display_tz", "Etc/UTC"),
         }
-    week_start = getattr(cw, "week_start_at", None)
+    # #703 + #707 §6.2 — the week's OWN start, not the rate anchor. It dates
+    # this card, clips `daily_progression`, and bounds `top_projects`, and all
+    # three describe `kpi_cost_usd`, which is the whole week's spend. Anchoring
+    # them at a credit instant would date the card at the credit while reporting
+    # the week's money, and would decompose that money over part of its range.
+    from _lib_view_models import displayed_week_start_at
+    week_start = displayed_week_start_at(cw)
     week_end = getattr(cw, "week_end_at", None)
     week_start_date = (
         week_start.strftime("%Y-%m-%d") if isinstance(week_start, dt.datetime)

package/bin/_cctally_db.py

@@ -190,6 +190,132 @@ def add_column_if_missing(
     return True
 
 
+# --------------------------------------------------------------------------
+# week_reset_events reshape for the unified credit record (#703 + #707)
+# --------------------------------------------------------------------------
+#
+# The unified credit record changed `week_reset_events` in three ways that
+# `CREATE TABLE IF NOT EXISTS` cannot deliver to a store whose table already
+# exists: six fact columns were added, both boundary columns became nullable,
+# and the row constraint moved from the boundary pair to
+# `(account_key, credit_key)`. Only a rename-recreate-copy applies all three.
+#
+# The epoch bump alone covers ONE of the two upgrade paths. A store above
+# `LEGACY_STATS_HEAD` defers to a rebuild that materializes a fresh scratch
+# index through the current DDL, so it arrives correct. A PRE-CUTOVER store at
+# `user_version <= 13` takes the other path: the schema apply is a no-op
+# against the table that is already there, the cutover stamps the new epoch in
+# place, and every later open fast-returns at the epoch gate before any schema
+# work runs. Without this reshape such a store REPORTS the current epoch while
+# missing every fact column and keeping both NOT NULL boundaries — a state with
+# no path back, in which the manual credit fold, the automatic fold and every
+# fact read raise.
+#
+# `add_column_if_missing` is not sufficient on its own, because it cannot relax
+# a NOT NULL constraint or replace a UNIQUE, and the manual fold inserts NULL
+# into both boundary columns.
+#
+# Split in two so the canonical DDL has exactly one copy — the one in
+# `_cctally_core.open_db`. `begin_week_reset_events_reshape` renames the legacy
+# table out of the way; the caller's own `CREATE TABLE IF NOT EXISTS` then
+# builds the current shape; `finish_week_reset_events_reshape` copies the rows
+# across and drops the legacy table. `sqlite_master.sql` for the recreated
+# table is therefore byte-identical to a freshly created one, which the rebuild
+# validator's schema fingerprint requires.
+
+#: Where the pre-reshape table is parked between the two halves. A leftover
+#: under this name means a previous attempt crashed after the rename; the next
+#: open resumes from it rather than starting over.
+WEEK_RESET_EVENTS_RESHAPE_OLD = "week_reset_events_pre_1012"
+
+#: Presence of these decides whether a reshape is needed. They arrived together
+#: with the nullability and constraint changes, so any store missing them is a
+#: store that predates all three.
+_WEEK_RESET_EVENTS_FACT_COLUMNS = frozenset({
+    "week_start_date", "observed_at_utc", "confirming_capture_at_utc",
+    "observed_post_credit_pct", "credit_key", "credit_order",
+})
+
+
+def _table_exists(conn: sqlite3.Connection, table: str) -> bool:
+    return conn.execute(
+        "SELECT 1 FROM sqlite_master WHERE type='table' AND name=?", (table,)
+    ).fetchone() is not None
+
+
+def begin_week_reset_events_reshape(conn: sqlite3.Connection) -> bool:
+    """Park a pre-#703 `week_reset_events` aside; return whether one is parked.
+
+    Returns True when the caller must call `finish_week_reset_events_reshape`
+    after creating the current-shape table — either because this call renamed a
+    legacy table, or because a previous attempt already did and crashed before
+    copying.
+    """
+    if _table_exists(conn, WEEK_RESET_EVENTS_RESHAPE_OLD):
+        return True
+    if not _table_exists(conn, "week_reset_events"):
+        return False
+    cols = {
+        str(r[1])
+        for r in conn.execute("PRAGMA table_info(week_reset_events)").fetchall()
+    }
+    if _WEEK_RESET_EVENTS_FACT_COLUMNS <= cols:
+        return False
+    conn.execute(
+        f"ALTER TABLE week_reset_events "
+        f"RENAME TO {WEEK_RESET_EVENTS_RESHAPE_OLD}"
+    )
+    return True
+
+
+def finish_week_reset_events_reshape(conn: sqlite3.Connection) -> None:
+    """Copy the parked rows into the current-shape table and drop the parked one.
+
+    `id` is copied explicitly. `percent_milestones.reset_event_id` names a
+    credit by that identifier and the foreign keys in this codebase are
+    documentation-only, so letting AUTOINCREMENT renumber the rows would
+    silently re-point every milestone at a different credit with nothing
+    raising.
+
+    Columns present only on the legacy table are dropped and columns present
+    only on the new one arrive NULL, which is the honest value: NULL on a fact
+    column means the row predates the change, exactly as it does for a legacy
+    `wr:` event replayed on the rebuild path.
+
+    The parked table's indexes followed it through the rename and still hold
+    the `idx_week_reset_events_*` names, so `DROP TABLE` here is what frees
+    those names for the caller's own `CREATE INDEX IF NOT EXISTS` to rebuild
+    them against the new table. Dropping them any later would leave the new
+    table unindexed while the statements that would have built them no-op.
+    """
+    if not _table_exists(conn, WEEK_RESET_EVENTS_RESHAPE_OLD):
+        return
+    old_cols = [
+        str(r[1])
+        for r in conn.execute(
+            f"PRAGMA table_info({WEEK_RESET_EVENTS_RESHAPE_OLD})").fetchall()
+    ]
+    new_cols = {
+        str(r[1])
+        for r in conn.execute("PRAGMA table_info(week_reset_events)").fetchall()
+    }
+    shared = [name for name in old_cols if name in new_cols]
+    projection = ", ".join(f'"{name}"' for name in shared)
+    if conn.in_transaction:
+        conn.commit()
+    conn.execute("BEGIN IMMEDIATE")
+    try:
+        conn.execute(
+            f"INSERT INTO week_reset_events ({projection}) "
+            f"SELECT {projection} FROM {WEEK_RESET_EVENTS_RESHAPE_OLD}"
+        )
+        conn.execute(f"DROP TABLE {WEEK_RESET_EVENTS_RESHAPE_OLD}")
+        conn.commit()
+    except Exception:
+        conn.rollback()
+        raise
+
+
 # === Region 2: Migration framework + dispatcher (was bin/cctally:10952-11229) ===
 
 _MIGRATION_NAME_RE = re.compile(r"^\d{3}_[a-z0-9_]+$")
@@ -3381,6 +3507,13 @@ def _migration_observed_pre_credit_pct(conn: sqlite3.Connection) -> None:
         switches from ``round(weekly_percent,1) = round(?,1)`` to
         ``ABS(weekly_percent - ?) < 1.0``.
 
+    That companion predicate is HISTORY, not current behaviour: #703 + #707
+    replaced the tolerance band with the evidence rules in
+    ``bin/_lib_credit_selection.py``, because the band compared the stored
+    percent against a remembered level rather than against evidence. The column
+    this migration adds is still written and still read; only the predicate that
+    consumed it changed.
+
     Idempotent: a second invocation finds the column already present
     and returns. Empty-column fast path: when the live CREATE TABLE
     already carries the column (fresh install), return without an ALTER
@@ -4206,10 +4339,18 @@ def _apply_codex_accounting_change_ledger(conn: sqlite3.Connection) -> None:
 class SchemaDeliveryObject(NamedTuple):
     """One re-derivable schema object declared by a version-gated apply.
 
-    ``kind`` is one of ``table``, ``view``, ``trigger`` or ``index``.  The two
-    store registries and their structural tests cover every explicit object of
-    those kinds, including virtual tables while excluding SQLite-created FTS
-    shadow objects.
+    ``kind`` is one of ``table``, ``view``, ``trigger``, ``index`` or
+    ``column``.  The two store registries and their structural tests cover
+    every explicit object of those kinds, including virtual tables while
+    excluding SQLite-created FTS shadow objects.
+
+    A ``column`` record is named ``<table>.<column>`` and covers exactly the
+    columns a schema apply declares with ``add_column_if_missing``.  Those
+    are the columns whose delivery depends on the version gate, because a
+    store created from scratch receives them from the CREATE TABLE body
+    instead.  #682 added two such declarations with no companion migration,
+    the head never moved, and every already-current store kept the old table
+    shape while the shipped code assumed the new one.
 
     ``ensure_helper`` names the shared module-level function that owns the DDL,
     or is ``None`` when the statement is written inline in the schema body.
@@ -4243,6 +4384,42 @@ class SchemaDeliveryObject(NamedTuple):
 #: identity so even a same-kind remove-one/add-one substitution fails.
 CACHE_REDERIVABLE_OBJECTS: "tuple[SchemaDeliveryObject, ...]" = (
     # ── frozen baseline: audited objects without handler-owned delivery DDL ──
+    # Columns predating this registry's column kind. Every one was verified
+    # present in a real production cache.db stamped at head 44, so the
+    # baseline is an observation rather than an assumption. Several arrived
+    # alongside a migration that backfilled their VALUES, but no handler owns
+    # the ALTER itself, so naming one here would fail the delivery assertion.
+    SchemaDeliveryObject("column", "codex_session_entries.account_key", None, None),
+    SchemaDeliveryObject("column", "codex_session_entries.conversation_key", None, None),
+    SchemaDeliveryObject("column", "codex_session_entries.source_root_key", None, None),
+    SchemaDeliveryObject("column", "codex_session_files.account_key", None, None),
+    SchemaDeliveryObject("column", "codex_session_files.last_conversation_key", None, None),
+    SchemaDeliveryObject("column", "codex_session_files.last_native_thread_id", None, None),
+    SchemaDeliveryObject("column", "codex_session_files.last_parent_thread_id", None, None),
+    SchemaDeliveryObject("column", "codex_session_files.last_root_thread_id", None, None),
+    SchemaDeliveryObject("column", "codex_session_files.last_turn_id", None, None),
+    SchemaDeliveryObject("column", "codex_session_files.source_root_key", None, None),
+    SchemaDeliveryObject("column", "conversation_messages.attribution_plugin", None, None),
+    SchemaDeliveryObject("column", "conversation_messages.attribution_skill", None, None),
+    SchemaDeliveryObject("column", "conversation_messages.search_thinking", None, None),
+    SchemaDeliveryObject("column", "conversation_messages.search_tool", None, None),
+    SchemaDeliveryObject("column", "conversation_messages.source_tool_use_id", None, None),
+    SchemaDeliveryObject("column", "conversation_messages.stop_reason", None, None),
+    SchemaDeliveryObject("column", "conversation_sessions.git_branch", None, None),
+    SchemaDeliveryObject("column", "conversation_sessions.models_json", None, None),
+    SchemaDeliveryObject("column", "conversation_sessions.title", None, None),
+    SchemaDeliveryObject("column", "quota_window_snapshots.account_key", None, None),
+    SchemaDeliveryObject("column", "quota_window_snapshots.canonical_resets_at_utc", None, None),
+    SchemaDeliveryObject("column", "quota_window_snapshots.observed_model", None, None),
+    SchemaDeliveryObject("column", "session_entries.account_key", None, None),
+    SchemaDeliveryObject("column", "session_entries.cache_create_1h_tokens", None, None),
+    SchemaDeliveryObject("column", "session_entries.cache_create_5m_tokens", None, None),
+    SchemaDeliveryObject("column", "session_entries.mutation_min_ts", None, None),
+    SchemaDeliveryObject("column", "session_entries.mutation_seq", None, None),
+    SchemaDeliveryObject("column", "session_entries.speed", None, None),
+    SchemaDeliveryObject("column", "session_files.account_key", None, None),
+    SchemaDeliveryObject("column", "session_files.project_path", None, None),
+    SchemaDeliveryObject("column", "session_files.session_id", None, None),
     SchemaDeliveryObject("index", "idx_codex_conv_msgs_conversation", None, None),
     SchemaDeliveryObject("index", "idx_codex_conv_msgs_source", None, None),
     SchemaDeliveryObject("index", "idx_codex_conv_rollups_recent", None, None),
@@ -4301,6 +4478,15 @@ CACHE_REDERIVABLE_OBJECTS: "tuple[SchemaDeliveryObject, ...]" = (
     SchemaDeliveryObject("trigger", "conv_title_fts_ai", None, None),
     SchemaDeliveryObject("trigger", "conv_title_fts_au", None, None),
     # ── post-baseline: each migration owns the object's delivery DDL ──
+    SchemaDeliveryObject(
+        "column", "codex_session_files.ingest_complete", None,
+        "038_codex_session_files_ingest_complete"),
+    SchemaDeliveryObject(
+        "column", "codex_conversation_rollups.render_revision", None,
+        "045_conversation_render_revision_columns"),
+    SchemaDeliveryObject(
+        "column", "conversation_sessions.render_revision", None,
+        "045_conversation_render_revision_columns"),
     SchemaDeliveryObject(
         "index", "idx_entries_physical", None,
         "020_session_entries_physical_unique"),
@@ -5368,6 +5554,22 @@ def _apply_codex_find_projection_schema(conn: sqlite3.Connection) -> None:
 #: projection is the one audited family with handler-owned delivery DDL.
 CONVERSATIONS_REDERIVABLE_OBJECTS: "tuple[SchemaDeliveryObject, ...]" = (
     # ── frozen baseline: audited objects without handler-owned delivery DDL ──
+    # Same column-kind baseline rule as the cache registry above. This store is
+    # projected from the cache schema, so most of these are the same physical
+    # declarations scoped to the tables conversations.db actually carries; all
+    # twelve were verified present in a real production conversations.db.
+    SchemaDeliveryObject("column", "codex_conversation_events.account_key", None, None),
+    SchemaDeliveryObject("column", "codex_conversation_messages.account_key", None, None),
+    SchemaDeliveryObject("column", "conversation_messages.account_key", None, None),
+    SchemaDeliveryObject("column", "conversation_messages.attribution_plugin", None, None),
+    SchemaDeliveryObject("column", "conversation_messages.attribution_skill", None, None),
+    SchemaDeliveryObject("column", "conversation_messages.search_thinking", None, None),
+    SchemaDeliveryObject("column", "conversation_messages.search_tool", None, None),
+    SchemaDeliveryObject("column", "conversation_messages.source_tool_use_id", None, None),
+    SchemaDeliveryObject("column", "conversation_messages.stop_reason", None, None),
+    SchemaDeliveryObject("column", "conversation_sessions.git_branch", None, None),
+    SchemaDeliveryObject("column", "conversation_sessions.models_json", None, None),
+    SchemaDeliveryObject("column", "conversation_sessions.title", None, None),
     SchemaDeliveryObject(
         "index", "idx_codex_conv_messages_account_conversation", None, None),
     SchemaDeliveryObject("index", "idx_codex_conv_msgs_conversation", None, None),
@@ -5411,7 +5613,13 @@ CONVERSATIONS_REDERIVABLE_OBJECTS: "tuple[SchemaDeliveryObject, ...]" = (
     SchemaDeliveryObject("trigger", "conv_title_fts_ad", None, None),
     SchemaDeliveryObject("trigger", "conv_title_fts_ai", None, None),
     SchemaDeliveryObject("trigger", "conv_title_fts_au", None, None),
-    # ── post-baseline: migration 004 owns the shared projection helper ──
+    # ── post-baseline: each migration owns the object's delivery DDL ──
+    SchemaDeliveryObject(
+        "column", "codex_conversation_rollups.render_revision", None,
+        "008_conversation_render_revision"),
+    SchemaDeliveryObject(
+        "column", "conversation_sessions.render_revision", None,
+        "008_conversation_render_revision"),
     SchemaDeliveryObject(
         "index", "idx_codex_find_projection_conversation_order",
         "_apply_codex_find_projection_schema", "004_codex_find_projection"),
@@ -8485,6 +8693,60 @@ def _044_codex_accounting_change_ledger(conn: sqlite3.Connection) -> None:
     conn.commit()
 
 
+@cache_migration("045_conversation_render_revision_columns")
+def _045_conversation_render_revision_columns(conn: sqlite3.Connection) -> None:
+    """Deliver #682's two ``render_revision`` columns to an existing store.
+
+    ``_apply_cache_schema`` already declares both columns with
+    ``add_column_if_missing``, so a store created from scratch has them. That
+    schema pass is VERSION-GATED though: ``open_cache_db`` runs it only when
+    ``PRAGMA user_version`` differs from ``len(_CACHE_MIGRATIONS)``. #682
+    shipped the two declarations with no companion migration, so the head never
+    moved, an already-current store never re-ran the apply, and the columns
+    reached new installs only. Registering here bumps the head, which is the
+    same mechanism migrations 029, 031 and 044 rely on and is stated there in
+    the same words.
+
+    The consequence on an unmigrated store was total rather than partial:
+    ``_recompute_conversation_sessions`` runs
+    ``UPDATE conversation_sessions SET render_revision=?`` on every sync, that
+    statement cannot be prepared against the old shape, and so every
+    ``sync_cache`` failed with ``no such column: render_revision`` while the
+    dashboard showed a permanent ``server sync error``.
+
+    No backfill is needed. ``render_revision`` is a monotonic invalidation
+    frontier whose whole purpose is to force re-assembly, and the DEFAULT 0 the
+    column arrives with is already the value that marks every existing row as
+    needing one. The rollup recompute chokepoints advance it from there.
+
+    Both tables are checked for existence first, because their absence is a
+    reachable state rather than a corrupt one: cache migration 028 removes
+    the legacy transcript objects, and ``open_cache_db`` recreates them only
+    afterwards. ``add_column_if_missing`` raises on a missing table, so an
+    unguarded ALTER here would turn that ordinary state into a migration
+    failure with a rendered error banner. Skipping is correct rather than
+    merely safe: a table created later is created by the schema apply, whose
+    CREATE TABLE body already carries the column.
+
+    The ``add_column_if_missing`` pair below is a defensive re-assert, not the
+    primary delivery path, exactly as migration 031 re-asserts its two tables:
+    it keeps the handler self-contained if the schema apply's ordering ever
+    drifts, it is what the per-migration golden exercises, and it is what
+    ``tests/test_cache_schema_delivery.py`` matches against this migration's
+    two registry records. Re-running is a no-op. NO self-stamp — the dispatcher
+    central-stamps on a clean return (#140).
+    """
+    if _table_exists(conn, "conversation_sessions"):
+        add_column_if_missing(
+            conn, "conversation_sessions", "render_revision",
+            "INTEGER NOT NULL DEFAULT 0")
+    if _table_exists(conn, "codex_conversation_rollups"):
+        add_column_if_missing(
+            conn, "codex_conversation_rollups", "render_revision",
+            "INTEGER NOT NULL DEFAULT 0")
+    conn.commit()
+
+
 # === Region 7d: Stats migration 008_recompute_weekly_cost_snapshots_dedup_fix ===
 
 @stats_migration("008_recompute_weekly_cost_snapshots_dedup_fix")

package/bin/_cctally_doctor.py

@@ -1399,31 +1399,56 @@ def _doctor_gather_state_impl(
                     # post_credit_milestone_count == 0.
                     # unixepoch() normalizes the cross-offset comparison.
                     try:
+                        # #703 + #707 §6.2: select by the canonical WEEK and the
+                        # ACCOUNT, not by `new_week_end_at`. A manual credit
+                        # leaves both boundary columns NULL, so the boundary
+                        # join found no snapshot and every `record-credit` week
+                        # was silently skipped by this check. The instant is the
+                        # accounting one, matching every other accounting read.
                         credit_rows = conn.execute(
                             """
                             SELECT wre.id AS event_id,
-                                   wre.new_week_end_at AS end_at,
-                                   wre.effective_reset_at_utc AS effective
+                                   wre.week_start_date AS week_start_date,
+                                   wre.account_key AS account_key,
+                                   wre.new_week_end_at AS end_at
                               FROM week_reset_events wre
-                             WHERE unixepoch(wre.effective_reset_at_utc)
+                             WHERE unixepoch(COALESCE(wre.observed_at_utc,
+                                                      wre.effective_reset_at_utc))
                                    <= unixepoch(?)
                             """,
                             (now_utc_iso(),),
                         ).fetchall()
                         credited_weeks = []
                         for cr in credit_rows:
-                            end_at = cr[1]
-                            evt_id = cr[0]
-                            latest = conn.execute(
-                                """
-                                SELECT week_start_date, weekly_percent
-                                  FROM weekly_usage_snapshots
-                                 WHERE week_end_at = ?
-                                 ORDER BY captured_at_utc DESC, id DESC
-                                 LIMIT 1
-                                """,
-                                (end_at,),
-                            ).fetchone()
+                            evt_id = cr["event_id"]
+                            # A row that predates `week_start_date` carries only
+                            # the boundary, so that join is the fallback for
+                            # exactly those rows and nothing else.
+                            if cr["week_start_date"]:
+                                latest = conn.execute(
+                                    """
+                                    SELECT week_start_date, weekly_percent
+                                      FROM weekly_usage_snapshots
+                                     WHERE week_start_date = ?
+                                       AND account_key = ?
+                                     ORDER BY captured_at_utc DESC, id DESC
+                                     LIMIT 1
+                                    """,
+                                    (cr["week_start_date"], cr["account_key"]),
+                                ).fetchone()
+                            elif cr["end_at"]:
+                                latest = conn.execute(
+                                    """
+                                    SELECT week_start_date, weekly_percent
+                                      FROM weekly_usage_snapshots
+                                     WHERE week_end_at = ?
+                                     ORDER BY captured_at_utc DESC, id DESC
+                                     LIMIT 1
+                                    """,
+                                    (cr["end_at"],),
+                                ).fetchone()
+                            else:
+                                latest = None
                             if latest is None or latest[0] is None:
                                 continue
                             ws = latest[0]

package/bin/_cctally_five_hour.py

@@ -351,13 +351,52 @@ def _load_recorded_five_hour_windows(
             # rendered as a phantom heuristic "~" row).
             credit_moments: list[dt.datetime] = []
             try:
+                # #703 + #707 §6.2: EVERY credit contributes a discontinuity
+                # moment, so the `old_week_end_at = effective_reset_at_utc`
+                # filter is gone. It selected only the automatic in-place shape,
+                # and a MANUAL credit leaves both boundary columns NULL — so a
+                # `record-credit` week produced no moment here at all and its
+                # overlapping canonical blocks still resolved by dropping one,
+                # leaving the phantom heuristic row this code exists to remove.
+                # The instant is the ACCOUNTING one, matching every other
+                # accounting read.
+                #
+                # This scan is account-BLIND, and deliberately stays so — but
+                # not for the reason first recorded here. That reason said no
+                # caller holds an account key, and it is false: the statusline
+                # resolves `_statusline_active_account()` and scopes its 7d
+                # clamp legs to it in the same render, then calls this function
+                # without one. The decision stands on the other two grounds. The
+                # canonical-block query above is account-blind, and so are the
+                # session entries these moments disambiguate, because `blocks`
+                # is a ccusage drop-in with no account axis at all. Scoping only
+                # this leg would make the truncation moments disagree with the
+                # anchors and the entries they are truncating; scoping the
+                # subsystem is a change to `blocks` itself.
+                #
+                # Two consequences are stated rather than left implicit. The
+                # widened selection admits manual credits and other accounts'
+                # credits as block-truncation points. And a moment can only be
+                # used when it falls in `[next_bs, rs]` for a canonical pair
+                # inside `[range_start, range_end]`; since a stored block start
+                # is at most one block duration before its own reset, every
+                # usable moment lies in `[range_start - BLOCK_DURATION,
+                # range_end]`, so the scan is bounded to exactly that and stops
+                # loading every credit ever recorded.
+                credit_scan_start = (
+                    range_start - _c.BLOCK_DURATION).isoformat()
+                credit_scan_end = range_end.isoformat()
                 credit_rows = conn.execute(
-                    "SELECT effective_reset_at_utc "
-                    "FROM week_reset_events "
-                    "WHERE old_week_end_at = effective_reset_at_utc"
+                    "SELECT COALESCE(observed_at_utc, effective_reset_at_utc) "
+                    "         AS accounting_at "
+                    "  FROM week_reset_events "
+                    " WHERE accounting_at IS NOT NULL "
+                    "   AND unixepoch(accounting_at) >= unixepoch(?) "
+                    "   AND unixepoch(accounting_at) <= unixepoch(?)",
+                    (credit_scan_start, credit_scan_end),
                 ).fetchall()
                 for c in credit_rows:
-                    raw = c["effective_reset_at_utc"]
+                    raw = c["accounting_at"]
                     try:
                         d = dt.datetime.fromisoformat(str(raw))
                     except ValueError:
@@ -1647,12 +1686,20 @@ def _backfill_five_hour_blocks(
                 # suffixes (block_start_at is host-local; week_start_at /
                 # effective_reset_at_utc are ``+00:00``); see the live-path
                 # comment for rationale.
+                # #703 + #707: the ACCOUNTING instant, so a block is flagged as
+                # crossing the moment the counter actually moved rather than the
+                # hour it is displayed at — the floored instant can fall in the
+                # previous block.
                 cross_row = conn.execute(
                     """
                     SELECT 1 FROM week_reset_events
                      WHERE account_key = ?
-                       AND unixepoch(effective_reset_at_utc) >= unixepoch(?)
-                       AND unixepoch(effective_reset_at_utc) <= unixepoch(?)
+                       AND unixepoch(COALESCE(observed_at_utc,
+                                              effective_reset_at_utc))
+                           >= unixepoch(?)
+                       AND unixepoch(COALESCE(observed_at_utc,
+                                              effective_reset_at_utc))
+                           <= unixepoch(?)
                      LIMIT 1
                     """,
                     (acct, block_start_at, last_obs),