cctally 1.83.0 → 1.84.0

package/bin/_lib_doctor.py

@@ -184,6 +184,11 @@ class DoctorState:
     # absent (pre-first-sync) or cache unreadable — check degrades OK.
     parse_health_claude: Optional[dict] = None
     parse_health_codex: Optional[dict] = None
+    # #416 review B4: `{"files": N, "at": iso}` written by a whole-tree Codex
+    # sync that deferred files because a `<root>/auth.json` read torn, deleted
+    # by the next whole-tree sync that defers none. None = key absent (the
+    # normal state) or cache unreadable — the check degrades OK.
+    codex_torn_deferred: Optional[dict] = None
     # #279 S2 (F5b): PRAGMA quick_check(1) results, gathered ONLY under
     # doctor_gather_state(deep=True) (CLI cmd_doctor) — the dashboard
     # rebuild loop calls the gather every rebuild and quick_check on a
@@ -191,6 +196,7 @@ class DoctorState:
     # "open failed: ..." | None = not run.
     stats_db_quick_check: Optional[str] = None
     cache_db_quick_check: Optional[str] = None
+    conversations_db_quick_check: Optional[str] = None
     # #279 S2 (F5c): non-blocking flock probes on the two sync lock files
     # (name -> True held / False free / None unreadable). Probe never
     # creates files (doctor read-only contract). None = probe errored.
@@ -1899,7 +1905,9 @@ def _check_data_parse_health(s: DoctorState) -> CheckResult:
 
 def _check_db_integrity(s: DoctorState) -> CheckResult:
     details = {"stats_quick_check": s.stats_db_quick_check,
-               "cache_quick_check": s.cache_db_quick_check}
+               "cache_quick_check": s.cache_db_quick_check,
+               "conversations_quick_check":
+                   s.conversations_db_quick_check}
     if s.stats_db_quick_check is not None and s.stats_db_quick_check != "ok":
         return CheckResult(
             id="db.integrity", title="Integrity", severity="fail",
@@ -1920,7 +1928,27 @@ def _check_db_integrity(s: DoctorState) -> CheckResult:
                          "`cctally cache-sync --rebuild`."),
             details=details,
         )
-    if s.stats_db_quick_check is None and s.cache_db_quick_check is None:
+    if (
+        s.conversations_db_quick_check is not None
+        and s.conversations_db_quick_check != "ok"
+    ):
+        return CheckResult(
+            id="db.integrity", title="Integrity", severity="warn",
+            summary=(
+                "conversations.db quick_check: "
+                f"{s.conversations_db_quick_check}"
+            ),
+            remediation=(
+                "conversations.db is re-derivable — run "
+                "`cctally cache-sync --rebuild`."
+            ),
+            details=details,
+        )
+    if (
+        s.stats_db_quick_check is None
+        and s.cache_db_quick_check is None
+        and s.conversations_db_quick_check is None
+    ):
         return CheckResult(
             id="db.integrity", title="Integrity", severity="ok",
             summary="not checked (fast gather — run `cctally doctor`)",
@@ -2505,6 +2533,42 @@ def _check_accounts_freshness(s: DoctorState) -> CheckResult:
     )
 
 
+def _check_accounts_codex_identity(s: DoctorState) -> CheckResult:
+    """WARN while a torn `<codex root>/auth.json` is deferring Codex ingest.
+
+    The defer is correct — spec §3.6's stable-read protocol never guesses an
+    account — but since #416 a growing ALREADY-DECIDED rollout also consults
+    `auth.json`, so a persistently torn file (truncated, half-written, replaced
+    by a directory) halts every rollout under that root, not just the
+    never-decided ones. `cache-sync` still exits 0, so this leg is the only
+    standing signal that Codex spend and quota have stopped moving.
+
+    Not R8-gated: it names no account and adds no per-account column, so it
+    reports at any account count (docs/accounts-gotchas.md).
+    """
+    st = s.codex_torn_deferred or {}
+    try:
+        files = int(st.get("files") or 0)
+    except (TypeError, ValueError):
+        files = 0
+    details = {"files": files, "at": st.get("at")}
+    if files > 0:
+        return CheckResult(
+            id="accounts.codex_identity", title="Codex account identity",
+            severity="warn",
+            summary=(f"{files} Codex rollout(s) deferred — auth.json read torn; "
+                     "no usage attributed from them"),
+            remediation=("Check the Codex auth.json (re-run `codex login` if it is "
+                         "truncated), then `cctally cache-sync --source codex`"),
+            details=details,
+        )
+    return CheckResult(
+        id="accounts.codex_identity", title="Codex account identity",
+        severity="ok", summary="no deferred Codex ingest",
+        remediation=None, details=details,
+    )
+
+
 def _check_accounts_attribution(s: DoctorState) -> CheckResult:
     """WARN when Claude usage is flowing but landing in `unattributed` despite a
     resolved active account (the stamping pipeline is broken), or while the
@@ -2599,6 +2663,7 @@ _CATEGORY_DEFINITIONS: tuple[tuple[str, str, tuple[tuple[str, str], ...]], ...]
     )),
     ("accounts", "Accounts", (
         ("accounts.identity", "_check_accounts_identity"),
+        ("accounts.codex_identity", "_check_accounts_codex_identity"),
         ("accounts.registry", "_check_accounts_registry"),
         ("accounts.freshness", "_check_accounts_freshness"),
         ("accounts.attribution", "_check_accounts_attribution"),

package/bin/_lib_journal.py

@@ -1118,6 +1118,54 @@ def make_account_label(
     return make_op(at=at, src="account-label", payload=payload)
 
 
+def make_codex_file_account(
+    at: str,
+    *,
+    root_scope: str,
+    file_identity: str,
+    incarnation: int,
+    from_offset: int,
+    account_key: "str | None" = None,
+) -> dict:
+    """Build a ``codex_file_account`` op — the DURABLE attribution decision for
+    one byte range of one rollout incarnation (#416 spec §3.3).
+
+    Why this exists: the Codex account is otherwise re-derived from the live
+    ``auth.json`` on every ingest cycle, so a ``cache-sync --rebuild`` (which
+    re-reads every rollout from offset 0, cache.db being fully re-derivable by
+    design) re-stamps the entire history with whoever is logged in at that
+    moment. A decision that is journaled ONCE and thereafter only replayed is
+    immune to that.
+
+    The identity is ``(root_scope, file_identity, incarnation, from_offset)``,
+    never ``(source_path, offset)`` (spec §3.2): discovery persists the first
+    configured candidate spelling, so reordering ``$CODEX_HOME`` roots or
+    respelling a symlink makes the same physical file miss a path-keyed map; and
+    a truncation or root requalification resets the file to offset zero, so a
+    permanent ``(path, offset)`` interval would overlap newly reused offsets and
+    stamp a replacement file with the previous account. A truncation or
+    requalification opens a NEW ``incarnation`` whose intervals can never
+    overlap the old one.
+
+    Sentinel encoding follows the two-shaped stamp rule
+    (``docs/accounts-gotchas.md``): this is an **op**, so a real account rides
+    ``payload.account_key`` and a stably-absent identity (no auth / api-key mode)
+    is an explicit sentinel decision that OMITS the field. Never write the
+    literal ``"unattributed"``. A **torn** read appends NOTHING at all — it is
+    not a decision (spec §3.6).
+    """
+    payload = {
+        "kind": "codex_file_account",
+        "root_scope": root_scope,
+        "file_identity": file_identity,
+        "incarnation": incarnation,
+        "from_offset": from_offset,
+    }
+    if account_key is not None:
+        payload["account_key"] = account_key
+    return make_op(at=at, src="codex-file-account", payload=payload)
+
+
 # --------------------------------------------------------------------------
 # segment naming + canonical order
 # --------------------------------------------------------------------------

package/bin/_lib_jsonl.py

@@ -641,6 +641,125 @@ def _codex_logical_limit_key(
     return _codex_canonical_json(payload)
 
 
+# --------------------------------------------------------------------------
+# #416 spec §4.3 (review F8): `window_minutes` snapping.
+#
+# The provider occasionally reports a weekly window as `10081` rather than
+# `10080`. `window_minutes` is a member of the logical limit key AND a column of
+# its own, and both feed `QuotaWindowIdentity`, so one minute of jitter mints a
+# second identity for one physical window — the second fragmentation axis behind
+# spec §1.4 (392 live weekly blocks across 126 distinct reset-minutes, plus a
+# stray `window_minutes = 10081`).
+#
+# Snapping is safe ONLY as a member-preserving replace. Rebuilding the key from
+# limit/root/slot/minutes would drop `modelPool`, and
+# `is_model_scoped_codex_quota` treats that member as an axis INDEPENDENT of the
+# Spark `limit_name` — so a rebuild would file a Spark window under account
+# weekly quota, which #373 forbids outright. Every other member (including one
+# a future version adds) therefore survives verbatim.
+#
+# ±1 minute only. The next genuine boundary is 300 or 10080, so a wider
+# tolerance buys nothing and a `10200` window is a different window, not jitter.
+# --------------------------------------------------------------------------
+
+CODEX_NATIVE_WINDOW_MINUTES: tuple[int, ...] = (300, 10080)
+CODEX_WINDOW_MINUTES_SNAP_TOLERANCE = 1
+
+
+def snap_codex_window_minutes(window_minutes: object) -> object:
+    """Snap a jittered Codex window length onto its native value.
+
+    Scalar half of the transform, used for the `window_minutes` COLUMN. Anything
+    that is not a plain positive int, or that is not within
+    ``CODEX_WINDOW_MINUTES_SNAP_TOLERANCE`` of a native length, is returned
+    unchanged — the caller must be able to apply this unconditionally.
+    """
+    if not isinstance(window_minutes, int) or isinstance(window_minutes, bool):
+        return window_minutes
+    for native in CODEX_NATIVE_WINDOW_MINUTES:
+        if abs(window_minutes - native) <= CODEX_WINDOW_MINUTES_SNAP_TOLERANCE:
+            return native
+    return window_minutes
+
+
+def codex_snap_equivalent_limit_keys(logical_limit_key: str) -> tuple[str, ...]:
+    """Every RAW logical limit key that ``snap_window_minutes`` maps onto the
+    same canonical key as ``logical_limit_key``.
+
+    The reset-anchor group (spec §4.2) must be the CANONICAL identity, but rows
+    are STORED under their raw key, so a group lookup has to enumerate the raw
+    spellings rather than snap in SQL. The set is bounded at three — the native
+    length plus/minus the tolerance — and contains the input itself, so a
+    non-snappable key resolves to a one-element tuple.
+    """
+    snapped = snap_window_minutes(logical_limit_key)
+    try:
+        payload = json.loads(snapped)
+    except (json.JSONDecodeError, TypeError, ValueError):
+        return (logical_limit_key,)
+    if not isinstance(payload, dict):
+        return (logical_limit_key,)
+    native = payload.get("windowMinutes")
+    if native not in CODEX_NATIVE_WINDOW_MINUTES:
+        return (logical_limit_key,)
+    tol = CODEX_WINDOW_MINUTES_SNAP_TOLERANCE
+    out: list[str] = []
+    for minutes in range(native - tol, native + tol + 1):
+        payload["windowMinutes"] = minutes
+        out.append(_codex_canonical_json(payload))
+    return tuple(out)
+
+
+def codex_snap_equivalent_window_minutes(window_minutes: object) -> tuple[object, ...]:
+    """The scalar sibling of ``codex_snap_equivalent_limit_keys``: every RAW
+    ``window_minutes`` value that ``snap_codex_window_minutes`` maps onto the
+    same native length as ``window_minutes``.
+
+    An identity carries the length in BOTH the logical limit key and a column of
+    its own, so a lookup that enumerates only the equivalent keys still misses a
+    stored row on the column predicate. Same bound (three values), same
+    self-inclusion for a non-snappable input.
+    """
+    native = snap_codex_window_minutes(window_minutes)
+    if native not in CODEX_NATIVE_WINDOW_MINUTES:
+        return (window_minutes,)
+    tol = CODEX_WINDOW_MINUTES_SNAP_TOLERANCE
+    return tuple(range(native - tol, native + tol + 1))
+
+
+def snap_window_minutes(logical_limit_key: str) -> str:
+    """Replace ONLY the ``windowMinutes`` member of a serialized logical limit
+    key, preserving every other member verbatim.
+
+    Re-serialized through ``_codex_canonical_json`` so the byte form is exactly
+    what a natively-minted key produces: the key is a natural-key member on both
+    the journal (``_codex_quota_natural_key``) and the cache
+    (``UNIQUE(source, source_path, line_offset, logical_limit_key)``), so a
+    near-miss serialization would mint a second window rather than merge one.
+
+    Fails OPEN on shape: a key this cannot parse, or one whose ``windowMinutes``
+    is not a plain int, is returned exactly as it arrived rather than rebuilt
+    from guessed members.
+    """
+    if not isinstance(logical_limit_key, str):
+        return logical_limit_key
+    try:
+        payload = json.loads(logical_limit_key)
+    except (json.JSONDecodeError, TypeError, ValueError):
+        return logical_limit_key
+    if not isinstance(payload, dict):
+        return logical_limit_key
+    minutes = payload.get("windowMinutes")
+    snapped = snap_codex_window_minutes(minutes)
+    if snapped == minutes and type(snapped) is type(minutes):
+        return logical_limit_key
+    payload["windowMinutes"] = snapped
+    try:
+        return _codex_canonical_json(payload)
+    except (TypeError, ValueError):  # pragma: no cover — non-serializable member
+        return logical_limit_key
+
+
 def _codex_quota_observations(
     obj: dict[str, Any], payload: dict[str, Any], path_str: str, line_offset: int,
     source_root_key: str | None, model: str | None,

package/bin/_lib_quota.py

@@ -38,6 +38,172 @@ def _integer_percent(value: float) -> int:
     return math.floor(value + 1e-9)
 
 
+# --------------------------------------------------------------------------
+# #416 spec §4.2 — tolerance-anchored reset canonicalization (decision D4).
+#
+# The Codex quota path never received the jitter canonicalization the Claude 5h
+# path has, so the RAW `resets_at` enters the window identity and one physical
+# window splits into many, each with its own peak and milestone ladder (spec
+# §1.4: one reset-minute observed split six ways).
+#
+# The tolerance is safe by construction: the next GENUINE reset of a 5h window
+# is five hours out and of a weekly window seven days out, so nothing within
+# 600s of an established anchor can be a different cycle.
+#
+# This kernel is pure and takes the established anchor set as an argument,
+# because resolution must happen at INGEST over the complete population (spec
+# §4.1 / review F7). A read-time anchor is deterministic only for a fixed input
+# population, and the dashboard reads at most 35 days / 1,000 rows with those
+# bounds applied in SQL — so omitting the earliest member of a jitter cluster
+# would silently move its anchor and make the dashboard and the CLI disagree
+# about window identity.
+# --------------------------------------------------------------------------
+
+CODEX_RESET_ANCHOR_TOLERANCE_SECONDS = 600
+
+
+def resolve_reset_anchor(
+    anchors: Iterable[dt.datetime], raw_reset: dt.datetime,
+    *, tolerance_seconds: int = CODEX_RESET_ANCHOR_TOLERANCE_SECONDS,
+) -> dt.datetime:
+    """Return the anchor ``raw_reset`` joins, or ``raw_reset`` itself when it
+    establishes a new one.
+
+    ``anchors`` are the anchors already established for this observation's
+    identity (the identity MINUS the reset and MINUS the account — see
+    ``_physical_window_key``, which excludes the account precisely so an
+    unidentified observation can be adopted by a same-window identified one).
+
+    First sight wins and an anchor NEVER moves: the returned value is always an
+    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.)
+    """
+    _require_aware(raw_reset, "raw_reset")
+    if (isinstance(anchors, ResetAnchorIndex)
+            and anchors.tolerance_seconds == tolerance_seconds):
+        # O(1) via the bucketed index; the linear body below stays the
+        # reference semantics for a caller holding a plain sequence, and
+        # `ResetAnchorIndex.resolve` is pinned against it by an equivalence
+        # test over a randomized population.
+        return anchors.resolve(raw_reset)
+    return _resolve_reset_anchor_linear(
+        anchors, raw_reset, tolerance_seconds=tolerance_seconds)
+
+
+def _resolve_reset_anchor_linear(
+    anchors: Iterable[dt.datetime], raw_reset: dt.datetime,
+    *, tolerance_seconds: int,
+) -> dt.datetime:
+    best: dt.datetime | None = None
+    best_delta: float | None = None
+    for anchor in anchors:
+        _require_aware(anchor, "anchor")
+        delta = abs((raw_reset - anchor).total_seconds())
+        if delta > tolerance_seconds:
+            continue
+        if best is None or delta < best_delta or (
+            delta == best_delta and anchor < best
+        ):
+            best, best_delta = anchor, delta
+    return raw_reset if best is None else best
+
+
+class ResetAnchorIndex:
+    """An established-anchor set with O(1) ``resolve``.
+
+    Semantically identical to ``resolve_reset_anchor`` over the same anchors —
+    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.
+
+    Only the LOOKUP changes. The linear scan did a full ``datetime`` subtraction
+    against every established anchor, and a 5h group accumulates ~1,750 anchors
+    a year — so the scan is quadratic in the population. That is not a
+    background cost: cache migration 032 runs the resolver over the WHOLE
+    ``quota_window_snapshots`` table synchronously on the first DB open after
+    upgrade, and ``cache-sync --rebuild`` runs it over the whole walk, so the
+    quadratic term lands on the operator's first post-upgrade command as a
+    multi-minute hang.
+
+    Anchors are bucketed by ``floor(epoch / tolerance)``. Anything within
+    ``tolerance`` of a probe lies in the probe's own bucket or one on either
+    side, so three bucket lookups are EXHAUSTIVE — this is an exact index, not
+    an approximation, and no correctness argument depends on the bucket width
+    beyond that identity.
+    """
+
+    __slots__ = ("_tolerance", "_buckets", "_order")
+
+    def __init__(
+        self, anchors: 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._order: list[dt.datetime] = []
+        for anchor in anchors:
+            self.add(anchor)
+
+    @property
+    def tolerance_seconds(self) -> int:
+        return self._tolerance
+
+    def _bucket(self, value: dt.datetime) -> int:
+        return int(value.timestamp() // self._tolerance)
+
+    def add(self, anchor: dt.datetime) -> bool:
+        """Establish ``anchor``. Returns False when it was already present."""
+        _require_aware(anchor, "anchor")
+        bucket = self._buckets.setdefault(self._bucket(anchor), [])
+        if anchor in bucket:
+            return False
+        bucket.append(anchor)
+        self._order.append(anchor)
+        return True
+
+    def resolve(self, raw_reset: dt.datetime) -> dt.datetime:
+        """The anchor ``raw_reset`` joins, or ``raw_reset`` when it establishes
+        a new one. Does NOT add it — the caller decides, exactly as with the
+        pure function."""
+        _require_aware(raw_reset, "raw_reset")
+        probe = self._bucket(raw_reset)
+        best: dt.datetime | None = None
+        best_delta: float | None = None
+        for offset in (-1, 0, 1):
+            for anchor in self._buckets.get(probe + offset, ()):
+                delta = abs((raw_reset - anchor).total_seconds())
+                if delta > self._tolerance:
+                    continue
+                if best is None or delta < best_delta or (
+                    delta == best_delta and anchor < best
+                ):
+                    best, best_delta = anchor, delta
+        return raw_reset if best is None else best
+
+    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):
+        """Established anchors in the order they were established."""
+        return iter(self._order)
+
+    def __len__(self) -> int:
+        return len(self._order)
+
+
 @dataclass(frozen=True)
 class QuotaWindowIdentity:
     """One root-qualified native quota window identity.
@@ -87,10 +253,25 @@ class QuotaObservation:
     plan_type: str | None = None
     individual_limit_json: str | None = None
     reached_type: str | None = None
+    # #416 spec §4.1/§4.2: the tolerance-anchored reset resolved at INGEST over
+    # the complete population and stored on the cache row. ``resets_at`` stays
+    # the RAW provider value, retained unchanged as evidence.
+    #
+    # Every reset-identity consumer reads THIS field, not ``resets_at``, and
+    # ``__post_init__`` fills it from ``resets_at`` when the caller has none —
+    # so a pre-migration row, an older binary's row, or any construction site
+    # that predates the column behaves exactly as it does today rather than
+    # failing. That default is what makes "route every consumer through the
+    # anchor" a safe blanket rule instead of a per-call-site judgement.
+    canonical_resets_at: dt.datetime | None = None
 
     def __post_init__(self) -> None:
         _require_aware(self.captured_at, "captured_at")
         _require_aware(self.resets_at, "resets_at")
+        if self.canonical_resets_at is None:
+            object.__setattr__(self, "canonical_resets_at", self.resets_at)
+        else:
+            _require_aware(self.canonical_resets_at, "canonical_resets_at")
         if not isinstance(self.used_percent, (int, float)) or isinstance(self.used_percent, bool):
             raise ValueError("used_percent must be a number")
         if not math.isfinite(self.used_percent) or not 0 <= self.used_percent <= 100:
@@ -221,10 +402,16 @@ def identity_sort_key(identity: QuotaWindowIdentity) -> tuple[str, str, str, str
 
 
 def physical_order_key(observation: QuotaObservation) -> tuple[dt.datetime, dt.datetime, str, int]:
-    """The frozen total order for physical rows within one identity."""
+    """The frozen total order for physical rows within one identity.
+
+    The reset component is the CANONICAL anchor (#416 §4.1), so two captures of
+    one physical window whose raw resets differ only by provider jitter tie here
+    and fall through to the deterministic physical position
+    (``source_path``, ``line_offset``) instead of being ordered by the jitter.
+    """
     return (
         observation.captured_at,
-        observation.resets_at,
+        observation.canonical_resets_at,
         observation.source_path,
         observation.line_offset,
     )
@@ -242,7 +429,10 @@ def logical_value_tuple(observation: QuotaObservation) -> tuple[object, ...]:
         identity.limit_id,
         identity.limit_name,
         observation.used_percent,
-        observation.resets_at,
+        # CANONICAL, not raw (#416 §4.1): the reset is part of the interpreted
+        # point's value, so raw jitter would make one unchanged reading look
+        # like a run of distinct interpreted points and defeat the dedup.
+        observation.canonical_resets_at,
         observation.plan_type,
         observation.individual_limit_json,
         observation.reached_type,
@@ -289,9 +479,13 @@ def _physical_window_key(observation: QuotaObservation) -> tuple[object, ...]:
     """The account-INDEPENDENT physical window key used by the continuity fold.
 
     Two observations share a physical window iff they agree on root, limit key,
-    slot, window minutes, and the exact (canonical UTC) reset boundary — the
-    account is deliberately EXCLUDED so unidentified observations can be adopted
-    by a same-window identified account (spec §2 window-account continuity).
+    slot, window minutes, and the reset boundary — the account is deliberately
+    EXCLUDED so unidentified observations can be adopted by a same-window
+    identified account (spec §2 window-account continuity).
+
+    The reset is the CANONICAL anchor (#416 §4.1). With the raw value, jitter
+    ALONE defeats continuity adoption: an unidentified observation a few seconds
+    off the identified one is a different physical window and is never adopted.
     """
     identity = observation.identity
     return (
@@ -300,7 +494,7 @@ def _physical_window_key(observation: QuotaObservation) -> tuple[object, ...]:
         identity.logical_limit_key,
         identity.observed_slot,
         identity.window_minutes,
-        observation.resets_at,
+        observation.canonical_resets_at,
     )
 
 
@@ -376,11 +570,18 @@ def select_baseline(
 
 
 def build_blocks(observations: Iterable[QuotaObservation]) -> tuple[QuotaBlock, ...]:
-    """Segment deduplicated interpreted history at each native reset boundary."""
+    """Segment deduplicated interpreted history at each native reset boundary.
+
+    Blocks are keyed on the CANONICAL anchor (#416 §4.1), so one physical window
+    is one block however many raw reset spellings its observations carry — and
+    ``QuotaBlock.resets_at``, which every renderer shows, is that same anchor.
+    """
     by_block: dict[tuple[QuotaWindowIdentity, dt.datetime], list[QuotaObservation]] = {}
     for history in build_history(observations):
         for observation in history.observations:
-            by_block.setdefault((history.identity, observation.resets_at), []).append(observation)
+            by_block.setdefault(
+                (history.identity, observation.canonical_resets_at), []
+            ).append(observation)
 
     blocks: list[QuotaBlock] = []
     for (identity, resets_at), points in sorted(
@@ -495,9 +696,13 @@ def forecast_quota(
     if baseline is None:
         return _null_forecast("future" if freshness.state == "future" else "unavailable")
 
+    # Same-cycle selection on the CANONICAL anchor (#416 §4.1). With the raw
+    # value, a jittered cycle's evidence splits and the forecast silently runs
+    # on a fraction of the samples it should have.
     points = tuple(
         observation for observation in history.observations
-        if observation.resets_at == baseline.resets_at and observation.captured_at <= as_of
+        if observation.canonical_resets_at == baseline.canonical_resets_at
+        and observation.captured_at <= as_of
     )
     points = tuple(sorted(points, key=physical_order_key))
     sample_count = 0
@@ -507,9 +712,13 @@ def forecast_quota(
         if elapsed_seconds > 0 and delta_percent > 0:
             sample_count += 1
 
-    remaining_seconds = max(0, int((baseline.resets_at - as_of).total_seconds()))
+    # The cycle geometry rides the same anchor, so the countdown, the elapsed
+    # fraction, and the reported reset all describe ONE window rather than
+    # whichever jittered spelling the baseline observation happened to carry.
+    anchor = baseline.canonical_resets_at
+    remaining_seconds = max(0, int((anchor - as_of).total_seconds()))
     native_window_seconds = baseline.identity.window_minutes * 60
-    cycle_start = baseline.resets_at - dt.timedelta(minutes=baseline.identity.window_minutes)
+    cycle_start = anchor - dt.timedelta(minutes=baseline.identity.window_minutes)
     cycle_elapsed_seconds = min(
         float(native_window_seconds),
         max(0.0, (as_of - cycle_start).total_seconds()),
@@ -544,7 +753,7 @@ def forecast_quota(
         current_percent=baseline.used_percent,
         rate_percent_per_hour=rate,
         projected_percent=projected,
-        resets_at=baseline.resets_at,
+        resets_at=anchor,
         remaining_seconds=remaining_seconds,
         sample_count=sample_count,
         sample_span_seconds=int(cycle_elapsed_seconds) if sample_count > 0 else 0,

package/bin/_lib_rederive.py

@@ -67,6 +67,12 @@ _EVT_CLASSIFICATIONS = {
         "historical project budgets are not journaled; stale latches retire"),
     "quota_alert_arming": KindClassification(
         "retained", "Codex quota lifecycle state is outside claude-usage"),
+    # #416 spec §7.2: terminal Codex quota alert evidence. `retained`, exactly
+    # like its `quota_alert_arming` sibling — it is provider state OUTSIDE the
+    # claude-usage family, replayed by its own fold applier rather than
+    # re-derived into the claude-usage scratch index.
+    "quota_threshold_event": KindClassification(
+        "retained", "Codex terminal quota alert evidence is outside claude-usage"),
 }
 
 _OP_CLASSIFICATIONS = {
@@ -81,6 +87,12 @@ _OP_CLASSIFICATIONS = {
         "legacy Claude ownership normalizes unstamped journal history"),
     "sync_week": KindClassification(
         "retained_input", "operator cost-sync request is re-executed in scratch"),
+    # #416: the durable Codex file/range attribution decision. `retained` (not
+    # `retained_input`) mirrors the `quota_alert_arming` precedent above — it is
+    # provider state OUTSIDE the claude-usage family, replayed by the Codex cache
+    # leg rather than into the claude-usage scratch index.
+    "codex_file_account": KindClassification(
+        "retained", "Codex file attribution decision is outside claude-usage"),
 }
 
 

package/bin/_lib_source_analytics.py

@@ -66,6 +66,19 @@ class QualifiedCodexEntry:
     # source-analytics renderers never expose either raw identity.
     session_id: str = ""
     source_path: str = ""
+    # #416 spec §5.2 (review F9): the ingest-stamped account, carried so the
+    # dashboard can partition ALREADY-LOADED rows by account instead of running
+    # a second query shape per account.
+    #
+    # CARRIED, never grouped. It is a trailing defaulted field and it is
+    # deliberately absent from `project_key`, from the `(root, project)` project
+    # grouping, from the `(source_root_key, source_path)` session grouping, and
+    # from every aggregator key — the merged parent stays byte-identical BY
+    # CONSTRUCTION rather than by careful re-derivation. Adding it to a grouping
+    # key would silently split every merged bucket a file that switches accounts
+    # contributes to. The default is the reserved `unattributed` sentinel, so
+    # every existing constructor (and the whole CLI path) is unchanged.
+    account_key: str = "unattributed"
 
 
 def emitted_project_label(entry: QualifiedCodexEntry) -> str: