cctally 1.22.4 → 1.23.0

package/bin/_lib_alert_axes.py

@@ -0,0 +1,44 @@
+"""Pure kernel: alert-axis descriptors + registry + shared severity policy.
+
+Single source of truth for axis *metadata* — id, chip/title labels (kept
+byte-identical with dashboard/web/src/lib/alertAxis.ts), the milestone-table
+name used by the dashboard envelope, and the axis-uniform severity policy
+(amber <95 / red >=95). This kernel does NOT own the write/transaction path:
+each axis keeps its own detect-and-arm code in bin/_cctally_record.py. The
+descriptor is the metadata/render contract, not the write engine.
+
+Stdlib-only, no I/O at import time. bin/cctally re-exports the public symbols.
+Spec: docs/superpowers/specs/2026-06-01-alerts-axis-registry-projected-pace-design.md
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# Severity boundary: thresholds at or above this render red, below it amber.
+# Mirrors the legacy hardcoded amber<95 / red>=95 split (axis-uniform v1).
+_SEVERITY_RED_FLOOR = 95
+
+
+def severity_for(threshold: int) -> str:
+    """Map a crossed integer threshold to a severity color ('amber' | 'red')."""
+    return "red" if int(threshold) >= _SEVERITY_RED_FLOOR else "amber"
+
+
+@dataclass(frozen=True)
+class AlertAxisDescriptor:
+    """Axis-agnostic metadata shared by the record path + dashboard envelope."""
+
+    id: str            # 'weekly' | 'five_hour' | 'budget' | 'projected'
+    chip_label: str    # SHOUT form, byte-identical with alertAxis.ts AXIS_CHIP_LABEL
+    title_label: str   # sentence-case form, byte-identical with AXIS_TITLE_LABEL
+    milestone_table: str  # SQLite table the dashboard envelope SELECTs from
+
+
+AXIS_REGISTRY: "tuple[AlertAxisDescriptor, ...]" = (
+    AlertAxisDescriptor("weekly", "WEEKLY", "Weekly", "percent_milestones"),
+    AlertAxisDescriptor("five_hour", "5H-BLOCK", "5h-block", "five_hour_milestones"),
+    AlertAxisDescriptor("budget", "BUDGET", "Budget", "budget_milestones"),
+    AlertAxisDescriptor("projected", "PROJECTED", "Projected", "projected_milestones"),
+)
+
+AXIS_BY_ID: "dict[str, AlertAxisDescriptor]" = {d.id: d for d in AXIS_REGISTRY}

package/bin/_lib_alerts_payload.py

@@ -242,3 +242,70 @@ def _build_alert_payload_budget(
             "consumption_pct": float(consumption_pct),
         },
     }
+
+
+def _alert_text_projected(payload: dict, tz: "ZoneInfo | None") -> tuple[str, str, str]:
+    """Build (title, subtitle, body) for a projected-pace alert (#121).
+
+    These fire on the WEEK-AVERAGE projection — what you're tracking toward at
+    the current week-average pace — NOT on an actual crossing. The text carries
+    an explicit "(projection)" / "on current pace" cue so a user never confuses
+    a projected alert with an actual-crossing one (which the weekly/budget
+    builders render). The rendered numbers come from the payload (the values
+    snapshotted at crossing), never from live config (Codex P0-4). ``tz`` is
+    accepted for signature parity with peer ``_alert_text_*`` builders and
+    intentionally unused (no instant is rendered, same as ``_alert_text_budget``).
+    """
+    metric = payload["metric"]
+    t = int(payload["threshold"])
+    proj = float(payload["projected_value"])
+    denom = float(payload["denominator"])
+    if metric == "weekly_pct":
+        title = f"cctally - projected to reach {t}% this week"
+        subtitle = "On current pace (projection)"
+        body = f"Projected ~{proj:.0f}% of cap by reset (week-average pace)"
+    else:  # budget_usd
+        title = "cctally - projected to exceed budget"
+        subtitle = f"On current pace (projection) - {t}% of budget"
+        body = (
+            f"Projected ${proj:,.2f} of ${denom:,.2f} budget "
+            f"(week-average pace)"
+        )
+    return title, subtitle, body
+
+
+def _build_alert_payload_projected(
+    *,
+    metric: str,
+    threshold: int,
+    projected_value: float,
+    denominator: float,
+    week_start_at: str,
+) -> dict:
+    """Build the alert payload for a projected-pace threshold crossing (#121).
+
+    ``axis: "projected"`` is the fourth alert axis; ``metric`` discriminates
+    ``weekly_pct`` (denominator 100.0, "% of cap") from ``budget_usd``
+    (denominator = target_usd, "$ of budget"). The frontend renders context
+    FROM these row-sourced fields (``metric`` / ``projected_value`` /
+    ``denominator``), not from live config that may have changed since crossing
+    (Codex P0-4). No ``crossed_at``/``alerted_at`` keys here: the projected
+    detector stamps ``alerted_at`` on the DB row itself in the same txn before
+    dispatch (set-then-dispatch), and the dashboard envelope reads it from the
+    row — mirroring ``_build_alert_payload_budget``'s context-only shape minus
+    the redundant timestamp echo.
+    """
+    return {
+        "id": f"projected:{week_start_at}:{metric}:{int(threshold)}",
+        "axis": "projected",
+        "metric": str(metric),
+        "threshold": int(threshold),
+        "projected_value": float(projected_value),
+        "denominator": float(denominator),
+        "context": {
+            "week_start_at": week_start_at,
+            "metric": str(metric),
+            "projected_value": float(projected_value),
+            "denominator": float(denominator),
+        },
+    }

package/bin/_lib_budget.py

@@ -52,6 +52,7 @@ class BudgetStatus:
     elapsed_fraction: float             # [0, 1]
     projected_eow_low_usd: float
     projected_eow_high_usd: float
+    week_avg_projection_usd: float      # spent + rate_avg*remaining (smooth estimator)
     verdict: str                        # "ok" | "warn" | "over"
     daily_budget_remaining_usd: float   # remaining / remaining-days
     daily_pace_usd: float               # current burn $/day (week-average)
@@ -93,6 +94,12 @@ def compute_budget_status(inputs: BudgetInputs) -> BudgetStatus:
         spent, remaining_hours, rate_low, rate_high
     )
 
+    # Smooth week-average end-of-week projection (additive surface field).
+    # Distinct from the displayed band (which keys off the high end): this is
+    # the conservative week-average value the projected-pace alert axis fires
+    # on. spent + rate_avg*remaining (== project_linear collapsed to one rate).
+    week_avg_projection_usd = spent + rate_avg * remaining_hours
+
     daily_pace_usd = rate_avg * 24.0
     daily_budget_remaining_usd = (
         (remaining_usd / remaining_days) if remaining_days > 0 else remaining_usd
@@ -125,6 +132,7 @@ def compute_budget_status(inputs: BudgetInputs) -> BudgetStatus:
         elapsed_fraction=elapsed_fraction,
         projected_eow_low_usd=projected_low,
         projected_eow_high_usd=projected_high,
+        week_avg_projection_usd=week_avg_projection_usd,
         verdict=verdict,
         daily_budget_remaining_usd=daily_budget_remaining_usd,
         daily_pace_usd=daily_pace_usd,

package/bin/cctally

@@ -366,14 +366,22 @@ _build_codex_weekly_parser = _cctally_parser._build_codex_weekly_parser
 _build_codex_session_parser = _cctally_parser._build_codex_session_parser
 
 
+_lib_alert_axes = _load_sibling("_lib_alert_axes")
+severity_for = _lib_alert_axes.severity_for
+AlertAxisDescriptor = _lib_alert_axes.AlertAxisDescriptor
+AXIS_REGISTRY = _lib_alert_axes.AXIS_REGISTRY
+AXIS_BY_ID = _lib_alert_axes.AXIS_BY_ID
+
 _lib_alerts_payload = _load_sibling("_lib_alerts_payload")
 _alert_text_weekly = _lib_alerts_payload._alert_text_weekly
 _alert_text_five_hour = _lib_alerts_payload._alert_text_five_hour
 _alert_text_budget = _lib_alerts_payload._alert_text_budget
+_alert_text_projected = _lib_alerts_payload._alert_text_projected
 _escape_applescript_string = _lib_alerts_payload._escape_applescript_string
 _build_alert_payload_weekly = _lib_alerts_payload._build_alert_payload_weekly
 _build_alert_payload_five_hour = _lib_alerts_payload._build_alert_payload_five_hour
 _build_alert_payload_budget = _lib_alerts_payload._build_alert_payload_budget
+_build_alert_payload_projected = _lib_alerts_payload._build_alert_payload_projected
 
 _lib_five_hour = _load_sibling("_lib_five_hour")
 _FIVE_HOUR_JITTER_FLOOR_SECONDS = _lib_five_hour._FIVE_HOUR_JITTER_FLOOR_SECONDS
@@ -799,6 +807,8 @@ _PERCENT_NORMALIZE_DECIMALS = _cctally_record._PERCENT_NORMALIZE_DECIMALS
 _normalize_percent = _cctally_record._normalize_percent
 maybe_record_milestone = _cctally_record.maybe_record_milestone
 maybe_record_budget_milestone = _cctally_record.maybe_record_budget_milestone
+maybe_record_projected_alert = _cctally_record.maybe_record_projected_alert
+_weekly_pct_week_avg_projection = _cctally_record._weekly_pct_week_avg_projection
 _compute_block_totals = _cctally_record._compute_block_totals
 maybe_update_five_hour_block = _cctally_record.maybe_update_five_hour_block
 cmd_record_usage = _cctally_record.cmd_record_usage
@@ -2053,6 +2063,8 @@ get_milestone_cost_for_week         = _cctally_milestones.get_milestone_cost_for
 get_milestones_for_week             = _cctally_milestones.get_milestones_for_week             # forecast c.; tui shim; percent-breakdown c.
 insert_percent_milestone            = _cctally_milestones.insert_percent_milestone            # record shim; idempotency-test mod.
 insert_budget_milestone             = _cctally_milestones.insert_budget_milestone             # record shim
+insert_projected_milestone          = _cctally_milestones.insert_projected_milestone          # record shim
+_projected_levels_already_latched   = _cctally_milestones._projected_levels_already_latched   # record shim
 _reconcile_budget_milestones_on_set = _cctally_milestones._reconcile_budget_milestones_on_set # test_budget_alerts ns[]
 _reconcile_budget_on_config_write   = _cctally_milestones._reconcile_budget_on_config_write   # forecast/config/dashboard c.; test_forecast_ns_patch mod. patch