cctally 1.103.0 → 1.105.0

package/bin/_lib_statusline.py

@@ -10,12 +10,62 @@ for the full design.
 from __future__ import annotations
 
 import json
+import pathlib
 import re
+import sys
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from typing import Callable, Optional
 
 
+def _load_lib(name: str):
+    """Late-import a sibling under ``bin/`` (the ``_lib_view_models`` recipe).
+
+    Late rather than top-level, so this KERNEL carries no import-time edge to
+    the quota modules and stays importable on its own.
+
+    WHAT THAT DOES NOT BUY, corrected after the #661 S2 review. An earlier
+    revision of this docstring claimed that a status line on an install which
+    has never fitted a calibration "loads none of them". At runtime it loads
+    all of them. ``_seven_day_projection`` imports ``_lib_forecast``
+    unconditionally, and ``_lib_forecast`` imports ``_lib_quota_model`` at
+    module scope, so the quota kernel arrives with the projection whether or
+    not a calibration exists. ``_rate_change_marker`` then calls
+    ``inj.quota_regimes()`` whenever any 5h or 7d reading exists, and that
+    port imports ``_cctally_quota_model``; a withheld figure imports
+    ``_lib_quota_copy``.
+
+    MEASURED here, as marginal cost in ONE process in the order the status
+    line pays it, three runs on an Apple M4 Max under CPython 3.13:
+    ``_cctally_core`` 13.1-13.4ms, then ``_lib_forecast`` 12.1-13.5ms,
+    ``_lib_quota_model`` 0.0ms because ``_lib_forecast`` already pulled it,
+    ``_cctally_quota_model`` 1.5-1.8ms, and ``_lib_quota_copy`` 0.1-0.3ms.
+    So about 14ms per prompt beyond ``_cctally_core``. Those durations are
+    this machine's; the STRUCTURAL fact — four modules, of which the largest
+    is on the unconditional projection path — is not.
+
+    That is an unstated cost rather than a violated constraint. Spec §9's
+    rule is about ``cache.db`` and ``analyse``, and neither is touched; see
+    ``tests/test_statusline_quota.py``, which makes both explode rather than
+    reading the source for their names. Gating the quota port behind a cheap
+    ``Path.exists()`` on the calibration file was measured and NOT taken: it
+    would remove ``_cctally_quota_model`` alone, 1.5ms of the 14, because
+    ``_lib_forecast`` and the kernel it pulls are already loaded by then, and
+    it would add a stat(2) to every prompt on an install that does have a
+    calibration.
+    """
+    cached = sys.modules.get(name)
+    if cached is not None:
+        return cached
+    import importlib.util as _ilu
+    p = pathlib.Path(__file__).resolve().parent / f"{name}.py"
+    spec = _ilu.spec_from_file_location(name, p)
+    mod = _ilu.module_from_spec(spec)
+    sys.modules[name] = mod
+    spec.loader.exec_module(mod)
+    return mod
+
+
 # ---- Stdin payload (subset we care about) ----------------------------------
 
 
@@ -97,6 +147,18 @@ class StatuslineInjections:
     context_pct: Callable[[Optional[str], Optional[str]], Optional[float]]
     # Emits one-shot stderr warnings (deduped by message — caller maintains set).
     warn_once: Callable[[str], None]
+    # #661 S2 §9. The stored metering regimes for this install, oldest
+    # first, as plain dicts — a dedicated FILESYSTEM port and deliberately
+    # NOT the DB port beside it. The read takes no flock and no throttle:
+    # `save_calibrations` writes through `os.replace` in the same directory,
+    # so a lock-free reader always sees a complete old or new inode, and a
+    # flock here would let a writer stall a prompt. It returns `()` for
+    # every unusable state — absent, malformed, version-ahead, quarantined
+    # — because the status line cannot distinguish them without scanning
+    # quarantine sidecars and renders the same thing for all of them: no
+    # marker. The default supplies no regimes, so a caller that has not
+    # wired the port renders exactly what it rendered before.
+    quota_regimes: Callable[[], tuple] = staticmethod(lambda: ())
 
 
 # ---- ParseError sentinel ---------------------------------------------------
@@ -369,20 +431,147 @@ def _fmt_countdown(seconds: int) -> str:
     return f"{minutes}m"
 
 
+#: The 7d meter's window length. The projection measures a rate over the
+#: elapsed part of THIS window, so it needs the window's span, and the reset
+#: epoch alone gives only its end.
+_SEVEN_DAY_HOURS = 7 * 24.0
+
+#: The marker §6.6's predicate raises. Short because it shares a line with
+#: four other segments, and literal because a bare glyph would have to be
+#: looked up: the word says the rate changed and `cctally quota` says how.
+_RATE_CHANGE_MARKER = "Δrate"
+
+#: How much of the window must have elapsed before a pace projection is
+#: rendered here. NOT a new threshold: it is
+#: `ForecastConfidenceCause.ELAPSED_HOURS`, the estate's existing rule for
+#: when a week-pace projection is low-confidence, restated as a number
+#: because the status line has no room for the `LOW CONF` qualifier
+#: `forecast` prints beside one. Without it the slot publishes arithmetic
+#: that is correct and useless: a 42% reading ten hours into a week
+#: projects to 697%, and a per-prompt line is the worst place to put a
+#: figure that moves by hundreds of points between prompts.
+_PROJECTION_MIN_ELAPSED_HOURS = 24.0
+
+@dataclass(frozen=True)
+class _ProjectionInputs:
+    """The duck-typed operand `select_projection_basis` reads.
+
+    The selector is shared with `forecast` and the dashboard and takes
+    whatever object carries these attributes, so the status line builds the
+    smallest one that answers it rather than reaching for a forecast.
+
+    `calibrated_projection_pct` is deliberately absent. Producing it needs a
+    whole-week `session_entries` scan, and spec §9 forbids this surface from
+    touching `cache.db` for quota at all, so the basis on this surface is
+    always the corrected meter. The selector is still asked rather than
+    bypassed, so the token the line prints names the basis it actually used
+    and would name a different one the day the basis becomes cheap.
+    """
+    p_now: "float | None"
+    p_now_corrected: "float | None"
+    right_censored: bool
+    elapsed_hours: "float | None"
+    remaining_hours: "float | None"
+
+
+def _seven_day_projection(seven_pct, seven_resets, now_epoch) -> Optional[str]:
+    """The `→ …` token for the 7d slot, or None when there is none.
+
+    None — rather than a withheld token — in the three cases where there is
+    nothing to say rather than a typed reason not to say it: the reset epoch
+    is unknown, so there is no window to project over; the reset instant has
+    already passed, so the window it named has closed; or too little of the
+    window has elapsed for a pace to mean anything. Otherwise the slot
+    carries a value with its basis, or the withholding cause in the short
+    register.
+    """
+    if seven_pct is None or seven_resets is None:
+        return None
+    if seven_resets <= now_epoch:
+        # A CLOSED window. The clamp below would drive `remaining` to 0 and
+        # `elapsed` to the whole 168 hours, so the projection would equal the
+        # corrected reading and the line would print a projected end-of-week
+        # percent for a week that has already ended. It is reachable from the
+        # DB-latest fallback row and from a long-idle machine, and it is a
+        # missing window rather than a statement about the reading — so it is
+        # withheld the way an unknown reset is, above the censoring branch
+        # and above the elapsed gate.
+        return None
+    fc = _load_lib("_lib_forecast")
+    remaining = (seven_resets - now_epoch) / 3600.0
+    remaining = max(0.0, min(_SEVEN_DAY_HOURS, remaining))
+    elapsed = _SEVEN_DAY_HOURS - remaining
+    shown = float(seven_pct)
+    corrected = fc.corrected_percent_point(shown)
+    selected = fc.select_projection_basis(_ProjectionInputs(
+        p_now=shown,
+        p_now_corrected=corrected,
+        # Censoring is read off the correction rather than re-tested here.
+        # `corrected_percent_point` returns None exactly when the reading is
+        # right-censored — a displayed 100 denotes `[99, +inf)` and has no
+        # finite point estimate — and a second spelling of that test would
+        # be a second place to disagree with it.
+        right_censored=corrected is None,
+        elapsed_hours=elapsed,
+        remaining_hours=remaining,
+    ))
+    copy = _load_lib("_lib_quota_copy")
+    if selected.basis is fc.ProjectionBasis.WITHHELD:
+        # A withholding is a statement about the READING and does not
+        # depend on how much of the window has elapsed, so it is rendered
+        # before the confidence gate below. A right-censored 100 is the
+        # case: it has no point estimate at any point in the week.
+        return f"→ {copy.short_form(selected.code)}"
+    if elapsed < _PROJECTION_MIN_ELAPSED_HOURS:
+        # Too early in the window for a pace to mean anything. The slot
+        # keeps the shape it has always had rather than printing a token,
+        # for the same reason an unknown reset epoch does: there is nothing
+        # to say, and a per-prompt line must not fill with non-statements.
+        return None
+    basis = copy.basis_presentation(selected.basis.value).get(
+        "short", selected.basis.value)
+    return f"→ {int(round(selected.value))}% {basis}"
+
+
+def _rate_change_marker(inj: StatuslineInjections) -> Optional[str]:
+    """`Δrate` while §6.6's predicate holds, else None.
+
+    The predicate is DERIVED — the active open regime has a confirmed
+    predecessor — so the marker clears on its own when that regime closes
+    and needs no durable state, which §1 forbids this session from adding.
+    """
+    try:
+        regimes = list(inj.quota_regimes() or ())
+    except Exception:                                  # noqa: BLE001
+        # A port that raises must not take the prompt down with it. The
+        # marker is information; the status line is the shell's.
+        return None
+    if not regimes:
+        return None
+    mrc = _load_lib("_lib_meter_rate_change")
+    return _RATE_CHANGE_MARKER if mrc.active_rate_change(regimes) else None
+
+
 def resolve_cctally_extensions(
     inp: StatuslineInput,
     now: datetime,
     inj: StatuslineInjections,
     *,
     include_countdowns: bool = True,
+    include_projection: bool = True,
 ) -> Optional[str]:
-    """Segment 5 — cctally-only `5h X% (...) · 7d Y% (...)`.
+    """Segment 5 — cctally-only `5h X% (...) · 7d Y% (...) → Z% meter`.
 
     Source priority chain (spec §3.5):
         1. stdin rate_limits (preferred — freshest)
         2. DB latest weekly_usage_snapshots row (if stdin EMPTY)
         3. HWM monotonic clamp (within window only)
         4. If all empty → return None (segment 5 suppressed)
+
+    #661 S2 §9: the 7d slot also carries the projected end-of-week percent
+    with the basis it came from, and a `Δrate` marker while §6.6's predicate
+    holds. `include_projection` is False for `--usage-only`, which is the
+    compact two-reading form other tools embed and keeps its shape.
     """
     five_pct = inp.rate_limits_5h_pct
     five_resets = inp.rate_limits_5h_resets_at
@@ -421,7 +610,16 @@ def resolve_cctally_extensions(
         s = f"7d {int(round(seven_pct))}%"
         if include_countdowns and seven_resets is not None:
             s += f" ({_fmt_countdown(seven_resets - now_epoch)})"
+        if include_projection:
+            projection = _seven_day_projection(
+                seven_pct, seven_resets, now_epoch)
+            if projection is not None:
+                s += f" {projection}"
         parts.append(s)
+    if include_projection:
+        marker = _rate_change_marker(inj)
+        if marker is not None:
+            parts.append(marker)
     return " · ".join(parts)
 
 
@@ -471,7 +669,7 @@ def render_statusline(
     """
     if args.usage_only:
         ext = resolve_cctally_extensions(
-            inp, now, inj, include_countdowns=False
+            inp, now, inj, include_countdowns=False, include_projection=False
         )
         return "" if ext is None else _colorize_usage_segment(ext, args)
 

package/bin/_lib_tick_stats.py

@@ -57,6 +57,7 @@ PUBLICATIONS = ("final", "partial", "seed", "degraded")
 #: validation lives in the recorder rather than in the dataclass because a
 #: frozen field typed `str` enforces nothing on its own.
 CONVERSATION_STATUSES = ("ok", "store_unavailable", "error")
+CONVERSATION_MODES = ("caught_up", "targeted", "full", "not_observed")
 
 _INGEST = "ingest"
 _BUILD = "build"
@@ -82,6 +83,7 @@ class TickRecord:
     published_at: str
     period_ns: "int | None"
     cache_pin_ns: int
+    cpu_ns: int
 
     def as_wire(self) -> dict:
         return {f.name: getattr(self, f.name) for f in dataclasses.fields(self)}
@@ -119,6 +121,10 @@ class ConversationSyncRecord:
     cpu_ns: int
     period_ns: "int | None"
     status: str
+    claude_mode: str
+    codex_mode: str
+    claude_files: int
+    codex_files: int
 
     def as_wire(self) -> dict:
         return {f.name: getattr(self, f.name) for f in dataclasses.fields(self)}
@@ -233,14 +239,17 @@ class _Span:
 class TickContext:
     """A tick in progress. Thread-confined; only ``finish`` touches the lock."""
 
-    __slots__ = ("_now", "_standalone", "_started_ns", "_spans", "_finished",
+    __slots__ = ("_now", "_cpu_now", "_standalone", "_started_ns",
+                 "_started_cpu_ns", "_spans", "_finished",
                  "_ingest_ns", "_builder_ns", "_ingest_ran", "_dispatch",
                  "_codex_regime", "_publication", "_cold", "_cache_pin_ns")
 
-    def __init__(self, *, monotonic_ns, standalone: bool):
+    def __init__(self, *, monotonic_ns, thread_time_ns, standalone: bool):
         self._now = monotonic_ns
+        self._cpu_now = thread_time_ns
         self._standalone = standalone
         self._started_ns = monotonic_ns()
+        self._started_cpu_ns = thread_time_ns()
         self._spans: list[_Span] = []
         self._finished = False
         self._ingest_ns = 0
@@ -388,6 +397,7 @@ class TickContext:
         while self._spans:
             self._spans.pop().__exit__(None, None, None)
         ended_ns = self._now()
+        ended_cpu_ns = self._cpu_now()
         if getattr(_tls, "tick", None) is self:
             _tls.tick = None
 
@@ -419,6 +429,7 @@ class TickContext:
                 published_at=published_at,
                 period_ns=period,
                 cache_pin_ns=self._cache_pin_ns,
+                cpu_ns=max(0, ended_cpu_ns - self._started_cpu_ns),
             )
             if self._standalone:
                 _STATE = dataclasses.replace(prior, standalone=record)
@@ -442,7 +453,9 @@ class TickContext:
 
 
 def record_conversation_pass(
-    *, seq, started_ns, ended_ns, duration_ns, cpu_ns, status
+    *, seq, started_ns, ended_ns, duration_ns, cpu_ns, status,
+    claude_mode="not_observed", codex_mode="not_observed",
+    claude_files=0, codex_files=0,
 ) -> None:
     """Append one conversation sync pass to its ring, under the SHARED lock.
 
@@ -469,6 +482,10 @@ def record_conversation_pass(
     """
     global _STATE
     safe_status = status if status in CONVERSATION_STATUSES else "error"
+    safe_claude_mode = (
+        claude_mode if claude_mode in CONVERSATION_MODES else "not_observed")
+    safe_codex_mode = (
+        codex_mode if codex_mode in CONVERSATION_MODES else "not_observed")
     start = int(started_ns)
     record = ConversationSyncRecord(
         seq=int(seq),
@@ -478,6 +495,10 @@ def record_conversation_pass(
         cpu_ns=max(0, int(cpu_ns)),
         period_ns=None,
         status=safe_status,
+        claude_mode=safe_claude_mode,
+        codex_mode=safe_codex_mode,
+        claude_files=max(0, int(claude_files)),
+        codex_files=max(0, int(codex_files)),
     )
     with _LOCK:
         prior = _STATE
@@ -495,7 +516,9 @@ def record_conversation_pass(
         )
 
 
-def begin_tick(*, monotonic_ns=None, standalone: bool = False) -> TickContext:
+def begin_tick(
+    *, monotonic_ns=None, thread_time_ns=None, standalone: bool = False,
+) -> TickContext:
     """Open a tick context and make it ``current()`` on this thread.
 
     ``standalone`` records a ``tui --render-once`` or
@@ -505,6 +528,7 @@ def begin_tick(*, monotonic_ns=None, standalone: bool = False) -> TickContext:
     """
     ctx = TickContext(
         monotonic_ns=monotonic_ns or time.monotonic_ns,
+        thread_time_ns=thread_time_ns or time.thread_time_ns,
         standalone=standalone,
     )
     _tls.tick = ctx

package/bin/_lib_view_models.py

@@ -1515,7 +1515,12 @@ def _forecast_verdict_of(output) -> str:
     inputs = getattr(output, "inputs", None)
     if inputs is not None and getattr(inputs, "confidence", "high") == "low":
         return _FORECAST_VERDICT_LOW_CONF
-    high = float(getattr(output, "final_percent_high", 0.0))
+    high = getattr(output, "final_percent_high", 0.0)
+    if high is None:
+        # #661 S2 spec section 3.2: a right-censored reading publishes no
+        # projection, and the meter is at its cap by construction.
+        return _FORECAST_VERDICT_OVER
+    high = float(high)
     if high >= 100:
         return _FORECAST_VERDICT_OVER
     if high >= 90:
@@ -1538,25 +1543,38 @@ def _forecast_dashboard_verdict_of(output) -> str:
 def _forecast_projection_pcts(output) -> "tuple[float | None, float | None]":
     """Return (week_avg_projection_pct, recent_24h_projection_pct).
 
-    Decomposes the dual-method projections from ``r_avg`` / ``r_recent``
-    + ``inputs.p_now`` + ``inputs.remaining_hours``. Mirrors the routing
-    in ``snapshot_to_envelope``: recent-24h is ``None`` when ``r_recent``
-    is ``None`` or its projection equals the week-avg projection (no
-    new info — a second method that agrees with the first contributes
-    nothing to the user-facing range).
+    The week-average value is READ from ``ForecastOutput`` rather than
+    re-derived (#661 S2 spec section 3.3). It is the one selector's answer,
+    so it is the calibrated model's number where that basis was reached and
+    ``None`` where the kernel withheld it. Re-deriving
+    ``p_now + r_avg * remaining`` here published a second answer to the same
+    question: the committed ``over`` dashboard golden carried
+    ``week_avg_projection_pct: 126.0`` in the envelope while its own nested
+    ``forecast.explain`` block said the projection was withheld because the
+    meter was right-censored.
+
+    The recent-24h value is the SECOND method and stays derived, because the
+    kernel publishes only one selected projection. It is ``None`` when
+    ``r_recent`` is ``None`` — which includes every censored reading — or
+    when its projection equals the week-average one (no new info; a second
+    method that agrees with the first contributes nothing to the range).
     """
     if output is None:
         return None, None
     inputs = getattr(output, "inputs", None)
     if inputs is None:
         return None, None
-    p_now = getattr(inputs, "p_now", None)
+    from _lib_forecast import projection_base
+
+    week_avg_pct = getattr(output, "week_avg_projection_pct", None)
+    if getattr(output, "projection_basis", None) == "withheld":
+        # The kernel withheld the projection itself, so there is no second
+        # method to offer either: the recent-24h rate over a censored or
+        # empty meter would publish the very number the withholding removed.
+        return None, None
+    p_now = projection_base(inputs)
     rem = getattr(inputs, "remaining_hours", None)
-    r_avg = getattr(output, "r_avg", None)
     r_recent = getattr(output, "r_recent", None)
-    week_avg_pct = None
-    if p_now is not None and rem is not None and r_avg is not None:
-        week_avg_pct = p_now + r_avg * rem
     recent_pct = None
     if p_now is not None and rem is not None and r_recent is not None:
         candidate = p_now + r_recent * rem

package/bin/cctally

@@ -568,6 +568,29 @@ _iter_codex_jsonl_entries_with_offsets = _lib_jsonl._iter_codex_jsonl_entries_wi
 # Provider-neutral quota interpretation kernel (#294 S2).  The module is pure
 # and contains no database, config, filesystem, notifier, parser, or command
 # dependency; adapters added in later stages own those concerns.
+# Quota model kernel (#661 S1): the pure-fn layer behind `cctally quota`,
+# re-exported here like the other _lib_* kernels so tests and the glue reach
+# one loaded instance.
+_lib_quota_model = _load_sibling("_lib_quota_model")
+CalibrationStatus = _lib_quota_model.CalibrationStatus
+WithholdingCause = _lib_quota_model.WithholdingCause
+Verdict = _lib_quota_model.Verdict
+BlockingReason = _lib_quota_model.BlockingReason
+CalibrationEvidence = _lib_quota_model.CalibrationEvidence
+QuotaAnalysis = _lib_quota_model.QuotaAnalysis
+DailyObservation = _lib_quota_model.DailyObservation
+DetectorResult = _lib_quota_model.DetectorResult
+EntryRecord = _lib_quota_model.EntryRecord
+SnapshotRecord = _lib_quota_model.SnapshotRecord
+CreditRecord = _lib_quota_model.CreditRecord
+Segment = _lib_quota_model.Segment
+Interval = _lib_quota_model.Interval
+Support = _lib_quota_model.Support
+quota_model_analyse = _lib_quota_model.analyse
+QUOTA_MODEL_ALGORITHM_REVISION = _lib_quota_model.QUOTA_MODEL_ALGORITHM_REVISION
+QUOTA_MODEL_CONSTANTS_FINGERPRINT = (
+    _lib_quota_model.QUOTA_MODEL_CONSTANTS_FINGERPRINT)
+
 _lib_quota = _load_sibling("_lib_quota")
 QuotaWindowIdentity = _lib_quota.QuotaWindowIdentity
 QuotaObservation = _lib_quota.QuotaObservation
@@ -889,6 +912,12 @@ cmd_pricing_check = _cctally_pricing_check.cmd_pricing_check
 _pricing_observed_models = _cctally_pricing_check._pricing_observed_models
 _PRICING_SCAN_DEFAULT_WINDOW = _cctally_pricing_check._PRICING_SCAN_DEFAULT_WINDOW
 
+# Eager re-export of bin/_cctally_quota_model.py — `cmd_quota` is invoked
+# via the parser's `set_defaults(func=c.cmd_quota)`, which resolves through
+# cctally's namespace, so it must live here.
+_cctally_quota_model = _load_sibling("_cctally_quota_model")
+cmd_quota = _cctally_quota_model.cmd_quota
+
 # Eager re-export of bin/_cctally_doctor.py — `cmd_doctor` is the parser's
 # `set_defaults(func=c.cmd_doctor)` target; `doctor_gather_state` is a
 # PATCHABLE binding reached by the dashboard shim
@@ -1477,6 +1506,7 @@ _project_detail_for_window = _cctally_dashboard._project_detail_for_window
 _handle_get_project_detail_impl = _cctally_dashboard._handle_get_project_detail_impl
 _select_current_block_for_envelope = _cctally_dashboard._select_current_block_for_envelope
 _build_alerts_envelope_array = _cctally_dashboard._build_alerts_envelope_array
+_build_meter_rate_change_array = _cctally_dashboard._build_meter_rate_change_array
 snapshot_to_envelope = _cctally_dashboard.snapshot_to_envelope
 _session_detail_to_envelope = _cctally_dashboard._session_detail_to_envelope
 DashboardHTTPHandler = _cctally_dashboard.DashboardHTTPHandler
@@ -1654,6 +1684,8 @@ _assess_forecast_confidence = _cctally_forecast._assess_forecast_confidence
 _pick_p_24h_ago = _cctally_forecast._pick_p_24h_ago
 _load_forecast_inputs = _cctally_forecast._load_forecast_inputs
 _compute_forecast = _cctally_forecast._compute_forecast
+corrected_percent_point = _cctally_forecast.corrected_percent_point
+corrected_percent_interval = _cctally_forecast.corrected_percent_interval
 _parse_forecast_targets = _cctally_forecast._parse_forecast_targets
 TOOL_VERSION = _cctally_forecast.TOOL_VERSION
 _build_forecast_json_payload = _cctally_forecast._build_forecast_json_payload