cctally 1.103.0 → 1.104.0

package/bin/_cctally_dashboard_envelope.py

@@ -824,6 +824,68 @@ def _source_bundle_to_envelope(bundle: object | None) -> dict:
         }
 
 
+#: How many rate-change events the envelope publishes. A metering-rate
+#: transition is rare — the maintainer's store holds one — so this is a
+#: bound rather than a page size, and a store holding more than a handful
+#: describes a detector that is misfiring rather than a busy account.
+METER_RATE_CHANGE_LIMIT = 20
+
+
+def _build_meter_rate_change_array(
+    conn: sqlite3.Connection, limit: int = METER_RATE_CHANGE_LIMIT,
+) -> list:
+    """The #661 S2 §6.1 non-threshold event family's wire rows.
+
+    A SEPARATE array from `alerts`, and deliberately so. Every member of
+    `AXIS_REGISTRY` is a numeric threshold axis: `AlertEntry` requires a
+    numeric `threshold`, its `id` is threshold-shaped, and `alert_row_owner`
+    raises on a seventh axis so that adding one without deciding its
+    ownership fails a test rather than shipping an invisible row. A rate
+    transition has neither a threshold nor a threshold-derived severity, so
+    it gets its own discriminated variant instead of being forced into that
+    union.
+
+    Each row carries the explicit severity, the old and new rates, the
+    effective instant, its OWNERSHIP (which provider tab renders it) and its
+    SCOPE (the account, decorated under R8 exactly as the alert rows are).
+    """
+    account_fields = _alert_account_resolver(conn)
+    try:
+        rows = conn.execute(
+            "SELECT provider, account_key, effective_from,"
+            "       previous_units_per_point, new_units_per_point, severity,"
+            "       detected_at_utc, created_at_utc"
+            "  FROM meter_rate_change_events"
+            " ORDER BY unixepoch(effective_from) DESC, id DESC"
+            " LIMIT ?", (int(limit),)).fetchall()
+    except sqlite3.Error:
+        # A store predating epoch 1011 has no such table, and the rebuild
+        # that creates it is deferred to a background worker. An empty array
+        # renders as "no change recorded", which is the truth on that store.
+        return []
+    out: list[dict] = []
+    for (provider, account_key, effective_from, previous, new, severity,
+         detected_at, created_at) in rows:
+        entry = {
+            # Opaque React key. It is never parsed — the same contract the
+            # alert `id` carries.
+            "id": f"meter_rate_change:{provider}:{account_key}:{effective_from}",
+            "family": "meter_rate_change",
+            "provider": str(provider),
+            "owner": str(provider),
+            "severity": str(severity or "info"),
+            "effective_from": str(effective_from),
+            "detected_at": str(detected_at or created_at or ""),
+            "recorded_at": str(created_at or ""),
+            "previous_units_per_point": (
+                None if previous is None else float(previous)),
+            "new_units_per_point": None if new is None else float(new),
+        }
+        entry.update(account_fields(str(provider), account_key))
+        out.append(entry)
+    return out
+
+
 def _build_alerts_envelope_array(
     conn: sqlite3.Connection,
     limit: int = 100,
@@ -1103,6 +1165,222 @@ def _sync_activity_envelope(activity: "dict | None") -> dict:
     }
 
 
+#: How far two subscription-week anchors may drift and still count as the
+#: same reset domain. The week anchor is normalized to the hour to absorb
+#: Anthropic's reset jitter, so two hours is comfortably wider than the
+#: jitter and far narrower than the shortest interval a synthesized
+#: mid-week row could produce.
+_RESET_DOMAIN_TOLERANCE_SECONDS = 2 * 3600
+_SUBSCRIPTION_WEEK_SECONDS = 7 * 24 * 3600
+
+
+def _same_reset_domain(current_start, prior_start) -> bool:
+    """Whether two week anchors belong to the same reset domain.
+
+    Spec §10.1 requires the prior operand to share the current row's reset
+    domain. The rows carry no domain field, so it is derived from the one
+    thing they always carry: two anchors are in the same domain when they
+    are a whole number of subscription weeks apart. A row synthesized by
+    reset or credit handling sits at a fractional offset and is skipped
+    rather than silently used, which is exactly what that clause is for.
+    """
+    if current_start is None or prior_start is None:
+        return False
+    delta = (current_start - prior_start).total_seconds()
+    if delta <= 0:
+        return False
+    offset = delta % _SUBSCRIPTION_WEEK_SECONDS
+    return min(offset, _SUBSCRIPTION_WEEK_SECONDS - offset) <= \
+        _RESET_DOMAIN_TOLERANCE_SECONDS
+
+
+def _cause_presentation(code):
+    """The §8 presentation fields for one cause, or None for no cause.
+
+    ADDITIVE beside the machine `code`, which is unchanged and stays the
+    stable value a client keys on. A client that receives no presentation
+    fields — a new tab against an older server, which `execvp` makes
+    ordinary — derives the short token from the code itself through the same
+    named function this uses.
+    """
+    if not code:
+        return None
+    try:
+        copy = sys.modules["cctally"]._load_sibling("_lib_quota_copy")
+    except Exception:                                  # noqa: BLE001
+        return None
+    out = copy.presentation(code)
+    return out or None
+
+
+def _forecast_quota_envelope(fc, cw, rate_change):
+    """Spec §10's optional typed `forecast.quota` object.
+
+    Additive, and deliberately does NOT bump `source_schema_version`: that
+    field describes the provider-source bundles, not this.
+
+    Every quantity here was already computed. The basis, the codes, the
+    corrected interval and the calibrated triple come off the forecast the
+    envelope is already serializing, and `rate_change` is the caller's cheap
+    calibration-file read. Nothing here opens a store.
+
+    NO PRESENTATION LATCH: this is rebuilt from the current forecast on
+    every refresh, so the surface switches with the shared selector rather
+    than presenting a model whose evidence has since been withheld.
+    """
+    if fc is None:
+        return None
+    inputs = getattr(fc, "inputs", None)
+    interval = getattr(inputs, "p_now_interval", None)
+    code = getattr(fc, "projection_code", None)
+    calibration_code = getattr(inputs, "calibrated_withheld_code", None)
+    consumption = getattr(inputs, "calibrated_consumption_pct", None)
+    consumption_interval = getattr(
+        inputs, "calibrated_consumption_interval", None)
+    observed = getattr(cw, "used_pct", None) if cw is not None else None
+    basis = getattr(fc, "projection_basis", None)
+    projection = getattr(fc, "week_avg_projection_pct", None)
+    headroom = getattr(inputs, "calibrated_headroom_pct", None)
+    # The calibrated view is published as a UNIT (#661 S2 review, D2).
+    #
+    # `select_projection_basis` reads ONLY `calibrated_projection_pct`, so a
+    # non-null projection beside a null modelled consumption would publish
+    # `basis: "calibrated"` over a number the model does not state — a modal
+    # reading "basis: model" above "modelled consumption: —". The invariant
+    # held until now only because `_calibrated_week_detail` sets the whole
+    # triple or none of it, which is the producer's discipline rather than a
+    # property of this serializer.
+    #
+    # WITHHELD rather than demoted. Demoting to `corrected-meter` would
+    # relabel a number the calibrated model produced, and the meter's own
+    # projection is not on this forecast to substitute, so there is nothing
+    # honest to publish. `withheld` is an already-rendered basis on the panel
+    # and in the modal, and it carries a cause.
+    # `projection is None` is included for completeness rather than because
+    # it is reachable: `select_projection_basis` reads `calibrated_projection_pct`,
+    # so a null projection does not yield this basis in the first place, and
+    # `bin/_lib_forecast.py` nulls the projection only on its WITHHELD branch.
+    # The argument that motivates the other two operands -- that the whole
+    # triple is the producer's discipline and not a property of this
+    # serializer -- applies to the projection identically, so leaving it out
+    # would make the guard state a narrower invariant than the one it means.
+    if basis == "calibrated" and (projection is None
+                                  or consumption is None
+                                  or headroom is None):
+        basis = "withheld"
+        projection = None
+        consumption = None
+        consumption_interval = None
+        headroom = None
+        code = code or "unavailable"
+        calibration_code = calibration_code or "unavailable"
+    return {
+        "basis":              basis,
+        "projection_pct":     projection,
+        "right_censored":     bool(getattr(fc, "right_censored", False)),
+        # The cause of a WITHHELD projection, and separately why the
+        # CALIBRATED basis was not reached. They are different questions and
+        # a surface that collapses them says nothing when it falls back.
+        "code":               code,
+        "code_presentation":  _cause_presentation(code),
+        "calibration_code":   calibration_code,
+        "calibration_code_presentation":
+            _cause_presentation(calibration_code),
+        # The corrected-meter interval a displayed reading denotes. `hi` is
+        # null at a right-censored 100, which is unbounded above.
+        "corrected_interval":
+            None if interval is None
+            else {"lo": interval[0], "hi": interval[1]},
+        "calibrated_consumption_pct": consumption,
+        "calibrated_consumption_interval":
+            None if not consumption_interval
+            else {"lo": consumption_interval[0],
+                  "hi": consumption_interval[1]},
+        "calibrated_headroom_pct": headroom,
+        "rate_change":        rate_change,
+        # Spec §10: the observed meter minus the modelled local quota,
+        # labelled as exactly that. It is a DIFFERENCE between two
+        # quantities and does not identify or estimate usage from another
+        # machine; the modal states that sentence, and it is null unless
+        # both sides exist.
+        "observed_minus_modelled_pct":
+            None if (observed is None or consumption is None)
+            else observed - consumption,
+    }
+
+
+def _header_rate_and_delta(current_rate, current_week_start, trend):
+    """`(dollar_per_pct, vs_last_week_delta)` from ONE current operand.
+
+    Spec §10.1, and the defect it closes: `header.dollar_per_pct` came from
+    `_tui_build_current_week` while `header.vs_last_week_delta` came from the
+    operand `build_trend_view` returned. Two computations, no guard, so the
+    hero could publish a week-over-week comparison on a screen stating no
+    `$ / 1%` at all.
+
+    Both values are computed here, from the header's own current operand,
+    before serialization — so the client never reconciles two differently
+    sourced "current" values. When the current rate is absent BOTH are null,
+    because a delta measured from an absent operand is not a delta.
+
+    The prior operand is the NEAREST COMPARABLE completed row, and
+    comparable is the exact list §10.1 gives. Provider and account scope are
+    properties of the whole snapshot, so every row in `trend` shares them by
+    construction; what has to be tested per row is the remaining three:
+
+      * a completed rather than current interval (`is_current` is False);
+      * a non-null rate on that row; and
+      * the same reset domain as the current week.
+
+    A row failing any of them is SKIPPED and the walk continues to the next
+    older row, rather than the delta being abandoned or the row being used.
+
+    NEAREST IS BY ANCHOR, not by list position. The walk used to be
+    `reversed(list(trend))`, which makes "nearest" mean "last in the list" and
+    rests the whole clause on `snap.trend` arriving ascending. That holds for
+    `build_trend_view` and for every committed fixture and was stated nowhere,
+    and `_same_reset_domain` accepts any positive whole-week multiple, so a
+    row twenty weeks back was as comparable as one week back. The candidates
+    are therefore ordered here, newest anchor first. A row carrying no anchor
+    sorts last and is skipped by the reset-domain test anyway.
+    """
+    if current_rate is None:
+        return None, None
+    # Only rows whose anchor is a `datetime` are sorted; anything else keeps
+    # list order after them. `sorted` compares the keys, so one naive anchor
+    # beside an aware one -- or a `str` anchor, which the sibling row type at
+    # `bin/_lib_view_models.py:174` carries -- would raise `TypeError` inside
+    # the dashboard's serialization path and surface as a 500 rather than a
+    # withheld figure. `build_trend_view` emits aware datetimes today, so the
+    # partition is a guard against a future producer, not a live defect.
+    # Ties keep list order, because `sorted` is stable: two rows sharing an
+    # anchor resolve to the earlier one in `trend`.
+    rows = list(trend or ())
+    anchored = [r for r in rows
+                if isinstance(getattr(r, "week_start_at", None), dt.datetime)]
+    unanchored = [r for r in rows
+                  if not isinstance(getattr(r, "week_start_at", None),
+                                    dt.datetime)]
+    aware = [r for r in anchored if r.week_start_at.tzinfo is not None]
+    naive = [r for r in anchored if r.week_start_at.tzinfo is None]
+    candidates = (
+        sorted(aware, key=lambda row: row.week_start_at, reverse=True)
+        + sorted(naive, key=lambda row: row.week_start_at, reverse=True)
+        + unanchored
+    )
+    for row in candidates:
+        if getattr(row, "is_current", False):
+            continue
+        prior_rate = getattr(row, "dollars_per_percent", None)
+        if prior_rate is None:
+            continue
+        if not _same_reset_domain(current_week_start,
+                                  getattr(row, "week_start_at", None)):
+            continue
+        return current_rate, current_rate - prior_rate
+    return current_rate, None
+
+
 def snapshot_to_envelope(snap: "DataSnapshot", *,
                          now_utc: "dt.datetime",
                          monotonic_now: "float | None" = None,
@@ -1256,17 +1534,13 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
         inputs = getattr(fc, "inputs", None)
         if inputs is not None:
             confidence = getattr(inputs, "confidence", None)
-        r_avg = getattr(fc, "r_avg", None)
-        r_recent = getattr(fc, "r_recent", None)
-        p_now = getattr(inputs, "p_now", None) if inputs is not None else None
-        rem_hrs = getattr(inputs, "remaining_hours", None) if inputs is not None else None
-        if p_now is not None and rem_hrs is not None and r_avg is not None:
-            fcast_pct = p_now + r_avg * rem_hrs
-        if (p_now is not None and rem_hrs is not None
-                and r_recent is not None):
-            p_final_recent = p_now + r_recent * rem_hrs
-            if fcast_pct is None or p_final_recent != fcast_pct:
-                recent_24h_pct = p_final_recent
+        # The ONE decomposition (#661 S2 spec section 3.3), so this legacy
+        # branch cannot answer the projection question differently from the
+        # View path above it — which is exactly what the `over` golden
+        # recorded before this call replaced the inline arithmetic.
+        from _lib_view_models import _forecast_projection_pcts
+
+        fcast_pct, recent_24h_pct = _forecast_projection_pcts(fc)
         if getattr(fc, "already_capped", False):
             verdict = "capped"
         elif getattr(fc, "projected_cap", False):
@@ -1474,6 +1748,11 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
     # the entire snapshot — fall back to safe defaults and rely on
     # `_warn_alerts_bad_config_once` for the user-visible signal.
     alerts_array = list(getattr(snap, "alerts", []) or [])
+    # #661 S2 §6.1. Precomputed at sync time beside `alerts`, so
+    # `snapshot_to_envelope` stays a pure renderer with no DB I/O on the
+    # dashboard hot path.
+    meter_rate_changes_array = list(
+        getattr(snap, "meter_rate_changes", []) or [])
     # #268 M4: reuse the precompute's config (or the fallback load_config()
     # resolved above) — the envelope used to call load_config() a SECOND time
     # here. Within one tick both reads returned the same file, so this is
@@ -1551,6 +1830,11 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
         # template itself).
         "notifier":           _alerts_cfg.get("notifier", "auto"),
         "command_configured": _alerts_cfg.get("command_template") is not None,
+        # #661 S2 §6.2: the metering-rate-change family's PUSH toggle. The
+        # events themselves are recorded whatever this says, so the client
+        # renders the history with no configuration; this mirror only tells
+        # Settings whether the OS popup is armed.
+        "rate_change_enabled": bool(_alerts_cfg.get("rate_change_enabled")),
     }
     # Dashboard render-prefs mirror (cache-failure-markers opt-out, spec §5).
     # Reuses the single `_cfg_for_alerts = load_config()` read above (no extra
@@ -1666,6 +1950,15 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
         (r for r in reversed(snap.trend) if r.is_current), None
     ) if snap.trend else None
 
+    # #661 S2 §10.1. BOTH header operands are decided here, together, from
+    # the header's own current rate. `_current_trend` is retained above
+    # because other blocks read it, but its `delta_dpp` is no longer what
+    # the header publishes: that field is computed against whichever row
+    # happened to precede the current one in the trend series, which is a
+    # different question from "the nearest comparable prior operand".
+    dollar_pp, header_delta = _header_rate_and_delta(
+        dollar_pp, week_start_at_utc, snap.trend)
+
     envelope = {
         "envelope_version": 2,
         # #278 Theme A: single additive first-paint hydration latch. True only
@@ -1718,9 +2011,7 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
             "dollar_per_pct":     dollar_pp,
             "forecast_pct":       header_fcast_pct,
             "forecast_verdict":   verdict,
-            "vs_last_week_delta": (
-                _current_trend.delta_dpp if _current_trend is not None else None
-            ),
+            "vs_last_week_delta": header_delta,
         },
 
         "current_week":
@@ -1804,6 +2095,12 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
                                                 else 2 if confidence == "low"
                                                 else 0),
                 "explain":                     sys.modules["cctally"]._build_forecast_json_payload(fc),
+                # #661 S2 §10. Optional, typed, and ADDITIVE: it sits under
+                # `forecast` because `ForecastEnvelope` is its semantic
+                # boundary, and it does not bump `source_schema_version`,
+                # which describes the provider-source bundles.
+                "quota":                       _forecast_quota_envelope(
+                    fc, cw, getattr(snap, "quota_rate_change", None)),
             },
 
         "trend":
@@ -1921,6 +2218,14 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
         "alerts":           alerts_array,
         "alerts_settings":  alerts_settings,
 
+        # #661 S2 §6.1: the non-threshold event family, in its OWN array
+        # rather than inside `alerts`. `AlertEntry` requires a numeric
+        # threshold and a rate transition has none, so mixing the two would
+        # either weaken that contract or ship a row every consumer skips.
+        # Additive optional — `envelope_version` stays at 2, and an older
+        # client simply does not read it.
+        "meter_rate_changes": meter_rate_changes_array,
+
         # Dashboard render-prefs mirror (cache-failure-markers opt-out, spec
         # §5). Additive optional, like alerts_settings — envelope_version
         # stays at 2. The client derives `markersEnabled` from this, defaulting

package/bin/_cctally_dashboard_share.py

@@ -966,16 +966,24 @@ def _build_forecast_share_panel_data(options: dict,
     Reuses ``DataSnapshot.forecast`` (ForecastOutput) and, when populated
     by the sync thread, ``DataSnapshot.forecast_view`` (the kernel
     wrapper from issue #57) for the (100, 90) budget pair.
-    ``projection_curve`` is synthesized from ``r_avg`` / ``r_recent`` /
-    ``inputs.p_now`` — the same arithmetic ``snapshot_to_envelope`` does
-    for ``week_avg_projection_pct`` / ``recent_24h_projection_pct``,
-    extended across the next 7 days.
+
+    ``projected_end_pct`` is the kernel's SELECTED projection (#661 S2 spec
+    section 3.3) rather than a sixth re-derivation of it, and the curve and
+    the ceiling distances are measured from the same ceiling-corrected base
+    the kernel used. This function previously paired a RAW ``inputs.p_now``
+    with the corrected ``r_avg`` the kernel publishes and described that as
+    "the same arithmetic ``snapshot_to_envelope`` does", which stopped being
+    true the moment the correction landed.
+
+    Every one of those quantities is withheld at a right-censored reading and
+    on a week with no observed usage, because each is derived from a meter
+    that supplies no point estimate.
     """
     fc = getattr(snap, "forecast", None) if snap else None
     fc_view = getattr(snap, "forecast_view", None) if snap else None
     if fc is None:
         return {
-            "projected_end_pct":  0.0,
+            "projected_end_pct":  None,
             # With no forecast at all there is no rate, so neither ceiling has
             # a distance — the same withholding the populated path performs.
             "days_to_100pct":     None,
@@ -987,25 +995,43 @@ def _build_forecast_share_panel_data(options: dict,
             "projection_curve": [],
             "confidence":       "LOW CONF",
         }
+    from _lib_forecast import projection_base
+
     inputs = getattr(fc, "inputs", None)
-    p_now = float(getattr(inputs, "p_now", 0.0) or 0.0) if inputs else 0.0
+    # The CEILING-CORRECTED base, through the one named resolver. `None` at a
+    # right-censored reading, where there is no point estimate at all.
+    base = projection_base(inputs) if inputs is not None else None
+    p_now = None if base is None else float(base)
     remaining_hours = float(
         getattr(inputs, "remaining_hours", 0.0) or 0.0
     ) if inputs else 0.0
     confidence = getattr(inputs, "confidence", "ok") if inputs else "ok"
-    r_avg = float(getattr(fc, "r_avg", 0.0) or 0.0)
+    r_avg_raw = getattr(fc, "r_avg", None)
+    r_avg = None if r_avg_raw is None else float(r_avg_raw)
     r_recent_raw = getattr(fc, "r_recent", None)
     r_recent = float(r_recent_raw) if r_recent_raw is not None else r_avg
-    # End-of-week projected %
-    projected_end_pct = (p_now + r_avg * remaining_hours) / 100.0
+    # End-of-week projected % — the kernel's selected value, expressed as the
+    # fraction this panel's contract carries. `None` when the kernel withheld
+    # it, which the templates render as `n/a` rather than as `0.0%`.
+    selected = getattr(fc, "week_avg_projection_pct", None)
+    projected_end_pct = None if selected is None else float(selected) / 100.0
     # Days to ceilings (simple inverse: hours-to-target / 24).
-    # The two exit conditions are opposite facts and must not share a value.
-    # `p_now >= target_pct` means the target is already reached, and zero days
-    # to it is true. `r_avg <= 0` means no rate was observed, so the target is
-    # not reachable on any timeline this data describes — and in the no-usage
-    # state BOTH hold (`p_now == 0`, `r_avg == 0`), so the shared `0.0`
-    # rendered `Days->90% 0.0`, stating the opposite of the truth.
+    # The three exit conditions are different facts and must not share a
+    # value. `p_now >= target_pct` means the target is already reached, and
+    # zero days to it is true. `r_avg <= 0` means no rate was observed, so the
+    # target is not reachable on any timeline this data describes. A withheld
+    # base or rate means the meter supplies no distance at all.
+    #
+    # #661 S2 §3.1 changed which of these fires in the no-usage state. Before
+    # the ceiling correction both `p_now == 0` and `r_avg == 0` held there,
+    # and the shared `0.0` rendered `Days->90% 0.0`, stating the opposite of
+    # the truth. The corrected point of a displayed 0 is 0.25, so NEITHER
+    # holds now: the distance is a real, finite, very large number. Bounding
+    # it is a PRESENTATION decision and is made in `_optional_days`, so this
+    # function keeps publishing the exact figure.
     def _days_to_ceiling(target_pct: float) -> "float | None":
+        if p_now is None or r_avg is None:
+            return None
         if p_now >= target_pct:
             return 0.0
         if r_avg <= 0:
@@ -1045,18 +1071,23 @@ def _build_forecast_share_panel_data(options: dict,
     # defect one layer below the fix.
     _raw_dpp = getattr(inputs, "dollars_per_percent", None) if inputs else None
     dpp = None if _raw_dpp is None else float(_raw_dpp)
-    budgets["avg"] = None if dpp is None else dpp * r_avg * 24.0
-    budgets["recent_24h"] = None if dpp is None else dpp * r_recent * 24.0
-    # Projection curve — 7-day forward, using r_avg
+    budgets["avg"] = (None if dpp is None or r_avg is None
+                      else dpp * r_avg * 24.0)
+    budgets["recent_24h"] = (None if dpp is None or r_recent is None
+                             else dpp * r_recent * 24.0)
+    # Projection curve — 7-day forward, using r_avg from the corrected base.
+    # Empty when either is withheld: a curve drawn from a censored reading is
+    # the same fabrication the scalar above refuses.
     today = _share_now_utc().date()
     projection_curve: list[dict] = []
-    for i in range(7):
-        d = today + dt.timedelta(days=i)
-        pct = (p_now + r_avg * (i * 24.0)) / 100.0
-        projection_curve.append({
-            "date":               d.isoformat(),
-            "projected_pct_used": pct,
-        })
+    if p_now is not None and r_avg is not None:
+        for i in range(7):
+            d = today + dt.timedelta(days=i)
+            pct = (p_now + r_avg * (i * 24.0)) / 100.0
+            projection_curve.append({
+                "date":               d.isoformat(),
+                "projected_pct_used": pct,
+            })
     return {
         "projected_end_pct":  projected_end_pct,
         "days_to_100pct":     days_to_100,

package/bin/_cctally_doctor.py

@@ -1021,6 +1021,41 @@ def _load_codex_quota_observations_for_doctor(*, force_cold: bool = False):
     return loaded
 
 
+_QUOTA_NO_CHANGE: dict = {
+    "active": False, "effective_from": None,
+    "previous_units_per_point": None, "new_units_per_point": None,
+}
+
+
+def _gather_quota_rate_change(c, rejection=None) -> "dict | None":
+    """§6.6's derived marker state, read WITHOUT the prediction gate.
+
+    The rate-change surfaces read the regime pair deliberately: S1 marks a
+    successor `detection-only` while its fit stays below the PREDICTION gate,
+    and detection is exactly what a detection-grade fit is for. So this
+    gather goes to the stored regimes rather than through the validated
+    reader's default, which refuses that mark.
+
+    An ABSENT calibration is "no change detected", not "not assessed" — a
+    store with no fitted regime has no transition to report, and that is the
+    state of every install that has never run `cctally quota`. `None` is
+    reserved for a calibration that exists and could not be read, where the
+    sibling `quota.calibration` check is already WARNing about it.
+    """
+    if rejection == "calibration-absent":
+        return dict(_QUOTA_NO_CHANGE)
+    mrc = c._load_sibling("_lib_meter_rate_change")
+    glue = c._load_sibling("_cctally_quota_model")
+    loaded = glue.read_stored_state_readonly()
+    if loaded is None:
+        return None
+    regimes = glue.stored_regimes(loaded, None)
+    active = mrc.active_rate_change(regimes)
+    if active is None:
+        return dict(_QUOTA_NO_CHANGE)
+    return active
+
+
 def doctor_gather_state(
     *,
     now_utc: "dt.datetime | None" = None,
@@ -2028,6 +2063,31 @@ def _doctor_gather_state_impl(
             except Exception:
                 pricing_coverage = None
 
+    with _lib_perf.phase("doctor.quota_calibration"):
+        # ── Quota (#661 S2 §7) ───────────────────────────────────────────
+        # Through the §1.1 NON-MUTATING reader. `load_calibrations` renames a
+        # malformed or version-ahead file aside through `_quarantine`, so
+        # calling it here would make a documented read-only command a writer.
+        # An already-quarantined file is reported simply as a missing primary:
+        # the reader cannot tell it from an absent one without scanning
+        # sidecars, and it deliberately does not scan them.
+        quota_calibration = None
+        quota_rate_change = None
+        try:
+            qcg = c._load_sibling("_cctally_quota_calibration")
+            read = qcg.read_calibration_file(account_key=None)
+            quota_calibration = {
+                "rejection": (None if read.rejection is None
+                              else str(read.rejection.value)),
+                "status": read.regime_status,
+                "present": read.regime is not None,
+            }
+            quota_rate_change = _gather_quota_rate_change(
+                c, quota_calibration["rejection"])
+        except Exception:
+            quota_calibration = None
+            quota_rate_change = None
+
     # ── Meta ─────────────────────────────────────────────────────────
     with _lib_perf.phase("doctor.journal"):
         # ── Journal (DB journal redesign §9) ─────────────────────────────
@@ -2413,6 +2473,9 @@ def _doctor_gather_state_impl(
         telemetry_reason=telemetry_reason,
         # Pricing-freshness check (spec §5.1): trailing-30d coverage gaps.
         pricing_coverage=pricing_coverage,
+        # #661 S2 §7: the `quota` category's two inputs.
+        quota_calibration=quota_calibration,
+        quota_rate_change=quota_rate_change,
         # Conversation-sessions rollup consistency (#217 S1 / U9).
         conv_sessions_rollup_count=conv_sessions_rollup_count,
         conv_messages_distinct_sessions=conv_messages_distinct_sessions,