cctally 1.27.1 → 1.29.0

package/bin/_cctally_milestones.py

@@ -331,32 +331,45 @@ def insert_percent_milestone(
 def insert_budget_milestone(
     conn: sqlite3.Connection,
     *,
-    week_start_at: str,
+    vendor: str,
+    period_start_at: str,
+    period: "str | None" = None,
     threshold: int,
     budget_usd: float,
     spent_usd: float,
     consumption_pct: float,
     commit: bool = True,
 ) -> int:
-    """INSERT OR IGNORE a budget threshold crossing. Returns ``cur.rowcount``
-    (1 = genuinely new crossing, 0 = INSERT OR IGNORE no-op on a pre-existing
-    ``(week_start_at, threshold)`` row).
-
-    Mirrors :func:`insert_percent_milestone`'s rowcount contract so the
-    alert-fire predicate (`if inserted == 1`) is race-safe without a
-    follow-up SELECT. ``alerted_at`` is left NULL — the caller stamps it in
-    the SAME transaction BEFORE dispatching (set-then-dispatch invariant,
-    CLAUDE.md Alerts gotcha). ``commit=False`` lets the caller bundle the
-    INSERT with the follow-up ``alerted_at`` UPDATE in one transaction so a
+    """INSERT OR IGNORE a budget threshold crossing into the unified vendor-tagged
+    table (#143). Returns ``cur.rowcount`` (1 = genuinely new crossing, 0 =
+    INSERT OR IGNORE no-op on a pre-existing ``(vendor, period_start_at, period,
+    threshold)`` row).
+
+    The merged ``budget_milestones`` table (migration 012) carries a ``vendor``
+    column (``'claude'``|``'codex'``) and the renamed ``period_start_at`` key
+    (the Claude subscription-week start OR the Codex calendar-period start —
+    Codex has no Anthropic subscription week, spec §6). Mirrors
+    :func:`insert_percent_milestone`'s rowcount contract so the alert-fire
+    predicate (`if inserted == 1`) is race-safe without a follow-up SELECT.
+    ``period`` (#137) is the configured period noun at crossing
+    ('calendar-week'|'calendar-month'|'subscription-week'); it discriminates the
+    UNIQUE key so calendar-week and calendar-month windows that share a start
+    instant don't collide. A NULL ``period`` is the pre-011 "unknown" sentinel
+    (only seeded migration rows carry it). ``alerted_at`` is left NULL — the
+    caller stamps it in the SAME transaction BEFORE dispatching (set-then-dispatch
+    invariant, CLAUDE.md Alerts gotcha). ``commit=False`` lets the caller bundle
+    the INSERT with the follow-up ``alerted_at`` UPDATE in one transaction so a
     crash between them can't strand ``alerted_at`` NULL forever.
     """
     cur = conn.execute(
         "INSERT OR IGNORE INTO budget_milestones "
-        "(week_start_at, threshold, budget_usd, spent_usd, consumption_pct, "
-        " crossed_at_utc) "
-        "VALUES (?, ?, ?, ?, ?, ?)",
+        "(vendor, period_start_at, period, threshold, budget_usd, spent_usd, "
+        " consumption_pct, crossed_at_utc) "
+        "VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
         (
-            week_start_at,
+            str(vendor),
+            period_start_at,
+            period,
             int(threshold),
             float(budget_usd),
             float(spent_usd),
@@ -419,6 +432,7 @@ def insert_projected_milestone(
     conn: sqlite3.Connection,
     *,
     week_start_at: str,
+    period: "str | None" = None,
     metric: str,
     threshold: int,
     projected_value: float,
@@ -427,23 +441,27 @@ def insert_projected_milestone(
 ) -> int:
     """INSERT OR IGNORE a projected-pace crossing. Returns ``cur.rowcount``
     (1 = genuinely new crossing, 0 = INSERT OR IGNORE no-op on a pre-existing
-    ``(week_start_at, metric, threshold)`` row).
+    ``(week_start_at, period, metric, threshold)`` row).
 
     Mirrors :func:`insert_budget_milestone`'s rowcount contract so the
     alert-fire predicate (`if inserted == 1`) is race-safe without a follow-up
-    SELECT. ``alerted_at`` is left NULL — the caller stamps it in the SAME
-    transaction BEFORE dispatching (set-then-dispatch invariant, CLAUDE.md
-    Alerts gotcha). ``commit=False`` lets the caller bundle the INSERT with the
-    follow-up ``alerted_at`` UPDATE in one transaction so a crash between them
-    can't strand ``alerted_at`` NULL forever.
+    SELECT. ``period`` (#137) is the configured period at crossing — for the
+    ``weekly_pct`` leg it is 'subscription-week', for ``budget_usd`` the Claude
+    configured period, for ``codex_budget_usd`` the Codex configured period;
+    NULL is the pre-011 unknown sentinel. ``alerted_at`` is left NULL — the
+    caller stamps it in the SAME transaction BEFORE dispatching (set-then-
+    dispatch invariant, CLAUDE.md Alerts gotcha). ``commit=False`` lets the
+    caller bundle the INSERT with the follow-up ``alerted_at`` UPDATE in one
+    transaction so a crash between them can't strand ``alerted_at`` NULL forever.
     """
     cur = conn.execute(
         "INSERT OR IGNORE INTO projected_milestones "
-        "(week_start_at, metric, threshold, projected_value, denominator, "
-        " crossed_at_utc) "
-        "VALUES (?, ?, ?, ?, ?, ?)",
+        "(week_start_at, period, metric, threshold, projected_value, "
+        " denominator, crossed_at_utc) "
+        "VALUES (?, ?, ?, ?, ?, ?, ?)",
         (
             week_start_at,
+            period,
             str(metric),
             int(threshold),
             float(projected_value),
@@ -460,69 +478,247 @@ def _projected_levels_already_latched(
     conn: sqlite3.Connection,
     *,
     week_start_at: str,
+    period: "str | None" = None,
     metric: str,
     levels: "tuple[int, ...]",
 ) -> bool:
     """True iff EVERY level in ``levels`` already has a row for
-    ``(week_start_at, metric)``.
+    ``(week_start_at, period, metric)``.
 
     Cheap indexed SELECT used as the pre-probe gate BEFORE any projection math
     / cost work ([Pre-probe before sync_cache]). Empty ``levels`` → True
     (nothing owed). When False, at least one level is still un-recorded and the
     caller must do the projection. Mirrors the per-week pre-probe SELECT in
     :func:`maybe_record_budget_milestone`.
+
+    The ``period IS NULL`` arm (#137) means a pre-011 NULL-period row for the
+    current window counts as latched — so an upgrading user never re-fires a
+    spurious projected alert against a historical crossing.
     """
     if not levels:
         return True
     rows = conn.execute(
         "SELECT threshold FROM projected_milestones "
-        "WHERE week_start_at = ? AND metric = ?",
-        (week_start_at, str(metric)),
+        "WHERE week_start_at = ? AND (period = ? OR period IS NULL) "
+        "  AND metric = ?",
+        (week_start_at, period, str(metric)),
     ).fetchall()
     have = {int(r[0]) for r in rows}
     return all(int(level) in have for level in levels)
 
 
-def _reconcile_budget_milestones_on_set(conn, *, target, thresholds, now_utc):
-    """Forward-only-from-set reconcile (spec §5): on `budget set`, every
-    threshold ALREADY crossed for the current week is recorded with
-    ``alerted_at`` SET but WITHOUT dispatch — so setting a budget when you're
-    already at 95% does NOT instant-popup. Thresholds not yet crossed get NO
-    row, so they fire later via :func:`maybe_record_budget_milestone`.
-
-    A mid-week target change re-runs this; thresholds already alerted stay
-    deduped via UNIQUE(week_start_at, threshold) + the ``alerted_at IS NULL``
-    guard on the UPDATE (so an existing alerted row is never re-stamped).
-    """
+def _resolve_claude_budget_window(conn, now_utc, *, period, config, tz):
+    """Resolve the Claude budget's ``(start_utc, end_utc)`` window for the
+    configured ``period`` (calendar-period-codex-budgets generalization, spec
+    §6). Subscription-week → the existing ``_resolve_current_budget_window``
+    (snapshot-anchored; may return ``None`` when no usage snapshot has landed
+    yet). Calendar period → the pure ``_resolve_calendar_window`` (derived purely
+    from ``now`` + the period; NEVER ``None``). The dedup key column is now
+    ``period_start_at`` (#143) — it carries the resolved PERIOD-start instant
+    (subscription-week OR calendar period-start)."""
     c = _cctally()
-    window = c._resolve_current_budget_window(conn, now_utc)
+    if period == "subscription-week":
+        return c._resolve_current_budget_window(conn, now_utc)
+    return c._resolve_calendar_window(period, now_utc, config, tz)
+
+
+def _resolve_budget_window(conn, *, vendor, now_utc, period, config, tz):
+    """Resolve the budget period-start instant for ``vendor`` (#143). CHEAP — does
+    NO cost SUM, preserving the pre-probe-before-spend hot path (spec §4.2): the
+    firing paths resolve this cheap window, pre-probe which thresholds are already
+    latched, and skip the cost SUM entirely when nothing is pending.
+
+    Dispatches to the per-vendor window primitive:
+      * claude → :func:`_resolve_claude_budget_window` (snapshot-anchored for
+        subscription-week → may be ``None`` pre-snapshot; calendar period → the
+        pure calendar window, never ``None``).
+      * codex  → :func:`_resolve_codex_budget_period_window` (pure calendar window;
+        never ``None``).
+
+    Returns the period-start ``datetime`` or ``None`` (claude subscription-week
+    pre-snapshot)."""
+    if vendor == "claude":
+        window = _resolve_claude_budget_window(
+            conn, now_utc, period=period, config=config, tz=tz
+        )
+    else:
+        window = _resolve_codex_budget_period_window(period, now_utc, config, tz)
     if window is None:
+        return None
+    start_at, _end_at = window
+    return start_at
+
+
+def _budget_spend_for_vendor(conn, *, vendor, start_at, now_utc) -> float:
+    """Spend over ``[start_at, now]`` for ``vendor`` (#143) — the COSTLY leg,
+    called only after the pre-probe finds pending thresholds (spec §4.2). claude
+    routes through the Claude cost SUM (``mode="auto"``); codex through the Codex
+    cost SUM."""
+    c = _cctally()
+    if vendor == "claude":
+        return c._sum_cost_for_range(start_at, now_utc, mode="auto")
+    return c._sum_codex_cost_for_range(start_at, now_utc)
+
+
+def _reconcile_budget_milestones_on_set(
+    conn, *, vendor, target, thresholds, now_utc, period, config=None, tz=None,
+):
+    """Forward-only-from-set reconcile for the budget axis (both vendors, #143):
+    on `budget set`, every threshold ALREADY crossed for the current
+    window/period is recorded with ``alerted_at`` SET but WITHOUT dispatch — so
+    setting a budget when you're already at 95% does NOT instant-popup. Thresholds
+    not yet crossed get NO row, so they fire later via the firing path
+    (:func:`maybe_record_budget_milestone` / :func:`maybe_record_codex_budget_milestone`).
+
+    A mid-window target change re-runs this; thresholds already alerted stay
+    deduped via UNIQUE(vendor, period_start_at, period, threshold) + the
+    ``alerted_at IS NULL`` guard on the UPDATE (so an existing alerted row is never
+    re-stamped).
+
+    Cold path — no pre-probe; resolves the cheap window then computes spend right
+    after (spec §4.2 ordering). ``vendor`` selects the window + spend dispatcher;
+    claude subscription-week may resolve ``None`` pre-snapshot (early return).
+    Keeps its own stamp-no-dispatch tail (distinct from :func:`_budget_crossings`,
+    which dispatches) — that asymmetry is intrinsic, not duplication.
+    """
+    start_at = _resolve_budget_window(
+        conn, vendor=vendor, now_utc=now_utc, period=period, config=config, tz=tz
+    )
+    if start_at is None:
         return
-    week_start_at, _week_end_at = window
-    week_key = week_start_at.isoformat(timespec="seconds")
-    spent = c._sum_cost_for_range(week_start_at, now_utc, mode="auto")
-    # target > 0 guaranteed by the caller (_cmd_budget_set passes the validated
-    # weekly_usd); the else is belt-and-suspenders.
+    period_key = start_at.isoformat(timespec="seconds")
+    spent = _budget_spend_for_vendor(
+        conn, vendor=vendor, start_at=start_at, now_utc=now_utc
+    )
+    # target > 0 guaranteed by the caller (validated weekly_usd / amount_usd);
+    # the else is belt-and-suspenders.
     consumption_pct = (spent / target * 100.0) if target > 0 else 0.0
     for t in sorted(thresholds):
         if consumption_pct + 1e-9 >= t:
             insert_budget_milestone(
                 conn,
-                week_start_at=week_key,
+                vendor=vendor,
+                period_start_at=period_key,
+                period=period,
                 threshold=t,
                 budget_usd=target,
                 spent_usd=spent,
                 consumption_pct=consumption_pct,
                 commit=False,
             )
+            # alerted_at UPDATE keys on the CONCRETE (vendor, period) (not the
+            # wildcard): only the row we just inserted is stamped, never a
+            # pre-011 NULL-period sibling (#137) or another vendor's row (#143).
             conn.execute(
                 "UPDATE budget_milestones SET alerted_at = ? "
-                "WHERE week_start_at = ? AND threshold = ? AND alerted_at IS NULL",
-                (now_utc_iso(), week_key, t),
+                "WHERE vendor = ? AND period_start_at = ? AND period = ? "
+                "  AND threshold = ? AND alerted_at IS NULL",
+                (now_utc_iso(), vendor, period_key, period, t),
             )
     conn.commit()
 
 
+def _resolve_codex_budget_period_window(period, now_utc, config, tz):
+    """Resolve the Codex budget's ``(start_utc, end_utc)`` calendar window via
+    the forecast layer's ``_resolve_calendar_window`` (which routes to the pure
+    ``calendar_month_window`` / ``calendar_week_window`` kernel functions). The
+    Codex axis NEVER touches ``weekly_usage_snapshots`` (no Anthropic week), so
+    the window comes purely from ``now`` + the configured calendar period.
+    ``period`` is canonical (calendar-week / calendar-month — the validator
+    forbids subscription-week for Codex)."""
+    c = _cctally()
+    return c._resolve_calendar_window(period, now_utc, config, tz)
+
+
+def _budget_crossings(
+    conn, *, vendor, period_key, period=None, thresholds, target, spent, now_utc
+):
+    """Shared INSERT-and-arm core for the budget axis (both vendors, #143): for
+    every STILL-pending threshold that's been crossed at ``spent``, ``INSERT OR
+    IGNORE`` a milestone (commit=False) into the unified vendor-tagged table and —
+    on the genuine-new-crossing winner (rowcount==1) — stamp ``alerted_at`` in the
+    SAME transaction (set-then-dispatch), returning the list of crossings the
+    caller must dispatch.
+
+    Pure of config/window resolution: both firing sites (record-usage +
+    opportunistic ``cctally budget``), for either vendor, feed the
+    already-resolved ``vendor`` / ``period_key`` / ``target`` / ``spent`` here, so
+    the crossing arithmetic + the set-then-dispatch invariant live in ONE place.
+    Does NOT commit — the caller owns the single durable commit that bundles every
+    INSERT with its ``alerted_at`` UPDATE. Applies the +1e-9 float-floor snap
+    (CLAUDE.md gotcha). Returns ``[(threshold, crossed_at, spent, target,
+    consumption_pct), ...]`` for the rowcount==1 winners only.
+
+    Forward-only / fire-once is enforced by INSERT OR IGNORE's rowcount on the
+    UNIQUE(vendor, period_start_at, period, threshold) key; a racing record-usage
+    instance OR an already-recorded threshold gets rowcount==0 and is skipped
+    ([Dedup mustn't gate side effects])."""
+    consumption_pct = (spent / target * 100.0) if target > 0 else 0.0
+    fired: "list" = []
+    for t in sorted(thresholds):
+        if consumption_pct + 1e-9 >= t:
+            inserted = insert_budget_milestone(
+                conn,
+                vendor=vendor,
+                period_start_at=period_key,
+                period=period,
+                threshold=t,
+                budget_usd=target,
+                spent_usd=spent,
+                consumption_pct=consumption_pct,
+                commit=False,
+            )
+            if inserted == 1:
+                crossed_at = now_utc_iso()
+                # alerted_at UPDATE keys on the CONCRETE (vendor, period) (#137 /
+                # #143): only the row just inserted is stamped, never a pre-011
+                # NULL-period sibling or another vendor's row.
+                conn.execute(
+                    "UPDATE budget_milestones SET alerted_at = ? "
+                    "WHERE vendor = ? AND period_start_at = ? AND period = ? "
+                    "  AND threshold = ? AND alerted_at IS NULL",
+                    (crossed_at, vendor, period_key, period, t),
+                )
+                fired.append((t, crossed_at, spent, target, consumption_pct))
+    return fired
+
+
+def _reconcile_codex_budget_on_config_write(validated_budget):
+    """Forward-only reconcile shared by the Codex-budget config write paths
+    (`budget set --vendor codex`, `config set budget.codex`). Gated +
+    best-effort: a Codex budget with alerts off or no thresholds records
+    nothing; a stats.db failure never fails the write. Runs OUTSIDE any
+    config_writer_lock (open_db has its own locking). Mirrors
+    :func:`_reconcile_budget_on_config_write`."""
+    codex = (validated_budget or {}).get("codex")
+    if not codex:
+        return
+    thresholds = codex.get("alert_thresholds") or []
+    if not (codex.get("alerts_enabled") and codex.get("amount_usd") and thresholds):
+        return
+    c = _cctally()
+    try:
+        import argparse
+        config = c.load_config()
+        tz = c.resolve_display_tz(argparse.Namespace(tz=None), config)
+        conn = open_db()
+        try:
+            _reconcile_budget_milestones_on_set(
+                conn,
+                vendor="codex",
+                target=codex["amount_usd"],
+                thresholds=thresholds,
+                now_utc=_command_as_of(),
+                period=codex["period"],
+                config=config,
+                tz=tz,
+            )
+        finally:
+            conn.close()
+    except Exception as exc:  # best-effort; never fail the write
+        eprint(f"[codex-budget-milestone] reconcile on set failed: {exc}")
+
+
 def _reconcile_budget_on_config_write(validated_budget):
     """Forward-only reconcile shared by all three budget-config write
     paths (`budget set`, `config set budget.*`, dashboard POST
@@ -532,14 +728,23 @@ def _reconcile_budget_on_config_write(validated_budget):
     thresholds = validated_budget.get("alert_thresholds") or []
     if not (_budget_alerts_active(validated_budget) and thresholds):
         return
+    c = _cctally()
+    period = validated_budget.get("period", "subscription-week")
     try:
+        import argparse
+        config = c.load_config()
+        tz = c.resolve_display_tz(argparse.Namespace(tz=None), config)
         conn = open_db()
         try:
             _reconcile_budget_milestones_on_set(
                 conn,
+                vendor="claude",
                 target=validated_budget["weekly_usd"],
                 thresholds=thresholds,
                 now_utc=_command_as_of(),
+                period=period,
+                config=config,
+                tz=tz,
             )
         finally:
             conn.close()

package/bin/_cctally_parser.py

@@ -1290,6 +1290,24 @@ def build_parser() -> argparse.ArgumentParser:
         "--project", nargs="?", const="__CWD__", default=None,
         help="Set/unset a per-project budget for this git repo "
              "(bare = current directory's git-root; or pass a path).")
+    bg.add_argument(
+        "--vendor", choices=["claude", "codex"], default="claude",
+        help="Which vendor budget to set/unset (default claude). Codex "
+             "budgets are calendar-period only.")
+    bg.add_argument(
+        "--period",
+        # Accept both canonical and short spellings; the command handler
+        # normalizes short->canonical and rejects `--vendor codex
+        # --period subscription-week` (Codex has no Anthropic week). The choices
+        # are single-sourced from `_BUDGET_PERIOD_CHOICES` (derived from the same
+        # short→canonical map the normalizer uses), so they can't drift from the
+        # handler (code-review #5).
+        choices=c._BUDGET_PERIOD_CHOICES,
+        default=None,
+        help="Budget period: subscription-week (claude only) / calendar-week "
+             "/ calendar-month. Default: preserve the stored period, else the "
+             "per-vendor default (claude=subscription-week, codex="
+             "calendar-month).")
     bg.add_argument("--reveal-projects", action="store_true", dest="reveal_projects",
                     help="Show real project basenames in the per-project section "
                          "of --format output (default anonymizes to project-1/…).")
@@ -2192,16 +2210,21 @@ def build_parser() -> argparse.ArgumentParser:
               cctally alerts test --axis five-hour --threshold 95
               cctally alerts test --axis budget --threshold 100
               cctally alerts test --axis project-budget --threshold 100
+              cctally alerts test --axis codex-budget --threshold 100
               cctally alerts test --axis projected --metric budget_usd
+              cctally alerts test --axis projected --metric codex_budget_usd
         """),
     )
     p_alerts_test.add_argument(
         "--axis",
-        choices=["weekly", "five-hour", "budget", "project-budget", "projected"],
+        choices=[
+            "weekly", "five-hour", "budget", "project-budget", "codex-budget",
+            "projected",
+        ],
         default="weekly",
         help="Alert axis to simulate: weekly subscription window, 5h block, "
-             "equiv-$ budget, per-project equiv-$ budget, or projected-pace "
-             "(default: weekly).",
+             "equiv-$ budget, per-project equiv-$ budget, Codex budget, or "
+             "projected-pace (default: weekly).",
     )
     p_alerts_test.add_argument(
         "--threshold",
@@ -2211,7 +2234,7 @@ def build_parser() -> argparse.ArgumentParser:
     )
     p_alerts_test.add_argument(
         "--metric",
-        choices=["weekly_pct", "budget_usd"],
+        choices=["weekly_pct", "budget_usd", "codex_budget_usd"],
         default="weekly_pct",
         help="For --axis projected: which projected metric to preview "
              "(default: weekly_pct).",
@@ -2334,6 +2357,23 @@ def build_parser() -> argparse.ArgumentParser:
     )
     db_unskip.set_defaults(func=c.cmd_db_unskip)
 
+    db_recover = db_sub.add_parser(
+        "recover",
+        help="Revert a version-ahead DB to the known schema head (#145)",
+    )
+    db_recover.add_argument(
+        "--db",
+        required=True,
+        choices=("cache", "stats"),
+        help="Which DB to recover",
+    )
+    db_recover.add_argument(
+        "--yes",
+        action="store_true",
+        help="Required for --db stats (non-re-derivable; may need a re-record)",
+    )
+    db_recover.set_defaults(func=c.cmd_db_recover)
+
     # ─── doctor (Diagnostics) ───────────────────────────────────────────
     doctor_p = sub.add_parser(
         "doctor",