codexLB-up 1.25.0b10__py3-none-any.whl

app/modules/usage/depletion_service.py

@@ -0,0 +1,277 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import TypeAlias
+
+from app.core.usage.depletion import (
+    EWMAState,
+    classify_risk,
+    compute_burn_rate,
+    compute_depletion_risk,
+    compute_safe_usage_percent,
+    ewma_update,
+)
+from app.core.utils.time import naive_utc_to_epoch, utcnow
+
+# Per-account cache key: (account_id, limit_name, window).
+_StateKey: TypeAlias = tuple[str, str, str]
+_RowEdgeSignature = tuple[int | None, datetime, float, float | None, int | None]
+
+
+@dataclass(frozen=True)
+class _HistorySignature:
+    row_count: int
+    first: _RowEdgeSignature
+    latest: _RowEdgeSignature
+    content_digest: int | None
+
+
+class _SignedHistory(list):
+    def __init__(self, rows: Iterable, signature: _HistorySignature) -> None:
+        super().__init__(rows)
+        self.depletion_history_signature = signature
+
+
+# In-memory EWMA state: keyed by (account_id, limit_name, window)
+# Persists across requests; resets on process restart.
+_ewma_states: dict[_StateKey, EWMAState] = {}
+# Parallel signature map used to memoize EWMA rebuilds across dashboard polls
+# (issue #537). When the in-window history is unchanged between requests we
+# reuse the cached EWMAState instead of replaying the full history.
+_history_signatures: dict[_StateKey, _HistorySignature] = {}
+
+
+@dataclass
+class DepletionMetrics:
+    risk: float
+    risk_level: str  # "safe" | "warning" | "danger" | "critical"
+    rate_per_second: float
+    burn_rate: float
+    safe_usage_percent: float  # budget line position
+    projected_exhaustion_at: datetime | None
+    seconds_until_exhaustion: float | None
+
+
+@dataclass
+class AggregateDepletionMetrics:
+    risk: float
+    risk_level: str
+    burn_rate: float
+    safe_usage_percent: float
+    projected_exhaustion_at: datetime | None
+    seconds_until_exhaustion: float | None
+
+
+def compute_depletion_for_account(
+    account_id: str,
+    limit_name: str,
+    window: str,
+    history: list,  # list of objects with: used_percent, recorded_at, reset_at, window_minutes
+    now: datetime | None = None,
+) -> DepletionMetrics | None:
+    """
+    Compute depletion metrics for a single account using EWMA.
+
+    - history: list of usage entries ordered by recorded_at ASC
+    - Returns None if insufficient data (<2 data points) or rate is unknown
+    - Uses module-level _ewma_states for in-memory state
+    """
+    if not history:
+        return None
+
+    now = now or utcnow()
+    key: _StateKey = (account_id, limit_name, window)
+
+    if len(history) < 2:
+        # Only one in-window sample — seed the EWMA but don't compute
+        # depletion.  Reset any cached state so we never derive a rate
+        # from an out-of-window sample plus this one.
+        entry = history[0]
+        _ewma_states[key] = ewma_update(
+            None, entry.used_percent, naive_utc_to_epoch(entry.recorded_at), reset_at=entry.reset_at
+        )
+        _history_signatures[key] = _history_signature_from_edges(history)
+        return None
+
+    signature = _history_signature(history)
+    cached_state = _ewma_states.get(key)
+    cached_signature = _history_signatures.get(key)
+
+    if cached_state is not None and cached_signature == signature:
+        # Same in-window history as the last call — reuse the cached EWMA
+        # state instead of replaying every row.  Time-dependent fields below
+        # (risk, safe_usage_percent, projected_exhaustion_at) are still
+        # recomputed from `now`, so dashboard polls remain live.
+        state: EWMAState | None = cached_state
+    else:
+        state = _rebuild_ewma_state(history)
+        if state is not None:
+            _ewma_states[key] = state
+            _history_signatures[key] = signature
+
+    if state is None or state.rate is None:
+        return None
+
+    latest = history[-1]
+    used_percent = latest.used_percent
+
+    seconds_until_reset = 0.0
+    if latest.reset_at is not None:
+        seconds_until_reset = max(0.0, latest.reset_at - naive_utc_to_epoch(now))
+        if seconds_until_reset == 0.0:
+            # Window has already reset — the stale used_percent is
+            # meaningless.  Clear EWMA state so next refresh starts fresh.
+            _ewma_states.pop(key, None)
+            return None
+    elif latest.window_minutes is not None:
+        # Without reset_at we cannot know when the window started.  Use
+        # the full window duration as a conservative upper bound rather
+        # than guessing from the first observed sample (which may appear
+        # mid-window and dramatically underestimate remaining time).
+        seconds_until_reset = float(latest.window_minutes * 60)
+
+    total_window_seconds = (latest.window_minutes * 60) if latest.window_minutes else 0.0
+    seconds_elapsed = max(0.0, total_window_seconds - seconds_until_reset)
+
+    risk = compute_depletion_risk(used_percent, state.rate, seconds_until_reset)
+    risk_level = classify_risk(risk)
+    burn_rate = compute_burn_rate(state.rate, 100.0 - used_percent, seconds_until_reset)
+    safe_pct = compute_safe_usage_percent(seconds_elapsed, total_window_seconds)
+
+    projected_exhaustion_at = None
+    seconds_until_exhaustion = None
+    if state.rate > 0 and seconds_until_reset > 0:
+        remaining = 100.0 - used_percent
+        secs = remaining / state.rate
+        if secs <= seconds_until_reset:
+            seconds_until_exhaustion = secs
+            projected_exhaustion_at = now + timedelta(seconds=secs)
+        # else: exhaustion falls after the window resets — leave as None
+
+    return DepletionMetrics(
+        risk=risk,
+        risk_level=risk_level,
+        rate_per_second=state.rate,
+        burn_rate=burn_rate,
+        safe_usage_percent=safe_pct,
+        projected_exhaustion_at=projected_exhaustion_at,
+        seconds_until_exhaustion=seconds_until_exhaustion,
+    )
+
+
+def compute_aggregate_depletion(
+    per_account_metrics: Sequence[DepletionMetrics | None],
+) -> AggregateDepletionMetrics | None:
+    """
+    Aggregate depletion metrics across accounts using max(risk).
+    Returns None if no valid metrics.
+    """
+    valid = [m for m in per_account_metrics if m is not None]
+    if not valid:
+        return None
+
+    # Use all fields from the worst-case account so that risk, safe-line,
+    # burn rate, and exhaustion ETA are internally consistent.
+    worst = max(valid, key=lambda m: m.risk)
+
+    return AggregateDepletionMetrics(
+        risk=worst.risk,
+        risk_level=worst.risk_level,
+        burn_rate=worst.burn_rate,
+        safe_usage_percent=worst.safe_usage_percent,
+        projected_exhaustion_at=worst.projected_exhaustion_at,
+        seconds_until_exhaustion=worst.seconds_until_exhaustion,
+    )
+
+
+def reset_ewma_state() -> None:
+    """Clear all in-memory EWMA state. Used for testing."""
+    _ewma_states.clear()
+    _history_signatures.clear()
+
+
+def prune_depletion_cache(active_keys: Iterable[tuple[str, str, str]]) -> None:
+    """Drop EWMA/signature cache entries outside the current account/window set."""
+    keep = set(active_keys)
+    for key in set(_ewma_states) | set(_history_signatures):
+        if key not in keep:
+            _ewma_states.pop(key, None)
+            _history_signatures.pop(key, None)
+
+
+def _rebuild_ewma_state(history: list) -> EWMAState | None:
+    state: EWMAState | None = None
+    for entry in history:
+        ts = naive_utc_to_epoch(entry.recorded_at)
+        state = ewma_update(state, entry.used_percent, ts, reset_at=entry.reset_at)
+    return state
+
+
+def attach_depletion_history_signature(history: Iterable) -> list:
+    """Return a list carrying a compact content signature for cache checks.
+
+    Dashboard code already iterates fetched rows while grouping/filtering them;
+    attaching the digest there keeps cache-hit checks O(1) and avoids retaining
+    a tuple per history row in the module-level cache.
+    """
+    rows = list(history)
+    return _signed_history_from_rows(rows)
+
+
+def filter_depletion_history_since(history: Iterable, cutoff: datetime) -> list:
+    """Filter rows by cutoff and attach the cache signature."""
+    rows = [entry for entry in history if entry.recorded_at >= cutoff]
+    if not rows:
+        return []
+    return _SignedHistory(rows, _history_signature_from_rows(rows))
+
+
+def _history_signature(history: list) -> _HistorySignature:
+    attached = getattr(history, "depletion_history_signature", None)
+    if isinstance(attached, _HistorySignature):
+        return attached
+    return _history_signature_from_edges(history)
+
+
+def _history_signature_from_rows(history: list) -> _HistorySignature:
+    if not history:
+        raise ValueError("history must not be empty")
+    # One fixed-width hash over every row's value-bearing fields: cheap
+    # enough to run per dashboard poll on dense histories, and still
+    # detects in-place corrections that leave the edges and count intact.
+    # The signature cache is process-local, so a process-local ``hash`` is
+    # sufficient; only the int is retained, never the per-row tuples.
+    edges = tuple(map(_row_edge_signature, history))
+    return _HistorySignature(
+        row_count=len(edges),
+        first=edges[0],
+        latest=edges[-1],
+        content_digest=hash(edges),
+    )
+
+
+def _signed_history_from_rows(history: list) -> list:
+    return _SignedHistory(history, _history_signature_from_rows(history))
+
+
+def _history_signature_from_edges(history: Sequence) -> _HistorySignature:
+    if not history:
+        raise ValueError("history must not be empty")
+    return _HistorySignature(
+        row_count=len(history),
+        first=_row_edge_signature(history[0]),
+        latest=_row_edge_signature(history[-1]),
+        content_digest=None,
+    )
+
+
+def _row_edge_signature(entry) -> _RowEdgeSignature:
+    return (
+        getattr(entry, "id", None),
+        entry.recorded_at,
+        entry.used_percent,
+        entry.reset_at,
+        entry.window_minutes,
+    )

app/modules/usage/live_ingest.py

@@ -0,0 +1,356 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+import weakref
+from dataclasses import dataclass
+
+from app.core import usage as usage_core
+from app.core.usage.live_hub import register_live_usage_publisher
+from app.core.usage.live_snapshots import LiveRateLimitSnapshot, LiveUsageWindow
+from app.db.session import get_background_session
+from app.modules.proxy.account_cache import get_account_selection_cache
+from app.modules.proxy.rate_limit_cache import get_rate_limit_headers_cache
+from app.modules.usage.repository import UsageRepository, UsageWindowWrite
+
+logger = logging.getLogger(__name__)
+
+# Write-coalescing tuning (fixed; issue #1340 / PRINCIPLES.md P2). The
+# ingestor keeps both as constructor fields so tests can exercise queue
+# overflow and coalescing with small values.
+_QUEUE_SIZE = 512
+_WRITE_MIN_INTERVAL_SECONDS = 5.0
+_CACHE_INVALIDATION_MIN_INTERVAL_SECONDS = 5.0
+
+# Ownership accounting for every task any ingestor instance creates (consumer
+# and trailing cache invalidation), so a task an owner lost track of (a stop
+# cancelled mid-await) can never end in a silently dropped exception:
+#
+# - `_owned_tasks` holds weak references (they never extend task lifetime) so
+#   the test suite's leak fence can cancel pending tasks and settle completed
+#   ones that some reference chain kept alive across a test boundary.
+# - `_record_owned_task_result` runs as each task's done callback: it
+#   retrieves the exception (so the loop's unobserved-task warning can never
+#   fire at garbage-collection time), logs it, and records it in the bounded
+#   `_owned_task_failures` strong handoff for the fence to drain (#1755).
+#
+# `_settled_owned_tasks` (also weak) marks tasks whose result was already
+# recorded, so the done callback and the fence's sweep of completed tasks
+# settle each task exactly once even when both observe it.
+_owned_tasks: weakref.WeakSet[asyncio.Task[None]] = weakref.WeakSet()
+_settled_owned_tasks: weakref.WeakSet[asyncio.Task[None]] = weakref.WeakSet()
+# (task name, exception repr) pairs. Reprs, not exception objects: a stored
+# exception's traceback would keep the failed ingestor's whole object graph
+# (task, queue, cached state) alive for the process lifetime, since production
+# never drains this record.
+_owned_task_failures: list[tuple[str, str]] = []
+_MAX_OWNED_TASK_FAILURES = 16
+
+
+def _record_owned_task_result(task: asyncio.Task[None]) -> None:
+    if task in _settled_owned_tasks:
+        return
+    _settled_owned_tasks.add(task)
+    _owned_tasks.discard(task)
+    if task.cancelled():
+        return
+    exc = task.exception()
+    if exc is None:
+        return
+    logger.error("Live usage ingestor task %r died unexpectedly", task.get_name(), exc_info=exc)
+    if len(_owned_task_failures) < _MAX_OWNED_TASK_FAILURES:
+        _owned_task_failures.append((task.get_name(), repr(exc)))
+
+
+def _enroll_owned_task(task: asyncio.Task[None]) -> None:
+    _owned_tasks.add(task)
+    task.add_done_callback(_record_owned_task_result)
+
+
+@dataclass(frozen=True, slots=True)
+class _QueuedSnapshot:
+    account_id: str | None
+    chatgpt_account_id: str | None
+    snapshot: LiveRateLimitSnapshot
+
+
+def _fingerprint(snapshot: LiveRateLimitSnapshot) -> tuple[object, ...]:
+    def window_key(window: LiveUsageWindow | None) -> tuple[object, ...] | None:
+        if window is None:
+            return None
+        return (round(window.used_percent, 2), window.window_minutes, window.reset_at)
+
+    return (
+        window_key(snapshot.primary),
+        window_key(snapshot.secondary),
+        snapshot.credits_has,
+        snapshot.credits_unlimited,
+        snapshot.credits_balance,
+    )
+
+
+class LiveUsageIngestor:
+    """Fire-and-forget sink for per-turn rate-limit snapshots.
+
+    Snapshots ride the serving path, so enqueueing must stay O(1) and never
+    raise; a single consumer task owns its own background sessions and writes
+    usage-history rows with the same shape the background poller produces.
+    """
+
+    def __init__(
+        self,
+        *,
+        queue_size: int,
+        write_min_interval_seconds: float,
+    ) -> None:
+        self._queue: asyncio.Queue[_QueuedSnapshot] = asyncio.Queue(maxsize=max(1, queue_size))
+        self._write_min_interval_seconds = write_min_interval_seconds
+        self._last_write: dict[str, tuple[tuple[object, ...], float]] = {}
+        self._consumer: asyncio.Task[None] | None = None
+        self._dropped = 0
+        self._last_cache_invalidation = 0.0
+        self._trailing_invalidation: asyncio.Task[None] | None = None
+
+    def publish(
+        self,
+        snapshot: LiveRateLimitSnapshot,
+        *,
+        account_id: str | None = None,
+        chatgpt_account_id: str | None = None,
+    ) -> None:
+        item = _QueuedSnapshot(account_id=account_id, chatgpt_account_id=chatgpt_account_id, snapshot=snapshot)
+        if account_id is not None and self._should_skip(account_id, snapshot):
+            return
+        try:
+            self._queue.put_nowait(item)
+        except asyncio.QueueFull:
+            try:
+                self._queue.get_nowait()
+            except asyncio.QueueEmpty:
+                pass
+            self._dropped += 1
+            if self._dropped % 100 == 1:
+                logger.warning("Live usage ingest queue full; dropped_total=%d", self._dropped)
+            try:
+                self._queue.put_nowait(item)
+            except asyncio.QueueFull:
+                pass
+
+    def start(self) -> None:
+        if self._consumer is None or self._consumer.done():
+            self._consumer = asyncio.create_task(self._run(), name="live-usage-ingestor")
+            _enroll_owned_task(self._consumer)
+
+    def is_running(self) -> bool:
+        consumer = self._consumer
+        return consumer is not None and not consumer.done()
+
+    async def stop(self) -> None:
+        consumer = self._consumer
+        self._consumer = None
+        trailing = self._trailing_invalidation
+        self._trailing_invalidation = None
+        for task in (consumer, trailing):
+            if task is not None:
+                task.cancel()
+                try:
+                    await task
+                except asyncio.CancelledError:
+                    pass
+
+    def _should_skip(self, account_id: str, snapshot: LiveRateLimitSnapshot) -> bool:
+        last = self._last_write.get(account_id)
+        if last is None:
+            return False
+        fingerprint, written_at = last
+        if fingerprint != _fingerprint(snapshot):
+            return False
+        return time.monotonic() - written_at < self._write_min_interval_seconds
+
+    async def _run(self) -> None:
+        while True:
+            item = await self._queue.get()
+            try:
+                await self._ingest(item)
+            except asyncio.CancelledError:
+                raise
+            except Exception:
+                logger.warning(
+                    "Live usage ingest failed account_id=%s chatgpt_account_id=%s",
+                    item.account_id,
+                    item.chatgpt_account_id,
+                    exc_info=True,
+                )
+
+    async def _ingest(self, item: _QueuedSnapshot) -> None:
+        snapshot = item.snapshot
+        primary = snapshot.primary
+        secondary = snapshot.secondary
+        monthly: LiveUsageWindow | None = None
+        # Mirror the poller's write-time normalization: a lone primary window
+        # with the monthly duration is the monthly-only free-plan shape and
+        # belongs in the monthly slot, not the primary one.
+        if (
+            primary is not None
+            and secondary is None
+            and primary.window_minutes == usage_core.DEFAULT_WINDOW_MINUTES_MONTHLY
+        ):
+            monthly, primary = primary, None
+        windows: list[UsageWindowWrite] = []
+        if primary is not None:
+            windows.append(
+                UsageWindowWrite(
+                    window="primary",
+                    used_percent=float(primary.used_percent),
+                    reset_at=primary.reset_at,
+                    window_minutes=primary.window_minutes,
+                    credits_has=snapshot.credits_has,
+                    credits_unlimited=snapshot.credits_unlimited,
+                    credits_balance=snapshot.credits_balance,
+                )
+            )
+        if secondary is not None:
+            # Mirror the poller: credits normally ride the primary row. A
+            # secondary-only snapshot must still carry fresh credit state.
+            secondary_carries_credits = primary is None
+            windows.append(
+                UsageWindowWrite(
+                    window="secondary",
+                    used_percent=float(secondary.used_percent),
+                    reset_at=secondary.reset_at,
+                    window_minutes=secondary.window_minutes,
+                    credits_has=snapshot.credits_has if secondary_carries_credits else None,
+                    credits_unlimited=snapshot.credits_unlimited if secondary_carries_credits else None,
+                    credits_balance=snapshot.credits_balance if secondary_carries_credits else None,
+                )
+            )
+        if monthly is not None:
+            windows.append(
+                UsageWindowWrite(
+                    window="monthly",
+                    used_percent=float(monthly.used_percent),
+                    reset_at=monthly.reset_at,
+                    window_minutes=monthly.window_minutes,
+                    credits_has=snapshot.credits_has,
+                    credits_unlimited=snapshot.credits_unlimited,
+                    credits_balance=snapshot.credits_balance,
+                )
+            )
+
+        async with get_background_session() as session:
+            account_id = await UsageRepository(session).settle_live_account_snapshot(
+                account_id=item.account_id,
+                chatgpt_account_id=item.chatgpt_account_id,
+                windows=windows,
+                should_skip=lambda resolved: self._should_skip(resolved, snapshot),
+            )
+        if account_id is None:
+            return
+        self._last_write[account_id] = (_fingerprint(snapshot), time.monotonic())
+        await self._invalidate_caches_throttled()
+
+    async def _invalidate_caches_throttled(self) -> None:
+        # Invalidations are throttled, but every write must still be covered:
+        # a write inside the throttle window schedules one trailing
+        # invalidation at window expiry, so cached selection inputs and
+        # downstream x-codex-* headers are stale for at most the throttle
+        # interval rather than the header cache TTL.
+        now = time.monotonic()
+        remaining = _CACHE_INVALIDATION_MIN_INTERVAL_SECONDS - (now - self._last_cache_invalidation)
+        if remaining <= 0:
+            await self._invalidate_caches_now()
+            return
+        if self._trailing_invalidation is None or self._trailing_invalidation.done():
+            self._trailing_invalidation = asyncio.create_task(
+                self._trailing_invalidate(remaining),
+                name="live-usage-trailing-invalidation",
+            )
+            _enroll_owned_task(self._trailing_invalidation)
+
+    async def _trailing_invalidate(self, delay_seconds: float) -> None:
+        await asyncio.sleep(delay_seconds)
+        await self._invalidate_caches_now()
+
+    async def _invalidate_caches_now(self) -> None:
+        self._last_cache_invalidation = time.monotonic()
+        get_account_selection_cache().invalidate()
+        # Downstream x-codex-* headers are served from a TTL cache that only
+        # the poller invalidates otherwise; drop it so clients see the live
+        # values before the TTL expires.
+        await get_rate_limit_headers_cache().invalidate()
+
+
+_ingestor: LiveUsageIngestor | None = None
+# Registrations a nested startup displaced, innermost-last. A stack rather
+# than a single prior slot: lifespans can nest more than one level deep (each
+# portal-loop ``TestClient`` adds one), and a stack restores each displaced
+# outer lifespan in LIFO order while an out-of-order stop simply removes its
+# instance from wherever it sits — a single slot would forget everything below
+# the most recent displacement.
+_displaced_ingestors: list[LiveUsageIngestor] = []
+
+
+def start_live_usage_ingestor() -> LiveUsageIngestor | None:
+    """Create, start, and register a fresh ingestor as the current singleton.
+
+    The caller (the app lifespan) MUST hold the returned instance and pass it
+    back to ``stop_live_usage_ingestor`` at shutdown. Two lifespans can be
+    live in one process (the test suite nests a portal-loop ``TestClient``
+    inside an app already running on the session loop); each owns its own
+    instance, and the module global only tracks whichever registered last. A
+    started ingestor whose only strong root is the module global would become
+    an unreferenced reference cycle (task -> coroutine frame -> ingestor ->
+    queue -> getter future -> task) the moment a nested startup overwrites the
+    global, and the cyclic GC would then destroy its consumer task mid-await.
+    """
+    global _ingestor
+    ingestor = LiveUsageIngestor(
+        queue_size=_QUEUE_SIZE,
+        write_min_interval_seconds=_WRITE_MIN_INTERVAL_SECONDS,
+    )
+    ingestor.start()
+    if _ingestor is not None and _ingestor.is_running():
+        # A nested startup displaces a still-running outer registration;
+        # remember it so the nested shutdown can restore it (a dead instance
+        # is never worth remembering).
+        _displaced_ingestors.append(_ingestor)
+    register_live_usage_publisher(ingestor.publish)
+    _ingestor = ingestor
+    return ingestor
+
+
+async def stop_live_usage_ingestor(ingestor: LiveUsageIngestor | None = None) -> None:
+    """Stop ``ingestor``, or the current singleton when omitted.
+
+    The module global and the publisher registration are touched only when
+    the stopped instance still owns them, so a lifespan shutting down cannot
+    orphan or unregister a nested lifespan's newer instance — and a nested
+    lifespan's shutdown cannot leave the outer instance dangling with no
+    stop path (the leak behind issue #1755's cross-test poisoning). When the
+    stopped instance is the current registration, the most recent displaced
+    ingestor that is still running is restored (registration and publisher
+    wiring), so a still-live outer lifespan resumes receiving publications
+    instead of going silently deaf after a nested shutdown.
+    """
+    global _ingestor
+    if ingestor is None:
+        ingestor = _ingestor
+    if ingestor is not None:
+        # Whatever happens next, a stopped instance must never be restorable.
+        try:
+            _displaced_ingestors.remove(ingestor)
+        except ValueError:
+            pass
+    if ingestor is None or _ingestor is ingestor:
+        restored: LiveUsageIngestor | None = None
+        while _displaced_ingestors:
+            candidate = _displaced_ingestors.pop()
+            if candidate.is_running():
+                restored = candidate
+                break
+            # Stopped or dead in the meantime — never restore a dead instance.
+        _ingestor = restored
+        register_live_usage_publisher(restored.publish if restored is not None else None)
+    if ingestor is not None:
+        await ingestor.stop()

app/modules/usage/mappers.py

@@ -0,0 +1,29 @@
+"""Adapters between usage ORM rows and the `UsageWindowRow` value type.
+
+The mapping itself is trivial, but it is shared by proxy, usage,
+dashboard, and account-summary code. Pulling it into a single helper keeps
+future ``UsageWindowRow`` changes from drifting across call sites.
+
+Lives in ``app/modules/usage/`` rather than ``app/core/usage/types.py``
+so that ``app/core/`` does not need to depend on ``app/db/models``.
+"""
+
+from __future__ import annotations
+
+from app.core.usage.types import UsageWindowRow
+from app.db.models import AdditionalUsageHistory, UsageHistory
+
+
+def usage_history_to_window_row(entry: UsageHistory | AdditionalUsageHistory) -> UsageWindowRow:
+    """Build a ``UsageWindowRow`` from a usage ORM row.
+
+    All fields map by name. Callers that need a ``UsageWindowRow`` from a
+    usage row should route through this helper.
+    """
+    return UsageWindowRow(
+        account_id=entry.account_id,
+        used_percent=entry.used_percent,
+        reset_at=entry.reset_at,
+        window_minutes=entry.window_minutes,
+        recorded_at=entry.recorded_at,
+    )