@evolvingmachines/sdk 0.0.50 → 0.0.52-launch-round-1.20260803.37a56fe

package/spec/openapi.yaml

@@ -0,0 +1,4031 @@
+openapi: 3.1.0
+
+info:
+  title: Evolve Evaluations API
+  version: 2.0.0
+  summary: Hosted evaluations — datasets, jobs, trials, agents.
+  description: |
+    The single source of truth for the renamed hosted-evaluations surface.
+
+    ## Vocabulary
+    Four nouns, used everywhere and without exception:
+    - **dataset** — a named, versioned set of tasks.
+    - **job** — one run: datasets x agents x attempts.
+    - **trial** — one attempt of one task by one agent. Trial ids are globally
+      addressable: no route requires the job id to reach a trial.
+    - **agent** — the thing that attempts a task (a harness plus a model).
+      Registered private agents live under `/api/agents`.
+
+    Wire fields are `snake_case`, except the individually frozen historical
+    keys named in the deviations below — nothing else is exempt.
+
+    ## Documented deviations (kept deliberately)
+    - **Status enums.** `Job.status` (6 members) and `Trial.status` (8 members)
+      are load-bearing: they drive cancel, watch exit codes, resume and regrade
+      eligibility, and the `?status=` filters. `verifier_result` and
+      `exception_info` are published alongside, never instead.
+    - **Cursor pagination.** Every collection is `{items, nextCursor, hasMore}`
+      with opaque keyset cursors — these three keys are frozen verbatim.
+      Offset paging duplicates and skips rows on a live, growing collection.
+    - **Idempotency.** `Idempotency-Key` on every job-creating POST, surfaced
+      as `idempotent_replay` on the job body. A hosted double-run
+      double-charges a customer.
+    - **SSE events.** `GET /api/jobs/{jobId}/events` is the progress display
+      for a run that executes on someone else's machine. Event *type* names
+      are frozen; event payload fields speak this document's vocabulary.
+    - **Money.** Spend enforcement is ours: `max_trial_spend_usd` (the only
+      enforced budget — a per-trial cap minted onto the trial's gateway key),
+      `worst_case_spend_usd` (stated, never left to the caller to multiply),
+      and the live lower-bound pair `live_spent_usd` / `live_spend_at`.
+      Measured spend travels as `cost_usd` (job: `stats.cost_usd`; trial:
+      `agent_result.cost_usd`).
+    - **Typed error catalog.** A closed 52-code union; every error response is
+      one envelope: `{code, message, param, details, retryAfterSec, requestId}`
+      (envelope keys frozen verbatim).
+    - **Two frozen camelCase field keys.** `trials.byStatus` (the trial-status
+      tally on job bodies) and `taskMatrix` (on the compare response) keep
+      their exact historical spellings, same as the pagination and error
+      envelope keys above. These four spots are the complete list of
+      non-`snake_case` keys on the wire.
+    - **Cancel and stop.** `POST /api/jobs/{jobId}/cancel` and
+      `POST /api/trials/stop` exist because a hosted run cannot be Ctrl-C'd.
+    - **Resume semantics.** `POST /api/jobs/{jobId}/resume` creates a NEW
+      linked job (`source_jobs`), keeping the original immutable and
+      separately citable. It never mutates the source job.
+    - **Compare cap.** `GET /api/jobs/compare` takes 2–10 ids. Bounded, not
+      unbounded: one GET must not become an unbounded server-side fan-out.
+
+    ## Wave sequencing
+    Anything marked `x-wave: 2` belongs to the second build wave: today the
+    `trajectory` artifact selector (not yet served) and the API-key
+    management pair (served, not yet in the SDKs). Everything unmarked is
+    live end to end.
+
+    ## Deliberately absent (wave 3, not yet specified)
+    The rename map's additive rows are new capabilities, not renames, and are
+    intentionally NOT in this document: job sharing
+    (`GET /api/jobs/{jobId}/shares`, `POST /api/jobs/{jobId}/share`), copying
+    (`POST /api/jobs/{jobId}/copy`, `POST /api/trials/{trialId}/copy`), job
+    deletion (`DELETE /api/jobs/{jobId}`), dataset visibility
+    (`POST /api/datasets/{name}/visibility` — public/private toggling arrives
+    with the registry/sharing model), and the leaderboard family. They
+    will be specified when they are designed; their absence here is a
+    decision, not an omission.
+
+servers:
+  - url: /
+    description: The platform origin. All paths are origin-relative.
+
+security:
+  - apiKey: []
+
+tags:
+  - name: jobs
+    description: Create, read, watch, cancel, resume, regrade, download, compare.
+  - name: trials
+    description: Globally addressable trials — read, trace, regrade, stop.
+  - name: datasets
+    description: Catalog, publish (async import), package download, activation.
+  - name: agents
+    description: Bring-your-own agents (private to their owner).
+  - name: meta
+    description: Public capability document.
+  - name: auth
+    description: Key and identity surface.
+
+paths:
+  # ===========================================================================
+  # Jobs
+  # ===========================================================================
+
+  /api/jobs:
+    post:
+      tags: [jobs]
+      operationId: createJob
+      summary: Start a job
+      description: |
+        Starts a job over one or more catalog datasets. Accepted (202) as soon
+        as the trials are recorded; execution is asynchronous — follow
+        `GET /api/jobs/{jobId}/events` or poll `GET /api/jobs/{jobId}`.
+
+        Datasets are a LIST with per-dataset glob filters (`task_names`,
+        `exclude_task_names`, `n_tasks`); each selector filters only its own
+        dataset, and the job's trials are the union across the list. The same
+        dataset name twice is refused (`invalid_input`). Every agent must name
+        a model; the server applies no model default.
+
+        The response is the job body plus `job_id`, an additive alias of `id`
+        that only this verb answers with — see JobCreated.
+
+        Send `Idempotency-Key` to make retries safe: the same key with the
+        same resolved request replays the original job (200,
+        `idempotent_replay: true`); the same key with a different request is
+        refused with `idempotency_key_reused` (409). Dataset references are
+        fingerprinted RESOLVED — a bare name and the currently active version
+        fingerprint alike while that version is active. The dataset list is
+        fingerprinted IN ORDER: `datasets` echoes the request order back, so
+        the same selectors reordered are a different request and a shared key
+        across the two orders is refused rather than silently replayed.
+      parameters:
+        - $ref: '#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/JobCreate'
+      responses:
+        '202':
+          description: Job created and queued.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/JobCreated'
+        '200':
+          description: Idempotent replay of an existing identical request.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/JobCreated'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '402':
+          description: Out of credits (`insufficient_credits`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          $ref: '#/components/responses/Conflict'
+        '422':
+          description: >
+            Job too large (`job_too_large`) or a task refused by the chosen
+            provider (`provider_unsupported`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+    get:
+      tags: [jobs]
+      operationId: listJobs
+      summary: List jobs
+      description: Newest first. Every filter is server-side.
+      parameters:
+        - $ref: '#/components/parameters/Limit'
+        - $ref: '#/components/parameters/Cursor'
+        - name: status
+          in: query
+          description: Filter by job status (repeatable).
+          schema:
+            type: array
+            items:
+              $ref: '#/components/schemas/JobStatus'
+          explode: true
+        - name: agent
+          in: query
+          description: Filter by agent name (repeatable).
+          schema:
+            type: array
+            items:
+              type: string
+          explode: true
+        - name: model
+          in: query
+          description: Filter by model name (repeatable).
+          schema:
+            type: array
+            items:
+              type: string
+          explode: true
+        - name: sandbox_provider
+          in: query
+          description: Filter by sandbox provider (repeatable).
+          schema:
+            type: array
+            items:
+              $ref: '#/components/schemas/SandboxProvider'
+          explode: true
+        - name: dataset
+          in: query
+          description: Filter to jobs that ran a given dataset name.
+          schema:
+            type: string
+        - name: is_regrade
+          in: query
+          description: >
+            true returns only regrade jobs; false only non-regrade jobs.
+            Replaces the retired standalone regrade listing — a regrade IS a
+            job.
+          schema:
+            type: boolean
+        - name: search
+          in: query
+          description: Free-text filter over job name and dataset names.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: One page of jobs.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/JobPage'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/jobs/compare:
+    get:
+      tags: [jobs]
+      operationId: compareJobs
+      summary: Compare jobs
+      description: |
+        Side-by-side comparison of 2–10 owned jobs: per-job aggregates plus a
+        per-task matrix. Matrix cells report `MIXED` when a cell's trials
+        disagree in status and `MISSING` when a job has no trials for a task;
+        disagreement rows sort first.
+      parameters:
+        - name: ids
+          in: query
+          required: true
+          description: Comma-separated job ids (2–10).
+          schema:
+            type: string
+            examples: ["9f2c1a7e-...,4b8d0e21-..."]
+      responses:
+        '200':
+          description: Comparison payload.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CompareResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/jobs/{jobId}:
+    get:
+      tags: [jobs]
+      operationId: getJob
+      summary: Get one job
+      parameters:
+        - $ref: '#/components/parameters/JobId'
+      responses:
+        '200':
+          description: The job.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Job'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/jobs/{jobId}/cancel:
+    post:
+      tags: [jobs]
+      operationId: cancelJob
+      summary: Cancel a job
+      description: |
+        Requests cancellation: QUEUED/RUNNING moves to CANCELLING (compare-and-
+        set with retries), queued trials are cancelled outright, and in-flight
+        trials are STOPPED — sandboxes killed, spend read honestly — through
+        the same per-trial machinery as `POST /api/trials/stop` before the job
+        settles CANCELLED. Idempotent — calling it on a job already CANCELLING
+        or terminal returns the current body.
+      parameters:
+        - $ref: '#/components/parameters/JobId'
+      responses:
+        '200':
+          description: The job after the cancel request.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Job'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          description: Lost a concurrent status race after retries (`concurrent_update`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/jobs/{jobId}/events:
+    get:
+      tags: [jobs]
+      operationId: watchJob
+      summary: Job event stream (SSE)
+      description: |
+        `text/event-stream` of the job's lifecycle. Each SSE message has
+        `id` = the event's monotonic `seq`, `event` = the event type, and
+        `data` = the JSON payload for that type.
+
+        Event types (frozen): `job.created`, `job.running`, `job.cancelling`,
+        `job.cancelled`, `job.completed`, `job.failed` (reserved — declared
+        terminal, no server path emits it today), `trial.running`,
+        `trial.scoring`, `trial.spend`, `trial.settled`.
+
+        Resume with the standard `Last-Event-ID` header or `?after=<seq>` —
+        both mean "events strictly after this sequence number". Heartbeat
+        comments (`:`) are sent every 15s; clients must skip comment lines.
+      parameters:
+        - $ref: '#/components/parameters/JobId'
+        - name: after
+          in: query
+          description: Resume position — deliver events with seq strictly greater.
+          schema:
+            type: integer
+            minimum: 0
+        - name: Last-Event-ID
+          in: header
+          description: Standard SSE resume header; same meaning as `?after=`.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: The event stream. Ends after the terminal job event.
+          content:
+            text/event-stream:
+              schema:
+                $ref: '#/components/schemas/JobEvent'
+        '400':
+          description: Bad resume position (`invalid_after`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/jobs/{jobId}/download:
+    get:
+      tags: [jobs]
+      operationId: downloadJob
+      summary: Download a job's results archive
+      description: |
+        A gzipped archive of the job in the standard results layout
+        (`config.json`, `result.json`, per-trial `config.json`/`result.json`).
+        Only terminal jobs are downloadable. The archive is deterministic:
+        sorted keys at every depth, no generation timestamp, zero gzip mtime.
+        Task environment identity only — instructions, verifier commands, and
+        test files never leave the server.
+      parameters:
+        - $ref: '#/components/parameters/JobId'
+      responses:
+        '200':
+          description: The archive.
+          content:
+            application/gzip:
+              schema:
+                type: string
+                format: binary
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          description: Job is not terminal (`job_not_terminal`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/jobs/{jobId}/resume:
+    post:
+      tags: [jobs]
+      operationId: resumeJob
+      summary: Resume a job (new linked job over its failed and stopped trials)
+      description: |
+        Creates a NEW job holding fresh trials for the source job's failed
+        and stopped work, linked back via `source_jobs` (`action: "resume"`).
+        The source job is never mutated — the original run stays immutable and
+        separately citable.
+
+        `filter_error_types` selects which failures to resume by their
+        `exception_info.exception_type`; omitted, the default set is
+        `["ScoringError", "InfrastructureError", "IncompleteTrialError"]`
+        plus stopped trials (settled CANCELLED, exception type
+        `CancelledError`) and any still-QUEUED trials of a cancelled source.
+        The source job must be terminal.
+
+        Supports `Idempotency-Key` with a fingerprint namespaced to this
+        route, so a create key can never replay a resume.
+      parameters:
+        - $ref: '#/components/parameters/JobId'
+        - $ref: '#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ResumeRequest'
+      responses:
+        '202':
+          description: The new linked job.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Job'
+        '200':
+          description: Idempotent replay of an identical resume request.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Job'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '402':
+          description: Out of credits (`insufficient_credits`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          description: >
+            Source not terminal (`job_not_terminal`), nothing to resume
+            (`no_failed_trials`), or `idempotency_key_reused`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/jobs/{jobId}/regrade:
+    post:
+      tags: [jobs]
+      operationId: regradeJob
+      summary: Regrade a job (verifier-only re-run)
+      description: |
+        Re-runs verification over a terminal job's trials. **The response is a
+        Job**: a regrade is an ordinary job whose `source_jobs` records
+        `action: "regrade"` and whose `is_regrade` is true. View it with
+        `GET /api/jobs/{jobId}`; there is no separate regrade resource.
+        The source job and its trials are immutable.
+
+        The optional filter narrows which trials are regraded. Decision order:
+        404 (unknown job) → 409 `job_not_terminal` → 409 `no_regradable_trials`
+        → 202.
+      parameters:
+        - $ref: '#/components/parameters/JobId'
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RegradeRequest'
+      responses:
+        '202':
+          description: The regrade job.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Job'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          description: >
+            `job_not_terminal`, `no_regradable_trials`, or
+            `regrade_source_ineligible` (a pre-cutover job with no inputs
+            bundle can never be regraded).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/jobs/{jobId}/trials:
+    get:
+      tags: [jobs]
+      operationId: listJobTrials
+      summary: List a job's trials
+      description: |
+        One page of the job's trials. List rows truncate
+        `exception_info.exception_message` to 2000 characters; the trial
+        detail route returns it untruncated. Reading a page refreshes the
+        live-spend lower bound on in-flight trials.
+      parameters:
+        - $ref: '#/components/parameters/JobId'
+        - $ref: '#/components/parameters/Limit'
+        - $ref: '#/components/parameters/Cursor'
+        - name: status
+          in: query
+          description: Filter by trial status — repeatable and/or comma-separated.
+          schema:
+            type: array
+            items:
+              $ref: '#/components/schemas/TrialStatus'
+          explode: true
+        - name: task_name
+          in: query
+          description: Filter to one task's trials.
+          schema:
+            type: string
+        - name: dataset
+          in: query
+          description: >
+            Filter to one dataset's trials — exact match on the trial's
+            `source`. A name the job does not span is an ordinary empty
+            selection.
+          schema:
+            type: string
+        - name: failed_only
+          in: query
+          description: Only trials in a failure status.
+          schema:
+            type: boolean
+      responses:
+        '200':
+          description: One page of trials.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TrialPage'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/jobs/{jobId}/tasks:
+    get:
+      tags: [jobs]
+      operationId: listJobTasks
+      summary: Per-task rollup of a job
+      description: |
+        One row per distinct task: its trial-status histogram, mean reward
+        over SCORED trials, and measured cost. Sits between the job body and
+        the trial list so a caller need not fetch every trial to see which
+        tasks are dragging.
+      parameters:
+        - $ref: '#/components/parameters/JobId'
+        - $ref: '#/components/parameters/Limit'
+        - $ref: '#/components/parameters/Cursor'
+      responses:
+        '200':
+          description: One page of task rollups.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/JobTaskRollupPage'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  # ===========================================================================
+  # Trials (globally addressable)
+  # ===========================================================================
+
+  /api/trials/{trialId}:
+    get:
+      tags: [trials]
+      operationId: getTrial
+      summary: Get one trial
+      description: >
+        A trial id is globally addressable — no job id in the path. The body
+        carries `job_id` for the reverse pointer. Detail responses return
+        `exception_info` untruncated.
+      parameters:
+        - $ref: '#/components/parameters/TrialId'
+      responses:
+        '200':
+          description: The trial.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Trial'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/trials/{trialId}/trace:
+    get:
+      tags: [trials]
+      operationId: getTrialTrace
+      summary: Trial trace and artifacts
+      description: |
+        Without `stream` (or with `stream=trace-parsed`, the same answer by
+        its vocabulary name): one page of parsed trace events, paged by
+        `cursor` (a sequence number) and `limit` (default 200, max 1000).
+
+        With `stream`: raw artifacts instead of parsed events —
+        - `verifier`, `trace-stdout`, `trace-stderr`, `trajectory` (wave 2):
+          the log text as JSON (`{"log": string | null}`; null means this
+          trial never stored that log — a normal answer, never an error).
+          With `format=log` a present log is delivered as a `text/plain`
+          attachment; an absent one still answers the JSON `{"log": null}`.
+        - `agent-home`: the agent home tree as JSON
+          (`{"files": {"<sandbox-path>": "<text>", ...} | null}`; null means
+          nothing was collected). With `format=tgz` a present tree is
+          delivered as a gzipped tarball; an absent one still answers the
+          JSON `{"files": null}`.
+      parameters:
+        - $ref: '#/components/parameters/TrialId'
+        - name: cursor
+          in: query
+          description: Sequence position to page from (parsed-event mode).
+          schema:
+            type: string
+        - name: limit
+          in: query
+          description: Page size (parsed-event mode). Default 200, max 1000.
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 1000
+            default: 200
+        - name: stream
+          in: query
+          description: >
+            Raw artifact selector. `trajectory` is in the vocabulary ahead of
+            its server wave: until that wave lands the route answers
+            not-found for it, reported as the API error it is.
+          schema:
+            type: string
+            enum:
+              - trace-parsed # the parsed event trace — same answer as omitting
+              - verifier
+              - trace-stdout
+              - trace-stderr
+              - trajectory   # x-wave: 2 — normalized-trajectory artifact slot
+              - agent-home
+        - name: format
+          in: query
+          description: >
+            `log` (text/plain, log selectors only) or `tgz` (gzipped tarball,
+            agent-home only).
+          schema:
+            type: string
+            enum: [log, tgz]
+      responses:
+        '200':
+          description: Trace events, or the selected artifact.
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - $ref: '#/components/schemas/TraceEventPage'
+                  - type: object
+                    description: >
+                      Log selector JSON form; `log` is null when this trial
+                      never stored that log — a normal answer, never an error.
+                    required: [log]
+                    properties:
+                      log:
+                        type: [string, 'null']
+                  - type: object
+                    description: >
+                      Agent-home JSON form — sandbox path to file text; `files`
+                      is null when nothing was collected, which no other shape
+                      can express.
+                    required: [files]
+                    properties:
+                      files:
+                        type: [object, 'null']
+                        additionalProperties:
+                          type: string
+            text/plain:
+              schema:
+                type: string
+                description: '`format=log` delivery of a log selector.'
+            application/gzip:
+              schema:
+                type: string
+                format: binary
+                description: '`format=tgz` delivery of agent-home.'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/trials/{trialId}/regrade:
+    post:
+      tags: [trials]
+      operationId: regradeTrial
+      summary: Regrade one trial
+      description: |
+        Verifier-only re-run of a single trial. **The response is a Job** — a
+        one-trial regrade job with `source_jobs` recording the provenance.
+        The source trial is immutable.
+      parameters:
+        - $ref: '#/components/parameters/TrialId'
+      responses:
+        '202':
+          description: The regrade job.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Job'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          description: >
+            `job_not_terminal`, `no_regradable_trials`, or
+            `regrade_source_ineligible`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/trials/stop:
+    post:
+      tags: [trials]
+      operationId: stopTrials
+      summary: Stop selected running trials
+      description: |
+        Stops individual in-flight trials without cancelling their job: each
+        trial's sandbox is killed and the trial is settled with its spend read
+        from the gateway. Only the caller's own trials; ids belonging to
+        someone else are reported in `not_found` (existence is never leaked).
+        Idempotent — already-terminal trials are reported as such and left
+        untouched.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/StopRequest'
+      responses:
+        '200':
+          description: Per-trial outcome of the stop request.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/StopResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  # ===========================================================================
+  # Datasets
+  # ===========================================================================
+
+  /api/datasets:
+    get:
+      tags: [datasets]
+      operationId: listDatasets
+      summary: List datasets
+      description: >
+        The catalog: public datasets plus the caller's own private ones.
+        Another user's private dataset is invisible, never 403. A dataset
+        whose every version is FAILED is not listed either — no partial
+        corpus ever exists, and that includes the catalog view. The name
+        still answers `GET /api/datasets/{name}` (and DELETE), and the
+        failed import stays readable at its import id, so nothing about the
+        failure is hidden; re-publishing the same name simply retries it.
+      parameters:
+        - $ref: '#/components/parameters/Limit'
+        - $ref: '#/components/parameters/Cursor'
+        - name: search
+          in: query
+          description: Free-text filter over name and description.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: One page of datasets (summary fields only).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DatasetPage'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/datasets/{name}:
+    get:
+      tags: [datasets]
+      operationId: getDataset
+      summary: Get one dataset
+      description: >
+        Detail view: all versions, the active version, upstream status, and
+        one page of the selected version's tasks (`limit`/`cursor` page the
+        task list; `version` selects which version's tasks are listed).
+      parameters:
+        - $ref: '#/components/parameters/DatasetName'
+        - name: version
+          in: query
+          description: Version whose tasks to list; default the active version.
+          schema:
+            type: string
+        - $ref: '#/components/parameters/Limit'
+        - $ref: '#/components/parameters/Cursor'
+      responses:
+        '200':
+          description: The dataset.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Dataset'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+    patch:
+      tags: [datasets]
+      operationId: updateDataset
+      summary: Update dataset settings
+      description: |
+        The only settable field is `upstream_auto_import`: automatically
+        import a new version when the dataset's upstream git ref moves.
+        Refused with `upstream_not_watchable` (409) when the dataset has no
+        moving git ref to follow, and 403 on platform-curated datasets.
+      parameters:
+        - $ref: '#/components/parameters/DatasetName'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/DatasetPatch'
+      responses:
+        '200':
+          description: The updated dataset.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Dataset'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          description: Platform-curated dataset (`dataset_not_owned`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          description: Nothing to watch (`upstream_not_watchable`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+    delete:
+      tags: [datasets]
+      operationId: deleteDataset
+      summary: Delete an owned dataset
+      parameters:
+        - $ref: '#/components/parameters/DatasetName'
+      responses:
+        '204':
+          description: Deleted.
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          description: Not the owner (`dataset_not_owned`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          description: >
+            In use by jobs (`dataset_in_use`); `details` names the blocking
+            job ids.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/datasets/{name}/download:
+    get:
+      tags: [datasets]
+      operationId: downloadDataset
+      summary: Download a dataset version's source package
+      description: |
+        The original uploaded corpus tarball for one of the caller's own
+        dataset versions (owner only). The server verifies the stored sha256
+        before streaming and echoes it in `x-package-sha256`; clients should
+        verify the digest and the Content-Length.
+      parameters:
+        - $ref: '#/components/parameters/DatasetName'
+        - name: version
+          in: query
+          description: Version to download; default the active version.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: The gzipped source package.
+          headers:
+            x-package-sha256:
+              description: Hex sha256 of the exact bytes streamed.
+              schema:
+                type: string
+                pattern: '^[a-f0-9]{64}$'
+          content:
+            application/gzip:
+              schema:
+                type: string
+                format: binary
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          description: >
+            Package unavailable: `package_not_retained`, `package_corrupt`,
+            or `package_missing`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/datasets/{name}/versions/{version}/activate:
+    post:
+      tags: [datasets]
+      operationId: activateDatasetVersion
+      summary: Activate a dataset version
+      description: |
+        Promotes a READY (or VALIDATING-complete) version to the dataset's
+        active version, making bare-name job references resolve to it.
+
+        You usually do not need this. A version you publish is activated for
+        you the moment its activation gate passes — VALIDATING becomes READY
+        and the dataset's default points at it, with no call. What this verb
+        is for is choosing a DIFFERENT default: rolling back to an older
+        READY version, or re-pointing at one auto-activation moved past.
+
+        The proof it requires is the same activation gate, which the worker
+        schedules automatically after a hosted import: the gold solution
+        scores exactly 1.0 through the real execution path, and a do-nothing
+        agent does not. While the gate is scheduled or running the verb
+        answers 202 `gate_running` (a healthy in-progress state, not an
+        error); once it lands, activation either promotes (200) or explains
+        (409 `version_not_ready`, with the gate's failure detail in
+        `details.gate_failure`). Refused with `version_not_activatable` when
+        the version can never be activated (for example, no reference
+        solutions were archived — see the import's `warnings`).
+
+        Idempotent: activating the version that is already active rewrites
+        the same pointer and answers 200.
+      parameters:
+        - $ref: '#/components/parameters/DatasetName'
+        - name: version
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: The dataset with its new active version.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Dataset'
+        '202':
+          description: >
+            Not yet — the activation gate is scheduled or running for this
+            version. Nothing is wrong and nothing is asked of the caller:
+            poll the dataset (each version carries `gate`). A gate that
+            PASSES activates the version itself, so there is normally
+            nothing left to call.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/GateRunning'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          description: Not the owner (`dataset_not_owned`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          description: '`version_not_ready` or `version_not_activatable`.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/datasets/publish:
+    post:
+      tags: [datasets]
+      operationId: publishDataset
+      summary: Publish a dataset version (async import)
+      description: |
+        Starts a server-side import that creates or extends a catalog dataset
+        with one new immutable version. Multipart only. Source is exactly one
+        of: a git repository (`git_url` + pinned `git_ref` — https only, an
+        unpinned import is not reproducible) or an uploaded gzipped tarball
+        (`archive`).
+
+        The import is asynchronous: the 202 returns a DatasetImport to poll at
+        `GET /api/datasets/imports/{importId}`. Name collisions are checked
+        before the upload lands; oversized uploads are fast-rejected on
+        Content-Length (413). The name `imports` is reserved (it is a literal
+        path segment under `/api/datasets`) and is refused like any other
+        invalid name.
+
+        Once the import COMPLETES, the worker automatically schedules the
+        activation gate (the version's `gate` field tracks it: PENDING ->
+        RUNNING -> PASSED/FAILED). When it PASSES, the version becomes READY
+        and the dataset's active version on its own — publish, poll until
+        `gate.status` is PASSED, and run the dataset by bare name. A version
+        with no archived reference solutions gets no gate — its import
+        `warnings` say so, and activation is refused
+        `version_not_activatable`.
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              $ref: '#/components/schemas/PublishRequest'
+      responses:
+        '202':
+          description: The import job.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DatasetImport'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '409':
+          description: '`dataset_name_taken` or `dataset_version_not_found` conflicts.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '413':
+          description: Archive over the size cap (`import_too_large`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/datasets/imports:
+    get:
+      tags: [datasets]
+      operationId: listDatasetImports
+      summary: List the caller's imports
+      parameters:
+        - $ref: '#/components/parameters/Limit'
+        - $ref: '#/components/parameters/Cursor'
+        - name: status
+          in: query
+          schema:
+            $ref: '#/components/schemas/DatasetImportStatus'
+        - name: dataset
+          in: query
+          description: Filter to imports of one dataset name.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: One page of imports.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DatasetImportPage'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/datasets/imports/{importId}:
+    get:
+      tags: [datasets]
+      operationId: getDatasetImport
+      summary: Poll one import
+      description: >
+        Imports of public datasets are pollable by anyone; private ones are
+        owner-only and read 404 (never 403) for anyone else.
+      parameters:
+        - name: importId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: The import.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DatasetImport'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  # ===========================================================================
+  # Agents (bring-your-own)
+  # ===========================================================================
+
+  /api/agents:
+    post:
+      tags: [agents]
+      operationId: registerAgent
+      summary: Register a private agent
+      description: |
+        Registers a bring-your-own agent. Once registered, its `name` is
+        usable in `agents[].name` on job creation exactly like a built-in.
+        Source is exactly one of: an `install_script` (runs in a throwaway
+        builder sandbox with internet and ZERO secrets; must leave executables
+        in `$PREFIX/bin`) or an uploaded gzipped tarball (`archive`).
+        Multipart only — nothing travels in the query string.
+
+        Registration validates SHAPE only and never executes the install
+        script: the bundle is built by the first trial that names the agent,
+        and a failing build settles that trial as an infrastructure error
+        with the builder's stdout/stderr stored on it (readable through the
+        trial's `trace-stdout` / `trace-stderr` streams). Line endings in
+        `install_script` and `run_command` are normalized CRLF -> LF on
+        receipt — multipart transports rewrite text-field newlines to CRLF,
+        which is never meaningful in shell text.
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              $ref: '#/components/schemas/AgentRegistration'
+      responses:
+        '201':
+          description: The registered agent.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Agent'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '409':
+          description: >
+            `agent_name_taken`, `agent_name_reserved`, `agent_source_conflict`,
+            or `agent_limit_reached`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '413':
+          description: Upload over the size cap (`agent_too_large`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+    get:
+      tags: [agents]
+      operationId: listAgents
+      summary: List the caller's registered agents
+      parameters:
+        - $ref: '#/components/parameters/Limit'
+        - $ref: '#/components/parameters/Cursor'
+      responses:
+        '200':
+          description: One page of agents.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AgentPage'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/agents/{name}:
+    get:
+      tags: [agents]
+      operationId: getAgent
+      summary: Get one registered agent
+      description: >
+        Private to its owner — another user's agent name reads
+        `agent_not_found`, never a permission error.
+      parameters:
+        - $ref: '#/components/parameters/AgentName'
+      responses:
+        '200':
+          description: The agent.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Agent'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+    put:
+      tags: [agents]
+      operationId: upsertAgent
+      summary: Create or replace a registered agent
+      parameters:
+        - $ref: '#/components/parameters/AgentName'
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              $ref: '#/components/schemas/AgentRegistration'
+      responses:
+        '200':
+          description: The agent after the upsert.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Agent'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '409':
+          description: '`agent_name_reserved` or `agent_source_conflict`.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '413':
+          description: Upload over the size cap (`agent_too_large`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+    delete:
+      tags: [agents]
+      operationId: deleteAgent
+      summary: Delete a registered agent
+      parameters:
+        - $ref: '#/components/parameters/AgentName'
+      responses:
+        '204':
+          description: Deleted.
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  # ===========================================================================
+  # Meta
+  # ===========================================================================
+
+  /api/meta:
+    get:
+      tags: [meta]
+      operationId: getMeta
+      summary: Capability document (no auth)
+      security: []
+      description: >
+        Everything a client would otherwise hardcode: agents (built-in and
+        registration rules), sandbox providers with sizing ceilings and
+        refusals, platform constraints, network modes, status vocabularies
+        with their terminal members, limits, and the closed error-code list.
+        Public and cacheable — weak ETag, 304 support, `max-age=300`.
+      parameters:
+        - name: If-None-Match
+          in: header
+          schema:
+            type: string
+      responses:
+        '200':
+          description: The capability document.
+          headers:
+            ETag:
+              schema:
+                type: string
+            Cache-Control:
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CapabilityDocument'
+        '304':
+          description: Not modified.
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  # ===========================================================================
+  # Auth
+  # ===========================================================================
+
+  /api/auth/status:
+    get:
+      tags: [auth]
+      operationId: getAuthStatus
+      summary: Who am I
+      description: >
+        Identifies the caller and the API key used, so `auth status` in
+        clients has a server answer.
+      responses:
+        '200':
+          description: The caller's identity.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AuthStatus'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/auth/keys:
+    get:
+      tags: [auth]
+      operationId: listApiKeys
+      summary: List the caller's API keys
+      x-wave: 2
+      description: Secrets are never returned.
+      parameters:
+        - $ref: '#/components/parameters/Limit'
+        - $ref: '#/components/parameters/Cursor'
+      responses:
+        '200':
+          description: One page of key descriptors.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiKeyPage'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/auth/keys/{keyId}:
+    delete:
+      tags: [auth]
+      operationId: revokeApiKey
+      summary: Revoke an API key
+      x-wave: 2
+      description: Revocation is immediate.
+      parameters:
+        - name: keyId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '204':
+          description: Revoked.
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+# =============================================================================
+# Components
+# =============================================================================
+
+components:
+  securitySchemes:
+    apiKey:
+      type: http
+      scheme: bearer
+      description: >
+        `Authorization: Bearer <API key>`. Required on everything except
+        `GET /api/meta`.
+
+  parameters:
+    JobId:
+      name: jobId
+      in: path
+      required: true
+      schema:
+        type: string
+        format: uuid
+    TrialId:
+      name: trialId
+      in: path
+      required: true
+      schema:
+        type: string
+        format: uuid
+    DatasetName:
+      name: name
+      in: path
+      required: true
+      description: >
+        A dataset's catalog name. `imports` is a reserved name — it is a
+        literal path segment under `/api/datasets` — and publish refuses it,
+        so `/api/datasets/imports/{importId}` can never collide with a
+        dataset route.
+      schema:
+        type: string
+    AgentName:
+      name: name
+      in: path
+      required: true
+      schema:
+        type: string
+    Limit:
+      name: limit
+      in: query
+      description: Page size. Collection default 50, max 200 (dataset tasks 200/500).
+      schema:
+        type: integer
+        minimum: 1
+    Cursor:
+      name: cursor
+      in: query
+      description: >
+        Opaque keyset cursor from a previous page's `nextCursor`. Never
+        constructed by the client.
+      schema:
+        type: string
+    IdempotencyKey:
+      name: Idempotency-Key
+      in: header
+      required: false
+      description: |
+        Client-chosen key that makes the POST safe to retry. The same key
+        with the same resolved request returns the original resource (200,
+        `idempotent_replay: true`); the same key with a different request is
+        refused with `idempotency_key_reused` (409). Keys are namespaced per
+        route and per caller.
+      schema:
+        type: string
+        maxLength: 200
+
+  responses:
+    BadRequest:
+      description: >
+        Malformed request — `invalid_json`, `invalid_input`, `invalid_limit`,
+        `invalid_status`, `invalid_cursor`, `invalid_format`, `invalid_ids`,
+        `invalid_multipart`, `invalid_archive`, `unknown_task_names`, or
+        `no_tasks`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    Unauthorized:
+      description: >
+        `missing_authorization`, `invalid_api_key`, or (503-adjacent, still
+        this envelope) `credential_service_unavailable`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    NotFound:
+      description: >
+        The addressed resource does not exist or is not visible to the
+        caller. Existence is never leaked: someone else's private resource
+        reads 404, not 403.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    Conflict:
+      description: State conflict; the `code` names which law was hit.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    TooManyRequests:
+      description: '`rate_limited`. Honor `Retry-After`.'
+      headers:
+        Retry-After:
+          schema:
+            type: integer
+        X-RateLimit-Limit:
+          schema:
+            type: integer
+        X-RateLimit-Remaining:
+          schema:
+            type: integer
+        X-RateLimit-Reset:
+          schema:
+            type: integer
+            description: Epoch seconds when the window resets.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    InternalError:
+      description: '`internal_error`; carries `requestId` for support.'
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+
+  schemas:
+    # -------------------------------------------------------------------------
+    # Errors
+    # -------------------------------------------------------------------------
+
+    ErrorCode:
+      type: string
+      description: |
+        The closed error-code union (52 members). Published at runtime by
+        `GET /api/meta` (`error_codes`); no route ever answers with a code
+        outside this list.
+      enum:
+        # Auth + throttling
+        - missing_authorization
+        - invalid_api_key
+        - credential_service_unavailable
+        - rate_limited
+        - insufficient_credits
+        # Request shape
+        - invalid_json
+        - invalid_input
+        - invalid_limit
+        - invalid_status
+        - invalid_cursor
+        - invalid_after
+        - invalid_format
+        - invalid_ids
+        - invalid_multipart
+        - idempotency_key_reused
+        # Datasets
+        - dataset_not_found
+        - dataset_version_not_found
+        - dataset_name_taken
+        - dataset_in_use
+        - dataset_not_owned
+        - upstream_not_watchable
+        - no_active_version
+        - version_not_ready
+        - version_not_activatable
+        - unknown_task_names
+        - no_tasks
+        # Registered agents
+        - agent_not_found
+        - agent_name_taken
+        - agent_name_reserved
+        - agent_invalid_name
+        - agent_source_required
+        - agent_source_conflict
+        - agent_invalid_env
+        - agent_too_large
+        - agent_limit_reached
+        # Jobs + trials
+        - agent_version_not_found
+        - job_too_large
+        - provider_unsupported
+        - job_not_found
+        - job_not_terminal
+        - no_failed_trials
+        - trial_not_found
+        - concurrent_update
+        # Regrade
+        - regrade_source_ineligible
+        - no_regradable_trials
+        # Imports
+        - import_not_found
+        - import_too_large
+        - invalid_archive
+        # Retained source package (owner-only download)
+        - package_not_retained
+        - package_corrupt
+        - package_missing
+        # Fallback
+        - internal_error
+
+    Error:
+      type: object
+      description: |
+        The ONE error envelope, under the top-level key `error`. Envelope keys
+        are frozen verbatim (documented deviation). `details` is open — each
+        code carries the machine-readable shape its own refusal needs (a list
+        of task names, a provider and per-task reasons, a ceiling and the
+        value that breached it, the blocking job ids).
+      required: [error]
+      properties:
+        error:
+          type: object
+          required: [code, message]
+          properties:
+            code:
+              $ref: '#/components/schemas/ErrorCode'
+            message:
+              type: string
+              description: Human-readable; never parse it — parse `code`.
+            param:
+              type: [string, 'null']
+              description: The input field the caller got wrong, in the caller's vocabulary.
+            details:
+              type: [object, 'null']
+              additionalProperties: true
+            retryAfterSec:
+              type: [integer, 'null']
+              description: Present on retryable refusals; mirrors the Retry-After header.
+            requestId:
+              type: string
+              description: Correlates with server logs; quote it in support requests.
+
+    # -------------------------------------------------------------------------
+    # Shared enums and small shapes
+    # -------------------------------------------------------------------------
+
+    JobStatus:
+      type: string
+      description: >
+        Job lifecycle (kept deviation — load-bearing for cancel, watch exit,
+        download gating, and resume/regrade eligibility). Terminal: COMPLETED,
+        CANCELLED, FAILED.
+      enum: [QUEUED, RUNNING, CANCELLING, COMPLETED, CANCELLED, FAILED]
+
+    TrialStatus:
+      type: string
+      description: |
+        Trial lifecycle (kept deviation). The status law: a valid reward
+        (including 0) = SCORED; a verifier crash or out-of-domain reward =
+        SCORING_ERROR (never a fabricated zero); INFRASTRUCTURE_ERROR = the
+        trial was lost before a result was recorded; INDETERMINATE = the
+        platform cannot tell whether the trial completed. Terminal: SCORED,
+        SCORING_ERROR, INFRASTRUCTURE_ERROR, INDETERMINATE, CANCELLED.
+      enum:
+        - QUEUED
+        - RUNNING
+        - SCORING
+        - SCORED
+        - SCORING_ERROR
+        - INFRASTRUCTURE_ERROR
+        - INDETERMINATE
+        - CANCELLED
+
+    SandboxProvider:
+      type: string
+      description: Where trials execute. Spelled identically on every surface.
+      enum: [e2b, daytona, modal]
+
+    SpendSource:
+      type: string
+      description: >
+        Which lane a settled trial's `agent_result.cost_usd` is in. `measured`
+        is final. The other two are PRE-CONFIRMATION lanes a freshly settled
+        trial commonly holds for a few minutes, served verbatim because the
+        lane is the only signal that the figure is still provisional:
+        `measured_provisional` is an honest floor read inside the gateway's
+        async spend flush (it can only be raised), and `assumed_cap` means
+        nothing was measured yet — it holds a zero placeholder, never an
+        invented figure. A deferred pass confirms or raises both from the
+        gateway's spend logs.
+      enum: [measured, measured_provisional, assumed_cap]
+
+    VerifierEnvironmentMode:
+      type: string
+      description: >
+        Where the verifier ran — inside the agent's environment (shared) or
+        in a separate one.
+      enum: [shared, separate]
+
+    AttemptPhase:
+      type: string
+      description: >
+        Which step a RUNNING trial is in, so a polling caller can tell a slow
+        build from a slow agent — RUNNING alone cannot.
+      enum: [prepare, build, boot, install, agent, verify, persist]
+
+    TrialStatusTally:
+      type: object
+      description: >
+        The one "how many" shape: a total plus a histogram over EVERY trial
+        status, zeros included, so a UI draws its status bar off the response
+        instead of hardcoding the enum.
+      required: [total, byStatus]
+      properties:
+        total:
+          type: integer
+          minimum: 0
+        byStatus:
+          type: object
+          description: One integer per TrialStatus member, zeros included.
+          required:
+            - QUEUED
+            - RUNNING
+            - SCORING
+            - SCORED
+            - SCORING_ERROR
+            - INFRASTRUCTURE_ERROR
+            - INDETERMINATE
+            - CANCELLED
+          properties:
+            QUEUED: { type: integer, minimum: 0 }
+            RUNNING: { type: integer, minimum: 0 }
+            SCORING: { type: integer, minimum: 0 }
+            SCORED: { type: integer, minimum: 0 }
+            SCORING_ERROR: { type: integer, minimum: 0 }
+            INFRASTRUCTURE_ERROR: { type: integer, minimum: 0 }
+            INDETERMINATE: { type: integer, minimum: 0 }
+            CANCELLED: { type: integer, minimum: 0 }
+
+    # -------------------------------------------------------------------------
+    # Job — config side
+    # -------------------------------------------------------------------------
+
+    DatasetRef:
+      type: object
+      description: A resolved dataset reference as echoed on job bodies.
+      required: [name, version]
+      properties:
+        name:
+          type: string
+        version:
+          type: string
+
+    DatasetSelector:
+      type: object
+      description: |
+        One dataset a job runs, with per-dataset task filters. `task_names`
+        and `exclude_task_names` are glob patterns; `n_tasks` caps the task
+        count AFTER filtering. A bare `name` resolves to the active version
+        (`no_active_version` when none).
+      required: [name]
+      properties:
+        name:
+          type: string
+          description: Catalog dataset name.
+        version:
+          type: string
+          description: Pin a version; omitted, the active version is used.
+        task_names:
+          type: array
+          description: Include filter — glob patterns over task names.
+          items:
+            type: string
+        exclude_task_names:
+          type: array
+          description: Exclude filter — glob patterns over task names.
+          items:
+            type: string
+        n_tasks:
+          type: integer
+          minimum: 1
+          description: Cap the task count after filters are applied.
+
+    AgentArmInput:
+      type: object
+      description: >
+        One agent arm of a job: an agent (built-in or registered) plus a
+        model. A model is always required; the server applies no default.
+      required: [name, model_name]
+      properties:
+        name:
+          type: string
+          description: Agent name — a built-in or one registered under /api/agents.
+        model_name:
+          type: string
+        version:
+          type: string
+          description: >
+            Pin an agent version; omitted, the platform resolves the latest
+            supported (`agent_version_not_found` when a pin cannot resolve).
+        reasoning_effort:
+          type: string
+          description: >
+            Platform extension — declared effort, part of arm identity.
+            Accepted values published by /api/meta; omitted, the runner
+            default applies.
+
+    AgentArm:
+      type: object
+      description: One agent arm as echoed on job bodies.
+      required: [name, model_name, version, reasoning_effort]
+      properties:
+        name:
+          type: string
+        model_name:
+          type: string
+        version:
+          type: [string, 'null']
+          description: The requested pin; null when the run took the latest.
+        reasoning_effort:
+          type: [string, 'null']
+          description: Declared effort; null when the run took the runner default.
+
+    SourceJob:
+      type: object
+      description: >
+        Provenance of a derived job. `action: regrade` = verifier-only re-run
+        of the source; `action: resume` (platform extension) = new job over
+        the source's failed and stopped trials. `type` is always `hub` on
+        this hosted surface.
+      required: [action, type, job_id]
+      properties:
+        action:
+          type: string
+          enum: [regrade, resume]
+        type:
+          type: string
+          enum: [hub]
+        job_id:
+          type: string
+          format: uuid
+
+    JobCreate:
+      type: object
+      description: The job-creation body.
+      required: [datasets, agents]
+      properties:
+        job_name:
+          type: string
+          maxLength: 200
+          description: >
+            User-facing label; server-generated when omitted. A LABEL, not an
+            identity: names are not unique, and two jobs may carry the same
+            one (Harbor's job name is a local directory and resumes in place;
+            a hosted registry keeps `id` as the only identity). Reuse a name
+            freely across runs; to prevent accidental double submission use
+            Idempotency-Key, which replays by request, not by name.
+        datasets:
+          type: array
+          minItems: 1
+          items:
+            $ref: '#/components/schemas/DatasetSelector'
+        agents:
+          type: array
+          minItems: 1
+          maxItems: 8
+          items:
+            $ref: '#/components/schemas/AgentArmInput'
+        n_attempts:
+          type: integer
+          minimum: 1
+          maximum: 100
+          default: 1
+          description: Attempts per task per agent arm.
+        n_concurrent_trials:
+          type: integer
+          minimum: 1
+          maximum: 16
+          default: 4
+          description: Parallel trials across the job.
+        max_trial_spend_usd:
+          type: number
+          minimum: 0
+          description: |
+            Per-trial spend cap in USD, minted onto each trial's gateway key —
+            the platform's ONLY spend enforcement (there is no job-wide
+            budget). Default published by /api/meta (200 unless the operator
+            tuned it).
+        sandbox_provider:
+          $ref: '#/components/schemas/SandboxProvider'
+        agent_env:
+          type: object
+          additionalProperties:
+            type: string
+          description: >
+            Env injected into every agent run — a pass-through slot: the
+            client sends it verbatim and the server owns acceptance (refused
+            where unsupported, never silently dropped).
+        verifier_env:
+          type: object
+          additionalProperties:
+            type: string
+          description: >
+            Env injected into every verifier run — same pass-through
+            contract.
+
+    ResumeRequest:
+      type: object
+      description: Body of POST /api/jobs/{jobId}/resume.
+      properties:
+        filter_error_types:
+          type: array
+          description: |
+            Which failures to resume, matched against
+            `exception_info.exception_type`. Omitted, the default set is
+            `["ScoringError", "InfrastructureError", "IncompleteTrialError"]`
+            plus stopped trials (settled CANCELLED, exception type
+            `CancelledError`) and still-QUEUED trials of a cancelled source.
+          items:
+            type: string
+
+    RegradeRequest:
+      type: object
+      description: >
+        Optional filter narrowing which trials a job-level regrade re-runs.
+        Omitted, every regradable trial is regraded.
+      properties:
+        statuses:
+          type: array
+          items:
+            $ref: '#/components/schemas/TrialStatus'
+        task_name:
+          type: string
+          description: Restrict to one task's trials.
+
+    # -------------------------------------------------------------------------
+    # Job — result side
+    # -------------------------------------------------------------------------
+
+    AgentDatasetStats:
+      type: object
+      description: |
+        Per-(agent, model, dataset) statistics. The evals key format is
+        `{agent}__{model}__{dataset}` — the dataset ref is always the LAST
+        `__` segment, which is where Harbor-compatible readers recover it —
+        with the platform extension of an `__{effort}` segment inserted
+        BEFORE the dataset when a declared reasoning effort is part of the
+        arm identity: `{agent}__{model}__{effort}__{dataset}`.
+      properties:
+        n_trials:
+          type: integer
+          minimum: 0
+          description: Trials that produced a rewards map — rewarded, not merely settled.
+        n_errors:
+          type: integer
+          minimum: 0
+          description: >
+            Trials carrying `exception_info` — indeterminate and cancelled
+            included.
+        metrics:
+          type: array
+          description: >
+            Metric results (a mean entry per arm today: the primary reward
+            averaged over EVERY trial of the group, unrewarded trials
+            counting 0); open objects so new metric types need no wire
+            change.
+          items:
+            type: object
+            additionalProperties: true
+        pass_at_k:
+          type: object
+          description: >
+            pass@k slot — keys are k as strings, values in [0,1]. Present and
+            empty until the platform computes it; the slot exists so adding
+            the statistic is not a wire change.
+          additionalProperties:
+            type: number
+        reward_stats:
+          type: object
+          description: 'reward key -> reward value -> trial identifiers.'
+          additionalProperties:
+            type: object
+            additionalProperties:
+              type: array
+              items:
+                type: string
+        exception_stats:
+          type: object
+          description: 'exception type -> trial identifiers.'
+          additionalProperties:
+            type: array
+            items:
+              type: string
+
+    JobStats:
+      type: object
+      description: |
+        Aggregate statistics of a job. Progress counters, token totals, and
+        measured cost. The `n_*` counters are CUMULATIVE, Harbor-style:
+        errored trials are a subset of completed, cancelled a subset of
+        errored — a cancelled trial counts in all three. The disjoint
+        per-status breakdown rides `Job.trials.byStatus`.
+        `cost_usd` is what the trials actually spent so far — reporting,
+        never a gate (enforcement is the per-trial cap).
+      properties:
+        n_completed_trials:
+          type: integer
+          minimum: 0
+          description: >
+            Cumulative: every trial that produced a result — errored and
+            cancelled included, never the scored subset alone.
+        n_errored_trials:
+          type: integer
+          minimum: 0
+          description: >
+            Cumulative: every completed trial carrying `exception_info`,
+            cancelled included. A subset of `n_completed_trials`.
+        n_running_trials:
+          type: integer
+          minimum: 0
+        n_pending_trials:
+          type: integer
+          minimum: 0
+        n_cancelled_trials:
+          type: integer
+          minimum: 0
+          description: A subset of `n_errored_trials`.
+        n_retries:
+          type: integer
+          minimum: 0
+        evals:
+          type: object
+          description: >
+            Keyed `{agent}__{model}__{dataset}` — dataset ref last, with the
+            optional effort segment inserted before it.
+          additionalProperties:
+            $ref: '#/components/schemas/AgentDatasetStats'
+        n_input_tokens:
+          type: [integer, 'null']
+          description: Total input tokens (cache included); null until recorded.
+        n_cache_tokens:
+          type: [integer, 'null']
+        n_output_tokens:
+          type: [integer, 'null']
+        cost_usd:
+          type: [number, 'null']
+          description: Measured spend across settled trials; null before any settled.
+
+    JobFailure:
+      type: object
+      description: >
+        Why a job FAILED — deliberately NOT under the key `error`, which on
+        this surface always means "this request failed". `if (body.error)
+        throw` stays correct on a healthy 200 read of a failed job.
+      required: [code, message]
+      properties:
+        code:
+          type: string
+          description: '`job_execution_failed` when the runner recorded no code.'
+        message:
+          type: string
+
+    Job:
+      type: object
+      description: |
+        THE job body — the same shape from create, get, list items, cancel,
+        resume, and regrade responses; no field appears on some responses and
+        not others. The create verb answers with JobCreated, which is this
+        shape plus one aliased id and nothing else.
+      required:
+        - id
+        - job_name
+        - status
+        - datasets
+        - agents
+        - n_attempts
+        - n_concurrent_trials
+        - max_trial_spend_usd
+        - worst_case_spend_usd
+        - sandbox_provider
+        - counts
+        - n_total_trials
+        - trials
+        - stats
+        - failure
+        - source_jobs
+        - is_regrade
+        - idempotent_replay
+        - started_at
+        - updated_at
+        - finished_at
+      properties:
+        id:
+          type: string
+          format: uuid
+        job_name:
+          type: string
+          description: User-facing label.
+        status:
+          $ref: '#/components/schemas/JobStatus'
+        datasets:
+          type: array
+          description: The resolved dataset references this job ran.
+          items:
+            $ref: '#/components/schemas/DatasetRef'
+        agents:
+          type: array
+          items:
+            $ref: '#/components/schemas/AgentArm'
+        n_attempts:
+          type: integer
+          minimum: 1
+        n_concurrent_trials:
+          type: integer
+          minimum: 1
+        max_trial_spend_usd:
+          type: number
+          description: The resolved per-trial cap every trial key was minted with.
+        worst_case_spend_usd:
+          type: number
+          description: |
+            The most this job can cost: every trial spending its whole cap.
+            Stated outright — the per-trial cap is the only enforcement, so
+            the product is the number someone approving a 500-trial run
+            actually needs to see.
+        sandbox_provider:
+          $ref: '#/components/schemas/SandboxProvider'
+        counts:
+          type: object
+          description: Entity cardinality only — things with no status of their own.
+          required: [agents, tasks]
+          properties:
+            agents:
+              type: integer
+              minimum: 0
+            tasks:
+              type: integer
+              minimum: 0
+        n_total_trials:
+          type: integer
+          minimum: 0
+        trials:
+          $ref: '#/components/schemas/TrialStatusTally'
+          description: >
+            Kept deviation — the zeros-included 8-status histogram, published
+            alongside the coarser counters in `stats`.
+        stats:
+          $ref: '#/components/schemas/JobStats'
+        failure:
+          oneOf:
+            - $ref: '#/components/schemas/JobFailure'
+            - type: 'null'
+        source_jobs:
+          type: array
+          description: Empty for an original job.
+          items:
+            $ref: '#/components/schemas/SourceJob'
+        is_regrade:
+          type: boolean
+          description: 'Derived: any source_jobs entry with action "regrade".'
+        idempotent_replay:
+          type: boolean
+          description: True only on a response that replayed an existing job for an Idempotency-Key.
+        started_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+        finished_at:
+          type: [string, 'null']
+          format: date-time
+          description: Null while the job is live.
+
+    JobCreated:
+      description: |
+        The CREATE verb's body: the whole Job shape plus `job_id`, an additive
+        alias of `id`.
+
+        The alias exists for one reason and lives in one place. Harbor's
+        hosted submit reads the new job's id under the key `job_id` and aborts
+        the submit outright when that key is absent, so the verb an
+        unmodified Harbor CLI starts a run with answers to both names. Every
+        other job response — get, list, cancel, resume, regrade — carries `id`
+        alone, so no reader has to learn a second spelling to follow a job.
+
+        Both of this verb's success bodies carry it: a create and the
+        idempotent replay of that same create (their submit sends an
+        `Idempotency-Key` on every attempt, so a retry lands on the replay).
+      required: [job_id]
+      allOf:
+        - $ref: '#/components/schemas/Job'
+        - type: object
+          properties:
+            job_id:
+              type: string
+              format: uuid
+              description: Alias of `id`, identical value. Create responses only.
+
+    JobPage:
+      type: object
+      description: Cursor page of jobs (envelope keys frozen verbatim).
+      required: [items, nextCursor, hasMore]
+      properties:
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/Job'
+        nextCursor:
+          type: [string, 'null']
+          description: Pass back as `?cursor=`; null means no next page.
+        hasMore:
+          type: boolean
+
+    # -------------------------------------------------------------------------
+    # Trial
+    # -------------------------------------------------------------------------
+
+    TimingInfo:
+      type: object
+      description: >
+        A phase's wall-clock as a start/stop pair (never a duration).
+        Either bound is null while the phase has not reached it.
+      properties:
+        started_at:
+          type: [string, 'null']
+          format: date-time
+        finished_at:
+          type: [string, 'null']
+          format: date-time
+
+    ModelInfo:
+      type: object
+      required: [name]
+      properties:
+        name:
+          type: string
+        provider:
+          type: [string, 'null']
+          description: Null means "not specified", never "unknown provider".
+
+    AgentInfo:
+      type: object
+      description: |
+        The agent that ran a trial. `version` is the version actually
+        RESOLVED and used (null until resolved) — the requested pin lives on
+        the job's `agents[].version`. `reasoning_effort` is the platform's
+        arm-identity extension.
+      required: [name, version, model_info]
+      properties:
+        name:
+          type: string
+        version:
+          type: [string, 'null']
+        model_info:
+          $ref: '#/components/schemas/ModelInfo'
+        reasoning_effort:
+          type: [string, 'null']
+
+    AgentResult:
+      type: object
+      description: |
+        What the agent phase produced and consumed. `n_input_tokens` includes
+        cache tokens. `cost_usd` is the settled spend (see `spend_source` on
+        the trial for which lane it came from, and whether it is final).
+        `metadata` carries
+        open per-run detail: the harness bundle digest and runtime, the
+        network mode the trial ran under and where that decision came from,
+        and any harness-reported usage detail.
+      properties:
+        n_input_tokens:
+          type: [integer, 'null']
+        n_cache_tokens:
+          type: [integer, 'null']
+        n_output_tokens:
+          type: [integer, 'null']
+        cost_usd:
+          type: [number, 'null']
+          description: Null until the trial has executed; null never means $0.
+        rollout_details:
+          type: [array, 'null']
+          description: Reserved for token-level rollout detail; null today.
+          items:
+            type: object
+            additionalProperties: true
+        metadata:
+          type: [object, 'null']
+          additionalProperties: true
+
+    VerifierResult:
+      type: object
+      description: |
+        The verifier's rewards map. The primary-reward convention: the value
+        under the key `"reward"`; else, when exactly one key exists, that
+        value; else no primary reward. Zero is a reward.
+      properties:
+        rewards:
+          type: [object, 'null']
+          additionalProperties:
+            type: number
+
+    ExceptionInfo:
+      type: object
+      description: |
+        Why a trial failed, when it did. `exception_type` is one of the
+        platform's stable failure names (`ScoringError`,
+        `InfrastructureError`, `CancelledError`, `IncompleteTrialError`) —
+        but filter with `Trial.status`, which is the primary key for failure
+        classes; this is the detail.
+      required: [exception_type, exception_message, occurred_at]
+      properties:
+        exception_type:
+          type: string
+        exception_message:
+          type: string
+          description: Truncated to 2000 chars on list rows; full on the detail route.
+        exception_traceback:
+          type: string
+          description: Empty when the platform recorded no traceback.
+        occurred_at:
+          type: string
+          format: date-time
+
+    StepResult:
+      type: object
+      description: >
+        Placeholder for multi-step tasks. Always null on trials today —
+        declared so multi-step lands without a wire change.
+      properties:
+        step_name:
+          type: string
+        agent_result:
+          oneOf:
+            - $ref: '#/components/schemas/AgentResult'
+            - type: 'null'
+        verifier_result:
+          oneOf:
+            - $ref: '#/components/schemas/VerifierResult'
+            - type: 'null'
+        exception_info:
+          oneOf:
+            - $ref: '#/components/schemas/ExceptionInfo'
+            - type: 'null'
+        agent_execution:
+          oneOf:
+            - $ref: '#/components/schemas/TimingInfo'
+            - type: 'null'
+        verifier:
+          oneOf:
+            - $ref: '#/components/schemas/TimingInfo'
+            - type: 'null'
+
+    Trial:
+      type: object
+      description: |
+        The ONE public trial shape, shared verbatim by list rows and the
+        detail route (detail returns `exception_info.exception_message`
+        untruncated — the only documented difference).
+
+        Execution facts (`sandbox_provider`, `verifier_environment_mode`,
+        `agent_result.cost_usd`, `spend_source`) are null until the trial has
+        actually executed: a QUEUED or CANCELLED trial never ran, so null
+        means "did not run" and never zero.
+      required:
+        - id
+        - job_id
+        - task_name
+        - source
+        - agent_info
+        - attempt
+        - status
+        - reward
+        - verifier_result
+        - exception_info
+        - started_at
+        - finished_at
+      properties:
+        id:
+          type: string
+          format: uuid
+        job_id:
+          type: string
+          format: uuid
+        task_name:
+          type: string
+        source:
+          type: string
+          description: The dataset this trial's task came from.
+        agent_info:
+          $ref: '#/components/schemas/AgentInfo'
+        attempt:
+          type: integer
+          minimum: 1
+          description: 'Attempt index within the arm (1..n_attempts).'
+        status:
+          $ref: '#/components/schemas/TrialStatus'
+        reward:
+          type: [number, 'null']
+          description: >
+            Convenience primary reward derived from `verifier_result.rewards`
+            by the primary-reward convention. Zero is a reward; null means
+            the trial did not score.
+        verifier_result:
+          oneOf:
+            - $ref: '#/components/schemas/VerifierResult'
+            - type: 'null'
+        exception_info:
+          oneOf:
+            - $ref: '#/components/schemas/ExceptionInfo'
+            - type: 'null'
+        agent_result:
+          oneOf:
+            - $ref: '#/components/schemas/AgentResult'
+            - type: 'null'
+        environment_setup:
+          oneOf:
+            - $ref: '#/components/schemas/TimingInfo'
+            - type: 'null'
+        agent_setup:
+          oneOf:
+            - $ref: '#/components/schemas/TimingInfo'
+            - type: 'null'
+        agent_execution:
+          oneOf:
+            - $ref: '#/components/schemas/TimingInfo'
+            - type: 'null'
+        verifier:
+          oneOf:
+            - $ref: '#/components/schemas/TimingInfo'
+            - type: 'null'
+        step_results:
+          type: [array, 'null']
+          description: Multi-step placeholder; null today.
+          items:
+            $ref: '#/components/schemas/StepResult'
+        spend_source:
+          oneOf:
+            - $ref: '#/components/schemas/SpendSource'
+            - type: 'null'
+        live_spent_usd:
+          type: [number, 'null']
+          description: |
+            A mid-run LOWER BOUND on spend, never the trial's cost. Only ever
+            climbs while the trial runs, and is CLEARED when the trial
+            settles — on a terminal trial read `agent_result.cost_usd` and
+            `spend_source`; those are the settled truth. Null is "no reading
+            yet", never $0.
+        live_spend_at:
+          type: [string, 'null']
+          format: date-time
+          description: When that reading was taken — show its age, never the figure alone.
+        max_trial_spend_usd:
+          type: [number, 'null']
+          description: >
+            The cap THIS trial's gateway key carried — history, which can
+            differ from the job's current cap for rows settled before a
+            change.
+        sandbox_provider:
+          oneOf:
+            - $ref: '#/components/schemas/SandboxProvider'
+            - type: 'null'
+        sandbox_id:
+          type: [string, 'null']
+          description: Provider id of the box the agent executed in; null when none booted.
+        verifier_sandbox_id:
+          type: [string, 'null']
+          description: The separate verifier box; null in shared mode or when never reached.
+        verifier_environment_mode:
+          oneOf:
+            - $ref: '#/components/schemas/VerifierEnvironmentMode'
+            - type: 'null'
+        attempt_phase:
+          oneOf:
+            - $ref: '#/components/schemas/AttemptPhase'
+            - type: 'null'
+        session_ref:
+          type: [string, 'null']
+          description: Reference to the agent session/trace, when recorded.
+        started_at:
+          type: [string, 'null']
+          format: date-time
+        finished_at:
+          type: [string, 'null']
+          format: date-time
+
+    TrialPage:
+      type: object
+      required: [items, nextCursor, hasMore]
+      properties:
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/Trial'
+        nextCursor:
+          type: [string, 'null']
+        hasMore:
+          type: boolean
+
+    StopRequest:
+      type: object
+      required: [trial_ids]
+      properties:
+        trial_ids:
+          type: array
+          minItems: 1
+          maxItems: 100
+          items:
+            type: string
+            format: uuid
+
+    StopResponse:
+      type: object
+      description: Per-trial outcome; every requested id appears in exactly one list.
+      required: [stopped, already_terminal, not_found]
+      properties:
+        stopped:
+          type: array
+          description: Trials killed and settled by this request, with their settled rows.
+          items:
+            $ref: '#/components/schemas/Trial'
+        already_terminal:
+          type: array
+          description: Ids that were already terminal; untouched.
+          items:
+            type: string
+            format: uuid
+        not_found:
+          type: array
+          description: Ids that do not exist or are not the caller's.
+          items:
+            type: string
+            format: uuid
+
+    JobTaskRollup:
+      type: object
+      description: One task's rollup within a job (wave 2).
+      required: [task_name, source, trials, mean_reward, cost_usd]
+      properties:
+        task_name:
+          type: string
+        source:
+          type: string
+          description: The dataset the task came from.
+        trials:
+          $ref: '#/components/schemas/TrialStatusTally'
+        mean_reward:
+          type: [number, 'null']
+          description: Mean over SCORED trials only; null when none. Zero is a reward.
+        cost_usd:
+          type: [number, 'null']
+          description: Measured spend across the task's settled trials.
+
+    JobTaskRollupPage:
+      type: object
+      required: [items, nextCursor, hasMore]
+      properties:
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/JobTaskRollup'
+        nextCursor:
+          type: [string, 'null']
+        hasMore:
+          type: boolean
+
+    TraceEvent:
+      type: object
+      description: >
+        One parsed trace event of a trial's transcript. `seq` orders the
+        stream and is the paging cursor. `data` is the harness-native payload,
+        deliberately open.
+      required: [seq, type]
+      properties:
+        seq:
+          type: integer
+        type:
+          type: string
+        timestamp:
+          type: [string, 'null']
+          format: date-time
+        data:
+          type: object
+          additionalProperties: true
+      additionalProperties: true
+
+    TraceEventPage:
+      type: object
+      required: [items, nextCursor, hasMore]
+      properties:
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/TraceEvent'
+        nextCursor:
+          type: [string, 'null']
+        hasMore:
+          type: boolean
+
+    # -------------------------------------------------------------------------
+    # Compare
+    # -------------------------------------------------------------------------
+
+    CompareCoverage:
+      type: object
+      description: How many of the trials behind an aggregate were SCORED.
+      required: [scored, total]
+      properties:
+        scored:
+          type: integer
+          minimum: 0
+        total:
+          type: integer
+          minimum: 0
+
+    CompareCell:
+      type: object
+      description: |
+        One (task, job) cell. `status` is a TrialStatus when every trial in
+        the cell shares it, `MIXED` when they differ, `MISSING` when the job
+        has no trials for the task.
+      required: [job_id, status, mean_reward, coverage]
+      properties:
+        job_id:
+          type: string
+          format: uuid
+        status:
+          type: string
+        mean_reward:
+          type: [number, 'null']
+        coverage:
+          $ref: '#/components/schemas/CompareCoverage'
+
+    CompareTaskRow:
+      type: object
+      required: [task_name, disagreement, cells]
+      properties:
+        task_name:
+          type: string
+        disagreement:
+          type: boolean
+          description: True when the jobs' cells differ in status or reward.
+        cells:
+          type: array
+          items:
+            $ref: '#/components/schemas/CompareCell'
+
+    CompareJobAggregate:
+      type: object
+      required: [id, datasets, status, mean_reward, coverage, cost_usd, agents, started_at]
+      properties:
+        id:
+          type: string
+          format: uuid
+        datasets:
+          type: array
+          items:
+            $ref: '#/components/schemas/DatasetRef'
+        status:
+          $ref: '#/components/schemas/JobStatus'
+        mean_reward:
+          type: [number, 'null']
+          description: Mean over SCORED trials only; null when none. Zero is a reward.
+        coverage:
+          $ref: '#/components/schemas/CompareCoverage'
+        cost_usd:
+          type: number
+        agents:
+          type: array
+          items:
+            $ref: '#/components/schemas/AgentArm'
+        started_at:
+          type: string
+          format: date-time
+
+    CompareResponse:
+      type: object
+      required: [jobs, taskMatrix]
+      properties:
+        jobs:
+          type: array
+          items:
+            $ref: '#/components/schemas/CompareJobAggregate'
+        taskMatrix:
+          type: array
+          description: Disagreement rows sort first.
+          items:
+            $ref: '#/components/schemas/CompareTaskRow'
+
+    # -------------------------------------------------------------------------
+    # SSE events
+    # -------------------------------------------------------------------------
+
+    JobEvent:
+      description: |
+        One server-sent event. On the wire, `seq` rides as the SSE `id` field
+        and `type` as the SSE `event` field; the JSON body is `data`. Payload
+        fields speak this document's vocabulary.
+
+        The union is discriminated on `type` and ONLY on `type`: several
+        event types carry identically shaped payloads (`job.running` and
+        `job.completed` are both `{job_id}`), so payload shape can never
+        route a validator — the `type` constant on each variant does.
+      oneOf:
+        - $ref: '#/components/schemas/JobCreatedEvent'
+        - $ref: '#/components/schemas/JobRunningEvent'
+        - $ref: '#/components/schemas/JobCancellingEvent'
+        - $ref: '#/components/schemas/JobCancelledEvent'
+        - $ref: '#/components/schemas/JobCompletedEvent'
+        - $ref: '#/components/schemas/JobFailedEvent'
+        - $ref: '#/components/schemas/TrialRunningEvent'
+        - $ref: '#/components/schemas/TrialScoringEvent'
+        - $ref: '#/components/schemas/TrialSpendEvent'
+        - $ref: '#/components/schemas/TrialSettledEvent'
+      discriminator:
+        propertyName: type
+        mapping:
+          job.created: '#/components/schemas/JobCreatedEvent'
+          job.running: '#/components/schemas/JobRunningEvent'
+          job.cancelling: '#/components/schemas/JobCancellingEvent'
+          job.cancelled: '#/components/schemas/JobCancelledEvent'
+          job.completed: '#/components/schemas/JobCompletedEvent'
+          job.failed: '#/components/schemas/JobFailedEvent'
+          trial.running: '#/components/schemas/TrialRunningEvent'
+          trial.scoring: '#/components/schemas/TrialScoringEvent'
+          trial.spend: '#/components/schemas/TrialSpendEvent'
+          trial.settled: '#/components/schemas/TrialSettledEvent'
+
+    EventSeq:
+      type: integer
+      minimum: 0
+      description: Monotonic sequence number — the resume position.
+
+    JobCreatedEvent:
+      type: object
+      required: [seq, type, data]
+      properties:
+        seq:
+          $ref: '#/components/schemas/EventSeq'
+        type:
+          type: string
+          const: job.created
+        data:
+          $ref: '#/components/schemas/JobCreatedData'
+
+    JobRunningEvent:
+      type: object
+      required: [seq, type, data]
+      properties:
+        seq:
+          $ref: '#/components/schemas/EventSeq'
+        type:
+          type: string
+          const: job.running
+        data:
+          $ref: '#/components/schemas/JobRunningData'
+
+    JobCancellingEvent:
+      type: object
+      required: [seq, type, data]
+      properties:
+        seq:
+          $ref: '#/components/schemas/EventSeq'
+        type:
+          type: string
+          const: job.cancelling
+        data:
+          $ref: '#/components/schemas/JobCancellingData'
+
+    JobCancelledEvent:
+      type: object
+      required: [seq, type, data]
+      properties:
+        seq:
+          $ref: '#/components/schemas/EventSeq'
+        type:
+          type: string
+          const: job.cancelled
+        data:
+          $ref: '#/components/schemas/JobCancelledData'
+
+    JobCompletedEvent:
+      type: object
+      required: [seq, type, data]
+      properties:
+        seq:
+          $ref: '#/components/schemas/EventSeq'
+        type:
+          type: string
+          const: job.completed
+        data:
+          $ref: '#/components/schemas/JobCompletedData'
+
+    JobFailedEvent:
+      type: object
+      required: [seq, type, data]
+      properties:
+        seq:
+          $ref: '#/components/schemas/EventSeq'
+        type:
+          type: string
+          const: job.failed
+        data:
+          $ref: '#/components/schemas/JobFailedData'
+
+    TrialRunningEvent:
+      type: object
+      required: [seq, type, data]
+      properties:
+        seq:
+          $ref: '#/components/schemas/EventSeq'
+        type:
+          type: string
+          const: trial.running
+        data:
+          $ref: '#/components/schemas/TrialRunningData'
+
+    TrialScoringEvent:
+      type: object
+      required: [seq, type, data]
+      properties:
+        seq:
+          $ref: '#/components/schemas/EventSeq'
+        type:
+          type: string
+          const: trial.scoring
+        data:
+          $ref: '#/components/schemas/TrialScoringData'
+
+    TrialSpendEvent:
+      type: object
+      required: [seq, type, data]
+      properties:
+        seq:
+          $ref: '#/components/schemas/EventSeq'
+        type:
+          type: string
+          const: trial.spend
+        data:
+          $ref: '#/components/schemas/TrialSpendData'
+
+    TrialSettledEvent:
+      type: object
+      required: [seq, type, data]
+      properties:
+        seq:
+          $ref: '#/components/schemas/EventSeq'
+        type:
+          type: string
+          const: trial.settled
+        data:
+          $ref: '#/components/schemas/TrialSettledData'
+
+    JobCreatedData:
+      type: object
+      description: >
+        The job's resolved creation inputs, echoed so a watcher that joined
+        late knows what it is watching.
+      required:
+        - datasets
+        - task_count
+        - agents
+        - n_attempts
+        - n_concurrent_trials
+        - max_trial_spend_usd
+        - sandbox_provider
+        - trial_count
+      properties:
+        datasets:
+          type: array
+          items:
+            $ref: '#/components/schemas/DatasetRef'
+        task_count:
+          type: integer
+        agents:
+          type: array
+          items:
+            $ref: '#/components/schemas/AgentArm'
+        n_attempts:
+          type: integer
+        n_concurrent_trials:
+          type: integer
+        max_trial_spend_usd:
+          type: number
+        sandbox_provider:
+          $ref: '#/components/schemas/SandboxProvider'
+        trial_count:
+          type: integer
+
+    JobRunningData:
+      type: object
+      required: [job_id]
+      properties:
+        job_id:
+          type: string
+          format: uuid
+
+    JobCancellingData:
+      type: object
+      required: [job_id, cancelled_trials, active_trials]
+      properties:
+        job_id:
+          type: string
+          format: uuid
+        cancelled_trials:
+          type: integer
+          description: Queued trials cancelled outright by the request.
+        active_trials:
+          type: integer
+          description: Trials still in flight, winding down before the job settles.
+
+    JobCancelledData:
+      type: object
+      required: [job_id, cancelled_trials]
+      properties:
+        job_id:
+          type: string
+          format: uuid
+        cancelled_trials:
+          type: integer
+          description: Total queued trials cancelled across the request and the settle.
+
+    JobCompletedData:
+      type: object
+      required: [job_id]
+      properties:
+        job_id:
+          type: string
+          format: uuid
+
+    JobFailedData:
+      type: object
+      description: >
+        The job settled FAILED. Terminal — the stream closes after this
+        event. The event type is declared and reserved (FAILED is a real job
+        status) but no server path emits it today; the payload is fixed here
+        so a client written now parses it when it first appears.
+      required: [job_id]
+      properties:
+        job_id:
+          type: string
+          format: uuid
+
+    TrialRunningData:
+      type: object
+      required: [trial_id, task_name]
+      properties:
+        trial_id:
+          type: string
+          format: uuid
+        task_name:
+          type: string
+
+    TrialScoringData:
+      type: object
+      required: [trial_id]
+      properties:
+        trial_id:
+          type: string
+          format: uuid
+        captured_bytes:
+          type: integer
+          description: Bytes of agent stdout retained for the failure detail.
+
+    TrialSpendData:
+      type: object
+      description: >
+        A mid-run spend sample landed on a still-live trial. Emitted only
+        when the reading actually updated a RUNNING/SCORING row. The token
+        sums come from the same ledger aggregation that produced the money
+        figure, present only when the sample carried them — an older event
+        replays without them.
+      required: [trial_id, task_name, live_spent_usd]
+      properties:
+        trial_id:
+          type: string
+          format: uuid
+        task_name:
+          type: string
+        live_spent_usd:
+          type: number
+          description: The same lagging lower bound as Trial.live_spent_usd.
+        n_input_tokens:
+          type: integer
+          description: Input tokens so far; includes cache tokens.
+        n_cache_tokens:
+          type: integer
+          description: Cached input tokens so far (a subset of n_input_tokens).
+        n_output_tokens:
+          type: integer
+          description: Output tokens so far.
+
+    TrialSettledData:
+      type: object
+      description: >
+        A trial reached a terminal status. `reward` is present only on the
+        scored path; `exception_type` only on a failure; `attempt_phase`
+        appears when the settle happened mid-phase (worker death), which is
+        exactly when knowing the phase is worth having.
+      required: [trial_id, task_name, status]
+      properties:
+        trial_id:
+          type: string
+          format: uuid
+        task_name:
+          type: string
+        status:
+          $ref: '#/components/schemas/TrialStatus'
+        reward:
+          type: [number, 'null']
+        exception_type:
+          type: string
+        attempt_phase:
+          oneOf:
+            - $ref: '#/components/schemas/AttemptPhase'
+            - type: 'null'
+
+    # -------------------------------------------------------------------------
+    # Datasets
+    # -------------------------------------------------------------------------
+
+    DatasetVersionState:
+      type: string
+      description: |
+        Terminal: READY, FAILED, ARCHIVED.
+
+        A hosted publish walks IMPORTING -> BUILDING -> VALIDATING on its own,
+        and VALIDATING -> READY happens on its own too: the activation gate
+        promotes the version it proves, and points the dataset's default at
+        it. The activate verb is not part of that path — it exists to move
+        the default to a different version (an older READY one, or a newer
+        one), never to finish a publish.
+      enum: [DRAFT, IMPORTING, BUILDING, VALIDATING, READY, FAILED, ARCHIVED]
+
+    DatasetVersion:
+      type: object
+      description: One immutable version of a dataset — one shape on every surface.
+      required: [version, state, created_at, task_count, gate]
+      properties:
+        version:
+          type: string
+        state:
+          $ref: '#/components/schemas/DatasetVersionState'
+        created_at:
+          type: string
+          format: date-time
+        task_count:
+          type: integer
+          minimum: 0
+        gate:
+          oneOf:
+            - $ref: '#/components/schemas/ActivationGate'
+            - type: 'null'
+          description: >
+            The activation gate's schedule state for this version. Null when
+            no gate was ever scheduled — a version imported before the gate
+            scheduler existed, a platform-seeded one, or one whose import
+            archived no reference solutions (see the import's `warnings`).
+
+    ActivationGateStatus:
+      type: string
+      description: |
+        Where the automatic activation gate stands for a version. The gate is
+        the oracle-conformance run the worker schedules once a hosted import
+        completes: the version's held-out reference (gold) solution must
+        score exactly 1.0 through the real execution path, and a do-nothing
+        agent must not. PENDING = scheduled, waiting for a worker; RUNNING =
+        proving tasks now (per-task verdicts land on the task list as they
+        finish); PASSED = every task is activation-eligible, and the version
+        was promoted to READY and made the dataset's active version by the
+        gate itself — except on a platform-curated dataset, whose default is
+        an operator setting, so its versions sit PASSED until an operator
+        promotes them; FAILED = at least one task is not — `failure` names
+        them and the dataset's active version is left alone.
+      enum: [PENDING, RUNNING, PASSED, FAILED]
+
+    ActivationGate:
+      type: object
+      description: >
+        A version's activation-gate schedule state. Watch `status` move
+        PENDING -> RUNNING -> PASSED/FAILED after a publish; the state that
+        used to read as "VALIDATING forever" is this object saying where the
+        proof stands.
+      required: [status, attempts, failure]
+      properties:
+        status:
+          $ref: '#/components/schemas/ActivationGateStatus'
+        attempts:
+          type: integer
+          minimum: 0
+          description: >
+            Times a worker has taken this gate. A run lost to a dead worker
+            is re-queued and RESUMES (verdicts already landed are kept),
+            bounded before the gate fails with `gate_lease_lost`.
+        failure:
+          oneOf:
+            - $ref: '#/components/schemas/ActivationGateFailure'
+            - type: 'null'
+          description: Why the gate FAILED; null unless status is FAILED.
+
+    ActivationGateFailure:
+      type: object
+      description: >
+        The gate's structured failure. `failed_tasks` names each ineligible
+        task with the gate's own reasons (a gold solution that never scored
+        1.0, a no-op that did, a solution that could not be resolved), so
+        nothing has to be parsed back out of the message.
+      required: [code, message]
+      properties:
+        code:
+          type: string
+          description: '`gate_failed`, or `gate_lease_lost` after repeated worker loss.'
+        message:
+          type: string
+        failed_tasks:
+          type: array
+          description: >
+            The ineligible tasks (first 25; when truncated,
+            `failed_task_count` carries the true total).
+          items:
+            type: object
+            required: [task_name, outcome, reasons]
+            properties:
+              task_name:
+                type: string
+              outcome:
+                type: string
+                description: FAIL, or ERROR (inconclusive — no usable score).
+              reasons:
+                type: array
+                items:
+                  type: string
+        failed_task_count:
+          type: integer
+          minimum: 0
+
+    GateRunning:
+      type: object
+      description: |
+        The 202 body of the activation verb while the gate is still proving
+        the version. Deliberately NOT the error envelope: an in-progress
+        gate is a healthy state, and `error` on this surface always means
+        "this request failed".
+      required: [code, message, gate]
+      properties:
+        code:
+          type: string
+          enum: [gate_running]
+        message:
+          type: string
+        gate:
+          type: object
+          description: Gate progress at the moment of the call.
+          required: [status, tasks, unverified, ineligible]
+          properties:
+            status:
+              $ref: '#/components/schemas/ActivationGateStatus'
+            tasks:
+              type: integer
+              minimum: 0
+            unverified:
+              type: integer
+              minimum: 0
+              description: Tasks the gate has not yet produced a verdict for.
+            ineligible:
+              type: integer
+              minimum: 0
+              description: Tasks whose verdict so far is not activation-eligible.
+
+    TaskProviderVerdict:
+      type: object
+      description: >
+        One provider's verdict for a task: runnable there, or refused with
+        the limitation named. Advisory for planning — creating a job whose
+        tasks include one refused on the chosen provider is rejected with the
+        same reason, so nothing is ever spent on a trial that cannot execute.
+      required: [ok]
+      properties:
+        ok:
+          type: boolean
+        reason:
+          type: string
+          description: Present when ok is false.
+
+    Task:
+      type: object
+      description: >
+        Public task fields only — instructions, environments, and tests never
+        leave the server.
+      required: [task_name, agent_timeout_sec, verifier_timeout_sec, providers, gate]
+      properties:
+        task_name:
+          type: string
+        agent_timeout_sec:
+          type: number
+        verifier_timeout_sec:
+          type: number
+        providers:
+          type: object
+          description: Verdict per sandbox provider.
+          additionalProperties:
+            $ref: '#/components/schemas/TaskProviderVerdict'
+        gate:
+          oneOf:
+            - $ref: '#/components/schemas/TaskGate'
+            - type: 'null'
+          description: >
+            This task's activation-gate verdict; null until the gate has run
+            it. The per-task half of the version's `gate` — while the gate is
+            RUNNING, verdicts appear here as they land.
+
+    TaskGate:
+      type: object
+      description: >
+        One task's activation-gate verdict — the public subset. The full
+        stored verdict carries oracle diagnostics that stay internal, like
+        the environment specs beside it.
+      required: [outcome, flaky, reasons, ran_at]
+      properties:
+        outcome:
+          type: string
+          description: >
+            PASS; FLAKY (gold passed only on a retry — still eligible under
+            the operator default); FAIL (definitive: gold never scored 1.0,
+            or a do-nothing agent did); ERROR (inconclusive — no usable
+            score, e.g. no archived solution to run).
+        flaky:
+          type: boolean
+        reasons:
+          type: array
+          items:
+            type: string
+          description: Human-readable; empty on PASS.
+        ran_at:
+          type: [string, 'null']
+          format: date-time
+
+    TaskPage:
+      type: object
+      required: [items, nextCursor, hasMore]
+      properties:
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/Task'
+        nextCursor:
+          type: [string, 'null']
+        hasMore:
+          type: boolean
+
+    UpstreamStatus:
+      type: object
+      description: |
+        Where the dataset's git source points now versus what its active
+        version was built from — the data behind a "new version available"
+        badge. The whole object is null on a dataset with nothing to watch;
+        null is never "up to date". Nothing here imports anything — a new
+        version is always a row you create (or `auto_import` creates).
+      required: [ref, current_commit, latest_commit, moved, behind_by, checked_at, error, auto_import]
+      properties:
+        ref:
+          type: string
+          description: The ref the active version was imported from.
+        current_commit:
+          type: string
+        latest_commit:
+          type: [string, 'null']
+          description: Where the ref points upstream now; null when the last check failed.
+        moved:
+          type: boolean
+          description: True when upstream has moved off the built-from commit. Branch on this.
+        behind_by:
+          type: [integer, 'null']
+          description: Reserved; always null today.
+        checked_at:
+          type: [string, 'null']
+          format: date-time
+        error:
+          type: [string, 'null']
+          description: Why the last check failed. Show "could not check", not "up to date".
+        auto_import:
+          type: boolean
+          description: Whether a moved upstream automatically imports a new version.
+
+    Dataset:
+      type: object
+      description: >
+        A dataset in the catalog. List responses carry the summary fields;
+        the detail route additionally populates `versions`,
+        `selected_version`, `tasks`, `created_at`, and `updated_at`.
+      required: [name, title, description, active_version, upstream]
+      properties:
+        name:
+          type: string
+        title:
+          type: [string, 'null']
+        description:
+          type: [string, 'null']
+        active_version:
+          oneOf:
+            - $ref: '#/components/schemas/DatasetVersion'
+            - type: 'null'
+          description: Null when no version is active (bare-name job refs refuse).
+        versions:
+          type: array
+          description: All versions, newest first (detail only).
+          items:
+            $ref: '#/components/schemas/DatasetVersion'
+        selected_version:
+          oneOf:
+            - $ref: '#/components/schemas/DatasetVersion'
+            - type: 'null'
+          description: The version whose tasks are listed below (detail only).
+        tasks:
+          $ref: '#/components/schemas/TaskPage'
+          description: One page of the selected version's tasks (detail only).
+        upstream:
+          oneOf:
+            - $ref: '#/components/schemas/UpstreamStatus'
+            - type: 'null'
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+
+    DatasetPage:
+      type: object
+      required: [items, nextCursor, hasMore]
+      properties:
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/Dataset'
+        nextCursor:
+          type: [string, 'null']
+        hasMore:
+          type: boolean
+
+    DatasetPatch:
+      type: object
+      description: The only settable dataset field.
+      required: [upstream_auto_import]
+      properties:
+        upstream_auto_import:
+          type: boolean
+
+    PublishRequest:
+      type: object
+      description: >
+        Multipart body of POST /api/datasets/publish. Exactly one source:
+        `git_url` + `git_ref`, or `archive`.
+      required: [name, version]
+      properties:
+        name:
+          type: string
+          description: Catalog dataset name the version lands under (created or extended).
+        version:
+          type: string
+          description: Version label for the new immutable version.
+        git_url:
+          type: string
+          description: https:// repository URL. For a private repo, put a token in the URL.
+        git_ref:
+          type: string
+          description: Pinned branch, tag, or commit. Required with git_url.
+        archive:
+          type: string
+          format: binary
+          description: Gzipped tarball of a standard-layout corpus directory.
+
+    DatasetImportStatus:
+      type: string
+      description: >
+        Same four words a job uses, deliberately. Terminal: COMPLETED (the
+        corpus landed as a dataset version; runnable once its activation gate
+        passes, which also activates it) and FAILED.
+      enum: [QUEUED, RUNNING, COMPLETED, FAILED]
+
+    DatasetImportFailure:
+      type: object
+      description: Structured failure detail for a FAILED import.
+      required: [code, message]
+      properties:
+        code:
+          type: string
+          description: '`import_failed` when none was recorded.'
+        message:
+          type: string
+        failures:
+          type: array
+          description: Per-task parse/validation failures, when the corpus was reachable.
+          items:
+            type: object
+            required: [task_name, error]
+            properties:
+              task_name:
+                type: string
+              error:
+                type: string
+
+    ImportWarning:
+      type: object
+      description: |
+        Non-fatal but consequential import outcomes. A version whose warnings
+        include `no_solutions_archived` cannot be activated through this API
+        (`version_not_activatable`).
+      required: [code]
+      properties:
+        code:
+          type: string
+          enum:
+            - solutions_archiving_disabled
+            - no_solutions_archived
+            - partial_solutions_archived
+        message:
+          type: string
+
+    DatasetImport:
+      type: object
+      description: >
+        An asynchronous publish. Self-describing: every response names the
+        dataset@version being imported, so a caller can render the row it
+        just created without a follow-up read.
+      required: [id, status, name, version, failure, warnings]
+      properties:
+        id:
+          type: string
+        status:
+          $ref: '#/components/schemas/DatasetImportStatus'
+        name:
+          type: string
+          description: Catalog dataset name the import creates or extends.
+        version:
+          type: string
+        failure:
+          oneOf:
+            - $ref: '#/components/schemas/DatasetImportFailure'
+            - type: 'null'
+          description: >
+            Why the import FAILED; null otherwise. Named `failure`, never
+            `error` — see JobFailure.
+        warnings:
+          type: array
+          items:
+            $ref: '#/components/schemas/ImportWarning'
+        task_count:
+          type: integer
+          description: Number of tasks parsed, once counted.
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+
+    DatasetImportPage:
+      type: object
+      required: [items, nextCursor, hasMore]
+      properties:
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/DatasetImport'
+        nextCursor:
+          type: [string, 'null']
+        hasMore:
+          type: boolean
+
+    # -------------------------------------------------------------------------
+    # Registered agents
+    # -------------------------------------------------------------------------
+
+    Agent:
+      type: object
+      description: A private agent registered by the caller.
+      required: [name, source, run_command, env, created_at, updated_at]
+      properties:
+        name:
+          type: string
+          description: The name to put in job `agents[].name`.
+        source:
+          type: string
+          enum: [install_script, tarball]
+          description: How the executables were produced. Echoed, never guessed.
+        run_command:
+          type: string
+          description: Run headless with `sh -c` at the task working directory.
+        env:
+          type: object
+          description: >
+            Caller-declared env injected at RUN time only; may not override
+            the run contract's own keys (`agent_invalid_env` at
+            registration).
+          additionalProperties:
+            type: string
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+
+    AgentRegistration:
+      type: object
+      description: >
+        Multipart registration body. Exactly one source: `install_script` or
+        `archive`.
+      required: [name, run_command]
+      properties:
+        name:
+          type: string
+        run_command:
+          type: string
+        env:
+          type: string
+          description: JSON object of env entries, as a multipart text part.
+        install_script:
+          type: string
+          description: >
+            The script itself (not a path). Runs in a throwaway builder
+            sandbox with internet and zero secrets; must leave executables in
+            `$PREFIX/bin`.
+        archive:
+          type: string
+          format: binary
+          description: Gzipped tarball of the agent directory. Same build rules.
+
+    AgentPage:
+      type: object
+      required: [items, nextCursor, hasMore]
+      properties:
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/Agent'
+        nextCursor:
+          type: [string, 'null']
+        hasMore:
+          type: boolean
+
+    # -------------------------------------------------------------------------
+    # Meta
+    # -------------------------------------------------------------------------
+
+    StatusVocabulary:
+      type: object
+      description: One status vocabulary and its terminal members.
+      required: [values, terminal]
+      properties:
+        values:
+          type: array
+          items:
+            type: string
+        terminal:
+          type: array
+          items:
+            type: string
+
+    AgentCapability:
+      type: object
+      description: One built-in agent's declared capabilities.
+      required: [name, effort_support, version_pinnable]
+      properties:
+        name:
+          type: string
+        effort_support:
+          type: boolean
+        version_pinnable:
+          type: boolean
+        latest_version:
+          type: [string, 'null']
+
+    ProviderCapability:
+      type: object
+      required: [name, default, sizing, refuses]
+      properties:
+        name:
+          type: string
+        default:
+          type: boolean
+        sizing:
+          type: object
+          required: [max_cpus, max_memory_mb, max_storage_mb, storage]
+          properties:
+            max_cpus:
+              type: integer
+            max_memory_mb:
+              type: integer
+            max_storage_mb:
+              type: integer
+            storage:
+              type: string
+              enum: [sized, fixed]
+        refuses:
+          type: array
+          items:
+            type: object
+            required: [capability, reason]
+            properties:
+              capability:
+                type: string
+              reason:
+                type: string
+
+    ManagedProviderCapability:
+      type: object
+      description: |
+        One managed sandbox door and whether this deployment serves it.
+        `configured` is derived from operator config presence only — it says
+        nothing about whether the pass-through behind the door is deployed or
+        the credential is valid. `agent_sessions` answers the separate
+        question of whether the door can carry a full SDK agent session.
+      required:
+        - name
+        - configured
+        - requires_config
+        - missing_config
+        - agent_sessions
+        - agent_sessions_reason
+      properties:
+        name:
+          type: string
+        configured:
+          type: boolean
+        requires_config:
+          type: array
+          items:
+            type: string
+        missing_config:
+          description: The subset of `requires_config` missing right now — empty when configured.
+          type: array
+          items:
+            type: string
+        agent_sessions:
+          type: boolean
+        agent_sessions_reason:
+          description: Why not, when `agent_sessions` is false. Null otherwise.
+          type: [string, 'null']
+
+    CapabilityDocument:
+      type: object
+      description: |
+        Everything a client would otherwise hardcode. Public and cacheable —
+        no API key needed, so a signed-out page can populate its own agent
+        picker. `schema_version` bumps when a FIELD changes meaning, never
+        when a value changes.
+      required:
+        - schema_version
+        - agents
+        - agent_registration
+        - sandbox_providers
+        - managed_providers
+        - platform_constraints
+        - network_modes
+        - statuses
+        - limits
+        - import_warning_codes
+        - error_codes
+      properties:
+        schema_version:
+          type: integer
+        agents:
+          type: array
+          description: Built-in agents and their declared capabilities.
+          items:
+            $ref: '#/components/schemas/AgentCapability'
+        agent_registration:
+          type: object
+          description: Rules a bring-your-own agent registration must satisfy.
+          properties:
+            name_pattern:
+              type: string
+            max_name_length:
+              type: integer
+            max_run_command_length:
+              type: integer
+            max_install_script_length:
+              type: integer
+            max_env_entries:
+              type: integer
+            max_per_user:
+              type: integer
+            max_upload_bytes:
+              type: integer
+            reserved_names:
+              type: array
+              description: Built-in names a registration may not reuse.
+              items:
+                type: string
+            reserved_env_keys:
+              type: array
+              description: Env keys the platform owns; declaring one is refused.
+              items:
+                type: string
+        sandbox_providers:
+          type: array
+          items:
+            $ref: '#/components/schemas/ProviderCapability'
+        managed_providers:
+          type: array
+          description: |
+            The managed doors this deployment serves — a different question
+            from `sandbox_providers`, which is about the eval lane. A managed
+            sandbox is one the caller drives directly holding nothing but an
+            Evolve key.
+          items:
+            $ref: '#/components/schemas/ManagedProviderCapability'
+        platform_constraints:
+          type: array
+          description: Constraints that hold on EVERY provider.
+          items:
+            type: object
+            required: [capability, reason]
+            properties:
+              capability:
+                type: string
+              reason:
+                type: string
+        network_modes:
+          type: array
+          items:
+            type: string
+        statuses:
+          type: object
+          description: Every status vocabulary on the surface, with terminal members.
+          required: [job, trial, import, dataset_version]
+          properties:
+            job:
+              $ref: '#/components/schemas/StatusVocabulary'
+            trial:
+              $ref: '#/components/schemas/StatusVocabulary'
+            import:
+              $ref: '#/components/schemas/StatusVocabulary'
+            dataset_version:
+              $ref: '#/components/schemas/StatusVocabulary'
+        limits:
+          type: object
+          properties:
+            job:
+              type: object
+              properties:
+                max_n_attempts:
+                  type: integer
+                max_agents:
+                  type: integer
+                max_trials:
+                  type: integer
+                n_concurrent_trials:
+                  type: object
+                  properties:
+                    default:
+                      type: integer
+                    max:
+                      type: integer
+                default_max_trial_spend_usd:
+                  type: number
+                default_sandbox_provider:
+                  type: string
+                default_sizing:
+                  type: object
+                  properties:
+                    cpus:
+                      type: integer
+                    memory_mb:
+                      type: integer
+                    storage_mb:
+                      type: integer
+                model_required:
+                  type: boolean
+                  description: Every agent must name a model; the server applies no default.
+                default_agent_timeout_sec:
+                  type: number
+                default_verifier_timeout_sec:
+                  type: number
+                reasoning_efforts:
+                  type: array
+                  items:
+                    type: string
+                default_reasoning_effort:
+                  type: string
+                max_job_name_length:
+                  type: integer
+                  description: Longest accepted `job_name` (JobCreate mirrors it as maxLength).
+            compare:
+              type: object
+              properties:
+                min_ids:
+                  type: integer
+                max_ids:
+                  type: integer
+            stop:
+              type: object
+              properties:
+                max_trial_ids:
+                  type: integer
+                  description: Most trials one stop request may name (StopRequest mirrors it as maxItems).
+            pagination:
+              type: object
+              properties:
+                collections:
+                  type: object
+                  properties:
+                    default:
+                      type: integer
+                    max:
+                      type: integer
+                dataset_tasks:
+                  type: object
+                  properties:
+                    default:
+                      type: integer
+                    max:
+                      type: integer
+                trace_events:
+                  type: object
+                  properties:
+                    default:
+                      type: integer
+                    max:
+                      type: integer
+            uploads:
+              type: object
+              properties:
+                dataset_archive_bytes:
+                  type: integer
+                agent_tarball_bytes:
+                  type: integer
+            dataset_names:
+              type: object
+              description: >
+                Name constraints for published datasets. Beyond the pattern,
+                `imports` is a reserved name (a literal path segment under
+                `/api/datasets`).
+              properties:
+                pattern:
+                  type: string
+                max_name_length:
+                  type: integer
+                max_version_length:
+                  type: integer
+                max_git_url_length:
+                  type: integer
+                max_git_ref_length:
+                  type: integer
+            max_items_named_in_error_message:
+              type: integer
+              description: How many items an error MESSAGE names before "and N more".
+        import_warning_codes:
+          type: array
+          items:
+            type: string
+        error_codes:
+          type: array
+          description: The closed error-code union, enumerated at runtime.
+          items:
+            type: string
+
+    # -------------------------------------------------------------------------
+    # Auth
+    # -------------------------------------------------------------------------
+
+    AuthStatus:
+      type: object
+      description: The caller's identity and the key this request authenticated with.
+      required: [user_id, key]
+      properties:
+        user_id:
+          type: string
+        email:
+          type: [string, 'null']
+        key:
+          $ref: '#/components/schemas/ApiKey'
+
+    ApiKey:
+      type: object
+      description: A key descriptor. The secret is never returned.
+      required: [id, created_at]
+      properties:
+        id:
+          type: string
+        label:
+          type: [string, 'null']
+        created_at:
+          type: [string, 'null']
+          format: date-time
+          description: Null when the credential store predates creation stamping.
+        last_used_at:
+          type: [string, 'null']
+          format: date-time
+
+    ApiKeyPage:
+      type: object
+      required: [items, nextCursor, hasMore]
+      properties:
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/ApiKey'
+        nextCursor:
+          type: [string, 'null']
+        hasMore:
+          type: boolean