codexLB-up 1.25.0b10__py3-none-any.whl

app/db/models.py

@@ -0,0 +1,3100 @@
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+from enum import Enum
+
+from sqlalchemy import (
+    BigInteger,
+    Boolean,
+    CheckConstraint,
+    DateTime,
+    Float,
+    ForeignKey,
+    Index,
+    Integer,
+    LargeBinary,
+    String,
+    Text,
+    UniqueConstraint,
+    false,
+    func,
+    literal_column,
+    text,
+    true,
+)
+from sqlalchemy import Enum as SqlEnum
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship
+
+from app.core.auth.dashboard_session_ttl import DEFAULT_DASHBOARD_SESSION_TTL_SECONDS
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+def _enum_values(enum_cls: type[Enum]) -> list[str]:
+    return [str(member.value) for member in enum_cls]
+
+
+def new_codex_installation_id() -> str:
+    return str(uuid.uuid4())
+
+
+class AccountStatus(str, Enum):
+    ACTIVE = "active"
+    RATE_LIMITED = "rate_limited"
+    QUOTA_EXCEEDED = "quota_exceeded"
+    PAUSED = "paused"
+    REAUTH_REQUIRED = "reauth_required"
+    DEACTIVATED = "deactivated"
+
+
+class AccountRoutingPolicy(str, Enum):
+    NORMAL = "normal"
+    BURN_FIRST = "burn_first"
+    PRESERVE = "preserve"
+
+
+class StickySessionKind(str, Enum):
+    CODEX_SESSION = "codex_session"
+    STICKY_THREAD = "sticky_thread"
+    PROMPT_CACHE = "prompt_cache"
+
+
+class RequestKind(str, Enum):
+    NORMAL = "normal"
+    WARMUP = "warmup"
+
+
+class FileAccountPin(Base):
+    __tablename__ = "file_account_pins"
+
+    file_id: Mapped[str] = mapped_column(String, primary_key=True)
+    account_id: Mapped[str] = mapped_column(String, nullable=False)
+    expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+
+    __table_args__ = (Index("ix_file_account_pins_expires_at", "expires_at"),)
+
+
+class Account(Base):
+    __tablename__ = "accounts"
+
+    id: Mapped[str] = mapped_column(String, primary_key=True)
+    chatgpt_account_id: Mapped[str | None] = mapped_column(String, nullable=True)
+    # Stable per-seat OpenAI principal identity (chatgpt_user_id / auth sub).
+    # Distinct from chatgpt_account_id, which is the shared Team/Business
+    # WORKSPACE identity. Two seats in one workspace share chatgpt_account_id
+    # but have different chatgpt_user_id. Used to target and verify reauth so
+    # repairing one seat cannot overwrite another seat sharing the workspace.
+    chatgpt_user_id: Mapped[str | None] = mapped_column(String, nullable=True)
+    codex_installation_id: Mapped[str] = mapped_column(
+        String(36),
+        default=new_codex_installation_id,
+        nullable=False,
+    )
+    email: Mapped[str] = mapped_column(String, nullable=False)
+    alias: Mapped[str | None] = mapped_column(String, nullable=True)
+    workspace_id: Mapped[str | None] = mapped_column(String, nullable=True)
+    workspace_label: Mapped[str | None] = mapped_column(String, nullable=True)
+    seat_type: Mapped[str | None] = mapped_column(String, nullable=True)
+    plan_type: Mapped[str] = mapped_column(String, nullable=False)
+    routing_policy: Mapped[str] = mapped_column(
+        String,
+        default="normal",
+        server_default=text("'normal'"),
+        nullable=False,
+    )
+
+    access_token_encrypted: Mapped[bytes] = mapped_column(LargeBinary, nullable=False)
+    refresh_token_encrypted: Mapped[bytes] = mapped_column(LargeBinary, nullable=False)
+    id_token_encrypted: Mapped[bytes] = mapped_column(LargeBinary, nullable=False)
+
+    last_refresh: Mapped[datetime] = mapped_column(DateTime, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), nullable=False)
+
+    status: Mapped[AccountStatus] = mapped_column(
+        SqlEnum(
+            AccountStatus,
+            name="account_status",
+            validate_strings=True,
+            values_callable=_enum_values,
+        ),
+        default=AccountStatus.ACTIVE,
+        nullable=False,
+    )
+    deactivation_reason: Mapped[str | None] = mapped_column(Text, nullable=True)
+    reset_at: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    blocked_at: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    limit_warmup_enabled: Mapped[bool] = mapped_column(
+        Boolean,
+        default=False,
+        server_default=false(),
+        nullable=False,
+    )
+    security_work_authorized: Mapped[bool] = mapped_column(
+        Boolean,
+        default=False,
+        server_default=false(),
+        nullable=False,
+    )
+    # Pending-deletion marker: set by the fast DELETE path, consumed by the
+    # background deletion worker, cleared only by a credential replacement
+    # (re-import/reauth) that supersedes the deletion. Non-NULL rows are
+    # hidden from account listings and are already unroutable (the fast path
+    # also sets status=DEACTIVATED).
+    delete_requested_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    # Frozen at the first delete request (repeat requests do not escalate):
+    # True selects the history-deleting variant in the background worker.
+    delete_history_requested: Mapped[bool] = mapped_column(
+        Boolean,
+        default=False,
+        server_default=false(),
+        nullable=False,
+    )
+
+    api_key_assignments: Mapped[list["ApiKeyAccountAssignment"]] = relationship(
+        "ApiKeyAccountAssignment",
+        back_populates="account",
+        cascade="all, delete-orphan",
+    )
+    request_logs: Mapped[list["RequestLog"]] = relationship(
+        "RequestLog",
+        back_populates="account",
+    )
+    limit_warmups: Mapped[list["AccountLimitWarmup"]] = relationship(
+        "AccountLimitWarmup",
+        back_populates="account",
+        cascade="all, delete-orphan",
+    )
+    proxy_binding: Mapped["AccountProxyBinding | None"] = relationship(
+        "AccountProxyBinding",
+        back_populates="account",
+        cascade="all, delete-orphan",
+        uselist=False,
+    )
+
+
+class UsageHistory(Base):
+    __tablename__ = "usage_history"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    account_id: Mapped[str] = mapped_column(String, ForeignKey("accounts.id", ondelete="CASCADE"), nullable=False)
+    recorded_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), nullable=False)
+    window: Mapped[str | None] = mapped_column(String, nullable=True)
+    used_percent: Mapped[float] = mapped_column(Float, nullable=False)
+    input_tokens: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    output_tokens: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    reset_at: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    window_minutes: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    credits_has: Mapped[bool | None] = mapped_column(Boolean, nullable=True)
+    credits_unlimited: Mapped[bool | None] = mapped_column(Boolean, nullable=True)
+    credits_balance: Mapped[float | None] = mapped_column(Float, nullable=True)
+
+
+class AccountUsageRollup(Base):
+    """Folded lifetime request-usage sums per account.
+
+    Request-log rows older than the fold watermark (the single
+    ``account_usage_rollup_state`` row) are summed here; account usage
+    summaries add a live aggregate over only the newer request-log tail.
+    Sums are stored unclamped; the ``cached_input_tokens <= input_tokens``
+    clamp applies after merging.
+    """
+
+    __tablename__ = "account_usage_rollups"
+
+    account_id: Mapped[str] = mapped_column(String, ForeignKey("accounts.id", ondelete="CASCADE"), primary_key=True)
+    request_count: Mapped[int] = mapped_column(BigInteger, default=0, server_default=text("0"), nullable=False)
+    input_tokens: Mapped[int] = mapped_column(BigInteger, default=0, server_default=text("0"), nullable=False)
+    output_tokens: Mapped[int] = mapped_column(BigInteger, default=0, server_default=text("0"), nullable=False)
+    cached_input_tokens: Mapped[int] = mapped_column(BigInteger, default=0, server_default=text("0"), nullable=False)
+    total_cost_usd: Mapped[float] = mapped_column(Float, default=0.0, server_default=text("0"), nullable=False)
+
+
+class ApiKeyUsageRollup(Base):
+    """Folded lifetime request-usage sums per API key.
+
+    Governed by the same fold watermark as ``AccountUsageRollup`` (the single
+    ``account_usage_rollup_state`` row); sums use the API-key summary
+    semantics (no dedupe, soft-deleted rows included, warmup kinds excluded).
+    Stored unclamped; the ``cached <= input`` clamp applies after merging
+    with the live tail.
+    """
+
+    __tablename__ = "api_key_usage_rollups"
+
+    api_key_id: Mapped[str] = mapped_column(String, ForeignKey("api_keys.id", ondelete="CASCADE"), primary_key=True)
+    request_count: Mapped[int] = mapped_column(BigInteger, default=0, server_default=text("0"), nullable=False)
+    input_tokens: Mapped[int] = mapped_column(BigInteger, default=0, server_default=text("0"), nullable=False)
+    output_tokens: Mapped[int] = mapped_column(BigInteger, default=0, server_default=text("0"), nullable=False)
+    cached_input_tokens: Mapped[int] = mapped_column(BigInteger, default=0, server_default=text("0"), nullable=False)
+    total_cost_usd: Mapped[float] = mapped_column(Float, default=0.0, server_default=text("0"), nullable=False)
+
+
+class AccountUsageRollupState(Base):
+    """Single-row fold watermark (naive-UTC), seeded by the migration.
+
+    Keeping the watermark on a dedicated always-present row gives fold passes
+    something to ``SELECT ... FOR UPDATE`` even before any rollup rows exist,
+    serializing concurrent backfills, and lets reads fetch sums + watermark in
+    one statement (one snapshot).
+    """
+
+    __tablename__ = "account_usage_rollup_state"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=False)
+    folded_through: Mapped[datetime] = mapped_column(DateTime, nullable=False)
+    # Hour-aligned watermark for the time-axis rollups below. Kept as a
+    # SEPARATE column (not shared with `folded_through`) so the hourly
+    # backfill never resets or rewrites the lifetime rollups, which cannot
+    # be recomputed once retention has pruned raw request logs. Invariant:
+    # always a whole UTC hour (epoch % 3600 == 0); rows with
+    # `requested_at < hourly_folded_through` are fully folded, newer rows
+    # are the live tail.
+    hourly_folded_through: Mapped[datetime] = mapped_column(
+        DateTime,
+        nullable=False,
+        server_default=text("'1970-01-01 00:00:00'"),
+    )
+    # Watermark for the conversation presence satellite. Separate from
+    # `hourly_folded_through` (same alignment invariant, same state row and
+    # row lock) so the satellite added later backfills from epoch without
+    # rewinding — and without being gated on — the other time-axis rollups.
+    conversation_folded_through: Mapped[datetime] = mapped_column(
+        DateTime,
+        nullable=False,
+        server_default=text("'1970-01-01 00:00:00'"),
+    )
+    # Start of the hourly range a legacy (pre-cancelled_count) fold pass may
+    # have written after the migration ran (#1552 rolling-upgrade fence).
+    # The migration stamps existing rows with their hourly_folded_through;
+    # the epoch server default covers a state row bootstrapped by an OLD
+    # replica after the migration (its entire backfill is legacy-folded).
+    # Only NEW code writes NULL, after refolding [marker, watermark) from
+    # raw — so NULL always means "no legacy-suspect range outstanding".
+    upgrade_repair_from: Mapped[datetime | None] = mapped_column(
+        DateTime,
+        nullable=True,
+        server_default=text("'1970-01-01 00:00:00'"),
+    )
+
+    reports_folded_through: Mapped[datetime] = mapped_column(
+        DateTime,
+        nullable=False,
+        server_default=text("'1970-01-01 00:00:00'"),
+    )
+
+
+class RequestReportHourlyRollup(Base):
+    """Permanent report measures; conversation remains a dimension for exact distinct counts.
+
+    Hours are assembled into timezone days at read time. Normal traffic only,
+    including detached/deleted accounts, matching the reports contract.
+    """
+
+    __tablename__ = "request_report_hourly_rollups"
+
+    bucket_epoch: Mapped[int] = mapped_column(BigInteger, primary_key=True)
+    account_id: Mapped[str] = mapped_column(String, primary_key=True)
+    api_key_id: Mapped[str] = mapped_column(String, primary_key=True)
+    model: Mapped[str] = mapped_column(String, primary_key=True)
+    useragent_group: Mapped[str] = mapped_column(String, primary_key=True)
+    conversation_id: Mapped[str] = mapped_column(String, primary_key=True)
+    first_requested_at: Mapped[datetime] = mapped_column(DateTime, nullable=False)
+    request_count: Mapped[int] = mapped_column(BigInteger, nullable=False, server_default=text("0"))
+    error_count: Mapped[int] = mapped_column(BigInteger, nullable=False, server_default=text("0"))
+    cancelled_count: Mapped[int] = mapped_column(BigInteger, nullable=False, server_default=text("0"))
+    input_tokens: Mapped[int] = mapped_column(BigInteger, nullable=False, server_default=text("0"))
+    output_tokens: Mapped[int] = mapped_column(BigInteger, nullable=False, server_default=text("0"))
+    reasoning_tokens: Mapped[int] = mapped_column(BigInteger, nullable=False, server_default=text("0"))
+    reasoning_usage_known_requests: Mapped[int] = mapped_column(BigInteger, nullable=False, server_default=text("0"))
+    cached_input_tokens: Mapped[int] = mapped_column(BigInteger, nullable=False, server_default=text("0"))
+    cost_usd: Mapped[float] = mapped_column(Float, nullable=False, server_default=text("0"))
+
+
+class RequestUsageHourlyRollup(Base):
+    """Hour-bucketed request-usage sums (time-axis rollup).
+
+    One row per UTC hour x dimension combination, folded from raw
+    ``request_logs`` below the ``hourly_folded_through`` watermark. Rows are
+    written by the hourly fold pass (DELETE-then-INSERT per slice, so
+    re-folds always converge) and mutated afterwards only by the account
+    lifecycle mirrors (soft/hard delete, consolidation) — never recomputed
+    from raw, so buckets survive request-log retention pruning.
+
+    Nullable raw dimensions (``account_id``/``api_key_id``/``service_tier``)
+    are stored via the collision-free NULL-sentinel encoding
+    (``usage_time_rollup.to_dimension``) so they can participate in the
+    primary key on both dialects (UNIQUE treats NULLs as distinct) without
+    conflating NULL with a legitimate empty string. ``request_kind`` is
+    NOT NULL at the source and stored verbatim (warmup kinds included; reads
+    filter by dimension). No FKs: rollup rows must outlive account deletion.
+    """
+
+    __tablename__ = "request_usage_hourly_rollups"
+
+    bucket_epoch: Mapped[int] = mapped_column(BigInteger, primary_key=True)
+    account_id: Mapped[str] = mapped_column(String, primary_key=True)
+    api_key_id: Mapped[str] = mapped_column(String, primary_key=True)
+    model: Mapped[str] = mapped_column(String, primary_key=True)
+    service_tier: Mapped[str] = mapped_column(String, primary_key=True)
+    request_kind: Mapped[str] = mapped_column(String, primary_key=True)
+    is_deleted: Mapped[bool] = mapped_column(Boolean, primary_key=True, default=False, server_default=false())
+    request_count: Mapped[int] = mapped_column(BigInteger, default=0, server_default=text("0"), nullable=False)
+    # sum(status NOT IN ('success', 'cancelled')) — status is folded as a
+    # measure, not a dimension. Rows folded before cancelled_count existed
+    # keep the legacy sum(status != 'success') fold (no backfill; a disclosed
+    # step change on error-rate trends).
+    error_count: Mapped[int] = mapped_column(BigInteger, default=0, server_default=text("0"), nullable=False)
+    # sum(status = 'cancelled') — client-side disconnect terminals, split out
+    # of error_count so dashboards can show success/cancelled/error distinctly.
+    # 0 (server default) on rows folded before the measure existed.
+    cancelled_count: Mapped[int] = mapped_column(BigInteger, default=0, server_default=text("0"), nullable=False)
+    input_tokens: Mapped[int] = mapped_column(BigInteger, default=0, server_default=text("0"), nullable=False)
+    output_tokens: Mapped[int] = mapped_column(BigInteger, default=0, server_default=text("0"), nullable=False)
+    reasoning_tokens: Mapped[int] = mapped_column(BigInteger, default=0, server_default=text("0"), nullable=False)
+    # sum(coalesce(output_tokens, reasoning_tokens, 0)) — not derivable from
+    # the two sums above (planner / trends / usage-summary semantics).
+    output_or_reasoning_tokens: Mapped[int] = mapped_column(
+        BigInteger, default=0, server_default=text("0"), nullable=False
+    )
+    cached_input_tokens: Mapped[int] = mapped_column(BigInteger, default=0, server_default=text("0"), nullable=False)
+    # sum(max(0, min(coalesce(cached, 0), coalesce(input, 0)))) — pre-folded
+    # for the future usage-summary switch (one-way door once raw is pruned).
+    cached_input_tokens_clamped: Mapped[int] = mapped_column(
+        BigInteger, default=0, server_default=text("0"), nullable=False
+    )
+    cost_usd: Mapped[float] = mapped_column(Float, default=0.0, server_default=text("0"), nullable=False)
+    # count(cost_usd IS NOT NULL) — preserves the "all-NULL model excluded"
+    # rule of cost-by-model aggregations.
+    cost_count: Mapped[int] = mapped_column(BigInteger, default=0, server_default=text("0"), nullable=False)
+
+
+class RequestUsageHourlyErrorRollup(Base):
+    """Hour-bucketed error-code counts (top-error satellite).
+
+    ``error_code`` has unbounded cardinality, so it is isolated from the main
+    hourly rollup. Fold filter reproduces the top-error read exactly:
+    non-warmup kinds, ``status NOT IN ('success', 'cancelled')``,
+    ``error_code IS NOT NULL`` (soft-deleted rows included). Rows folded
+    before cancelled rows left the error fold still carry
+    ``client_disconnected`` counts; the top-error reads exclude that code.
+    ``account_id`` is carried only so account hard-deletion can mirror raw
+    row removal.
+    """
+
+    __tablename__ = "request_usage_hourly_error_rollups"
+
+    bucket_epoch: Mapped[int] = mapped_column(BigInteger, primary_key=True)
+    account_id: Mapped[str] = mapped_column(String, primary_key=True)
+    error_code: Mapped[str] = mapped_column(String, primary_key=True)
+    error_count: Mapped[int] = mapped_column(BigInteger, default=0, server_default=text("0"), nullable=False)
+
+
+class RequestDemandQuarterRollup(Base):
+    """Quarter-hour demand sums for the quota planner (the only sub-hour
+    consumer, ``DEFAULT_SLOT_SECONDS = 900``).
+
+    The FULL legacy demand grain (account, api_key, model, reasoning_effort,
+    request_kind, status) is preserved as dimensions: the planner's
+    ``_bin_demand_units`` applies ``max(token, cost, request units)`` per bin
+    BEFORE summing (nonlinear), so a coarser fold would change forecasts
+    wherever a slot mixes groups with different dominant components. The row
+    count equals what the legacy runtime ``GROUP BY`` returned per query.
+
+    ``is_deleted`` is a dimension (not a fold-time filter) and ``account_id``
+    a carried key so account soft/hard deletion — which retroactively detaches
+    or removes the account's entire raw history — can be mirrored here instead
+    of permanently diverging from the planner's ``deleted_at IS NULL`` view.
+    """
+
+    __tablename__ = "request_demand_quarter_rollups"
+
+    slot_epoch: Mapped[int] = mapped_column(BigInteger, primary_key=True)
+    account_id: Mapped[str] = mapped_column(String, primary_key=True)
+    api_key_id: Mapped[str] = mapped_column(String, primary_key=True)
+    model: Mapped[str] = mapped_column(String, primary_key=True)
+    reasoning_effort: Mapped[str] = mapped_column(String, primary_key=True)
+    request_kind: Mapped[str] = mapped_column(String, primary_key=True)
+    status: Mapped[str] = mapped_column(String, primary_key=True)
+    is_deleted: Mapped[bool] = mapped_column(Boolean, primary_key=True, default=False, server_default=false())
+    request_count: Mapped[int] = mapped_column(BigInteger, default=0, server_default=text("0"), nullable=False)
+    input_tokens: Mapped[int] = mapped_column(BigInteger, default=0, server_default=text("0"), nullable=False)
+    output_or_reasoning_tokens: Mapped[int] = mapped_column(
+        BigInteger, default=0, server_default=text("0"), nullable=False
+    )
+    cached_input_tokens: Mapped[int] = mapped_column(BigInteger, default=0, server_default=text("0"), nullable=False)
+    cost_usd: Mapped[float] = mapped_column(Float, default=0.0, server_default=text("0"), nullable=False)
+
+
+class RequestConversationHourlyRollup(Base):
+    """Hour-bucketed conversation presence (distinct-conversation satellite).
+
+    One row means "this conversation had ``request_count`` countable requests
+    in this UTC hour under this (account, is_deleted) attribution". Distinct
+    conversation counts are not additive across buckets, so the reads UNION
+    the folded ``conversation_id`` values with the raw live tail and count
+    distinct over the merge; ``request_count`` stays additive for the
+    conversation-request totals.
+
+    ``conversation_id`` is the normalized value (whitespace-trimmed,
+    non-empty — NULL/blank rows are excluded by the fold filter, matching
+    every reader). ``is_deleted`` is a dimension because the dashboard
+    conversation reads exclude soft-deleted rows while the reports reads
+    include them; ``account_id`` (NULL-sentinel encoded) is carried only so
+    the account lifecycle mirrors can re-attribute or remove folded presence
+    exactly as the raw mutation does. No FKs: rows must outlive accounts.
+    """
+
+    __tablename__ = "request_conversation_hourly_rollups"
+
+    bucket_epoch: Mapped[int] = mapped_column(BigInteger, primary_key=True)
+    conversation_id: Mapped[str] = mapped_column(String, primary_key=True)
+    account_id: Mapped[str] = mapped_column(String, primary_key=True)
+    is_deleted: Mapped[bool] = mapped_column(Boolean, primary_key=True, default=False, server_default=false())
+    request_count: Mapped[int] = mapped_column(BigInteger, default=0, server_default=text("0"), nullable=False)
+
+
+class AdditionalUsageHistory(Base):
+    __tablename__ = "additional_usage_history"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    account_id: Mapped[str] = mapped_column(String, ForeignKey("accounts.id", ondelete="CASCADE"), nullable=False)
+    quota_key: Mapped[str] = mapped_column(String, nullable=False)
+    limit_name: Mapped[str] = mapped_column(String, nullable=False)
+    metered_feature: Mapped[str] = mapped_column(String, nullable=False)
+    window: Mapped[str] = mapped_column(String, nullable=False)
+    used_percent: Mapped[float] = mapped_column(Float, nullable=False)
+    reset_at: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    window_minutes: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    recorded_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), nullable=False)
+
+
+class RequestLog(Base):
+    __tablename__ = "request_logs"
+    __table_args__ = (
+        Index("idx_logs_useragent_group", "useragent_group"),
+        Index("idx_logs_conversation_id", "conversation_id"),
+        Index("idx_logs_client_ip", "client_ip"),
+    )
+
+    sticky_key_source: Mapped[str | None] = mapped_column(String, nullable=True)
+    sticky_kind: Mapped[str | None] = mapped_column(String, nullable=True)
+    sticky_key_hash: Mapped[str | None] = mapped_column(String, nullable=True)
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    account_id: Mapped[str | None] = mapped_column(
+        String,
+        ForeignKey("accounts.id", ondelete="SET NULL"),
+        nullable=True,
+    )
+    model_source_id: Mapped[str | None] = mapped_column(
+        String,
+        nullable=True,
+    )
+    model_source_kind: Mapped[str | None] = mapped_column(String, nullable=True)
+    api_key_id: Mapped[str | None] = mapped_column(String, nullable=True)
+    session_id: Mapped[str | None] = mapped_column(String, nullable=True)
+    request_id: Mapped[str] = mapped_column(String, nullable=False)
+    archive_request_id: Mapped[str | None] = mapped_column(String, nullable=True)
+    request_kind: Mapped[str] = mapped_column(
+        String,
+        default=RequestKind.NORMAL.value,
+        server_default=text("'normal'"),
+        nullable=False,
+    )
+    connection_request_kind: Mapped[str | None] = mapped_column(String, nullable=True)
+    requested_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), nullable=False)
+    deleted_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    model: Mapped[str] = mapped_column(String, nullable=False)
+    plan_type: Mapped[str | None] = mapped_column(String, nullable=True)
+    source: Mapped[str | None] = mapped_column(String, nullable=True)
+    useragent: Mapped[str | None] = mapped_column(Text, nullable=True)
+    useragent_group: Mapped[str | None] = mapped_column(String, nullable=True)
+    conversation_id: Mapped[str | None] = mapped_column(String, nullable=True)
+    client_ip: Mapped[str | None] = mapped_column(String, nullable=True)
+    transport: Mapped[str | None] = mapped_column(String, nullable=True)
+    service_tier: Mapped[str | None] = mapped_column(String, nullable=True)
+    requested_service_tier: Mapped[str | None] = mapped_column(String, nullable=True)
+    actual_service_tier: Mapped[str | None] = mapped_column(String, nullable=True)
+    input_tokens: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    output_tokens: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    cached_input_tokens: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    reasoning_tokens: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    cost_usd: Mapped[float | None] = mapped_column(Float, nullable=True)
+    reasoning_effort: Mapped[str | None] = mapped_column(String, nullable=True)
+    latency_ms: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    latency_first_token_ms: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    # Pre-attempt wait (account selection, admission waits, failed failover
+    # attempts) — kept out of latency_ms/latency_first_token_ms so those two
+    # always share the successful attempt's anchor.
+    latency_queue_ms: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    latency_response_created_ms: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    latency_first_upstream_event_ms: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    latency_response_create_gate_wait_ms: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    latency_bridge_queue_wait_ms: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    prewarm_status: Mapped[str | None] = mapped_column(String, nullable=True)
+    prewarm_latency_ms: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    session_previous_gap_ms: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    status: Mapped[str] = mapped_column(String, nullable=False)
+    error_code: Mapped[str | None] = mapped_column(String, nullable=True)
+    error_message: Mapped[str | None] = mapped_column(Text, nullable=True)
+    failure_phase: Mapped[str | None] = mapped_column(String, nullable=True)
+    failure_detail: Mapped[str | None] = mapped_column(Text, nullable=True)
+    failure_exception_type: Mapped[str | None] = mapped_column(String, nullable=True)
+    upstream_status_code: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    upstream_error_code: Mapped[str | None] = mapped_column(String, nullable=True)
+    bridge_stage: Mapped[str | None] = mapped_column(String, nullable=True)
+    upstream_proxy_route_mode: Mapped[str | None] = mapped_column(String, nullable=True)
+    upstream_transport: Mapped[str | None] = mapped_column(String, nullable=True)
+    upstream_proxy_pool_id: Mapped[str | None] = mapped_column(String, nullable=True)
+    upstream_proxy_endpoint_id: Mapped[str | None] = mapped_column(String, nullable=True)
+    upstream_proxy_fallback_used: Mapped[bool | None] = mapped_column(Boolean, nullable=True)
+    upstream_proxy_fail_closed_reason: Mapped[str | None] = mapped_column(String, nullable=True)
+    account: Mapped[Account | None] = relationship(
+        "Account",
+        back_populates="request_logs",
+    )
+    model_source: Mapped["ModelSource | None"] = relationship(
+        "ModelSource",
+        back_populates="request_logs",
+        primaryjoin="foreign(RequestLog.model_source_id) == ModelSource.id",
+    )
+
+
+class ProxyEndpoint(Base):
+    __tablename__ = "proxy_endpoints"
+
+    id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    name: Mapped[str] = mapped_column(String, nullable=False)
+    scheme: Mapped[str] = mapped_column(String, nullable=False)
+    host: Mapped[str] = mapped_column(String, nullable=False)
+    port: Mapped[int] = mapped_column(Integer, nullable=False)
+    username: Mapped[str | None] = mapped_column(String, nullable=True)
+    password_encrypted: Mapped[bytes | None] = mapped_column(LargeBinary, nullable=True)
+    is_active: Mapped[bool] = mapped_column(Boolean, default=True, server_default=true(), nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), nullable=False)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime,
+        server_default=func.now(),
+        onupdate=func.now(),
+        nullable=False,
+    )
+
+    pool_memberships: Mapped[list["ProxyPoolMember"]] = relationship(
+        "ProxyPoolMember",
+        back_populates="endpoint",
+        cascade="all, delete-orphan",
+    )
+
+
+class ProxyPool(Base):
+    __tablename__ = "proxy_pools"
+
+    id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    name: Mapped[str] = mapped_column(String, nullable=False)
+    is_active: Mapped[bool] = mapped_column(Boolean, default=True, server_default=true(), nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), nullable=False)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime,
+        server_default=func.now(),
+        onupdate=func.now(),
+        nullable=False,
+    )
+
+    members: Mapped[list["ProxyPoolMember"]] = relationship(
+        "ProxyPoolMember",
+        back_populates="pool",
+        cascade="all, delete-orphan",
+    )
+    account_bindings: Mapped[list["AccountProxyBinding"]] = relationship(
+        "AccountProxyBinding",
+        back_populates="pool",
+    )
+
+
+class ProxyPoolMember(Base):
+    __tablename__ = "proxy_pool_members"
+
+    id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    pool_id: Mapped[str] = mapped_column(String, ForeignKey("proxy_pools.id", ondelete="CASCADE"), nullable=False)
+    endpoint_id: Mapped[str] = mapped_column(
+        String,
+        ForeignKey("proxy_endpoints.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    sort_order: Mapped[int] = mapped_column(Integer, default=0, server_default=text("0"), nullable=False)
+    weight: Mapped[int] = mapped_column(Integer, default=1, server_default=text("1"), nullable=False)
+    is_active: Mapped[bool] = mapped_column(Boolean, default=True, server_default=true(), nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), nullable=False)
+
+    pool: Mapped[ProxyPool] = relationship("ProxyPool", back_populates="members")
+    endpoint: Mapped[ProxyEndpoint] = relationship("ProxyEndpoint", back_populates="pool_memberships")
+
+    __table_args__ = (
+        UniqueConstraint("pool_id", "endpoint_id", name="uq_proxy_pool_members_pool_endpoint"),
+        Index("idx_proxy_pool_members_pool_order", "pool_id", "is_active", "sort_order", "id"),
+    )
+
+
+class AccountProxyBinding(Base):
+    __tablename__ = "account_proxy_bindings"
+
+    id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    account_id: Mapped[str] = mapped_column(String, ForeignKey("accounts.id", ondelete="CASCADE"), nullable=False)
+    pool_id: Mapped[str] = mapped_column(String, ForeignKey("proxy_pools.id", ondelete="RESTRICT"), nullable=False)
+    is_active: Mapped[bool] = mapped_column(Boolean, default=True, server_default=true(), nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), nullable=False)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime,
+        server_default=func.now(),
+        onupdate=func.now(),
+        nullable=False,
+    )
+
+    account: Mapped[Account] = relationship("Account", back_populates="proxy_binding")
+    pool: Mapped[ProxyPool] = relationship("ProxyPool", back_populates="account_bindings")
+
+    __table_args__ = (UniqueConstraint("account_id", name="uq_account_proxy_bindings_account"),)
+
+
+class AccountLimitWarmup(Base):
+    __tablename__ = "account_limit_warmups"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    account_id: Mapped[str] = mapped_column(String, ForeignKey("accounts.id", ondelete="CASCADE"), nullable=False)
+    window: Mapped[str] = mapped_column(String, nullable=False)
+    reset_at: Mapped[int] = mapped_column(Integer, nullable=False)
+    status: Mapped[str] = mapped_column(String, nullable=False)
+    model: Mapped[str] = mapped_column(String, nullable=False)
+    attempted_at: Mapped[datetime] = mapped_column(DateTime, nullable=False)
+    completed_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    error_code: Mapped[str | None] = mapped_column(String, nullable=True)
+    error_message: Mapped[str | None] = mapped_column(Text, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), nullable=False)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime,
+        server_default=func.now(),
+        onupdate=func.now(),
+        nullable=False,
+    )
+
+    account: Mapped[Account] = relationship(
+        "Account",
+        back_populates="limit_warmups",
+    )
+
+    __table_args__ = (
+        UniqueConstraint(
+            "account_id",
+            "window",
+            "reset_at",
+            name="uq_account_limit_warmups_account_window_reset",
+        ),
+    )
+
+
+class AuditLog(Base):
+    """Append-only record of dashboard actions.
+
+    The ``actor_*`` columns are a snapshot of the acting account, not foreign
+    keys: a row must survive the deletion of the account it names. They are all
+    NULL for rows written before attribution existed and for principals without
+    an account row (implicit local admin, trusted header, guest).
+    """
+
+    __tablename__ = "audit_logs"
+    __table_args__ = (
+        Index("idx_audit_logs_actor_user_id", "actor_user_id"),
+        Index("idx_audit_logs_target", "target_type", "target_id"),
+    )
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    timestamp: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=func.now(), nullable=False, index=True)
+    action: Mapped[str] = mapped_column(String(100), nullable=False, index=True)
+    actor_ip: Mapped[str | None] = mapped_column(String(50), nullable=True)
+    details: Mapped[str | None] = mapped_column(Text, nullable=True)
+    request_id: Mapped[str | None] = mapped_column(String(100), nullable=True)
+    actor_user_id: Mapped[str | None] = mapped_column(String(36), nullable=True)
+    actor_username: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    actor_role_slug: Mapped[str | None] = mapped_column(String(32), nullable=True)
+    auth_method: Mapped[str | None] = mapped_column(String(32), nullable=True)
+    target_type: Mapped[str | None] = mapped_column(String(32), nullable=True)
+    target_id: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    severity: Mapped[str] = mapped_column(String(16), nullable=False, server_default=text("'info'"))
+
+
+class SchedulerLeader(Base):
+    __tablename__ = "scheduler_leader"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, default=1)
+    leader_id: Mapped[str] = mapped_column(String(100), nullable=False)
+    acquired_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, index=True)
+
+
+class ResetCreditRedeemRequest(Base):
+    """Durable (account, redeem_request_id) -> credit_id idempotency ledger.
+
+    Written inside the per-account serialized redeem section BEFORE the
+    upstream consume call so a retry carrying the same redeem_request_id —
+    served by ANY replica — resolves to the originally selected credit and
+    never burns a second one. Rows are purged opportunistically after 24h.
+    """
+
+    __tablename__ = "reset_credit_redeem_requests"
+
+    account_id: Mapped[str] = mapped_column(
+        String,
+        ForeignKey("accounts.id", ondelete="CASCADE"),
+        primary_key=True,
+    )
+    redeem_request_id: Mapped[str] = mapped_column(String, primary_key=True)
+    credit_id: Mapped[str] = mapped_column(String, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, index=True)
+
+
+class ResetCreditRedeemClaim(Base):
+    """Cross-process per-account redeem serialization claim for SQLite.
+
+    A single atomic conditional upsert (INSERT ... ON CONFLICT DO UPDATE ...
+    WHERE expires_at < now) under SQLite's single-writer lock gives real
+    multi-process mutual exclusion; the lease expiry recovers crashed holders.
+    PostgreSQL deployments keep using pg_advisory_xact_lock instead.
+    """
+
+    __tablename__ = "reset_credit_redeem_claims"
+
+    account_id: Mapped[str] = mapped_column(
+        String,
+        ForeignKey("accounts.id", ondelete="CASCADE"),
+        primary_key=True,
+    )
+    holder_id: Mapped[str] = mapped_column(String(100), nullable=False)
+    expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+
+
+class OAuthFlowState(Base):
+    """Durable dashboard OAuth add-account / reauth flow state.
+
+    The dashboard OAuth flow (PKCE `code_verifier`, `state` token, device-code
+    poll metadata, and status) is persisted here keyed by `flow_id` so that any
+    replica behind a load balancer can complete a flow it did not start: the
+    browser callback, a manually pasted callback URL, or a device-code status
+    poll can land on a different replica than the one that ran `start`. The
+    `code_verifier` is stored encrypted with the same key material as account
+    tokens. Abandoned pending flows expire via `expires_at` and are purged
+    opportunistically on write.
+    """
+
+    __tablename__ = "oauth_flow_states"
+
+    flow_id: Mapped[str] = mapped_column(String, primary_key=True)
+    state_token: Mapped[str | None] = mapped_column(String, nullable=True, unique=True, index=True)
+    method: Mapped[str] = mapped_column(String, nullable=False)
+    status: Mapped[str] = mapped_column(String, nullable=False)
+    error_message: Mapped[str | None] = mapped_column(Text, nullable=True)
+    intended_account_id: Mapped[str | None] = mapped_column(String, nullable=True)
+    code_verifier_encrypted: Mapped[bytes | None] = mapped_column(LargeBinary, nullable=True)
+    device_auth_id: Mapped[str | None] = mapped_column(String, nullable=True)
+    user_code: Mapped[str | None] = mapped_column(String, nullable=True)
+    interval_seconds: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    expires_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, index=True)
+    finished_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+
+
+class OAuthDeviceFlowSlot(Base):
+    """Single-active-device-flow coordination slot (cross-replica).
+
+    At most one dashboard device-code OAuth flow is "current" at a time. A
+    device ``start`` atomically REPLACES the slot via a single conditional
+    UPSERT on the fixed ``slot_key``, so two replicas starting device OAuth
+    simultaneously leave exactly one current ``flow_id`` instead of two orphaned
+    pending rows that both believe they are current. A poller atomically
+    CONSUMES the slot (delete-if-mine) as its point of no return immediately
+    before persisting tokens: a poller whose flow was superseded (the slot now
+    names a different ``flow_id``) loses the consume and MUST abort without
+    adding or re-authenticating an account. ``generation`` is a monotonic claim
+    token bumped on every replacement, retained for observability.
+    """
+
+    __tablename__ = "oauth_device_flow_slots"
+
+    slot_key: Mapped[str] = mapped_column(String, primary_key=True)
+    flow_id: Mapped[str] = mapped_column(String, nullable=False)
+    generation: Mapped[int] = mapped_column(Integer, nullable=False)
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+
+
+class StickySession(Base):
+    __tablename__ = "sticky_sessions"
+
+    key: Mapped[str] = mapped_column(String, primary_key=True)
+    kind: Mapped[StickySessionKind] = mapped_column(
+        SqlEnum(
+            StickySessionKind,
+            name="sticky_session_kind",
+            validate_strings=True,
+            values_callable=_enum_values,
+        ),
+        primary_key=True,
+        default=StickySessionKind.STICKY_THREAD,
+        server_default=text("'sticky_thread'"),
+        nullable=False,
+    )
+    account_id: Mapped[str] = mapped_column(String, ForeignKey("accounts.id", ondelete="CASCADE"), nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), nullable=False)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime,
+        server_default=func.now(),
+        onupdate=func.now(),
+        nullable=False,
+    )
+    # A non-null timestamp with NULL scope is the historical global tombstone.
+    # Source-scoped abandonment instead leaves this timestamp NULL and stores
+    # the typed scope below. That asymmetry is intentional: binaries predating
+    # the scope column see a live hard owner during rollout/rollback, while new
+    # binaries can let a process-session restart ignore the ambiguous raw row
+    # without erasing its explicit-turn-state ownership. Stale-hard cleanup
+    # may later promote the scoped marker to a timestamped global tombstone.
+    continuity_abandoned_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True, default=None)
+    continuity_abandonment_scope: Mapped[str | None] = mapped_column(String(32), nullable=True, default=None)
+
+
+class CapabilityLineageMarker(Base):
+    __tablename__ = "capability_lineage_markers"
+
+    marker_hash: Mapped[str] = mapped_column(String(64), primary_key=True)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        nullable=False,
+    )
+    last_seen_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        onupdate=func.now(),
+        nullable=False,
+    )
+
+
+class DashboardUserStatus(str, Enum):
+    ACTIVE = "active"
+    DISABLED = "disabled"
+    INVITED = "invited"
+
+
+class DashboardUserRoleSource(str, Enum):
+    MANUAL = "manual"
+    MAPPING = "mapping"
+    SCIM = "scim"
+
+
+class ApiKeyDeactivatedReason(str, Enum):
+    MANUAL = "manual"
+    OWNER_DISABLED = "owner_disabled"
+    EXPIRED = "expired"
+
+
+class AuthProviderKind(str, Enum):
+    PASSWORD = "password"
+    TRUSTED_HEADER = "trusted_header"
+    OIDC = "oidc"
+
+
+class LocalLoginPolicy(str, Enum):
+    """Who may still sign in with a local password (PLAN §4.6, DB only).
+
+    ``ENABLED`` is today's behaviour and the default: every active account that
+    holds a password may sign in. The two tightened values are the switch a
+    company throws once its people arrive through a sign-in provider; both are
+    guarded by the qualifying break-glass invariant so the switch can never be
+    a lockout.
+    """
+
+    ENABLED = "enabled"
+    ADMINS_ONLY = "admins_only"
+    BREAK_GLASS_ONLY = "break_glass_only"
+
+
+#: Name the install's first (break-glass) account is created under, and the one
+#: name no other account may take. It is a reservation of the *name*: the
+#: account itself may be renamed, so nothing may identify it by this string.
+COMPAT_ADMIN_USERNAME = "admin"
+
+#: Deterministic id of that account, so the migration and the runtime bootstrap
+#: path create the same row, re-runs stay idempotent, and every path that has to
+#: find the bootstrapped account after a rename has a stable handle.
+COMPAT_ADMIN_USER_ID = str(
+    uuid.uuid5(uuid.UUID("6f1c0e4e-2b4a-4c1e-9c3b-7a5d2e8f0a11"), "codex-lb:dashboard-user:compat-admin")
+)
+
+
+class DashboardUser(Base):
+    """A person (or service) who signs in to the dashboard.
+
+    ``status``/``role_source`` are plain strings validated by the enums above
+    (no database enum type, so adding values needs no type migration). The
+    ``role_id`` foreign key is RESTRICT: a role in use cannot be deleted.
+    """
+
+    __tablename__ = "dashboard_users"
+
+    id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    username: Mapped[str] = mapped_column(String(64), unique=True, nullable=False)
+    display_name: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    email: Mapped[str | None] = mapped_column(String(320), unique=True, nullable=True)
+    role_id: Mapped[str] = mapped_column(
+        String,
+        ForeignKey("dashboard_roles.id", ondelete="RESTRICT"),
+        nullable=False,
+    )
+    role_source: Mapped[str] = mapped_column(
+        String(16),
+        default=DashboardUserRoleSource.MANUAL.value,
+        server_default=text("'manual'"),
+        nullable=False,
+    )
+    status: Mapped[str] = mapped_column(
+        String(16),
+        default=DashboardUserStatus.ACTIVE.value,
+        server_default=text("'active'"),
+        nullable=False,
+    )
+    password_hash: Mapped[str | None] = mapped_column(Text, nullable=True)
+    totp_secret_encrypted: Mapped[bytes | None] = mapped_column(LargeBinary, nullable=True)
+    totp_last_verified_step: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    session_generation: Mapped[int] = mapped_column(Integer, default=0, server_default=text("0"), nullable=False)
+    must_change_password: Mapped[bool] = mapped_column(Boolean, default=False, server_default=false(), nullable=False)
+    is_break_glass: Mapped[bool] = mapped_column(Boolean, default=False, server_default=false(), nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), nullable=False)
+    created_by_user_id: Mapped[str | None] = mapped_column(
+        String,
+        ForeignKey("dashboard_users.id", ondelete="SET NULL"),
+        nullable=True,
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime, server_default=func.now(), onupdate=func.now(), nullable=False
+    )
+    last_login_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+
+    role: Mapped["DashboardRoleRecord"] = relationship("DashboardRoleRecord")
+    identities: Mapped[list["DashboardIdentity"]] = relationship(
+        "DashboardIdentity",
+        back_populates="user",
+        cascade="all, delete-orphan",
+        passive_deletes=True,
+    )
+
+
+class DashboardIdentity(Base):
+    """An external identity (reverse-proxy header, OIDC, SCIM) linked to a user.
+
+    One user may hold several identities from several providers; the
+    ``(provider, provider_key, subject)`` triple is unique.
+    """
+
+    __tablename__ = "dashboard_identities"
+    __table_args__ = (
+        UniqueConstraint("provider", "provider_key", "subject", name="uq_dashboard_identities_subject"),
+        Index("idx_dashboard_identities_user_id", "user_id"),
+    )
+
+    id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    user_id: Mapped[str] = mapped_column(
+        String,
+        ForeignKey("dashboard_users.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    provider: Mapped[str] = mapped_column(String(32), nullable=False)
+    provider_key: Mapped[str] = mapped_column(String(128), nullable=False)
+    subject: Mapped[str] = mapped_column(String(512), nullable=False)
+    email: Mapped[str | None] = mapped_column(String(320), nullable=True)
+    display_name: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    groups_json: Mapped[str | None] = mapped_column(Text, nullable=True)
+    #: What the provider calls this person, as pushed and unslugified. Only the
+    #: SCIM path writes it, because only SCIM has to answer a filter on the
+    #: provider's own spelling: our usernames have no ``@``, so an address can
+    #: never equal one and an identity provider reconciling its own resources
+    #: would otherwise match nothing it created.
+    user_name: Mapped[str | None] = mapped_column(String(256), nullable=True)
+    last_seen_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), nullable=False)
+
+    user: Mapped["DashboardUser"] = relationship("DashboardUser", back_populates="identities")
+
+
+class DashboardUserInvite(Base):
+    """A one-time invitation link for a pre-created (``status=invited``) account.
+
+    Only the SHA-256 of the token is stored; the plaintext is returned once when
+    the invite is issued or resent. A user holds at most one invite row
+    (resending rotates the token in place). Revoking or lazily expiring the
+    invite of an ``invited`` account deletes the account row with it, so no
+    orphan "invited" accounts remain. ``created_by_user_id`` is a snapshot, not
+    a foreign key: the invite must survive the inviter's deletion.
+    """
+
+    __tablename__ = "dashboard_user_invites"
+    __table_args__ = (
+        # One open invite per expected identity: two pre-created accounts must not wait for the same person.
+        Index(
+            "uq_dashboard_user_invites_expected_identity",
+            "expected_provider",
+            "expected_provider_key",
+            "expected_subject",
+            unique=True,
+            postgresql_where=text("consumed_at IS NULL AND revoked_at IS NULL"),
+            sqlite_where=text("consumed_at IS NULL AND revoked_at IS NULL"),
+        ),
+    )
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
+    user_id: Mapped[str] = mapped_column(
+        String,
+        ForeignKey("dashboard_users.id", ondelete="CASCADE"),
+        unique=True,
+        nullable=False,
+    )
+    token_hash: Mapped[bytes] = mapped_column(LargeBinary, unique=True, nullable=False)
+    expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    consumed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    revoked_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    created_by_user_id: Mapped[str] = mapped_column(String(36), nullable=False)
+    sso_only: Mapped[bool] = mapped_column(Boolean, default=False, server_default=false(), nullable=False)
+    username_locked: Mapped[bool] = mapped_column(Boolean, default=False, server_default=false(), nullable=False)
+    #: The external identity this pre-created account waits for; the identity
+    #: resolver links it (and activates the account) on an exact triple match.
+    expected_provider: Mapped[str | None] = mapped_column(String(32), nullable=True)
+    expected_provider_key: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    expected_subject: Mapped[str | None] = mapped_column(String(512), nullable=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+
+    user: Mapped["DashboardUser"] = relationship("DashboardUser")
+
+
+class DashboardAuthProvider(Base):
+    """One way of signing in to the dashboard (password, trusted header, later OIDC).
+
+    Rows carry the settings the identity resolver reads: which role an unknown
+    identity gets (``NULL`` = refuse), where a mapped user without a matching
+    mapping lands, whether e-mail linking is allowed, and whether the IdP is
+    trusted for MFA. The password and trusted-header providers have one row
+    each (``provider_key`` ``default``). ``enabled`` is not a copy of the auth
+    mode: a provider is *active* when its row is enabled and the mode allows
+    it. ``config_encrypted`` holds provider secrets (OIDC) and is never returned
+    in clear.
+    """
+
+    __tablename__ = "dashboard_auth_providers"
+    __table_args__ = (UniqueConstraint("kind", "provider_key", name="uq_dashboard_auth_providers_kind_key"),)
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
+    kind: Mapped[str] = mapped_column(String(32), nullable=False)
+    provider_key: Mapped[str] = mapped_column(String(64), nullable=False)
+    enabled: Mapped[bool] = mapped_column(Boolean, default=True, server_default=true(), nullable=False)
+    label: Mapped[str] = mapped_column(String(64), nullable=False)
+    config_encrypted: Mapped[bytes | None] = mapped_column(LargeBinary, nullable=True)
+    unknown_identity_role_id: Mapped[str | None] = mapped_column(
+        String(36),
+        ForeignKey("dashboard_roles.id", ondelete="SET NULL"),
+        nullable=True,
+    )
+    no_match_role_id: Mapped[str | None] = mapped_column(
+        String(36),
+        ForeignKey("dashboard_roles.id", ondelete="SET NULL"),
+        nullable=True,
+    )
+    link_by_email: Mapped[bool] = mapped_column(Boolean, default=False, server_default=false(), nullable=False)
+    skip_role_sync: Mapped[bool] = mapped_column(Boolean, default=False, server_default=false(), nullable=False)
+    idp_mfa_enforced: Mapped[bool] = mapped_column(Boolean, default=False, server_default=false(), nullable=False)
+    #: Proof that the acting admin's own browser completed a round trip through
+    #: this exact configuration. Enabling a redirect-style provider requires one
+    #: no older than ten minutes; freshness is computed on read, never stored as
+    #: a deadline, and a connection-field write clears it.
+    test_login_user_id: Mapped[str | None] = mapped_column(
+        String(36),
+        ForeignKey("dashboard_users.id", ondelete="SET NULL"),
+        nullable=True,
+    )
+    test_login_verified_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), onupdate=func.now(), nullable=False
+    )
+
+
+class DashboardOidcLoginFlow(Base):
+    """One in-flight OIDC round trip, held where every replica can see it.
+
+    The callback routinely lands on a replica that did not serve the start, so
+    the flow cannot live in process memory. Neither the ``state`` nor the
+    ``nonce`` is stored in clear: the ``state`` arrives in the callback URL and
+    the ``nonce`` arrives inside the ID token, so both can be hashed and
+    compared, and a copy that is never needed in clear is only a liability. The
+    row is consumed by one conditional ``DELETE``, which is what makes a state
+    single-use across the fleet.
+    """
+
+    __tablename__ = "dashboard_oidc_login_flows"
+    __table_args__ = (Index("idx_dashboard_oidc_login_flows_expires_at", "expires_at"),)
+
+    state_hash: Mapped[str] = mapped_column(String(64), primary_key=True)
+    provider_id: Mapped[str] = mapped_column(
+        String(36),
+        ForeignKey("dashboard_auth_providers.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    nonce_hash: Mapped[str] = mapped_column(String(64), nullable=False)
+    code_verifier_encrypted: Mapped[bytes] = mapped_column(LargeBinary, nullable=False)
+    #: ``login``, ``test`` or ``step_up``; it decides where the browser lands,
+    #: which is why no destination is ever accepted from the caller.
+    purpose: Mapped[str] = mapped_column(String(16), nullable=False)
+    acting_user_id: Mapped[str | None] = mapped_column(
+        String(36),
+        ForeignKey("dashboard_users.id", ondelete="CASCADE"),
+        nullable=True,
+    )
+    #: The redirect URI exactly as sent, so the token exchange repeats it
+    #: byte-identically even if the configuration changes mid-flow.
+    redirect_uri: Mapped[str] = mapped_column(String(512), nullable=False)
+    #: A digest of the connection document this flow was started against. A
+    #: pre-flight proves *a configuration*, so the stamp it leaves must name the
+    #: one it actually reached: without this a configuration write that commits
+    #: while the callback is exchanging its code would be handed the proof that
+    #: the previous issuer worked.
+    config_fingerprint: Mapped[str] = mapped_column(String(64), nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+
+
+class DashboardScimToken(Base):
+    """A bearer credential that may reach ``/scim/v2`` and nothing else.
+
+    Only the SHA-256 digest of the secret is stored, in a unique index, so the
+    lookup is an index equality and no copy of the credential exists after it
+    is issued; ``token_prefix`` is the non-secret head of the value, kept in
+    clear so an operator can tell two tokens apart. Rotation replaces the
+    digest and the prefix on the same row, so the id, the label and the sync
+    history survive and the previous secret stops working the moment the write
+    commits. ``provider_key`` is the identity namespace the token writes and
+    reads: it comes from this row on every request and never from the caller.
+    """
+
+    __tablename__ = "dashboard_scim_tokens"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
+    label: Mapped[str] = mapped_column(String(64), nullable=False)
+    token_hash: Mapped[str] = mapped_column(String(64), unique=True, nullable=False)
+    token_prefix: Mapped[str] = mapped_column(String(32), nullable=False)
+    provider_key: Mapped[str] = mapped_column(String(128), nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+    #: A snapshot link, cleared rather than cascaded: revoking a token is an
+    #: act of its own and must not be a side effect of deleting its issuer.
+    created_by_user_id: Mapped[str | None] = mapped_column(
+        String(36),
+        ForeignKey("dashboard_users.id", ondelete="SET NULL"),
+        nullable=True,
+    )
+    last_used_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    rotated_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+
+
+class DashboardRoleMappingClaim(str, Enum):
+    """Which fact about an identity a rule matches on.
+
+    A plain string column validated here, not a database enum: a later claim
+    (an OIDC claim name, a SCIM attribute) must not need a type migration.
+    """
+
+    GROUPS = "groups"
+    EMAIL_DOMAIN = "email_domain"
+
+
+class DashboardRoleMapping(Base):
+    """One "identities like this get that role" rule of a sign-in provider.
+
+    Rules are evaluated in descending ``priority`` and the first match wins;
+    ``UNIQUE(provider, provider_key, priority)`` makes a tie impossible and the
+    order server-owned (the rows of one provider are always the contiguous
+    integers ``N..1``). ``role_id`` is RESTRICT: a role a rule hands out cannot
+    be deleted while the rule exists.
+    """
+
+    __tablename__ = "dashboard_role_mappings"
+    __table_args__ = (
+        UniqueConstraint("provider", "provider_key", "priority", name="uq_dashboard_role_mappings_priority"),
+        Index("idx_dashboard_role_mappings_provider", "provider", "provider_key"),
+    )
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
+    provider: Mapped[str] = mapped_column(String(32), nullable=False)
+    provider_key: Mapped[str] = mapped_column(String(64), nullable=False)
+    claim_name: Mapped[str] = mapped_column(String(32), nullable=False)
+    #: Normalized (trimmed, case-folded; an ``email_domain`` value carries no leading ``@``).
+    claim_value: Mapped[str] = mapped_column(String(320), nullable=False)
+    role_id: Mapped[str] = mapped_column(
+        String(36),
+        ForeignKey("dashboard_roles.id", ondelete="RESTRICT"),
+        nullable=False,
+    )
+    priority: Mapped[int] = mapped_column(Integer, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), onupdate=func.now(), nullable=False
+    )
+
+
+class DashboardRoleRecord(Base):
+    """A dashboard role: one of the five presets or an operator-defined custom role.
+
+    Preset rows exist so users, invites, mappings and policies can reference a
+    role by foreign key and so listings have one source; their grants are the
+    code table ``PRESET_ROLE_GRANTS`` and are never stored. Only custom roles
+    carry ``dashboard_role_grants`` rows. ``kind`` is a plain string validated
+    by the application (adding a value must not need a database type change).
+    """
+
+    __tablename__ = "dashboard_roles"
+
+    id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    slug: Mapped[str] = mapped_column(String(32), unique=True, nullable=False)
+    name: Mapped[str] = mapped_column(String(64), nullable=False)
+    description: Mapped[str | None] = mapped_column(Text, nullable=True)
+    kind: Mapped[str] = mapped_column(String(16), nullable=False)
+    assignable_to_users: Mapped[bool] = mapped_column(Boolean, default=True, server_default=true(), nullable=False)
+    cloned_from_role_id: Mapped[str | None] = mapped_column(
+        String,
+        ForeignKey("dashboard_roles.id", ondelete="SET NULL"),
+        nullable=True,
+    )
+    permissions_version: Mapped[int] = mapped_column(Integer, default=1, server_default=text("1"), nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), nullable=False)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime, server_default=func.now(), onupdate=func.now(), nullable=False
+    )
+
+    grants: Mapped[list["DashboardRoleGrant"]] = relationship(
+        "DashboardRoleGrant",
+        back_populates="role",
+        cascade="all, delete-orphan",
+        passive_deletes=True,
+    )
+
+
+class DashboardRoleGrant(Base):
+    """One (permission, scope) grant of a custom dashboard role."""
+
+    __tablename__ = "dashboard_role_grants"
+
+    role_id: Mapped[str] = mapped_column(
+        String,
+        ForeignKey("dashboard_roles.id", ondelete="CASCADE"),
+        primary_key=True,
+    )
+    permission: Mapped[str] = mapped_column(String(64), primary_key=True)
+    scope: Mapped[str] = mapped_column(String(8), nullable=False)
+
+    role: Mapped["DashboardRoleRecord"] = relationship("DashboardRoleRecord", back_populates="grants")
+
+
+class DashboardSettings(Base):
+    __tablename__ = "dashboard_settings"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=False)
+    sticky_threads_enabled: Mapped[bool] = mapped_column(Boolean, default=True, server_default=true(), nullable=False)
+    upstream_stream_transport: Mapped[str] = mapped_column(
+        String,
+        default="auto",
+        server_default=text("'auto'"),
+        nullable=False,
+    )
+    prohibit_fast_mode: Mapped[bool] = mapped_column(
+        Boolean,
+        default=False,
+        server_default=false(),
+        nullable=False,
+    )
+    http_downstream_transport_policy: Mapped[str] = mapped_column(
+        String,
+        default="smart",
+        server_default=text("'smart'"),
+        nullable=False,
+    )
+    # T3, tri-state: NULL inherits the environment value and then the ``shared``
+    # code default. Never seeded from the environment (configuration-tiers,
+    # "Environment values are fallbacks, never seeds").
+    thread_cache_identity_mode: Mapped[str | None] = mapped_column(String, nullable=True)
+    proxy_account_response_create_limit: Mapped[int | None] = mapped_column(
+        Integer,
+        nullable=True,
+    )
+    proxy_account_stream_limit: Mapped[int | None] = mapped_column(
+        Integer,
+        nullable=True,
+    )
+    proxy_account_stream_recovery_reserve: Mapped[int | None] = mapped_column(
+        Integer,
+        nullable=True,
+    )
+    proxy_api_key_fair_share_congestion_threshold_pct: Mapped[int | None] = mapped_column(
+        Integer,
+        nullable=True,
+    )
+    # C2-1 timeouts: dashboard-managed upstream timeouts and request budgets.
+    # NULL = inherit the ``Settings`` field (environment value or code default).
+    upstream_connect_timeout_seconds: Mapped[float | None] = mapped_column(Float, nullable=True)
+    proxy_request_budget_seconds: Mapped[float | None] = mapped_column(Float, nullable=True)
+    compact_request_budget_seconds: Mapped[float | None] = mapped_column(Float, nullable=True)
+    transcription_request_budget_seconds: Mapped[float | None] = mapped_column(Float, nullable=True)
+    stream_idle_timeout_seconds: Mapped[float | None] = mapped_column(Float, nullable=True)
+    proxy_downstream_websocket_idle_timeout_seconds: Mapped[float | None] = mapped_column(Float, nullable=True)
+    sse_keepalive_interval_seconds: Mapped[float | None] = mapped_column(Float, nullable=True)
+    # end C2-1 timeouts
+    # M1 stream/bridge budgets: dashboard-managed Responses stream and HTTP
+    # session bridge request budgets. NULL = inherit the ``Settings`` field.
+    http_responses_stream_request_budget_seconds: Mapped[float | None] = mapped_column(Float, nullable=True)
+    http_responses_session_bridge_request_budget_seconds: Mapped[float | None] = mapped_column(Float, nullable=True)
+    # end M1 stream/bridge budgets
+    # C2-2 routing/overload: dashboard-managed routing weights and overload
+    # isolation. NULL inherits the process environment value (or the code
+    # default) at read time; a non-NULL value wins over the environment.
+    proxy_overload_isolation_seconds: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    proxy_account_error_rate_weighting_enabled: Mapped[bool | None] = mapped_column(Boolean, nullable=True)
+    proxy_account_inflight_penalty_pct: Mapped[float | None] = mapped_column(Float, nullable=True)
+    proxy_account_lease_token_weight: Mapped[float | None] = mapped_column(Float, nullable=True)
+    proxy_account_lease_ttl_seconds: Mapped[float | None] = mapped_column(Float, nullable=True)
+    # end C2-2 routing/overload
+    prefer_earlier_reset_accounts: Mapped[bool] = mapped_column(
+        Boolean, default=True, server_default=true(), nullable=False
+    )
+    prefer_earlier_reset_window: Mapped[str] = mapped_column(
+        String,
+        default="secondary",
+        server_default=text("'secondary'"),
+        nullable=False,
+    )
+    show_reset_credit_badges: Mapped[bool] = mapped_column(
+        Boolean,
+        default=True,
+        server_default=true(),
+        nullable=False,
+    )
+    auto_redeem_reset_credits_before_expiry: Mapped[bool] = mapped_column(
+        Boolean,
+        default=False,
+        server_default=false(),
+        nullable=False,
+    )
+    show_reset_credit_expiry_badge: Mapped[bool] = mapped_column(
+        Boolean,
+        default=True,
+        server_default=true(),
+        nullable=False,
+    )
+    routing_strategy: Mapped[str] = mapped_column(
+        String,
+        default="capacity_weighted",
+        server_default=text("'capacity_weighted'"),
+        nullable=False,
+    )
+    relative_availability_power: Mapped[float] = mapped_column(
+        Float,
+        default=2.0,
+        server_default=text("2.0"),
+        nullable=False,
+    )
+    relative_availability_top_k: Mapped[int] = mapped_column(
+        Integer,
+        default=5,
+        server_default=text("5"),
+        nullable=False,
+    )
+    single_account_id: Mapped[str | None] = mapped_column(String, nullable=True)
+    # Subscription-exhaustion overflow designation (#2123). No foreign key on
+    # purpose: a dangling id means "off", mirroring single_account_id. The drain
+    # deadline is armed when the designation is cleared and compared against
+    # utcnow() (naive UTC) like every other dashboard_settings timestamp.
+    openai_cache_affinity_max_age_seconds: Mapped[int] = mapped_column(
+        Integer,
+        default=1800,
+        server_default=text("1800"),
+        nullable=False,
+    )
+    dashboard_session_ttl_seconds: Mapped[int] = mapped_column(
+        Integer,
+        default=DEFAULT_DASHBOARD_SESSION_TTL_SECONDS,
+        server_default=text(str(DEFAULT_DASHBOARD_SESSION_TTL_SECONDS)),
+        nullable=False,
+    )
+    import_without_overwrite: Mapped[bool] = mapped_column(
+        Boolean,
+        default=True,
+        server_default=true(),
+        nullable=False,
+    )
+    totp_required_on_login: Mapped[bool] = mapped_column(
+        Boolean,
+        default=False,
+        nullable=False,
+    )
+    # D9: TOTP required for admin-level accounts only (admin preset or a custom
+    # role holding a privileged permission); independent of the global toggle.
+    totp_required_for_admin_role: Mapped[bool] = mapped_column(
+        Boolean,
+        default=False,
+        server_default=false(),
+        nullable=False,
+    )
+    # PLAN §4.6: who may still use the local password form. Deliberately has no
+    # environment variable -- a redeploy must not silently re-open local
+    # sign-in a company closed. Tightening it is gated on a qualifying
+    # break-glass account; the host CLI is the way back.
+    local_login_policy: Mapped[str] = mapped_column(
+        String(32),
+        default=LocalLoginPolicy.ENABLED.value,
+        server_default=text(f"'{LocalLoginPolicy.ENABLED.value}'"),
+        nullable=False,
+    )
+    guest_access_enabled: Mapped[bool] = mapped_column(
+        Boolean,
+        default=False,
+        server_default=false(),
+        nullable=False,
+    )
+    guest_password_hash: Mapped[str | None] = mapped_column(Text, nullable=True)
+    # Bumped whenever guest credentials or guest access change so every
+    # outstanding guest session cookie (which carries the generation it was
+    # issued under) stops validating. Sessions are stateless Fernet cookies, so
+    # this counter is the only server-side revocation handle for guests.
+    guest_session_generation: Mapped[int] = mapped_column(
+        Integer,
+        default=0,
+        server_default=text("0"),
+        nullable=False,
+    )
+    bootstrap_token_encrypted: Mapped[bytes | None] = mapped_column(LargeBinary, nullable=True)
+    bootstrap_token_hash: Mapped[bytes | None] = mapped_column(LargeBinary, nullable=True)
+    api_key_auth_enabled: Mapped[bool] = mapped_column(
+        Boolean,
+        default=False,
+        nullable=False,
+    )
+    hide_upstream_quota_from_api_keys: Mapped[bool] = mapped_column(
+        Boolean,
+        default=False,
+        server_default=false(),
+        nullable=False,
+    )
+    telemetry_consent: Mapped[str] = mapped_column(
+        String(16),
+        default="undecided",
+        server_default=text("'undecided'"),
+        nullable=False,
+    )
+    telemetry_instance_id: Mapped[str | None] = mapped_column(String(36), nullable=True)
+    telemetry_private_key_encrypted: Mapped[bytes | None] = mapped_column(LargeBinary, nullable=True)
+    http_responses_session_bridge_prompt_cache_idle_ttl_seconds: Mapped[int] = mapped_column(
+        Integer,
+        default=3600,
+        server_default=text("3600"),
+        nullable=False,
+    )
+    http_responses_session_bridge_gateway_safe_mode: Mapped[bool] = mapped_column(
+        Boolean,
+        default=False,
+        server_default=false(),
+        nullable=False,
+    )
+    # M3 codex prewarm: dashboard-managed Codex HTTP-bridge session prewarm.
+    # NULL inherits the deprecated ``CODEX_LB_*`` env alias (then the code
+    # default, off); a non-NULL value is dashboard-owned.
+    http_responses_session_bridge_codex_prewarm_enabled: Mapped[bool | None] = mapped_column(Boolean, nullable=True)
+    # end M3 codex prewarm
+    upstream_proxy_routing_enabled: Mapped[bool] = mapped_column(
+        Boolean,
+        default=False,
+        server_default=false(),
+        nullable=False,
+    )
+    upstream_proxy_default_pool_id: Mapped[str | None] = mapped_column(
+        String,
+        ForeignKey("proxy_pools.id", ondelete="SET NULL"),
+        nullable=True,
+    )
+    sticky_reallocation_budget_threshold_pct: Mapped[float] = mapped_column(
+        Float,
+        default=95.0,
+        server_default=text("95.0"),
+        nullable=False,
+    )
+    sticky_reallocation_primary_budget_threshold_pct: Mapped[float] = mapped_column(
+        Float,
+        default=95.0,
+        server_default=text("95.0"),
+        nullable=False,
+    )
+    sticky_reallocation_secondary_budget_threshold_pct: Mapped[float] = mapped_column(
+        Float,
+        default=100.0,
+        server_default=text("100.0"),
+        nullable=False,
+    )
+    additional_quota_routing_policies_json: Mapped[str] = mapped_column(
+        Text,
+        default="{}",
+        server_default=text("'{}'"),
+        nullable=False,
+    )
+    limit_warmup_enabled: Mapped[bool] = mapped_column(
+        Boolean,
+        default=False,
+        server_default=false(),
+        nullable=False,
+    )
+    limit_warmup_windows: Mapped[str] = mapped_column(
+        String,
+        default="both",
+        server_default=text("'both'"),
+        nullable=False,
+    )
+    limit_warmup_model: Mapped[str] = mapped_column(
+        String,
+        default="auto",
+        server_default=text("'auto'"),
+        nullable=False,
+    )
+    limit_warmup_prompt: Mapped[str] = mapped_column(
+        Text,
+        default="Say OK.",
+        server_default=text("'Say OK.'"),
+        nullable=False,
+    )
+    limit_warmup_cooldown_seconds: Mapped[int] = mapped_column(
+        Integer,
+        default=3600,
+        server_default=text("3600"),
+        nullable=False,
+    )
+    limit_warmup_exhausted_threshold_percent: Mapped[float] = mapped_column(
+        Float,
+        default=99.0,
+        server_default=text("99.0"),
+        nullable=False,
+    )
+    limit_warmup_idle_threshold_percent: Mapped[float] = mapped_column(
+        Float,
+        default=1.0,
+        server_default=text("1.0"),
+        nullable=False,
+    )
+    limit_warmup_min_available_percent: Mapped[float] = mapped_column(
+        Float,
+        default=100.0,
+        server_default=text("100.0"),
+    )
+    weekly_pace_working_days: Mapped[str] = mapped_column(
+        String,
+        default="0,1,2,3,4,5,6",
+        server_default=text("'0,1,2,3,4,5,6'"),
+        nullable=False,
+    )
+    weekly_pace_smoothing_minutes: Mapped[int] = mapped_column(
+        Integer,
+        default=30,
+        server_default=text("30"),
+        nullable=False,
+    )
+    limit_warmup_staggered_idle_enabled: Mapped[bool] = mapped_column(
+        Boolean,
+        default=False,
+        server_default=false(),
+        nullable=False,
+    )
+    warmup_model: Mapped[str] = mapped_column(
+        String,
+        default="gpt-5.4-mini",
+        server_default=text("'gpt-5.4-mini'"),
+        nullable=False,
+    )
+    additional_quota_routing_policies_json: Mapped[str] = mapped_column(
+        Text,
+        default="{}",
+        server_default=text("'{}'"),
+        nullable=False,
+    )
+    # Data retention windows in days; NULL = never set from the dashboard
+    # (treated as disabled), 0 = explicitly disabled.
+    request_log_retention_days: Mapped[int | None] = mapped_column(
+        Integer,
+        nullable=True,
+    )
+    usage_history_retention_days: Mapped[int | None] = mapped_column(
+        Integer,
+        nullable=True,
+    )
+    # C2-3 resilience toggles: NULL inherits the deprecated ``CODEX_LB_*`` env
+    # alias (then the code default); a non-NULL value is dashboard-owned.
+    soft_drain_enabled: Mapped[bool | None] = mapped_column(Boolean, nullable=True)
+    deterministic_failover_enabled: Mapped[bool | None] = mapped_column(Boolean, nullable=True)
+    circuit_breaker_enabled: Mapped[bool | None] = mapped_column(Boolean, nullable=True)
+    # M2 background jobs: NULL inherits the deprecated ``CODEX_LB_*`` env alias
+    # (then the code default); schedulers read the value at every cycle entry.
+    auth_guardian_enabled: Mapped[bool | None] = mapped_column(Boolean, nullable=True)
+    automations_scheduler_enabled: Mapped[bool | None] = mapped_column(Boolean, nullable=True)
+    rate_limit_reset_credits_refresh_enabled: Mapped[bool | None] = mapped_column(Boolean, nullable=True)
+    # end M2 background jobs
+    # M5 conversation archive: NULL inherits the deprecated
+    # ``CODEX_LB_CONVERSATION_ARCHIVE_ENABLED`` env alias (then the code
+    # default, off); a non-NULL value is dashboard-owned.
+    conversation_archive_enabled: Mapped[bool | None] = mapped_column(Boolean, nullable=True)
+    # end M5 conversation archive
+    # R2 spool retention: how long the durable HTTP-bridge operation spool --
+    # raw request payloads and their spooled response events -- is kept before
+    # the retention sweep deletes it. NULL inherits the deprecated
+    # ``CODEX_LB_HTTP_RESPONSES_SESSION_BRIDGE_OPERATION_SPOOL_RETENTION_SECONDS``
+    # env alias (then the code default, 7 days); a non-NULL value is
+    # dashboard-owned and must stay at or above the replay floor.
+    http_responses_session_bridge_operation_spool_retention_seconds: Mapped[float | None] = mapped_column(
+        Float, nullable=True
+    )
+    # end R2 spool retention
+    version: Mapped[int] = mapped_column(
+        Integer,
+        default=1,
+        server_default=text("1"),
+        nullable=False,
+    )
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), nullable=False)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime,
+        server_default=func.now(),
+        onupdate=func.now(),
+        nullable=False,
+    )
+
+    __mapper_args__ = {"version_id_col": version}
+
+
+# M4 model catalogue: dashboard-managed per-model context window overrides.
+class ModelContextWindowOverride(Base):
+    """One dashboard-stored context window override for a model slug.
+
+    A row wins over the ``CODEX_LB_MODEL_CONTEXT_WINDOW_OVERRIDES`` entry for
+    the same slug; slugs without a row inherit the environment entry (or have
+    no override). The migration never copies the environment into rows.
+    """
+
+    __tablename__ = "model_context_window_overrides"
+
+    slug: Mapped[str] = mapped_column(String, primary_key=True)
+    context_window: Mapped[int] = mapped_column(Integer, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), nullable=False)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime,
+        server_default=func.now(),
+        onupdate=func.now(),
+        nullable=False,
+    )
+
+
+# end M4 model catalogue
+
+
+class RuntimeSentinel(Base):
+    """Cross-replica consistency sentinels stamped into the shared database.
+
+    Each row records a value every replica must agree on (for example the
+    encryption-key fingerprint). Rows are written with an atomic
+    insert-if-absent so the first replica to boot wins and later replicas
+    verify against the stored value.
+    """
+
+    __tablename__ = "runtime_sentinels"
+
+    name: Mapped[str] = mapped_column(String(64), primary_key=True)
+    value: Mapped[str] = mapped_column(String(128), nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), nullable=False)
+    updated_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+
+
+class ApiFirewallAllowlist(Base):
+    __tablename__ = "api_firewall_allowlist"
+
+    ip_address: Mapped[str] = mapped_column(String, primary_key=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), nullable=False)
+
+
+class ApiKey(Base):
+    __tablename__ = "api_keys"
+    __table_args__ = (
+        CheckConstraint(
+            "allowed_reasoning_efforts IS NULL OR enforced_reasoning_effort IS NULL",
+            name="ck_api_keys_reasoning_policy_exclusive",
+        ),
+    )
+
+    id: Mapped[str] = mapped_column(String, primary_key=True)
+    name: Mapped[str] = mapped_column(String, nullable=False)
+    key_hash: Mapped[str] = mapped_column(String, nullable=False, unique=True)
+    key_prefix: Mapped[str] = mapped_column(String, nullable=False)
+    allowed_models: Mapped[str | None] = mapped_column(Text, nullable=True)
+    apply_to_codex_model: Mapped[bool] = mapped_column(
+        Boolean,
+        default=False,
+        server_default=false(),
+        nullable=False,
+    )
+    enforced_model: Mapped[str | None] = mapped_column(String, nullable=True)
+    enforced_reasoning_effort: Mapped[str | None] = mapped_column(String, nullable=True)
+    allowed_reasoning_efforts: Mapped[str | None] = mapped_column(Text, nullable=True)
+    enforced_service_tier: Mapped[str | None] = mapped_column(String, nullable=True)
+    traffic_class: Mapped[str] = mapped_column(
+        String,
+        default="foreground",
+        server_default=text("'foreground'"),
+        nullable=False,
+    )
+    transport_policy_override: Mapped[str | None] = mapped_column(String, nullable=True)
+    # NULL = follow the fleet (dashboard, then environment, then ``shared``).
+    thread_cache_identity_override: Mapped[str | None] = mapped_column(String, nullable=True)
+    account_assignment_scope_enabled: Mapped[bool] = mapped_column(
+        Boolean,
+        default=False,
+        server_default=false(),
+        nullable=False,
+    )
+    source_assignment_scope_enabled: Mapped[bool] = mapped_column(
+        Boolean,
+        default=False,
+        server_default=false(),
+        nullable=False,
+    )
+    usage_sections: Mapped[str | None] = mapped_column(
+        Text,
+        nullable=False,
+        default="upstream_limits,account_pool_usage",
+        server_default="upstream_limits,account_pool_usage",
+    )
+    expires_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    is_active: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
+    # Ownership (per-user accounts). NULL owner = shared/service key. Populated
+    # once principals carry a user id; declared here so the schema lands once.
+    owner_user_id: Mapped[str | None] = mapped_column(
+        String,
+        ForeignKey("dashboard_users.id", ondelete="SET NULL"),
+        nullable=True,
+    )
+    created_by_user_id: Mapped[str | None] = mapped_column(
+        String,
+        ForeignKey("dashboard_users.id", ondelete="SET NULL"),
+        nullable=True,
+    )
+    # Why an inactive key is inactive, so re-enabling a user restores only the
+    # keys that were disabled because of that user (never manual blocks).
+    deactivated_reason: Mapped[str | None] = mapped_column(String(32), nullable=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), nullable=False)
+    last_used_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+
+    limits: Mapped[list["ApiKeyLimit"]] = relationship(
+        "ApiKeyLimit",
+        back_populates="api_key",
+        cascade="all, delete-orphan",
+        lazy="selectin",
+    )
+    account_assignments: Mapped[list["ApiKeyAccountAssignment"]] = relationship(
+        "ApiKeyAccountAssignment",
+        back_populates="api_key",
+        cascade="all, delete-orphan",
+        lazy="selectin",
+    )
+    source_assignments: Mapped[list["ApiKeyModelSourceAssignment"]] = relationship(
+        "ApiKeyModelSourceAssignment",
+        back_populates="api_key",
+        cascade="all, delete-orphan",
+        lazy="selectin",
+    )
+
+
+class ApiKeyAccountAssignment(Base):
+    __tablename__ = "api_key_accounts"
+
+    api_key_id: Mapped[str] = mapped_column(
+        String,
+        ForeignKey("api_keys.id", ondelete="CASCADE"),
+        primary_key=True,
+    )
+    account_id: Mapped[str] = mapped_column(
+        String,
+        ForeignKey("accounts.id", ondelete="CASCADE"),
+        primary_key=True,
+    )
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), nullable=False)
+
+    api_key: Mapped["ApiKey"] = relationship("ApiKey", back_populates="account_assignments")
+    account: Mapped["Account"] = relationship("Account", back_populates="api_key_assignments")
+
+
+class ModelSource(Base):
+    __tablename__ = "model_sources"
+
+    id: Mapped[str] = mapped_column(String, primary_key=True)
+    name: Mapped[str] = mapped_column(String, nullable=False)
+    kind: Mapped[str] = mapped_column(
+        String,
+        default="openai_compatible",
+        server_default=text("'openai_compatible'"),
+        nullable=False,
+    )
+    base_url: Mapped[str] = mapped_column(String, nullable=False)
+    api_key_encrypted: Mapped[bytes | None] = mapped_column(LargeBinary, nullable=True)
+    is_enabled: Mapped[bool] = mapped_column(Boolean, default=True, server_default=true(), nullable=False)
+    health_status: Mapped[str] = mapped_column(
+        String,
+        default="unknown",
+        server_default=text("'unknown'"),
+        nullable=False,
+    )
+    supports_chat_completions: Mapped[bool] = mapped_column(
+        Boolean,
+        default=True,
+        server_default=true(),
+        nullable=False,
+    )
+    supports_responses: Mapped[bool] = mapped_column(
+        Boolean,
+        default=False,
+        server_default=false(),
+        nullable=False,
+    )
+    supports_audio_transcriptions: Mapped[bool] = mapped_column(
+        Boolean,
+        default=False,
+        server_default=false(),
+        nullable=False,
+    )
+    supports_embeddings: Mapped[bool] = mapped_column(
+        Boolean,
+        default=False,
+        server_default=false(),
+        nullable=False,
+    )
+    timeout_seconds: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    max_concurrency: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), nullable=False)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime,
+        server_default=func.now(),
+        onupdate=func.now(),
+        nullable=False,
+    )
+
+    models: Mapped[list["ModelSourceModel"]] = relationship(
+        "ModelSourceModel",
+        back_populates="source",
+        cascade="all, delete-orphan",
+        lazy="selectin",
+    )
+    api_key_assignments: Mapped[list["ApiKeyModelSourceAssignment"]] = relationship(
+        "ApiKeyModelSourceAssignment",
+        back_populates="source",
+        cascade="all, delete-orphan",
+    )
+    request_logs: Mapped[list["RequestLog"]] = relationship(
+        "RequestLog",
+        back_populates="model_source",
+        primaryjoin="ModelSource.id == foreign(RequestLog.model_source_id)",
+        viewonly=True,
+    )
+
+
+class ModelSourceModel(Base):
+    __tablename__ = "model_source_models"
+    __table_args__ = (UniqueConstraint("source_id", "model", name="uq_model_source_models_source_model"),)
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    source_id: Mapped[str] = mapped_column(String, ForeignKey("model_sources.id", ondelete="CASCADE"), nullable=False)
+    model: Mapped[str] = mapped_column(String, nullable=False)
+    display_name: Mapped[str | None] = mapped_column(String, nullable=True)
+    context_window: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    max_output_tokens: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    supports_streaming: Mapped[bool] = mapped_column(Boolean, default=True, server_default=true(), nullable=False)
+    supports_tools: Mapped[bool] = mapped_column(Boolean, default=False, server_default=false(), nullable=False)
+    supports_vision: Mapped[bool] = mapped_column(Boolean, default=False, server_default=false(), nullable=False)
+    input_per_1m: Mapped[float | None] = mapped_column(Float, nullable=True)
+    cached_input_per_1m: Mapped[float | None] = mapped_column(Float, nullable=True)
+    output_per_1m: Mapped[float | None] = mapped_column(Float, nullable=True)
+    audio_per_minute: Mapped[float | None] = mapped_column(Float, nullable=True)
+    raw_metadata_json: Mapped[str | None] = mapped_column(Text, nullable=True)
+    is_enabled: Mapped[bool] = mapped_column(Boolean, default=True, server_default=true(), nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), nullable=False)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime,
+        server_default=func.now(),
+        onupdate=func.now(),
+        nullable=False,
+    )
+
+    source: Mapped["ModelSource"] = relationship("ModelSource", back_populates="models")
+
+
+class ApiKeyModelSourceAssignment(Base):
+    __tablename__ = "api_key_model_sources"
+
+    api_key_id: Mapped[str] = mapped_column(
+        String,
+        ForeignKey("api_keys.id", ondelete="CASCADE"),
+        primary_key=True,
+    )
+    source_id: Mapped[str] = mapped_column(
+        String,
+        ForeignKey("model_sources.id", ondelete="CASCADE"),
+        primary_key=True,
+    )
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), nullable=False)
+
+    api_key: Mapped["ApiKey"] = relationship("ApiKey", back_populates="source_assignments")
+    source: Mapped["ModelSource"] = relationship("ModelSource", back_populates="api_key_assignments")
+
+
+class LimitType(str, Enum):
+    TOTAL_TOKENS = "total_tokens"
+    INPUT_TOKENS = "input_tokens"
+    OUTPUT_TOKENS = "output_tokens"
+    COST_USD = "cost_usd"
+    CREDITS = "credits"
+
+
+class LimitWindow(str, Enum):
+    DAILY = "daily"
+    WEEKLY = "weekly"
+    MONTHLY = "monthly"
+    FIVE_HOURS = "5h"
+    SEVEN_DAYS = "7d"
+
+
+class ApiKeyLimit(Base):
+    __tablename__ = "api_key_limits"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    api_key_id: Mapped[str] = mapped_column(
+        String,
+        ForeignKey("api_keys.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    limit_type: Mapped[LimitType] = mapped_column(
+        SqlEnum(
+            LimitType,
+            name="limit_type",
+            validate_strings=True,
+            values_callable=_enum_values,
+        ),
+        nullable=False,
+    )
+    limit_window: Mapped[LimitWindow] = mapped_column(
+        SqlEnum(
+            LimitWindow,
+            name="limit_window",
+            validate_strings=True,
+            values_callable=_enum_values,
+        ),
+        nullable=False,
+    )
+    max_value: Mapped[int] = mapped_column(BigInteger, nullable=False)
+    current_value: Mapped[int] = mapped_column(BigInteger, default=0, server_default=text("0"), nullable=False)
+    model_filter: Mapped[str | None] = mapped_column(String, nullable=True)
+    reset_at: Mapped[datetime] = mapped_column(DateTime, nullable=False)
+
+    api_key: Mapped["ApiKey"] = relationship("ApiKey", back_populates="limits")
+
+
+class ApiKeyUsageReservation(Base):
+    __tablename__ = "api_key_usage_reservations"
+
+    id: Mapped[str] = mapped_column(String, primary_key=True)
+    api_key_id: Mapped[str] = mapped_column(
+        String,
+        ForeignKey("api_keys.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    model: Mapped[str] = mapped_column(String, nullable=False)
+    status: Mapped[str] = mapped_column(String, nullable=False, default="reserved")
+    input_tokens: Mapped[int | None] = mapped_column(BigInteger, nullable=True)
+    output_tokens: Mapped[int | None] = mapped_column(BigInteger, nullable=True)
+    cached_input_tokens: Mapped[int | None] = mapped_column(BigInteger, nullable=True)
+    cost_microdollars: Mapped[int | None] = mapped_column(BigInteger, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), nullable=False)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime,
+        server_default=func.now(),
+        onupdate=func.now(),
+        nullable=False,
+    )
+
+    items: Mapped[list["ApiKeyUsageReservationItem"]] = relationship(
+        "ApiKeyUsageReservationItem",
+        back_populates="reservation",
+        cascade="all, delete-orphan",
+        lazy="selectin",
+    )
+
+
+class ApiKeyUsageReservationItem(Base):
+    __tablename__ = "api_key_usage_reservation_items"
+    __table_args__ = (UniqueConstraint("reservation_id", "limit_id", name="uq_reservation_limit"),)
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    reservation_id: Mapped[str] = mapped_column(
+        String,
+        ForeignKey("api_key_usage_reservations.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    limit_id: Mapped[int] = mapped_column(
+        Integer,
+        ForeignKey("api_key_limits.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    limit_type: Mapped[str] = mapped_column(String, nullable=False)
+    reserved_delta: Mapped[int] = mapped_column(BigInteger, nullable=False)
+    actual_delta: Mapped[int | None] = mapped_column(BigInteger, nullable=True)
+    expected_reset_at: Mapped[datetime] = mapped_column(DateTime, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), nullable=False)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime,
+        server_default=func.now(),
+        onupdate=func.now(),
+        nullable=False,
+    )
+
+    reservation: Mapped[ApiKeyUsageReservation] = relationship(
+        "ApiKeyUsageReservation",
+        back_populates="items",
+    )
+    limit: Mapped[ApiKeyLimit] = relationship("ApiKeyLimit")
+
+
+class AutomationJob(Base):
+    __tablename__ = "automation_jobs"
+
+    id: Mapped[str] = mapped_column(String, primary_key=True)
+    name: Mapped[str] = mapped_column(String(200), nullable=False)
+    enabled: Mapped[bool] = mapped_column(Boolean, default=True, server_default=true(), nullable=False)
+    schedule_type: Mapped[str] = mapped_column(
+        String(32),
+        nullable=False,
+        default="daily",
+        server_default=text("'daily'"),
+    )
+    schedule_time: Mapped[str] = mapped_column(String(5), nullable=False)
+    schedule_timezone: Mapped[str] = mapped_column(String(64), nullable=False)
+    schedule_days: Mapped[str] = mapped_column(
+        String(64),
+        nullable=False,
+        default="mon,tue,wed,thu,fri,sat,sun",
+        server_default=text("'mon,tue,wed,thu,fri,sat,sun'"),
+    )
+    schedule_threshold_minutes: Mapped[int] = mapped_column(
+        Integer,
+        nullable=False,
+        default=0,
+        server_default=text("0"),
+    )
+    include_paused_accounts: Mapped[bool] = mapped_column(
+        Boolean,
+        nullable=False,
+        default=False,
+        server_default=false(),
+    )
+    account_scope_all: Mapped[bool] = mapped_column(Boolean, nullable=False, default=True, server_default=true())
+    model: Mapped[str] = mapped_column(String, nullable=False)
+    reasoning_effort: Mapped[str | None] = mapped_column(String(16), nullable=True)
+    prompt: Mapped[str] = mapped_column(Text, nullable=False, default="ping", server_default=text("'ping'"))
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), nullable=False)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime,
+        server_default=func.now(),
+        onupdate=func.now(),
+        nullable=False,
+    )
+
+    account_links: Mapped[list["AutomationJobAccount"]] = relationship(
+        "AutomationJobAccount",
+        back_populates="job",
+        cascade="all, delete-orphan",
+    )
+    runs: Mapped[list["AutomationRun"]] = relationship(
+        "AutomationRun",
+        back_populates="job",
+        cascade="all, delete-orphan",
+    )
+    run_cycles: Mapped[list["AutomationRunCycle"]] = relationship(
+        "AutomationRunCycle",
+        back_populates="job",
+        cascade="all, delete-orphan",
+    )
+
+
+class AutomationJobAccount(Base):
+    __tablename__ = "automation_job_accounts"
+    __table_args__ = (UniqueConstraint("job_id", "position", name="uq_automation_job_accounts_position"),)
+
+    job_id: Mapped[str] = mapped_column(
+        String,
+        ForeignKey("automation_jobs.id", ondelete="CASCADE"),
+        primary_key=True,
+    )
+    account_id: Mapped[str] = mapped_column(
+        String,
+        ForeignKey("accounts.id", ondelete="CASCADE"),
+        primary_key=True,
+    )
+    position: Mapped[int] = mapped_column(Integer, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), nullable=False)
+
+    job: Mapped[AutomationJob] = relationship("AutomationJob", back_populates="account_links")
+    account: Mapped[Account] = relationship("Account")
+
+
+class AutomationRun(Base):
+    __tablename__ = "automation_runs"
+
+    id: Mapped[str] = mapped_column(String, primary_key=True)
+    job_id: Mapped[str] = mapped_column(
+        String,
+        ForeignKey("automation_jobs.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    trigger: Mapped[str] = mapped_column(String(16), nullable=False)
+    slot_key: Mapped[str] = mapped_column(String(128), nullable=False, unique=True)
+    cycle_key: Mapped[str] = mapped_column(String(160), nullable=False)
+    cycle_expected_accounts: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    cycle_window_end: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    model: Mapped[str | None] = mapped_column(String, nullable=True)
+    reasoning_effort: Mapped[str | None] = mapped_column(String(16), nullable=True)
+    prompt: Mapped[str | None] = mapped_column(Text, nullable=True)
+    scheduled_for: Mapped[datetime] = mapped_column(DateTime, nullable=False)
+    started_at: Mapped[datetime] = mapped_column(DateTime, nullable=False)
+    finished_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    status: Mapped[str] = mapped_column(String(16), nullable=False, default="running", server_default=text("'running'"))
+    account_id: Mapped[str | None] = mapped_column(
+        String,
+        ForeignKey("accounts.id", ondelete="SET NULL"),
+        nullable=True,
+    )
+    error_code: Mapped[str | None] = mapped_column(String(100), nullable=True)
+    error_message: Mapped[str | None] = mapped_column(Text, nullable=True)
+    attempt_count: Mapped[int] = mapped_column(Integer, nullable=False, default=0, server_default=text("0"))
+    # Compact request budget (seconds) in effect when this row was last
+    # claimed; the stale-claim reclaim window covers the larger of this value
+    # and the current budget so a later dashboard change cannot reclaim an
+    # in-flight run early. NULL on rows claimed before the column existed
+    # (they use the current budget).
+    claim_budget_seconds: Mapped[float | None] = mapped_column(Float, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), nullable=False)
+
+    job: Mapped[AutomationJob] = relationship("AutomationJob", back_populates="runs")
+    account: Mapped[Account | None] = relationship("Account")
+
+
+class AutomationRunCycle(Base):
+    __tablename__ = "automation_run_cycles"
+
+    cycle_key: Mapped[str] = mapped_column(String(160), primary_key=True)
+    job_id: Mapped[str] = mapped_column(
+        String,
+        ForeignKey("automation_jobs.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    trigger: Mapped[str] = mapped_column(String(16), nullable=False)
+    cycle_expected_accounts: Mapped[int] = mapped_column(Integer, nullable=False, default=0, server_default=text("0"))
+    cycle_window_end: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    include_paused_accounts: Mapped[bool] = mapped_column(
+        Boolean,
+        nullable=False,
+        default=False,
+        server_default=false(),
+    )
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), nullable=False)
+
+    job: Mapped[AutomationJob] = relationship("AutomationJob", back_populates="run_cycles")
+    cycle_accounts: Mapped[list["AutomationRunCycleAccount"]] = relationship(
+        "AutomationRunCycleAccount",
+        back_populates="cycle",
+        cascade="all, delete-orphan",
+    )
+
+
+class AutomationRunCycleAccount(Base):
+    __tablename__ = "automation_run_cycle_accounts"
+    __table_args__ = (UniqueConstraint("cycle_key", "position", name="uq_automation_run_cycle_accounts_position"),)
+
+    cycle_key: Mapped[str] = mapped_column(
+        String(160),
+        ForeignKey("automation_run_cycles.cycle_key", ondelete="CASCADE"),
+        primary_key=True,
+    )
+    account_id: Mapped[str] = mapped_column(String, primary_key=True)
+    slot_key: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    position: Mapped[int] = mapped_column(Integer, nullable=False)
+    scheduled_for: Mapped[datetime] = mapped_column(DateTime, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), nullable=False)
+
+    cycle: Mapped[AutomationRunCycle] = relationship("AutomationRunCycle", back_populates="cycle_accounts")
+
+
+class RateLimitAttempt(Base):
+    __tablename__ = "rate_limit_attempts"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    key: Mapped[str] = mapped_column(String(255), nullable=False, index=True)
+    attempted_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=func.now(), nullable=False)
+    type: Mapped[str] = mapped_column(String(50), nullable=False)
+
+
+class QuotaPlannerSettings(Base):
+    __tablename__ = "quota_planner_settings"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=False)
+    mode: Mapped[str] = mapped_column(String, default="shadow", server_default=text("'shadow'"), nullable=False)
+    timezone: Mapped[str] = mapped_column(String, default="UTC", server_default=text("'UTC'"), nullable=False)
+    working_days_json: Mapped[str] = mapped_column(
+        Text,
+        default="[0,1,2,3,4]",
+        server_default=text("'[0,1,2,3,4]'"),
+        nullable=False,
+    )
+    working_hours_start: Mapped[str] = mapped_column(
+        String,
+        default="09:00",
+        server_default=text("'09:00'"),
+        nullable=False,
+    )
+    working_hours_end: Mapped[str] = mapped_column(
+        String,
+        default="18:00",
+        server_default=text("'18:00'"),
+        nullable=False,
+    )
+    prewarm_enabled: Mapped[bool] = mapped_column(Boolean, default=True, server_default=true(), nullable=False)
+    prewarm_lead_minutes: Mapped[int] = mapped_column(Integer, default=300, server_default=text("300"), nullable=False)
+    max_warmups_per_day: Mapped[int] = mapped_column(Integer, default=3, server_default=text("3"), nullable=False)
+    max_warmup_credits_per_day: Mapped[float] = mapped_column(
+        Float,
+        default=0.0,
+        server_default=text("0.0"),
+        nullable=False,
+    )
+    min_expected_gain: Mapped[float] = mapped_column(Float, default=1.0, server_default=text("1.0"), nullable=False)
+    forecast_quantile: Mapped[str] = mapped_column(String, default="p75", server_default=text("'p75'"), nullable=False)
+    allow_synthetic_traffic: Mapped[bool] = mapped_column(
+        Boolean,
+        default=False,
+        server_default=false(),
+        nullable=False,
+    )
+    warmup_model_preference: Mapped[str | None] = mapped_column(String, nullable=True)
+    dry_run: Mapped[bool] = mapped_column(Boolean, default=True, server_default=true(), nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), nullable=False)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime,
+        server_default=func.now(),
+        onupdate=func.now(),
+        nullable=False,
+    )
+
+
+class QuotaPlannerDecision(Base):
+    __tablename__ = "quota_planner_decisions"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), nullable=False)
+    mode: Mapped[str] = mapped_column(String, nullable=False)
+    account_id: Mapped[str | None] = mapped_column(
+        String,
+        ForeignKey("accounts.id", ondelete="SET NULL"),
+        nullable=True,
+    )
+    action: Mapped[str] = mapped_column(String, nullable=False)
+    scheduled_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    executed_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    lease_expires_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    score: Mapped[float] = mapped_column(Float, default=0.0, server_default=text("0.0"), nullable=False)
+    reason: Mapped[str | None] = mapped_column(Text, nullable=True)
+    forecast_snapshot_hash: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    state_before_json: Mapped[str | None] = mapped_column(Text, nullable=True)
+    state_after_json: Mapped[str | None] = mapped_column(Text, nullable=True)
+    status: Mapped[str] = mapped_column(String, default="planned", server_default=text("'planned'"), nullable=False)
+    idempotency_key: Mapped[str] = mapped_column(String, nullable=False, unique=True)
+
+
+class QuotaWindowObservation(Base):
+    __tablename__ = "quota_window_observations"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    account_id: Mapped[str] = mapped_column(String, ForeignKey("accounts.id", ondelete="CASCADE"), nullable=False)
+    observed_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), nullable=False)
+    model: Mapped[str | None] = mapped_column(String, nullable=True)
+    primary_remaining_percent: Mapped[float | None] = mapped_column(Float, nullable=True)
+    primary_reset_at: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    secondary_remaining_percent: Mapped[float | None] = mapped_column(Float, nullable=True)
+    secondary_reset_at: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    source: Mapped[str] = mapped_column(String, nullable=False)
+    confidence: Mapped[str] = mapped_column(String, default="unknown", server_default=text("'unknown'"), nullable=False)
+
+
+class CacheInvalidation(Base):
+    __tablename__ = "cache_invalidation"
+
+    namespace: Mapped[str] = mapped_column(String(50), primary_key=True)
+    version: Mapped[int] = mapped_column(Integer, nullable=False, server_default="0")
+
+
+class ModelRegistrySnapshotRecord(Base):
+    """Single-row (id=1) persisted serialization of the refreshed model registry.
+
+    Written by the leader's model refresh cycle and loaded by every replica via
+    the cache-invalidation bus so the catalog stays replica-coherent.
+    """
+
+    __tablename__ = "model_registry_snapshot"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=False)
+    schema_version: Mapped[int] = mapped_column(Integer, nullable=False)
+    content_hash: Mapped[str] = mapped_column(String(64), nullable=False)
+    payload: Mapped[str] = mapped_column(Text, nullable=False)
+    refreshed_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    leader_id: Mapped[str | None] = mapped_column(String(255), nullable=True)
+
+
+class AccountRefreshClaim(Base):
+    """Cross-replica, per-account token-refresh claim.
+
+    One row per account marks which claimant (replica/process) currently owns
+    the right to run the upstream OAuth token exchange. Rows are acquired via a
+    conditional upsert that only succeeds when no unexpired claim by another
+    claimant exists, and carry a TTL (`claim_expires_at`) so a crashed claimant
+    can never block refresh indefinitely. The claim is pure coordination state:
+    it holds no token material and is deleted after the refreshed tokens are
+    persisted.
+    """
+
+    __tablename__ = "account_refresh_claims"
+
+    account_id: Mapped[str] = mapped_column(
+        String,
+        ForeignKey("accounts.id", ondelete="CASCADE"),
+        primary_key=True,
+    )
+    claimed_by: Mapped[str] = mapped_column(String(128), nullable=False)
+    claimed_at: Mapped[datetime] = mapped_column(DateTime, nullable=False)
+    claim_expires_at: Mapped[datetime] = mapped_column(DateTime, nullable=False)
+
+
+class AccountPlanDowngradeObservation(Base):
+    """Pending workspace-less paid -> free plan-downgrade evidence per account.
+
+    A workspace-less usage payload reporting ``free`` for a paid account is only
+    trusted once two consecutive refreshes agree (issue #1456). The observation
+    count lives here rather than in process memory so the sequence is coherent
+    across replicas sharing one database: an intervening paid payload observed by
+    any replica clears the evidence for all of them, and two ``free`` samples
+    split across replicas still converge.
+
+    ``credential_fingerprint`` pins the evidence to the credential lineage that
+    produced it: a fixed-salt digest over the account's stable seat identity
+    (workspace and principal identifiers, email, ``codex_installation_id``),
+    deliberately not over token material -- refresh tokens rotate on every
+    token refresh, and rotation must not read as a credential replacement.
+    Account ids are deterministic, so a delete-and-re-import or an in-place
+    reauthentication reuses the same id with new credentials; those replacements
+    discard this row explicitly (the accounts repository deletes it in the same
+    transaction that applies the fresh credentials), and the fingerprint
+    comparison restarts the count for any remaining path that rebinds the row's
+    seat identity.
+
+    The row holds no secrets: a count, a plan value, timestamps, and the
+    non-reversible identity digest, stored outside the encrypted token columns.
+    It is deleted as soon as the downgrade is applied or the evidence is
+    invalidated. ``ondelete="CASCADE"`` drops it with the account.
+    """
+
+    __tablename__ = "account_plan_downgrade_observations"
+
+    account_id: Mapped[str] = mapped_column(
+        String,
+        ForeignKey("accounts.id", ondelete="CASCADE"),
+        primary_key=True,
+    )
+    observations: Mapped[int] = mapped_column(Integer, nullable=False)
+    credential_fingerprint: Mapped[str] = mapped_column(String(64), nullable=False)
+    observed_plan_type: Mapped[str] = mapped_column(String, nullable=False)
+    first_observed_at: Mapped[datetime] = mapped_column(DateTime, nullable=False)
+    last_observed_at: Mapped[datetime] = mapped_column(DateTime, nullable=False)
+
+
+class BridgeRingMember(Base):
+    __tablename__ = "bridge_ring_members"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
+    instance_id: Mapped[str] = mapped_column(String(255), nullable=False, unique=True)
+    registered_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=func.now())
+    last_heartbeat_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=func.now())
+    metadata_json: Mapped[str | None] = mapped_column(Text, nullable=True)
+
+
+class HttpBridgeSessionState(str, Enum):
+    ACTIVE = "active"
+    DRAINING = "draining"
+    CLOSED = "closed"
+
+
+class HttpBridgeRecoveryAttemptState(str, Enum):
+    UNKNOWN = "unknown"
+    REPLAYED = "replayed"
+
+
+HTTP_BRIDGE_SPOOL_FORMAT_ROWS_V1 = "rows_v1"
+HTTP_BRIDGE_SPOOL_FORMAT_CHUNKS_V2 = "chunks_v2"
+
+# Where one dispatch of an operation stands in the two-phase terminal write.
+# This is deliberately separate from ``event_spool_complete``: an ordinary
+# operation carries an incomplete spool under a terminal ``state`` for the whole
+# window in which its terminal append runs, because the relay publishes the
+# operation state before appending the terminal transcript block.
+#
+#   PENDING  -> no terminal transcript outcome recorded yet; appends allowed.
+#   APPENDED -> a terminal append committed and is awaiting fenced
+#               finalization; further terminal appends must not rewrite the
+#               outcome, but finalization may still mark it replayable.
+#   SETTLED  -> the terminal outcome was published without a confirmed append
+#               (fallback settlement). The row is final and never replayable,
+#               so both later appends and finalization are refused.
+HTTP_BRIDGE_TERMINAL_APPEND_PHASE_PENDING = "pending"
+HTTP_BRIDGE_TERMINAL_APPEND_PHASE_APPENDED = "appended"
+HTTP_BRIDGE_TERMINAL_APPEND_PHASE_SETTLED = "settled"
+
+
+class HttpBridgeOperationState(str, Enum):
+    SUBMITTED = "submitted"
+    UNKNOWN = "unknown"
+    ACKNOWLEDGED = "acknowledged"
+    ABANDONED = "abandoned"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+class HttpBridgeSessionRecord(Base):
+    __tablename__ = "http_bridge_sessions"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
+    session_key_kind: Mapped[str] = mapped_column(String(64), nullable=False)
+    session_key_value: Mapped[str] = mapped_column(Text, nullable=False)
+    session_key_hash: Mapped[str] = mapped_column(String(64), nullable=False)
+    api_key_scope: Mapped[str] = mapped_column(String(255), nullable=False)
+    owner_instance_id: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    owner_process_epoch: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    owner_epoch: Mapped[int] = mapped_column(Integer, nullable=False, default=0, server_default=text("0"))
+    lease_expires_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    state: Mapped[HttpBridgeSessionState] = mapped_column(
+        SqlEnum(
+            HttpBridgeSessionState,
+            name="http_bridge_session_state",
+            validate_strings=True,
+            values_callable=_enum_values,
+        ),
+        default=HttpBridgeSessionState.ACTIVE,
+        server_default=text("'active'"),
+        nullable=False,
+    )
+    account_id: Mapped[str | None] = mapped_column(
+        String, ForeignKey("accounts.id", ondelete="SET NULL"), nullable=True
+    )
+    model: Mapped[str | None] = mapped_column(String, nullable=True)
+    service_tier: Mapped[str | None] = mapped_column(String, nullable=True)
+    latest_turn_state: Mapped[str | None] = mapped_column(Text, nullable=True)
+    latest_response_id: Mapped[str | None] = mapped_column(Text, nullable=True)
+    latest_input_item_count: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    latest_input_full_fingerprint: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    latest_pending_tool_calls_json: Mapped[str | None] = mapped_column(Text, nullable=True)
+    # Continuity-owner retirement, mirroring sticky_sessions' pair: a non-NULL
+    # scope retires ownership only for the matching typed source, while a
+    # non-NULL timestamp with NULL scope retires it globally. Deleting the row
+    # instead would be indistinguishable from "never seen" and would leave the
+    # lookup failing closed forever; a marker says the owner was deliberately
+    # abandoned, so picking a fresh one is authorized.
+    continuity_abandoned_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    continuity_abandonment_scope: Mapped[str | None] = mapped_column(String(32), nullable=True)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        nullable=False,
+        default=func.now(),
+        server_default=func.now(),
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        nullable=False,
+        default=func.now(),
+        server_default=func.now(),
+        onupdate=func.now(),
+    )
+    last_seen_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        nullable=False,
+        default=func.now(),
+        server_default=func.now(),
+    )
+    closed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+
+    aliases: Mapped[list["HttpBridgeSessionAlias"]] = relationship(
+        "HttpBridgeSessionAlias",
+        back_populates="session",
+        cascade="all, delete-orphan",
+    )
+
+    __table_args__ = (
+        UniqueConstraint(
+            "session_key_kind",
+            "session_key_hash",
+            "api_key_scope",
+            name="uq_http_bridge_sessions_session_key",
+        ),
+    )
+
+
+class HttpBridgeRecoveryAttemptRecord(Base):
+    __tablename__ = "http_bridge_recovery_attempts"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
+    session_id: Mapped[str] = mapped_column(
+        String(36),
+        ForeignKey("http_bridge_sessions.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    request_fingerprint: Mapped[str] = mapped_column(String(64), nullable=False)
+    request_id: Mapped[str] = mapped_column(String(255), nullable=False)
+    account_id: Mapped[str | None] = mapped_column(String, nullable=True)
+    model: Mapped[str | None] = mapped_column(String, nullable=True)
+    replay_safe: Mapped[bool] = mapped_column(Boolean, nullable=False, server_default=text("false"))
+    state: Mapped[HttpBridgeRecoveryAttemptState] = mapped_column(
+        SqlEnum(
+            HttpBridgeRecoveryAttemptState,
+            name="http_bridge_recovery_attempt_state",
+            validate_strings=True,
+            values_callable=_enum_values,
+        ),
+        default=HttpBridgeRecoveryAttemptState.UNKNOWN,
+        server_default=text("'unknown'"),
+        nullable=False,
+    )
+    response_id: Mapped[str | None] = mapped_column(Text, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, default=func.now(), server_default=func.now()
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, default=func.now(), server_default=func.now(), onupdate=func.now()
+    )
+
+    __table_args__ = (
+        UniqueConstraint(
+            "session_id",
+            "request_fingerprint",
+            name="uq_http_bridge_recovery_attempts_session_fingerprint",
+        ),
+        Index("idx_http_bridge_recovery_attempts_state", "state", "updated_at"),
+    )
+
+
+class HttpBridgeOperationRecord(Base):
+    """Durable identity and outcome for a continuity-bound response.create."""
+
+    __tablename__ = "http_bridge_operations"
+
+    operation_id: Mapped[str] = mapped_column(String(80), primary_key=True)
+    session_id: Mapped[str] = mapped_column(
+        String(36),
+        ForeignKey("http_bridge_sessions.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    request_fingerprint: Mapped[str] = mapped_column(String(64), nullable=False)
+    account_id: Mapped[str | None] = mapped_column(String, nullable=True)
+    model: Mapped[str | None] = mapped_column(String, nullable=True)
+    parent_response_id: Mapped[str | None] = mapped_column(Text, nullable=True)
+    request_text: Mapped[str | None] = mapped_column(Text, nullable=True)
+    state: Mapped[str] = mapped_column(String(32), nullable=False, server_default=text("'submitted'"))
+    response_id: Mapped[str | None] = mapped_column(Text, nullable=True)
+    recovery_dispatch_count: Mapped[int] = mapped_column(Integer, nullable=False, server_default=text("0"))
+    event_bytes: Mapped[int] = mapped_column(Integer, nullable=False, server_default=text("0"))
+    event_spool_complete: Mapped[bool] = mapped_column(Boolean, nullable=False, server_default=text("false"))
+    terminal_append_phase: Mapped[str] = mapped_column(
+        String(16),
+        nullable=False,
+        default=HTTP_BRIDGE_TERMINAL_APPEND_PHASE_PENDING,
+        server_default=text("'pending'"),
+    )
+    spool_format: Mapped[str] = mapped_column(
+        String(16),
+        nullable=False,
+        default=HTTP_BRIDGE_SPOOL_FORMAT_ROWS_V1,
+        server_default=text("'rows_v1'"),
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, default=func.now(), server_default=func.now()
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, default=func.now(), server_default=func.now(), onupdate=func.now()
+    )
+
+    __table_args__ = (
+        UniqueConstraint(
+            "session_id",
+            "request_fingerprint",
+            name="uq_http_bridge_operations_session_fingerprint",
+        ),
+        Index(
+            "uq_http_bridge_operations_request_fingerprint",
+            "request_fingerprint",
+            unique=True,
+        ),
+        Index("idx_http_bridge_operations_session_parent_state", "session_id", "parent_response_id", "state"),
+        Index("idx_http_bridge_operations_parent_state", "parent_response_id", "state", "updated_at"),
+        Index("idx_http_bridge_operations_state_updated", "state", "updated_at"),
+    )
+
+
+class HttpBridgeOperationEvent(Base):
+    """Replayable upstream SSE blocks for a durable bridge operation."""
+
+    __tablename__ = "http_bridge_operation_events"
+
+    event_id: Mapped[str] = mapped_column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
+    operation_id: Mapped[str] = mapped_column(
+        String(80),
+        ForeignKey("http_bridge_operations.operation_id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    sequence_number: Mapped[int] = mapped_column(Integer, nullable=False)
+    event_fingerprint: Mapped[str] = mapped_column(String(64), nullable=False)
+    event_text: Mapped[str] = mapped_column(Text, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, default=func.now(), server_default=func.now()
+    )
+
+    __table_args__ = (
+        UniqueConstraint(
+            "operation_id",
+            "event_fingerprint",
+            name="uq_http_bridge_operation_events_operation_fingerprint",
+        ),
+        Index("idx_http_bridge_operation_events_operation_sequence", "operation_id", "sequence_number"),
+    )
+
+
+class HttpBridgeOperationEventChunk(Base):
+    """Compressed, ordered SSE blocks for a future chunk-format operation."""
+
+    __tablename__ = "http_bridge_operation_event_chunks"
+
+    operation_id: Mapped[str] = mapped_column(
+        String(80),
+        ForeignKey("http_bridge_operations.operation_id", ondelete="CASCADE"),
+        primary_key=True,
+    )
+    first_sequence_number: Mapped[int] = mapped_column(Integer, primary_key=True)
+    event_count: Mapped[int] = mapped_column(Integer, nullable=False)
+    codec: Mapped[str] = mapped_column(String(64), nullable=False)
+    uncompressed_bytes: Mapped[int] = mapped_column(Integer, nullable=False)
+    payload: Mapped[bytes] = mapped_column(LargeBinary, nullable=False)
+    payload_sha256: Mapped[str] = mapped_column(String(64), nullable=False)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, default=func.now(), server_default=func.now()
+    )
+
+    __table_args__ = (
+        CheckConstraint("first_sequence_number > 0", name="ck_http_bridge_event_chunks_first_sequence_positive"),
+        CheckConstraint("event_count > 0", name="ck_http_bridge_event_chunks_event_count_positive"),
+        CheckConstraint("uncompressed_bytes >= 0", name="ck_http_bridge_event_chunks_bytes_nonnegative"),
+    )
+
+
+class HttpBridgeSessionAlias(Base):
+    __tablename__ = "http_bridge_session_aliases"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
+    session_id: Mapped[str] = mapped_column(
+        String(36),
+        ForeignKey("http_bridge_sessions.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    alias_kind: Mapped[str] = mapped_column(String(64), nullable=False)
+    alias_value: Mapped[str] = mapped_column(Text, nullable=False)
+    alias_hash: Mapped[str] = mapped_column(String(64), nullable=False)
+    api_key_scope: Mapped[str] = mapped_column(String(255), nullable=False)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        nullable=False,
+        default=func.now(),
+        server_default=func.now(),
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        nullable=False,
+        default=func.now(),
+        server_default=func.now(),
+        onupdate=func.now(),
+    )
+
+    session: Mapped[HttpBridgeSessionRecord] = relationship(
+        "HttpBridgeSessionRecord",
+        back_populates="aliases",
+    )
+
+    __table_args__ = (
+        UniqueConstraint(
+            "alias_kind",
+            "alias_hash",
+            "api_key_scope",
+            name="uq_http_bridge_session_aliases_alias",
+        ),
+    )
+
+
+class HttpBridgeRetryCircuit(Base):
+    __tablename__ = "http_bridge_retry_circuits"
+
+    session_key_kind: Mapped[str] = mapped_column(String(64), primary_key=True)
+    session_key_hash: Mapped[str] = mapped_column(String(64), primary_key=True)
+    api_key_scope: Mapped[str] = mapped_column(String(255), primary_key=True)
+    consecutive_failures: Mapped[int] = mapped_column(
+        Integer,
+        nullable=False,
+        default=0,
+        server_default=text("0"),
+    )
+    cooldown_until_epoch: Mapped[float] = mapped_column(
+        Float,
+        nullable=False,
+        default=0.0,
+        server_default=text("0"),
+    )
+    last_detail: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    updated_at_epoch: Mapped[float] = mapped_column(Float, nullable=False)
+    admission_generation: Mapped[int] = mapped_column(
+        Integer,
+        nullable=False,
+        default=0,
+        server_default=text("0"),
+    )
+
+
+_PRIMARY_WINDOW_INDEX_EXPR = func.coalesce(UsageHistory.window, literal_column("'primary'"))
+
+Index("idx_usage_recorded_at", UsageHistory.recorded_at)
+Index("idx_usage_account_time", UsageHistory.account_id, UsageHistory.recorded_at)
+Index(
+    "idx_usage_window_account_time",
+    _PRIMARY_WINDOW_INDEX_EXPR,
+    UsageHistory.account_id,
+    UsageHistory.recorded_at,
+)
+Index(
+    "idx_usage_window_account_latest",
+    _PRIMARY_WINDOW_INDEX_EXPR,
+    UsageHistory.account_id,
+    UsageHistory.recorded_at.desc(),
+    UsageHistory.id.desc(),
+)
+Index(
+    "idx_usage_window_raw_account_latest",
+    UsageHistory.window,
+    UsageHistory.account_id,
+    UsageHistory.recorded_at.desc(),
+    UsageHistory.id.desc(),
+)
+# The raw "window" column rides in the payload because the planner only
+# considers an index-only scan when every column referenced by the query is
+# returnable from the index, and the coalesce(...) expression key cannot
+# return its underlying raw column.
+Index(
+    "idx_usage_window_account_time_covering",
+    _PRIMARY_WINDOW_INDEX_EXPR,
+    UsageHistory.account_id,
+    UsageHistory.recorded_at,
+    postgresql_include=["used_percent", "reset_at", "window_minutes", "id", "window"],
+)
+Index(
+    "idx_usage_window_raw_account_time_covering",
+    UsageHistory.window,
+    UsageHistory.account_id,
+    UsageHistory.recorded_at,
+    postgresql_include=["used_percent", "reset_at", "window_minutes", "id"],
+)
+Index("idx_accounts_email", Account.email)
+# Pending-deletion queue: every replica probes ``delete_requested_at IS NOT
+# NULL LIMIT 1`` each worker interval and the leader orders the queue by
+# (delete_requested_at, id); the partial index keeps both reads off the full
+# accounts table and is empty in the steady state (no pending deletions).
+Index(
+    "idx_accounts_delete_requested_at",
+    Account.delete_requested_at,
+    Account.id,
+    postgresql_where=text("delete_requested_at IS NOT NULL"),
+    sqlite_where=text("delete_requested_at IS NOT NULL"),
+)
+Index("idx_accounts_chatgpt_account_id", Account.chatgpt_account_id)
+Index("idx_api_keys_name", ApiKey.name)
+Index("idx_logs_account_time", RequestLog.account_id, RequestLog.requested_at)
+Index("idx_logs_model_source_time", RequestLog.model_source_id, RequestLog.requested_at)
+Index("idx_logs_api_key_time", RequestLog.api_key_id, RequestLog.requested_at.desc(), RequestLog.id.desc())
+Index("idx_logs_request_kind_time", RequestLog.request_kind, RequestLog.requested_at.desc(), RequestLog.id.desc())
+Index(
+    "idx_logs_account_kind_deleted_latest",
+    RequestLog.account_id,
+    RequestLog.request_kind,
+    RequestLog.deleted_at,
+    RequestLog.requested_at,
+    RequestLog.id,
+)
+Index(
+    "idx_logs_account_request_latest",
+    RequestLog.account_id,
+    RequestLog.request_id,
+    RequestLog.requested_at,
+    RequestLog.id,
+)
+Index("idx_logs_source_requested_at", RequestLog.source, RequestLog.requested_at.desc())
+Index("idx_logs_requested_at_id", RequestLog.requested_at.desc(), RequestLog.id.desc())
+Index(
+    "idx_logs_missing_cost",
+    RequestLog.model_source_id,
+    RequestLog.id,
+    postgresql_where=text(
+        "cost_usd IS NULL AND model_source_id IS NULL AND input_tokens IS NOT NULL "
+        "AND (output_tokens IS NOT NULL OR reasoning_tokens IS NOT NULL) "
+        "AND (model_source_kind IS NULL OR model_source_kind = 'subscription')"
+    ),
+    sqlite_where=text(
+        "cost_usd IS NULL AND model_source_id IS NULL AND input_tokens IS NOT NULL "
+        "AND (output_tokens IS NOT NULL OR reasoning_tokens IS NOT NULL) "
+        "AND (model_source_kind IS NULL OR model_source_kind = 'subscription')"
+    ),
+)
+Index(
+    "idx_logs_deleted_at_requested_at_id",
+    RequestLog.deleted_at,
+    RequestLog.requested_at.desc(),
+    RequestLog.id.desc(),
+)
+# Covering partial index for the dashboard usage aggregation hot path. On
+# PostgreSQL the INCLUDE payload lets the aggregation run as an index-only
+# scan without touching the heap; on SQLite it degrades to a partial index on
+# requested_at. Enforced via the manual drift index requirements because
+# partial-index reflection is not consistent across dialects.
+Index(
+    "idx_logs_dash_usage_covering",
+    RequestLog.requested_at,
+    postgresql_include=[
+        "account_id",
+        "api_key_id",
+        "model",
+        "reasoning_effort",
+        "request_kind",
+        "status",
+        "input_tokens",
+        "cached_input_tokens",
+        "output_tokens",
+        "reasoning_tokens",
+        "cost_usd",
+        "id",
+    ],
+    postgresql_where=text("deleted_at IS NULL"),
+    sqlite_where=text("deleted_at IS NULL"),
+)
+Index(
+    "idx_logs_requested_at_model_tier",
+    RequestLog.requested_at.desc(),
+    RequestLog.model,
+    RequestLog.service_tier,
+)
+Index(
+    "idx_logs_model_effort_time",
+    RequestLog.model,
+    RequestLog.reasoning_effort,
+    RequestLog.requested_at.desc(),
+    RequestLog.id.desc(),
+)
+Index(
+    "idx_logs_status_error_time",
+    RequestLog.status,
+    RequestLog.error_code,
+    RequestLog.requested_at.desc(),
+    RequestLog.id.desc(),
+)
+# Live-row partial indexes for the unfiltered request-log facet skip scan
+# (recursive ``facet_skip`` probes: ``min(column) WHERE deleted_at IS NULL AND
+# column > previous``). The predicate matches the probe so a probe never walks
+# the soft-deleted cohort sharing a value. Account ids need none: soft deletion
+# detaches account_id (NULL), which ``account_id > previous`` never walks.
+# Enforced via the manual drift index requirements like the covering index.
+Index(
+    "idx_logs_live_api_key",
+    RequestLog.api_key_id,
+    postgresql_where=text("deleted_at IS NULL"),
+    sqlite_where=text("deleted_at IS NULL"),
+)
+Index(
+    "idx_logs_live_model_effort",
+    RequestLog.model,
+    RequestLog.reasoning_effort,
+    postgresql_where=text("deleted_at IS NULL"),
+    sqlite_where=text("deleted_at IS NULL"),
+)
+Index(
+    "idx_logs_live_status_error",
+    RequestLog.status,
+    RequestLog.error_code,
+    postgresql_where=text("deleted_at IS NULL"),
+    sqlite_where=text("deleted_at IS NULL"),
+)
+Index(
+    "idx_logs_request_status_api_key_time",
+    RequestLog.request_id,
+    RequestLog.status,
+    RequestLog.api_key_id,
+    RequestLog.requested_at.desc(),
+    RequestLog.id.desc(),
+)
+Index(
+    "idx_logs_request_status_api_key_session_time",
+    RequestLog.request_id,
+    RequestLog.status,
+    RequestLog.api_key_id,
+    RequestLog.session_id,
+    RequestLog.requested_at.desc(),
+    RequestLog.id.desc(),
+)
+Index("idx_sticky_account", StickySession.account_id)
+Index("idx_sticky_kind_updated_at", StickySession.kind, StickySession.updated_at.desc())
+Index("idx_api_keys_hash", ApiKey.key_hash)
+Index(
+    "idx_account_limit_warmups_account_attempted", AccountLimitWarmup.account_id, AccountLimitWarmup.attempted_at.desc()
+)
+Index("idx_account_limit_warmups_status_attempted", AccountLimitWarmup.status, AccountLimitWarmup.attempted_at.desc())
+Index("idx_api_key_accounts_account_id", ApiKeyAccountAssignment.account_id)
+Index("idx_api_key_model_sources_source_id", ApiKeyModelSourceAssignment.source_id)
+Index("idx_model_source_models_model_enabled", ModelSourceModel.model, ModelSourceModel.is_enabled)
+Index("idx_api_key_limits_key_id", ApiKeyLimit.api_key_id)
+Index("idx_api_key_limits_reset_at", ApiKeyLimit.reset_at)
+Index("idx_api_key_usage_reservations_key_id", ApiKeyUsageReservation.api_key_id)
+Index("idx_api_key_usage_reservations_status", ApiKeyUsageReservation.status)
+Index(
+    "idx_api_key_usage_reservations_status_updated_at", ApiKeyUsageReservation.status, ApiKeyUsageReservation.updated_at
+)
+Index("idx_api_key_usage_res_items_reservation_id", ApiKeyUsageReservationItem.reservation_id)
+Index("idx_quota_planner_decisions_status_created", QuotaPlannerDecision.status, QuotaPlannerDecision.created_at.desc())
+Index(
+    "idx_quota_planner_decisions_account_created",
+    QuotaPlannerDecision.account_id,
+    QuotaPlannerDecision.created_at.desc(),
+)
+Index(
+    "idx_quota_window_observations_account_time",
+    QuotaWindowObservation.account_id,
+    QuotaWindowObservation.observed_at.desc(),
+)
+Index("idx_automation_jobs_enabled", AutomationJob.enabled)
+Index("idx_automation_job_accounts_account_id", AutomationJobAccount.account_id)
+Index("idx_automation_runs_job_id_started_at", AutomationRun.job_id, AutomationRun.started_at)
+Index("idx_automation_runs_status_started_at", AutomationRun.status, AutomationRun.started_at)
+Index("idx_automation_runs_scheduled_for", AutomationRun.scheduled_for)
+Index("idx_automation_runs_cycle_key_started_at", AutomationRun.cycle_key, AutomationRun.started_at)
+Index(
+    "idx_http_bridge_sessions_owner_state",
+    HttpBridgeSessionRecord.owner_instance_id,
+    HttpBridgeSessionRecord.owner_process_epoch,
+    HttpBridgeSessionRecord.state,
+)
+Index("idx_http_bridge_sessions_lease", HttpBridgeSessionRecord.lease_expires_at)
+Index("idx_http_bridge_sessions_last_seen", HttpBridgeSessionRecord.last_seen_at.desc())
+Index(
+    "idx_http_bridge_sessions_latest_turn_scope_state_seen",
+    HttpBridgeSessionRecord.latest_turn_state,
+    HttpBridgeSessionRecord.api_key_scope,
+    HttpBridgeSessionRecord.state,
+    HttpBridgeSessionRecord.last_seen_at.desc(),
+    HttpBridgeSessionRecord.updated_at.desc(),
+)
+Index(
+    "idx_http_bridge_sessions_latest_response_scope_state_seen",
+    HttpBridgeSessionRecord.latest_response_id,
+    HttpBridgeSessionRecord.api_key_scope,
+    HttpBridgeSessionRecord.state,
+    HttpBridgeSessionRecord.last_seen_at.desc(),
+    HttpBridgeSessionRecord.updated_at.desc(),
+)
+Index(
+    "idx_http_bridge_session_aliases_session_id",
+    HttpBridgeSessionAlias.session_id,
+)
+Index(
+    "idx_http_bridge_session_aliases_alias_kind_hash_scope",
+    HttpBridgeSessionAlias.alias_kind,
+    HttpBridgeSessionAlias.alias_hash,
+    HttpBridgeSessionAlias.api_key_scope,
+)
+Index("ix_additional_usage_history_recorded_at", AdditionalUsageHistory.recorded_at)
+Index(
+    "ix_additional_usage_distinct_labels",
+    AdditionalUsageHistory.account_id,
+    AdditionalUsageHistory.quota_key,
+    AdditionalUsageHistory.limit_name,
+    AdditionalUsageHistory.metered_feature,
+)
+Index(
+    "ix_rate_limit_attempts_type_key_attempted_at",
+    RateLimitAttempt.type,
+    RateLimitAttempt.key,
+    RateLimitAttempt.attempted_at,
+)
+Index(
+    "ix_additional_usage_history_composite",
+    AdditionalUsageHistory.account_id,
+    AdditionalUsageHistory.quota_key,
+    AdditionalUsageHistory.window,
+    AdditionalUsageHistory.recorded_at,
+)
+Index(
+    "ix_additional_usage_quota_window",
+    AdditionalUsageHistory.quota_key,
+    AdditionalUsageHistory.window,
+    AdditionalUsageHistory.account_id,
+    AdditionalUsageHistory.recorded_at,
+)
+Index(
+    "ix_additional_usage_quota_window_latest",
+    AdditionalUsageHistory.quota_key,
+    AdditionalUsageHistory.window,
+    AdditionalUsageHistory.account_id,
+    AdditionalUsageHistory.recorded_at.desc(),
+    AdditionalUsageHistory.used_percent.desc(),
+    AdditionalUsageHistory.id.desc(),
+)
+Index(
+    "ix_additional_usage_alias_limit_latest",
+    func.lower(AdditionalUsageHistory.limit_name),
+    AdditionalUsageHistory.window,
+    AdditionalUsageHistory.account_id,
+    AdditionalUsageHistory.recorded_at.desc(),
+    AdditionalUsageHistory.used_percent.desc(),
+    AdditionalUsageHistory.id.desc(),
+)
+Index(
+    "ix_additional_usage_alias_feature_latest",
+    func.lower(AdditionalUsageHistory.metered_feature),
+    AdditionalUsageHistory.window,
+    AdditionalUsageHistory.account_id,
+    AdditionalUsageHistory.recorded_at.desc(),
+    AdditionalUsageHistory.used_percent.desc(),
+    AdditionalUsageHistory.id.desc(),
+)