cctally 1.109.0 → 1.111.0

package/bin/_cctally_milestone_history.py

@@ -320,7 +320,42 @@ def _claude_cycle_rows(conn: sqlite3.Connection, ref) -> list:
     ).fetchall()
 
 
-def _index_entry(conn, ref, current_cycle_key, tz) -> dict:
+def _five_hour_detail_revision(conn, start_iso, end_iso) -> tuple[int, ...]:
+    """Append-only 5h child revision for one cycle's intersecting blocks.
+
+    The detail cache uses the index stamp. Weekly crossing counts do not move
+    when another account records a 5h credit or crossing in an existing block.
+    These child tables insert new ids for those events; count and max id also
+    notice deletions and replacement rows without hashing an unbounded ledger.
+    """
+    if not start_iso or not end_iso:
+        return (0, 0, 0, 0, 0, 0)
+    interval = (
+        "unixepoch(b.block_start_at) < unixepoch(?) "
+        "AND unixepoch(b.five_hour_resets_at) > unixepoch(?)"
+    )
+    bounds = (end_iso, start_iso)
+    blocks = conn.execute(
+        "SELECT COUNT(*), MAX(b.id) FROM five_hour_blocks b "
+        f"WHERE {interval}", bounds,
+    ).fetchone()
+    milestones = conn.execute(
+        "SELECT COUNT(*), MAX(m.id) FROM five_hour_blocks b "
+        "JOIN five_hour_milestones m ON m.block_id = b.id "
+        f"WHERE {interval}", bounds,
+    ).fetchone()
+    credits = conn.execute(
+        "SELECT COUNT(*), MAX(e.id) FROM five_hour_blocks b "
+        "JOIN five_hour_reset_events e "
+        "ON e.account_key = b.account_key "
+        "AND e.five_hour_window_key = b.five_hour_window_key "
+        f"WHERE {interval}", bounds,
+    ).fetchone()
+    return tuple(int(value or 0) for row in (blocks, milestones, credits)
+                 for value in row)
+
+
+def _index_entry(conn, ref, current_cycle_key, tz, *, decorated=False) -> dict:
     rows = _claude_cycle_rows(conn, ref)
     milestone_count = len(rows)
     segment_count = 1 if rows else 0
@@ -329,6 +364,11 @@ def _index_entry(conn, ref, current_cycle_key, tz) -> dict:
     end_z = _to_iso_z(ref.week_end_at)
     block_count = _count_blocks(conn, start_z, end_z)
     key = _claude_cycle_key(ref)
+    # R8: leave the <=1-real-account stamp byte-identical. On a decorated
+    # provider the fetched block list contains multiple account-owned rows,
+    # so its cache identity also needs their child-ledger revision.
+    block_revision = (
+        _five_hour_detail_revision(conn, start_z, end_z) if decorated else ())
 
     # #750 S4 §5.3. A CURRENT single-segment cycle neither fetches its detail
     # nor uses one that arrives, so a gap in the LIVE cycle would stay
@@ -356,7 +396,8 @@ def _index_entry(conn, ref, current_cycle_key, tz) -> dict:
         "segment_count": segment_count,
         "has_observation_gap": has_gap,
         "detail_stamp": _mh.compute_detail_stamp(
-            key, milestone_count, block_count, segment_count, max_captured
+            key, milestone_count, block_count, segment_count, max_captured,
+            *block_revision,
         ),
     }
 
@@ -377,7 +418,12 @@ def build_claude_week_index(conn: sqlite3.Connection) -> list:
     )
     current_cycle_key = _claude_cycle_key(current_ref) if current_ref else None
     tz = _resolve_display_tz()
-    entries = [_index_entry(conn, ref, current_cycle_key, tz) for ref in refs]
+    import _cctally_account
+    decorated = _cctally_account.provider_is_decorated(conn, "claude")
+    entries = [
+        _index_entry(conn, ref, current_cycle_key, tz, decorated=decorated)
+        for ref in refs
+    ]
     entries.sort(key=lambda e: e["start_at_utc"] or "", reverse=True)
     return entries
 
@@ -443,14 +489,17 @@ def _shape_observation_gap_runs(disclosure, rows) -> list:
     return out
 
 
-def _load_block_credits(conn: sqlite3.Connection, window_key: int) -> list:
+def _load_block_credits(
+    conn: sqlite3.Connection, window_key: int, account_key: str,
+) -> list:
     """5h in-place credit rows for a block, ascending by effective time —
     same wire shape as the envelope's ``five_hour_block.credits``."""
     rows = conn.execute(
         "SELECT effective_reset_at_utc, prior_percent, post_percent "
-        "FROM five_hour_reset_events WHERE five_hour_window_key = ? "
+        "FROM five_hour_reset_events "
+        "WHERE five_hour_window_key = ? AND account_key = ? "
         "ORDER BY effective_reset_at_utc ASC",
-        (int(window_key),),
+        (int(window_key), account_key),
     ).fetchall()
     return [
         {
@@ -470,6 +519,8 @@ def _build_blocks(conn: sqlite3.Connection, start_iso, end_iso) -> list:
     if not start_iso or not end_iso:
         return []
     c = _cctally()
+    import _cctally_account
+    decorated = _cctally_account.provider_is_decorated(conn, "claude")
     # #834 S1 (#836): `id` is selected so each block's milestones are loaded by
     # the PRECISE selector. This route used to select blocks account-blind and
     # then pass a bare `five_hour_window_key` to the milestone read, while block
@@ -477,13 +528,13 @@ def _build_blocks(conn: sqlite3.Connection, start_iso, end_iso) -> list:
     # window's per-account blocks each rendered EVERY account's milestones. `id`
     # stays internal: it is not added to the published `blocks[]` shape.
     rows = conn.execute(
-        "SELECT id, five_hour_window_key, block_start_at, five_hour_resets_at, "
+        "SELECT id, account_key, five_hour_window_key, block_start_at, five_hour_resets_at, "
         "       final_five_hour_percent, total_cost_usd, "
         "       crossed_seven_day_reset, is_closed "
         "FROM five_hour_blocks "
         "WHERE unixepoch(block_start_at) < unixepoch(?) "
         "  AND unixepoch(five_hour_resets_at) > unixepoch(?) "
-        "ORDER BY unixepoch(block_start_at) ASC, five_hour_window_key ASC",
+        "ORDER BY unixepoch(block_start_at) ASC, five_hour_window_key ASC, id ASC",
         (end_iso, start_iso),
     ).fetchall()
     out: list = []
@@ -502,7 +553,12 @@ def _build_blocks(conn: sqlite3.Connection, start_iso, end_iso) -> list:
                 "is_closed": bool(b["is_closed"]),
                 "milestones": c._tui_build_five_hour_milestones(
                     conn, wk, block_id=int(b["id"])),
-                "credits": _load_block_credits(conn, wk),
+                "credits": _load_block_credits(conn, wk, b["account_key"]),
+                **({
+                    "account_key": b["account_key"],
+                    "account_label": _cctally_account.display_account_label(
+                        conn, b["account_key"]),
+                } if decorated else {}),
             }
         )
     return out

package/bin/_cctally_parser.py

@@ -3175,6 +3175,11 @@ def _build_db_parser(subparsers, name, *, help_text, xref=None):
         action="store_true",
         help="Append the correction batch and rebuild stats.db (default: preview)",
     )
+    db_rederive.add_argument(
+        "--reviewed-weekly-decisions",
+        metavar="PATH",
+        help="Review exact Claude weekly observations from a pinned manifest",
+    )
     db_rederive.add_argument(
         "--json",
         action="store_true",

package/bin/_cctally_record.py

@@ -3922,7 +3922,7 @@ def detect_reset_and_credit(conn, *, week_start_date, week_end_at,
                             five_hour_percent, as_of=None, commit=True,
                             ctx=None, account_key=_lib_accounts.UNATTRIBUTED,
                             origin_observation_id=None, capture_at=None,
-                            source=None):
+                            source=None, hold_weekly_axis=False):
     """Detect + record weekly and 5h reset/credit artifacts for one usage
     observation (extracted from ``cmd_record_usage``; DB journal redesign
     §5.2.3).
@@ -3986,6 +3986,10 @@ def detect_reset_and_credit(conn, *, week_start_date, week_end_at,
       one value. The weekly branch does not read it: extending source-local
       confirmation to the weekly path would delay the immediate 63-to-0 reset
       that #755 exists to stop delaying.
+    - ``hold_weekly_axis`` (default ``False``): scratch replay's explicit
+      reviewed observation hold. It bypasses weekly reset/credit detection
+      while still running the independent five-hour detector below. Live
+      callers retain the default.
     """
     c = _cctally()
     now_utc = _as_of_or_command(as_of)
@@ -4025,7 +4029,7 @@ def detect_reset_and_credit(conn, *, week_start_date, week_end_at,
             "ORDER BY captured_at_utc DESC, id DESC LIMIT 1",
             (account_key,),
         ).fetchone()
-        if prior and prior["week_end_at"] and cur_end_canon:
+        if not hold_weekly_axis and prior and prior["week_end_at"] and cur_end_canon:
             prior_end_canon = _canonicalize_optional_iso(
                 prior["week_end_at"], "record.prior"
             )
@@ -7265,6 +7269,13 @@ def _pipeline_claude_usage(ctx, rec):
     if "resets_at" not in payload or "weekly_percent" not in payload:
         return
 
+    # The exact raw observation id is reviewed outside this pipeline. A hold
+    # can only be supplied on scratch replay; live ingest has no event sink.
+    hold_weekly_axis = (
+        ctx.event_sink is not None
+        and rec.get("id") in ctx.held_weekly_observation_ids
+    )
+
     c = _cctally()
     conn = ctx.conn
     # `as_of` is the record's `at` (= `_command_as_of()` at capture, CCTALLY_AS_OF
@@ -7326,6 +7337,20 @@ def _pipeline_claude_usage(ctx, rec):
         except (ValueError, TypeError) as exc:
             eprint(f"[ingest] 5h window-key derivation failed: {exc}")
 
+    import _cctally_journal as jr
+    reviewed_weekly_basis = None
+    if hold_weekly_axis:
+        reviewed_weekly_basis = (
+            ctx.reviewed_weekly_basis_by_account.get(account_key)
+            or jr._latest_weekly_basis(conn, account_key)
+        )
+        if reviewed_weekly_basis is None:
+            import _lib_rederive
+            raise _lib_rederive.RederiveConflict(
+                "reviewed weekly hold has no accepted account basis: "
+                f"{rec['id']}"
+            )
+
     # 1. Reset/credit detection (fold into the cycle txn; Design B suppression).
     c.detect_reset_and_credit(
         conn,
@@ -7350,11 +7375,11 @@ def _pipeline_claude_usage(ctx, rec):
         # #769 S2 §3: the contributor discriminator for five-hour credit
         # confirmation. `payload.source`, never `rec["src"]`.
         source=source,
+        hold_weekly_axis=hold_weekly_axis,
     )
 
     # 2. Accept/skip DECISION (clamp + dedup), made ONCE and journaled via the
     #    snapshot_accept evt (so replay never re-derives it — spec §5.3).
-    import _cctally_journal as jr
     fold = jr._usage_snapshot_fold_decision(conn, {
         "week_start_date": week_start_date,
         "week_start_at": week_start_at,
@@ -7363,10 +7388,11 @@ def _pipeline_claude_usage(ctx, rec):
         "five_hour_percent": five_hour_percent,
         "five_hour_window_key": five_hour_window_key,
         "account_key": account_key,
-    })
-    # #769 S11 (#824). `weekly_held` says the incoming weekly reading
-    # CONTRADICTS the stored one and the weekly axis is held at the stored
-    # maximum; `wrote_row` says whether this tick materialized a snapshot at
+    }, force_weekly_hold=hold_weekly_axis,
+       reviewed_weekly_basis=reviewed_weekly_basis)
+    # #769 S11 (#824). `weekly_held` says the weekly axis is held at the
+    # accepted basis (an ordinary lower clamp or an explicit scratch hold);
+    # `wrote_row` says whether this tick materialized a snapshot at
     # all. They are independent now: a held tick DOES write a row when its
     # five-hour axis carries evidence, and that row is the only place the
     # evidence survives, because `db rebuild` reconstructs open blocks from
@@ -7453,12 +7479,25 @@ def _pipeline_claude_usage(ctx, rec):
         if rowid is None:
             return
         saved["id"] = rowid
+        if ctx.event_sink is not None and not weekly_held:
+            # Keep the most recent accepted weekly source across scratch
+            # records. A later five-hour credit may suppress its snapshot
+            # row, but that independent effect must not erase the reviewed
+            # weekly basis for another held observation.
+            basis = jr._latest_weekly_basis(conn, account_key)
+            if basis is not None:
+                ctx.reviewed_weekly_basis_by_account[account_key] = basis
     else:
+        saved_week_start_date = (
+            fold.weekly.basis.week_start_date
+            if weekly_held and fold.weekly.basis is not None
+            else week_start_date
+        )
         latest = conn.execute(
             "SELECT * FROM weekly_usage_snapshots WHERE week_start_date = ? "
             "  AND account_key = ? "
             "ORDER BY captured_at_utc DESC, id DESC LIMIT 1",
-            (week_start_date, account_key),
+            (saved_week_start_date, account_key),
         ).fetchone()
         if latest is None:
             return  # nothing recorded yet -> nothing to derive against
@@ -7472,10 +7511,9 @@ def _pipeline_claude_usage(ctx, rec):
     #    crosses a $ threshold still derives it.
     #    The one exception is a HELD weekly axis. A no-change tick AGREES with
     #    the stored row, so re-deriving against it is the self-heal; a held
-    #    weekly axis means the incoming 7d percent is strictly BELOW the
-    #    reset-aware in-window maximum,
-    #    so the observation CONTRADICTS `saved` and a weekly milestone derived
-    #    from `saved`'s higher percent records a crossing the meter says did not
+    #    weekly axis means the observation's 7d value was not accepted,
+    #    so it CONTRADICTS `saved` and a weekly milestone derived
+    #    from `saved`'s carried percent can record a crossing the meter did not
     #    happen. That is how the 2026-09-01 incident fabricated a 13% milestone
     #    in a fresh post-credit epoch from a stale pre-credit replica, and
     #    because milestones are forward-only within an epoch that row forecloses