cctally 1.97.0 → 1.99.0

package/bin/_lib_aggregators.py

@@ -37,10 +37,12 @@ Spec: docs/superpowers/specs/2026-05-13-bin-cctally-split-design.md
 """
 from __future__ import annotations
 
+import contextlib
 import datetime as dt
 import os
 import pathlib
 import sys
+import threading
 from dataclasses import dataclass
 from typing import Any, Callable, Iterable
 
@@ -476,13 +478,16 @@ def _aggregate_codex_buckets(
         })
         order = models_order.setdefault(key, [])
 
-        cost = _calculate_codex_entry_cost(
-            entry.model,
-            entry.input_tokens,
-            entry.cached_input_tokens,
-            entry.output_tokens,
-            entry.reasoning_output_tokens,
-            speed=speed,
+        cost = (
+            entry.cost_usd if entry.cost_usd is not None
+            else _calculate_codex_entry_cost(
+                entry.model,
+                entry.input_tokens,
+                entry.cached_input_tokens,
+                entry.output_tokens,
+                entry.reasoning_output_tokens,
+                speed=speed,
+            )
         )
 
         bucket["input"] += entry.input_tokens
@@ -588,9 +593,108 @@ def _aggregate_codex_weekly(
     return _aggregate_codex_buckets(entries, key_fn=_week_key, speed=speed)
 
 
+_CODEX_PATH_SCOPE = threading.local()
+
+
+class CodexPathScope:
+    """One source build's Codex path-identity memo (#566 §5.1 item 1).
+
+    Holds the ordered session roots captured when the build opened, plus one
+    parsed identity per distinct ``source_path``. It holds plain tuples only —
+    never a connection, cursor, iterator or open transaction (spec §5.4) — and
+    dies with the ``codex_path_scope`` block that created it, so a
+    ``$CODEX_HOME`` or configuration change between builds can never be served
+    from it.
+
+    ``misses`` counts the parses actually performed, which is the bounded-work
+    quantity the suite asserts on: it can never exceed the number of distinct
+    session paths the build touched.
+    """
+
+    __slots__ = ("_roots", "_parts", "misses")
+
+    def __init__(self, roots: "Iterable[Any] | None" = None) -> None:
+        self._roots: "tuple[Any, ...] | None" = (
+            None if roots is None else tuple(roots)
+        )
+        self._parts: dict[str, tuple[str, str, str]] = {}
+        self.misses = 0
+
+    @property
+    def roots(self) -> "tuple[Any, ...]":
+        """The session roots this build resolved, resolved on FIRST USE.
+
+        Lazy, not eager. ``_codex_session_roots()`` runs an ``is_dir()`` syscall
+        per configured root, and the rooted fallback session view is
+        contractually filesystem-free — it derives identity lexically from
+        ``(source_root_key, source_path)`` and must never discover anything.
+        Resolving at scope entry made every build touch the filesystem even
+        when nothing in it ever asked for a path identity, which broke that
+        contract. Resolving on the first miss still pins one answer for the
+        whole build, which is what the memo key needs.
+        """
+        if self._roots is None:
+            self._roots = tuple(_cctally()._codex_session_roots())
+        return self._roots
+
+    def parts(self, source_path: str) -> tuple[str, str, str]:
+        hit = self._parts.get(source_path)
+        if hit is None:
+            hit = _session_path_parts_for_roots(self.roots, source_path)
+            self._parts[source_path] = hit
+            self.misses += 1
+        return hit
+
+
+def active_codex_path_scope() -> "CodexPathScope | None":
+    """The scope this thread is building under, or None outside a build."""
+    return getattr(_CODEX_PATH_SCOPE, "scope", None)
+
+
+@contextlib.contextmanager
+def codex_path_scope(roots: "Iterable[Any] | None" = None):
+    """Open a build-scoped Codex path memo on this thread.
+
+    The roots are resolved ONCE per scope rather than once per entry, which is
+    the whole point: ``_codex_session_roots()`` runs an ``is_dir()`` syscall per
+    configured root, and the per-entry form ran it 191,304 times on a store
+    holding 2,324 distinct session files. Resolution is deferred to the first
+    path the scope is actually asked about, so a build that never needs a path
+    identity — the rooted fallback session view, which is contractually
+    filesystem-free — still touches nothing.
+
+    Scopes nest and restore, and the memo is thread-local, so the dashboard's
+    sync thread and its HTTP threads never share one.
+    """
+    scope = CodexPathScope(roots)
+    previous = getattr(_CODEX_PATH_SCOPE, "scope", None)
+    _CODEX_PATH_SCOPE.scope = scope
+    try:
+        yield scope
+    finally:
+        _CODEX_PATH_SCOPE.scope = previous
+
+
 def _session_path_parts(source_path: str) -> tuple[str, str, str]:
     """Return (session_id_path, session_file, directory) from a full path.
 
+    Inside a ``codex_path_scope`` the answer comes from that build's memo,
+    keyed on ``(scope roots, source_path)``. Outside one the roots are
+    resolved per call, which is the historic behaviour every CLI caller keeps.
+    """
+    scope = getattr(_CODEX_PATH_SCOPE, "scope", None)
+    if scope is not None:
+        return scope.parts(source_path)
+    return _session_path_parts_for_roots(
+        _cctally()._codex_session_roots(), source_path,
+    )
+
+
+def _session_path_parts_for_roots(
+    roots: Iterable[Any], source_path: str,
+) -> tuple[str, str, str]:
+    """Return (session_id_path, session_file, directory) under ``roots``.
+
     session_id_path = relative path under the matched $CODEX_HOME session
                       root with .jsonl stripped (e.g. "2025/12/25/rollout-...").
     session_file    = basename without .jsonl extension.
@@ -604,7 +708,6 @@ def _session_path_parts(source_path: str) -> tuple[str, str, str]:
     files stay free of maintainer absolute paths), then basename. Direct-JSONL
     roots yield an id relative to <entry> itself (no sessions/ prefix).
     """
-    roots = _cctally()._codex_session_roots()
     p = pathlib.Path(source_path)
     rel: pathlib.PurePath | None = None
     for root in roots:
@@ -659,9 +762,12 @@ def _aggregate_codex_sessions_keyed(
             "cost": 0.0, "models": {}, "models_order": [],
             "last": entry.timestamp,
         })
-        cost = _calculate_codex_entry_cost(
-            entry.model, entry.input_tokens, entry.cached_input_tokens,
-            entry.output_tokens, entry.reasoning_output_tokens, speed=speed,
+        cost = (
+            entry.cost_usd if entry.cost_usd is not None
+            else _calculate_codex_entry_cost(
+                entry.model, entry.input_tokens, entry.cached_input_tokens,
+                entry.output_tokens, entry.reasoning_output_tokens, speed=speed,
+            )
         )
         sess["input"] += entry.input_tokens
         sess["cached_input"] += entry.cached_input_tokens

package/bin/_lib_alert_axes.py

@@ -55,13 +55,18 @@ AXIS_REGISTRY: "tuple[AlertAxisDescriptor, ...]" = (
         "project_budget", "PROJECT", "Project budget", "project_budget_milestones"
     ),
     # Per-vendor Codex budget alerts (calendar-period; calendar-period-codex-budgets
-    # feature). Distinct "CODEX" chip vs the global "BUDGET" / per-project
-    # "PROJECT" chips. As of #143 it shares the unified vendor-tagged
+    # feature). #556 S3 §4.3: the chip reads "BUDGET", the same as the Claude
+    # budget axis, because it names the METRIC. Attribution is the row's source
+    # chip, which under All reads "Codex" — a chip reading "CODEX" beside a
+    # source chip reading "Codex" said the same thing twice and named neither
+    # the metric nor anything the source chip did not already say. The two
+    # BUDGET chips stay visually distinct through `chip--codex_budget`, which
+    # keeps its own colour. As of #143 it shares the unified vendor-tagged
     # `budget_milestones` table with the Claude `budget` axis; the envelope
     # mapper's `WHERE vendor=?` filter does the row-level split (keyed on the
     # resolved period-window start instant period_start_at, threshold).
     AlertAxisDescriptor(
-        "codex_budget", "CODEX", "Codex budget", "budget_milestones", vendor="codex"
+        "codex_budget", "BUDGET", "Codex budget", "budget_milestones", vendor="codex"
     ),
 )
 

package/bin/_lib_budget.py

@@ -187,3 +187,63 @@ def compute_budget_status(inputs: BudgetInputs) -> BudgetStatus:
         low_confidence=low_confidence,
         crossed_thresholds=crossed,
     )
+
+
+def budget_status_payload(
+    *,
+    period: str,
+    window_start_at: dt.datetime,
+    window_end_at: dt.datetime,
+    target_usd: float,
+    spent_usd: float,
+    recent_24h_usd: float,
+    now: dt.datetime,
+    alert_thresholds,
+) -> dict:
+    """The one dashboard-wire budget status, from ALREADY-RESOLVED bounds.
+
+    #556 S5 §3.1/§3.3. Both providers publish this exact object, so a single
+    client component renders either — which is only true if there is one
+    producer. It is a pure operation over resolved bounds and supplied spend
+    facts: it opens no database, reads no configuration, and never calls a bare
+    host-local ``astimezone()``.
+
+    Window resolution deliberately stays OUTSIDE this kernel. ``display.tz =
+    local`` has no DST-aware stdlib handle, so its per-instant resolution lives
+    in ``_cctally_forecast._resolve_local_calendar_window``, and
+    subscription-week resolution opens stats.db. Both are injected by the
+    caller; re-deriving either here would shift a window that straddles a DST
+    transition (issue #136) or make the kernel impure.
+
+    ``alert_thresholds`` is emitted as the normalized tuple the kernel consumed,
+    not as the caller's raw sequence.
+    """
+    inputs = BudgetInputs(
+        target_usd=float(target_usd),
+        spent_usd=float(spent_usd),
+        recent_24h_usd=float(recent_24h_usd),
+        week_start_at=window_start_at,
+        week_end_at=window_end_at,
+        now=now,
+        alert_thresholds=tuple(int(value) for value in alert_thresholds),
+    )
+    status = compute_budget_status(inputs)
+    return {
+        "period": period,
+        "budget_usd": inputs.target_usd,
+        "spent_usd": status.spent_usd,
+        "remaining_usd": status.remaining_usd,
+        "consumption_pct": status.consumption_pct,
+        "verdict": status.verdict,
+        "low_confidence": status.low_confidence,
+        "window_start_at": window_start_at.astimezone(dt.timezone.utc).isoformat(),
+        "window_end_at": window_end_at.astimezone(dt.timezone.utc).isoformat(),
+        "recent_24h_usd": inputs.recent_24h_usd,
+        "alert_thresholds": inputs.alert_thresholds,
+        "pace": {
+            "daily_usd": status.daily_pace_usd,
+            "projected_low_usd": status.projected_eow_low_usd,
+            "projected_high_usd": status.projected_eow_high_usd,
+            "week_avg_projection_usd": status.week_avg_projection_usd,
+        },
+    }

package/bin/_lib_codex_window_attribution.py

@@ -0,0 +1,259 @@
+"""Operator attribution of recorded Codex quota windows (pure kernel).
+
+Spec: ``docs/superpowers/specs/2026-08-14-500-codex-window-attribution-design.md``
+
+The operator asserts that a physical Codex quota window group belongs to an
+account.  This kernel decides, and only decides: which current group each
+assertion owns, and what each observation's account becomes as a result.  Every
+SQL read and every write stays in the glue layer.
+
+Two phases, and they are not interchangeable (spec §6.4.1).  RESOLUTION decides
+which current group an assertion owns and must always run against COMPLETE group
+evidence, because witness matching is population-dependent.  APPLICATION maps the
+resolved ownership onto whatever rows the caller actually asked for.  A bounded
+read may show fewer rows than a full read; it must never show a different owner.
+
+Binding is the four normalized axes plus the tolerance-connected component
+witnessed by raw reset values (spec §5.1).  The canonical anchor is NEVER matched
+on: a later bridging observation can union two components and retire it.
+
+A pure leaf: stdlib only, no ``_cctally_*`` import, no I/O, no writes — the same
+contract ``_lib_codex_account_adoption`` carries, and for the same reason.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from typing import Iterable, Mapping
+
+# The ONE leaf import this module makes, and it exists to avoid a fourth
+# spelling of two constants that already have three (#500 review round 2,
+# finding R2-3).  ``_lib_codex_account_adoption`` imports nothing but the
+# standard library, so binding it here introduces no cycle, no I/O and no
+# ``_cctally_*`` dependency — the leaf contract is about those, not about
+# whether one leaf may name another.  ``_lib_journal`` and
+# ``_lib_codex_account_adoption`` must stay respelled with respect to each other
+# (the journal module is loaded on paths this kernel is not), which is what
+# ``test_the_two_window_constants_have_one_value_across_both_leaves`` pins.
+import _lib_codex_account_adoption as _adoption
+
+
+#: Native length of the account-level Codex weekly quota window, in minutes.
+ACCOUNT_WEEKLY_WINDOW_MINUTES = _adoption.ACCOUNT_WEEKLY_WINDOW_MINUTES
+
+#: The reserved "account could not be determined" sentinel
+#: (``_lib_accounts.UNATTRIBUTED``).
+UNATTRIBUTED_SENTINEL = _adoption.UNATTRIBUTED_SENTINEL
+
+#: Resolution outcomes.  ``RESOLVED`` is the only one that applies anything.
+RESOLVED = "resolved"
+DORMANT = "dormant"
+SPLIT = "split"
+SUPPRESSED_NATIVE = "suppressed_native"
+SUPPRESSED_CONFLICT = "suppressed_conflict"
+#: Covers BOTH out-of-scope shapes the spec's precedence table pairs on one row:
+#: a model-scoped pool (#373) and a window that is not account weekly quota.
+#: They are one outcome because they have one remedy and one meaning — "this
+#: window is not account-level standard quota, so no assertion can file it as
+#: such" — and separating them would put two codes on a distinction no operator
+#: acts on differently.
+SUPPRESSED_MODEL_SCOPED = "suppressed_model_scoped"
+
+
+@dataclass(frozen=True)
+class WindowAssertion:
+    """One active operator assertion, as the derived table holds it."""
+
+    op_id: str
+    account_key: str
+    source_root_key: str
+    logical_limit_key: str
+    observed_slot: str
+    window_minutes: int
+    raw_resets_at_utc: "frozenset[str]"
+
+    def __post_init__(self) -> None:
+        object.__setattr__(
+            self, "raw_resets_at_utc", frozenset(self.raw_resets_at_utc))
+        if not self.raw_resets_at_utc:
+            raise ValueError("an assertion must carry at least one witness")
+
+    @property
+    def axes(self) -> tuple:
+        return (self.source_root_key, self.logical_limit_key,
+                self.observed_slot, self.window_minutes)
+
+
+@dataclass(frozen=True)
+class WindowGroup:
+    """One current physical window group, as the loader's complete evidence
+    describes it.
+
+    ``identified_accounts`` is the set of non-sentinel accounts natively present.
+    ``model_scoped`` is the authoritative ``_lib_codex_pools`` verdict, re-checked
+    at every evaluation because ``limit_name`` sits outside identity equality and
+    can change on re-materialization (spec §7).
+    """
+
+    group_key: tuple
+    source_root_key: str
+    logical_limit_key: str
+    observed_slot: str
+    window_minutes: int
+    raw_resets_at_utc: "frozenset[str]"
+    identified_accounts: "frozenset[str]" = frozenset()
+    model_scoped: bool = False
+
+    def __post_init__(self) -> None:
+        object.__setattr__(
+            self, "raw_resets_at_utc", frozenset(self.raw_resets_at_utc))
+        object.__setattr__(
+            self, "identified_accounts", frozenset(self.identified_accounts))
+
+    @property
+    def axes(self) -> tuple:
+        return (self.source_root_key, self.logical_limit_key,
+                self.observed_slot, self.window_minutes)
+
+    @property
+    def in_scope(self) -> bool:
+        return (self.window_minutes == ACCOUNT_WEEKLY_WINDOW_MINUTES
+                and not self.model_scoped)
+
+
+@dataclass(frozen=True)
+class AssertionResolution:
+    """What one assertion resolves to against the current population."""
+
+    op_id: str
+    account_key: str
+    outcome: str
+    group_key: "tuple | None" = None
+    matched_group_count: int = 0
+    conflicting_account_keys: "frozenset[str]" = frozenset()
+
+    def __post_init__(self) -> None:
+        object.__setattr__(
+            self, "conflicting_account_keys",
+            frozenset(self.conflicting_account_keys))
+
+    @property
+    def applies(self) -> bool:
+        return self.outcome == RESOLVED
+
+
+def resolve_window_attributions(
+    assertions: Iterable[WindowAssertion],
+    groups: Iterable[WindowGroup],
+) -> "tuple[tuple[AssertionResolution, ...], Mapping[tuple, str]]":
+    """Resolve every assertion against COMPLETE current group evidence.
+
+    Returns ``(resolutions, ownership)`` where ``ownership`` maps a group key to
+    the account that assertion supplies.  Only ``RESOLVED`` assertions appear in
+    ``ownership``.
+
+    Precedence, in order (spec §7):
+
+    1. Zero matching groups is DORMANT — recorded, honest, applying to nothing.
+       This is the correct outcome when the underlying rollout evidence has
+       evaporated; the alternative would be fabricating a window to attach to.
+    2. More than one matching group is SPLIT.  The component has since divided in
+       a way the assertion cannot adjudicate, so it applies nothing.
+    3. Model-scoped and non-weekly groups are out of scope entirely (#373).
+    4. Native evidence always wins.  A group already naming a real account is
+       authoritative and is never re-assigned, so the assertion is suppressed
+       rather than fighting it.  This holds whether the native account agrees or
+       disagrees; a matching one simply has nothing to do.
+    5. Two assertions naming DIFFERENT accounts for one group FAIL CLOSED and
+       neither applies.  Journal order is the wrong tiebreaker for an operator
+       assertion: a stale or mistaken second assertion would silently displace a
+       correct first one with no signal.  A visible conflict forces a retraction.
+
+    Order-independent in its verdicts: the conflict pass below runs after every
+    assertion has been matched, so two assertions disagreeing about one group
+    reach ``SUPPRESSED_CONFLICT`` whichever order they arrive in.
+    """
+    group_list = tuple(groups)
+    resolutions: "list[AssertionResolution]" = []
+    claims: "dict[tuple, set[str]]" = {}
+
+    for assertion in assertions:
+        candidates = [
+            group for group in group_list
+            if group.axes == assertion.axes
+            and (group.raw_resets_at_utc & assertion.raw_resets_at_utc)
+        ]
+        if not candidates:
+            resolutions.append(AssertionResolution(
+                op_id=assertion.op_id, account_key=assertion.account_key,
+                outcome=DORMANT))
+            continue
+        if len(candidates) > 1:
+            resolutions.append(AssertionResolution(
+                op_id=assertion.op_id, account_key=assertion.account_key,
+                outcome=SPLIT, matched_group_count=len(candidates)))
+            continue
+        group = candidates[0]
+        if not group.in_scope:
+            resolutions.append(AssertionResolution(
+                op_id=assertion.op_id, account_key=assertion.account_key,
+                outcome=SUPPRESSED_MODEL_SCOPED, group_key=group.group_key,
+                matched_group_count=1))
+            continue
+        if group.identified_accounts:
+            resolutions.append(AssertionResolution(
+                op_id=assertion.op_id, account_key=assertion.account_key,
+                outcome=SUPPRESSED_NATIVE, group_key=group.group_key,
+                matched_group_count=1,
+                conflicting_account_keys=group.identified_accounts))
+            continue
+        claims.setdefault(group.group_key, set()).add(assertion.account_key)
+        resolutions.append(AssertionResolution(
+            op_id=assertion.op_id, account_key=assertion.account_key,
+            outcome=RESOLVED, group_key=group.group_key, matched_group_count=1))
+
+    final: "list[AssertionResolution]" = []
+    ownership: "dict[tuple, str]" = {}
+    for resolution in resolutions:
+        if not resolution.applies:
+            final.append(resolution)
+            continue
+        claimants = claims.get(resolution.group_key, set())
+        if len(claimants) > 1:
+            final.append(replace(
+                resolution, outcome=SUPPRESSED_CONFLICT,
+                conflicting_account_keys=frozenset(claimants)))
+            continue
+        ownership[resolution.group_key] = resolution.account_key
+        final.append(resolution)
+    return tuple(final), ownership
+
+
+def apply_resolution(
+    ownership: "Mapping[tuple, str]",
+    observations: Iterable,
+    group_key_of,
+    account_key_of,
+    with_account,
+) -> tuple:
+    """Stamp resolved ownership onto currently-unattributed observations.
+
+    Deliberately caller-parameterized on ``group_key_of`` / ``account_key_of`` /
+    ``with_account`` so this leaf never imports the observation type.  Runs
+    BEFORE the ordinary continuity fold, which then finds nothing left to adopt
+    in an attributed group.
+
+    An already-identified observation is never re-stamped, matching
+    ``adopt_unidentified_observations``.  ``None`` and the empty string are
+    admitted as unattributed alongside the literal sentinel, because the cache
+    column is nullable and all three spellings mean the same thing on the read
+    path (``entry_is_unattributed`` states the same rule for the spend axis).
+    """
+    result = []
+    for observation in observations:
+        account = account_key_of(observation)
+        if account and account != UNATTRIBUTED_SENTINEL:
+            result.append(observation)
+            continue
+        owner = ownership.get(group_key_of(observation))
+        result.append(with_account(observation, owner) if owner else observation)
+    return tuple(result)