codexLB-up 1.25.0b10__py3-none-any.whl

app/modules/api_keys/service.py

@@ -0,0 +1,2123 @@
+from __future__ import annotations
+
+import json
+import secrets
+import time
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from hashlib import sha256
+from math import ceil
+from typing import Protocol
+
+from sqlalchemy.exc import IntegrityError, OperationalError
+
+from app.core.auth.api_key_cache import get_api_key_cache
+from app.core.cache.invalidation import NAMESPACE_API_KEY, get_cache_invalidation_poller
+from app.core.clients.thread_cache_identity import (
+    THREAD_CACHE_IDENTITY_MODES,
+    normalize_thread_cache_identity_mode,
+)
+from app.core.usage.pricing import (
+    UsageTokens,
+    calculate_cost_from_usage,
+    get_pricing_for_model,
+)
+from app.core.usage.types import UsageWindowRow
+from app.core.utils.time import to_utc_naive, utcnow
+from app.db.models import Account, AccountStatus, ApiKey, ApiKeyLimit, LimitType, LimitWindow, ModelSource, UsageHistory
+from app.db.session import sqlite_writer_section
+from app.db.sqlite_lock_retry import should_retry_after_sqlite_lock
+from app.modules.api_keys.last_used_coalescer import ApiKeyLastUsedCoalescer, get_api_key_last_used_coalescer
+from app.modules.api_keys.limit_windows import advance_limit_reset, limit_window_delta, next_limit_reset
+from app.modules.api_keys.repository import (
+    _UNSET,
+    ApiKeyTrendBucket,
+    ApiKeyUsageSummary,
+    ApiKeyUsageTotals,
+    ReservationResult,
+    UsageReservationData,
+    UsageReservationItemData,
+    _Unset,
+)
+from app.modules.usage.repository import UsageRepository
+
+_SQLITE_BUSY_RETRY_ATTEMPTS = 4
+_SQLITE_BUSY_RETRY_BASE_SECONDS = 0.1
+_SPARKLINE_DAYS = 7
+_DETAIL_BUCKET_SECONDS = 3600
+API_KEY_USAGE_RESERVATION_MAX_TOKEN_BUDGET = 8_192
+API_KEY_USAGE_RESERVATION_DEFAULT_INPUT_TOKENS = API_KEY_USAGE_RESERVATION_MAX_TOKEN_BUDGET
+API_KEY_USAGE_RESERVATION_DEFAULT_OUTPUT_TOKENS = 2_048
+_API_KEY_USAGE_RESERVATION_UNKNOWN_MODEL_MICRODOLLARS = 2_000_000
+_API_KEY_USAGE_RESERVATION_UNKNOWN_MODEL_BASE_TOKENS = API_KEY_USAGE_RESERVATION_MAX_TOKEN_BUDGET * 2
+TRAFFIC_CLASS_FOREGROUND = "foreground"
+TRAFFIC_CLASS_OPPORTUNISTIC = "opportunistic"
+_SUPPORTED_TRAFFIC_CLASSES = frozenset({TRAFFIC_CLASS_FOREGROUND, TRAFFIC_CLASS_OPPORTUNISTIC})
+_SUPPORTED_TRANSPORT_POLICY_OVERRIDES = frozenset({"smart", "always_http", "always_websocket"})
+_REASONING_POLICY_EXCLUSIVE_CONSTRAINT = "ck_api_keys_reasoning_policy_exclusive"
+
+
+class ApiKeysRepositoryProtocol(Protocol):
+    async def create(self, row: ApiKey, *, commit: bool = True) -> ApiKey: ...
+
+    async def get_by_id(self, key_id: str) -> ApiKey | None: ...
+
+    async def get_for_limit_enforcement(self, key_id: str) -> ApiKey | None: ...
+
+    async def get_by_hash(self, key_hash: str) -> ApiKey | None: ...
+
+    async def list_all(self) -> list[ApiKey]: ...
+    async def list_usage_summary_by_key(self) -> dict[str, ApiKeyUsageSummary]: ...
+    async def get_usage_summary_by_key_id(self, key_id: str) -> ApiKeyUsageSummary: ...
+    async def get_limit_usage_value(
+        self,
+        key_id: str,
+        *,
+        limit_type: LimitType,
+        since: datetime,
+        until: datetime,
+        model_filter: str | None,
+    ) -> int: ...
+    async def list_accounts_by_ids(self, account_ids: list[str]) -> list[Account]: ...
+    async def list_model_sources_by_ids(self, source_ids: list[str]) -> list[ModelSource]: ...
+    async def list_all_accounts(self) -> list[Account]: ...
+
+    async def update(
+        self,
+        key_id: str,
+        *,
+        name: str | _Unset = ...,
+        allowed_models: str | None | _Unset = ...,
+        apply_to_codex_model: bool | _Unset = ...,
+        enforced_model: str | None | _Unset = ...,
+        enforced_reasoning_effort: str | None | _Unset = ...,
+        allowed_reasoning_efforts: str | None | _Unset = ...,
+        enforced_service_tier: str | None | _Unset = ...,
+        traffic_class: str | _Unset = ...,
+        transport_policy_override: str | None | _Unset = ...,
+        thread_cache_identity_override: str | None | _Unset = ...,
+        usage_sections: str | _Unset = ...,
+        account_assignment_scope_enabled: bool | _Unset = ...,
+        source_assignment_scope_enabled: bool | _Unset = ...,
+        expires_at: datetime | None | _Unset = ...,
+        is_active: bool | _Unset = ...,
+        key_hash: str | _Unset = ...,
+        key_prefix: str | _Unset = ...,
+        commit: bool = True,
+    ) -> ApiKey | None: ...
+
+    async def delete(self, key_id: str) -> bool: ...
+
+    async def commit(self) -> None: ...
+
+    async def rollback(self) -> None: ...
+
+    async def get_limits_by_key(self, key_id: str) -> list[ApiKeyLimit]: ...
+
+    async def replace_limits(self, key_id: str, limits: list[ApiKeyLimit]) -> list[ApiKeyLimit]: ...
+
+    async def upsert_limits(
+        self,
+        key_id: str,
+        limits: list[ApiKeyLimit],
+        *,
+        commit: bool = True,
+        preserve_matched_usage: bool = False,
+    ) -> list[ApiKeyLimit]: ...
+    async def replace_account_assignments(
+        self, key_id: str, account_ids: list[str], *, commit: bool = True
+    ) -> None: ...
+    async def replace_source_assignments(self, key_id: str, source_ids: list[str], *, commit: bool = True) -> None: ...
+
+    async def increment_limit_usage(
+        self,
+        key_id: str,
+        *,
+        model: str,
+        input_tokens: int,
+        output_tokens: int,
+        cost_microdollars: int,
+    ) -> None: ...
+
+    async def reset_limit(self, limit_id: int, *, expected_reset_at: datetime, new_reset_at: datetime) -> bool: ...
+
+    async def try_reserve_usage(
+        self,
+        limit_id: int,
+        *,
+        delta: int,
+        expected_reset_at: datetime,
+    ) -> ReservationResult: ...
+
+    async def adjust_reserved_usage(
+        self,
+        limit_id: int,
+        *,
+        delta: int,
+        expected_reset_at: datetime,
+    ) -> bool: ...
+
+    async def create_usage_reservation(
+        self,
+        reservation_id: str,
+        *,
+        key_id: str,
+        model: str,
+        items: list[UsageReservationItemData],
+    ) -> None: ...
+
+    async def get_usage_reservation(self, reservation_id: str) -> UsageReservationData | None: ...
+
+    async def transition_usage_reservation_status(
+        self,
+        reservation_id: str,
+        *,
+        expected_status: str,
+        new_status: str,
+    ) -> bool: ...
+
+    async def upsert_reservation_item_actual(
+        self,
+        reservation_id: str,
+        *,
+        item: UsageReservationItemData,
+        actual_delta: int,
+    ) -> None: ...
+
+    async def settle_usage_reservation(
+        self,
+        reservation_id: str,
+        *,
+        status: str,
+        input_tokens: int | None,
+        output_tokens: int | None,
+        cached_input_tokens: int | None,
+        cost_microdollars: int | None,
+    ) -> None: ...
+
+    async def touch_usage_reservation(self, reservation_id: str) -> bool: ...
+
+    async def trends_by_key(
+        self,
+        key_id: str,
+        since: datetime,
+        until: datetime,
+        bucket_seconds: int = 3600,
+    ) -> list[ApiKeyTrendBucket]: ...
+
+    async def usage_7d(
+        self,
+        key_id: str,
+        since: datetime,
+        until: datetime,
+    ) -> ApiKeyUsageTotals: ...
+
+
+class ApiKeyNotFoundError(ValueError):
+    pass
+
+
+class ApiKeyInvalidError(ValueError):
+    pass
+
+
+class ApiKeyValidationError(ValueError):
+    """Raised when api_keys service input fails domain validation.
+
+    Subclasses ValueError so existing transitive callers that catch
+    ``ValueError`` continue to work, but lets API routes catch the
+    typed exception explicitly so unrelated programming errors that
+    happen to surface as ``ValueError`` are no longer silently
+    converted into 4xx client responses (#619).
+    """
+
+    pass
+
+
+class ApiKeyRateLimitExceededError(ValueError):
+    def __init__(self, *, message: str, reset_at: datetime) -> None:
+        super().__init__(message)
+        self.reset_at = reset_at
+
+
+def _ensure_optional_int_token_budget(field_name: str, value: int | None) -> None:
+    if value is None:
+        return
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise TypeError(f"{field_name} must be an int or None")
+
+
+@dataclass(frozen=True, slots=True)
+class ApiKeyRequestUsageBudget:
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+
+    def __post_init__(self) -> None:
+        _ensure_optional_int_token_budget("input_tokens", self.input_tokens)
+        _ensure_optional_int_token_budget("output_tokens", self.output_tokens)
+
+
+@dataclass(frozen=True, slots=True)
+class LimitRuleData:
+    id: int
+    limit_type: str
+    limit_window: str
+    max_value: int
+    current_value: int
+    model_filter: str | None
+    reset_at: datetime
+
+
+@dataclass(frozen=True, slots=True)
+class LimitRuleInput:
+    limit_type: str
+    limit_window: str
+    max_value: int
+    model_filter: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ApiKeyCreateData:
+    name: str
+    allowed_models: list[str] | None
+    apply_to_codex_model: bool = False
+    enforced_model: str | None = None
+    enforced_reasoning_effort: str | None = None
+    allowed_reasoning_efforts: list[str] | None = None
+    enforced_service_tier: str | None = None
+    traffic_class: str = TRAFFIC_CLASS_FOREGROUND
+    transport_policy_override: str | None = None
+    thread_cache_identity_override: str | None = None
+    usage_sections: str = "upstream_limits,account_pool_usage"
+    expires_at: datetime | None = None
+    assigned_account_ids: list[str] | None = None
+    assigned_source_ids: list[str] | None = None
+    limits: list[LimitRuleInput] = field(default_factory=list)
+
+
+@dataclass(frozen=True, slots=True)
+class ApiKeyUpdateData:
+    name: str | None = None
+    name_set: bool = False
+    allowed_models: list[str] | None = None
+    allowed_models_set: bool = False
+    apply_to_codex_model: bool | None = None
+    apply_to_codex_model_set: bool = False
+    enforced_model: str | None = None
+    enforced_model_set: bool = False
+    enforced_reasoning_effort: str | None = None
+    enforced_reasoning_effort_set: bool = False
+    allowed_reasoning_efforts: list[str] | None = None
+    allowed_reasoning_efforts_set: bool = False
+    enforced_service_tier: str | None = None
+    enforced_service_tier_set: bool = False
+    traffic_class: str | None = None
+    traffic_class_set: bool = False
+    transport_policy_override: str | None = None
+    transport_policy_override_set: bool = False
+    thread_cache_identity_override: str | None = None
+    thread_cache_identity_override_set: bool = False
+    usage_sections: str | None = None
+    usage_sections_set: bool = False
+    expires_at: datetime | None = None
+    expires_at_set: bool = False
+    is_active: bool | None = None
+    is_active_set: bool = False
+    assigned_account_ids: list[str] | None = None
+    assigned_account_ids_set: bool = False
+    assigned_source_ids: list[str] | None = None
+    assigned_source_ids_set: bool = False
+    limits: list[LimitRuleInput] | None = None
+    limits_set: bool = False
+    reset_usage: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class ApiKeyData:
+    id: str
+    name: str
+    key_prefix: str
+    allowed_models: list[str] | None
+    enforced_model: str | None
+    enforced_reasoning_effort: str | None
+    enforced_service_tier: str | None
+    expires_at: datetime | None
+    is_active: bool
+    created_at: datetime
+    last_used_at: datetime | None
+    allowed_reasoning_efforts: list[str] | None = None
+    apply_to_codex_model: bool = False
+    traffic_class: str = TRAFFIC_CLASS_FOREGROUND
+    transport_policy_override: str | None = None
+    thread_cache_identity_override: str | None = None
+    usage_sections: str = "upstream_limits,account_pool_usage"
+    limits: list[LimitRuleData] = field(default_factory=list)
+    usage_summary: "ApiKeyUsageSummaryData | None" = None
+    account_assignment_scope_enabled: bool = False
+    source_assignment_scope_enabled: bool = False
+    assigned_account_ids: list[str] = field(default_factory=list)
+    assigned_source_ids: list[str] = field(default_factory=list)
+    pooled_credits: "PooledCreditData | None" = None
+
+
+@dataclass(frozen=True, slots=True)
+class ApiKeyCreatedData(ApiKeyData):
+    key: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class ApiKeyUsageSummaryData:
+    request_count: int
+    total_tokens: int
+    cached_input_tokens: int
+    total_cost_usd: float
+
+
+@dataclass(frozen=True, slots=True)
+class PooledCreditData:
+    remaining_percent_primary: float | None = None
+    remaining_percent_secondary: float | None = None
+    capacity_credits_primary: float = 0.0
+
+
+def _compute_pooled_credits(
+    *,
+    assigned_account_ids: list[str],
+    all_accounts: list[Account],
+    primary_usage: dict[str, UsageHistory],
+    secondary_usage: dict[str, UsageHistory],
+    account_assignment_scope_enabled: bool = False,
+) -> PooledCreditData:
+    import app.core.usage as usage_core
+    from app.modules.usage.mappers import usage_history_to_window_row
+
+    if account_assignment_scope_enabled and not assigned_account_ids:
+        return PooledCreditData()
+
+    if assigned_account_ids:
+        requested_account_ids = set(assigned_account_ids)
+    else:
+        requested_account_ids = {a.id for a in all_accounts}
+
+    account_map = {
+        a.id: a
+        for a in all_accounts
+        if a.id in requested_account_ids and a.status not in (AccountStatus.DEACTIVATED, AccountStatus.PAUSED)
+    }
+    account_ids = set(account_map)
+
+    primary_rows_raw = [
+        usage_history_to_window_row(entry) for entry in primary_usage.values() if entry.account_id in account_ids
+    ]
+    secondary_rows_raw = [
+        usage_history_to_window_row(entry) for entry in secondary_usage.values() if entry.account_id in account_ids
+    ]
+
+    primary_rows, secondary_rows = usage_core.normalize_weekly_only_rows(
+        primary_rows_raw,
+        secondary_rows_raw,
+    )
+    now_epoch = int(time.time())
+    # A live primary sample is one whose reset has not elapsed; when none
+    # exists (upstream stopped reporting the short window), the pooled
+    # primary bar must read absent rather than frozen or optimistic.
+    has_live_primary = any(row.reset_at is None or row.reset_at > now_epoch for row in primary_rows)
+    primary_rows = usage_core.expire_elapsed_window_rows(primary_rows, now_epoch=now_epoch)
+    # Secondary (weekly) rows pool raw: upstream still reports long windows,
+    # so an elapsed sample is transient staleness the next refresh rewrites —
+    # zeroing it would briefly report an exhausted weekly pool as 100% free.
+    primary_rows = _seed_missing_usage_rows(primary_rows, account_ids)
+    secondary_rows = _seed_missing_usage_rows(secondary_rows, account_ids)
+
+    primary_summary = usage_core.summarize_usage_window(primary_rows, account_map, "primary")
+    secondary_summary = usage_core.summarize_usage_window(secondary_rows, account_map, "secondary")
+
+    primary_remaining = usage_core.remaining_percent_from_used(primary_summary.used_percent)
+    secondary_remaining = usage_core.remaining_percent_from_used(secondary_summary.used_percent)
+
+    if primary_summary.capacity_credits == 0.0 or not has_live_primary:
+        primary_remaining = None
+
+    return PooledCreditData(
+        remaining_percent_primary=primary_remaining,
+        remaining_percent_secondary=secondary_remaining,
+        capacity_credits_primary=primary_summary.capacity_credits,
+    )
+
+
+def _seed_missing_usage_rows(
+    rows: list[UsageWindowRow],
+    account_ids: set[str],
+) -> list[UsageWindowRow]:
+    present_account_ids = {row.account_id for row in rows}
+    missing_account_ids = account_ids - present_account_ids
+    if not missing_account_ids:
+        return rows
+    return rows + [
+        UsageWindowRow(account_id=account_id, used_percent=0.0) for account_id in sorted(missing_account_ids)
+    ]
+
+
+@dataclass(frozen=True, slots=True)
+class ApiKeyUsageReservationData:
+    reservation_id: str
+    key_id: str
+    model: str
+    has_applicable_limits: bool = True
+
+
+class ApiKeysService:
+    def __init__(
+        self,
+        repository: ApiKeysRepositoryProtocol,
+        usage_repository: UsageRepository | None = None,
+        *,
+        last_used_coalescer: ApiKeyLastUsedCoalescer | None = None,
+    ) -> None:
+        self._repository = repository
+        self._usage_repository = usage_repository
+        self._last_used_coalescer = last_used_coalescer or get_api_key_last_used_coalescer()
+
+    async def create_key(self, payload: ApiKeyCreateData) -> ApiKeyCreatedData:
+        _validate_unique_limit_rule_identities(payload.limits)
+        now = utcnow()
+        expires_at = _normalize_expires_at(payload.expires_at)
+        plain_key = _generate_plain_key()
+        normalized_allowed_models = _normalize_allowed_models(payload.allowed_models)
+        assigned_account_ids = await self._resolve_assigned_account_ids(payload.assigned_account_ids)
+        assigned_source_ids = await self._resolve_assigned_source_ids(payload.assigned_source_ids)
+        enforced_model = _normalize_model_slug(payload.enforced_model)
+        enforced_reasoning_effort = _normalize_reasoning_effort(payload.enforced_reasoning_effort)
+        allowed_reasoning_efforts = _normalize_allowed_reasoning_efforts(payload.allowed_reasoning_efforts)
+        enforced_service_tier = _normalize_service_tier(payload.enforced_service_tier)
+        traffic_class = _normalize_traffic_class(payload.traffic_class)
+        transport_policy_override = _normalize_transport_policy_override(payload.transport_policy_override)
+        thread_cache_identity_override = _normalize_thread_cache_identity_override(
+            payload.thread_cache_identity_override
+        )
+        usage_sections = _normalize_usage_sections(payload.usage_sections)
+        _validate_model_enforcement(enforced_model=enforced_model, allowed_models=normalized_allowed_models)
+        _validate_reasoning_effort_policy(
+            enforced_reasoning_effort=enforced_reasoning_effort,
+            allowed_reasoning_efforts=allowed_reasoning_efforts,
+        )
+        row = ApiKey(
+            id=str(__import__("uuid").uuid4()),
+            name=_normalize_name(payload.name),
+            key_hash=_hash_key(plain_key),
+            key_prefix=plain_key[:15],
+            allowed_models=_serialize_allowed_models(normalized_allowed_models),
+            apply_to_codex_model=bool(payload.apply_to_codex_model),
+            enforced_model=enforced_model,
+            enforced_reasoning_effort=enforced_reasoning_effort,
+            allowed_reasoning_efforts=_serialize_allowed_reasoning_efforts(allowed_reasoning_efforts),
+            enforced_service_tier=enforced_service_tier,
+            account_assignment_scope_enabled=bool(assigned_account_ids),
+            source_assignment_scope_enabled=bool(assigned_source_ids),
+            traffic_class=traffic_class,
+            transport_policy_override=transport_policy_override,
+            thread_cache_identity_override=thread_cache_identity_override,
+            usage_sections=usage_sections,
+            expires_at=expires_at,
+            is_active=True,
+            created_at=now,
+            last_used_at=None,
+        )
+        try:
+            created = await self._repository.create(row, commit=False)
+
+            if assigned_account_ids:
+                await self._repository.replace_account_assignments(created.id, assigned_account_ids, commit=False)
+            if assigned_source_ids:
+                await self._repository.replace_source_assignments(created.id, assigned_source_ids, commit=False)
+
+            if payload.limits:
+                limit_rows = [_limit_input_to_row(li, created.id, now) for li in payload.limits]
+                await self._repository.upsert_limits(created.id, limit_rows, commit=False)
+
+            await self._repository.commit()
+        except Exception as exc:
+            await self._repository.rollback()
+            if isinstance(exc, IntegrityError) and _is_reasoning_policy_constraint_error(exc):
+                raise ApiKeyValidationError(
+                    "enforced_reasoning_effort and allowed_reasoning_efforts cannot be configured together"
+                ) from exc
+            raise
+
+        created = await self._repository.get_by_id(created.id)
+        if created is None:
+            raise ValueError("Failed to create API key")
+
+        return _to_created_data(_to_api_key_data(created), plain_key)
+
+    async def list_keys(self) -> list[ApiKeyData]:
+        rows = await self._repository.list_all()
+        usage_summary_by_key = await self._repository.list_usage_summary_by_key()
+
+        pooled_by_key: dict[str, PooledCreditData] = {}
+        if self._usage_repository is not None:
+            assigned_ids_by_key = {
+                row.id: [a.account_id for a in getattr(row, "account_assignments", [])] for row in rows
+            }
+            needs_all_accounts = any(
+                not assigned_ids_by_key[row.id] and not row.account_assignment_scope_enabled for row in rows
+            )
+            if needs_all_accounts:
+                all_accounts = await self._repository.list_all_accounts()
+                primary_usage = await self._usage_repository.latest_by_account("primary")
+                secondary_usage = await self._usage_repository.latest_by_account("secondary")
+            else:
+                all_account_ids = sorted({account_id for ids in assigned_ids_by_key.values() for account_id in ids})
+                if all_account_ids:
+                    all_accounts = await self._repository.list_accounts_by_ids(all_account_ids)
+                    primary_usage = await self._usage_repository.latest_by_account(
+                        "primary", account_ids=all_account_ids
+                    )
+                    secondary_usage = await self._usage_repository.latest_by_account(
+                        "secondary",
+                        account_ids=all_account_ids,
+                    )
+                else:
+                    all_accounts = []
+                    primary_usage = {}
+                    secondary_usage = {}
+            for row in rows:
+                pooled_by_key[row.id] = _compute_pooled_credits(
+                    assigned_account_ids=assigned_ids_by_key[row.id],
+                    all_accounts=all_accounts,
+                    primary_usage=primary_usage,
+                    secondary_usage=secondary_usage,
+                    account_assignment_scope_enabled=row.account_assignment_scope_enabled,
+                )
+
+        return [
+            _to_api_key_data(
+                row,
+                usage_summary=_to_usage_summary_data(usage_summary_by_key.get(row.id)),
+                pooled_credits=pooled_by_key.get(row.id),
+            )
+            for row in rows
+        ]
+
+    async def update_key(
+        self,
+        key_id: str,
+        payload: ApiKeyUpdateData,
+        *,
+        _retry_attempt: int = 0,
+    ) -> ApiKeyData:
+        expires_at = _normalize_expires_at(payload.expires_at) if payload.expires_at_set else None
+        existing = await self._repository.get_by_id(key_id)
+        if existing is None:
+            raise ApiKeyNotFoundError(f"API key not found: {key_id}")
+
+        if payload.allowed_models_set:
+            allowed_models = _normalize_allowed_models(payload.allowed_models)
+        else:
+            allowed_models = None
+        if payload.assigned_account_ids_set:
+            assigned_account_ids = await self._resolve_assigned_account_ids(payload.assigned_account_ids)
+            account_assignment_scope_enabled: bool | _Unset = bool(assigned_account_ids)
+        else:
+            assigned_account_ids = None
+            account_assignment_scope_enabled = _UNSET
+        if payload.assigned_source_ids_set:
+            assigned_source_ids = await self._resolve_assigned_source_ids(payload.assigned_source_ids)
+            source_assignment_scope_enabled: bool | _Unset = bool(assigned_source_ids)
+        else:
+            assigned_source_ids = None
+            source_assignment_scope_enabled = _UNSET
+
+        if payload.enforced_model_set:
+            enforced_model = _normalize_model_slug(payload.enforced_model)
+        else:
+            enforced_model = None
+
+        apply_to_codex_model: bool | _Unset
+        if payload.apply_to_codex_model_set:
+            if payload.apply_to_codex_model is None:
+                apply_to_codex_model = _UNSET
+            else:
+                apply_to_codex_model = payload.apply_to_codex_model
+        else:
+            apply_to_codex_model = _UNSET
+
+        if payload.enforced_reasoning_effort_set:
+            enforced_reasoning_effort = _normalize_reasoning_effort(payload.enforced_reasoning_effort)
+        else:
+            enforced_reasoning_effort = None
+
+        if payload.allowed_reasoning_efforts_set:
+            allowed_reasoning_efforts = _normalize_allowed_reasoning_efforts(payload.allowed_reasoning_efforts)
+        else:
+            allowed_reasoning_efforts = None
+
+        if payload.enforced_service_tier_set:
+            enforced_service_tier = _normalize_service_tier(payload.enforced_service_tier)
+        else:
+            enforced_service_tier = None
+
+        traffic_class_update: str | _Unset = _UNSET
+        if payload.traffic_class_set:
+            traffic_class_update = _normalize_traffic_class(payload.traffic_class)
+        transport_policy_override_update: str | None | _Unset = _UNSET
+        if payload.transport_policy_override_set:
+            transport_policy_override_update = _normalize_transport_policy_override(payload.transport_policy_override)
+        thread_cache_identity_override_update: str | None | _Unset = _UNSET
+        if payload.thread_cache_identity_override_set:
+            thread_cache_identity_override_update = _normalize_thread_cache_identity_override(
+                payload.thread_cache_identity_override
+            )
+        usage_sections: str | _Unset = _UNSET
+        if payload.usage_sections_set:
+            usage_sections = _normalize_usage_sections(payload.usage_sections)
+
+        if payload.allowed_models_set or payload.enforced_model_set:
+            effective_allowed_models = (
+                allowed_models if payload.allowed_models_set else _deserialize_allowed_models(existing.allowed_models)
+            )
+            effective_enforced_model = (
+                enforced_model if payload.enforced_model_set else _normalize_model_slug(existing.enforced_model)
+            )
+            _validate_model_enforcement(
+                enforced_model=effective_enforced_model,
+                allowed_models=effective_allowed_models,
+            )
+
+        if payload.enforced_reasoning_effort_set or payload.allowed_reasoning_efforts_set:
+            effective_enforced_reasoning_effort = (
+                enforced_reasoning_effort
+                if payload.enforced_reasoning_effort_set
+                else _normalize_reasoning_effort_lenient(existing.enforced_reasoning_effort)
+            )
+            effective_allowed_reasoning_efforts = (
+                allowed_reasoning_efforts
+                if payload.allowed_reasoning_efforts_set
+                else _deserialize_allowed_reasoning_efforts(existing.allowed_reasoning_efforts)
+            )
+            _validate_reasoning_effort_policy(
+                enforced_reasoning_effort=effective_enforced_reasoning_effort,
+                allowed_reasoning_efforts=effective_allowed_reasoning_efforts,
+            )
+
+        limit_rows: list[ApiKeyLimit] | None = None
+        if payload.limits_set:
+            now = utcnow()
+            existing_limits = await self._repository.get_limits_by_key(key_id)
+            submitted_limits = payload.limits or []
+            limit_rows = await _build_limit_rows_for_update(
+                key_id=key_id,
+                now=now,
+                submitted_limits=submitted_limits,
+                existing_limits=existing_limits,
+                reset_usage=payload.reset_usage,
+                repository=self._repository,
+            )
+        elif payload.reset_usage:
+            now = utcnow()
+            existing_limits = await self._repository.get_limits_by_key(key_id)
+            limit_rows = _build_reset_limit_rows(key_id=key_id, now=now, existing_limits=existing_limits)
+
+        try:
+            row = await self._repository.update(
+                key_id,
+                name=_normalize_name(payload.name or "") if payload.name_set else _UNSET,
+                allowed_models=_serialize_allowed_models(allowed_models) if payload.allowed_models_set else _UNSET,
+                apply_to_codex_model=apply_to_codex_model,
+                enforced_model=enforced_model if payload.enforced_model_set else _UNSET,
+                enforced_reasoning_effort=(
+                    enforced_reasoning_effort if payload.enforced_reasoning_effort_set else _UNSET
+                ),
+                allowed_reasoning_efforts=(
+                    _serialize_allowed_reasoning_efforts(allowed_reasoning_efforts)
+                    if payload.allowed_reasoning_efforts_set
+                    else _UNSET
+                ),
+                enforced_service_tier=(enforced_service_tier if payload.enforced_service_tier_set else _UNSET),
+                traffic_class=traffic_class_update,
+                transport_policy_override=transport_policy_override_update,
+                thread_cache_identity_override=thread_cache_identity_override_update,
+                usage_sections=usage_sections,
+                account_assignment_scope_enabled=account_assignment_scope_enabled,
+                source_assignment_scope_enabled=source_assignment_scope_enabled,
+                expires_at=expires_at if payload.expires_at_set else _UNSET,
+                is_active=(payload.is_active if payload.is_active_set and payload.is_active is not None else _UNSET),
+                commit=False,
+            )
+            if row is None:
+                raise ApiKeyNotFoundError(f"API key not found: {key_id}")
+
+            if payload.assigned_account_ids_set:
+                assert assigned_account_ids is not None
+                await self._repository.replace_account_assignments(key_id, assigned_account_ids, commit=False)
+            if payload.assigned_source_ids_set:
+                assert assigned_source_ids is not None
+                await self._repository.replace_source_assignments(key_id, assigned_source_ids, commit=False)
+
+            if limit_rows is not None:
+                await self._repository.upsert_limits(
+                    key_id,
+                    limit_rows,
+                    commit=False,
+                    preserve_matched_usage=not payload.reset_usage,
+                )
+
+            await self._repository.commit()
+        except Exception as exc:
+            await self._repository.rollback()
+            if await should_retry_after_sqlite_lock(
+                exc,
+                what="update_key",
+                attempt=_retry_attempt,
+                max_attempts=_SQLITE_BUSY_RETRY_ATTEMPTS,
+                base_delay_seconds=_SQLITE_BUSY_RETRY_BASE_SECONDS,
+            ):
+                return await self.update_key(key_id, payload, _retry_attempt=_retry_attempt + 1)
+            if isinstance(exc, IntegrityError) and _is_reasoning_policy_constraint_error(exc):
+                raise ApiKeyValidationError(
+                    "enforced_reasoning_effort and allowed_reasoning_efforts cannot be configured together"
+                ) from exc
+            raise
+
+        if (
+            payload.assigned_account_ids_set
+            or payload.assigned_source_ids_set
+            or limit_rows is not None
+            or payload.name_set
+            or payload.allowed_models_set
+            or payload.apply_to_codex_model_set
+            or payload.enforced_model_set
+            or payload.enforced_reasoning_effort_set
+            or payload.allowed_reasoning_efforts_set
+            or payload.enforced_service_tier_set
+            or payload.traffic_class_set
+            or payload.transport_policy_override_set
+            or payload.thread_cache_identity_override_set
+            or payload.usage_sections_set
+            or payload.expires_at_set
+            or payload.is_active_set
+        ):
+            row = await self._repository.get_by_id(key_id)
+            if row is None:
+                raise ApiKeyNotFoundError(f"API key not found: {key_id}")
+
+        await get_api_key_cache().invalidate(row.key_hash)
+        poller = get_cache_invalidation_poller()
+        if poller is not None:
+            await poller.bump(NAMESPACE_API_KEY)
+        return _to_api_key_data(row)
+
+    async def _resolve_assigned_account_ids(self, account_ids: list[str] | None) -> list[str]:
+        normalized_account_ids = _normalize_assigned_account_ids(account_ids)
+        existing_accounts = await self._repository.list_accounts_by_ids(normalized_account_ids)
+        existing_account_ids = {account.id for account in existing_accounts}
+        missing_account_ids = [
+            account_id for account_id in normalized_account_ids if account_id not in existing_account_ids
+        ]
+        if missing_account_ids:
+            missing = ", ".join(missing_account_ids)
+            raise ApiKeyValidationError(f"Unknown account ids: {missing}")
+        return normalized_account_ids
+
+    async def _resolve_assigned_source_ids(self, source_ids: list[str] | None) -> list[str]:
+        normalized_source_ids = _normalize_assigned_source_ids(source_ids)
+        if not normalized_source_ids:
+            return []
+        existing_sources = await self._repository.list_model_sources_by_ids(normalized_source_ids)
+        existing_source_ids = {source.id for source in existing_sources}
+        missing_source_ids = [source_id for source_id in normalized_source_ids if source_id not in existing_source_ids]
+        if missing_source_ids:
+            missing = ", ".join(missing_source_ids)
+            raise ApiKeyValidationError(f"Unknown model source ids: {missing}")
+        return normalized_source_ids
+
+    async def delete_key(self, key_id: str) -> None:
+        row = await self._repository.get_by_id(key_id)
+        if row is None:
+            raise ApiKeyNotFoundError(f"API key not found: {key_id}")
+        deleted = await self._repository.delete(key_id)
+        if not deleted:
+            raise ApiKeyNotFoundError(f"API key not found: {key_id}")
+        await get_api_key_cache().invalidate(row.key_hash)
+        poller = get_cache_invalidation_poller()
+        if poller is not None:
+            await poller.bump(NAMESPACE_API_KEY)
+
+    async def regenerate_key(self, key_id: str) -> ApiKeyCreatedData:
+        row = await self._repository.get_by_id(key_id)
+        if row is None:
+            raise ApiKeyNotFoundError(f"API key not found: {key_id}")
+        old_key_hash = row.key_hash
+        plain_key = _generate_plain_key()
+        updated = await self._repository.update(
+            key_id,
+            key_hash=_hash_key(plain_key),
+            key_prefix=plain_key[:15],
+        )
+        if updated is None:
+            raise ApiKeyNotFoundError(f"API key not found: {key_id}")
+        await get_api_key_cache().invalidate(old_key_hash)
+        poller = get_cache_invalidation_poller()
+        if poller is not None:
+            await poller.bump(NAMESPACE_API_KEY)
+        return _to_created_data(_to_api_key_data(updated), plain_key)
+
+    async def validate_key(self, plain_key: str) -> ApiKeyData:
+        if not plain_key:
+            raise ApiKeyInvalidError("Missing API key in Authorization header")
+
+        key_hash = _hash_key(plain_key)
+        now = utcnow()
+        row = _ensure_valid_api_key_row(await self._repository.get_by_hash(key_hash))
+        if row.expires_at is not None and row.expires_at < now:
+            raise ApiKeyInvalidError("API key has expired")
+        limits_reset = await _lazy_reset_expired_limits(self._repository, row.limits, now=now)
+        refreshed = _ensure_valid_api_key_row(await self._repository.get_by_hash(key_hash)) if limits_reset else row
+        if refreshed.expires_at is not None and refreshed.expires_at < now:
+            raise ApiKeyInvalidError("API key has expired")
+        return _to_api_key_data(refreshed)
+
+    async def get_key_by_id(self, key_id: str) -> ApiKeyData:
+        now = utcnow()
+        row = _ensure_valid_api_key_row(await self._repository.get_by_id(key_id))
+        if row.expires_at is not None and row.expires_at < now:
+            raise ApiKeyInvalidError("API key has expired")
+        return _to_api_key_data(row)
+
+    async def enforce_limits_for_request(
+        self,
+        key_id: str,
+        *,
+        request_model: str | None,
+        request_service_tier: str | None = None,
+        request_usage_budget: ApiKeyRequestUsageBudget | None = None,
+    ) -> ApiKeyUsageReservationData | None:
+        for attempt in range(_SQLITE_BUSY_RETRY_ATTEMPTS):
+            try:
+                return await self._enforce_limits_for_request_once(
+                    key_id,
+                    request_model=request_model,
+                    request_service_tier=request_service_tier,
+                    request_usage_budget=request_usage_budget,
+                )
+            except OperationalError as exc:
+                await self._repository.rollback()
+                if not await should_retry_after_sqlite_lock(
+                    exc,
+                    what="enforce_limits_for_request",
+                    attempt=attempt,
+                    max_attempts=_SQLITE_BUSY_RETRY_ATTEMPTS,
+                    base_delay_seconds=_SQLITE_BUSY_RETRY_BASE_SECONDS,
+                ):
+                    raise
+
+        raise RuntimeError("unreachable")
+
+    async def _enforce_limits_for_request_once(
+        self,
+        key_id: str,
+        *,
+        request_model: str | None,
+        request_service_tier: str | None,
+        request_usage_budget: ApiKeyRequestUsageBudget | None,
+    ) -> ApiKeyUsageReservationData | None:
+        now = utcnow()
+        async with sqlite_writer_section():
+            row = _ensure_valid_api_key_row(await self._repository.get_for_limit_enforcement(key_id))
+            if row.expires_at is not None and row.expires_at < now:
+                raise ApiKeyInvalidError("API key has expired")
+            limits_reset = await _lazy_reset_expired_limits(self._repository, row.limits, now=now)
+            refreshed = (
+                _ensure_valid_api_key_row(await self._repository.get_for_limit_enforcement(key_id))
+                if limits_reset
+                else row
+            )
+            if refreshed.expires_at is not None and refreshed.expires_at < now:
+                raise ApiKeyInvalidError("API key has expired")
+
+            reservation_items: list[UsageReservationItemData] = []
+            reservation_id: str | None = None
+            normalized_usage_budget = _normalize_request_usage_budget(request_usage_budget)
+            try:
+                for limit in refreshed.limits:
+                    if not _limit_applies_for_request(limit, request_model=request_model):
+                        continue
+                    if limit.current_value >= limit.max_value:
+                        raise _rate_limit_exceeded_error(limit)
+                    reserve_delta = _reserve_delta_for_limit(
+                        limit,
+                        request_model=request_model,
+                        request_service_tier=request_service_tier,
+                        request_usage_budget=normalized_usage_budget,
+                    )
+                    if reserve_delta > 0:
+                        result = await self._repository.try_reserve_usage(
+                            limit.id,
+                            delta=reserve_delta,
+                            expected_reset_at=limit.reset_at,
+                        )
+                        if not result.success:
+                            raise _rate_limit_exceeded_error(limit)
+                    reservation_items.append(
+                        UsageReservationItemData(
+                            limit_id=limit.id,
+                            limit_type=limit.limit_type,
+                            reserved_delta=reserve_delta,
+                            expected_reset_at=limit.reset_at,
+                        )
+                    )
+
+                if not reservation_items:
+                    # No configured limit applies to this request, so there is
+                    # nothing to reserve and nothing to settle. Skip the empty
+                    # reservation INSERT and its full-durability commit (the
+                    # lazy expired-limit reset above commits inside
+                    # ``reset_limit`` itself, so no write is pending here).
+                    # Every downstream consumer treats a missing reservation
+                    # as "nothing to settle". Commit to close the implicit
+                    # transaction opened by the admission SELECTs: on sessions
+                    # that outlive this call (e.g. the quota-planner warmup
+                    # service) an open transaction would otherwise idle across
+                    # the upstream round-trip until the next commit. This must
+                    # be ``commit()`` rather than ``rollback()``:
+                    # ``AsyncSession.rollback()`` expires every tracked ORM
+                    # object regardless of ``expire_on_commit``, and the warmup
+                    # service shares this session with already-loaded
+                    # ``account``/``decision`` rows whose attribute access
+                    # after expiry raises ``MissingGreenlet``. ``commit()``
+                    # with ``expire_on_commit=False`` (app/db/session.py)
+                    # leaves tracked state loaded, and is semantically
+                    # equivalent here because the transaction holds only the
+                    # admission SELECTs — no reservation write ran, and every
+                    # production caller either dedicates a session to
+                    # admission (proxy paths) or commits each prior write
+                    # inside its repository methods (quota-planner), so no
+                    # unrelated dirty state can be flushed by this commit.
+                    await self._repository.commit()
+                else:
+                    reservation_id = _next_usage_reservation_id()
+                    await self._repository.create_usage_reservation(
+                        reservation_id,
+                        key_id=key_id,
+                        model=request_model or "",
+                        items=reservation_items,
+                    )
+                    await self._repository.commit()
+            except Exception:
+                await self._repository.rollback()
+                raise
+
+        if reservation_id is None:
+            # Settlement is the only other production writer of
+            # ``last_used_at``; without a reservation it never runs, so record
+            # the last-used touch at admission instead. Recorded outside
+            # sqlite_writer_section() for the same reason as settlement: the
+            # shutdown write-through flush takes the writer section itself.
+            await self._last_used_coalescer.record(key_id, utcnow())
+            return None
+
+        return ApiKeyUsageReservationData(
+            reservation_id=reservation_id,
+            key_id=key_id,
+            model=request_model or "",
+            has_applicable_limits=bool(reservation_items),
+        )
+
+    async def finalize_usage_reservation(
+        self,
+        reservation_id: str,
+        *,
+        model: str,
+        input_tokens: int,
+        output_tokens: int,
+        cached_input_tokens: int = 0,
+        service_tier: str | None = None,
+        cost_microdollars: int | None = None,
+    ) -> None:
+        for attempt in range(_SQLITE_BUSY_RETRY_ATTEMPTS):
+            try:
+                await self._settle_usage_reservation(
+                    reservation_id,
+                    model=model,
+                    input_tokens=input_tokens,
+                    output_tokens=output_tokens,
+                    cached_input_tokens=cached_input_tokens,
+                    service_tier=service_tier,
+                    status="finalized",
+                    cost_microdollars_override=cost_microdollars,
+                )
+                return
+            except OperationalError as exc:
+                await self._repository.rollback()
+                if not await should_retry_after_sqlite_lock(
+                    exc,
+                    what="finalize_usage_reservation",
+                    attempt=attempt,
+                    max_attempts=_SQLITE_BUSY_RETRY_ATTEMPTS,
+                    base_delay_seconds=_SQLITE_BUSY_RETRY_BASE_SECONDS,
+                ):
+                    raise
+
+        raise RuntimeError("unreachable")
+
+    async def fail_usage_reservation(
+        self,
+        reservation_id: str,
+        *,
+        model: str,
+        input_tokens: int | None = None,
+        output_tokens: int | None = None,
+        cached_input_tokens: int | None = None,
+        service_tier: str | None = None,
+    ) -> None:
+        for attempt in range(_SQLITE_BUSY_RETRY_ATTEMPTS):
+            try:
+                await self._settle_usage_reservation(
+                    reservation_id,
+                    model=model,
+                    input_tokens=input_tokens,
+                    output_tokens=output_tokens,
+                    cached_input_tokens=cached_input_tokens,
+                    service_tier=service_tier,
+                    status="failed",
+                )
+                return
+            except OperationalError as exc:
+                await self._repository.rollback()
+                if not await should_retry_after_sqlite_lock(
+                    exc,
+                    what="fail_usage_reservation",
+                    attempt=attempt,
+                    max_attempts=_SQLITE_BUSY_RETRY_ATTEMPTS,
+                    base_delay_seconds=_SQLITE_BUSY_RETRY_BASE_SECONDS,
+                ):
+                    raise
+
+        raise RuntimeError("unreachable")
+
+    async def _settle_usage_reservation(
+        self,
+        reservation_id: str,
+        *,
+        model: str,
+        input_tokens: int | None,
+        output_tokens: int | None,
+        cached_input_tokens: int | None,
+        service_tier: str | None,
+        status: str,
+        cost_microdollars_override: int | None = None,
+    ) -> None:
+        async with sqlite_writer_section():
+            reservation = await self._repository.get_usage_reservation(reservation_id)
+            if reservation is None or reservation.status != "reserved":
+                return
+
+            claimed = await self._repository.transition_usage_reservation_status(
+                reservation_id,
+                expected_status="reserved",
+                new_status="settling",
+            )
+            if not claimed:
+                await self._repository.rollback()
+                return
+
+            effective_input_tokens = input_tokens or 0
+            effective_output_tokens = output_tokens or 0
+            effective_cached_input_tokens = cached_input_tokens or 0
+            cost_microdollars = (
+                cost_microdollars_override
+                if cost_microdollars_override is not None
+                else _calculate_cost_microdollars(
+                    model,
+                    effective_input_tokens,
+                    effective_output_tokens,
+                    effective_cached_input_tokens,
+                    service_tier,
+                )
+            )
+
+            try:
+                for item in reservation.items:
+                    actual_delta = _compute_increment_for_limit_type(
+                        item.limit_type,
+                        input_tokens=effective_input_tokens,
+                        output_tokens=effective_output_tokens,
+                        cost_microdollars=cost_microdollars,
+                    )
+                    delta = actual_delta - item.reserved_delta
+                    if delta != 0:
+                        await self._repository.adjust_reserved_usage(
+                            item.limit_id,
+                            delta=delta,
+                            expected_reset_at=item.expected_reset_at,
+                        )
+                    await self._repository.upsert_reservation_item_actual(
+                        reservation_id,
+                        item=item,
+                        actual_delta=actual_delta,
+                    )
+
+                await self._repository.settle_usage_reservation(
+                    reservation_id,
+                    status=status,
+                    input_tokens=input_tokens,
+                    output_tokens=output_tokens,
+                    cached_input_tokens=cached_input_tokens,
+                    cost_microdollars=cost_microdollars,
+                )
+                await self._repository.commit()
+            except Exception:
+                await self._repository.rollback()
+                raise
+
+        # Write-behind: the periodic flusher persists last_used_at (coalesced,
+        # greatest-wins) instead of this settlement commit. Recorded outside
+        # sqlite_writer_section(): during shutdown write-through the record
+        # flushes immediately, and that flush takes the writer section itself.
+        await self._last_used_coalescer.record(reservation.api_key_id, utcnow())
+
+    async def touch_usage_reservation(self, reservation_id: str) -> bool:
+        for attempt in range(_SQLITE_BUSY_RETRY_ATTEMPTS):
+            try:
+                async with sqlite_writer_section():
+                    touched = await self._repository.touch_usage_reservation(reservation_id)
+                    await self._repository.commit()
+                    return touched
+            except OperationalError as exc:
+                await self._repository.rollback()
+                if not await should_retry_after_sqlite_lock(
+                    exc,
+                    what="touch_usage_reservation",
+                    attempt=attempt,
+                    max_attempts=_SQLITE_BUSY_RETRY_ATTEMPTS,
+                    base_delay_seconds=_SQLITE_BUSY_RETRY_BASE_SECONDS,
+                ):
+                    raise
+
+        raise RuntimeError("unreachable")
+
+    async def release_usage_reservation(self, reservation_id: str) -> None:
+        for attempt in range(_SQLITE_BUSY_RETRY_ATTEMPTS):
+            try:
+                await self._release_usage_reservation_once(reservation_id)
+                return
+            except OperationalError as exc:
+                await self._repository.rollback()
+                if not await should_retry_after_sqlite_lock(
+                    exc,
+                    what="release_usage_reservation",
+                    attempt=attempt,
+                    max_attempts=_SQLITE_BUSY_RETRY_ATTEMPTS,
+                    base_delay_seconds=_SQLITE_BUSY_RETRY_BASE_SECONDS,
+                ):
+                    raise
+
+        raise RuntimeError("unreachable")
+
+    async def _release_usage_reservation_once(self, reservation_id: str) -> None:
+        async with sqlite_writer_section():
+            reservation = await self._repository.get_usage_reservation(reservation_id)
+            if reservation is None or reservation.status != "reserved":
+                return
+
+            claimed = await self._repository.transition_usage_reservation_status(
+                reservation_id,
+                expected_status="reserved",
+                new_status="released",
+            )
+            if not claimed:
+                await self._repository.rollback()
+                return
+
+            try:
+                for item in reservation.items:
+                    await self._repository.adjust_reserved_usage(
+                        item.limit_id,
+                        delta=-item.reserved_delta,
+                        expected_reset_at=item.expected_reset_at,
+                    )
+                    await self._repository.upsert_reservation_item_actual(
+                        reservation_id,
+                        item=item,
+                        actual_delta=0,
+                    )
+                await self._repository.settle_usage_reservation(
+                    reservation_id,
+                    status="released",
+                    input_tokens=None,
+                    output_tokens=None,
+                    cached_input_tokens=None,
+                    cost_microdollars=None,
+                )
+                await self._repository.commit()
+            except Exception:
+                await self._repository.rollback()
+                raise
+
+    async def record_usage(
+        self,
+        key_id: str,
+        *,
+        model: str,
+        input_tokens: int,
+        output_tokens: int,
+        cached_input_tokens: int = 0,
+        service_tier: str | None = None,
+    ) -> None:
+        cost_microdollars = _calculate_cost_microdollars(
+            model,
+            input_tokens,
+            output_tokens,
+            cached_input_tokens,
+            service_tier,
+        )
+        await self._repository.increment_limit_usage(
+            key_id,
+            model=model,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            cost_microdollars=cost_microdollars,
+        )
+        await self._last_used_coalescer.record(key_id, utcnow())
+
+    async def get_key_trends(self, key_id: str) -> ApiKeyTrendsData | None:
+        row = await self._repository.get_by_id(key_id)
+        if row is None:
+            return None
+        now = utcnow()
+        since = now - timedelta(days=_SPARKLINE_DAYS)
+        buckets = await self._repository.trends_by_key(
+            key_id,
+            since,
+            now,
+            _DETAIL_BUCKET_SECONDS,
+        )
+        return _build_api_key_trends(key_id, buckets, since, now, _DETAIL_BUCKET_SECONDS)
+
+    async def get_key_usage_summary_for_self(self, key_id: str) -> ApiKeySelfUsageData | None:
+        """Return usage summary + current limits for a single key (self-service lookup)."""
+        row = await self._repository.get_by_id(key_id)
+        if row is None:
+            return None
+
+        now = utcnow()
+        # Reset any expired limits before reading state
+        limits_reset = await _lazy_reset_expired_limits(self._repository, row.limits, now=now)
+        refreshed = await self._repository.get_by_id(key_id) if limits_reset else row
+        if refreshed is None:
+            return None
+
+        usage = await self._repository.get_usage_summary_by_key_id(key_id)
+        limits = [
+            ApiKeySelfLimitData(
+                limit_type=limit.limit_type.value,
+                limit_window=limit.limit_window.value,
+                max_value=limit.max_value,
+                current_value=max(0, min(limit.current_value, limit.max_value)),
+                remaining_value=max(0, limit.max_value - max(0, min(limit.current_value, limit.max_value))),
+                model_filter=limit.model_filter,
+                reset_at=limit.reset_at,
+                source="api_key_limit",
+            )
+            for limit in refreshed.limits
+        ]
+        return ApiKeySelfUsageData(
+            request_count=usage.request_count,
+            total_tokens=usage.total_tokens,
+            cached_input_tokens=usage.cached_input_tokens,
+            total_cost_usd=usage.total_cost_usd,
+            limits=limits,
+        )
+
+    async def get_key_usage_7d(self, key_id: str) -> ApiKeyUsage7DayData | None:
+        row = await self._repository.get_by_id(key_id)
+        if row is None:
+            return None
+        now = utcnow()
+        since = now - timedelta(days=7)
+        data = await self._repository.usage_7d(key_id, since, now)
+        return ApiKeyUsage7DayData(
+            key_id=key_id,
+            total_tokens=data.total_tokens,
+            total_cost_usd=data.total_cost_usd,
+            total_requests=data.total_requests,
+            cached_input_tokens=data.cached_input_tokens,
+            account_costs=[
+                ApiKeyAccountCostData(
+                    account_id=ac.account_id,
+                    email=ac.email,
+                    cost_usd=ac.cost_usd,
+                    is_deleted=ac.is_deleted,
+                )
+                for ac in data.account_costs
+            ],
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ApiKeyTrendsPoint:
+    t: datetime
+    v: float
+
+
+@dataclass(frozen=True, slots=True)
+class ApiKeyTrendsData:
+    key_id: str
+    cost: list[ApiKeyTrendsPoint] = field(default_factory=list)
+    tokens: list[ApiKeyTrendsPoint] = field(default_factory=list)
+
+
+@dataclass(frozen=True, slots=True)
+class ApiKeyAccountCostData:
+    account_id: str | None
+    email: str | None
+    cost_usd: float
+    is_deleted: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class ApiKeyUsage7DayData:
+    key_id: str
+    total_tokens: int = 0
+    total_cost_usd: float = 0.0
+    total_requests: int = 0
+    cached_input_tokens: int = 0
+    account_costs: list[ApiKeyAccountCostData] = field(default_factory=list)
+
+
+@dataclass(frozen=True, slots=True)
+class ApiKeySelfLimitData:
+    limit_type: str
+    limit_window: str
+    max_value: int
+    current_value: int
+    remaining_value: int
+    model_filter: str | None
+    reset_at: datetime
+    source: str = "api_key_limit"
+
+
+@dataclass(frozen=True, slots=True)
+class ApiKeySelfUsageData:
+    request_count: int = 0
+    total_tokens: int = 0
+    cached_input_tokens: int = 0
+    total_cost_usd: float = 0.0
+    limits: list[ApiKeySelfLimitData] = field(default_factory=list)
+
+
+def _normalize_name(name: str) -> str:
+    normalized = name.strip()
+    if not normalized:
+        raise ApiKeyValidationError("API key name is required")
+    return normalized
+
+
+_VALID_USAGE_SECTIONS = {"upstream_limits", "account_pool_usage"}
+_DEFAULT_USAGE_SECTIONS = "upstream_limits,account_pool_usage"
+
+
+def _normalize_usage_sections(raw: str | None) -> str:
+    if raw is None:
+        return _DEFAULT_USAGE_SECTIONS
+    if not raw.strip():
+        return ""
+    sections = [s.strip() for s in raw.split(",") if s.strip()]
+    invalid = [s for s in sections if s not in _VALID_USAGE_SECTIONS]
+    if invalid:
+        raise ApiKeyValidationError(f"Invalid usage sections: {', '.join(invalid)}")
+    return ",".join(dict.fromkeys(sections))
+
+
+def _get_usage_sections_with_default(row: ApiKey) -> str:
+    value = getattr(row, "usage_sections", None)
+    if value is None:
+        return _DEFAULT_USAGE_SECTIONS
+    return value
+
+
+def _generate_plain_key() -> str:
+    return f"sk-clb-{secrets.token_hex(24)}"
+
+
+def _hash_key(plain_key: str) -> str:
+    return sha256(plain_key.encode("utf-8")).hexdigest()
+
+
+def _serialize_allowed_models(allowed_models: list[str] | None) -> str | None:
+    if allowed_models is None:
+        return None
+    return json.dumps(allowed_models)
+
+
+def _serialize_allowed_reasoning_efforts(allowed_reasoning_efforts: list[str] | None) -> str | None:
+    if allowed_reasoning_efforts is None:
+        return None
+    return json.dumps(allowed_reasoning_efforts)
+
+
+def _deserialize_allowed_models(payload: str | None) -> list[str] | None:
+    if payload is None:
+        return None
+    parsed = json.loads(payload)
+    if not isinstance(parsed, list):
+        return None
+    models = [value.strip() for value in parsed if isinstance(value, str) and value.strip()]
+    return models
+
+
+def _deserialize_allowed_reasoning_efforts(payload: str | None) -> list[str] | None:
+    if payload is None:
+        return None
+    try:
+        parsed = json.loads(payload)
+        if not isinstance(parsed, list):
+            return []
+        return _normalize_allowed_reasoning_efforts(parsed)
+    except (ApiKeyValidationError, TypeError, json.JSONDecodeError):
+        return []
+
+
+def _is_reasoning_policy_constraint_error(exc: IntegrityError) -> bool:
+    return _REASONING_POLICY_EXCLUSIVE_CONSTRAINT in str(exc).lower()
+
+
+def _normalize_allowed_models(allowed_models: list[str] | None) -> list[str] | None:
+    if allowed_models is None:
+        return None
+    return [model.strip() for model in allowed_models if model and model.strip()]
+
+
+def _normalize_assigned_account_ids(account_ids: list[str] | None) -> list[str]:
+    if not account_ids:
+        return []
+    normalized: list[str] = []
+    seen: set[str] = set()
+    for account_id in account_ids:
+        value = account_id.strip()
+        if not value or value in seen:
+            continue
+        normalized.append(value)
+        seen.add(value)
+    return normalized
+
+
+def _normalize_assigned_source_ids(source_ids: list[str] | None) -> list[str]:
+    if not source_ids:
+        return []
+    normalized: list[str] = []
+    seen: set[str] = set()
+    for source_id in source_ids:
+        value = source_id.strip()
+        if not value or value in seen:
+            continue
+        normalized.append(value)
+        seen.add(value)
+    return normalized
+
+
+def _normalize_model_slug(value: str | None) -> str | None:
+    if value is None:
+        return None
+    normalized = value.strip()
+    if not normalized:
+        return None
+    return normalized
+
+
+_REASONING_EFFORT_ORDER = ("minimal", "low", "medium", "high", "xhigh", "max", "ultra")
+_SUPPORTED_REASONING_EFFORTS = frozenset({"none", *_REASONING_EFFORT_ORDER})
+_SUPPORTED_SELECTABLE_REASONING_EFFORTS = frozenset(_REASONING_EFFORT_ORDER)
+_SUPPORTED_SERVICE_TIERS = frozenset({"auto", "default", "priority", "flex", "ultrafast"})
+
+
+def _normalize_expires_at(value: datetime | None) -> datetime | None:
+    if value is None:
+        return None
+    return to_utc_naive(value)
+
+
+def _normalize_reasoning_effort(value: str | None) -> str | None:
+    if value is None:
+        return None
+    normalized = value.strip().lower()
+    if not normalized:
+        return None
+    if normalized not in _SUPPORTED_REASONING_EFFORTS:
+        options = ", ".join(sorted(_SUPPORTED_REASONING_EFFORTS))
+        raise ApiKeyValidationError(f"Unsupported enforced reasoning effort '{normalized}'. Expected one of: {options}")
+    return normalized
+
+
+def _normalize_reasoning_effort_lenient(value: str | None) -> str | None:
+    if value is None:
+        return None
+    normalized = value.strip().lower()
+    if not normalized:
+        return None
+    if normalized in _SUPPORTED_REASONING_EFFORTS:
+        return normalized
+    return None
+
+
+def _normalize_allowed_reasoning_efforts(values: list[str] | None) -> list[str] | None:
+    if values is None:
+        return None
+
+    normalized: set[str] = set()
+    for value in values:
+        if not isinstance(value, str):
+            raise ApiKeyValidationError("Allowed reasoning efforts must be strings")
+        effort = value.strip().lower()
+        if effort not in _SUPPORTED_SELECTABLE_REASONING_EFFORTS:
+            options = ", ".join(_REASONING_EFFORT_ORDER)
+            raise ApiKeyValidationError(f"Unsupported allowed reasoning effort '{effort}'. Expected one of: {options}")
+        normalized.add(effort)
+
+    if not normalized:
+        raise ApiKeyValidationError("Allowed reasoning efforts must not be empty")
+    return [effort for effort in _REASONING_EFFORT_ORDER if effort in normalized]
+
+
+def _normalize_service_tier(value: str | None) -> str | None:
+    if value is None:
+        return None
+    normalized = value.strip().lower()
+    if not normalized:
+        return None
+    if normalized == "fast":
+        normalized = "priority"
+    if normalized not in _SUPPORTED_SERVICE_TIERS:
+        options = ", ".join(sorted(_SUPPORTED_SERVICE_TIERS | {"fast"}))
+        raise ApiKeyValidationError(f"Unsupported enforced service tier '{normalized}'. Expected one of: {options}")
+    return normalized
+
+
+def _normalize_service_tier_lenient(value: str | None) -> str | None:
+    if value is None:
+        return None
+    normalized = value.strip().lower()
+    if not normalized:
+        return None
+    if normalized == "fast":
+        return "priority"
+    if normalized in _SUPPORTED_SERVICE_TIERS:
+        return normalized
+    return None
+
+
+def _normalize_traffic_class(value: str | None) -> str:
+    normalized = (value or TRAFFIC_CLASS_FOREGROUND).strip().lower()
+    if normalized not in _SUPPORTED_TRAFFIC_CLASSES:
+        options = ", ".join(sorted(_SUPPORTED_TRAFFIC_CLASSES))
+        raise ValueError(f"Unsupported traffic class '{normalized}'. Expected one of: {options}")
+    return normalized
+
+
+def _normalize_traffic_class_lenient(value: str | None) -> str:
+    normalized = (value or TRAFFIC_CLASS_FOREGROUND).strip().lower()
+    if normalized in _SUPPORTED_TRAFFIC_CLASSES:
+        return normalized
+    return TRAFFIC_CLASS_FOREGROUND
+
+
+def _normalize_thread_cache_identity_override(value: str | None) -> str | None:
+    """Strict (write path): an unknown value is a 400, not a silent fallback."""
+    if value is None:
+        return None
+    normalized = normalize_thread_cache_identity_mode(value)
+    if normalized is not None:
+        return normalized
+    options = ", ".join(sorted(THREAD_CACHE_IDENTITY_MODES))
+    raise ApiKeyValidationError(
+        f"Unsupported thread cache identity override '{value.strip().lower()}'. Expected one of: {options}"
+    )
+
+
+def _normalize_thread_cache_identity_override_lenient(value: str | None) -> str | None:
+    """Read path: a stale or hand-edited value reads as "no override" rather than a 500."""
+    return normalize_thread_cache_identity_mode(value)
+
+
+def _normalize_transport_policy_override(value: str | None) -> str | None:
+    if value is None:
+        return None
+    normalized = value.strip().lower()
+    if normalized in _SUPPORTED_TRANSPORT_POLICY_OVERRIDES:
+        return normalized
+    options = ", ".join(sorted(_SUPPORTED_TRANSPORT_POLICY_OVERRIDES))
+    raise ApiKeyValidationError(f"Unsupported transport policy override '{normalized}'. Expected one of: {options}")
+
+
+def _normalize_transport_policy_override_lenient(value: str | None) -> str | None:
+    if value is None:
+        return None
+    normalized = value.strip().lower()
+    if normalized in _SUPPORTED_TRANSPORT_POLICY_OVERRIDES:
+        return normalized
+    return None
+
+
+def _validate_model_enforcement(*, enforced_model: str | None, allowed_models: list[str] | None) -> None:
+    if enforced_model is None or not allowed_models:
+        return
+    if enforced_model not in allowed_models:
+        raise ApiKeyValidationError(
+            "enforced_model must be present in allowed_models when allowed_models is configured"
+        )
+
+
+def _validate_reasoning_effort_policy(
+    *,
+    enforced_reasoning_effort: str | None,
+    allowed_reasoning_efforts: list[str] | None,
+) -> None:
+    if enforced_reasoning_effort is not None and allowed_reasoning_efforts is not None:
+        raise ApiKeyValidationError(
+            "enforced_reasoning_effort and allowed_reasoning_efforts cannot be configured together"
+        )
+
+
+def _to_limit_rule_data(limit: ApiKeyLimit) -> LimitRuleData:
+    return LimitRuleData(
+        id=limit.id,
+        limit_type=limit.limit_type.value,
+        limit_window=limit.limit_window.value,
+        max_value=limit.max_value,
+        current_value=limit.current_value,
+        model_filter=limit.model_filter,
+        reset_at=limit.reset_at,
+    )
+
+
+def _ensure_valid_api_key_row(row: ApiKey | None) -> ApiKey:
+    if row is None or not row.is_active:
+        raise ApiKeyInvalidError("Invalid API key")
+    return row
+
+
+async def _lazy_reset_expired_limits(
+    repository: ApiKeysRepositoryProtocol,
+    limits: list[ApiKeyLimit],
+    *,
+    now: datetime,
+) -> bool:
+    reset_performed = False
+    for limit in limits:
+        if limit.reset_at >= now:
+            continue
+        new_reset_at = advance_limit_reset(limit.reset_at, now, limit.limit_window)
+        await repository.reset_limit(
+            limit.id,
+            expected_reset_at=limit.reset_at,
+            new_reset_at=new_reset_at,
+        )
+        reset_performed = True
+    return reset_performed
+
+
+def _rate_limit_exceeded_error(limit: ApiKeyLimit) -> ApiKeyRateLimitExceededError:
+    return ApiKeyRateLimitExceededError(
+        message=f"API key {limit.limit_type.value} {limit.limit_window.value} limit exceeded"
+        + (f" for model {limit.model_filter}" if limit.model_filter else ""),
+        reset_at=limit.reset_at,
+    )
+
+
+def _limit_applies_for_request(limit: ApiKeyLimit, *, request_model: str | None) -> bool:
+    if limit.model_filter is None:
+        return True
+    if request_model is None:
+        return False
+    return limit.model_filter == request_model
+
+
+def _reserve_delta_for_limit(
+    limit: ApiKeyLimit,
+    *,
+    request_model: str | None,
+    request_service_tier: str | None,
+    request_usage_budget: ApiKeyRequestUsageBudget,
+) -> int:
+    remaining = limit.max_value - limit.current_value
+    if remaining <= 0:
+        return 0
+    budget = _reserve_budget_for_limit_type(
+        limit.limit_type,
+        request_model=request_model,
+        request_service_tier=request_service_tier,
+        request_usage_budget=request_usage_budget,
+    )
+    return min(remaining, budget)
+
+
+def _normalize_request_usage_budget(budget: ApiKeyRequestUsageBudget | None) -> ApiKeyRequestUsageBudget:
+    if budget is None:
+        return ApiKeyRequestUsageBudget(
+            input_tokens=API_KEY_USAGE_RESERVATION_DEFAULT_INPUT_TOKENS,
+            output_tokens=API_KEY_USAGE_RESERVATION_DEFAULT_OUTPUT_TOKENS,
+        )
+    return ApiKeyRequestUsageBudget(
+        input_tokens=_normalize_reservation_token_budget(
+            budget.input_tokens,
+            default=API_KEY_USAGE_RESERVATION_DEFAULT_INPUT_TOKENS,
+        ),
+        output_tokens=_normalize_reservation_token_budget(
+            budget.output_tokens,
+            default=API_KEY_USAGE_RESERVATION_DEFAULT_OUTPUT_TOKENS,
+        ),
+    )
+
+
+def _normalize_reservation_token_budget(value: int | None, *, default: int) -> int:
+    if value is None:
+        return default
+    return max(0, min(value, API_KEY_USAGE_RESERVATION_MAX_TOKEN_BUDGET))
+
+
+def _reserve_budget_for_limit_type(
+    limit_type: LimitType,
+    *,
+    request_model: str | None,
+    request_service_tier: str | None,
+    request_usage_budget: ApiKeyRequestUsageBudget,
+) -> int:
+    input_tokens = request_usage_budget.input_tokens or 0
+    output_tokens = request_usage_budget.output_tokens or 0
+    if limit_type == LimitType.TOTAL_TOKENS:
+        return input_tokens + output_tokens
+    if limit_type == LimitType.INPUT_TOKENS:
+        return input_tokens
+    if limit_type == LimitType.OUTPUT_TOKENS:
+        return output_tokens
+    if limit_type == LimitType.COST_USD:
+        return _reserve_cost_budget_microdollars(
+            request_model,
+            request_service_tier,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+        )
+    if limit_type == LimitType.CREDITS:
+        return 0
+    return 1
+
+
+def _reserve_cost_budget_microdollars(
+    model: str | None,
+    service_tier: str | None,
+    *,
+    input_tokens: int,
+    output_tokens: int,
+) -> int:
+    if not model:
+        return _unknown_model_reserve_cost_budget_microdollars(input_tokens=input_tokens, output_tokens=output_tokens)
+    cost_microdollars = _calculate_cost_microdollars(
+        model,
+        input_tokens,
+        output_tokens,
+        0,
+        service_tier,
+    )
+    return (
+        cost_microdollars
+        if cost_microdollars > 0
+        else _unknown_model_reserve_cost_budget_microdollars(input_tokens=input_tokens, output_tokens=output_tokens)
+    )
+
+
+def _unknown_model_reserve_cost_budget_microdollars(*, input_tokens: int, output_tokens: int) -> int:
+    token_budget = max(0, input_tokens) + max(0, output_tokens)
+    if token_budget <= 0:
+        return 0
+    return ceil(
+        _API_KEY_USAGE_RESERVATION_UNKNOWN_MODEL_MICRODOLLARS
+        * token_budget
+        / _API_KEY_USAGE_RESERVATION_UNKNOWN_MODEL_BASE_TOKENS
+    )
+
+
+def _compute_increment_for_limit_type(
+    limit_type: LimitType,
+    *,
+    input_tokens: int,
+    output_tokens: int,
+    cost_microdollars: int,
+) -> int:
+    if limit_type == LimitType.TOTAL_TOKENS:
+        return input_tokens + output_tokens
+    if limit_type == LimitType.INPUT_TOKENS:
+        return input_tokens
+    if limit_type == LimitType.OUTPUT_TOKENS:
+        return output_tokens
+    if limit_type == LimitType.COST_USD:
+        return cost_microdollars
+    if limit_type == LimitType.CREDITS:
+        return 0
+    return 0
+
+
+def _next_usage_reservation_id() -> str:
+    return f"ur_{uuid.uuid4().hex}"
+
+
+def _to_created_data(data: ApiKeyData, key: str) -> ApiKeyCreatedData:
+    return ApiKeyCreatedData(
+        id=data.id,
+        name=data.name,
+        key_prefix=data.key_prefix,
+        allowed_models=data.allowed_models,
+        apply_to_codex_model=data.apply_to_codex_model,
+        enforced_model=data.enforced_model,
+        enforced_reasoning_effort=data.enforced_reasoning_effort,
+        allowed_reasoning_efforts=data.allowed_reasoning_efforts,
+        enforced_service_tier=data.enforced_service_tier,
+        traffic_class=data.traffic_class,
+        transport_policy_override=data.transport_policy_override,
+        thread_cache_identity_override=data.thread_cache_identity_override,
+        usage_sections=data.usage_sections,
+        expires_at=data.expires_at,
+        is_active=data.is_active,
+        created_at=data.created_at,
+        last_used_at=data.last_used_at,
+        limits=data.limits,
+        usage_summary=data.usage_summary,
+        account_assignment_scope_enabled=data.account_assignment_scope_enabled,
+        source_assignment_scope_enabled=data.source_assignment_scope_enabled,
+        assigned_account_ids=data.assigned_account_ids,
+        assigned_source_ids=data.assigned_source_ids,
+        key=key,
+    )
+
+
+def _to_api_key_data(
+    row: ApiKey,
+    *,
+    usage_summary: ApiKeyUsageSummaryData | None = None,
+    pooled_credits: PooledCreditData | None = None,
+) -> ApiKeyData:
+    limits = [_to_limit_rule_data(limit) for limit in row.limits] if row.limits else []
+    account_assignments = getattr(row, "account_assignments", [])
+    source_assignments = getattr(row, "source_assignments", [])
+    return ApiKeyData(
+        id=row.id,
+        name=row.name,
+        key_prefix=row.key_prefix,
+        allowed_models=_deserialize_allowed_models(row.allowed_models),
+        apply_to_codex_model=getattr(row, "apply_to_codex_model", False),
+        enforced_model=_normalize_model_slug(row.enforced_model),
+        enforced_reasoning_effort=_normalize_reasoning_effort_lenient(row.enforced_reasoning_effort),
+        allowed_reasoning_efforts=_deserialize_allowed_reasoning_efforts(
+            getattr(row, "allowed_reasoning_efforts", None)
+        ),
+        enforced_service_tier=_normalize_service_tier_lenient(row.enforced_service_tier),
+        traffic_class=_normalize_traffic_class_lenient(getattr(row, "traffic_class", TRAFFIC_CLASS_FOREGROUND)),
+        transport_policy_override=_normalize_transport_policy_override_lenient(
+            getattr(row, "transport_policy_override", None)
+        ),
+        thread_cache_identity_override=_normalize_thread_cache_identity_override_lenient(
+            getattr(row, "thread_cache_identity_override", None)
+        ),
+        usage_sections=_get_usage_sections_with_default(row),
+        expires_at=row.expires_at,
+        is_active=row.is_active,
+        created_at=row.created_at,
+        last_used_at=row.last_used_at,
+        limits=limits,
+        usage_summary=usage_summary,
+        account_assignment_scope_enabled=getattr(row, "account_assignment_scope_enabled", False),
+        source_assignment_scope_enabled=getattr(row, "source_assignment_scope_enabled", False),
+        assigned_account_ids=[assignment.account_id for assignment in account_assignments],
+        assigned_source_ids=[assignment.source_id for assignment in source_assignments],
+        pooled_credits=pooled_credits,
+    )
+
+
+def _to_usage_summary_data(summary: ApiKeyUsageSummary | None) -> ApiKeyUsageSummaryData | None:
+    if summary is None:
+        return None
+    return ApiKeyUsageSummaryData(
+        request_count=summary.request_count,
+        total_tokens=summary.total_tokens,
+        cached_input_tokens=summary.cached_input_tokens,
+        total_cost_usd=summary.total_cost_usd,
+    )
+
+
+def _limit_input_to_row(
+    li: LimitRuleInput,
+    key_id: str,
+    now: datetime,
+    *,
+    current_value: int = 0,
+    reset_at: datetime | None = None,
+) -> ApiKeyLimit:
+    window = LimitWindow(li.limit_window)
+    if li.limit_type == LimitType.CREDITS.value and li.model_filter is not None:
+        raise ApiKeyValidationError("credits limits do not support model_filter")
+    return ApiKeyLimit(
+        api_key_id=key_id,
+        limit_type=LimitType(li.limit_type),
+        limit_window=window,
+        max_value=li.max_value,
+        current_value=current_value,
+        model_filter=li.model_filter,
+        reset_at=reset_at if reset_at is not None else next_limit_reset(now, window),
+    )
+
+
+async def _build_limit_rows_for_update(
+    *,
+    key_id: str,
+    now: datetime,
+    submitted_limits: list[LimitRuleInput],
+    existing_limits: list[ApiKeyLimit],
+    reset_usage: bool,
+    repository: ApiKeysRepositoryProtocol | None = None,
+) -> list[ApiKeyLimit]:
+    existing_by_key = {_limit_identity_from_row(limit): limit for limit in existing_limits}
+    _validate_unique_limit_rule_identities(submitted_limits)
+
+    rows: list[ApiKeyLimit] = []
+    for submitted in submitted_limits:
+        identity = _limit_identity_from_input(submitted)
+        matched = existing_by_key.get(identity)
+        if reset_usage:
+            rows.append(_limit_input_to_row(submitted, key_id, now))
+            continue
+        if matched is None:
+            if repository is None:
+                raise TypeError("repository is required to backfill new API key limit usage")
+            rows.append(await _new_limit_input_to_backfilled_row(submitted, key_id, now, repository))
+            continue
+        rows.append(
+            _limit_input_to_row(
+                submitted,
+                key_id,
+                now,
+                current_value=matched.current_value,
+                reset_at=matched.reset_at,
+            )
+        )
+    return rows
+
+
+async def _new_limit_input_to_backfilled_row(
+    submitted: LimitRuleInput,
+    key_id: str,
+    now: datetime,
+    repository: ApiKeysRepositoryProtocol,
+) -> ApiKeyLimit:
+    limit_type = LimitType(submitted.limit_type)
+    window = LimitWindow(submitted.limit_window)
+    reset_at = next_limit_reset(now, window)
+    since = now - limit_window_delta(window)
+    current_value = await repository.get_limit_usage_value(
+        key_id,
+        limit_type=limit_type,
+        since=since,
+        until=now,
+        model_filter=submitted.model_filter,
+    )
+    return _limit_input_to_row(
+        submitted,
+        key_id,
+        now,
+        current_value=current_value,
+        reset_at=reset_at,
+    )
+
+
+def _build_reset_limit_rows(
+    *,
+    key_id: str,
+    now: datetime,
+    existing_limits: list[ApiKeyLimit],
+) -> list[ApiKeyLimit]:
+    rows: list[ApiKeyLimit] = []
+    for existing in existing_limits:
+        rows.append(
+            ApiKeyLimit(
+                api_key_id=key_id,
+                limit_type=existing.limit_type,
+                limit_window=existing.limit_window,
+                max_value=existing.max_value,
+                current_value=0,
+                model_filter=existing.model_filter,
+                reset_at=next_limit_reset(now, existing.limit_window),
+            )
+        )
+    return rows
+
+
+def _limit_identity_from_input(limit: LimitRuleInput) -> tuple[str, str, str | None]:
+    return (limit.limit_type, limit.limit_window, limit.model_filter)
+
+
+def _validate_unique_limit_rule_identities(limits: list[LimitRuleInput]) -> None:
+    identities: set[tuple[str, str, str | None]] = set()
+    for limit in limits:
+        identity = _limit_identity_from_input(limit)
+        if identity in identities:
+            raise ApiKeyValidationError(f"Duplicate limit rules are not allowed: {identity!r}")
+        identities.add(identity)
+
+
+def _limit_identity_from_row(limit: ApiKeyLimit) -> tuple[str, str, str | None]:
+    return (limit.limit_type.value, limit.limit_window.value, limit.model_filter)
+
+
+def _calculate_cost_microdollars(
+    model: str,
+    input_tokens: int,
+    output_tokens: int,
+    cached_input_tokens: int,
+    service_tier: str | None = None,
+) -> int:
+    resolved = get_pricing_for_model(model)
+    if resolved is None:
+        return 0
+    _, price = resolved
+    usage = UsageTokens(
+        input_tokens=float(input_tokens),
+        output_tokens=float(output_tokens),
+        cached_input_tokens=float(cached_input_tokens),
+    )
+    cost_usd = calculate_cost_from_usage(usage, price, service_tier=service_tier)
+    if cost_usd is None:
+        return 0
+    return int(cost_usd * 1_000_000)
+
+
+def _build_api_key_trends(
+    key_id: str,
+    buckets: list[ApiKeyTrendBucket],
+    since: datetime,
+    until: datetime,
+    bucket_seconds: int,
+) -> ApiKeyTrendsData:
+    since_utc = since.replace(tzinfo=timezone.utc) if since.tzinfo is None else since.astimezone(timezone.utc)
+    until_utc = until.replace(tzinfo=timezone.utc) if until.tzinfo is None else until.astimezone(timezone.utc)
+    if until_utc <= since_utc:
+        return ApiKeyTrendsData(key_id=key_id)
+
+    start_epoch = (int(since_utc.timestamp()) // bucket_seconds) * bucket_seconds
+    # The SQL window is exclusive of `until`, so step back one microsecond to find the last visible bucket.
+    end_epoch = (int((until_utc - timedelta(microseconds=1)).timestamp()) // bucket_seconds) * bucket_seconds
+    bucket_count = ((end_epoch - start_epoch) // bucket_seconds) + 1
+    time_grid = [start_epoch + i * bucket_seconds for i in range(bucket_count)]
+
+    cost_by_bucket: dict[int, float] = {}
+    tokens_by_bucket: dict[int, int] = {}
+    for b in buckets:
+        cost_by_bucket[b.bucket_epoch] = b.total_cost_usd
+        tokens_by_bucket[b.bucket_epoch] = b.total_tokens
+
+    cost_points: list[ApiKeyTrendsPoint] = []
+    tokens_points: list[ApiKeyTrendsPoint] = []
+    for epoch in time_grid:
+        dt = datetime.fromtimestamp(epoch, tz=timezone.utc)
+        cost_points.append(ApiKeyTrendsPoint(t=dt, v=round(cost_by_bucket.get(epoch, 0.0), 6)))
+        tokens_points.append(ApiKeyTrendsPoint(t=dt, v=float(tokens_by_bucket.get(epoch, 0))))
+
+    return ApiKeyTrendsData(key_id=key_id, cost=cost_points, tokens=tokens_points)