cctally 1.22.4 → 1.23.0

package/bin/_cctally_dashboard.py

@@ -336,6 +336,10 @@ def _build_alert_payload_budget(*args, **kwargs):
     return sys.modules["cctally"]._build_alert_payload_budget(*args, **kwargs)
 
 
+def _build_alert_payload_projected(*args, **kwargs):
+    return sys.modules["cctally"]._build_alert_payload_projected(*args, **kwargs)
+
+
 def _dispatch_alert_notification(*args, **kwargs):
     return sys.modules["cctally"]._dispatch_alert_notification(*args, **kwargs)
 
@@ -4065,31 +4069,16 @@ def _select_current_block_for_envelope(
     }
 
 
-def _build_alerts_envelope_array(
-    conn: sqlite3.Connection,
-    limit: int = 100,
-) -> list[dict]:
-    """Return the ``alerts`` array for the SSE snapshot envelope.
-
-    Union of ``percent_milestones``, ``five_hour_milestones``, and
-    ``budget_milestones`` rows with ``alerted_at IS NOT NULL``, ordered
-    newest-first by ``alerted_at``, capped at ``limit`` (default 100).
-    Single source of truth for both the dashboard panel (slices to 10
-    client-side) and the modal (renders all 100). Forward-only
-    semantics: only rows the alert-dispatch path stamped get included;
-    pre-deploy crossings stay NULL and are intentionally invisible
-    (spec §4.3).
+# === Alerts-envelope per-axis row-mappers (Task F) =========================
+# Each mapper turns one axis's ``alerted_at IS NOT NULL`` milestone rows into
+# the shared envelope-item dicts. The SQL is genuinely heterogeneous per axis
+# (Codex P0-3: distinct columns, JOINs, id shapes), so the registry unifies the
+# *set* of axes + their ``milestone_table`` + the shared ``severity_for``
+# authority, not the query itself. ``descriptor.milestone_table`` drives each
+# ``FROM`` clause so the table name lives in the registry, not inlined here.
 
-    All three axes share the same envelope schema; the ``axis`` field
-    (``weekly`` / ``five_hour`` / ``budget``) discriminates.
 
-    Per-axis ``LIMIT`` is applied at the SQL level (each query may yield
-    up to ``limit``) and the union is re-sorted + sliced — important for
-    the boundary case where one axis has ``limit`` rows and the other
-    has more recent ones that would otherwise be dropped before the
-    final sort.
-    """
-    out: list[dict] = []
+def _envelope_rows_weekly(conn, descriptor, limit, severity_for) -> list[dict]:
     # ``reset_event_id`` (v1.7.2) segments the same (week, threshold)
     # across pre-credit (0) and post-credit (event.id) cohorts, both
     # of which can be alerted. The envelope id must include the
@@ -4097,25 +4086,27 @@ def _build_alerts_envelope_array(
     # collide on the duplicate (week, threshold) pair. Older clients
     # tolerate longer ids — the id is opaque to them; only the React
     # key uniqueness invariant matters.
-    weekly_rows = conn.execute(
-        """
+    rows = conn.execute(
+        f"""
         SELECT week_start_date, percent_threshold, captured_at_utc,
                alerted_at, cumulative_cost_usd, reset_event_id
-        FROM percent_milestones
+        FROM {descriptor.milestone_table}
         WHERE alerted_at IS NOT NULL
         ORDER BY alerted_at DESC
         LIMIT ?
         """,
         (limit,),
     ).fetchall()
-    for r in weekly_rows:
+    out: list[dict] = []
+    for r in rows:
         threshold = int(r["percent_threshold"])
         cumulative = float(r["cumulative_cost_usd"])
         dpp = (cumulative / threshold) if threshold else None
         out.append({
             "id": f"weekly:{r['week_start_date']}:{threshold}:{r['reset_event_id']}",
-            "axis": "weekly",
+            "axis": descriptor.id,
             "threshold": threshold,
+            "severity": severity_for(threshold),
             "crossed_at": r["captured_at_utc"],
             "alerted_at": r["alerted_at"],
             "context": {
@@ -4132,20 +4123,22 @@ def _build_alerts_envelope_array(
                 "reset_event_id":      int(r["reset_event_id"]),
             },
         })
+    return out
+
 
+def _envelope_rows_five_hour(conn, descriptor, limit, severity_for) -> list[dict]:
     # Site F (spec §3.2 bucket C / §3.3): widen the row identity to
     # include ``reset_event_id`` so post-credit (seg=event.id) crossings
     # of the same (window_key, threshold) don't collide with pre-credit
     # (seg=0) crossings on the React row key. Older clients tolerate
     # longer ids — the id is opaque to them; only the React key
-    # uniqueness invariant matters. Mirrors the weekly precedent at
-    # line ~2597.
-    fh_rows = conn.execute(
-        """
+    # uniqueness invariant matters. Mirrors the weekly precedent.
+    rows = conn.execute(
+        f"""
         SELECT m.five_hour_window_key, m.percent_threshold, m.captured_at_utc,
                m.alerted_at, m.block_cost_usd, m.reset_event_id,
                b.block_start_at
-        FROM five_hour_milestones m
+        FROM {descriptor.milestone_table} m
         LEFT JOIN five_hour_blocks b ON b.five_hour_window_key = m.five_hour_window_key
         WHERE m.alerted_at IS NOT NULL
         ORDER BY m.alerted_at DESC
@@ -4153,15 +4146,17 @@ def _build_alerts_envelope_array(
         """,
         (limit,),
     ).fetchall()
-    for r in fh_rows:
+    out: list[dict] = []
+    for r in rows:
         threshold = int(r["percent_threshold"])
         out.append({
             "id":          (
                 f"five_hour:{int(r['five_hour_window_key'])}:"
                 f"{threshold}:{int(r['reset_event_id'])}"
             ),
-            "axis":        "five_hour",
+            "axis":        descriptor.id,
             "threshold":   threshold,
+            "severity":    severity_for(threshold),
             "crossed_at":  r["captured_at_utc"],
             "alerted_at":  r["alerted_at"],
             "context": {
@@ -4171,7 +4166,10 @@ def _build_alerts_envelope_array(
                 "reset_event_id":       int(r["reset_event_id"]),
             },
         })
+    return out
+
 
+def _envelope_rows_budget(conn, descriptor, limit, severity_for) -> list[dict]:
     # Third axis (issue #19): equiv-$ budget threshold crossings. Budget
     # alerts are keyed by the effective (post-reset) week_start_at + the
     # integer threshold; the envelope id mirrors the dispatch payload's
@@ -4179,23 +4177,25 @@ def _build_alerts_envelope_array(
     # (``_build_alert_payload_budget``). No ``reset_event_id`` segment —
     # a mid-week reset re-anchors ``week_start_at`` so the new window
     # naturally gets fresh rows under ``UNIQUE(week_start_at, threshold)``.
-    budget_rows = conn.execute(
-        """
+    rows = conn.execute(
+        f"""
         SELECT week_start_at, threshold, crossed_at_utc, alerted_at,
                budget_usd, spent_usd, consumption_pct
-        FROM budget_milestones
+        FROM {descriptor.milestone_table}
         WHERE alerted_at IS NOT NULL
         ORDER BY alerted_at DESC
         LIMIT ?
         """,
         (limit,),
     ).fetchall()
-    for r in budget_rows:
+    out: list[dict] = []
+    for r in rows:
         threshold = int(r["threshold"])
         out.append({
             "id":         f"budget:{r['week_start_at']}:{threshold}",
-            "axis":       "budget",
+            "axis":       descriptor.id,
             "threshold":  threshold,
+            "severity":   severity_for(threshold),
             "crossed_at": r["crossed_at_utc"],
             "alerted_at": r["alerted_at"],
             "context": {
@@ -4205,12 +4205,115 @@ def _build_alerts_envelope_array(
                 "consumption_pct": float(r["consumption_pct"]),
             },
         })
+    return out
+
+
+def _envelope_rows_projected(conn, descriptor, limit, severity_for) -> list[dict]:
+    # Fourth axis (issue #121): projected-pace threshold crossings. Like
+    # budget, projected alerts re-anchor ``week_start_at`` on a mid-week
+    # reset, so there is NO ``reset_event_id`` segment — the new window gets
+    # fresh rows under ``UNIQUE(week_start_at, metric, threshold)``. The
+    # ``metric`` discriminator (``weekly_pct`` | ``budget_usd``) drives the
+    # frontend's metric-aware context renderer; ``denominator`` +
+    # ``projected_value`` are rendered FROM THE ROW (the values snapshotted at
+    # crossing), never live config that may have changed since (Codex P0-4).
+    # The envelope id mirrors the dispatch payload's
+    # ``projected:<week_start_at>:<metric>:<threshold>`` shape.
+    rows = conn.execute(
+        f"""
+        SELECT week_start_at, metric, threshold, projected_value,
+               denominator, crossed_at_utc, alerted_at
+        FROM {descriptor.milestone_table}
+        WHERE alerted_at IS NOT NULL
+        ORDER BY alerted_at DESC
+        LIMIT ?
+        """,
+        (limit,),
+    ).fetchall()
+    out: list[dict] = []
+    for r in rows:
+        threshold = int(r["threshold"])
+        metric = str(r["metric"])
+        out.append({
+            "id":         f"projected:{r['week_start_at']}:{metric}:{threshold}",
+            "axis":       descriptor.id,
+            "metric":     metric,
+            "threshold":  threshold,
+            "severity":   severity_for(threshold),
+            "crossed_at": r["crossed_at_utc"],
+            "alerted_at": r["alerted_at"],
+            "context": {
+                "week_start_at":   r["week_start_at"],
+                "metric":          metric,
+                "projected_value": float(r["projected_value"]),
+                "denominator":     float(r["denominator"]),
+            },
+        })
+    return out
+
+
+# Keyed by ``AlertAxisDescriptor.id`` — the registry decides which axes run,
+# in what order; this table supplies the bespoke heterogeneous row-mapper.
+_ENVELOPE_AXIS_MAPPERS = {
+    "weekly": _envelope_rows_weekly,
+    "five_hour": _envelope_rows_five_hour,
+    "budget": _envelope_rows_budget,
+    "projected": _envelope_rows_projected,
+}
+
+
+def _build_alerts_envelope_array(
+    conn: sqlite3.Connection,
+    limit: int = 100,
+) -> list[dict]:
+    """Return the ``alerts`` array for the SSE snapshot envelope.
+
+    Union of ``percent_milestones``, ``five_hour_milestones``,
+    ``budget_milestones``, and ``projected_milestones`` rows with
+    ``alerted_at IS NOT NULL``, ordered newest-first by ``alerted_at``,
+    capped at ``limit`` (default 100). Single source of truth for both the
+    dashboard panel (slices to 10 client-side) and the modal (renders all
+    100). Forward-only semantics: only rows the alert-dispatch path stamped
+    get included; pre-deploy crossings stay NULL and are intentionally
+    invisible (spec §4.3).
+
+    All four axes share the same envelope schema; the ``axis`` field
+    (``weekly`` / ``five_hour`` / ``budget`` / ``projected``) discriminates.
+    The ``projected`` axis additionally carries a top-level ``metric``
+    (``weekly_pct`` | ``budget_usd``) so the frontend can pick its
+    metric-aware context renderer.
+
+    Per-axis ``LIMIT`` is applied at the SQL level (each query may yield
+    up to ``limit``) and the union is re-sorted + sliced — important for
+    the boundary case where one axis has ``limit`` rows and the other
+    has more recent ones that would otherwise be dropped before the
+    final sort.
+
+    **Registry-driven (Task F).** The *set* of axes, their union *order*,
+    and each axis's ``milestone_table`` come from
+    ``_lib_alert_axes.AXIS_REGISTRY`` — adding a future axis is "register a
+    descriptor + add a row-mapper", not "hand-roll a parallel branch". The
+    SQL stays genuinely heterogeneous per axis (Codex P0-3: different
+    columns, JOINs, id shapes), so each descriptor pairs with a bespoke
+    row-mapper keyed by ``descriptor.id`` in ``_ENVELOPE_AXIS_MAPPERS``. The
+    shared ``severity_for`` kernel stamps the additive ``severity`` field on
+    every item (single severity authority, consumed by the frontend too).
+    """
+    c = _cctally()
+    registry = c.AXIS_REGISTRY
+    severity_for = c.severity_for
+    out: list[dict] = []
+    for descriptor in registry:
+        mapper = _ENVELOPE_AXIS_MAPPERS.get(descriptor.id)
+        if mapper is None:  # pragma: no cover - registry/mapper drift guard
+            continue
+        out.extend(mapper(conn, descriptor, limit, severity_for))
 
     # Python's list.sort is stable. When two alerts share the same
     # `alerted_at` ISO string (rare; multiple axes firing within the same
-    # millisecond), the union order (weekly, then 5h, then budget)
-    # determines the tiebreaker — no extra deterministic key is added
-    # because the spec doesn't require one.
+    # millisecond), the union order (weekly, then 5h, then budget, then
+    # projected) determines the tiebreaker — no extra deterministic key is
+    # added because the spec doesn't require one.
     out.sort(key=lambda a: a["alerted_at"], reverse=True)
     return out[:limit]
 
@@ -4583,6 +4686,7 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
             "enabled": False,
             "weekly_thresholds": [],
             "five_hour_thresholds": [],
+            "projected_enabled": False,
         }
     # Budget is its OWN config block (issue #19) — source budget fields
     # from ``_get_budget_config`` (the validated ``budget`` block), NOT
@@ -4592,13 +4696,18 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
         _budget_cfg = _get_budget_config(_cfg_for_alerts)
     except _BudgetConfigError:
         _budget_cfg = {"weekly_usd": None, "alerts_enabled": True,
-                       "alert_thresholds": []}
+                       "alert_thresholds": [], "projected_enabled": False}
     alerts_settings = {
         "enabled":              _alerts_cfg["enabled"],
         "weekly_thresholds":    list(_alerts_cfg["weekly_thresholds"]),
         "five_hour_thresholds": list(_alerts_cfg["five_hour_thresholds"]),
         "budget_thresholds":    list(_budget_cfg["alert_thresholds"]),
         "budget_enabled":       _budget_alerts_active(_budget_cfg),
+        # Projected-pace opt-in mirrors (#121). Two flags, one per parent
+        # axis — the frontend SettingsOverlay seeds two toggles. Sourced
+        # from the validated getters' ``projected_enabled`` (default False).
+        "projected_weekly_enabled": bool(_alerts_cfg.get("projected_enabled")),
+        "projected_budget_enabled": bool(_budget_cfg.get("projected_enabled")),
     }
 
     # Mirror update-state.json + update-suppress.json into the envelope
@@ -5182,16 +5291,17 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         "update"?: {"check"?: {"enabled"?: bool, "ttl_hours"?: int}},
         "cache_report"?: {"anomaly_threshold_pp"?: int},
         "budget"?: {"weekly_usd"?: number|null, "alerts_enabled"?: bool,
-        "alert_thresholds"?: int[]}}`` — every top-level key is optional;
-        any subset may be sent together (combined save). Unknown
-        top-level keys are rejected with 400.
+        "alert_thresholds"?: int[], "projected_enabled"?: bool}}`` — every
+        top-level key is optional; any subset may be sent together
+        (combined save). Unknown top-level keys are rejected with 400.
 
         Per-block validation:
           * ``display.tz`` — "local", "utc", or a valid IANA zone (via
             ``normalize_display_tz_value``); 400 on invalid.
-          * ``alerts`` — must be a dict; ``alerts.enabled`` must be a
-            JSON boolean (string "yes"/"true" rejected, per spec). Merged
-            block is validated via ``_get_alerts_config(merged)``;
+          * ``alerts`` — must be a dict; ``alerts.enabled`` and
+            ``alerts.projected_enabled`` must each be a JSON boolean
+            (string "yes"/"true" rejected, per spec). Merged block is
+            validated via ``_get_alerts_config(merged)``;
             ``_AlertsConfigError`` → 400.
           * ``update.check.enabled`` — JSON bool; 400 on type mismatch.
           * ``update.check.ttl_hours`` — JSON int (NOT string), in
@@ -5203,10 +5313,12 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             ``{error, field: "anomaly_threshold_pp"}`` on out-of-range
             or non-int. Spec §6.1 hardcodes ``anomaly_window_days``;
             F10 tracks lifting that.
-          * ``budget`` — must be a dict; merged onto the persisted
-            ``budget`` block and validated via ``_get_budget_config(merged)``
-            (issue #19); ``_BudgetConfigError`` → 400. Budget is its OWN
-            config block, distinct from ``alerts``.
+          * ``budget`` — must be a dict; the inbound leaves
+            (``weekly_usd`` / ``alerts_enabled`` / ``alert_thresholds`` /
+            ``projected_enabled``) are merged onto the persisted ``budget``
+            block and validated via ``_get_budget_config(merged)`` (issue
+            #19, projected toggle #121); ``_BudgetConfigError`` → 400.
+            Budget is its OWN config block, distinct from ``alerts``.
 
         Atomic merged write: if all touched blocks validate, the merged
         config is persisted in a single ``save_config`` call inside the
@@ -5367,6 +5479,14 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                     {"error": "alerts.enabled must be a JSON boolean"},
                 )
                 return
+            if "projected_enabled" in alerts_block and not isinstance(
+                alerts_block["projected_enabled"], bool
+            ):
+                self._respond_json(
+                    400,
+                    {"error": "alerts.projected_enabled must be a JSON boolean"},
+                )
+                return
 
         # Pre-validate budget shape (the structural type check; full
         # cross-key validation runs inside the lock via
@@ -5478,6 +5598,10 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 alerts_in = payload["alerts"]
                 if "enabled" in alerts_in:
                     merged_alerts["enabled"] = alerts_in["enabled"]
+                if "projected_enabled" in alerts_in:
+                    merged_alerts["projected_enabled"] = (
+                        alerts_in["projected_enabled"]
+                    )
                 merged["alerts"] = merged_alerts
                 # Final cross-field validation against the merged block.
                 # _AlertsConfigError → 400 (no partial write since
@@ -5504,7 +5628,10 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                     return
                 merged_budget = dict(existing_budget or {})
                 budget_in = payload["budget"]
-                for leaf in ("weekly_usd", "alerts_enabled", "alert_thresholds"):
+                for leaf in (
+                    "weekly_usd", "alerts_enabled", "alert_thresholds",
+                    "projected_enabled",
+                ):
                     if leaf in budget_in:
                         merged_budget[leaf] = budget_in[leaf]
                 merged["budget"] = merged_budget
@@ -5641,8 +5768,11 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         dispatch status string in the JSON response.
 
         Body (all fields optional): ``{"axis":
-        "weekly"|"five_hour"|"budget", "threshold": 1..100}``. Defaults:
-        axis="weekly", threshold=90.
+        "weekly"|"five_hour"|"budget"|"projected", "threshold": 1..100,
+        "metric": "weekly_pct"|"budget_usd"}``. Defaults: axis="weekly",
+        threshold=90, metric="weekly_pct". ``metric`` is only consulted for
+        the ``projected`` axis (mirrors the CLI ``alerts test --axis
+        projected --metric`` surface); it is ignored for the other axes.
 
         IMPORTANT: ``axis`` uses the underscore form (``"five_hour"``)
         in the JSON API to match the dispatch payload's internal axis
@@ -5681,12 +5811,25 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 return
 
         axis = body.get("axis", "weekly")
-        if axis not in ("weekly", "five_hour", "budget"):
+        if axis not in ("weekly", "five_hour", "budget", "projected"):
+            self._respond_json(
+                400,
+                {"error": (
+                    "axis must be 'weekly', 'five_hour', 'budget' or "
+                    f"'projected', got {axis!r}"
+                )},
+            )
+            return
+        # ``metric`` discriminates the projected axis (weekly_pct vs
+        # budget_usd); the other axes ignore it. Validate only when it
+        # matters so a stray metric on a weekly/budget test isn't a 400.
+        metric = body.get("metric", "weekly_pct")
+        if axis == "projected" and metric not in ("weekly_pct", "budget_usd"):
             self._respond_json(
                 400,
                 {"error": (
-                    "axis must be 'weekly', 'five_hour' or 'budget', "
-                    f"got {axis!r}"
+                    "metric must be 'weekly_pct' or 'budget_usd', "
+                    f"got {metric!r}"
                 )},
             )
             return
@@ -5724,6 +5867,28 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 spent_usd=300.0 * threshold / 100.0,
                 consumption_pct=float(threshold),
             )
+        elif axis == "projected":
+            # Synthetic projected-pace payload — mirrors the CLI
+            # cmd_alerts_test projected branch (NO DB writes, test/real
+            # divergence contract). The metric discriminator picks the
+            # wiring; projected_value is the threshold's denominator-relative
+            # value (so the body reads plausibly, e.g. weekly 100% → "~100% of
+            # cap", budget 100% → "$300 of $300"). denominator is the
+            # at-crossing target the row would carry (Codex P0-4): 100.0 for
+            # weekly_pct, $300 for budget_usd.
+            if metric == "budget_usd":
+                denominator = 300.0
+                projected_value = 300.0 * threshold / 100.0
+            else:  # weekly_pct
+                denominator = 100.0
+                projected_value = float(threshold)
+            payload = _build_alert_payload_projected(
+                metric=metric,
+                threshold=threshold,
+                projected_value=projected_value,
+                denominator=denominator,
+                week_start_at=dt.date.today().isoformat(),
+            )
         else:
             payload = _build_alert_payload_five_hour(
                 threshold=threshold,

package/bin/_cctally_forecast.py

@@ -266,7 +266,9 @@ def _resolve_current_budget_window(conn, now_utc):
     return (week_start_at, week_end_at)
 
 
-def _build_budget_status_inputs(conn, *, target_usd, now_utc, alert_thresholds):
+def _build_budget_status_inputs(
+    conn, *, target_usd, now_utc, alert_thresholds, skip_sync=False
+):
     """Gather live spend over the current subscription week and build a
     :class:`BudgetInputs`. Returns ``None`` when no week window resolves.
 
@@ -280,19 +282,29 @@ def _build_budget_status_inputs(conn, *, target_usd, now_utc, alert_thresholds):
     (``max(week_start_at, now - 24h)``) so a heavy spend just before reset
     can't leak last week's dollars into a fresh week's verdict (false
     WARN/OVER).
+
+    ``skip_sync`` skips the JSONL ingest pass inside ``get_entries`` for BOTH
+    cost SUMs — used by the projected-pace record path, where the actual-budget
+    axis already ran ``_sum_cost_for_range`` (warming the cache) earlier in the
+    same ``cmd_record_usage`` tick. The default ``False`` preserves the
+    standalone ``budget`` command's sync-on-read behavior unchanged.
     """
     c = _cctally()
     window = _resolve_current_budget_window(conn, now_utc)
     if window is None:
         return None
     week_start_at, week_end_at = window
-    spent = c._sum_cost_for_range(week_start_at, now_utc, mode="auto")
+    spent = c._sum_cost_for_range(
+        week_start_at, now_utc, mode="auto", skip_sync=skip_sync
+    )
     # Clamp the recent-rate window at the week start: both bounds are tz-aware
     # so max() is well-defined. Without this, a brand-new week (now < week
     # start + 24h) would pull pre-reset spend into rate_recent and flip a
     # fresh verdict to warn/over.
     recent_start = max(week_start_at, now_utc - dt.timedelta(hours=24))
-    recent_24h = c._sum_cost_for_range(recent_start, now_utc, mode="auto")
+    recent_24h = c._sum_cost_for_range(
+        recent_start, now_utc, mode="auto", skip_sync=skip_sync
+    )
     return c.BudgetInputs(
         target_usd=float(target_usd),
         spent_usd=float(spent),
@@ -497,6 +509,7 @@ class ForecastOutput:
     r_recent: float | None         # pct per hour, 24h recent; None if no prior sample
     final_percent_low: float
     final_percent_high: float
+    week_avg_projection_pct: float  # p_now + r_avg*remaining (smooth estimator)
     projected_cap: bool
     already_capped: bool
     cap_at: dt.datetime | None
@@ -527,6 +540,12 @@ def _compute_forecast(inputs: ForecastInputs, targets: list[int]) -> ForecastOut
         )
         final_low, final_high = min(a, b), max(a, b)
 
+    # Smooth week-average projection (additive surface field). Distinct from
+    # the displayed band (which keys off final_high): this is the conservative
+    # week-average value the projected-pace alert axis fires on.
+    # p_now + r_avg*remaining (== project_linear collapsed to the single rate).
+    week_avg_projection_pct = inputs.p_now + r_avg * inputs.remaining_hours
+
     already_capped = inputs.p_now >= 100.0
     projected_cap = already_capped or final_high >= 100.0
 
@@ -562,6 +581,7 @@ def _compute_forecast(inputs: ForecastInputs, targets: list[int]) -> ForecastOut
         r_recent=r_recent,
         final_percent_low=final_low,
         final_percent_high=final_high,
+        week_avg_projection_pct=week_avg_projection_pct,
         projected_cap=projected_cap,
         already_capped=already_capped,
         cap_at=cap_at,
@@ -628,6 +648,7 @@ def _build_forecast_json_payload(out: ForecastOutput) -> dict:
         "forecast": {
             "final_percent_low":  round(out.final_percent_low, 3),
             "final_percent_high": round(out.final_percent_high, 3),
+            "week_avg_projection_pct": round(out.week_avg_projection_pct, 3),
             "projected_cap":      out.projected_cap,
             "cap_at":             (None if out.cap_at is None else _iso_z(out.cap_at)),
             "already_capped":     out.already_capped,
@@ -1818,6 +1839,7 @@ def _budget_emit_json(budget_cfg, inputs, status) -> int:
         "elapsed_fraction": status.elapsed_fraction,
         "projected_eow_low_usd": status.projected_eow_low_usd,
         "projected_eow_high_usd": status.projected_eow_high_usd,
+        "week_avg_projection_usd": status.week_avg_projection_usd,
         "daily_pace_usd": status.daily_pace_usd,
         "daily_budget_remaining_usd": status.daily_budget_remaining_usd,
         "verdict": status.verdict,

package/bin/_cctally_milestones.py

@@ -369,6 +369,74 @@ def insert_budget_milestone(
     return int(cur.rowcount)
 
 
+def insert_projected_milestone(
+    conn: sqlite3.Connection,
+    *,
+    week_start_at: str,
+    metric: str,
+    threshold: int,
+    projected_value: float,
+    denominator: float,
+    commit: bool = True,
+) -> 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).
+
+    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.
+    """
+    cur = conn.execute(
+        "INSERT OR IGNORE INTO projected_milestones "
+        "(week_start_at, metric, threshold, projected_value, denominator, "
+        " crossed_at_utc) "
+        "VALUES (?, ?, ?, ?, ?, ?)",
+        (
+            week_start_at,
+            str(metric),
+            int(threshold),
+            float(projected_value),
+            float(denominator),
+            now_utc_iso(),
+        ),
+    )
+    if commit:
+        conn.commit()
+    return int(cur.rowcount)
+
+
+def _projected_levels_already_latched(
+    conn: sqlite3.Connection,
+    *,
+    week_start_at: str,
+    metric: str,
+    levels: "tuple[int, ...]",
+) -> bool:
+    """True iff EVERY level in ``levels`` already has a row for
+    ``(week_start_at, 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`.
+    """
+    if not levels:
+        return True
+    rows = conn.execute(
+        "SELECT threshold FROM projected_milestones "
+        "WHERE week_start_at = ? AND metric = ?",
+        (week_start_at, 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

package/bin/_cctally_parser.py

@@ -2186,14 +2186,15 @@ def build_parser() -> argparse.ArgumentParser:
               cctally alerts test
               cctally alerts test --axis five-hour --threshold 95
               cctally alerts test --axis budget --threshold 100
+              cctally alerts test --axis projected --metric budget_usd
         """),
     )
     p_alerts_test.add_argument(
         "--axis",
-        choices=["weekly", "five-hour", "budget"],
+        choices=["weekly", "five-hour", "budget", "projected"],
         default="weekly",
         help="Alert axis to simulate: weekly subscription window, 5h block, "
-             "or equiv-$ budget (default: weekly).",
+             "equiv-$ budget, or projected-pace (default: weekly).",
     )
     p_alerts_test.add_argument(
         "--threshold",
@@ -2201,6 +2202,13 @@ def build_parser() -> argparse.ArgumentParser:
         default=90,
         help="Threshold percent (1-100, default: 90).",
     )
+    p_alerts_test.add_argument(
+        "--metric",
+        choices=["weekly_pct", "budget_usd"],
+        default="weekly_pct",
+        help="For --axis projected: which projected metric to preview "
+             "(default: weekly_pct).",
+    )
     p_alerts_test.set_defaults(func=c.cmd_alerts_test)
 
     # ---- setup (onboarding spec §2) ----