cctally 1.7.3 → 1.7.4

package/bin/_cctally_dashboard.py

@@ -251,121 +251,55 @@ def _cctally():
     return sys.modules["cctally"]
 
 
+# === Honest imports from extracted homes ===================================
+# Spec 2026-05-17-cctally-core-kernel-extraction.md §3.3: kernel symbols
+# import from _cctally_core; already-decentralized buckets (X = _lib_*,
+# Y = _cctally_*) import from their natural home. These bypass the
+# legacy shim pattern entirely.
+from _cctally_core import (
+    eprint,
+    now_utc_iso,
+    parse_iso_datetime,
+    _now_utc,
+    _command_as_of,
+    open_db,
+    get_latest_usage_for_week,
+    make_week_ref,
+    _get_alerts_config,
+    _AlertsConfigError,
+)
+from _lib_display_tz import (
+    format_display_dt,
+    resolve_display_tz,
+    normalize_display_tz_value,
+    _compute_display_block,
+)
+from _lib_aggregators import _aggregate_daily, _aggregate_monthly, _aggregate_weekly
+from _lib_pricing import _calculate_entry_cost, _chip_for_model, _short_model_name
+from _lib_five_hour import _canonical_5h_window_key
+from _lib_subscription_weeks import _compute_subscription_weeks
+from _lib_blocks import _group_entries_into_blocks
+from _cctally_config import save_config, _load_config_unlocked
+from _cctally_db import _render_migration_error_banner
+from _cctally_cache import get_entries
+
+
 # === Module-level back-ref shims for helpers that STAY in bin/cctally ======
 # Each shim resolves ``sys.modules['cctally'].X`` at CALL TIME (not bind
 # time), so monkeypatches on cctally's namespace propagate into the moved
-# code unchanged. Mirrors the precedent established in
-# ``bin/_cctally_record.py`` (34 shims), ``bin/_cctally_cache.py``
-# (4 shims), ``bin/_cctally_db.py`` (4 shims), and
-# ``bin/_cctally_update.py`` (8 shims).
-def eprint(*args, **kwargs):
-    return sys.modules["cctally"].eprint(*args, **kwargs)
-
-
-def now_utc_iso(*args, **kwargs):
-    return sys.modules["cctally"].now_utc_iso(*args, **kwargs)
-
-
-def parse_iso_datetime(*args, **kwargs):
-    return sys.modules["cctally"].parse_iso_datetime(*args, **kwargs)
-
-
-def _now_utc(*args, **kwargs):
-    return sys.modules["cctally"]._now_utc(*args, **kwargs)
-
-
-def _command_as_of(*args, **kwargs):
-    return sys.modules["cctally"]._command_as_of(*args, **kwargs)
-
-
+# code unchanged. `load_config` and `get_claude_session_entries` STAY as
+# shims even though their natural homes are decentralized (_cctally_config
+# / _cctally_cache) — tests monkeypatch them via `ns["X"]` (21 sites total,
+# audited 2026-05-17); direct imports would silently bypass the patches.
+# See spec §3.5 (carve-out) and §3.7 (stays-on-shim allowlist).
 def load_config(*args, **kwargs):
     return sys.modules["cctally"].load_config(*args, **kwargs)
 
 
-def save_config(*args, **kwargs):
-    return sys.modules["cctally"].save_config(*args, **kwargs)
-
-
-def open_db(*args, **kwargs):
-    return sys.modules["cctally"].open_db(*args, **kwargs)
-
-
-def get_entries(*args, **kwargs):
-    return sys.modules["cctally"].get_entries(*args, **kwargs)
-
-
 def get_claude_session_entries(*args, **kwargs):
     return sys.modules["cctally"].get_claude_session_entries(*args, **kwargs)
 
 
-def get_latest_usage_for_week(*args, **kwargs):
-    return sys.modules["cctally"].get_latest_usage_for_week(*args, **kwargs)
-
-
-def make_week_ref(*args, **kwargs):
-    return sys.modules["cctally"].make_week_ref(*args, **kwargs)
-
-
-def format_display_dt(*args, **kwargs):
-    return sys.modules["cctally"].format_display_dt(*args, **kwargs)
-
-
-def resolve_display_tz(*args, **kwargs):
-    return sys.modules["cctally"].resolve_display_tz(*args, **kwargs)
-
-
-def normalize_display_tz_value(*args, **kwargs):
-    return sys.modules["cctally"].normalize_display_tz_value(*args, **kwargs)
-
-
-def _compute_display_block(*args, **kwargs):
-    return sys.modules["cctally"]._compute_display_block(*args, **kwargs)
-
-
-def _render_migration_error_banner(*args, **kwargs):
-    return sys.modules["cctally"]._render_migration_error_banner(*args, **kwargs)
-
-
-def _aggregate_daily(*args, **kwargs):
-    return sys.modules["cctally"]._aggregate_daily(*args, **kwargs)
-
-
-def _aggregate_monthly(*args, **kwargs):
-    return sys.modules["cctally"]._aggregate_monthly(*args, **kwargs)
-
-
-def _aggregate_weekly(*args, **kwargs):
-    return sys.modules["cctally"]._aggregate_weekly(*args, **kwargs)
-
-
-def _calculate_entry_cost(*args, **kwargs):
-    return sys.modules["cctally"]._calculate_entry_cost(*args, **kwargs)
-
-
-def _canonical_5h_window_key(*args, **kwargs):
-    return sys.modules["cctally"]._canonical_5h_window_key(*args, **kwargs)
-
-
-def _chip_for_model(*args, **kwargs):
-    return sys.modules["cctally"]._chip_for_model(*args, **kwargs)
-
-
-def _short_model_name(*args, **kwargs):
-    return sys.modules["cctally"]._short_model_name(*args, **kwargs)
-
-
-def _compute_subscription_weeks(*args, **kwargs):
-    return sys.modules["cctally"]._compute_subscription_weeks(*args, **kwargs)
-
-
-def _group_entries_into_blocks(*args, **kwargs):
-    return sys.modules["cctally"]._group_entries_into_blocks(*args, **kwargs)
-
-
-def _get_alerts_config(*args, **kwargs):
-    return sys.modules["cctally"]._get_alerts_config(*args, **kwargs)
-
-
 def _warn_alerts_bad_config_once(*args, **kwargs):
     return sys.modules["cctally"]._warn_alerts_bad_config_once(*args, **kwargs)
 
@@ -402,10 +336,6 @@ def doctor_gather_state(*args, **kwargs):
     return sys.modules["cctally"].doctor_gather_state(*args, **kwargs)
 
 
-def _load_config_unlocked(*args, **kwargs):
-    return sys.modules["cctally"]._load_config_unlocked(*args, **kwargs)
-
-
 def _apply_display_tz_override(*args, **kwargs):
     return sys.modules["cctally"]._apply_display_tz_override(*args, **kwargs)
 
@@ -2987,7 +2917,7 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
     alerts_array = list(getattr(snap, "alerts", []) or [])
     try:
         _alerts_cfg = _get_alerts_config(load_config())
-    except sys.modules["cctally"]._AlertsConfigError as exc:
+    except _AlertsConfigError as exc:
         _warn_alerts_bad_config_once(exc)
         _alerts_cfg = {
             "enabled": False,
@@ -3782,7 +3712,7 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 # save_config has not yet been called).
                 try:
                     _get_alerts_config(merged)
-                except sys.modules["cctally"]._AlertsConfigError as exc:
+                except _AlertsConfigError as exc:
                     self._respond_json(400, {"error": str(exc)})
                     return
 

package/bin/_cctally_db.py

@@ -71,35 +71,32 @@ def _cctally():
     return sys.modules["cctally"]
 
 
-# Module-level back-ref shims for the four callables most heavily used
-# across migration handlers + cmd_db_* renderers. Each shim resolves
-# `sys.modules['cctally'].X` at CALL TIME (not bind time), so
-# monkeypatches on cctally's namespace propagate into the moved code
-# unchanged. This lets the moved function bodies stay byte-identical
-# at every bare-name call site (`now_utc_iso(...)`,
-# `parse_iso_datetime(...)`, etc.) without requiring per-function
-# `c = _cctally()` boilerplate or `c.X` rewrites at every call site.
+# === Honest imports from extracted homes ===================================
+# Spec 2026-05-17-cctally-core-kernel-extraction.md §3.3: kernel symbols
+# import from _cctally_core. The legacy shim functions for these names
+# are deleted.
+from _cctally_core import (
+    eprint,
+    now_utc_iso,
+    parse_iso_datetime,
+)
+
+
+# Module-level back-ref shim for the one Z-high callable that STAYS in
+# bin/cctally. Resolves `sys.modules['cctally'].X` at CALL TIME (not
+# bind time), so monkeypatches on cctally's namespace propagate into the
+# moved code unchanged. `_compute_block_totals` is Z-high (reaches into
+# _cctally_cache via get_claude_session_entries) and is explicitly listed
+# in spec §3.7's stays-on-shim allowlist.
 #
 # Path constants and rarer helpers (`MIGRATION_ERROR_LOG_PATH`,
 # `LOG_DIR`, `DB_PATH`, `CACHE_DB_PATH`, `format_local_iso`) are
 # accessed via the standard `c = _cctally()` + `c.X` pattern instead
 # (call-time lookup so fixture-HOME redirects propagate).
-def now_utc_iso(*args, **kwargs):
-    return sys.modules["cctally"].now_utc_iso(*args, **kwargs)
-
-
-def parse_iso_datetime(*args, **kwargs):
-    return sys.modules["cctally"].parse_iso_datetime(*args, **kwargs)
-
-
 def _compute_block_totals(*args, **kwargs):
     return sys.modules["cctally"]._compute_block_totals(*args, **kwargs)
 
 
-def eprint(*args, **kwargs):
-    return sys.modules["cctally"].eprint(*args, **kwargs)
-
-
 # === BEGIN MOVED REGIONS ===
 # Regions below are inserted verbatim from bin/cctally. Bare-name
 # references to `now_utc_iso(...)`, `parse_iso_datetime(...)`,
@@ -1598,6 +1595,78 @@ def _migration_five_hour_milestones_reset_event_id(conn: sqlite3.Connection) ->
         raise
 
 
+@stats_migration("007_observed_pre_credit_pct")
+def _migration_observed_pre_credit_pct(conn: sqlite3.Connection) -> None:
+    """Add ``observed_pre_credit_pct`` to ``week_reset_events`` so the
+    race-defensive cleanup DELETE in the in-place weekly credit branch
+    has a durable record of the pre-credit baseline we observed at
+    write time — independent of how the upstream claude-statusline
+    tool rounds replays.
+
+    Today statusline replays cctally's ``hwm-7d`` value byte-identically,
+    so the existing strict ``round(.,1)`` equality predicate is sound.
+    Future-proofs against rounding drift: if Anthropic ever rounds the
+    ``--percent`` payload differently from the OAuth API used by
+    record-usage, or if statusline grows its own coarser rounding, a
+    replay at e.g. 67.5 against a stored prior_pct = 67.4 would slip
+    past strict equality and then dominate the reset-aware clamp's
+    MAX over the post-credit segment. With the value stamped on the
+    event row, the cleanup predicate widens to a 1.0pp tolerance band
+    (issue #45) — wide enough to absorb single-digit drift, narrow
+    enough that legitimate post-credit observations (≥25pp away by
+    the in-place credit detection threshold's hypothesis) stay.
+
+    Backfill: NULL on existing rows. NULL is legacy / never-stamped;
+    the live cleanup's bind still uses the current tick's in-scope
+    ``prior_pct`` (the value we just observed and would have stamped),
+    so the cleanup remains correct on the very tick that writes the
+    row. The stored value matters for future tooling that may re-run
+    cleanup against an already-written event row.
+
+    Companion live-path edits land in:
+      - bin/cctally — CREATE TABLE adds the column for fresh installs.
+      - bin/_cctally_record.py — in-place credit INSERT stamps
+        ``observed_pre_credit_pct = prior_pct``; race-defensive DELETE
+        switches from ``round(weekly_percent,1) = round(?,1)`` to
+        ``ABS(weekly_percent - ?) < 1.0``.
+
+    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), stamp the marker and
+    return without an ALTER. Simple ADD COLUMN — no UNIQUE constraint
+    change, so no rename-recreate-copy needed (contrast migrations
+    005 / 006).
+    """
+    cols = {
+        str(r[1])
+        for r in conn.execute("PRAGMA table_info(week_reset_events)").fetchall()
+    }
+    if "observed_pre_credit_pct" in cols:
+        conn.execute(
+            "INSERT OR IGNORE INTO schema_migrations (name, applied_at_utc) "
+            "VALUES (?, ?)",
+            ("007_observed_pre_credit_pct", now_utc_iso()),
+        )
+        conn.commit()
+        return
+
+    conn.execute("BEGIN")
+    try:
+        conn.execute(
+            "ALTER TABLE week_reset_events "
+            "ADD COLUMN observed_pre_credit_pct REAL"
+        )
+        conn.execute(
+            "INSERT OR IGNORE INTO schema_migrations (name, applied_at_utc) "
+            "VALUES (?, ?)",
+            ("007_observed_pre_credit_pct", now_utc_iso()),
+        )
+        conn.commit()
+    except Exception:
+        conn.rollback()
+        raise
+
+
 # === Region 8: Test-only migration registration (was bin/cctally:12086-12140) ===
 
 # ──────────────────────────────────────────────────────────────────────

package/bin/_cctally_record.py

@@ -156,25 +156,40 @@ def _cctally():
     return sys.modules["cctally"]
 
 
+# === Honest imports from extracted homes ===================================
+# Spec 2026-05-17-cctally-core-kernel-extraction.md §3.3.
+from _cctally_core import (
+    eprint,
+    now_utc_iso,
+    parse_iso_datetime,
+    open_db,
+    get_week_start_name,
+    compute_week_bounds,
+    parse_date_str,
+    _canonicalize_optional_iso,
+    make_week_ref,
+    _get_alerts_config,
+    _AlertsConfigError,
+)
+from _lib_five_hour import _canonical_5h_window_key
+from _lib_pricing import _calculate_entry_cost
+
+
 # Module-level back-ref shims. Each shim resolves
 # ``sys.modules['cctally'].X`` at CALL TIME (not bind time), so
 # monkeypatches on cctally's namespace propagate into the moved code
-# unchanged. Mirrors the precedent established in
-# ``bin/_cctally_cache.py`` and ``bin/_cctally_db.py``.
-def eprint(*args, **kwargs):
-    return sys.modules["cctally"].eprint(*args, **kwargs)
-
-
-def now_utc_iso(*args, **kwargs):
-    return sys.modules["cctally"].now_utc_iso(*args, **kwargs)
-
-
-def parse_iso_datetime(*args, **kwargs):
-    return sys.modules["cctally"].parse_iso_datetime(*args, **kwargs)
+# unchanged. `load_config` and `get_claude_session_entries` STAY as
+# shims even though their natural homes are decentralized
+# (_cctally_config / _cctally_cache) — tests monkeypatch them via
+# `ns["X"]` (21 sites total, audited 2026-05-17); direct imports would
+# silently bypass the patches.
+# See spec §3.5 (carve-out) and §3.7 (stays-on-shim allowlist).
+def load_config(*args, **kwargs):
+    return sys.modules["cctally"].load_config(*args, **kwargs)
 
 
-def open_db(*args, **kwargs):
-    return sys.modules["cctally"].open_db(*args, **kwargs)
+def get_claude_session_entries(*args, **kwargs):
+    return sys.modules["cctally"].get_claude_session_entries(*args, **kwargs)
 
 
 def open_cache_db(*args, **kwargs):
@@ -185,30 +200,6 @@ def sync_cache(*args, **kwargs):
     return sys.modules["cctally"].sync_cache(*args, **kwargs)
 
 
-def load_config(*args, **kwargs):
-    return sys.modules["cctally"].load_config(*args, **kwargs)
-
-
-def get_week_start_name(*args, **kwargs):
-    return sys.modules["cctally"].get_week_start_name(*args, **kwargs)
-
-
-def compute_week_bounds(*args, **kwargs):
-    return sys.modules["cctally"].compute_week_bounds(*args, **kwargs)
-
-
-def parse_date_str(*args, **kwargs):
-    return sys.modules["cctally"].parse_date_str(*args, **kwargs)
-
-
-def _canonicalize_optional_iso(*args, **kwargs):
-    return sys.modules["cctally"]._canonicalize_optional_iso(*args, **kwargs)
-
-
-def _canonical_5h_window_key(*args, **kwargs):
-    return sys.modules["cctally"]._canonical_5h_window_key(*args, **kwargs)
-
-
 def _floor_to_hour(*args, **kwargs):
     return sys.modules["cctally"]._floor_to_hour(*args, **kwargs)
 
@@ -245,22 +236,10 @@ def insert_percent_milestone(*args, **kwargs):
     return sys.modules["cctally"].insert_percent_milestone(*args, **kwargs)
 
 
-def make_week_ref(*args, **kwargs):
-    return sys.modules["cctally"].make_week_ref(*args, **kwargs)
-
-
 def cmd_sync_week(*args, **kwargs):
     return sys.modules["cctally"].cmd_sync_week(*args, **kwargs)
 
 
-def _calculate_entry_cost(*args, **kwargs):
-    return sys.modules["cctally"]._calculate_entry_cost(*args, **kwargs)
-
-
-def get_claude_session_entries(*args, **kwargs):
-    return sys.modules["cctally"].get_claude_session_entries(*args, **kwargs)
-
-
 def _resolve_primary_model_for_block(*args, **kwargs):
     return sys.modules["cctally"]._resolve_primary_model_for_block(*args, **kwargs)
 
@@ -281,10 +260,6 @@ def _dispatch_alert_notification(*args, **kwargs):
     return sys.modules["cctally"]._dispatch_alert_notification(*args, **kwargs)
 
 
-def _get_alerts_config(*args, **kwargs):
-    return sys.modules["cctally"]._get_alerts_config(*args, **kwargs)
-
-
 def _warn_alerts_bad_config_once(*args, **kwargs):
     return sys.modules["cctally"]._warn_alerts_bad_config_once(*args, **kwargs)
 
@@ -532,7 +507,7 @@ def maybe_record_milestone(
         # the underlying problem is config-wide, not axis-specific.
         try:
             alerts_cfg: "dict | None" = _get_alerts_config(load_config())
-        except sys.modules["cctally"]._AlertsConfigError as exc:
+        except _AlertsConfigError as exc:
             _warn_alerts_bad_config_once(exc)
             alerts_cfg = None
 
@@ -803,7 +778,7 @@ def maybe_update_five_hour_block(saved: dict[str, Any]) -> None:
         cfg_for_alerts = load_config()
         try:
             alerts_cfg: "dict | None" = _get_alerts_config(cfg_for_alerts)
-        except sys.modules["cctally"]._AlertsConfigError as exc:
+        except _AlertsConfigError as exc:
             _warn_alerts_bad_config_once(exc)
             alerts_cfg = None
         # Resolve display.tz once (shares the cfg load above). Threaded
@@ -1500,12 +1475,19 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
                             # UNIQUE(old, new) constraint permits this
                             # row, and the pre-check above keys on
                             # new_week_end_at so dedup still works.
+                            # Stamp ``observed_pre_credit_pct = prior_pct``
+                            # (issue #45): durable record of the pre-credit
+                            # baseline we observed at write time. Decouples
+                            # any future cleanup tooling from re-deriving
+                            # prior_pct via SELECT. Existing rows from
+                            # migration 007 carry NULL.
                             conn.execute(
                                 "INSERT OR IGNORE INTO week_reset_events "
                                 "(detected_at_utc, old_week_end_at, new_week_end_at, "
-                                " effective_reset_at_utc) VALUES (?, ?, ?, ?)",
+                                " effective_reset_at_utc, observed_pre_credit_pct) "
+                                "VALUES (?, ?, ?, ?, ?)",
                                 (now_utc_iso(), effective_iso, cur_end_canon,
-                                 effective_iso),
+                                 effective_iso, float(prior_pct)),
                             )
                             conn.commit()
                         # Pivots fire UNCONDITIONALLY whenever a credit
@@ -1553,24 +1535,29 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
                         # own in-memory HWM cache and re-runs us once
                         # per status-line tick). Those replays land
                         # captured_at_utc >= effective_iso with
-                        # weekly_percent == prior_pct (the pre-credit
+                        # weekly_percent near prior_pct (the pre-credit
                         # value), and they dominate the reset-aware
                         # clamp's MAX over the post-credit segment so
                         # legitimate fresh OAuth values are rejected.
-                        # Strict equality (round(.,1)) keeps this
-                        # narrow: we only delete rows whose percent
-                        # exactly matches the pre-credit value we just
-                        # observed — legitimate post-credit climbs
-                        # past `prior_pct` (rare, but possible if the
-                        # credit is small + activity is heavy) stay.
+                        # 1.0pp tolerance band (issue #45) around the
+                        # observed pre-credit baseline absorbs any
+                        # rounding drift between cctally's OAuth read
+                        # and statusline's --percent payload (today
+                        # they match byte-identically, but the band
+                        # future-proofs against Anthropic or statusline
+                        # changing rounding). The band stays well below
+                        # the 25pp in-place credit detection threshold,
+                        # so legitimate post-credit values are never
+                        # caught. Bind is the in-scope ``prior_pct``,
+                        # which equals the just-stamped
+                        # ``observed_pre_credit_pct`` on the event row.
                         try:
                             conn.execute(
                                 "DELETE FROM weekly_usage_snapshots "
                                 "WHERE week_start_date = ? "
                                 "  AND unixepoch(captured_at_utc) >= "
                                 "      unixepoch(?) "
-                                "  AND round(weekly_percent, 1) = "
-                                "      round(?, 1)",
+                                "  AND ABS(weekly_percent - ?) < 1.0",
                                 (week_start_date, effective_iso,
                                  float(prior_pct)),
                             )
@@ -1755,20 +1742,34 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
                             # replaying the pre-credit
                             # ``--five-hour-percent`` value past the
                             # credit moment from its own in-memory
-                            # HWM cache. Strict round-1 equality
-                            # keeps the scope narrow — only rows
-                            # whose five_hour_percent exactly matches
-                            # the just-observed pre-credit value are
-                            # removed. ``unixepoch()`` on both sides
-                            # for offset robustness (Z vs +00:00).
+                            # HWM cache. 1.0pp tolerance band (issue
+                            # #48 — symmetric follow-up to weekly #45)
+                            # around the observed pre-credit baseline
+                            # absorbs any rounding drift between
+                            # cctally's OAuth read and statusline's
+                            # ``--five-hour-percent`` payload (today
+                            # they match byte-identically, but the
+                            # band future-proofs against Anthropic or
+                            # statusline changing 5h rounding). The
+                            # band stays well below the 5.0pp 5h
+                            # in-place credit detection threshold
+                            # (``_FIVE_HOUR_RESET_PCT_DROP_THRESHOLD``)
+                            # — 4pp safety margin — so legitimate
+                            # post-credit values are never caught.
+                            # ``unixepoch()`` on both sides for offset
+                            # robustness (Z vs +00:00). Bind is the
+                            # in-scope ``prior_5h_pct``, which equals
+                            # the just-stamped
+                            # ``five_hour_reset_events.prior_percent``
+                            # on the event row.
                             try:
                                 conn.execute(
                                     "DELETE FROM weekly_usage_snapshots "
                                     " WHERE five_hour_window_key = ? "
                                     "   AND unixepoch(captured_at_utc) "
                                     "       >= unixepoch(?) "
-                                    "   AND round(five_hour_percent, 1) "
-                                    "       = round(?, 1)",
+                                    "   AND ABS(five_hour_percent - ?) "
+                                    "       < 1.0",
                                     (
                                         int(five_hour_window_key),
                                         effective_iso,