sequence-base 0.3.0__py3-none-any.whl

sequence_base/contract/accounts.py

@@ -0,0 +1,93 @@
+"""
+契约 6 — accounts / secret / billing wire types (full picture in docs/platform/accounts.md).
+
+Secret-leak rule, mechanically checkable (goal 15). Two kinds of secret:
+  (a) platform-minted — `direct_secret`, TLS private key. May appear in the DOWN direction only:
+      ConnectResponse.direct_secret, BootstrapResponse.direct_secret + tls_key.
+  (b) user Secret-Manager values. May appear in the WRITE direction only:
+      SecretCreateRequest.env, BootstrapResponse.env (injected into the worker subprocess).
+These four fields are the entire allow-list for carrying a plaintext secret value. Everything returned
+to a client, reported asynchronously, or written to a report/log (SecretRef, SecretInfo, UsageReport,
+eval report, /act response) exposes only names / env_keys — never a value-bearing field.
+"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from sequence_base.contract.connect import Lease
+
+__all__ = [
+    "SecretRef",
+    "SecretCreateRequest",
+    "SecretInfo",
+    "BootstrapResponse",
+    "UsageReport",
+]
+
+
+class SecretRef(BaseModel):
+    """A by-name reference to a secret (PolicySpec.secrets / BenchmarkSpec.secrets). Name only — the
+    value lives in Secret Manager and is injected at worker bootstrap. Never carries a value."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+
+
+class SecretCreateRequest(BaseModel):
+    """POST /v1/secrets — one name = one group of env values (e.g. openrouter = {OPENROUTER_API_KEY}).
+    `env` carries plaintext values; this is the WRITE-direction allow-list field (goal 15)."""
+
+    # F6: write-direction plaintext carrier — hide_input_in_errors so a malformed body's ValidationError
+    # str() never echoes the raw secret value (symmetric with SecretInfo). RUNTIME config, no schema change.
+    model_config = ConfigDict(extra="forbid", hide_input_in_errors=True)
+
+    name: str
+    env: dict[str, str] = Field(..., description="ENV_KEY → value; write-only, never echoed back")
+
+
+class SecretInfo(BaseModel):
+    """GET /v1/secrets element — metadata only, NO values. Exposes `env_keys`, not `env`."""
+
+    # hide_input_in_errors: if a malformed wire response carries a value-bearing extra field, extra="forbid"
+    # raises ValidationError; without this, its str() would echo the raw input (the secret value). Defense in
+    # depth so no caller that forgets to guard model_validate can leak it. RUNTIME config, not a wire shape —
+    # does NOT change the serialized schema, so CONTRACT_VERSION is unaffected.
+    model_config = ConfigDict(extra="forbid", hide_input_in_errors=True)
+
+    name: str
+    env_keys: list[str] = Field(..., description="The env var names in this secret — values withheld")
+    created_at: datetime
+    last_used_at: datetime | None = None
+
+
+class BootstrapResponse(BaseModel):
+    """POST /v1/internal/bootstrap (worker instance-identity JWT) — everything a worker needs to serve
+    direct TLS `/act`. `direct_secret` + `tls_key` are DOWN-direction platform secrets; `env` is the
+    WRITE-direction injection of the policy's declared user secrets into its subprocess (goal 15)."""
+
+    # F6: carries down-direction platform secrets + write-direction user env — hide_input_in_errors so a
+    # malformed body's ValidationError never echoes plaintext (symmetric with SecretInfo). RUNTIME config.
+    model_config = ConfigDict(extra="forbid", hide_input_in_errors=True)
+
+    direct_secret: str = Field(..., description="Platform-minted bearer the worker's guard checks")
+    tls_key: str = Field(..., description="Self-signed TLS private key (down-direction platform secret)")
+    tls_cert: str = Field(..., description="Self-signed TLS certificate (public)")
+    env: dict[str, str] = Field(..., description="Policy's user secrets, expanded ENV_KEY → value")
+    weights_uri: str
+    lease: Lease
+
+
+class UsageReport(BaseModel):
+    """POST /v1/internal/usage — the worker's async metering report. Carries counts only, no secrets.
+    This usage shape is defined here (sequence-base) once, so gateway and worker cannot drift."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    deployment_id: str
+    window_start: datetime
+    window_end: datetime
+    requests: int
+    controlled_seconds: float

sequence_base/contract/act.py

@@ -0,0 +1,89 @@
+"""
+Shared /act contract — the obs/action shapes used by the robot SDK, the gateway, and the
+container harness. One definition, three consumers, so the wire format cannot drift.
+
+Extracted verbatim (fields) from general-sequences/backend/sequences/api/schema.py. Only the
+core DATA types live here; request/response/perf envelopes (ActRequest, ActResponse, ActPerf …)
+stay in the gateway, which is their only consumer.
+"""
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ImageFrame(BaseModel):
+    """One camera frame at one instant. Repeat a `view` (ordered by timestamp_ms) for a series."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    view: str = Field(..., description="Logical view name, e.g. top / wrist_left / exterior_1. "
+                                       "May appear more than once to express a time series")
+    # URLs are NOT fetched — the string is passed to the worker untouched (an SSRF guard would be
+    # needed before ever dereferencing one). {schema.py:76}
+    data: str = Field(..., description="Base64-encoded image (PNG or JPEG). URLs are not fetched.")
+    timestamp_ms: int | None = Field(default=None,
+                                     description="Orders multiple frames of a view; array order used when omitted")
+
+
+class Proprioception(BaseModel):
+    """Proprioceptive state. Only joint_positions is required; the rest is zero-padded per model."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    joint_positions: list[float] = Field(..., description="Joint angles, in radians")
+    joint_velocities: list[float] | None = None
+    # [x,y,z, qx,qy,qz,qw]; the quaternion avoids gimbal lock from Euler angles.
+    end_effector_pose: list[float] | None = Field(default=None, min_length=7, max_length=7)
+    # A list, not a scalar: a dual-arm setup has two grippers.
+    gripper: list[float] | None = None
+
+
+class Observation(BaseModel):
+    """The robot's world at one instant: camera frames + proprioception + a language instruction."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    # max_length bounds the frame COUNT (not bytes; body size is capped by the gateway middleware).
+    # 256 clears the widest catalogue window while refusing a memory-exhaustion list. {schema.py:97}
+    images: list[ImageFrame] = Field(..., min_length=1, max_length=256)
+    proprioception: Proprioception
+    instruction: str
+
+
+class ActionSpace(str, Enum):
+    """Must be explicit: the same floats mean opposite things across spaces — executing an absolute
+    joint position as a delta flings the arm into its limit stops. {schema.py:124}"""
+
+    JOINT_ABSOLUTE = "joint_absolute"
+    JOINT_DELTA = "joint_delta"
+    EE_ABSOLUTE = "ee_absolute"
+    EE_DELTA = "ee_delta"
+
+
+class ActionStep(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    index: int
+    values: list[float]
+
+
+class ActionChunk(BaseModel):
+    """A chunk of actions. `covers_seconds` is what the robot schedules the next request against —
+    it must ask again before this much motion finishes playing out."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    steps: list[ActionStep]
+    # Echoed back, not left to the caller: the same floats mean different things per body, and the
+    # caller may not be the code that chose the model.
+    robot: str
+    action_space: ActionSpace
+    action_dim: int
+    control_frequency_hz: float
+    covers_seconds: float
+    # How many steps to execute before asking again; None → execute the whole chunk.
+    open_loop_horizon: int | None = None
+    # How long the executed steps (open_loop_horizon of them) keep the arm moving.
+    sustains_seconds: float | None = None

sequence_base/contract/benchmarks.py

@@ -0,0 +1,130 @@
+"""
+契约 5 (registration half) — benchmark is a second authorizable artifact, its registration symmetric to
+a policy's. `BenchmarkSpec` carries the same infra declaration a PolicySpec does, plus a structured
+`Conditions` (the eval matrix), versioned `assets` volumes, an optional `render` (mp4) declaration, and
+SeqFlags→method bindings covering SETUP / RESET / CHECK / SCORE. The eval *run* wire types (RolloutResult,
+EvalReport, …) live in contract/eval.py.
+
+eval-raw revision: the platform provides the reset→step→check loop as a tool; the user hooks the goal in.
+`Step` is what `@seq.check` returns each step (platform never invents a success metric — the user names
+them); `RenderSpec` (a.k.a. `seq.Record`) declares the mp4 the platform records. Note `Step` here is the
+benchmark per-step result — a different type from ImageSpec's build `ImageStep*` variants.
+"""
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from sequence_base.contract.accounts import SecretRef
+from sequence_base.contract.flags import BENCHMARK_BINDABLE, SeqFlags
+from sequence_base.contract.policy import ImageSpec, VolumeRef
+
+__all__ = [
+    "Variant",
+    "Conditions",
+    "RenderSpec",
+    "Step",
+    "BenchmarkSpec",
+    "BenchmarkRegisterRequest",
+]
+
+
+class Variant(BaseModel):
+    """One structured variant axis of the eval matrix (e.g. axis="lighting", values=["day","night"])."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    axis: str
+    values: list[str]
+
+
+class Conditions(BaseModel):
+    """The eval matrix — structured, not a bare dict. `tasks` and `seeds` required; `variants` optional."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    tasks: list[str]
+    seeds: list[int]
+    variants: list[Variant] = Field(default_factory=list)
+
+
+class RenderSpec(BaseModel):
+    """a.k.a. `seq.Record` — declares the mp4 the platform records (money-shot is a platform tool, not user
+    glue). `camera` picks which camera stream to pull frames from; `fps` is the output frame rate. Used two
+    ways: as `BenchmarkSpec.render` (record the whole eval) and as `Step.record` (a per-frame hint)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    camera: str = Field(..., description="Which camera to pull frames from, e.g. 'wrist' / 'agentview'")
+    fps: int = 30
+
+
+class Step(BaseModel):
+    """What `@seq.check` returns each step. The platform settles each env per-step from this and NEVER
+    invents a success metric — `done` is the user's call, and `metrics` keys are user-named (the platform
+    neither enumerates nor validates the names; each value must be a float). A per-frame `record` hint may
+    ask the platform to record this frame into the mp4."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    done: bool
+    terminated: bool = False
+    truncated: bool = False
+    metrics: dict[str, float] = Field(
+        default_factory=dict, description="User-named metrics; platform does not know the field names"
+    )
+    record: RenderSpec | None = None
+
+
+class BenchmarkSpec(BaseModel):
+    """What `@seq.benchmark(...)` accrues — symmetric to PolicySpec. `secrets` are by-name only (accounts
+    ⑦: a benchmark also references secrets by name). `assets` are versioned scene/mesh/URDF/MJCF/USD volumes
+    the worker mounts at /assets (reusing S2's Volume mechanism). `render` optionally declares the mp4.
+    `max_steps` is the platform SAFETY cap (cost backstop, records `truncated` — NOT semantic termination;
+    `done` is decided by @seq.check). `bindings` covers SETUP / RESET / CHECK / SCORE (ROLLOUT is deprecated
+    and must not appear)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    image: ImageSpec
+    conditions: Conditions
+    max_steps: int = Field(..., description="Platform safety cap; truncates and records truncated")
+    handler_ref: str
+    bindings: dict[SeqFlags, str] = Field(..., description="SETUP / RESET / CHECK / SCORE → method name")
+    gpu: str | list[str] | None = None
+    assets: list[VolumeRef] = Field(default_factory=list)
+    render: RenderSpec | None = None
+    cpu: int | None = None
+    memory_gb: int | None = None
+    secrets: list[SecretRef] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def _bindings_only_benchmark_hooks(self) -> "BenchmarkSpec":
+        # eval-raw: only SETUP / RESET / CHECK / SCORE are bindable. ROLLOUT is deprecated (never bound) and
+        # a policy-lifecycle flag has no place here — either is a malformed registration, caught at build.
+        bad = set(self.bindings) - set(BENCHMARK_BINDABLE)
+        if bad:
+            names = ", ".join(sorted(f.name or str(f.value) for f in bad))
+            raise ValueError(
+                f"benchmark bindings may only cover SETUP / RESET / CHECK / SCORE; got disallowed {names}"
+                " (ROLLOUT is deprecated and must not be bound)"
+            )
+        return self
+
+
+class BenchmarkRegisterRequest(BaseModel):
+    """POST /v1/benchmarks — register body, same types as the spec (ImageSpec / Conditions / VolumeRef /
+    RenderSpec). Carries assets / render / cpu / memory_gb / max_steps so the gateway can build the image,
+    provision the `assets` Volume, and register in one call."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    image: ImageSpec
+    conditions: Conditions
+    max_steps: int
+    handler_ref: str
+    assets: list[VolumeRef] = Field(default_factory=list)
+    render: RenderSpec | None = None
+    cpu: int | None = None
+    memory_gb: int | None = None

sequence_base/contract/connect.py

@@ -0,0 +1,53 @@
+"""
+契约 3 — connect / lease (client → gateway; control plane, first call + renewal).
+
+Control plane / data plane split: `connect(model)` goes through the gateway once (admission → acquire →
+ensure worker up) and hands back the *direct* coordinates the client then uses to hit the worker's
+`/act` without the gateway in the hot path (契约 4). The cold-start fallback is a defined wire body,
+not an HTTP header alone — a 503 returns `WarmingError` (contract/errors.py), so `503 + Retry-After`
+and the warming ETA are typed and checkable.
+"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# The 503 cold/warming body is defined once in contract.errors and reused here — no second shape.
+from sequence_base.contract.errors import WarmingError
+
+__all__ = ["Lease", "ConnectRequest", "ConnectResponse", "WarmingError"]
+
+
+class Lease(BaseModel):
+    """A time-boxed grant of the direct coordinates. Renewed before `expires_at`; `epoch` is the
+    worker/secret generation — a client holding a stale epoch against a new worker gets 401 and must
+    re-connect."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    ttl_s: int
+    expires_at: datetime
+    epoch: int = Field(..., description="Worker/secret generation counter; rolls on worker change")
+
+
+class ConnectRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    model: str = Field(..., description="Deployment name to connect to")
+
+
+class ConnectResponse(BaseModel):
+    """200 — the full set of coordinates for a direct worker connection.
+
+    `direct_secret` is a plaintext platform-minted bearer for the worker's `/act`; it is on the
+    allow-list of fields permitted to carry a secret value in the down direction (契约 6 / goal 15)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    worker_url: str = Field(..., description="Worker static-IP direct URL, e.g. https://<ip>:8080")
+    cert_fingerprint: str = Field(..., description="Self-signed cert fingerprint the SDK pins")
+    direct_secret: str = Field(..., description="Bearer for the worker /act; valid within the lease")
+    lease: Lease
+    warming: bool = Field(default=False, description="True → worker still warming; see warming_eta_s")
+    warming_eta_s: int | None = Field(default=None, description="Seconds until warm, when warming")

sequence_base/contract/deployments.py

@@ -0,0 +1,197 @@
+"""
+契约 2 — `POST /v1/deployments` (SDK `seq deploy` → gateway) and its responses.
+
+The request is the normalized wire form of a PolicySpec: one big body (à la Modal's single `Function`
+message — new config adds a field, never a new endpoint) whose sub-shapes reuse contract 1's types
+(ImageSpec, VolumeMount, Concurrency, ActionContract). Field names align with the PolicySpec side —
+`gpu` is normalized to list[str] here, the memory field is `memory_gb` (goal 7).
+
+Responses have no open-ended fields: 202 → status fixed to `building`; GET → status is a restricted
+enum building | ready | failed, with a failure channel (`error`) when failed (goal 8).
+"""
+from __future__ import annotations
+
+import base64
+import binascii
+import hashlib
+from enum import Enum
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from sequence_base.contract.accounts import SecretRef
+from sequence_base.contract.policy import (
+    ActionContract,
+    Concurrency,
+    ImageSpec,
+    VolumeMount,
+)
+
+__all__ = [
+    "MAX_CODE_BUNDLE_BYTES",
+    "CodeBundle",
+    "Resources",
+    "Autoscaler",
+    "Timeouts",
+    "VolumeAttach",
+    "DeploymentPolicy",
+    "DeploymentRequest",
+    "DeploymentAccepted",
+    "DeploymentState",
+    "DeploymentStatusResponse",
+]
+
+
+class Resources(BaseModel):
+    """= Modal Resources + GPUConfig. `gpu` is list[str] (the PolicySpec `str | list[str]` normalized)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    gpu: list[str]
+    cpu: int
+    memory_gb: int
+
+
+class Autoscaler(BaseModel):
+    """= Modal AutoscalerSettings. Defaults mirror PolicySpec so an omitted block scale-to-zeroes."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    min_containers: int = 0
+    max_containers: int | None = None
+    buffer_containers: int | None = None
+    scaledown_window: int = 600
+
+
+class Timeouts(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    request: int
+    startup: int
+
+
+class VolumeAttach(BaseModel):
+    """A non-weights volume mount in the deploy body (goal 7). Distinct from `weights` (a `VolumeMount`,
+    a provisioned pull at the reserved `/data`): an explicit `volumes=` attachment names a persistent
+    volume by `vol://<name>` ref, pins its container `mount`, and carries the `create_if_missing`
+    provisioning intent so the gateway either binds an existing volume or creates it — the semantic the
+    wire `VolumeMount` deliberately does not carry. Not reused/extended from `VolumeMount` because
+    `create_if_missing` is meaningless for the weights pull."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    uri: str
+    mount: str
+    create_if_missing: bool
+
+
+class DeploymentPolicy(BaseModel):
+    """The policy block of the deployments body. `handler_ref` and `action` are required; `action` is the
+    fixed obs→ActionChunk contract, not a bare dict.
+
+    `secrets` carries the policy's declared secret BUNDLES BY NAME ONLY (list[SecretRef]) — the gateway
+    validates each name exists and belongs to the deployer at submit time (accounts ⑦ / S3 goal 14), and the
+    worker bootstrap fetches the matching env group by name. A secret VALUE never travels here: SecretRef is
+    name-only, so this field cannot carry one (S3 goal 15). Defaults to `[]` so a policy with no secrets is
+    unaffected."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    handler_ref: str
+    action: ActionContract
+    streaming: bool = False
+    frames_per_chunk: int | None = None
+    secrets: list[SecretRef] = Field(default_factory=list)
+
+
+MAX_CODE_BUNDLE_BYTES = 8 * 1024 * 1024
+"""Upper bound on the compressed code bundle. Policy source is kilobytes; anything near this is weights or
+data that belongs in `weights` / a volume, and the bound keeps the deploy body well under the gateway's
+request limit (base64 adds a third)."""
+
+
+class CodeBundle(BaseModel):
+    """The policy's own source, shipped with the deploy so the worker can import `policy.handler_ref`
+    (what Modal's automount does for the entrypoint module). A gzip'd tar of the handler's top-level module
+    or package, base64 on the wire, with the sha256 of the decoded bytes so a truncated or altered upload
+    is refused at the edge instead of failing as an ImportError on a GPU."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    format: Literal["tar.gz"] = "tar.gz"
+    data: str
+    sha256: str
+
+    @model_validator(mode="after")
+    def _intact(self) -> "CodeBundle":
+        raw = self.raw()
+        if len(raw) > MAX_CODE_BUNDLE_BYTES:
+            raise ValueError(f"code bundle is {len(raw)} bytes; the limit is {MAX_CODE_BUNDLE_BYTES} "
+                             "(ship weights/data via `weights` or a volume, not with the code)")
+        if hashlib.sha256(raw).hexdigest() != self.sha256:
+            raise ValueError("code bundle sha256 does not match its data")
+        return self
+
+    def raw(self) -> bytes:
+        try:
+            return base64.b64decode(self.data, validate=True)
+        except binascii.Error as exc:
+            raise ValueError(f"code bundle data is not valid base64: {exc}") from None
+
+    @classmethod
+    def from_bytes(cls, raw: bytes) -> "CodeBundle":
+        return cls(data=base64.b64encode(raw).decode("ascii"), sha256=hashlib.sha256(raw).hexdigest())
+
+
+class DeploymentRequest(BaseModel):
+    """The full `POST /v1/deployments` body. Required: name, image, weights, resources, policy (goal 18).
+    autoscaler / concurrency / timeouts are typed optional knobs with sane defaults."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    image: ImageSpec
+    weights: VolumeMount
+    resources: Resources
+    policy: DeploymentPolicy
+    # The handler's source. None only when `handler_ref` is importable from the image itself (a package the
+    # ImageSpec installs); otherwise the worker has nothing to import and the build fails.
+    code: CodeBundle | None = None
+    # Non-weights volumes the policy declares (goal 7). List, not dict, so a mount is never duplicated as
+    # both key and value; the gateway only stores the dump, no consumer needs dict lookup.
+    volumes: list[VolumeAttach] = Field(default_factory=list)
+    autoscaler: Autoscaler = Field(default_factory=Autoscaler)
+    # An omitted @seq.concurrent must NOT send null: the gateway would then have no concurrency to scale by.
+    # Materialize the spec default — contracts.md §2's example {"max_inputs": 1, "target_inputs": 1}, i.e.
+    # one input per container (Modal's no-`@modal.concurrent` semantics) — same discipline as `autoscaler`
+    # (goal 13).
+    concurrency: Concurrency = Field(default_factory=lambda: Concurrency(max_inputs=1, target_inputs=1))
+    timeouts: Timeouts | None = None
+
+
+class DeploymentAccepted(BaseModel):
+    """202 — the build is async; the id comes back first, status pinned to `building`."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    deployment_id: str
+    status: Literal["building"] = "building"
+
+
+class DeploymentState(str, Enum):
+    """GET status — a restricted enum, not a free string (same discipline as EvalStatus)."""
+
+    BUILDING = "building"
+    READY = "ready"
+    FAILED = "failed"
+
+
+class DeploymentStatusResponse(BaseModel):
+    """GET /v1/deployments/{id}. `error` carries the build-failure reason when status is FAILED —
+    the failure channel the spec and the old goal both lacked (goal 8)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    status: DeploymentState
+    model: str
+    error: str | None = Field(default=None, description="Build-failure reason; set only when FAILED")

sequence_base/contract/errors.py

@@ -0,0 +1,45 @@
+"""
+Shared error-body wire types (契约 4 / 契约 6 client semantics). These are the *bodies* returned to a
+client on the sad path — distinct from `sequence_base.errors.transport`, which is the internal
+exception taxonomy the gateway / harness raise. Defined here once so "is an error response a wire
+type?" has one answer: yes, and this is its shape.
+
+    402  OutOfCredit    → ErrorBody(code=OUT_OF_CREDIT)     (connect / lease renew / eval balance)
+    401  Unauthorized   → ErrorBody(code=UNAUTHORIZED)      (secret expired / epoch rolled)
+    503  Warming        → WarmingError(code=WARMING, ...)   (worker cold / warming; carries retry hints)
+
+`WarmingError` is the single definition of the 503 body: contract 3's connect cold-path (503 +
+Retry-After / warming eta) reuses it rather than declaring a second {retry_after_s, eta_s} shape.
+"""
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ErrorCode(str, Enum):
+    """Restricted set — a client switches on this, so it is an enum, not a free string."""
+
+    OUT_OF_CREDIT = "out_of_credit"
+    UNAUTHORIZED = "unauthorized"
+    WARMING = "warming"
+
+
+class ErrorBody(BaseModel):
+    """The base error body (402 / 401): a machine-readable `code` plus a human `message`."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    code: ErrorCode
+    message: str
+
+
+class WarmingError(ErrorBody):
+    """503 body — worker cold / warming. Adds the two retry hints so `503 + Retry-After` and the
+    warming ETA are expressible in the type, not smuggled in an HTTP header alone. `code` defaults to
+    WARMING; a caller waits `retry_after_s` and, when known, learns `eta_s` until hot."""
+
+    code: ErrorCode = ErrorCode.WARMING
+    retry_after_s: int
+    eta_s: int | None = Field(default=None, description="Seconds until warm, when estimable")