cctally 1.85.1 → 1.87.0

package/bin/_cctally_record.py

@@ -702,6 +702,7 @@ def maybe_record_milestone(
 
         # Threshold crossed — sync cost before recording so the milestone
         # captures up-to-date cumulative cost, not a stale snapshot.
+        cost_synced = True
         try:
             if retained_selection is None:
                 retained_selection = _cctally().WeekSelection(
@@ -740,7 +741,13 @@ def maybe_record_milestone(
                 retained_selection=retained_selection,
             )
         except Exception as exc:
-            eprint(f"[milestone] cost sync failed, using latest available: {exc}")
+            # The snapshot read below would now return a row from an EARLIER
+            # crossing, so recording here stamps that older cumulative onto
+            # this threshold — a write-once row with a $0.00 marginal and a
+            # fabricated $/1%. Fall through only far enough to reach the
+            # skip guard on the snapshot branch.
+            cost_synced = False
+            eprint(f"[milestone] cost sync failed: {exc}")
 
         week_start = dt.date.fromisoformat(week_start_date)
         week_end = dt.date.fromisoformat(week_end_date)
@@ -762,17 +769,36 @@ def maybe_record_milestone(
             effective_ref = adjusted[0]
 
         if _week_ref_has_reset_event(conn, effective_ref):
-            live_cost = _compute_cost_for_weekref(
-                effective_ref,
-                account_key=account_key,
-                as_of=as_of,
-            )
+            import _cctally_cache  # fail-closed attribution guard (#341)
+            try:
+                live_cost = _compute_cost_for_weekref(
+                    effective_ref,
+                    account_key=account_key,
+                    as_of=as_of,
+                )
+            except _cctally_cache.AccountAttributionUnavailable as exc:
+                # Same contract the budget ladder already holds (#341 Task 4):
+                # an account-scoped read that fell into the fail-closed guard
+                # SKIPS this tick and fires on the next healthy one. Never
+                # re-raised — on the passed-conn (ingest) path a bare raise
+                # would abort the whole cycle over a transient lock.
+                eprint("[milestone] account attribution unavailable, "
+                       f"skipping this crossing: {exc}")
+                return
             if live_cost is None:
                 eprint("[milestone] could not compute effective-range cost, skipping")
                 return
             cumulative_cost = live_cost
             cost_snapshot_id = 0  # no snapshot row to anchor against
         else:
+            if not cost_synced:
+                # The latest snapshot predates this crossing. Milestones are
+                # write-once, so a stale cumulative here is permanent; skip
+                # instead. The next observation still sees current_floor >
+                # max_existing and records the crossing with a real cost.
+                eprint("[milestone] skipping this crossing — its cost would "
+                       "come from a snapshot taken before the crossing")
+                return
             # Account-scoped read (#341 P2-1): the cost snapshot was just
             # materialized under `account_key`, so scope the read to it — the
             # merged (account-blind) read would return another account's row on

package/bin/_lib_aggregators.py

@@ -387,6 +387,9 @@ class CodexBucketUsage:
     period_end_at: dt.datetime | None = None
     used_pct: float | None = None
     dollar_per_pct: float | None = None
+    # #424: owning accounts for a pooled native weekly period. Empty for
+    # calendar buckets, focused account children, and undecorated providers.
+    account_keys: tuple[str, ...] = ()
 
 
 @dataclass

package/bin/_lib_codex_account_adoption.py

@@ -0,0 +1,173 @@
+"""Codex window-scoped spend adoption (pure kernel).
+
+Spec: ``docs/superpowers/specs/2026-07-30-codex-window-scoped-spend-adoption.md``
+
+``adopt_unidentified_observations`` (``bin/_lib_quota.py``) applies the #341 §2
+window-account continuity rule to the OBSERVATION axis: inside one physical
+quota window, unidentified observations are adopted by the window's account iff
+exactly one identified account is ever observed for that window key.  This
+kernel applies the same inference, with the same grouping key and the same
+guard, to the SPEND axis — ``codex_session_entries.account_key``.
+
+A pure leaf module: stdlib only, no cctally imports.  The caller supplies window
+descriptors (already grouped on ``_lib_quota._physical_window_key`` and already
+folded, so ``identified_accounts`` is the window's post-fold identified set) and
+candidate entries; this kernel decides, and only decides.  Every SQL read and
+every write stays in the glue layer.
+"""
+from __future__ import annotations
+
+import datetime as dt
+from dataclasses import dataclass
+from typing import Iterable
+
+
+#: Native length of the account-level Codex weekly quota window, in minutes.
+ACCOUNT_WEEKLY_WINDOW_MINUTES = 10_080
+
+
+#: The reserved "account could not be determined" sentinel
+#: (``_lib_accounts.UNATTRIBUTED``), spelled here so this leaf stays import-free.
+UNATTRIBUTED_SENTINEL = "unattributed"
+
+
+def entry_is_unattributed(account_key: object) -> bool:
+    """Whether a ``codex_session_entries`` row is still up for adoption.
+
+    ``NULL`` is the stamp every never-decided row carries (#416 spec D1:
+    ``stably_absent`` -> ``NULL``), and the empty string is its degenerate
+    spelling.  The literal ``unattributed`` sentinel is admitted too: no producer
+    writes it to this column today, but ``_codex_cache_account_predicate`` counts
+    it in the ``unattributed`` BUCKET, so excluding it here would make such a row
+    permanently unadoptable — visible as nobody's money and ineligible for the
+    only mechanism that could give it an owner.
+    """
+    return (
+        account_key is None
+        or account_key == ""
+        or account_key == UNATTRIBUTED_SENTINEL
+    )
+
+
+@dataclass(frozen=True)
+class SpendAdoptionWindow:
+    """One physical Codex quota window, as the fold left it.
+
+    ``canonical_resets_at`` is the tolerance-anchored reset (#416 §4.1), never a
+    raw jittered provider value — the same anchor
+    ``_lib_quota._physical_window_key`` groups on.  ``identified_accounts`` is
+    the set of non-``unattributed`` account keys observed for that key.
+    """
+
+    source_root_key: str
+    window_minutes: int
+    canonical_resets_at: dt.datetime
+    identified_accounts: frozenset[str] = frozenset()
+    model_scoped: bool = False
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.source_root_key, str) or not self.source_root_key:
+            raise ValueError("source_root_key must be a non-empty string")
+        if (not isinstance(self.window_minutes, int)
+                or isinstance(self.window_minutes, bool)
+                or self.window_minutes <= 0):
+            raise ValueError("window_minutes must be a positive integer")
+        reset = self.canonical_resets_at
+        if reset.tzinfo is None or reset.utcoffset() is None:
+            raise ValueError("canonical_resets_at must be timezone-aware")
+        object.__setattr__(
+            self, "identified_accounts", frozenset(self.identified_accounts))
+
+    @property
+    def nominal_start_at(self) -> dt.datetime:
+        return self.canonical_resets_at - dt.timedelta(
+            minutes=self.window_minutes)
+
+    @property
+    def in_scope(self) -> bool:
+        """Account-level weekly windows only.
+
+        A 5h window nests inside the weekly one and adds no evidence; a
+        model-scoped pool such as GPT-5.3-Codex-Spark is never account weekly
+        quota (#373).  Both are excluded from candidacy entirely, so neither
+        stamps nor blocks.
+        """
+        return (
+            self.window_minutes == ACCOUNT_WEEKLY_WINDOW_MINUTES
+            and not self.model_scoped
+        )
+
+    def covers(self, timestamp: dt.datetime) -> bool:
+        """Whether ``timestamp`` falls in the NOMINAL ``[start, reset)`` range.
+
+        Nominal rather than first-observation: spend before the window's first
+        retained observation is still spend inside the cycle.
+        """
+        return self.nominal_start_at <= timestamp < self.canonical_resets_at
+
+
+@dataclass(frozen=True)
+class SpendAdoptionCandidate:
+    """One ``codex_session_entries`` row offered to the pass."""
+
+    entry_id: int
+    source_root_key: str
+    timestamp: dt.datetime
+    account_key: "str | None" = None
+
+
+@dataclass(frozen=True)
+class SpendAdoptionStamp:
+    """One decided write: give ``entry_id`` this account."""
+
+    entry_id: int
+    account_key: str
+
+
+def build_spend_adoption_plan(
+    windows: Iterable[SpendAdoptionWindow],
+    candidates: Iterable[SpendAdoptionCandidate],
+) -> tuple[SpendAdoptionStamp, ...]:
+    """Return the stamping plan, ordered by ``entry_id``.
+
+    An in-scope window CLAIMS every candidate its nominal range covers on its own
+    root.  A candidate is stamped iff the UNION of identified accounts across
+    every claiming window is exactly one.
+
+    A claiming window that identifies no account contributes nothing to that
+    union and therefore does NOT block: absence of evidence is not evidence of
+    ambiguity.  That is the same shape ``adopt_unidentified_observations`` uses on
+    the observation axis, which likewise resolves a window from its *identified*
+    observations only and treats an unidentified population as no evidence.  The
+    first implementation blocked on any claiming window that resolved to nothing
+    and measured ZERO stamped rows on a real store: weekly resets move by days,
+    so one cycle overlaps many neighbours and pre-attribution history is
+    unidentified by construction — one such neighbour was always enough to veto.
+
+    Two claiming windows naming DIFFERENT accounts still leave the entry alone
+    (union of two), and so does a single window that itself saw two accounts
+    (#341 never-combine).  An already-identified row is never re-stamped, so
+    re-running over this kernel's own output returns an empty plan.
+    """
+    by_root: dict[str, list[SpendAdoptionWindow]] = {}
+    for window in windows:
+        if window.in_scope:
+            by_root.setdefault(window.source_root_key, []).append(window)
+
+    stamps: list[SpendAdoptionStamp] = []
+    for candidate in candidates:
+        if not entry_is_unattributed(candidate.account_key):
+            continue
+        identified: set[str] = set()
+        for window in by_root.get(candidate.source_root_key, ()):
+            if window.covers(candidate.timestamp):
+                identified |= window.identified_accounts
+                if len(identified) > 1:
+                    break
+        if len(identified) != 1:
+            continue
+        account = next(iter(identified))
+        stamps.append(SpendAdoptionStamp(
+            entry_id=candidate.entry_id, account_key=account))
+    stamps.sort(key=lambda stamp: (stamp.entry_id, stamp.account_key))
+    return tuple(stamps)

package/bin/_lib_doctor.py

@@ -2607,6 +2607,33 @@ def _check_accounts_attribution(s: DoctorState) -> CheckResult:
     )
 
 
+def _check_accounts_codex_reset_anchors(s: DoctorState) -> CheckResult:
+    """Surface Codex quota rows that landed after migration 032 with no anchor."""
+    st = s.accounts_state or {}
+    try:
+        null_rows = int(st.get("codex_null_reset_anchors") or 0)
+    except (TypeError, ValueError):
+        null_rows = 0
+    details = {"null_anchor_rows": null_rows}
+    if null_rows > 0:
+        return CheckResult(
+            id="accounts.codex_reset_anchors",
+            title="Codex reset anchors",
+            severity="warn",
+            summary=f"{null_rows} Codex quota observation(s) lack a canonical reset anchor",
+            remediation="Run `cctally cache-sync --source codex --rebuild`",
+            details=details,
+        )
+    return CheckResult(
+        id="accounts.codex_reset_anchors",
+        title="Codex reset anchors",
+        severity="ok",
+        summary="Codex reset anchors complete",
+        remediation=None,
+        details=details,
+    )
+
+
 _CATEGORY_DEFINITIONS: tuple[tuple[str, str, tuple[tuple[str, str], ...]], ...] = (
     ("install", "Install", (
         ("install.mode", "_check_install_dev_mode"),
@@ -2667,6 +2694,7 @@ _CATEGORY_DEFINITIONS: tuple[tuple[str, str, tuple[tuple[str, str], ...]], ...]
         ("accounts.registry", "_check_accounts_registry"),
         ("accounts.freshness", "_check_accounts_freshness"),
         ("accounts.attribution", "_check_accounts_attribution"),
+        ("accounts.codex_reset_anchors", "_check_accounts_codex_reset_anchors"),
     )),
     ("pricing", "Pricing", (
         ("pricing.coverage", "_check_pricing_coverage"),

package/bin/_lib_quota.py

@@ -78,11 +78,11 @@ def resolve_reset_anchor(
     anchor already in ``anchors`` or the observation's own raw value, never a
     recomputed centroid. Assignment picks the NEAREST anchor within tolerance,
     breaking a tie on the earlier anchor, so for a given anchor set the answer
-    does not depend on the order the anchors were established in. (The anchor
-    SET can still depend on arrival order in the pathological case of a chain of
-    observations each within tolerance of its neighbour but not of the first;
-    real jitter is seconds wide, so a real cluster collapses to one anchor under
-    every order.)
+    does not depend on the order the anchors were established in. The anchor
+    SET can still depend on arrival order in the chain-of-neighbours case. This
+    is retained as migration 032's reference rule; production ingest uses
+    :class:`ResetAnchorComponents` after #425 real-data evidence proved those
+    chains occur.
     """
     _require_aware(raw_reset, "raw_reset")
     if (isinstance(anchors, ResetAnchorIndex)
@@ -121,7 +121,9 @@ class ResetAnchorIndex:
     nearest within tolerance, ties broken on the earlier anchor, first sight
     wins, the anchor never moves, and the pathological chain-of-neighbours
     order-dependence that docstring documents is preserved exactly, because the
-    anchor SET is still whatever the caller established in whatever order.
+    anchor SET is still whatever the caller established in whatever order. This
+    class remains the exact migration-032 oracle; current ingest uses
+    ``ResetAnchorComponents``.
 
     Only the LOOKUP changes. The linear scan did a full ``datetime`` subtraction
     against every established anchor, and a 5h group accumulates ~1,750 anchors
@@ -204,6 +206,156 @@ class ResetAnchorIndex:
         return len(self._order)
 
 
+class ResetAnchorComponents:
+    """Tolerance-connected raw-reset components with first-sight anchors.
+
+    ``ResetAnchorIndex`` intentionally preserves the original migration-032
+    rule: compare a raw reset only with already-established anchors. Real data
+    proved that rule can split a chain whose adjacent members are all within
+    tolerance. This index retains every distinct raw reset as evidence and
+    unions adjacent members transitively. The member with the smallest stable
+    physical ``order_key`` remains the completed component's canonical anchor,
+    independent of filesystem traversal or journal batch arrival. Callers that
+    omit an order key retain insertion-order behavior for compatibility.
+
+    ``add`` returns both the winning anchor and any formerly independent
+    component anchors retired by the union. Writers use the retired set to
+    converge rows materialized before a later bridge observation arrived.
+    """
+
+    __slots__ = (
+        "_tolerance", "_buckets", "_parent", "_rank",
+        "_anchor", "_first_order", "_member_order", "_next_order",
+    )
+
+    def __init__(
+        self, raws: Iterable[dt.datetime] = (),
+        *, tolerance_seconds: int = CODEX_RESET_ANCHOR_TOLERANCE_SECONDS,
+    ) -> None:
+        if not isinstance(tolerance_seconds, int) or isinstance(
+                tolerance_seconds, bool):
+            raise ValueError("tolerance_seconds must be an int")
+        if tolerance_seconds <= 0:
+            raise ValueError("tolerance_seconds must be positive")
+        self._tolerance = tolerance_seconds
+        self._buckets: dict[int, list[dt.datetime]] = {}
+        self._parent: dict[dt.datetime, dt.datetime] = {}
+        self._rank: dict[dt.datetime, int] = {}
+        self._anchor: dict[dt.datetime, dt.datetime] = {}
+        self._first_order: dict[
+            dt.datetime, tuple[str, int, int]
+        ] = {}
+        self._member_order: dict[
+            dt.datetime, tuple[str, int, int]
+        ] = {}
+        self._next_order = 0
+        for raw in raws:
+            self.add(raw)
+
+    @property
+    def tolerance_seconds(self) -> int:
+        return self._tolerance
+
+    def _bucket(self, value: dt.datetime) -> int:
+        return int(value.timestamp() // self._tolerance)
+
+    def _find(self, value: dt.datetime) -> dt.datetime:
+        parent = self._parent[value]
+        if parent != value:
+            self._parent[value] = self._find(parent)
+        return self._parent[value]
+
+    def _union(
+        self, left: dt.datetime, right: dt.datetime,
+    ) -> dt.datetime:
+        left_root = self._find(left)
+        right_root = self._find(right)
+        if left_root == right_root:
+            return left_root
+        if self._rank[left_root] < self._rank[right_root]:
+            left_root, right_root = right_root, left_root
+        self._parent[right_root] = left_root
+        if self._rank[left_root] == self._rank[right_root]:
+            self._rank[left_root] += 1
+        if self._first_order[right_root] < self._first_order[left_root]:
+            self._anchor[left_root] = self._anchor[right_root]
+            self._first_order[left_root] = self._first_order[right_root]
+        del self._anchor[right_root]
+        del self._first_order[right_root]
+        return left_root
+
+    def add(
+        self, raw_reset: dt.datetime,
+        *, order_key: "tuple[str, int, int] | None" = None,
+    ) -> tuple[dt.datetime, tuple[dt.datetime, ...]]:
+        """Add one raw reset and return ``(anchor, retired_anchors)``."""
+        _require_aware(raw_reset, "raw_reset")
+        if order_key is None:
+            order_key = ("", self._next_order, 0)
+        if (
+            not isinstance(order_key, tuple) or len(order_key) != 3
+            or not isinstance(order_key[0], str)
+            or not isinstance(order_key[1], int)
+            or isinstance(order_key[1], bool)
+            or not isinstance(order_key[2], int)
+            or isinstance(order_key[2], bool)
+        ):
+            raise ValueError(
+                "order_key must be a (source_path, line_offset, row_id) tuple")
+        self._next_order += 1
+        if raw_reset in self._parent:
+            root = self._find(raw_reset)
+            previous = self._anchor[root]
+            if order_key < self._member_order[raw_reset]:
+                self._member_order[raw_reset] = order_key
+                if order_key < self._first_order[root]:
+                    self._first_order[root] = order_key
+                    self._anchor[root] = raw_reset
+            winner = self._anchor[root]
+            retired = (previous,) if previous != winner else ()
+            return winner, retired
+
+        probe = self._bucket(raw_reset)
+        neighbours: list[dt.datetime] = []
+        for bucket_id in (probe - 1, probe, probe + 1):
+            for candidate in self._buckets.get(bucket_id, ()):
+                if abs((raw_reset - candidate).total_seconds()) <= self._tolerance:
+                    neighbours.append(candidate)
+
+        self._parent[raw_reset] = raw_reset
+        self._rank[raw_reset] = 0
+        self._anchor[raw_reset] = raw_reset
+        self._first_order[raw_reset] = order_key
+        self._member_order[raw_reset] = order_key
+        self._buckets.setdefault(probe, []).append(raw_reset)
+
+        prior_anchors = {raw_reset}
+        prior_anchors.update(
+            self._anchor[self._find(candidate)] for candidate in neighbours)
+        root = raw_reset
+        for candidate in neighbours:
+            root = self._union(root, candidate)
+        winner = self._anchor[self._find(root)]
+        return winner, tuple(sorted(prior_anchors - {winner}))
+
+    def canonical(self, raw_reset: dt.datetime) -> dt.datetime:
+        """Return the completed component's first-sight anchor."""
+        _require_aware(raw_reset, "raw_reset")
+        return self._anchor[self._find(raw_reset)]
+
+    def __contains__(self, anchor: object) -> bool:
+        if not isinstance(anchor, dt.datetime):
+            return False
+        return anchor in self._buckets.get(self._bucket(anchor), ())
+
+    def __iter__(self):
+        """Distinct raw-reset evidence in insertion order."""
+        return iter(self._parent)
+
+    def __len__(self) -> int:
+        return len(self._parent)
+
+
 @dataclass(frozen=True)
 class QuotaWindowIdentity:
     """One root-qualified native quota window identity.
@@ -313,6 +465,7 @@ class QuotaBlock:
     last_observed_at: dt.datetime
     first_percent: float
     current_percent: float
+    physical_observations: tuple[QuotaObservation, ...] = ()
 
 
 @dataclass(frozen=True)
@@ -577,7 +730,14 @@ def build_blocks(observations: Iterable[QuotaObservation]) -> tuple[QuotaBlock,
     ``QuotaBlock.resets_at``, which every renderer shows, is that same anchor.
     """
     by_block: dict[tuple[QuotaWindowIdentity, dt.datetime], list[QuotaObservation]] = {}
+    physical_by_block: dict[
+        tuple[QuotaWindowIdentity, dt.datetime], list[QuotaObservation]
+    ] = {}
     for history in build_history(observations):
+        for observation in history.physical_observations:
+            physical_by_block.setdefault(
+                (history.identity, observation.canonical_resets_at), []
+            ).append(observation)
         for observation in history.observations:
             by_block.setdefault(
                 (history.identity, observation.canonical_resets_at), []
@@ -599,6 +759,10 @@ def build_blocks(observations: Iterable[QuotaObservation]) -> tuple[QuotaBlock,
             last_observed_at=last.captured_at,
             first_percent=first.used_percent,
             current_percent=last.used_percent,
+            physical_observations=tuple(sorted(
+                physical_by_block[(identity, resets_at)],
+                key=physical_order_key,
+            )),
         ))
     return tuple(blocks)