cctally 1.100.0 → 1.102.0

package/bin/_lib_alerts_payload.py

@@ -63,6 +63,100 @@ _lib_accounts = _load_lib("_lib_accounts")
 _UNATTRIBUTED = _lib_accounts.UNATTRIBUTED
 _VENDOR_WIDE = _lib_accounts.VENDOR_WIDE
 
+# Next-step routing (#620 S1, D11): every axis offers the command that explains
+# it, scoped to that alert's own provider and window. The scope is derived from
+# the retained context by `_lib_alert_scope`; nothing here parses an alert id.
+_lib_alert_scope = _load_lib("_lib_alert_scope")
+derive_alert_scope = _lib_alert_scope.derive_alert_scope
+format_next_step = _lib_alert_scope.format_next_step
+alert_next_step_command = _lib_alert_scope.alert_next_step_command
+
+
+next_step_line = _lib_alert_scope.next_step_line
+
+
+def alert_next_step_line(
+    payload: dict, tz: "ZoneInfo | None", now: "dt.datetime | None" = None,
+) -> str:
+    """The one affordance line an alert body ends with.
+
+    The command's own arguments stay in UTC, because that is what the
+    selectors they feed accept (``--block-start`` is documented naive-is-UTC);
+    the trailing scope statement is what renders in the display zone.
+
+    ``now`` is the instant the liveness test compares against; it defaults to
+    the current UTC instant. The clock read lives here rather than in
+    ``_lib_alert_scope`` so that kernel stays a pure leaf.
+    """
+    axis = payload.get("axis")
+    ctx = payload.get("context") or {}
+    scope = derive_alert_scope(axis, ctx, payload.get("account_key"))
+    command = alert_next_step_command(axis, ctx, scope)
+    if command is None:
+        return format_next_step(
+            None,
+            unavailable_reason=_lib_alert_scope.alert_target_unavailable_reason(
+                axis, ctx, scope
+            ),
+        )
+    # A command that reports only the live window cannot address one that has
+    # already closed. Offering it anyway would report the current window under
+    # a line naming the closed one, so the navigation is withheld with its
+    # cause — the same treatment a purged five-hour block already gets.
+    if (
+        _lib_alert_scope.command_reports_the_live_period_only(command)
+        and scope.window_end is not None
+    ):
+        if now is None:
+            now = dt.datetime.now(dt.timezone.utc)
+        if scope.window_end <= now:
+            return format_next_step(
+                None,
+                unavailable_reason=_lib_alert_scope.closed_window_reason(command),
+            )
+    if scope.available:
+        return next_step_line(
+            command,
+            provider=scope.provider,
+            window_start=scope.window_start,
+            window_end=scope.window_end,
+            tz=tz,
+            granularity=scope.window_granularity,
+        )
+    # A live-window command with no derivable length: name the provider and
+    # say what is missing, never a window the alert did not describe.
+    detail = (
+        f"{scope.provider} · {scope.withheld_reason}"
+        if scope.provider else scope.withheld_reason
+    )
+    return format_next_step(command, detail=detail)
+
+
+def synthetic_preview_week_start(
+    now: "dt.datetime | None" = None,
+) -> dt.datetime:
+    """The week start the two `alerts test --axis weekly` previews use.
+
+    A real crossing carries `percent_milestones.week_start_at`, the week's
+    reset instant, and a preview that omitted it rendered the day-granularity
+    fallback — two bare dates with no reset hour and no zone — which is not
+    what a real crossing produces. The instant is hour-aligned and one day
+    back so its reset hour is a real clock reading rather than the midnight
+    that would render identically to the fallback it replaces.
+    """
+    if now is None:
+        now = dt.datetime.now(dt.timezone.utc)
+    return (now - dt.timedelta(days=1)).replace(
+        minute=0, second=0, microsecond=0
+    )
+
+
+def _with_next_step(body: str, payload: dict, tz: "ZoneInfo | None") -> str:
+    """Append the affordance as its own line. AppleScript collapses the
+    newline to a space (``_escape_applescript_string``) and ``notify-send``
+    keeps it, so both notifiers render the whole sentence."""
+    return f"{body}\n{alert_next_step_line(payload, tz)}"
+
 
 def _alert_text_weekly(payload: dict, tz: "ZoneInfo | None") -> tuple[str, str, str]:
     """Build (title, subtitle, body) for a weekly threshold alert.
@@ -96,7 +190,7 @@ def _alert_text_weekly(payload: dict, tz: "ZoneInfo | None") -> tuple[str, str,
         body = f"${cumulative:.2f} spent so far - ${float(dpp):.2f} per 1%"
     else:
         body = f"${cumulative:.2f} spent so far"
-    return title, subtitle, body
+    return title, subtitle, _with_next_step(body, payload, tz)
 
 
 def _alert_text_five_hour(payload: dict, tz: "ZoneInfo | None") -> tuple[str, str, str]:
@@ -121,7 +215,7 @@ def _alert_text_five_hour(payload: dict, tz: "ZoneInfo | None") -> tuple[str, st
         body = f"${cost:.2f} spent in this block - current model: {model}"
     else:
         body = f"${cost:.2f} spent in this block"
-    return title, subtitle, body
+    return title, subtitle, _with_next_step(body, payload, tz)
 
 
 def _escape_applescript_string(s: str) -> str:
@@ -147,6 +241,7 @@ def _build_alert_payload_weekly(
     cumulative_cost_usd: float,
     dollars_per_percent: "float | None",
     account_key: str = _UNATTRIBUTED,
+    week_start_at: "str | None" = None,
 ) -> dict:
     """Build the alert payload for a weekly threshold crossing.
 
@@ -155,7 +250,16 @@ def _build_alert_payload_weekly(
     (set-then-dispatch invariant, spec §3.2). Consumers (envelope builders,
     test inspectors) read the ``alerted_at`` field as the authoritative
     "alert was attempted" timestamp. ``account_key`` (#341) is the real account
-    the crossing wrote under (per-account family)."""
+    the crossing wrote under (per-account family).
+
+    ``week_start_at`` is the week's RESET INSTANT, retained on the milestone
+    row and already a declared ``AlertEntry.context`` key. Without it a reader
+    can only fall back to ``week_start_date``, which names the right week but
+    places both bounds at UTC midnight — wrong by the whole reset-hour offset
+    for every account whose week does not reset at midnight. Empty string when
+    the row predates the column, matching the five-hour axis's
+    ``block_start_at``: the key stays on the wire and the reader degrades to
+    day granularity rather than inventing a clock reading."""
     return {
         "id": f"weekly:{week_start_date}:{threshold}",
         "axis": "weekly",
@@ -165,6 +269,7 @@ def _build_alert_payload_weekly(
         "account_key": str(account_key),
         "context": {
             "week_start_date": week_start_date,
+            "week_start_at": week_start_at or "",
             "cumulative_cost_usd": float(cumulative_cost_usd),
             "dollars_per_percent": (
                 float(dollars_per_percent) if dollars_per_percent is not None else None
@@ -224,7 +329,7 @@ def _alert_text_budget(payload: dict, tz: "ZoneInfo | None") -> tuple[str, str,
     budget = float(ctx.get("budget_usd") or 0.0)
     consumption = float(ctx.get("consumption_pct") or 0.0)
     body = f"${spent:,.2f} of ${budget:,.2f} ({consumption:.0f}% of budget)"
-    return title, subtitle, body
+    return title, subtitle, _with_next_step(body, payload, tz)
 
 
 def _build_alert_payload_budget(
@@ -298,7 +403,7 @@ def _alert_text_project_budget(
         f"Project {project} - ${spent:,.2f} of ${budget:,.2f} "
         f"({consumption:.0f}% of budget)"
     )
-    return title, subtitle, body
+    return title, subtitle, _with_next_step(body, payload, tz)
 
 
 def _build_alert_payload_project_budget(
@@ -374,7 +479,7 @@ def _alert_text_codex_budget(
         f"Codex - ${spent:,.2f} of ${budget:,.2f} "
         f"({consumption:.0f}% of budget)"
     )
-    return title, subtitle, body
+    return title, subtitle, _with_next_step(body, payload, tz)
 
 
 def _build_alert_payload_codex_budget(
@@ -451,7 +556,7 @@ def _alert_text_projected(payload: dict, tz: "ZoneInfo | None") -> tuple[str, st
             f"Projected ${proj:,.2f} of ${denom:,.2f} budget "
             f"(week-average pace)"
         )
-    return title, subtitle, body
+    return title, subtitle, _with_next_step(body, payload, tz)
 
 
 def _build_alert_payload_projected(

package/bin/_lib_blocks.py

@@ -105,6 +105,7 @@ def _group_entries_into_blocks(
         dt.datetime, tuple[dt.datetime, dt.datetime]
     ] | None = None,
     now: dt.datetime | None = None,
+    _entry_membership: dict[int, list[UsageEntry]] | None = None,
 ) -> list[Block]:
     """Group sorted UsageEntry objects into 5-hour blocks with gap detection.
 
@@ -138,6 +139,13 @@ def _group_entries_into_blocks(
 
     `now` pins the current instant (typically via `_command_as_of()`). When
     omitted, falls back to wall clock so existing callers are unaffected.
+
+    ``_entry_membership`` is an internal detail-route seam. When supplied,
+    each non-gap result object's identity maps to the exact entries assigned
+    by this grouping pass. That ownership is stricter than a later
+    ``start <= timestamp < end`` filter when adjacent recorded windows overlap
+    after a reset shift; consumers that render per-entry samples must use the
+    grouping decision rather than independently reconstructing it.
     """
     if not entries:
         return []
@@ -264,6 +272,8 @@ def _group_entries_into_blocks(
             anchor="recorded",
         )
         first_entry_ts_by_block[id(blk)] = bucket_sorted[0].timestamp
+        if _entry_membership is not None:
+            _entry_membership[id(blk)] = bucket_sorted
         recorded_block_objs.append(blk)
 
     # Phase 2: Build heuristic Block objects from raw_blocks using _aggregate_block
@@ -278,6 +288,8 @@ def _group_entries_into_blocks(
         )
         if block_entries:
             first_entry_ts_by_block[id(blk)] = block_entries[0].timestamp
+        if _entry_membership is not None:
+            _entry_membership[id(blk)] = block_entries
         heuristic_block_objs.append(blk)
 
     # Merge + sort by start_time

package/bin/_lib_cache_report.py

@@ -17,7 +17,9 @@ from __future__ import annotations
 
 import datetime as dt
 from dataclasses import dataclass, field
-from typing import Any, Callable, Iterable, Literal, NamedTuple, Optional
+from typing import (
+    Any, Callable, Iterable, Literal, NamedTuple, Optional, Sequence,
+)
 from zoneinfo import ZoneInfo
 
 
@@ -853,6 +855,113 @@ def _compute_baseline_median(
     return statistics.median(values)
 
 
+class CacheRowVerdict(NamedTuple):
+    """One row's four-state Cache Report verdict (#620 S1 D6).
+
+    ``observed`` travels beside ``state`` rather than inside it: a day with
+    no activity is still ``unevaluated``, and whether anything happened is a
+    separate fact from whether the predicates ran.
+    """
+    state: str          # "anomalous" | "clean" | "partial" | "unevaluated"
+    triggered: bool
+    unevaluated: "tuple[CacheAnomalyReason, ...]"
+    observed: bool
+
+
+# The worded terminal labels. The dashboard renders glyph + CSS class from
+# `cacheRowFlagGlyph` / `cacheRowFlagClass`; the terminal has no CSS and a
+# bare glyph cannot say which of the three non-anomalous states a row is in,
+# which is exactly the defect: an unmarked tick meant "evaluated and clean",
+# "one predicate skipped" and "nothing evaluated at all" alike.
+#
+# WIDTH IS A HARD CONSTRAINT, and it is why these read `not eval` rather than
+# the spec's `· not evaluated`. `_layout_cache_table` gives a left-aligned,
+# non-expandable column a compact floor of 8 characters, and at the shipped
+# 120-column default the daily table has EXACTLY 8 columns of slack for a
+# twelfth column once the ultra-compact fallback has run:
+#     120 - 34 border - 10 Date - 12 Models - 56 (8 numeric x 7) = 8.
+# A 15-character `· not evaluated` cannot be rendered there; it truncates to
+# `· not e…`, which is unreadable and is the overflow class the plan refuses
+# to re-take a golden over. The glyph is dropped from the label rather than
+# the word, because an anomalous row already carries the red anomaly glyph on
+# its first cell — so no state loses its marker, and every state gains a word
+# that fits.
+_CACHE_ROW_VERDICT_LABELS: "dict[str, str]" = {
+    "anomalous":   "anomaly",
+    "clean":       "clear",
+    "partial":     "partial",
+    "unevaluated": "not eval",
+}
+
+
+def cache_row_verdict(
+    *,
+    triggered: bool,
+    reasons: "Sequence[CacheAnomalyReason] | None" = None,
+    unevaluated: "Sequence[CacheAnomalyReason] | None" = None,
+    predicates: "Sequence[CacheAnomalyReason] | None" = None,
+    observed: "bool | None" = None,
+) -> CacheRowVerdict:
+    """Classify one row into the four Cache Report states (#620 S1 D6).
+
+    Mirrors ``cacheRowVerdict`` in
+    ``dashboard/web/src/lib/cacheReportVerdict.ts`` exactly, including
+    triggered precedence. The two are separate implementations — one literal
+    classifier is not possible across the language boundary without code
+    generation — and they are pinned to each other by a single shared
+    truth-table fixture, ``tests/fixtures/cache-report-verdict-vectors.json``,
+    which both ``tests/test_620_cache_report_verdict.py`` and
+    ``dashboard/web/__tests__/cacheReportVerdictParity.test.ts`` read.
+
+    ``predicates`` is the set the PROVIDER can evaluate at all, defaulting to
+    ``CACHE_ANOMALY_PREDICATES`` (Claude's pair). Codex can only ever
+    evaluate ``cache_drop``, so a Codex row carrying it alone is FULLY
+    unevaluated; resolving it against the Claude pair would call it
+    ``partial``, which claims some other predicate ran when none exists.
+    Not applicable is not unevaluated.
+
+    ``observed=None`` means observed, so a row from a producer that does not
+    publish the field reads as it does today.
+
+    ``reasons`` is accepted and deliberately unused in the classification:
+    the state is a function of ``triggered`` and the unevaluated set. It is
+    part of the signature because the truth table carries it and a caller
+    should not have to know which half the rule reads.
+    """
+    unevaluated_t = tuple(unevaluated or ())
+    predicate_t = tuple(
+        predicates if predicates is not None else CACHE_ANOMALY_PREDICATES
+    )
+    # Triggered wins first. A thin-baseline cache_drop beside a real
+    # net_negative is still a real anomaly, and the unevaluated presentation
+    # must never swallow it.
+    if triggered:
+        state = "anomalous"
+    elif not unevaluated_t:
+        state = "clean"
+    elif len(unevaluated_t) >= len(predicate_t):
+        state = "unevaluated"
+    else:
+        state = "partial"
+    return CacheRowVerdict(
+        state=state,
+        triggered=bool(triggered),
+        unevaluated=unevaluated_t,
+        observed=observed is not False,
+    )
+
+
+def cache_row_verdict_label(state: str) -> str:
+    """The worded terminal label for one verdict state.
+
+    There is no `unicode_ok` axis: every label above is pure ASCII, so an
+    ASCII-fallback table would be a verbatim copy and the parameter would
+    select between two identical results while every caller still had to
+    pass it. A future label that does need a glyph adds the axis then.
+    """
+    return _CACHE_ROW_VERDICT_LABELS[state]
+
+
 def _classify_anomalies(
     rows: list[CacheRow],
     *,

package/bin/_lib_codex_conversation.py

@@ -2142,6 +2142,20 @@ def infer_codex_event_turns(
     return turns, current
 
 
+def fold_codex_event_turns(events) -> dict:
+    """Map each prefetched physical event's ``line_offset`` to its turn.
+
+    The pure half of ``_file_turn_map`` (#620 S3 X3): the caller supplies the
+    ordered ``codex_conversation_events`` batch and this returns
+    ``{line_offset: turn_id | None}`` over the same lifecycle inference cost
+    attribution and normalized prose already share. Opens no database.
+    """
+    materialized = list(events)
+    turns, _terminal = infer_codex_event_turns(materialized)
+    return {event.line_offset: turn
+            for event, turn in zip(materialized, turns)}
+
+
 def _is_late_turn_anchor(
     record_type: str | None, payload_type: str | None, explicit_turn: str | None,
 ) -> bool:

package/bin/_lib_codex_conversation_query.py

@@ -1272,15 +1272,18 @@ def _tokens_union(tokens: dict) -> dict:
 # ── cost attribution (§5.4) ───────────────────────────────────────────────────
 
 
-def _file_turn_map(conn: sqlite3.Connection, source_path: str) -> dict[int, str | None]:
-    """Exact physical-offset → canonical logical turn for one retained file.
-
-    Cost attribution and normalized prose use the same pure lifecycle inference,
-    including resumed segments whose native proof arrives on task completion.
+def _codex_file_events(conn: sqlite3.Connection, source_path: str) -> list:
+    """One retained file's physical events, in offset order.
+
+    Split out of ``_file_turn_map`` (#620 S3 X3) so the turn attribution can
+    run as a pure fold over a prefetched batch. This walk is UNBOUNDED by
+    construction: it reads every event the file retains, however far the
+    in-window entry sits behind that history, which is why the diagnosis
+    budgets its own use of it rather than calling this directly.
     """
     from _lib_jsonl import CodexPhysicalEvent
 
-    events = [
+    return [
         CodexPhysicalEvent(*row)
         for row in conn.execute(
             "SELECT source_path, line_offset, source_root_key, conversation_key, "
@@ -1291,8 +1294,19 @@ def _file_turn_map(conn: sqlite3.Connection, source_path: str) -> dict[int, str
             (source_path,),
         )
     ]
-    turns, _terminal = kern.infer_codex_event_turns(events)
-    return {event.line_offset: turn for event, turn in zip(events, turns)}
+
+
+def _file_turn_map(conn: sqlite3.Connection, source_path: str) -> dict[int, str | None]:
+    """Exact physical-offset → canonical logical turn for one retained file.
+
+    Cost attribution and normalized prose use the same pure lifecycle inference,
+    including resumed segments whose native proof arrives on task completion.
+
+    Since #620 S3 this is a thin wrapper: it fetches and delegates to
+    ``fold_codex_event_turns``. Its signature, return shape and every caller
+    are unchanged.
+    """
+    return kern.fold_codex_event_turns(_codex_file_events(conn, source_path))
 
 
 def _attribute_costs(conn: sqlite3.Connection, conversation_key: str, effective_speed: str):

package/bin/_lib_codex_pools.py

@@ -38,18 +38,30 @@ def is_model_scoped_codex_quota(logical_limit_key: object, limit_name: object) -
     return codex_model_scoped_quota_pool(limit_name) is not None
 
 
-def _key_has_model_pool(logical_limit_key: object) -> bool:
+def codex_key_model_pool(logical_limit_key: object) -> str | None:
+    """Return the ``modelPool`` an interpreted quota key names, else ``None``.
+
+    The name axis of the same classification ``is_model_scoped_codex_quota``
+    answers as a boolean.  Callers that need to PRESENT the pool (#620 S1's
+    alert scope) read it here rather than parsing the key themselves, so pool
+    classification keeps exactly one home.
+    """
     if not isinstance(logical_limit_key, str):
-        return False
+        return None
     try:
         payload = json.loads(logical_limit_key)
     except (json.JSONDecodeError, TypeError, ValueError):
-        return False
-    return (
-        isinstance(payload, dict)
-        and isinstance(payload.get("modelPool"), str)
-        and bool(payload["modelPool"].strip())
-    )
+        return None
+    if not isinstance(payload, dict):
+        return None
+    pool = payload.get("modelPool")
+    if not isinstance(pool, str) or not pool.strip():
+        return None
+    return pool.strip().lower()
+
+
+def _key_has_model_pool(logical_limit_key: object) -> bool:
+    return codex_key_model_pool(logical_limit_key) is not None
 
 
 def codex_history_is_model_scoped(history, *, baseline=None) -> bool:

package/bin/_lib_conversation.py

@@ -55,10 +55,13 @@ def _join_text_blocks(blocks):
     migration-011 consumer rebuilds the marker text from blocks_json to feed
     _extract_command_invocation, so this lives in the parser kernel (the one
     _cctally_cache already imports) to keep the two derivations identical."""
-    if not blocks:
+    if not isinstance(blocks, list) or not blocks:
         return ""
-    return "\n".join(b.get("text", "") or ""
-                     for b in blocks if b.get("kind") == "text")
+    return "\n".join(
+        text for b in blocks
+        if isinstance(b, dict) and b.get("kind") == "text"
+        and isinstance((text := b.get("text")), str)
+    )
 
 
 def _extract_command_invocation(blocks, text):