cctally 1.98.0 → 1.99.0

package/bin/_lib_journal.py

@@ -1308,6 +1308,218 @@ def make_codex_file_account(
     return make_op(at=at, src="codex-file-account", payload=payload)
 
 
+#: Only account-level weekly Codex quota is attributable (#500 spec §5). A 5h
+#: window and a model-scoped pool are out of scope, and the builder refuses
+#: rather than recording an assertion the overlay would always suppress.
+ACCOUNT_WEEKLY_WINDOW_MINUTES = 10_080
+
+#: The sentinel is never an assertable subject and is never written into a
+#: payload (the two-shaped stamp rule, docs/accounts-gotchas.md).
+_ATTRIBUTION_SENTINEL = "unattributed"
+
+WINDOW_ATTRIBUTION_KIND = "codex_window_attribution"
+WINDOW_ATTRIBUTION_RETRACT_KIND = "codex_window_attribution_retract"
+WINDOW_ATTRIBUTION_SRC = "account-attribute"
+
+
+def _sorted_unique_strings(values, what: str) -> list:
+    """Sorted, de-duplicated, non-empty strings, or ``ValueError``.
+
+    A bare string is refused rather than iterated: ``"abc"`` would otherwise
+    silently become three one-character witnesses. Types are checked BEFORE the
+    sort, so a non-string member raises ``ValueError`` rather than the
+    ``TypeError`` a mixed-type ``sorted`` would raise.
+    """
+    if isinstance(values, (str, bytes)):
+        raise ValueError(f"{what} must be a sequence of strings, not a string")
+    try:
+        items = list(values)
+    except TypeError as exc:
+        raise ValueError(f"{what} must be a sequence of strings") from exc
+    for item in items:
+        if not isinstance(item, str) or not item:
+            raise ValueError(f"every {what} entry must be a non-empty string")
+    return sorted(set(items))
+
+
+def _normalize_attribution_instant(at: str) -> str:
+    """One ISO spelling for a #500 assertion's `at` (review finding F9).
+
+    `make_op` stores the caller's string verbatim, and the active read orders
+    assertions with `ORDER BY asserted_at_utc ASC` — a LEXICOGRAPHIC sort over
+    that stored text. Lexicographic order is chronological order only while
+    every value uses one spelling: `2026-08-14T12:00:00+00:00` sorts before
+    `2026-08-14T06:00:00Z` because `+` (0x2B) precedes `Z` (0x5A), so a single
+    offset-form assertion would silently take precedence over every later
+    Z-form one. Normalizing HERE, at the one chokepoint both builders pass
+    through, is what makes the cheap SQL ordering correct.
+
+    MICROSECOND precision with a `Z` suffix, and the six fractional digits are
+    written ALWAYS, even when they are zero (review round 2, finding R2-1).
+    Two separate rules meet here and both require the fixed width.
+
+    Truncating to seconds is a correctness defect, not a cosmetic one. The
+    normalized value is what `content_id` digests, so two assertions inside one
+    wall-clock second with otherwise-identical payloads collapse to the SAME
+    `op_id`. Spec §7.2's assert -> retract -> re-assert then loses its last
+    step: the re-assertion carries the id the tombstone already names, so
+    `INSERT OR IGNORE` drops it against the retracted row and the operator's
+    second assertion vanishes with no error. §7.2 requires a re-assertion to
+    carry an id no earlier tombstone names, and sub-second precision is what
+    supplies it.
+
+    Emitting the fraction only when non-zero would break the ordering rule
+    above: `.` (0x2E) precedes `Z` (0x5A), so `2026-08-14T00:00:05.500000Z`
+    would sort BEFORE `2026-08-14T00:00:05Z` — a fractional value ahead of the
+    whole second it follows. One fixed-width spelling is what keeps
+    lexicographic order equal to chronological order.
+
+    A naive value is refused rather than assumed to be UTC: the assertion is
+    durable, and guessing a zone for it is not recoverable.
+    """
+    if not isinstance(at, str) or not at:
+        raise ValueError("at must be a non-empty ISO instant")
+    try:
+        parsed = dt.datetime.fromisoformat(at.replace("Z", "+00:00"))
+    except ValueError as exc:
+        raise ValueError(f"at is not an ISO instant: {at!r}") from exc
+    if parsed.tzinfo is None:
+        raise ValueError(f"at must carry a timezone offset: {at!r}")
+    return parsed.astimezone(dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+
+
+def _window_attribution_payload(
+    kind: str,
+    *,
+    account_key: str,
+    source_root_key: str,
+    logical_limit_key: str,
+    observed_slot: str,
+    window_minutes: int,
+    raw_resets_at_utc,
+    canonical_resets_at_utc: str,
+) -> dict:
+    """Shared payload for the two #500 operator-attribution op kinds.
+
+    The binding is the four normalized axes plus the tolerance-connected
+    component WITNESSED by ``raw_resets_at_utc``. The canonical anchor is
+    carried for audit and preview only and is NEVER matched on: it is
+    population-dependent, because a later bridging observation can union two
+    components and retire the earlier anchor (``_lib_quota`` component union),
+    which is exactly why the canonical value is not journaled anywhere else.
+
+    The ``account_key`` here is the SUBJECT of the assertion — the account the
+    operator says the window belongs to — not the two-shaped stamp naming which
+    account wrote the record. Both kinds are registered in
+    ``_ACCOUNTS_MACHINERY_KINDS``, but NOT because the legacy normalizer would
+    otherwise mistake this field for a missing stamp (review finding F7) — it
+    would not, being gated on ``_REAL_ACCOUNT_EVT_OP_KINDS``, which these kinds
+    were never in. Registration is what puts the kinds into the re-derive
+    planner's ``op_kinds`` set, which makes their
+    ``_lib_rederive._OP_CLASSIFICATIONS`` entries mandatory.
+    """
+    if not isinstance(account_key, str) or not account_key:
+        raise ValueError("account_key must be a non-empty string")
+    if account_key == _ATTRIBUTION_SENTINEL:
+        raise ValueError("the unattributed sentinel is not an assertable subject")
+    for name, value in (("source_root_key", source_root_key),
+                        ("logical_limit_key", logical_limit_key),
+                        ("observed_slot", observed_slot),
+                        ("canonical_resets_at_utc", canonical_resets_at_utc)):
+        if not isinstance(value, str) or not value:
+            raise ValueError(f"{name} must be a non-empty string")
+    if (not isinstance(window_minutes, int)
+            or isinstance(window_minutes, bool)
+            or window_minutes != ACCOUNT_WEEKLY_WINDOW_MINUTES):
+        raise ValueError(
+            f"window_minutes must be {ACCOUNT_WEEKLY_WINDOW_MINUTES} "
+            "(account weekly quota)")
+    witnesses = _sorted_unique_strings(raw_resets_at_utc, "raw reset witness")
+    if not witnesses:
+        raise ValueError("raw_resets_at_utc must carry at least one witness")
+    return {
+        "kind": kind,
+        "source": "codex",
+        "account_key": account_key,
+        "source_root_key": source_root_key,
+        "logical_limit_key": logical_limit_key,
+        "observed_slot": observed_slot,
+        "window_minutes": window_minutes,
+        "raw_resets_at_utc": witnesses,
+        "canonical_resets_at_utc": canonical_resets_at_utc,
+    }
+
+
+def make_codex_window_attribution(
+    at: str,
+    *,
+    account_key: str,
+    source_root_key: str,
+    logical_limit_key: str,
+    observed_slot: str,
+    window_minutes: int,
+    raw_resets_at_utc,
+    canonical_resets_at_utc: str,
+) -> dict:
+    """Build a ``codex_window_attribution`` op — the operator's durable
+    assertion that one physical Codex quota window group belongs to one account
+    (#500 spec §5).
+
+    Ordinary ``content_id``, deliberately NOT a stable singleton id like the
+    accounts cutover's: a fixed id would make assert -> retract -> reassert
+    impossible, because the second assertion would collide with the first.
+    """
+    payload = _window_attribution_payload(
+        WINDOW_ATTRIBUTION_KIND,
+        account_key=account_key,
+        source_root_key=source_root_key,
+        logical_limit_key=logical_limit_key,
+        observed_slot=observed_slot,
+        window_minutes=window_minutes,
+        raw_resets_at_utc=raw_resets_at_utc,
+        canonical_resets_at_utc=canonical_resets_at_utc,
+    )
+    return make_op(at=_normalize_attribution_instant(at),
+                   src=WINDOW_ATTRIBUTION_SRC, payload=payload)
+
+
+def make_codex_window_attribution_retract(
+    at: str,
+    *,
+    account_key: str,
+    source_root_key: str,
+    logical_limit_key: str,
+    observed_slot: str,
+    window_minutes: int,
+    raw_resets_at_utc,
+    canonical_resets_at_utc: str,
+    retracted_assertion_ids,
+) -> dict:
+    """Build a ``codex_window_attribution_retract`` op (#500 spec §5, §7.2).
+
+    Targets specific assertion op IDs rather than the group, so an older
+    tombstone can never suppress a later reassertion: the reassertion carries a
+    new content id that no earlier tombstone names.
+    """
+    payload = _window_attribution_payload(
+        WINDOW_ATTRIBUTION_RETRACT_KIND,
+        account_key=account_key,
+        source_root_key=source_root_key,
+        logical_limit_key=logical_limit_key,
+        observed_slot=observed_slot,
+        window_minutes=window_minutes,
+        raw_resets_at_utc=raw_resets_at_utc,
+        canonical_resets_at_utc=canonical_resets_at_utc,
+    )
+    targets = _sorted_unique_strings(
+        retracted_assertion_ids, "retracted assertion id")
+    if not targets:
+        raise ValueError("retracted_assertion_ids must name at least one assertion")
+    payload["retracted_assertion_ids"] = targets
+    return make_op(at=_normalize_attribution_instant(at),
+                   src=WINDOW_ATTRIBUTION_SRC, payload=payload)
+
+
 # --------------------------------------------------------------------------
 # segment naming + canonical order
 # --------------------------------------------------------------------------

package/bin/_lib_jsonl.py

@@ -81,6 +81,12 @@ class CodexEntry:
     reasoning_output_tokens: int
     total_tokens: int
     source_path: str
+    # Cache-backed readers already compute the canonical price while loading.
+    # Direct JSONL/CLI readers leave this unset and retain historical pricing.
+    cost_usd: float | None = None
+    cache_entry_id: int = field(default=0, compare=False, repr=False)
+    source_root_key: str = field(default="", compare=False, repr=False)
+    conversation_key: str = field(default="", compare=False, repr=False)
 
 
 def _entry_token_total(entry: "UsageEntry") -> int:

package/bin/_lib_rederive.py

@@ -105,6 +105,14 @@ _OP_CLASSIFICATIONS = {
     # leg rather than into the claude-usage scratch index.
     "codex_file_account": KindClassification(
         "retained", "Codex file attribution decision is outside claude-usage"),
+    # #500: operator attribution of recorded Codex quota windows. `retained`,
+    # exactly like the `codex_file_account` precedent above — provider state
+    # OUTSIDE the claude-usage family, replayed by the Codex cache leg rather
+    # than into the claude-usage scratch index.
+    "codex_window_attribution": KindClassification(
+        "retained", "operator Codex window attribution is outside claude-usage"),
+    "codex_window_attribution_retract": KindClassification(
+        "retained", "operator Codex window retraction is outside claude-usage"),
 }
 
 

package/bin/_lib_snapshot_cache.py

@@ -91,6 +91,11 @@ class SnapshotSignature(NamedTuple):
     # sequence supplies that missing identity leg; the stats digest arrives
     # from the independently-committed quota/budget projection database.
     codex_physical_mutation_seq: int = 0
+    # #582: path-ledger accounting changes must leave the snapshot idle path,
+    # even when MAX(id) and the broader physical counter stay flat. This leg
+    # is internal dispatch identity only; published data-version bytes retain
+    # their existing contract.
+    codex_accounting_mutation_seq: int = 0
     codex_stats_digest: str = ""
     # #341 finding 9: a digest of the account registry + the providers' on-disk
     # identity-file/active-account state. Empty for every <=1-account install (no
@@ -251,6 +256,9 @@ def compute_signature(
         generation=int(generation),
         entry_mutation_seq=_entry_mutation_seq(cache_conn),
         codex_physical_mutation_seq=_codex_physical_mutation_seq(cache_conn),
+        codex_accounting_mutation_seq=(
+            _codex_accounting_mutation_seq(cache_conn) or 0
+        ),
         codex_stats_digest=str(codex_stats_digest),
         accounts_digest=str(accounts_digest),
         codex_ingest_backlog_sig=_codex_ingest_backlog_sig(cache_conn),
@@ -960,6 +968,228 @@ def reset_session_cache_state() -> None:
     _SESSION_LAST_SEEN.clear()
 
 
+# === #582 — persistent Codex accounting rows by dirty physical path =========
+
+
+@dataclass(frozen=True)
+class CodexAccountingCacheResult:
+    """One cold or incrementally refreshed accounting population."""
+
+    entries: tuple[object, ...]
+    dirty_paths: tuple[tuple[str, str], ...]
+    dirty_accounts: tuple[str, ...]
+    cold: bool
+    changed_old: tuple[object, ...] = ()
+    changed_new: tuple[object, ...] = ()
+
+
+_CODEX_ACCOUNTING_CACHE_STATE: dict[str, object] = {}
+_CODEX_ACCOUNTING_MAX_DIRTY_PATHS = 300
+
+
+def reset_codex_accounting_cache_state() -> None:
+    """Drop #582's value-only Codex accounting cache and ledger cursor."""
+    _assert_owner()
+    _CODEX_ACCOUNTING_CACHE_STATE.clear()
+
+
+def checkpoint_codex_accounting_cache_state() -> dict[str, object]:
+    """Copy the value-only state so a failed source build can roll back."""
+    _assert_owner()
+    return dict(_CODEX_ACCOUNTING_CACHE_STATE)
+
+
+def restore_codex_accounting_cache_state(state: dict[str, object]) -> None:
+    """Restore a checkpoint after downstream source construction fails."""
+    _assert_owner()
+    _CODEX_ACCOUNTING_CACHE_STATE.clear()
+    _CODEX_ACCOUNTING_CACHE_STATE.update(state)
+
+
+def _codex_accounting_mutation_seq(conn: sqlite3.Connection) -> int | None:
+    """Return the dedicated ledger sequence, or ``None`` when unsupported."""
+    try:
+        row = conn.execute(
+            "SELECT value FROM cache_meta "
+            "WHERE key='codex_accounting_mutation_seq'"
+        ).fetchone()
+        table = conn.execute(
+            "SELECT 1 FROM sqlite_master WHERE type='table' "
+            "AND name='codex_accounting_change_log'"
+        ).fetchone()
+    except sqlite3.Error:
+        return None
+    if table is None or row is None or row[0] is None:
+        return None
+    try:
+        return int(row[0])
+    except (TypeError, ValueError):
+        return None
+
+
+def codex_accounting_cache_pending(conn: sqlite3.Connection) -> bool:
+    """Whether the process cache has not consumed the durable ledger head."""
+    _assert_owner()
+    current = _codex_accounting_mutation_seq(conn)
+    if current is None or not _CODEX_ACCOUNTING_CACHE_STATE:
+        return True
+    return current != int(_CODEX_ACCOUNTING_CACHE_STATE.get("seq", -1))
+
+
+def build_cached_codex_accounting(
+    *,
+    cache_conn: sqlite3.Connection,
+    range_start: dt.datetime,
+    range_end: dt.datetime,
+    extra_signature: object,
+    load_all: "Callable[[], tuple[object, ...]]",
+    load_paths: "Callable[[tuple[tuple[str, str], ...]], tuple[object, ...]]",
+    path_of: "Callable[[object], tuple[str, str]]",
+    account_of: "Callable[[object], str]",
+    order_key: "Callable[[object], object]",
+    identity_of: "Callable[[object], object] | None" = None,
+    finalize_entries: "Callable[[tuple[object, ...], tuple[object, ...] | None], tuple[object, ...]] | None" = None,
+) -> CodexAccountingCacheResult:
+    """Cold-load once, then replace only ledger-dirty Codex file populations.
+
+    The cache retains plain immutable values and one integer cursor.  A missing
+    ledger, cursor gap, full marker, semantic-key change, range-start change,
+    or clock regression goes cold.  When the upper bound advances, paths with
+    already-stored future rows crossing into the range are dirtied even though
+    no mutation sequence moved.
+    """
+    _assert_owner()
+    if (
+        range_start.tzinfo is None or range_start.utcoffset() is None
+        or range_end.tzinfo is None or range_end.utcoffset() is None
+        or range_end <= range_start
+    ):
+        raise ValueError("Codex accounting cache range must be aware and ordered")
+    current_seq = _codex_accounting_mutation_seq(cache_conn)
+    state = _CODEX_ACCOUNTING_CACHE_STATE
+    prior_cached_entries = tuple(state.get("entries", ())) if state else ()
+    cold = (
+        current_seq is None
+        or not state
+        or state.get("extra") != extra_signature
+        or state.get("start") != range_start
+        or range_end < state.get("end", range_end)
+        or current_seq < int(state.get("seq", 0))
+    )
+    dirty: set[tuple[str, str]] = set()
+    if not cold:
+        last_seq = int(state["seq"])
+        if current_seq > last_seq:
+            try:
+                changes = tuple(cache_conn.execute(
+                    "SELECT mutation_seq, change_kind, source_root_key, source_path "
+                    "FROM codex_accounting_change_log "
+                    "WHERE mutation_seq > ? ORDER BY mutation_seq, seq",
+                    (last_seq,),
+                ))
+            except sqlite3.Error:
+                cold = True
+            else:
+                if (
+                    not changes
+                    or int(changes[0][0]) > last_seq + 1
+                    or int(changes[-1][0]) != current_seq
+                    or any(row[1] == "full" for row in changes)
+                ):
+                    cold = True
+                else:
+                    dirty.update(
+                        (str(row[2] or ""), str(row[3]))
+                        for row in changes
+                        if row[1] == "path" and row[3]
+                    )
+        prior_end = state.get("end")
+        if not cold and isinstance(prior_end, dt.datetime) and range_end > prior_end:
+            try:
+                dirty.update(
+                    (str(root or ""), str(path))
+                    for root, path in cache_conn.execute(
+                        "SELECT DISTINCT source_root_key, source_path "
+                        "FROM codex_session_entries "
+                        "WHERE timestamp_utc >= ? AND timestamp_utc < ?",
+                        (prior_end.astimezone(dt.timezone.utc).isoformat(),
+                         range_end.astimezone(dt.timezone.utc).isoformat()),
+                    )
+                )
+            except sqlite3.Error:
+                cold = True
+        # The qualified path loader emits two SQL parameters and one OR arm per
+        # identity. Beyond this bound a cold indexed range read is both safer
+        # and cheaper than approaching SQLite's variable/expression limits.
+        if not cold and len(dirty) > _CODEX_ACCOUNTING_MAX_DIRTY_PATHS:
+            cold = True
+
+    if cold:
+        entries = tuple(sorted(tuple(load_all()), key=order_key))
+        if finalize_entries is not None:
+            entries = tuple(finalize_entries(entries, None))
+        accounts = tuple(sorted({
+            str(account_of(entry))
+            for entry in (*prior_cached_entries, *entries)
+        }))
+        _CODEX_ACCOUNTING_CACHE_STATE.clear()
+        _CODEX_ACCOUNTING_CACHE_STATE.update({
+            "entries": entries,
+            "seq": 0 if current_seq is None else current_seq,
+            "start": range_start,
+            "end": range_end,
+            "extra": extra_signature,
+        })
+        return CodexAccountingCacheResult(
+            entries, (), accounts, True, prior_cached_entries, entries,
+        )
+
+    prior_entries = tuple(state["entries"])
+    if not dirty:
+        state["seq"] = current_seq
+        state["end"] = range_end
+        return CodexAccountingCacheResult(prior_entries, (), (), False)
+
+    dirty_paths = tuple(sorted(dirty))
+    prior_dirty = tuple(
+        entry for entry in prior_entries if path_of(entry) in dirty
+    )
+    replacements = tuple(load_paths(dirty_paths))
+    entries = tuple(sorted(
+        (
+            *(entry for entry in prior_entries if path_of(entry) not in dirty),
+            *replacements,
+        ),
+        key=order_key,
+    ))
+    if finalize_entries is not None:
+        entries = tuple(finalize_entries(entries, prior_entries))
+    entry_identity = identity_of or order_key
+    prior_by_identity = {entry_identity(entry): entry for entry in prior_dirty}
+    replacement_by_identity = {
+        entry_identity(entry): entry for entry in replacements
+    }
+    changed_old = tuple(
+        entry for identity, entry in prior_by_identity.items()
+        if identity not in replacement_by_identity
+        or replacement_by_identity[identity] != entry
+    )
+    changed_new = tuple(
+        entry for identity, entry in replacement_by_identity.items()
+        if identity not in prior_by_identity
+        or prior_by_identity[identity] != entry
+    )
+    dirty_accounts = tuple(sorted(
+        {str(account_of(entry)) for entry in (*changed_old, *changed_new)}
+    ))
+    state["entries"] = entries
+    state["seq"] = current_seq
+    state["end"] = range_end
+    return CodexAccountingCacheResult(
+        entries, dirty_paths, dirty_accounts, False, changed_old, changed_new,
+    )
+
+
 def build_cached_sessions(
     *,
     cache_conn: sqlite3.Connection,
@@ -1370,14 +1600,13 @@ def session_files_sig(cache_conn) -> "tuple[int, int]":
     moves. Returns ``(0, 0)`` on a missing table (fresh DB) so callers never
     raise.
 
-    #271 §9d rider (from the #269 final review): this ``(COUNT(*), MAX(rowid))``
-    leg does NOT by itself catch the in-place ``ON CONFLICT(path) DO UPDATE SET
+    #271 §9d rider (tightened by #567): this ``(COUNT(*), MAX(rowid))`` leg
+    does NOT by itself catch the in-place ``ON CONFLICT(path) DO UPDATE SET
     project_path = COALESCE(...)`` attribution backfill — that UPDATE preserves
-    the rowid and the row count, so both legs are unmoved. It is covered
-    belt-and-suspenders, though: the backfill lands in the SAME ``sync_cache``
-    ingest-loop iteration as the file's new ``session_entries`` rows, which bump
-    ``max_entry_id`` — caught by the watermark eviction path. So a pure
-    attribution move never both slips this signal and leaves the cache stale.
+    both values. `_ensure_session_files_row` therefore stamps the joined
+    `session_entries` rows with a fresh mutation sequence when it fills either
+    identity column. The envelope's mutation-sequence reconcile catches that
+    pure metadata move even when no new entry is ingested.
     """
     try:
         row = cache_conn.execute(

package/bin/_lib_source_analytics.py

@@ -5,7 +5,7 @@ import datetime as dt
 import hashlib
 import math
 from collections import defaultdict
-from dataclasses import dataclass, replace
+from dataclasses import dataclass, field, replace
 from typing import Generic, Iterable, Literal, TypeVar
 
 
@@ -79,6 +79,11 @@ class QualifiedCodexEntry:
     # contributes to. The default is the reserved `unattributed` sentinel, so
     # every existing constructor (and the whole CLI path) is unchanged.
     account_key: str = "unattributed"
+    # Internal stable ordering identity from cache.db.  It is deliberately
+    # excluded from equality and representation: provider outputs do not carry
+    # it, while #582's dirty-path replacement needs the original SQL tie-break
+    # when rows share timestamp/root/conversation.
+    cache_entry_id: int = field(default=0, compare=False, repr=False)
 
 
 def emitted_project_label(entry: QualifiedCodexEntry) -> str:
@@ -205,7 +210,20 @@ class TokenTotals:
 
 
 def _totals(entries: Iterable[QualifiedCodexEntry]) -> TokenTotals:
-    values = assign_collision_safe_project_labels(entries)
+    # #566 §5.1 item 7. `TokenTotals` carries no label, and nothing this
+    # function returns can observe one, so the collision-safe allocation this
+    # line used to run was dead work: it re-created every entry through
+    # `dataclasses.replace` purely to sum six numeric fields off the copies.
+    # On the maintainer's store the 148 calls from here drove 775,568
+    # `dataclasses.replace` calls and about 1.9s of every build.
+    #
+    # The allocation that MATTERS still runs, once, in
+    # `build_codex_project_result`, over the complete population, before any
+    # subset is taken -- which is the only place it can be correct. Guarding
+    # this call on "the subset holds more than one project identity" would
+    # have kept nearly all of the cost, because the expensive callers are the
+    # per-block totals over a population spanning every project.
+    values = tuple(entries)
     return TokenTotals(
         input_tokens=sum(entry.input_tokens for entry in values),
         cached_input_tokens=sum(entry.cached_input_tokens for entry in values),

package/bin/cctally

@@ -399,6 +399,7 @@ _lib_budget = _load_sibling("_lib_budget")
 BudgetInputs = _lib_budget.BudgetInputs
 BudgetStatus = _lib_budget.BudgetStatus
 compute_budget_status = _lib_budget.compute_budget_status
+budget_status_payload = _lib_budget.budget_status_payload
 project_linear = _lib_budget.project_linear
 calendar_month_window = _lib_budget.calendar_month_window
 calendar_week_window = _lib_budget.calendar_week_window
@@ -1378,6 +1379,11 @@ _empty_dashboard_snapshot = _cctally_dashboard._empty_dashboard_snapshot
 # which is also the seam its fold-failure tests monkeypatch.
 resolve_shared_range = _cctally_dashboard.resolve_shared_range
 iter_shared_range_entries = _cctally_dashboard.iter_shared_range_entries
+# #556 S5 §3.7: the Claude budget cost-event carrier rebuilds the same
+# `UsageEntry` these rows already feed, so the 1-hour cache-write split (#195)
+# is priced through the one `claude_usage_dict` chokepoint rather than a second
+# hand-rolled row unpack.
+_shared_range_row_to_usage_entry = _cctally_dashboard._shared_range_row_to_usage_entry
 fold_projects_over_range = _cctally_dashboard.fold_projects_over_range
 fold_daily_over_range = _cctally_dashboard.fold_daily_over_range
 materialise_daily_calendar = _cctally_dashboard.materialise_daily_calendar
@@ -1385,6 +1391,12 @@ build_daily_aggregate_rows = _cctally_dashboard.build_daily_aggregate_rows
 daily_panel_row_to_wire = _cctally_dashboard.daily_panel_row_to_wire
 build_project_aggregate_rows = _cctally_dashboard.build_project_aggregate_rows
 legacy_project_labels = _cctally_dashboard.legacy_project_labels
+build_cached_claude_range_aggregates = (
+    _cctally_dashboard.build_cached_claude_range_aggregates
+)
+reset_claude_range_aggregate_memo = (
+    _cctally_dashboard.reset_claude_range_aggregate_memo
+)
 # _iso_z is NOT bound here anymore — the former dashboard-then-forecast
 # double-bind collapses to a single canonical bind below (#279 S6 W4).
 # Projects panel + modal (spec 2026-05-19-projects-panel-design.md).