openapi.yaml

openapi: 3.1.0
info:
  title: RDK Robot Learning Platform API
  version: 1.0.0
  description: >-
    Versioned control-plane contract for the standalone MicroDuck/RDK Duck
    Sim2Real workflow. The legacy /api/sim2real paths are aliases.
servers:
  - url: https://example.invalid
    description: Replace with the deployment origin.
tags:
  - name: service
  - name: sso
  - name: workspace
  - name: runs
  - name: telemetry
  - name: deployments
  - name: devices
  - name: board-station
  - name: agent
security:
  - cookieAuth: []
paths:
  /healthz:
    get:
      tags: [service]
      summary: Liveness and dependency summary
      operationId: getHealth
      security: []
      responses:
        "200":
          description: Service is alive (it may be degraded).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Health" }
  /readyz:
    get:
      tags: [service]
      summary: Readiness probe
      operationId: getReadiness
      security: []
      responses:
        "200": { $ref: "#/components/responses/Ready" }
        "503": { $ref: "#/components/responses/NotReady" }
  /api/sso/session:
    get:
      tags: [sso]
      summary: Current cookie identity or an auth-required challenge
      operationId: getSsoSession
      security: []
      description: >-
        Returns 200 with the identity when the site-wide Studio session cookie
        is present and valid, otherwise 401 with login-relay availability
        (loginRelay.configured and optionally loginRelay.loginPageUrl) so the
        workbench can render a direct login form or a redirect.
      responses:
        "200":
          description: Verified identity.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/SsoSessionResponse" }
        "401":
          description: >-
            No valid session; body carries loginRelay availability.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
  /api/sso/login:
    post:
      tags: [sso]
      summary: Relay credentials to the Studio account center and adopt its cookie
      operationId: ssoLogin
      security: []
      description: >-
        Relays a whitelist of login fields to POST /api/sso/direct/login on
        the Studio main shell, then adopts only the web-cloud session cookie
        it can verify (legacy cookies are dropped). In same-origin
        deployments nginx may route the browser directly to the Studio shell
        instead, in which case this endpoint is unused. Failed by
        sim2RealCsrfMiddleware for cross-site submissions.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/SsoLoginRequest" }
      responses:
        "200":
          description: Login accepted; session cookie set on the response.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/SsoSessionResponse" }
        "400": { description: Login method missing or not in account/sms/email. }
        "409": { description: Credentials rejected by the account center. }
        "502": { description: Relay transport failure or unusable cookie. }
        "503": { description: Cookie secret or relay target not configured. }
  /api/sso/logout:
    post:
      tags: [sso]
      summary: Clear the shared session cookie
      operationId: ssoLogout
      security: []
      description: Expires the site-wide session cookie for this service only.
      responses:
        "200":
          description: Cookie cleared.
          content:
            application/json:
              schema:
                type: object
                required: [ok]
                properties:
                  ok: { const: true }
  /api/v1/duck/task-packs/{taskId}/failure-cases:
    get:
      tags: [workspace]
      summary: Read the public seed failure-case pack for a task pack
      description: >
        Public, immutable seed assets for the first task-pack flywheel. Only
        goal-navigation-clear-arena is served today; the route is
        unauthenticated so demos can cite it without credentials.
      operationId: getTaskPackFailureCases
      parameters:
        - in: path
          name: taskId
          required: true
          schema: { type: string }
      responses:
        "200": { description: Failure-case seed entries, content: { application/json: { schema: { type: object } } } }
        "404": { description: "Unknown task pack: { ok: false, error: TASK_PACK_NOT_FOUND }" }
        "503": { description: "Seed asset unavailable: { ok: false, error: TASK_PACK_ASSET_UNAVAILABLE }" }
  /api/v1/duck/overview:
    get:
      tags: [workspace]
      summary: Read the account-scoped workspace snapshot
      operationId: getOverview
      parameters:
        - $ref: "#/components/parameters/ProductId"
      responses:
        "200":
          description: Products, contracts, models, runs, devices and integrations.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/OverviewResponse" }
        "401": { $ref: "#/components/responses/AuthRequired" }
  /api/v1/duck/workspace-summary:
    get:
      tags: [workspace]
      summary: Read a lightweight workspace summary
      operationId: getWorkspaceSummary
      description: >-
        Returns account-scoped counts and the latest run/deployment projection
        for dashboards and assistants. It intentionally omits model manifests,
        telemetry layouts and integration probes so it is safe to poll often.
      responses:
        "200":
          description: Lightweight workspace summary.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceSummaryResponse"
        "401": { $ref: "#/components/responses/AuthRequired" }
  /api/v1/duck/research-loop/summary:
    get:
      tags: [workspace]
      summary: Read aggregate research feedback-loop metrics
      operationId: getResearchLoopSummary
      description: >-
        Returns owner-scoped aggregate metrics for experiment-to-evidence
        cycle latency, agent-attributed work, approval-free chains, marginal
        returns and current queue/resource walls. It is read-only, excludes
        mock runs from cycle measurements, and is never a release gate.
      parameters:
        - in: query
          name: days
          schema: { type: integer, minimum: 1, maximum: 365, default: 30 }
          description: Look-back window for run-scoped metrics; current walls are not windowed.
      responses:
        "200":
          description: Aggregate research-loop metrics.
          content:
            application/json:
              schema:
                type: object
                required: [ok, summary]
                properties:
                  ok: { const: true }
                  summary:
                    type: object
                    description: Stable aggregate shape; fields may be extended additively.
        "401": { $ref: "#/components/responses/AuthRequired" }
  /api/v1/duck/golden-path:
    get:
      tags: [workspace]
      summary: Read the canonical RDK Golden Path state
      operationId: getRdkGoldenPath
      description: >-
        Returns one account-scoped read model for task selection, dataset
        readiness, training, evaluation, RDK deployment and board feedback.
        The response is read-only and safe to poll while a worker is running.
      parameters:
        - in: query
          name: projectId
          schema: { type: string, maxLength: 160 }
        - in: query
          name: modelId
          schema: { type: string, maxLength: 160 }
        - in: query
          name: taskId
          schema: { type: string, maxLength: 160 }
      responses:
        "200":
          description: Canonical six-stage RDK workflow state.
          content:
            application/json:
              schema:
                type: object
                required: [ok, goldenPath]
                properties:
                  ok: { type: boolean }
                  goldenPath: { type: object }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
  /api/v1/duck/audit:
    get:
      tags: [workspace]
      summary: Read the owner-scoped mutation audit trail
      operationId: listAuditEvents
      parameters:
        - in: query
          name: limit
          schema: { type: integer, minimum: 1, maximum: 2000, default: 200 }
        - in: query
          name: resourceType
          schema: { type: string, maxLength: 80 }
        - in: query
          name: outcome
          schema: { type: string, enum: [succeeded, failed, denied] }
      responses:
        "200": { description: Audit events, content: { application/json: { schema: { $ref: "#/components/schemas/AuditResponse" } } } }
        "401": { $ref: "#/components/responses/AuthRequired" }
  /api/v1/duck/audit/health:
    get:
      tags: [workspace]
      summary: Check audit stream availability
      operationId: getAuditHealth
      responses:
        "200": { description: Audit health, content: { application/json: { schema: { $ref: "#/components/schemas/AuditHealthResponse" } } } }
        "401": { $ref: "#/components/responses/AuthRequired" }
  /api/v1/duck/projects:
    get:
      tags: [workspace]
      summary: List account-scoped learning projects
      operationId: listProjects
      responses:
        "200": { description: Projects, content: { application/json: { schema: { $ref: "#/components/schemas/ProjectsResponse" } } } }
        "401": { $ref: "#/components/responses/AuthRequired" }
    post:
      tags: [workspace]
      summary: Create a learning project
      operationId: createProject
      requestBody:
        required: true
        content: { application/json: { schema: { $ref: "#/components/schemas/ProjectInput" } } }
      responses:
        "201": { description: Created, content: { application/json: { schema: { $ref: "#/components/schemas/ProjectResponse" } } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "409": { description: Duplicate slug. }
  /api/v1/duck/projects/{id}:
    parameters: [{ $ref: "#/components/parameters/ProjectId" }]
    get:
      tags: [workspace]
      summary: Read a project with linked datasets and runs
      operationId: getProject
      responses:
        "200": { description: Project detail, content: { application/json: { schema: { $ref: "#/components/schemas/ProjectDetailResponse" } } } }
        "404": { $ref: "#/components/responses/NotFound" }
    patch:
      tags: [workspace]
      summary: Update project metadata and asset links
      operationId: updateProject
      requestBody:
        required: true
        content: { application/json: { schema: { $ref: "#/components/schemas/ProjectInput" } } }
      responses:
        "200": { description: Updated, content: { application/json: { schema: { $ref: "#/components/schemas/ProjectResponse" } } } }
        "400": { $ref: "#/components/responses/BadRequest" }
  /api/v1/duck/projects/{id}/runs/compare:
    get:
      tags: [runs]
      summary: Compare experiment runs in a project
      operationId: compareProjectRuns
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - in: query
          name: runIds
          schema: { type: string, maxLength: 1024 }
          description: Comma-separated run ids; omitted returns the latest 20.
      responses:
        "200": { description: Comparison rows, content: { application/json: { schema: { $ref: "#/components/schemas/RunComparisonResponse" } } } }
        "404": { $ref: "#/components/responses/NotFound" }
  /api/v1/duck/datasets:
    get:
      tags: [workspace]
      summary: List dataset metadata references
      operationId: listDatasets
      responses:
        "200": { description: Datasets, content: { application/json: { schema: { $ref: "#/components/schemas/DatasetsResponse" } } } }
    post:
      tags: [workspace]
      summary: Register a dataset metadata reference
      operationId: createDataset
      requestBody:
        required: true
        content: { application/json: { schema: { $ref: "#/components/schemas/DatasetInput" } } }
      responses:
        "201": { description: Created, content: { application/json: { schema: { $ref: "#/components/schemas/DatasetResponse" } } } }
        "400": { $ref: "#/components/responses/BadRequest" }
  /api/v1/duck/models/validate:
    post:
      tags: [workspace]
      summary: Validate a manifest without persisting it
      operationId: validateModelManifest
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/ManifestEnvelope" }
      responses:
        "200":
          description: Validation result (valid may be false).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ValidationResponse" }
        "401": { $ref: "#/components/responses/AuthRequired" }
  /api/v1/duck/models:
    get:
      tags: [workspace]
      summary: List account-scoped model manifests
      operationId: listModels
      responses:
        "200":
          description: Registered models, including the built-in MicroDuck contract.
          content:
            application/json:
              schema:
                type: object
                required: [ok, models]
                properties:
                  ok: { const: true }
                  models: { type: array, items: { $ref: "#/components/schemas/Model" } }
        "401": { $ref: "#/components/responses/AuthRequired" }
    post:
      tags: [workspace]
      summary: Register an immutable model manifest
      operationId: createModel
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/ManifestEnvelope" }
      responses:
        "201":
          description: Model registered.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ModelResponse" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "409": { description: Model version already exists. }
  /api/v1/duck/models/{modelId}:
    parameters:
      - $ref: "#/components/parameters/ModelId"
    get:
      tags: [workspace]
      summary: Read one registered model
      operationId: getModel
      responses:
        "200":
          description: Model.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ModelResponse" }
        "404": { $ref: "#/components/responses/NotFound" }
  /api/v1/duck/runs:
    get:
      tags: [runs]
      summary: List account-scoped runs
      operationId: listRuns
      responses:
        "200":
          description: Recent runs with product and contract provenance.
          content:
            application/json:
              schema:
                type: object
                required: [ok, runs]
                properties:
                  ok: { const: true }
                  runs: { type: array, items: { $ref: "#/components/schemas/Run" } }
        "401": { $ref: "#/components/responses/AuthRequired" }
    post:
      tags: [runs]
      summary: Start or register a browser, local, RoboGo or contract run
      operationId: createRun
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/RunRequest" }
      responses:
        "201":
          description: New run.
          content: { application/json: { schema: { $ref: "#/components/schemas/RunResponse" } } }
        "200":
          description: Idempotent replay.
          content: { application/json: { schema: { $ref: "#/components/schemas/RunResponse" } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "429": { description: Per-account active-run quota reached. }
  /api/v1/duck/runs/{runId}:
    parameters:
      - $ref: "#/components/parameters/RunId"
    get:
      tags: [runs]
      summary: Read a run and refresh remote status when applicable
      operationId: getRun
      responses:
        "200":
          description: Run.
          content: { application/json: { schema: { $ref: "#/components/schemas/RunResponse" } } }
        "404": { $ref: "#/components/responses/NotFound" }
        "503": { description: Status lookup is retryable; last known state is preserved. }
  /api/v1/duck/runs/{runId}/reconcile:
    post:
      tags: [runs]
      summary: Attach a confirmed external id without relaunching work
      operationId: reconcileRun
      parameters:
        - $ref: "#/components/parameters/RunId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [externalRunId, confirm]
              properties:
                externalRunId: { type: string }
                confirm: { const: true }
      responses:
        "200":
          description: Reconciled run.
          content: { application/json: { schema: { $ref: "#/components/schemas/RunResponse" } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "409": { description: Run is not reconcilable or the id does not match. }
  /api/v1/duck/runs/{runId}/relay/claim:
    post:
      tags: [runs]
      summary: Claim a run submitted by the user's browser Local GPU Agent
      operationId: claimRelayRun
      parameters:
        - $ref: "#/components/parameters/RunId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [externalRunId]
              properties:
                externalRunId: { type: string, maxLength: 120 }
      responses:
        "200": { description: Relay run claimed. }
        "409": { description: Another browser already claimed the run. }
  /api/v1/duck/runs/{runId}/relay/sync:
    post:
      tags: [runs]
      summary: Sync status from a browser Local GPU Agent
      operationId: syncRelayRun
      parameters:
        - $ref: "#/components/parameters/RunId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [status]
              properties:
                status: { type: string, enum: [queued, running, completed, failed] }
                message: { type: string, maxLength: 500 }
      responses:
        "200": { description: Relay status accepted. }
        "400": { $ref: "#/components/responses/BadRequest" }
  /api/v1/duck/runs/{runId}/relay/artifact:
    post:
      tags: [runs]
      summary: Upload a digest-verified artifact from a browser Local GPU Agent
      operationId: uploadRelayArtifact
      parameters:
        - $ref: "#/components/parameters/RunId"
        - name: X-Artifact-Sha256
          in: header
          required: true
          schema: { type: string, pattern: "^[a-f0-9]{64}$" }
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema: { type: string, format: binary }
      responses:
        "200": { description: Artifact stored after SHA-256 verification. }
        "400": { $ref: "#/components/responses/BadRequest" }
        "413": { description: Artifact exceeds 50 MiB. }
  /api/v1/duck/runs/{runId}/policy.onnx:
    get:
      tags: [runs]
      summary: Download the completed run's ONNX policy bytes for the browser trial
      operationId: getRunPolicyOnnx
      description: >-
        Serves the digest-verified ONNX artifact of a completed, real (non-mock)
        local run so the browser trial runs the exact bytes that would be
        staged to a board. The browser trial is an operator aid and never
        release evidence. The response carries the worker-recomputed
        X-Artifact-Sha256 header and is rejected when it diverges from the
        ledger's recorded digest.
      parameters:
        - $ref: "#/components/parameters/RunId"
      responses:
        "200":
          description: ONNX policy bytes.
          content:
            application/octet-stream:
              schema: { type: string, format: binary }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "404": { description: Run not found or not owned by the account. }
        "409":
          description: >-
            Trial not available: run unfinished, mock, wrong backend, no ONNX
            artifact, artifact bytes unreadable, or digest mismatch
            (SIM2REAL_POLICY_TRIAL_*).
  /api/v1/duck/telemetry:
    post:
      tags: [telemetry]
      summary: Append one ordered telemetry chunk
      operationId: appendTelemetry
      security:
        - cookieAuth: []
        - telemetryBearer: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/TelemetryRequest" }
      responses:
        "201":
          description: Chunk accepted.
          content: { application/json: { schema: { $ref: "#/components/schemas/TelemetryResponse" } } }
        "200":
          description: Idempotent replay.
          content: { application/json: { schema: { $ref: "#/components/schemas/TelemetryResponse" } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "413": { description: Telemetry quota exceeded. }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "403": { description: Bearer attestation owner, binding, or source mismatch. }
        "409": { description: Idempotency or telemetry sequence conflict. }
  /api/v1/duck/runs/{runId}/telemetry:
    parameters:
      - $ref: "#/components/parameters/RunId"
    get:
      tags: [telemetry]
      summary: List accepted telemetry chunks
      operationId: listTelemetry
      responses:
        "200":
          description: Telemetry chunks.
          content: { application/json: { schema: { $ref: "#/components/schemas/TelemetryListResponse" } } }
        "404": { $ref: "#/components/responses/NotFound" }
    post:
      tags: [telemetry]
      summary: Append a chunk using the run id in the path
      operationId: appendRunTelemetry
      security:
        - cookieAuth: []
        - telemetryBearer: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/TelemetryRequestWithoutRunId" }
      responses:
        "201":
          description: Chunk accepted.
          content: { application/json: { schema: { $ref: "#/components/schemas/TelemetryResponse" } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "403": { description: Bearer attestation owner, binding, or source mismatch. }
        "409": { description: Idempotency or telemetry sequence conflict. }
  /api/v1/duck/runs/{runId}/replay:
    get:
      tags: [telemetry]
      summary: Read the replay summary
      operationId: getReplay
      parameters:
        - $ref: "#/components/parameters/RunId"
      responses:
        "200":
          description: Replay and evaluation summary.
          content: { application/json: { schema: { $ref: "#/components/schemas/ReplayResponse" } } }
        "404": { $ref: "#/components/responses/NotFound" }
  /api/v1/duck/runs/{runId}/logs:
    get:
      tags: [runs]
      summary: Read incremental engine stdout/stderr log lines
      operationId: getRunLogs
      description: >-
        Proxies the local training worker's bounded line ring (scrubbed
        stdout/stderr, newest 600 lines / 64 KiB) for a local-backend run.
        Lines carry worker-assigned sequence numbers; the `after` query
        parameter is a cursor so a poll returns only the new tail. Any job
        status may be read — queued runs have no lines yet and terminal runs
        keep their final log for post-mortem inspection. RoboGo or mock runs
        answer 409: there is no log channel to serve, and the platform never
        fabricates one.
      parameters:
        - $ref: "#/components/parameters/RunId"
        - name: after
          in: query
          required: false
          schema: { type: integer, minimum: 0, default: 0 }
          description: Only lines with a sequence number greater than this cursor are returned.
      responses:
        "200":
          description: >-
            Log lines plus cursor state (`total`, `retainedFrom`, and
            `truncated` when the cursor predates the retention window).
          content:
            application/json:
              schema:
                type: object
                required: [ok, runId, status, total, retainedFrom, lines]
                properties:
                  ok: { type: boolean }
                  runId: { type: string }
                  status: { type: string }
                  total: { type: integer }
                  retainedFrom: { type: integer }
                  truncated: { type: boolean }
                  lines:
                    type: array
                    items:
                      type: object
                      required: [n, stream, text]
                      properties:
                        n: { type: integer, minimum: 1 }
                        stream: { type: string, enum: [stdout, stderr] }
                        text: { type: string, maxLength: 2000 }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409":
          description: No log channel (remote runner, mock run, or no external run id).
        "503":
          description: Worker temporarily unreachable; retryable.
  /api/v1/duck/runs/{runId}/replay-video:
    parameters:
      - $ref: "#/components/parameters/RunId"
    post:
      tags: [telemetry]
      summary: Render the run's camera frames into an MP4 artifact
      operationId: renderReplayVideo
      description: >-
        Encodes the aligned camera frames already accepted in the run's
        telemetry into a shareable MP4 (server-side ffmpeg, raw rgb8/bgr8/
        mono8 piped in). The video is a rendering of accepted evidence, not
        new evidence: only a single-source, fully attested board run
        qualifies — mixed or imported runs fail closed with the reason. The
        digest and frame count are recorded in the run's metrics; the bytes
        are digest-re-verified on every serve. A geometry mismatch across
        frames or a missing ffmpeg is refused, never substituted.
      responses:
        "200":
          description: Video rendered; digest, size, frame count, fps, and duration.
          content:
            application/json:
              schema:
                type: object
                required: [ok, runId, video]
                properties:
                  ok: { type: boolean }
                  runId: { type: string }
                  video:
                    type: object
                    required: [sha256, sizeBytes, frameCount, fps, durationSeconds, url]
                    properties:
                      sha256: { type: string }
                      sizeBytes: { type: integer }
                      frameCount: { type: integer }
                      fps: { type: number }
                      durationSeconds: { type: number }
                      url: { type: string }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409":
          description: Not eligible (mixed sources, not attested, no camera frames, or geometry mismatch).
        "503":
          description: ffmpeg render failed or is unavailable; retryable.
    get:
      tags: [telemetry]
      summary: Download the rendered replay video bytes
      operationId: downloadReplayVideo
      description: >-
        Streams the MP4 rendered by the POST of the same path. Served only
        when the run's metrics record a replay video whose sha256 matches the
        bytes on disk; a stale or tampered file answers 404 instead of
        unverified content.
      responses:
        "200":
          description: MP4 bytes (digest in X-Replay-Video-Sha256).
          content:
            video/mp4:
              schema: { type: string, format: binary }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "404":
          description: Run not found, or no digest-matching rendered video.
  /api/v1/duck/runs/{runId}/retraining-advice:
    get:
      tags: [telemetry]
      summary: Read-only drift analysis and optional retraining suggestion
      description: >-
        Analyzes board telemetry drift (action MAE, done ratio, stale
        observation ratio) and returns an advisory verdict plus a pre-filled
        training request when retraining is recommended. Read-only: the
        flywheel never submits a run; the operator must POST /runs explicitly.
      operationId: getRetrainingAdvice
      parameters:
        - $ref: "#/components/parameters/RunId"
      responses:
        "200":
          description: Advisory verdict, per-signal evidence, and optional suggested training request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean }
                  advice:
                    type: object
                    properties:
                      verdict: { type: string, enum: [retrain-recommended, healthy, insufficient-evidence] }
                      checkedAt: { type: string, format: date-time }
                      runId: { type: string }
                      taskId: { type: string }
                      boardSamples: { type: integer, minimum: 0 }
                      summary: { type: string }
                      note: { type: string }
                      signals:
                        type: array
                        items:
                          type: object
                          properties:
                            id: { type: string }
                            label: { type: string }
                            value: { type: [number, "null"] }
                            threshold: { type: number }
                            breached: { type: boolean }
                            evidence: { type: string }
                      suggestedTraining:
                        type: object
                        description: Present only on retrain-recommended; a request body for the operator to submit, never auto-fired.
                        properties:
                          taskId: { type: string }
                          backend: { type: string, enum: [local] }
                          training:
                            type: object
                            properties:
                              profile: { type: string }
                              algorithm: { type: string }
        "404": { $ref: "#/components/responses/NotFound" }
  /api/v1/duck/runs/{runId}/board-sessions:
    get:
      tags: [telemetry]
      summary: Reconstruct board policy sessions from lifecycle events
      description: >-
        Aggregates the session-started / session-stopped lifecycle markers
        carried in board-agent telemetry chunks into one summary per policy
        motion session: start/stop times, stop reason, inference statistics,
        and the model fingerprint that was active. A session whose stop marker
        never arrived (process killed mid-motion) keeps an absent stoppedAt
        and is reported as interrupted, never as a clean stop. Sessions are
        attested only when every contributing chunk was server-attested;
        otherwise they are review-only evidence.
      operationId: listBoardSessions
      parameters:
        - $ref: "#/components/parameters/RunId"
      responses:
        "200":
          description: Board sessions reconstructed from accepted telemetry chunks.
          content:
            application/json:
              schema:
                type: object
                required: [ok, runId, sessions, count]
                properties:
                  ok: { const: true }
                  runId: { type: string }
                  count: { type: integer, minimum: 0 }
                  sessions:
                    type: array
                    items: { $ref: "#/components/schemas/BoardSessionSummary" }
        "404": { $ref: "#/components/responses/NotFound" }
  /api/v1/duck/runs-correlation:
    get:
      tags: [telemetry]
      summary: SimplerEnv-style sim-real correlation across runs
      description: >-
        Pairs each non-mock run's simulation-side metric (task-pack nominal
        envelope successRate, falling back to the final training progress
        recentSuccess) with its real-side telemetry evaluation actionMae, then
        reports Pearson r, Spearman rho and the MMRV summary of the signed
        relative error. Degenerate inputs (too few pairs, zero variance, no
        relative-error pairs) are reported as null with a reason — never as a
        fabricated coefficient. Evidence about the evidence chain, not a
        release gate. Direction: the sim channel is higher-is-better while the
        real channel is lower-is-better, so a NEGATIVE coefficient means the
        sim metric preserves the real ranking.
      operationId: getRunsCorrelation
      responses:
        "200":
          description: >-
            Pair list plus the correlation report; skipped runs are counted by
            reason (mock-run, missing-channel).
          content:
            application/json:
              schema:
                type: object
                required: [ok, methodology, channels, pairs, report]
                properties:
                  ok: { const: true }
                  methodology: { type: string }
                  channels:
                    type: object
                    properties:
                      sim: { type: string }
                      real: { type: string }
                  directionNote: { type: string }
                  runCount: { type: integer, minimum: 0 }
                  skipped:
                    type: object
                    additionalProperties: { type: integer, minimum: 0 }
                  pairs:
                    type: array
                    items:
                      type: object
                      required: [runId, simValue, realValue]
                      properties:
                        runId: { type: string }
                        simValue: { type: number }
                        realValue: { type: number }
                  report:
                    type: object
                    required: [pairCount, excludedPairCount, exclusionReasons, minPairs, pearson, spearman, mmrv]
                    properties:
                      pairCount: { type: integer, minimum: 0 }
                      excludedPairCount: { type: integer, minimum: 0 }
                      exclusionReasons:
                        type: object
                        additionalProperties: { type: integer, minimum: 0 }
                      minPairs: { type: integer, minimum: 2 }
                      pearson: { $ref: "#/components/schemas/CorrelationStatistic" }
                      spearman: { $ref: "#/components/schemas/CorrelationStatistic" }
                      mmrv:
                        oneOf:
                          - type: object
                            required: [mean, median, rms, variance, count]
                            properties:
                              mean: { type: number }
                              median: { type: number }
                              rms: { type: number }
                              variance: { type: number }
                              count: { type: integer, minimum: 1 }
                          - type: object
                            required: [value, reason]
                            properties:
                              value: { const: null }
                              reason: { type: string }
  /api/v1/duck/runs/{runId}/evaluate:
    post:
      tags: [telemetry]
      summary: Evaluate accepted telemetry against an optional reference
      operationId: evaluateRun
      parameters:
        - $ref: "#/components/parameters/RunId"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                referenceSamples: { type: array, maxItems: 5000, items: { $ref: "#/components/schemas/TelemetrySample" } }
                referenceJsonl: { type: string, maxLength: 2000000 }
      responses:
        "200":
          description: Evaluation.
          content: { application/json: { schema: { $ref: "#/components/schemas/EvaluationResponse" } } }
        "400": { $ref: "#/components/responses/BadRequest" }
  /api/sim2real/agent/plan:
    post:
      tags: [agent]
      summary: Parse a Chinese task into a guarded Sim2Real tool plan
      operationId: createSim2RealAgentPlan
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [message]
              properties:
                message: { type: string, minLength: 1, maxLength: 2000 }
                context: { type: object, additionalProperties: true }
      responses:
        "200": { description: Agent plan. }
        "400": { $ref: "#/components/responses/BadRequest" }
  /api/sim2real/agent/execute:
    post:
      tags: [agent]
      summary: Start an asynchronous guarded Agent run
      operationId: executeSim2RealAgentPlan
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [plan]
              properties:
                plan: { type: object, additionalProperties: true }
                approved: { type: boolean, default: false }
      responses:
        "202": { description: Run accepted. }
        "409": { description: Explicit approval required. }
        "429": { description: Per-account or process-wide active Agent run quota reached; retry after completion. }
  /api/sim2real/agent/runs/{runId}:
    get:
      tags: [agent]
      summary: Read Agent run status, tool events and evidence
      operationId: getSim2RealAgentRun
      parameters:
        - $ref: "#/components/parameters/RunId"
      responses:
        "200": { description: Agent run snapshot. }
        "404": { $ref: "#/components/responses/NotFound" }
  /api/sim2real/agent/capabilities:
    get:
      tags: [agent]
      summary: Discover the capabilities exposed by this deployment
      operationId: listSim2RealAgentCapabilities
      security: []
      description: >-
        Public metadata for clients that need to render the Agent surface. The
        legacy planner atoms and the DSH catalog are reported separately;
        `dsh.capabilities[].bound` is false when a deployment has not supplied a real
        product handler. Discovery never grants permission to execute an
        operation.
      responses:
        "200":
          description: Capability catalogs and runtime state.
          content:
            application/json:
              schema:
                type: object
                required: [ok, runtime, capabilities, dsh]
                properties:
                  ok: { const: true }
                  runtime: { type: string, enum: [legacy, dsh, dsh-configured] }
                  capabilities:
                    type: array
                    items:
                      type: object
                      required: [id, description, readOnly]
                      properties:
                        id: { type: string }
                        description: { type: string }
                        readOnly: { type: boolean }
                  dsh:
                    type: object
                    required: [configured, initialized, capabilities]
                    properties:
                      configured: { type: boolean }
                      initialized: { type: boolean }
                      imageInput:
                        type: object
                        required: [enabled, models, maxImageBytes, maxImageDimension, maxImagePixels, mediaTypes]
                        properties:
                          enabled: { type: boolean }
                          models: { type: array, maxItems: 16, items: { type: string } }
                          maxImageBytes: { type: integer, const: 4194304 }
                          maxImageDimension: { type: integer, const: 4096 }
                          maxImagePixels: { type: integer, const: 8000000 }
                          mediaTypes: { type: array, items: { type: string, enum: [image/png, image/jpeg] } }
                      capabilities:
                        type: array
                        items:
                          type: object
                          required: [id, description, readOnly, bound]
                          properties:
                            id: { type: string }
                            description: { type: string }
                            readOnly: { type: boolean }
                            bound: { type: boolean }
  /api/sim2real/dsh/approvals:
    get:
      tags: [agent]
      summary: List pending DSH tool approvals for the current owner
      operationId: listDshApprovals
      responses:
        "200":
          description: Pending approvals.
          content:
            application/json:
              schema:
                type: object
                required: [ok, approvals]
                properties:
                  ok: { type: boolean }
                  approvals: { type: array, items: { type: object } }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "403": { description: Account lacks the Agent permission. }
  /api/sim2real/dsh/approvals/{approvalId}:
    post:
      tags: [agent]
      summary: Approve or reject one pending DSH tool request
      operationId: decideDshApproval
      parameters:
        - in: path
          name: approvalId
          required: true
          schema: { type: string, maxLength: 160 }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [decision]
              properties:
                decision: { type: string, enum: [approve, reject] }
      responses:
        "200": { description: Decision recorded, content: { application/json: { schema: { type: object } } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "403": { description: Account lacks the Agent permission. }
        "404": { $ref: "#/components/responses/NotFound" }
  /api/sim2real/dsh/chat:
    post:
      tags: [agent]
      summary: Send one prompt to the deployment-owned DSH runtime
      operationId: askSim2RealDsh
      description: >-
        Authenticated execution endpoint. The runtime is available only when
        `RDK_SIM2REAL_DSH_RUNTIME` is enabled and its provider is configured;
        product capability handlers remain deployment-owned. The service
        returns a bounded session event tail for diagnostics and never exposes
        provider transport errors verbatim. One user-uploaded PNG/JPEG is accepted
        only for a model explicitly declared in RDK_SIM2REAL_DSH_VISION_MODELS.
        Bytes are fully decoded and stored under the owner-scoped session boundary;
        uploads never certify real hardware or bypass tool approvals. JSON is bounded
        to 6 MiB; image bytes to 4 MiB, each side to 4096 pixels and area to 8000000.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [message]
              properties:
                message: { type: string, minLength: 1, maxLength: 12000 }
                sessionId: { type: string, maxLength: 160, pattern: "^sim2real-[A-Za-z0-9-]+$" }
                model: { type: string, minLength: 1, maxLength: 160, pattern: "^[A-Za-z0-9][A-Za-z0-9._:/-]{0,159}$" }
                turnId:
                  type: string
                  maxLength: 120
                  pattern: "^[A-Za-z0-9_-]+$"
                  description: >-
                    Client-generated turn key. When present, the turn survives a
                    client disconnect and its outcome stays pollable at
                    `/dsh/chat/turns/{turnId}` until expiry; without it a client
                    disconnect cancels the turn (legacy behaviour).
                context:
                  type: object
                  properties:
                    modelId: { type: string, maxLength: 128 }
                    deviceId: { type: string, maxLength: 128 }
                    computeResourceId: { type: string, maxLength: 128 }
                image:
                  type: object
                  additionalProperties: false
                  required: [mediaType, base64]
                  properties:
                    mediaType: { type: string, enum: [image/png, image/jpeg] }
                    base64:
                      type: string
                      minLength: 4
                      maxLength: 5592408
                      description: Canonical base64 bytes, without a data URL prefix. URLs and attachment references are refused.
      responses:
        "200":
          description: DSH response and session evidence.
          content:
            application/json:
              schema:
                type: object
                required: [ok, sessionId, text, events]
                properties:
                  ok: { const: true }
                  sessionId: { type: string }
                  text: { type: string, maxLength: 20000 }
                  imageAccepted:
                    type: object
                    additionalProperties: false
                    required: [mediaType, width, height, bytes]
                    properties:
                      mediaType: { type: string, enum: [image/png, image/jpeg] }
                      width: { type: integer, minimum: 1, maximum: 4096 }
                      height: { type: integer, minimum: 1, maximum: 4096 }
                      bytes: { type: integer, minimum: 1, maximum: 4194304 }
                  usage:
                    type: object
                    additionalProperties: false
                    properties:
                      inputTokens: { type: integer, minimum: 0 }
                      outputTokens: { type: integer, minimum: 0 }
                      totalTokens: { type: integer, minimum: 0 }
                  events:
                    type: array
                    maxItems: 50
                    items:
                      type: object
                      required: [type]
                      additionalProperties: false
                      properties:
                        type: { type: string, maxLength: 80 }
                        at: { type: string, maxLength: 80 }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "403": { description: Account lacks the Agent permission. }
        "413": { description: Image bytes or JSON body exceed the upload limit. }
        "422": { description: Image cannot be fully decoded, geometry exceeds the limit, or selected model lacks an explicit image declaration. }
        "502": { description: DSH provider or runtime failure (generic, retryable). }
        "503": { description: DSH runtime is not enabled on this deployment. }
  /api/sim2real/dsh/chat/turns/{turnId}:
    get:
      tags: [agent]
      summary: Poll the outcome of a detached DSH chat turn
      operationId: getSim2RealDshTurn
      description: >-
        Re-attach surface for a turn sent with a `turnId`: the turn keeps
        running after its browser connection dies, and a reloaded page polls
        here until the terminal state. 404 covers missing, expired (15 min
        retention) and foreign turns alike; running turns past the retention
        window report `status: failed` with `DSH_TURN_TIMEOUT`.
      parameters:
        - name: turnId
          in: path
          required: true
          schema: { type: string, minLength: 1, maxLength: 120, pattern: "^[A-Za-z0-9_-]+$" }
      responses:
        "200":
          description: Turn state; the terminal outcome rides in `status`.
          content:
            application/json:
              schema:
                type: object
                required: [ok, turnId, sessionId, status]
                properties:
                  ok: { const: true }
                  turnId: { type: string }
                  sessionId: { type: string }
                  status: { type: string, enum: [running, complete, failed] }
                  text: { type: string, maxLength: 20000 }
                  reasoning: { type: string }
                  toolTrail: { type: array, items: { type: object } }
                  events: { type: array, items: { type: object } }
                  error: { type: string }
                  message: { type: string }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "403": { description: Account lacks the Agent permission. }
        "404": { description: Unknown, expired or foreign turn. }
  /api/sim2real/dsh/chat/turns/{turnId}/cancel:
    post:
      tags: [agent]
      summary: Cancel a detached DSH chat turn
      operationId: cancelSim2RealDshTurn
      description: >-
        Owner-scoped cancellation of a still-running turn. Idempotent: an
        already-terminal turn reports its current status unchanged.
      parameters:
        - name: turnId
          in: path
          required: true
          schema: { type: string, minLength: 1, maxLength: 120, pattern: "^[A-Za-z0-9_-]+$" }
      responses:
        "200":
          description: Cancellation accepted (or the turn had already finished).
          content:
            application/json:
              schema:
                type: object
                required: [ok, turnId, status]
                properties:
                  ok: { const: true }
                  turnId: { type: string }
                  status: { type: string, enum: [cancelled, complete, failed] }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "403": { description: Account lacks the Agent permission. }
        "404": { description: Unknown, expired or foreign turn. }
  /api/sim2real/auth/session:
    get:
      tags: [sso]
      summary: Current workbench session for the top-bar account menu
      operationId: getSim2RealAuthSession
      security: []
      description: >-
        No-store session probe behind the workbench "更多" menu. Never
        requires authentication: unauthenticated visitors and single-user
        standalone deployments get authenticated=false so the UI keeps its
        guest form. displayName/accountId appear only for a verified
        principal; logoutUrl only when the active auth adapter owns a logout
        route (studio-cookie or user-center).
      responses:
        "200":
          description: Session state; authentication is carried in the body, not the status code.
          content:
            application/json:
              schema:
                type: object
                required: [ok, authenticated]
                properties:
                  ok: { const: true }
                  authenticated: { type: boolean }
                  displayName: { type: string }
                  accountId: { type: string }
                  logoutUrl: { type: string, description: Logout endpoint relative to the deployment's public base path. }
  /api/sim2real/auth/studio-direct/logout:
    get:
      tags: [sso]
      summary: Invalidate the direct-login session cookies and return to the login page
      operationId: logoutStudioDirectSession
      security: []
      description: >-
        GET-redirect logout for the studio-cookie direct login surface (the
        endpoint advertised by /api/sim2real/auth/session as logoutUrl). Each
        session cookie passed through at login is expired, then the browser is
        redirected to the deployment login page with a logged-out notice.
      responses:
        "302":
          description: Redirect to the deployment login page after clearing session cookies.
        "404":
          description: Deployment is not running the studio-cookie direct login surface.
  /api/sim2real/auth/studio-direct/login:
    post:
      tags: [sso]
      summary: Direct-login form relay for the studio-cookie surface
      operationId: loginStudioDirectForm
      security: []
      description: >-
        Browser-form endpoint of the studio-cookie direct login relay
        (application/x-www-form-urlencoded). Credentials are relayed
        server-to-server to the configured Studio origin and never stored;
        success sets the passed-through session cookies. Mounted on every
        deployment so the contract is introspectable; deployments without the
        studio-cookie surface answer 404.
      responses:
        "302":
          description: Redirect to the workbench (success) or the login page with an error flag.
        "401":
          description: Credentials rejected by the upstream login service.
        "404":
          description: Deployment is not running the studio-cookie direct login surface.
  /api/sim2real/auth/studio-direct/login.json:
    post:
      tags: [sso]
      summary: Direct-login JSON relay for the studio-cookie surface
      operationId: loginStudioDirectJson
      security: []
      description: >-
        JSON twin of the form relay ({userName, password}). Success sets the
        passed-through session cookies and answers JSON; deployments without
        the studio-cookie surface answer 404.
      responses:
        "200":
          description: Session established; session cookies ride the Set-Cookie headers.
          content:
            application/json:
              schema:
                type: object
                required: [ok]
                properties:
                  ok: { const: true }
        "401":
          description: Credentials rejected by the upstream login service.
        "404":
          description: Deployment is not running the studio-cookie direct login surface.
  /api/sim2real/auth/uc/login:
    get:
      tags: [sso]
      summary: User Center OAuth2 authorization-code entry
      operationId: loginUserCenter
      security: []
      description: >-
        Redirects to the User Center authorize endpoint. Mounted on every
        deployment so the contract is introspectable; deployments without
        user-center SSO configured answer 404.
      responses:
        "302":
          description: Redirect to the User Center authorize URL.
        "404":
          description: Deployment is not running the user-center auth surface.
  /api/sim2real/auth/uc/callback:
    get:
      tags: [sso]
      summary: User Center OAuth2 code callback
      operationId: callbackUserCenter
      security: []
      description: >-
        Exchanges the authorization code for tokens, verifies the RS256/JWKS
        signature and mints the local session cookie. Path is configurable via
        RDK_SIM2REAL_UC_CALLBACK_PATH; the default is declared here.
        Deployments without user-center SSO configured answer 404.
      responses:
        "302":
          description: Redirect into the workbench on success, or to the login entry with a failure flag.
        "404":
          description: Deployment is not running the user-center auth surface.
  /api/sim2real/auth/uc/logout:
    get:
      tags: [sso]
      summary: Clear the user-center session cookie
      operationId: logoutUserCenter
      security: []
      description: >-
        Expires the user-center session cookie and returns to the workbench
        root. This is the logoutUrl advertised by /api/sim2real/auth/session
        in user-center mode. Deployments without user-center SSO configured
        answer 404.
      responses:
        "302":
          description: Redirect to the workbench root after clearing the session cookie.
        "404":
          description: Deployment is not running the user-center auth surface.
  /api/v1/duck/events:
    get:
      tags: [events]
      summary: Server-sent events stream for workbench domain events
      operationId: streamDuckEvents
      security: []
      description: >-
        EventSource stream bridging store domain events (run/deployment/model/
        project lifecycle) to the browser. Requires Accept: text/event-stream;
        shared deployments scope events to the authenticated account. The
        legacy /api/sim2real alias mounts the identical surface.
      responses:
        "200":
          description: text/event-stream; heartbeats keep intermediaries from closing idle streams.
        "401":
          description: Multi-user deployment and no verified principal on the request.
        "406":
          description: Accept header does not include text/event-stream.
        "503":
          description: Stream capacity exhausted.
  /api/v1/duck/events/stream:
    get:
      tags: [events]
      summary: Alias of the SSE events stream
      operationId: streamDuckEventsAlias
      security: []
      description: >-
        Alias route of /api/v1/duck/events kept for earlier clients; behavior
        and status codes are identical.
      responses:
        "200":
          description: text/event-stream.
        "401":
          description: Multi-user deployment and no verified principal on the request.
        "406":
          description: Accept header does not include text/event-stream.
        "503":
          description: Stream capacity exhausted.
  /api/v1/duck/deployments:
    get:
      tags: [deployments]
      summary: List account-scoped deployment plans
      operationId: listDeployments
      responses:
        "200":
          description: Recent deployment plans.
          content:
            application/json:
              schema:
                type: object
                required: [ok, deployments]
                properties:
                  ok: { const: true }
                  deployments: { type: array, items: { $ref: "#/components/schemas/Deployment" } }
        "401": { $ref: "#/components/responses/AuthRequired" }
    post:
      tags: [deployments]
      summary: Create a preflight, canary or live deployment plan
      operationId: createDeployment
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/DeploymentRequest" }
      responses:
        "201":
          description: Deployment plan.
          content: { application/json: { schema: { $ref: "#/components/schemas/DeploymentResponse" } } }
        "200":
          description: Idempotent replay.
          content: { application/json: { schema: { $ref: "#/components/schemas/DeploymentResponse" } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "409": { description: Board detection, compatibility, or release-evidence gate is not satisfied. }
  /api/v1/duck/deployments/{deploymentId}:
    parameters:
      - $ref: "#/components/parameters/DeploymentId"
    get:
      tags: [deployments]
      summary: Read a deployment plan
      operationId: getDeployment
      responses:
        "200":
          description: Deployment.
          content: { application/json: { schema: { $ref: "#/components/schemas/DeploymentResponse" } } }
        "404": { $ref: "#/components/responses/NotFound" }
  /api/v1/duck/deployments/{deploymentId}/cancel:
    post:
      tags: [deployments]
      summary: Cancel a deployment plan before board action
      operationId: cancelDeployment
      parameters:
        - $ref: "#/components/parameters/DeploymentId"
      responses:
        "200":
          description: Cancelled plan.
          content: { application/json: { schema: { $ref: "#/components/schemas/DeploymentResponse" } } }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: Plan is no longer cancellable. }
  /api/v1/duck/deployments/{deploymentId}/history:
    get:
      tags: [deployments]
      summary: Read deployment lifecycle history and verification evidence
      operationId: getDeploymentHistory
      parameters:
        - $ref: "#/components/parameters/DeploymentId"
      responses:
        "200":
          description: Append-only lifecycle events and latest verification.
          content:
            application/json:
              schema:
                type: object
                required: [ok, deploymentId, history, verification]
                properties:
                  ok: { const: true }
                  deploymentId: { type: string }
                  history: { type: array, items: { type: object, additionalProperties: true } }
                  verification: { type: [object, "null"], additionalProperties: true }
        "404": { $ref: "#/components/responses/NotFound" }
  /api/v1/duck/deployments/{deploymentId}/approval:
    post:
      tags: [deployments]
      summary: Record the human approval decision for a canary/live plan
      operationId: decideDeploymentApproval
      parameters:
        - $ref: "#/components/parameters/DeploymentId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                decision: { type: string, enum: [approved, rejected] }
                approved: { type: boolean, description: Legacy boolean alias for decision. }
                note: { type: string, maxLength: 500 }
              anyOf:
                - required: [decision]
                - required: [approved]
      responses:
        "200":
          description: Updated approval state; ready plans still require a board-agent executor.
          content: { application/json: { schema: { $ref: "#/components/schemas/DeploymentResponse" } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: Evidence gate, compatibility, or lifecycle state does not permit the decision. }
  /api/v1/duck/deployments/{deploymentId}/version-switch:
    post:
      tags: [deployments]
      summary: Create a guarded preflight plan for another model version
      operationId: switchDeploymentVersion
      parameters:
        - $ref: "#/components/parameters/DeploymentId"
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [targetModelId]
              properties:
                targetModelId: { type: string }
      responses:
        "201":
          description: New preflight plan.
          content: { application/json: { schema: { $ref: "#/components/schemas/DeploymentResponse" } } }
        "200":
          description: Idempotent replay.
          content: { application/json: { schema: { $ref: "#/components/schemas/DeploymentResponse" } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: Target model is invalid or incompatible. }
  /api/v1/duck/deployments/{deploymentId}/preflight:
    post:
      tags: [deployments]
      summary: Execute the fixed read-only board preflight
      operationId: runPreflight
      parameters:
        - $ref: "#/components/parameters/DeploymentId"
      responses:
        "200":
          description: Real read-only preflight passed.
          content: { application/json: { schema: { $ref: "#/components/schemas/PreflightResponse" } } }
        "409": { description: Preflight failed or a mock agent was used; actuator action is not attempted. }
        "503": { description: Board agent unavailable. }
  /api/devices/{deviceId}/board/detect:
    post:
      tags: [devices]
      summary: Probe and optionally persist board passport metadata
      operationId: detectBoard
      parameters:
        - $ref: "#/components/parameters/DeviceId"
        - in: query
          name: persist
          schema: { type: boolean, default: false }
      responses:
        "200":
          description: Board passport result.
          content: { application/json: { schema: { $ref: "#/components/schemas/BoardDetectResponse" } } }
        "404": { $ref: "#/components/responses/NotFound" }
        "503": { description: Board agent unavailable. }
  /api/v1/duck/board-station/policy:
    get:
      tags: [board-station]
      summary: Read board policy runtime state
      operationId: getBoardStationPolicy
      parameters:
        - in: query
          name: deviceId
          schema: { type: string }
      responses:
        "200":
          description: Policy runtime state and platform gates.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/BoardPolicyResponse" }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
        "502": { description: Board agent unreachable. }
  /api/v1/duck/board-station/onboarding/preflight:
    get:
      tags: [board-station]
      summary: Read the structured board onboarding preflight passport
      operationId: getBoardStationOnboardingPreflight
      parameters:
        - in: query
          name: deviceId
          schema: { type: string }
      responses:
        "200":
          description: Structured read-only board passport.
          content:
            application/json:
              schema:
                type: object
                required: [ok, deviceId, passport]
                properties:
                  ok: { type: boolean }
                  deviceId: { type: string }
                  passport: { type: object, additionalProperties: true }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
        "502": { description: Board agent unreachable. }
  /api/v1/duck/local-bridge/status:
    get:
      tags: [devices]
      summary: Read the current Local Bridge discovery status
      operationId: getLocalBridgeStatus
      responses:
        "200":
          description: Bridge sessions and discovered devices.
          content: { application/json: { schema: { type: object, additionalProperties: true } } }
        "401": { $ref: "#/components/responses/AuthRequired" }
  /api/v1/duck/local-bridge/pairing-code:
    post:
      tags: [devices]
      summary: Create a short-lived Local Bridge pairing command
      operationId: createLocalBridgePairingCode
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object, additionalProperties: true }
      responses:
        "200": { description: Pairing command created. }
        "401": { $ref: "#/components/responses/AuthRequired" }
  /api/v1/duck/local-bridge/devices/{bridgeDeviceId}/connect:
    post:
      tags: [devices]
      summary: Register a discovered Local Bridge device in Sim2Real
      operationId: connectLocalBridgeDevice
      parameters:
        - in: path
          name: bridgeDeviceId
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema: { type: object, additionalProperties: true }
      responses:
        "200": { description: Device connected and registered. }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
        "502": { description: Bridge device registration failed. }
  /api/v1/duck/board-station/policy/files:
    get:
      tags: [board-station]
      summary: List staged policy files in the board policies directory
      operationId: listBoardStationPolicyFiles
      parameters:
        - in: query
          name: deviceId
          schema: { type: string }
      responses:
        "200":
          description: Read-only listing of the pinned board policies directory.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean }
                  policies:
                    type: array
                    items:
                      type: object
                      properties:
                        name: { type: string }
                        bytes: { type: integer, minimum: 0 }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "502": { description: Board agent unreachable. }
  /api/v1/duck/board-station/policy/stage:
    post:
      tags: [board-station]
      summary: Stage a training artifact into the board policies directory
      description: >-
        Three-hop evidence chain: fetches the run's policy.onnx bytes from the
        training worker, cross-checks the SHA-256 against the run ledger, and
        forwards to the board agent which verifies the digest again before an
        atomic write. Staging only writes the file — it never loads the model
        and never moves the robot; loading and starting stay separate explicit
        operator actions.
      operationId: stageBoardStationPolicy
      parameters:
        - in: query
          name: deviceId
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [runId]
              properties:
                runId: { type: string, pattern: "^[\\w.-]{1,120}$" }
                filename:
                  type: string
                  description: Optional bare filename; defaults to <runId>.onnx.
                  pattern: "^[\\w.-]+\\.onnx$"
      responses:
        "200":
          description: Artifact staged into the board policies directory.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean }
                  staged: { type: boolean }
                  path: { type: string }
                  bytes: { type: integer, minimum: 0 }
                  sha256: { type: string }
                  policies:
                    type: array
                    items:
                      type: object
                      properties:
                        name: { type: string }
                        bytes: { type: integer, minimum: 0 }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409":
          description: >-
            Platform policy gate disabled, run not staged-eligible (mock,
            not completed, wrong backend/format, missing digest), artifact
            unavailable, digest mismatch, or filename conflict.
        "501": { description: Run artifact fetching is not wired on this deployment. }
        "502": { description: Board agent unreachable. }
  /api/v1/duck/board-station/policy/load:
    post:
      tags: [board-station]
      summary: Load an allowlisted ONNX policy from the board policies directory
      operationId: loadBoardStationPolicy
      parameters:
        - in: query
          name: deviceId
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [path]
              properties:
                path: { type: string, pattern: "^[\\w.-]+\\.onnx$" }
      responses:
        "200": { description: Policy loaded. }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: Platform policy gate is disabled. }
        "502": { description: Board agent unreachable. }
  /api/v1/duck/board-station/policy/start:
    post:
      tags: [board-station]
      summary: Start constrained policy motion after all gates are enabled
      operationId: startBoardStationPolicy
      parameters:
        - in: query
          name: deviceId
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [direction]
              properties:
                direction: { type: number, minimum: -1, maximum: 1 }
      responses:
        "200": { description: Policy motion started. }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: One or more safety gates are disabled. }
        "502": { description: Board agent unreachable. }
  /api/v1/duck/board-station/policy/reset:
    post:
      tags: [board-station]
      summary: Reset a sticky policy runtime fault
      operationId: resetBoardStationPolicy
      parameters:
        - in: query
          name: deviceId
          schema: { type: string }
      responses:
        "200": { description: Policy fault reset. }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: Platform policy gate is disabled. }
        "502": { description: Board agent unreachable. }
  /api/v1/duck/board-station/policy/stop:
    post:
      tags: [board-station]
      summary: Stop policy motion and publish zero output
      operationId: stopBoardStationPolicy
      parameters:
        - in: query
          name: deviceId
          schema: { type: string }
      responses:
        "200": { description: Policy stopped. }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
        "502": { description: Board agent unreachable; watchdog remains active. }
  /api/v1/duck/board-station/health:
    get:
      tags: [board-station]
      summary: Station capability probe for the workbench
      operationId: getBoardStationHealth
      description: >-
        Returns the resolved station target device plus the agent's honest
        capability snapshot (capabilities, stationCommands, actuatorControl,
        mock, cameraSupported). Fails closed with 503 when no board agent is
        configured.
      parameters:
        - in: query
          name: deviceId
          schema: { type: string }
          description: Optional explicit station target; defaults to the first visible device.
      responses:
        "200":
          description: Station health and capabilities.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/StationHealthResponse" }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
        "502": { description: Board agent unreachable (retryable). }
        "503": { description: Board agent not configured. }
  /api/v1/duck/board-station/status:
    get:
      tags: [board-station]
      summary: One board status snapshot (CPU, memory, power, TROS topics)
      operationId: getBoardStationStatus
      parameters:
        - in: query
          name: deviceId
          schema: { type: string }
      responses:
        "200":
          description: Status snapshot.
          content:
            application/json:
              schema:
                type: object
                required: [ok, status]
                properties:
                  ok: { const: true }
                  status: { type: object, additionalProperties: true }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
        "502": { description: Board agent unreachable (retryable). }
        "503": { description: Board agent not configured. }
  /api/v1/duck/board-station/status/stream:
    get:
      tags: [board-station]
      summary: Forwarded NDJSON status heartbeat
      operationId: getBoardStationStatusStream
      description: >-
        Streams NDJSON status frames from the agent through the authenticated
        proxy; one upstream connection per client, torn down together, with a
        bounded lifetime.
      parameters:
        - in: query
          name: deviceId
          schema: { type: string }
      responses:
        "200":
          description: NDJSON stream (content-type application/x-ndjson).
          content: { application/x-ndjson: { schema: { type: object, additionalProperties: true } } }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
        "502": { description: Board agent stream unreachable (retryable). }
        "503": { description: Board agent not configured. }
  /api/v1/duck/board-station/camera.mjpeg:
    get:
      tags: [board-station]
      summary: Forwarded MJPEG camera stream
      operationId: getBoardStationCamera
      description: >-
        Forwards the board camera MJPEG stream; rendered directly by a plain
        img tag in the workbench. The agent reports 503 (not synthetic
        frames) when no camera is connected.
      parameters:
        - in: query
          name: deviceId
          schema: { type: string }
      responses:
        "200":
          description: MJPEG stream (multipart/x-mixed-replace).
          content:
            multipart/x-mixed-replace:
              schema: { type: string, format: binary }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
        "502": { description: Board agent stream unreachable (retryable). }
        "503": { description: Board agent not configured or camera absent. }
  /api/v1/duck/board-station/commands:
    post:
      tags: [board-station]
      summary: Dispatch one allowlisted read-only station command
      operationId: postBoardStationCommand
      description: >-
        Accepts only the four read-only station commands
        (list-tros-nodes, list-tros-topics, disk-usage, service-status);
        anything else is rejected before any agent call is made.
      parameters:
        - in: query
          name: deviceId
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [id]
              properties:
                id: { type: string, enum: [list-tros-nodes, list-tros-topics, disk-usage, service-status] }
      responses:
        "200":
          description: Command result from the agent.
          content:
            application/json:
              schema: { type: object, additionalProperties: true }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "502": { description: Board agent unreachable or refused the command. }
  /api/v1/duck/board-station/devices:
    get:
      tags: [board-station]
      summary: Devices usable as the station target
      operationId: getBoardStationDevices
      responses:
        "200":
          description: Visible devices and agent configuration state.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/StationDevicesResponse" }
        "401": { $ref: "#/components/responses/AuthRequired" }
  /api/v1/duck/board-station/drive:
    get:
      tags: [board-station]
      summary: Constrained-drive state (motion canary)
      operationId: getBoardStationDrive
      description: >-
        Honest snapshot of the constrained-drive canary: platform switch,
        board agent switch, and the actuator policy (clamps, window, publish
        rate, chassis watchdog). Read-only; never moves the robot.
      parameters:
        - in: query
          name: deviceId
          schema: { type: string }
      responses:
        "200":
          description: Drive state and policy.
          content: { application/json: { schema: { $ref: "#/components/schemas/DriveState" } } }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "502": { description: Board agent unreachable (retryable). }
    post:
      tags: [board-station]
      summary: One clamped, time-boxed motion command
      operationId: postBoardStationDrive
      description: >-
        Sends a single constrained motion command to the board chassis.
        Double-gated: 409 unless BOTH the platform switch
        (RDK_SIM2REAL_STATION_DRIVE_ENABLED=1) and the board agent switch
        (RDK_SIM2REAL_BOARD_AGENT_ENABLE_DRIVE=1) are enabled. Values are
        re-clamped at the proxy and again on the board (linear <=0.3 m/s,
        angular <=1.0 rad/s, duration 0.2-2.0 s). The chassis firmware
        watchdog stops the robot 500 ms after /cmd_vel goes silent.
      parameters:
        - in: query
          name: deviceId
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/DriveCommand" }
      responses:
        "200":
          description: Command accepted; motion window opened.
          content: { application/json: { schema: { $ref: "#/components/schemas/DriveState" } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "409":
          description: >-
            Refused: drive disabled on the platform (no agent call made), or
            the board agent refused (drive-disabled / out-of-range /
            rate-limited / publisher-unavailable). The refusal reason is
            passed through verbatim.
          content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
        "502": { description: Board agent unreachable (retryable); robot stays at rest. }
  /api/v1/duck/board-station/drive/stop:
    post:
      tags: [board-station]
      summary: Emergency zero-speed stop (always available)
      operationId: postBoardStationDriveStop
      description: >-
        Zero-speed emergency stop. Always forwarded to the board agent
        regardless of both drive switches, so the stop path has no failure
        mode from gating. The board writes a zero command frame and the
        chassis watchdog enforces rest.
      parameters:
        - in: query
          name: deviceId
          schema: { type: string }
      responses:
        "200":
          description: Stop delivered; zero-speed frame published.
          content: { application/json: { schema: { $ref: "#/components/schemas/DriveState" } } }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "502": { description: Board agent unreachable; chassis watchdog still enforces rest. }
  /api/v1/duck/board-station/policy-infer:
    post:
      tags: [board-station]
      summary: Batch inference on the loaded board model
      operationId: postBoardStationPolicyInfer
      description: >-
        Hybrid-mode primitive: the browser keeps computing physics while
        policy inference for N simulated bodies is served by the board's
        loaded model. Deliberately NOT gated by the motion switches —
        nothing here actuates hardware; the board runtime fail-closes every
        row and action before anything comes back. Batch capped at 64 rows.
      parameters:
        - in: query
          name: deviceId
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [observations]
              properties:
                observations:
                  type: array
                  minItems: 1
                  maxItems: 64
                  description: One observation vector per simulated body.
                  items:
                    type: array
                    items: { type: number }
      responses:
        "200":
          description: Batch of predicted action rows (board contract shape).
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "502": { description: Board agent unreachable or model not loaded (retryable). }
  /api/v1/duck/board-station/arm:
    get:
      tags: [board-station]
      summary: Constrained-arm (D6A) state
      operationId: getBoardStationArm
      description: >-
        Honest arm snapshot: platform switch, board agent arm capability and
        read-only pose preflight. arm_sdk absent or preflight off -> the arm
        is simply not advertised (never simulated).
      parameters:
        - in: query
          name: deviceId
          schema: { type: string }
      responses:
        "200":
          description: Arm state and capabilities.
          content: { application/json: { schema: { $ref: "#/components/schemas/ArmStatusResponse" } } }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "502": { description: Board agent unreachable (retryable). }
  /api/v1/duck/board-station/arm/move:
    post:
      tags: [board-station]
      summary: One clamped Cartesian move (blocking arm_sdk)
      operationId: postBoardStationArmMove
      description: >-
        Double-gated like the drive (RDK_SIM2REAL_STATION_ARM_ENABLED plus the
        board agent's RDK_SIM2REAL_BOARD_AGENT_ENABLE_ARM). The proxy clamps
        x/y/z into the declared workspace box and speedMmPerS to <=120, and
        the board clamps again. arm_sdk move_to is BLOCKING: acceptance (200)
        is not completion, and an in-flight move cannot be interrupted.
      parameters:
        - in: query
          name: deviceId
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/ArmMoveCommand" }
      responses:
        "200":
          description: Move accepted; completion lands in the arm status.
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "409":
          description: >-
            Refused: platform switch off (no agent call), or the board agent
            refused (arm-disabled / move-in-progress / rate-limited /
            out-of-workspace). Reason passed through verbatim.
        "502": { description: Board agent unreachable (retryable). }
  /api/v1/duck/board-station/arm/gripper:
    post:
      tags: [board-station]
      summary: Clamped gripper close/open
      operationId: postBoardStationArmGripper
      description: >-
        Same double gate as arm/move. close value is a force clamped to
        <=20; open value is a width clamped to <=65mm.
      parameters:
        - in: query
          name: deviceId
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/ArmGripperCommand" }
      responses:
        "200":
          description: Gripper command executed (blocking, short).
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "409": { description: Refused (switch off, invalid value, or agent-side refusal). }
        "502": { description: Board agent unreachable (retryable). }
  /api/v1/duck/board-station/arm/stop:
    post:
      tags: [board-station]
      summary: Refuse-new + best-effort home (always available)
      operationId: postBoardStationArmStop
      description: >-
        Always forwarded regardless of switches. Refuses NEW arm commands and
        best-effort returns the arm home; a mid-flight blocking move cannot be
        interrupted — the arm's physical e-stop is the final safety floor and
        the response states whether a move was in progress.
      parameters:
        - in: query
          name: deviceId
          schema: { type: string }
      responses:
        "200":
          description: Stop delivered (homed best-effort; wasMoving reported honestly).
        "401": { $ref: "#/components/responses/AuthRequired" }
        "502": { description: Board agent unreachable; use the arm's physical e-stop. }
  /api/v1/duck/board-station/switches:
    get:
      tags: [board-station]
      summary: Platform-side motion switch states
      operationId: getBoardStationSwitches
      description: >-
        Honest platform gate states for the constrained-drive canary and the
        policy runtime. Values resolve as runtime override over the env
        default (RDK_SIM2REAL_STATION_DRIVE_ENABLED / _POLICY_ENABLED).
        Readable even when the board is unreachable.
      responses:
        "200":
          description: Platform switch states.
          content: { application/json: { schema: { $ref: "#/components/schemas/StationSwitchState" } } }
        "401": { $ref: "#/components/responses/AuthRequired" }
    put:
      tags: [board-station]
      summary: Toggle the platform-side motion switches
      operationId: putBoardStationSwitches
      description: >-
        One half of the double gate: flips the platform drive/policy switches
        (persisted runtime override, env remains the deploy default). Turning
        a switch ON requires confirm=true in the same request (operator
        present, area cleared); turning OFF is always allowed. The board-side
        switches stay opt-in through the device-connection config surface.
        Emergency stop never consults these switches.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/StationSwitchPatch" }
      responses:
        "200":
          description: Updated switch states.
          content: { application/json: { schema: { $ref: "#/components/schemas/StationSwitchState" } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/AuthRequired" }
  /api/v1/duck/device-connections:
    get:
      tags: [devices]
      summary: List saved board connections and live tunnel flags
      operationId: listDeviceConnections
      description: >-
        Web-managed board connections (SSH coordinates). Each record reports
        whether its loopback SSH tunnel is currently up. Credentials are
        never stored: tunnels authenticate with the operator's local ssh
        keys/agent, exactly like scripts/deploy-x5-board-agent.sh.
      responses:
        "200":
          description: Saved connections.
          content: { application/json: { schema: { $ref: "#/components/schemas/DeviceConnectionList" } } }
        "401": { $ref: "#/components/responses/AuthRequired" }
    post:
      tags: [devices]
      summary: Save SSH coordinates for one board
      operationId: createDeviceConnection
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/DeviceConnectionInput" }
      responses:
        "201":
          description: Connection saved (tunnel not opened yet).
          content: { application/json: { schema: { $ref: "#/components/schemas/DeviceConnection" } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "409": { description: Same host/port/user connection already exists. }
        "507": { description: Connection quota (50) exceeded. }
  /api/v1/duck/device-connections/{connectionId}:
    delete:
      tags: [devices]
      summary: Remove a saved connection and tear down its tunnel
      operationId: deleteDeviceConnection
      parameters:
        - $ref: "#/components/parameters/ConnectionId"
      responses:
        "200": { description: Connection deleted. }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
  /api/v1/duck/device-connections/{connectionId}/connect:
    post:
      tags: [devices]
      summary: Open the SSH tunnel and probe the board agent
      operationId: connectDeviceConnection
      description: >-
        Spawns the server-side `ssh -N -L` loopback tunnel for this
        connection and verifies the board agent's /healthz through it. Fails
        closed: any SSH or health failure tears the tunnel down and reports
        the reason verbatim (no synthesized success).
      parameters:
        - $ref: "#/components/parameters/ConnectionId"
      responses:
        "200":
          description: Tunnel up and agent healthy.
          content: { application/json: { schema: { $ref: "#/components/schemas/DeviceConnectionProbe" } } }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
        "502": { description: SSH or agent health failure (reason passed through). }
        "503": { description: ssh client unavailable on the server. }
  /api/v1/duck/device-connections/{connectionId}/disconnect:
    post:
      tags: [devices]
      summary: Tear down this connection's tunnel
      operationId: disconnectDeviceConnection
      parameters:
        - $ref: "#/components/parameters/ConnectionId"
      responses:
        "200": { description: Tunnel torn down. }
        "401": { $ref: "#/components/responses/AuthRequired" }
  /api/v1/duck/device-connections/{connectionId}/config:
    get:
      tags: [devices]
      summary: Board-side motion switch states (through the tunnel)
      operationId: getDeviceConnectionConfig
      parameters:
        - $ref: "#/components/parameters/ConnectionId"
      responses:
        "200":
          description: Board switch states, env file path, restartability.
          content: { application/json: { schema: { $ref: "#/components/schemas/BoardConfigState" } } }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "409": { description: Tunnel is down; connect the device first. }
        "502": { description: Board agent unreachable or predates /v1/config. }
    post:
      tags: [devices]
      summary: Flip the board-side motion switches (agent restarts)
      operationId: putDeviceConnectionConfig
      description: >-
        Accepts ONLY the two documented opt-in switches
        (RDK_SIM2REAL_BOARD_AGENT_ENABLE_DRIVE / _ENABLE_POLICY). The board
        agent rewrites its EnvironmentFile and restarts its own systemd unit
        so it cold-starts through the normal publisher handshake and
        watchdog; the restart is refused while a motion window is active.
        This surface can never send a speed command.
      parameters:
        - $ref: "#/components/parameters/ConnectionId"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/BoardConfigPatch" }
      responses:
        "200": { description: Switches applied; agent restarted (or env updated without restart on non-systemd boards). }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "409": { description: Tunnel down, motion window active, or the board refused the restart. }
        "502": { description: Board agent unreachable; env untouched. }
  /api/v1/duck/compute-resources:
    get:
      tags: [workspace]
      summary: List account-owned GPU workers
      operationId: listComputeResources
      responses:
        "200": { description: Compute resources returned. }
    post:
      tags: [workspace]
      summary: Register a GPU worker
      operationId: createComputeResource
      requestBody:
        required: true
        content:
          application/json: { schema: { type: object, required: [name, runnerUrl] } }
      responses:
        "201": { description: Compute resource created. }
        "400": { $ref: "#/components/responses/BadRequest" }
  /api/v1/duck/compute-resources/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string }
    patch:
      tags: [workspace]
      summary: Update a GPU worker
      operationId: updateComputeResource
      requestBody:
        content:
          application/json: { schema: { type: object } }
      responses:
        "200": { description: Compute resource updated. }
        "404": { $ref: "#/components/responses/NotFound" }
    delete:
      tags: [workspace]
      summary: Remove a GPU worker
      operationId: deleteComputeResource
      responses:
        "200": { description: Compute resource removed. }
        "404": { $ref: "#/components/responses/NotFound" }
  /api/v1/duck/compute-resources/{id}/test:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string }
    post:
      tags: [workspace]
      summary: Probe a GPU worker health endpoint
      operationId: testComputeResource
      responses:
        "200": { description: Probe result returned. }
        "404": { $ref: "#/components/responses/NotFound" }
  /api/v1/duck/datasets/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string }
    get:
      tags: [workspace]
      summary: Read one immutable dataset snapshot
      operationId: getDataset
      responses:
        "200": { description: Dataset, content: { application/json: { schema: { $ref: "#/components/schemas/DatasetResponse" } } } }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
    patch:
      tags: [workspace]
      summary: Advance a dataset lifecycle state
      operationId: updateDatasetStatus
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [status]
              properties:
                status: { type: string, enum: [registered, ready, revoked] }
      responses:
        "200": { description: Dataset state updated, content: { application/json: { schema: { $ref: "#/components/schemas/DatasetResponse" } } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: Invalid or terminal lifecycle transition. }
  /api/v1/duck/datasets/{id}/revoke:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string }
    post:
      tags: [workspace]
      summary: Revoke an immutable dataset snapshot
      operationId: revokeDataset
      responses:
        "200": { description: Dataset revoked, content: { application/json: { schema: { $ref: "#/components/schemas/DatasetResponse" } } } }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: Dataset lifecycle transition is invalid. }
  /api/v1/duck/artifacts:
    get:
      tags: [workspace]
      summary: List immutable model artifacts and legacy catalog entries
      operationId: listArtifacts
      parameters:
        - in: query
          name: type
          schema: { type: string, enum: [model, checkpoint, recording, dataset, deployment, artifact] }
        - in: query
          name: modelId
          schema: { type: string }
        - in: query
          name: runId
          schema: { type: string }
        - in: query
          name: projectId
          schema: { type: string }
        - in: query
          name: taskId
          schema: { type: string }
        - in: query
          name: status
          schema: { type: string }
        - in: query
          name: limit
          schema: { type: integer, minimum: 1, maximum: 500, default: 200 }
      responses:
        "200": { description: Artifact catalog, content: { application/json: { schema: { $ref: "#/components/schemas/ArtifactsResponse" } } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/AuthRequired" }
    post:
      tags: [workspace]
      summary: Register one immutable artifact version
      operationId: createArtifact
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json: { schema: { $ref: "#/components/schemas/ArtifactInput" } }
      responses:
        "201": { description: Artifact registered, content: { application/json: { schema: { $ref: "#/components/schemas/ArtifactRecordResponse" } } } }
        "200": { description: Idempotent replay, content: { application/json: { schema: { $ref: "#/components/schemas/ArtifactRecordResponse" } } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "409": { description: Artifact version or idempotency conflict. }
        "422": { description: Artifact lineage is invalid. }
  /api/v1/duck/artifacts/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string }
    get:
      tags: [workspace]
      summary: Read one immutable artifact version
      operationId: getArtifact
      responses:
        "200": { description: Artifact, content: { application/json: { schema: { $ref: "#/components/schemas/ArtifactRecordResponse" } } } }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
    patch:
      tags: [workspace]
      summary: Advance an artifact lifecycle state
      operationId: updateArtifactStatus
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [status]
              properties:
                status: { type: string, enum: [validated, published, revoked] }
                reason: { type: string, maxLength: 500 }
      responses:
        "200": { description: Artifact state updated, content: { application/json: { schema: { $ref: "#/components/schemas/ArtifactRecordResponse" } } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: Artifact lifecycle transition is invalid. }
  /api/v1/duck/artifacts/{id}/validate:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string }
    post:
      tags: [workspace]
      summary: Validate an artifact version before publication
      operationId: validateArtifact
      responses:
        "200": { description: Artifact validated, content: { application/json: { schema: { $ref: "#/components/schemas/ArtifactRecordResponse" } } } }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: Artifact lifecycle transition is invalid. }
  /api/v1/duck/artifacts/{id}/publish:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string }
    post:
      tags: [workspace]
      summary: Publish an immutable artifact version
      operationId: publishArtifact
      responses:
        "200": { description: Artifact published, content: { application/json: { schema: { $ref: "#/components/schemas/ArtifactRecordResponse" } } } }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: Artifact must be validated before publication. }
  /api/v1/duck/artifacts/{id}/revoke:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string }
    post:
      tags: [workspace]
      summary: Revoke an artifact version while retaining evidence
      operationId: revokeArtifact
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties: { reason: { type: string, maxLength: 500 } }
      responses:
        "200": { description: Artifact revoked, content: { application/json: { schema: { $ref: "#/components/schemas/ArtifactRecordResponse" } } } }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: Artifact lifecycle transition is invalid. }
  /api/v1/duck/evaluations:
    get:
      tags: [runs]
      summary: List first-class evaluation evidence
      operationId: listEvaluations
      parameters:
        - in: query
          name: runId
          schema: { type: string }
        - in: query
          name: artifactId
          schema: { type: string }
        - in: query
          name: status
          schema: { type: string, enum: [pending, running, passed, failed, invalid] }
        - in: query
          name: limit
          schema: { type: integer, minimum: 1, maximum: 500, default: 200 }
      responses:
        "200": { description: Evaluation evidence, content: { application/json: { schema: { $ref: "#/components/schemas/EvaluationsResponse" } } } }
        "401": { $ref: "#/components/responses/AuthRequired" }
    post:
      tags: [runs]
      summary: Register evaluation evidence for a run
      operationId: createEvaluation
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json: { schema: { $ref: "#/components/schemas/EvaluationInput" } }
      responses:
        "201": { description: Evaluation created, content: { application/json: { schema: { $ref: "#/components/schemas/EvaluationRecordResponse" } } } }
        "200": { description: Idempotent replay, content: { application/json: { schema: { $ref: "#/components/schemas/EvaluationRecordResponse" } } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "422": { description: Evaluation lineage is invalid. }
  /api/v1/duck/evaluations/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string }
    get:
      tags: [runs]
      summary: Read one evaluation evidence record
      operationId: getEvaluation
      responses:
        "200": { description: Evaluation, content: { application/json: { schema: { $ref: "#/components/schemas/EvaluationRecordResponse" } } } }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
    patch:
      tags: [runs]
      summary: Advance evaluation status or append result evidence
      operationId: updateEvaluation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status: { type: string, enum: [pending, running, passed, failed, invalid] }
                summary: { type: string, maxLength: 500 }
                report: { type: object, additionalProperties: true }
                taskEvaluation: { $ref: "#/components/schemas/TaskEvaluation" }
                deviceId: { type: string }
      responses:
        "200": { description: Evaluation updated, content: { application/json: { schema: { $ref: "#/components/schemas/EvaluationRecordResponse" } } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: Evaluation lifecycle transition is invalid. }
  /api/v1/duck/lineage:
    get:
      tags: [workspace]
      summary: Read the owner-scoped dataset to deployment lineage graph
      operationId: getLineage
      parameters:
        - in: query
          name: runId
          schema: { type: string }
        - in: query
          name: artifactId
          schema: { type: string }
        - in: query
          name: evaluationId
          schema: { type: string }
        - in: query
          name: projectId
          schema: { type: string }
          description: Exactly one selector is required.
      responses:
        "200": { description: Lineage graph, content: { application/json: { schema: { $ref: "#/components/schemas/LineageResponse" } } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
  /api/v1/duck/runs/{runId}/lineage:
    parameters:
      - $ref: "#/components/parameters/RunId"
    get:
      tags: [runs]
      summary: Read lineage anchored at one run
      operationId: getRunLineage
      responses:
        "200": { description: Lineage graph, content: { application/json: { schema: { $ref: "#/components/schemas/LineageResponse" } } } }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
  /api/v1/duck/feedback:
    post:
      tags: [workspace]
      summary: Record one piece of granular workspace feedback
      operationId: createFeedback
      description: >-
        Operational telemetry only — feedback never feeds promotion or release
        gates. Unknown surface/verdict values degrade to closed contract
        defaults and are echoed in a `degraded` block instead of being
        rejected, so stale clients keep working.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [surface, verdict]
              properties:
                surface:
                  type: string
                  enum: [retraining-advice, agent-reply, run-record]
                verdict:
                  type: string
                  enum: [accurate, inaccurate]
                note: { type: string, maxLength: 600 }
                runId: { type: string, maxLength: 120 }
      responses:
        "201": { description: Feedback saved, content: { application/json: { schema: { type: object } } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/AuthRequired" }
    get:
      tags: [workspace]
      summary: List the caller's feedback with the closed contract values
      operationId: listFeedback
      responses:
        "200": { description: Feedback records, content: { application/json: { schema: { type: object } } } }
        "401": { $ref: "#/components/responses/AuthRequired" }
  /api/v1/duck/feedback/summary:
    get:
      tags: [workspace]
      summary: Aggregate reliance summary of the caller's feedback
      operationId: getFeedbackSummary
      responses:
        "200": { description: Per-surface counts and accuracy share, content: { application/json: { schema: { type: object } } } }
        "401": { $ref: "#/components/responses/AuthRequired" }
  /api/v1/duck/notices:
    get:
      tags: [workspace]
      summary: Read workspace notices (anonymous; packaging and health identity)
      operationId: getWorkspaceNotices
      security: []
      description: >-
        Served, never stored: the package version is the release identity and
        the storage readiness snapshot is the health identity, so there is no
        second source of truth that can drift. Accessible without a session.
      responses:
        "200": { description: Current notices, content: { application/json: { schema: { type: object } } } }
  /api/v1/duck/workshop-sessions:
    get:
      tags: [workspace]
      summary: Read owner-scoped current Workshop and history
      operationId: getWorkshop
      responses:
        "200":
          description: Owner-scoped Workshop state or single submission claim
        "400":
          description: Invalid or missing explicit input
        "401":
          description: Authentication required
        "403":
          description: Role does not allow this mutation
        "404":
          description: No owned experiment or course asset
        "409":
          description: Frozen recipe, uncertain submission, or previously claimed step
    post:
      tags: [workspace]
      summary: Record learner intent or claim one workflow step; submissions use normal runs API
      operationId: postWorkshop
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [modelId, computeResourceId]
              properties:
                modelId: { type: string }
                computeResourceId: { type: string }
                comparisonBaseId:
                  type: string
                  description: Owned Workshop with completed evaluation and the same model and resource.
      responses:
        "200":
          description: Owner-scoped Workshop state or single submission claim
        "400":
          description: Invalid or missing explicit input
        "401":
          description: Authentication required
        "403":
          description: Role does not allow this mutation
        "404":
          description: No owned experiment or course asset
        "409":
          description: Frozen recipe, uncertain submission, or previously claimed step
  /api/v1/duck/workshop-sessions/setup:
    get:
      tags: [workspace]
      summary: List the current learner's selectable Workshop compute resources
      operationId: listWorkshopSetupResources
      responses:
        "200":
          description: Current account and a list of resource IDs, names and last-known status.
        "401": { $ref: "#/components/responses/AuthRequired" }
    post:
      tags: [workspace]
      summary: Prepare a Workshop draft on an explicitly selected compute resource
      operationId: createWorkshopSetupDraft
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [accountId, computeResourceId]
              properties:
                accountId:
                  type: [string, "null"]
                  description: Account returned by the resource list, or null in local mode.
                computeResourceId: { type: string, minLength: 1, maxLength: 160 }
      responses:
        "200": { description: Draft session. No training or evaluation is submitted. }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/AuthRequired" }
        "403": { description: The current role cannot create a draft. }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: Existing course model contract does not match. }
        "503": { description: The course manifest or storage is unavailable. }
  /api/v1/duck/workshop-sessions/{contextId}:
    parameters:
      - in: path
        name: contextId
        required: true
        schema: { type: string, pattern: "^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$" }
    get:
      tags: [workspace]
      summary: Read owner-scoped current Workshop and history
      operationId: getWorkshopContextid
      responses:
        "200":
          description: Owner-scoped Workshop state or single submission claim
        "400":
          description: Invalid or missing explicit input
        "401":
          description: Authentication required
        "403":
          description: Role does not allow this mutation
        "404":
          description: No owned experiment or course asset
        "409":
          description: Frozen recipe, uncertain submission, or previously claimed step
  /api/v1/duck/workshop-sessions/{contextId}/comparison:
    parameters:
      - in: path
        name: contextId
        required: true
        schema: { type: string, pattern: "^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$" }
    get:
      tags: [workspace]
      summary: Compare up to three owner-scoped Workshop rounds
      operationId: getWorkshopComparison
      parameters:
        - in: query
          name: with
          description: One or two comma-separated owned context IDs. Omit to follow saved comparison links.
          schema: { type: string }
      responses:
        "200":
          description: Ordered round summaries and protocol and training-setup comparability flags
        "400":
          description: Invalid or duplicate round selection
        "401":
          description: Authentication required
        "404":
          description: No owned experiment
        "409":
          description: Incomplete or unverified evaluation evidence
  /api/v1/duck/workshop-sessions/{contextId}/select:
    parameters:
      - in: path
        name: contextId
        required: true
        schema: { type: string, pattern: "^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$" }
    post:
      tags: [workspace]
      summary: Record learner intent or claim one workflow step; submissions use normal runs API
      operationId: postWorkshopContextidSelect
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object }
      responses:
        "200":
          description: Owner-scoped Workshop state or single submission claim
        "400":
          description: Invalid or missing explicit input
        "401":
          description: Authentication required
        "403":
          description: Role does not allow this mutation
        "404":
          description: No owned experiment or course asset
        "409":
          description: Frozen recipe, uncertain submission, or previously claimed step
  /api/v1/duck/workshop-sessions/{contextId}/reference:
    parameters:
      - in: path
        name: contextId
        required: true
        schema: { type: string, pattern: "^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$" }
    post:
      tags: [workspace]
      summary: Record learner intent or claim one workflow step; submissions use normal runs API
      operationId: postWorkshopContextidReference
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object }
      responses:
        "200":
          description: Owner-scoped Workshop state or single submission claim
        "400":
          description: Invalid or missing explicit input
        "401":
          description: Authentication required
        "403":
          description: Role does not allow this mutation
        "404":
          description: No owned experiment or course asset
        "409":
          description: Frozen recipe, uncertain submission, or previously claimed step
  /api/v1/duck/workshop-sessions/{contextId}/pause:
    parameters:
      - in: path
        name: contextId
        required: true
        schema: { type: string, pattern: "^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$" }
    post:
      tags: [workspace]
      summary: Record learner intent or claim one workflow step; submissions use normal runs API
      operationId: postWorkshopContextidPause
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object }
      responses:
        "200":
          description: Owner-scoped Workshop state or single submission claim
        "400":
          description: Invalid or missing explicit input
        "401":
          description: Authentication required
        "403":
          description: Role does not allow this mutation
        "404":
          description: No owned experiment or course asset
        "409":
          description: Frozen recipe, uncertain submission, or previously claimed step
  /api/v1/duck/workshop-sessions/{contextId}/continue:
    parameters:
      - in: path
        name: contextId
        required: true
        schema: { type: string, pattern: "^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$" }
    post:
      tags: [workspace]
      summary: Record learner intent or claim one workflow step; submissions use normal runs API
      operationId: postWorkshopContextidContinue
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object }
      responses:
        "200":
          description: Owner-scoped Workshop state or single submission claim
        "400":
          description: Invalid or missing explicit input
        "401":
          description: Authentication required
        "403":
          description: Role does not allow this mutation
        "404":
          description: No owned experiment or course asset
        "409":
          description: Frozen recipe, uncertain submission, or previously claimed step
  /api/v1/duck/workshop-sessions/{contextId}/claim/{phase}:
    parameters:
      - in: path
        name: contextId
        required: true
        schema: { type: string, pattern: "^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$" }
      - in: path
        name: phase
        required: true
        schema: { type: string, enum: [train, evaluate] }
    post:
      tags: [workspace]
      summary: Record learner intent or claim one workflow step; submissions use normal runs API
      operationId: postWorkshopContextidClaimPhase
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object }
      responses:
        "200":
          description: Owner-scoped Workshop state or single submission claim
        "400":
          description: Invalid or missing explicit input
        "401":
          description: Authentication required
        "403":
          description: Role does not allow this mutation
        "404":
          description: No owned experiment or course asset
        "409":
          description: Frozen recipe, uncertain submission, or previously claimed step
  /api/v1/duck/experiments/capabilities:
    get:
      tags: [workspace]
      operationId: getExperimentCapabilities
      summary: Discover owner-scoped experiment references
      responses:
        "200":
          description: Versioned capability; does not submit a task.
          content:
            application/json:
              schema:
                type: object
                required: [ok, schemaVersion, ownerScoped, submission]
                properties:
                  ok: { const: true }
                  schemaVersion: { const: 1 }
                  ownerScoped: { const: true }
                  submission: { const: false }
        "401": { description: Login required. }
        "403": { description: Workspace read permission required. }
  /api/v1/duck/experiments:
    post:
      tags: [workspace]
      operationId: rememberExperiment
      summary: Bind existing training and same-parent evaluation to an owner-scoped experiment
      description: Requires workspace edit permission. Does not submit or retry Runs. Existing training binding is immutable; status and policy digests are re-read from the original Runs.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [contextId, runId]
              properties:
                contextId: { type: string, pattern: '^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$' }
                runId: { type: string, pattern: '^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$' }
                evaluationRunId: { type: string, pattern: '^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$' }
      responses:
        "200": { description: Same owner reference saved; repeated binding is idempotent. }
        "400": { description: Invalid reference. }
        "401": { description: Login required. }
        "403": { description: Workspace edit permission required. }
        "404": { description: Referenced Run not visible to current owner. }
        "409": { description: Reference, parent, model or policy digest conflict. }
        "503": { description: Private reference storage unavailable. }
  /api/v1/duck/experiments/{contextId}:
    get:
      tags: [workspace]
      operationId: resumeExperiment
      summary: Re-read the current owner's original Runs and verified experiment view
      parameters:
        - { in: path, name: contextId, required: true, schema: { type: string } }
      responses:
        "200": { description: Version 1 view and revision; completion, quality, media receipt and hardware evidence remain distinct. }
        "401": { description: Login required. }
        "403": { description: Workspace read permission required. }
        "404": { description: Experiment or original Run not visible to current owner. }
        "409": { description: Original reference no longer passes source validation. }
        "503": { description: Private reference storage unavailable. }
  /api/v1/duck/experiments/{contextId}/events:
    get:
      tags: [workspace]
      operationId: streamExperimentEvents
      summary: Replay owner-scoped snapshots with a bounded SSE connection
      description: Retains 128 changes. An expired cursor yields reset snapshots; future or malformed cursors are rejected. Connections close after 20 seconds so reconnect re-enters authentication. Closing a stream does not cancel any Run.
      parameters:
        - { in: path, name: contextId, required: true, schema: { type: string } }
        - { in: header, name: Last-Event-ID, schema: { type: string, pattern: '^[0-9]{1,12}$' } }
        - { in: query, name: after, schema: { type: string, pattern: '^[0-9]{1,12}$' } }
      responses:
        "200":
          description: snapshot/reset events contain id, observation time and verified view.
          content:
            text/event-stream:
              schema: { type: string }
        "400": { description: Invalid or future cursor. }
        "401": { description: Login required. }
        "403": { description: Workspace read permission required. }
        "404": { description: Experiment not visible to current owner. }
        "503": { description: Stream capacity or storage unavailable. }
components:
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: rdk_sso_web_session
      description: >-
        Site-wide encrypted session cookie issued by the Studio main shell;
        the reference studio-cookie-auth adapter verifies it with
        AES-256-GCM (v1.iv.tag.ciphertext). The reference local adapter has
        no login.
    telemetryBearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Short-lived server-issued HS256 board-agent attestation. Claims bind
        owner, runId and deviceId and include an exp Unix timestamp. Bearer
        uploads must include a non-negative chunk sequence; retries with the
        same (run, device, sequence, content) are idempotent while a conflicting
        sequence is rejected. The telemetry service sets attested=true only
        after successful verification; this credential cannot be used for other
        API resources. Legacy uploads without this credential remain review-only.
  parameters:
    ProductId:
      in: query
      name: productId
      schema: { type: string, enum: [microduck, rdk-duck] }
    IdempotencyKey:
      in: header
      name: Idempotency-Key
      schema: { type: string, minLength: 1, maxLength: 128 }
      description: Required for local/RoboGo runs and canary/live plans.
    ModelId:
      in: path
      name: modelId
      required: true
      schema: { type: string }
    DeviceId:
      in: path
      name: deviceId
      required: true
      schema: { type: string }
    ConnectionId:
      in: path
      name: connectionId
      required: true
      schema: { type: string }
      description: Board connection id from POST /device-connections.
    RunId:
      in: path
      name: runId
      required: true
      schema: { type: string }
    DeploymentId:
      in: path
      name: deploymentId
      required: true
      schema: { type: string }
    ProjectId:
      in: path
      # The runtime keeps the legacy `:id` mount parameter for this resource;
      # keep the versioned OpenAPI template aligned with the actual route.
      name: id
      required: true
      schema: { type: string }
  responses:
    Ready:
      description: Control plane is ready.
      content: { application/json: { schema: { $ref: "#/components/schemas/Health" } } }
    NotReady:
      description: A required dependency is not ready.
      content: { application/json: { schema: { $ref: "#/components/schemas/Health" } } }
    AuthRequired:
      description: Shared deployment requires a verified SSO principal.
      content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
    BadRequest:
      description: Input or contract validation failed.
      content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
    NotFound:
      description: Resource is not visible to this account.
      content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
  schemas:
    Project:
      type: object
      required: [id, name, slug, modelIds, datasetIds, createdAt, updatedAt]
      properties:
        id: { type: string }
        name: { type: string, maxLength: 160 }
        slug: { type: string, pattern: '^[a-z0-9][a-z0-9-]{1,63}$' }
        description: { type: string }
        modelIds: { type: array, items: { type: string } }
        datasetIds: { type: array, items: { type: string } }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
    ProjectInput:
      type: object
      required: [name]
      properties:
        name: { type: string, maxLength: 160 }
        slug: { type: string, maxLength: 64 }
        description: { type: string, maxLength: 4000 }
        modelIds: { type: array, maxItems: 100, items: { type: string } }
        datasetIds: { type: array, maxItems: 500, items: { type: string } }
    Dataset:
      type: object
      required: [id, name, createdAt, updatedAt]
      properties:
        id: { type: string }
        name: { type: string }
        version: { type: string, maxLength: 64 }
        description: { type: string }
        uri: { type: string }
        format: { type: string }
        sha256: { type: string, pattern: "^[a-f0-9]{64}$" }
        contractId: { type: string }
        sourceRunId: { type: string }
        sampleCount: { type: integer, minimum: 0 }
        sizeBytes: { type: integer, minimum: 0 }
        tags: { type: array, items: { type: string } }
        status: { type: string, enum: [registered, ready, revoked] }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
    DatasetInput:
      type: object
      required: [name]
      properties:
        name: { type: string, maxLength: 160 }
        version: { type: string, maxLength: 64 }
        description: { type: string, maxLength: 4000 }
        uri: { type: string, maxLength: 2048 }
        format: { type: string, maxLength: 32 }
        sha256: { type: string, pattern: "^[a-f0-9]{64}$" }
        contractId: { type: string, maxLength: 128 }
        sourceRunId: { type: string, maxLength: 128 }
        sampleCount: { type: integer, minimum: 0 }
        sizeBytes: { type: integer, minimum: 0 }
        tags: { type: array, maxItems: 32, items: { type: string } }
        status: { type: string, enum: [registered, ready] }
    ProjectsResponse:
      type: object
      required: [ok, projects]
      properties:
        ok: { const: true }
        projects: { type: array, items: { $ref: "#/components/schemas/Project" } }
    ProjectResponse:
      type: object
      required: [ok, project]
      properties:
        ok: { const: true }
        project: { $ref: "#/components/schemas/Project" }
    ProjectDetailResponse:
      allOf:
        - $ref: "#/components/schemas/ProjectResponse"
        - type: object
          properties:
            datasets: { type: array, items: { $ref: "#/components/schemas/Dataset" } }
            runs: { type: array, items: { $ref: "#/components/schemas/Run" } }
    RunComparisonResponse:
      type: object
      required: [ok, projectId, runs, comparison]
      properties:
        ok: { const: true }
        projectId: { type: string }
        runs: { type: array, items: { $ref: "#/components/schemas/Run" } }
        comparison: { type: array, items: { type: object, additionalProperties: true } }
    DatasetsResponse:
      type: object
      required: [ok, datasets]
      properties:
        ok: { const: true }
        datasets: { type: array, items: { $ref: "#/components/schemas/Dataset" } }
    DatasetResponse:
      type: object
      required: [ok, dataset]
      properties:
        ok: { const: true }
        dataset: { $ref: "#/components/schemas/Dataset" }
    ArtifactRecord:
      type: object
      required: [id, artifactId, version, name, role, kind, format, ref, sha256, datasetIds, evaluationIds, status, createdAt, updatedAt]
      properties:
        id: { type: string }
        artifactId: { type: string, maxLength: 128 }
        version: { type: string, maxLength: 64, pattern: '^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$' }
        name: { type: string, maxLength: 180 }
        role: { type: string, enum: [policy, compiled-policy, calibration] }
        kind: { type: string, enum: [source, compiled] }
        format: { type: string, enum: [pytorch, onnx, bin, hbm, gguf, unknown] }
        runtime: { type: string, enum: [cpu-onnx, bpu] }
        workload: { type: string, enum: [locomotion, perception, navigation, speech, multimodal] }
        threads: { type: integer, minimum: 1, maximum: 128 }
        targetPlatforms: { type: array, items: { type: string } }
        toolchainTarget: { type: string }
        acceleratorArchitecture: { type: string }
        runtimePackage: { type: string }
        ref: { type: string, pattern: '^artifact://' }
        sha256: { type: string, pattern: '^[a-f0-9]{64}$' }
        sizeBytes: { type: integer, minimum: 0 }
        modelId: { type: string }
        runId: { type: string }
        datasetIds: { type: array, items: { type: string } }
        evaluationIds: { type: array, items: { type: string } }
        contractId: { type: string }
        status: { type: string, enum: [draft, validated, published, revoked] }
        metadata: { type: object, additionalProperties: true }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
        publishedAt: { type: string, format: date-time }
        revokedAt: { type: string, format: date-time }
        revocationReason: { type: string }
    ArtifactInput:
      type: object
      required: [artifactId, version, name, role, kind, format, ref, sha256]
      properties:
        artifactId: { type: string, maxLength: 128 }
        version: { type: string, maxLength: 64 }
        name: { type: string, maxLength: 180 }
        role: { type: string, enum: [policy, compiled-policy, calibration] }
        kind: { type: string, enum: [source, compiled] }
        format: { type: string, enum: [pytorch, onnx, bin, hbm, gguf, unknown] }
        runtime: { type: string, enum: [cpu-onnx, bpu] }
        workload: { type: string, enum: [locomotion, perception, navigation, speech, multimodal] }
        threads: { type: integer, minimum: 1, maximum: 128 }
        targetPlatforms: { type: array, maxItems: 16, items: { type: string } }
        toolchainTarget: { type: string, maxLength: 128 }
        acceleratorArchitecture: { type: string, maxLength: 64 }
        runtimePackage: { type: string, maxLength: 128 }
        ref: { type: string, pattern: '^artifact://' }
        sha256: { type: string, pattern: '^[a-f0-9]{64}$' }
        sizeBytes: { type: integer, minimum: 0 }
        modelId: { type: string }
        runId: { type: string }
        datasetIds: { type: array, maxItems: 500, items: { type: string } }
        evaluationIds: { type: array, maxItems: 500, items: { type: string } }
        contractId: { type: string }
        status: { type: string, enum: [draft, validated, published] }
        metadata: { type: object, additionalProperties: true }
        idempotencyKey: { type: string, maxLength: 128 }
    ArtifactCatalogEntry:
      type: object
      required: [id, type, name, status, createdAt]
      properties:
        id: { type: string }
        type: { type: string, enum: [model, checkpoint, recording, dataset, deployment, artifact] }
        name: { type: string }
        status: { type: string }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
        modelId: { type: string }
        runId: { type: string }
        projectId: { type: string }
        taskId: { type: string }
        datasetIds: { type: array, items: { type: string } }
        artifactIds: { type: array, items: { type: string } }
        format: { type: string }
        uri: { type: string }
        sizeBytes: { type: integer, minimum: 0 }
        sampleCount: { type: integer, minimum: 0 }
        metadata: { type: object, additionalProperties: true }
    ArtifactsResponse:
      type: object
      required: [ok, artifacts, total, available]
      properties:
        ok: { const: true }
        artifacts: { type: array, items: { $ref: "#/components/schemas/ArtifactCatalogEntry" } }
        total: { type: integer, minimum: 0 }
        available: { type: integer, minimum: 0 }
    ArtifactRecordResponse:
      type: object
      required: [ok, artifact]
      properties:
        ok: { const: true }
        artifact: { $ref: "#/components/schemas/ArtifactRecord" }
        idempotentReplay: { type: boolean }
    EvaluationRecord:
      type: object
      required: [id, runId, modelId, datasetIds, status, summary, source, createdAt, updatedAt]
      properties:
        id: { type: string }
        runId: { type: string }
        modelId: { type: string }
        artifactId: { type: string }
        datasetIds: { type: array, items: { type: string } }
        projectId: { type: string }
        taskId: { type: string }
        status: { type: string, enum: [pending, running, passed, failed, invalid] }
        summary: { type: string }
        report: { type: object, additionalProperties: true }
        taskEvaluation: { $ref: "#/components/schemas/TaskEvaluation" }
        source: { type: string, enum: [platform, runner, import] }
        deviceId: { type: string }
        contractId: { type: string }
        seed: { type: integer, minimum: 0 }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
        completedAt: { type: string, format: date-time }
    EvaluationInput:
      type: object
      required: [runId]
      properties:
        runId: { type: string }
        artifactId: { type: string }
        datasetIds: { type: array, maxItems: 500, items: { type: string } }
        projectId: { type: string }
        taskId: { type: string }
        status: { type: string, enum: [pending, running, passed, failed, invalid], default: pending }
        summary: { type: string, maxLength: 500 }
        report: { type: object, additionalProperties: true }
        taskEvaluation: { $ref: "#/components/schemas/TaskEvaluation" }
        source: { type: string, enum: [platform, runner, import], default: import }
        deviceId: { type: string }
        contractId: { type: string }
        seed: { type: integer, minimum: 0 }
        idempotencyKey: { type: string, maxLength: 128 }
    EvaluationsResponse:
      type: object
      required: [ok, evaluations, total, available]
      properties:
        ok: { const: true }
        evaluations: { type: array, items: { $ref: "#/components/schemas/EvaluationRecord" } }
        total: { type: integer, minimum: 0 }
        available: { type: integer, minimum: 0 }
    EvaluationRecordResponse:
      type: object
      required: [ok, evaluation]
      properties:
        ok: { const: true }
        evaluation: { $ref: "#/components/schemas/EvaluationRecord" }
        idempotentReplay: { type: boolean }
    LineageResponse:
      type: object
      required: [ok, lineage]
      properties:
        ok: { const: true }
        lineage:
          type: object
          required: [project, datasets, run, runs, artifacts, evaluations, deployments]
          properties:
            project:
              oneOf:
                - $ref: "#/components/schemas/Project"
                - type: "null"
            datasets: { type: array, items: { $ref: "#/components/schemas/Dataset" } }
            run:
              oneOf:
                - $ref: "#/components/schemas/Run"
                - type: "null"
            runs: { type: array, items: { $ref: "#/components/schemas/Run" } }
            artifacts: { type: array, items: { $ref: "#/components/schemas/ArtifactRecord" } }
            evaluations: { type: array, items: { $ref: "#/components/schemas/EvaluationRecord" } }
            deployments: { type: array, items: { $ref: "#/components/schemas/Deployment" } }
    AuditEvent:
      type: object
      required: [id, at, action, resourceType, outcome, status]
      properties:
        id: { type: string }
        at: { type: string, format: date-time }
        owner: { type: string }
        actor: { type: object, additionalProperties: true }
        action: { type: string }
        resourceType: { type: string }
        resourceId: { type: string }
        outcome: { type: string, enum: [succeeded, failed, denied] }
        status: { type: integer, minimum: 100, maximum: 599 }
        requestId: { type: string }
        details: { type: object, additionalProperties: true }
    AuditResponse:
      type: object
      required: [ok, events, total]
      properties:
        ok: { const: true }
        events: { type: array, items: { $ref: "#/components/schemas/AuditEvent" } }
        total: { type: integer, minimum: 0 }
    AuditHealthResponse:
      type: object
      required: [ok, configured, readable, writable]
      properties:
        ok: { type: boolean }
        configured: { type: boolean }
        readable: { type: boolean }
        writable: { type: boolean }
        eventCount: { type: integer, minimum: 0, nullable: true }
    SsoLoginRequest:
      type: object
      required: [method]
      properties:
        method:
          type: string
          enum: [account, sms, email]
          description: Only whitelisted fields are relayed upstream; everything else is dropped.
        userName: { type: string, maxLength: 4096 }
        password: { type: string, maxLength: 4096, description: Relayed to the Studio account center, never stored. }
        mobile: { type: string, maxLength: 4096 }
        email: { type: string, maxLength: 4096 }
        code: { type: string, maxLength: 4096 }
        emailcode: { type: string, maxLength: 4096 }
    SsoSessionResponse:
      type: object
      required: [ok, identity]
      properties:
        ok: { const: true }
        identity:
          type: object
          required: [accountId]
          properties:
            accountId: { type: string }
            displayName: { type: string }
            email: { type: string }
        sessionExpiresAt: { type: string }
        loginRelay:
          type: object
          properties:
            configured: { type: boolean }
            loginPageUrl: { type: string }
    StationHealthResponse:
      type: object
      required: [ok, device, agent, cameraSupported]
      properties:
        ok: { const: true }
        device:
          type: object
          required: [id, name, status]
          properties:
            id: { type: string }
            name: { type: string }
            status: { type: string }
            boardPlatform: { type: [string, "null"] }
            boardModel: { type: [string, "null"] }
        agent:
          type: object
          required: [capabilities, stationCommands, actuatorControl, mock]
          properties:
            capabilities: { type: array, items: { type: string } }
            stationCommands: { type: array, items: { type: object, additionalProperties: true } }
            actuatorControl: { type: boolean }
            mock: { type: boolean }
        cameraSupported: { type: boolean }
    StationDevicesResponse:
      type: object
      required: [ok, agentConfigured, devices]
      properties:
        ok: { const: true }
        agentConfigured: { type: boolean }
        devices:
          type: array
          items:
            type: object
            required: [id, name, status]
            properties:
              id: { type: string }
              name: { type: string }
              status: { type: string }
              boardPlatform: { type: [string, "null"] }
              boardModel: { type: [string, "null"] }
              connectionMode: { type: [string, "null"] }
    BoardPolicyResponse:
      type: object
      required: [ok, platformEnabled, drivePlatformEnabled, policy]
      properties:
        ok: { const: true }
        platformEnabled: { type: boolean }
        drivePlatformEnabled: { type: boolean }
        policy:
          oneOf:
            - type: object
              additionalProperties: true
            - type: "null"
    DriveCommand:
      type: object
      required: [linear, angular, durationSec]
      properties:
        linear:
          type: number
          minimum: -0.3
          maximum: 0.3
          description: Forward/backward speed in m/s; re-clamped at both proxy and board.
        angular:
          type: number
          minimum: -1.0
          maximum: 1.0
          description: Yaw rate in rad/s; re-clamped at both proxy and board.
        durationSec:
          type: number
          minimum: 0.2
          maximum: 2.0
          description: Motion window length in seconds; one command may never drive longer.
    StationSwitchState:
      type: object
      required: [ok, drive, policy]
      properties:
        ok: { type: boolean }
        drive:
          type: boolean
          description: Platform constrained-drive switch (runtime override over RDK_SIM2REAL_STATION_DRIVE_ENABLED).
        policy:
          type: boolean
          description: Platform policy-runtime switch (runtime override over RDK_SIM2REAL_STATION_POLICY_ENABLED).
        arm:
          type: boolean
          description: Platform constrained-arm (D6A) switch (runtime override over RDK_SIM2REAL_STATION_ARM_ENABLED).
    StationSwitchPatch:
      type: object
      properties:
        drive: { type: boolean, description: New platform drive switch value. }
        policy: { type: boolean, description: New platform policy switch value. }
        arm: { type: boolean, description: New platform constrained-arm (D6A) switch value. }
        confirm:
          type: boolean
          description: Required true when turning a switch ON (operator present, area cleared).
        reset:
          type: boolean
          description: True to drop the runtime override and fall back to the env default.
    DeviceConnection:
      type: object
      required: [id, label, host, port, username, agentPort, tunnelActive]
      properties:
        id: { type: string }
        label: { type: string }
        host: { type: string, description: SSH host/IP without scheme. }
        port: { type: integer, description: SSH port (default 22). }
        username: { type: string }
        agentPort: { type: integer, description: Board agent port on the board (default 19100). }
        tunnelActive: { type: boolean, description: True while this connection's loopback tunnel is up. }
        createdAt: { type: string, format: date-time }
        lastCheckedAt: { type: string, format: date-time, nullable: true }
        lastCheckOk: { type: boolean, nullable: true }
        lastCheckMessage: { type: string }
    DeviceConnectionList:
      type: object
      required: [ok, connections]
      properties:
        ok: { type: boolean }
        connections:
          type: array
          items: { $ref: "#/components/schemas/DeviceConnection" }
        sshNote: { type: string }
    DeviceConnectionInput:
      type: object
      required: [host]
      properties:
        host: { type: string, description: Board IP or hostname, no scheme. }
        port: { type: integer, default: 22 }
        username: { type: string, default: root }
        label: { type: string }
        agentPort: { type: integer, default: 19100 }
    DeviceConnectionProbe:
      type: object
      required: [ok, connection, probe]
      properties:
        ok: { type: boolean }
        connection: { $ref: "#/components/schemas/DeviceConnection" }
        probe:
          type: object
          required: [ok, message]
          properties:
            ok: { type: boolean }
            message: { type: string }
            agentInfo:
              type: object
              properties:
                mock: { type: boolean }
                capabilities: { type: array, items: { type: string } }
                boardModel: { type: string }
    BoardConfigState:
      type: object
      required: [ok, switches, restartable]
      properties:
        ok: { type: boolean }
        envFile: { type: string }
        envFileExists: { type: boolean }
        unit: { type: string }
        systemdManaged: { type: boolean }
        restartable: { type: boolean }
        switches:
          type: object
          required: [RDK_SIM2REAL_BOARD_AGENT_ENABLE_DRIVE, RDK_SIM2REAL_BOARD_AGENT_ENABLE_POLICY]
          properties:
            RDK_SIM2REAL_BOARD_AGENT_ENABLE_DRIVE: { type: boolean }
            RDK_SIM2REAL_BOARD_AGENT_ENABLE_POLICY: { type: boolean }
    BoardConfigPatch:
      type: object
      required: [switches]
      properties:
        switches:
          type: object
          minProperties: 1
          maxProperties: 2
          propertyNames:
            enum: [RDK_SIM2REAL_BOARD_AGENT_ENABLE_DRIVE, RDK_SIM2REAL_BOARD_AGENT_ENABLE_POLICY]
          additionalProperties: { type: boolean }
    DriveState:
      type: object
      required: [ok, platformEnabled, drive]
      properties:
        ok: { type: boolean }
        platformEnabled:
          type: boolean
          description: The platform-side drive switch state (RDK_SIM2REAL_STATION_DRIVE_ENABLED).
        drive:
          type: object
          required: [enabled, active]
          properties:
            enabled: { type: boolean, description: Board agent drive switch state. }
            active: { type: boolean, description: True while a motion window is open. }
            linear: { type: number }
            angular: { type: number }
            remainingMs: { type: integer }
            lastStopReason: { type: string }
            published: { type: integer, description: Total accepted commands since agent start. }
        actuatorPolicy:
          type: object
          properties:
            enabled: { type: boolean }
            maxLinear: { type: number }
            maxAngular: { type: number }
            maxWindowSec: { type: number }
            publishHz: { type: integer }
            chassisWatchdogMs: { type: integer }
            emergencyStop: { type: string }
    ArmStatusResponse:
      type: object
      required: [ok, platformEnabled]
      properties:
        ok: { type: boolean }
        platformEnabled:
          type: boolean
          description: Platform constrained-arm switch state.
        arm:
          type: object
          description: >-
            Board arm snapshot. available=false carries a reason; the arm is
            never simulated.
          properties:
            available: { type: boolean }
            reason: { type: string }
            mock: { type: boolean }
            enabled: { type: boolean }
            moving: { type: boolean }
            pose: { type: object, description: arm_sdk get_pose() snapshot. }
            lastPose: { type: object }
            lastError: { type: string }
        capabilities:
          type: array
          items: { type: string }
          description: arm-preflight / constrained-arm-drive, as advertised by the board.
    ArmMoveCommand:
      type: object
      required: [x, y, z]
      properties:
        x: { type: number, description: Base-frame X, mm; clamped to the workspace box. }
        y: { type: number, description: Base-frame Y, mm; clamped to the workspace box. }
        z: { type: number, description: Base-frame Z, mm; clamped to the workspace box. }
        speedMmPerS: { type: number, description: Move speed, mm/s; default 60, clamped <=120. }
    ArmGripperCommand:
      type: object
      required: [action, value]
      properties:
        action: { type: string, enum: [close, open] }
        value:
          type: number
          description: close force (clamped <=20) or open width in mm (clamped <=65).
    Error:
      type: object
      required: [ok, error]
      properties:
        ok: { const: false }
        error: { type: string }
        code: { type: string }
        message: { type: string, description: Human-readable detail when available. }
        requestId: { type: string }
        retryable: { type: boolean }
    Health:
      type: object
      required: [ok, service, ready, schemaVersion]
      properties:
        ok: { type: boolean }
        service: { const: sim2real-web }
        ready: { type: boolean }
        schemaVersion: { type: integer, const: 1 }
        degraded: { type: array, items: { type: string } }
    BoardDetectResponse:
      type: object
      required: [ok, platform, model, osVersion, checks, device, output, persisted, mock, actuatorControl]
      properties:
        ok: { const: true }
        platform: { type: [string, "null"] }
        model: { type: string }
        osVersion: { type: string }
        checks: { type: object, additionalProperties: true }
        device: { type: object, additionalProperties: true }
        output: { type: string, maxLength: 12000 }
        persisted: { type: boolean }
        mock: { type: boolean }
        actuatorControl: { type: boolean }
    Contract:
      type: object
      required: [id, robotId, jointCount, observationSize, actionSize, controlHz, physicsTimestepSeconds, decimation, observationLayout]
      properties:
        id: { type: string }
        robotId: { type: string, enum: [microduck, rdk-duck, originbot] }
        jointCount: { type: integer, minimum: 1, maximum: 256 }
        observationSize: { type: integer, minimum: 1, maximum: 4096 }
        actionSize: { type: integer, minimum: 1, maximum: 4096 }
        controlHz: { type: number, exclusiveMinimum: 0, maximum: 1000 }
        physicsTimestepSeconds: { type: number, exclusiveMinimum: 0, maximum: 1 }
        decimation: { type: integer, minimum: 1, maximum: 256 }
        observationLayout:
          type: array
          maxItems: 16
          items:
            type: object
            required: [name, size]
            properties:
              name: { type: string }
              size: { type: integer, minimum: 1, maximum: 4096 }
    Artifact:
      type: object
      required: [id, role, name, kind, format, ref]
      properties:
        id: { type: string }
        role: { type: string, enum: [policy, compiled-policy, calibration] }
        name: { type: string }
        kind: { type: string, enum: [source, compiled] }
        format: { type: string, enum: [pytorch, onnx, bin, hbm, gguf, unknown] }
        runtime: { type: string, enum: [cpu-onnx, bpu] }
        workload: { type: string, enum: [locomotion, perception, navigation, speech, multimodal] }
        threads: { type: integer, minimum: 1, maximum: 128 }
        targetPlatforms: { type: array, items: { type: string } }
        ref: { type: string, pattern: "^artifact://" }
    Manifest:
      type: object
      required: [schemaVersion, modelId, displayName, version, robot, contract, simulator, artifacts]
      properties:
        schemaVersion: { type: integer, const: 1 }
        modelId: { type: string }
        displayName: { type: string }
        version: { type: string }
        robot: { type: object, required: [id, variant], properties: { id: { type: string, enum: [microduck, rdk-duck, originbot] }, variant: { type: string } } }
        contract: { $ref: "#/components/schemas/Contract" }
        simulator: { type: object, required: [backends, policyArtifactId], additionalProperties: true }
        artifacts: { type: array, minItems: 1, items: { $ref: "#/components/schemas/Artifact" } }
    ManifestEnvelope:
      oneOf:
        - $ref: "#/components/schemas/Manifest"
        - type: object
          required: [manifest]
          properties:
            manifest: { $ref: "#/components/schemas/Manifest" }
            platforms: { type: array, items: { type: string } }
    Training:
      type: object
      description: The profile supplies safe defaults. ACT and Diffusion Policy require an owner/project/contract-matched demonstration Run, or explicit syntheticSmoke with the smoke profile.
      properties:
        profile: { type: string, enum: [smoke, low-vram, standard, high-vram] }
        numEnvs: { type: integer, minimum: 1, maximum: 16384 }
        maxIterations: { type: integer, minimum: 1, maximum: 2000000 }
        video: { type: boolean }
        runName: { type: string, maxLength: 80 }
        algorithm: { type: string, enum: [ppo, sac] }
        engine: { type: string, enum: [starter-ppo, mjx-ppo, visual-ppo, dm-control-ppo, mjlab-rsl-rl, microduck-rl, microduck-recurrent, microduck-football, act, diffusion-policy, smolvla, isaac-lab] }
        demonstrationRunId: { type: string, maxLength: 200, description: Recorded telemetry Run with at least eight complete episodes of four or more steps. Requires matching owner, project, and vector contract; Mock and demo-fixture data are rejected. }
        demonstrationSha256: { type: string, pattern: "^[a-f0-9]{64}$", readOnly: true, description: Server-pinned digest of the accepted demonstration JSONL. }
        syntheticSmoke: { type: boolean, description: Explicit synthetic imitation smoke only; mutually exclusive with demonstrationRunId and requires profile=smoke. }
    RunRequest:
      type: object
      required: [modelId, backend]
      properties:
        modelId: { type: string }
        backend: { type: string, enum: [browser, local, robogo, contract] }
        taskId: { type: string }
        projectId: { type: string }
        experimentId: { type: string }
        label: { type: string, maxLength: 120 }
        computeResourceId: { type: string }
        datasetIds: { type: array, maxItems: 500, items: { type: string } }
        training: { $ref: "#/components/schemas/Training" }
        resumeFrom: { type: object, required: [checkpointId, artifactRef], properties: { checkpointId: { type: string }, artifactRef: { type: string }, iteration: { type: integer, minimum: 0 } } }
        idempotencyKey: { type: string, maxLength: 128 }
    TaskEvaluationEnvelope:
      type: object
      properties:
        successRate: { type: number, minimum: 0, maximum: 1 }
        collisionRate: { type: number, minimum: 0, maximum: 1 }
        successRateCiLow: { type: number, minimum: 0, maximum: 1 }
        successRateCiHigh: { type: number, minimum: 0, maximum: 1 }
        collisionRateCiLow: { type: number, minimum: 0, maximum: 1 }
        collisionRateCiHigh: { type: number, minimum: 0, maximum: 1 }
        episodes: { type: integer, minimum: 1, maximum: 100000 }
        meanReward: { type: number }
    TaskEvaluation:
      type: object
      required: [taskId]
      description: Sanitized Task-Pack eval-report evidence. The server recomputes release eligibility from these measurements and never trusts the runner's boolean alone.
      properties:
        schemaVersion: { type: integer, minimum: 1 }
        taskId: { type: string }
        adapterId: { type: string }
        observationAdapterId: { type: string }
        trained:
          type: object
          properties:
            envelopes: { type: object, additionalProperties: { $ref: "#/components/schemas/TaskEvaluationEnvelope" } }
            meanReward: { type: number }
            episodesPerEnvelope: { type: integer, minimum: 1 }
            confidenceLevel: { type: number, minimum: 0.5, maximum: 0.9999 }
        baseline:
          type: object
          properties:
            envelopes: { type: object, additionalProperties: { $ref: "#/components/schemas/TaskEvaluationEnvelope" } }
            meanReward: { type: number }
            episodesPerEnvelope: { type: integer, minimum: 1 }
            confidenceLevel: { type: number, minimum: 0.5, maximum: 0.9999 }
        qualityGate:
          type: object
          properties:
            passed: { type: boolean, description: Informational only; the server recomputes the verdict. }
            errors: { type: array, maxItems: 32, items: { type: string, maxLength: 240 } }
            criteria:
              type: object
              properties:
                minSuccessRate: { type: number, minimum: 0, maximum: 1 }
                maxCollisionRate: { type: number, minimum: 0, maximum: 1 }
                gateOn: { type: string, enum: [point, ciLowerBound] }
        controlLatencyMs: { type: number, minimum: 0, maximum: 60000 }
        seed: { type: integer, minimum: 0 }
        reportSha256: { type: string, pattern: "^[a-f0-9]{64}$" }
    Run:
      type: object
      required: [id, modelId, backend, status, summary, createdAt]
      properties:
        id: { type: string }
        modelId: { type: string }
        productId: { type: string, enum: [microduck, rdk-duck] }
        contractId: { type: string }
        taskId: { type: string }
        projectId: { type: string }
        datasetIds: { type: array, items: { type: string } }
        artifactIds: { type: array, items: { type: string } }
        evaluationId: { type: string }
        backend: { type: string, enum: [browser, local, robogo, contract] }
        status: { type: string, enum: [ready, queued, running, completed, blocked, failed] }
        summary: { type: string }
        externalRunId: { type: string }
        mock: { type: boolean }
        training: { $ref: "#/components/schemas/Training" }
        checkpoint: { type: object, additionalProperties: true }
        artifact: { type: object, additionalProperties: true }
        metrics: { type: object, additionalProperties: true }
        taskEvaluation: { $ref: "#/components/schemas/TaskEvaluation" }
        createdAt: { type: string, format: date-time }
        finishedAt: { type: string, format: date-time }
    Model:
      type: object
      required: [id, manifest, createdAt, updatedAt]
      properties:
        id: { type: string }
        productId: { type: string }
        contractId: { type: string }
        builtin: { type: boolean }
        manifest: { $ref: "#/components/schemas/Manifest" }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
    Compatibility:
      type: object
      required: [platformId, status, deployable, reason]
      properties:
        platformId: { type: string }
        status: { type: string }
        artifactId: { type: string }
        deployable: { type: boolean }
        reason: { type: string }
        result: { type: object, additionalProperties: true }
    DeploymentRequest:
      type: object
      description: runId and Idempotency-Key are mandatory when mode is canary or live; preflight remains read-only and does not require training evidence.
      required: [modelId, deviceId]
      properties:
        modelId: { type: string }
        deviceId: { type: string }
        mode: { type: string, enum: [preflight, canary, live], default: preflight }
        runId: { type: string, description: Completed non-mock local/RoboGo run whose artifact and metrics authorize canary/live planning. }
        artifactId: { type: string, description: Immutable published artifact authorized by the release gate. }
        evaluationId: { type: string, description: Passed evaluation evidence associated with the run. }
        idempotencyKey: { type: string, maxLength: 128 }
    Deployment:
      type: object
      required: [id, modelId, deviceId, targetPlatform, mode, status, summary, steps, createdAt, updatedAt]
      properties:
        id: { type: string }
        modelId: { type: string }
        runId: { type: string }
        artifactId: { type: string }
        evaluationId: { type: string }
        deviceId: { type: string }
        targetPlatform: { type: string }
        mode: { type: string }
        status: { type: string, enum: [planned, running, ready, blocked, failed, completed, cancelled] }
        summary: { type: string }
        compatibility: { $ref: "#/components/schemas/Compatibility" }
        steps: { type: array, items: { type: object, additionalProperties: true } }
        history:
          type: array
          items:
            type: object
            required: [id, type, status, summary, createdAt]
            properties:
              id: { type: string }
              type: { type: string, enum: [created, status_changed, preflight, cancelled, version_switched, approval_approved, approval_rejected, updated] }
              status: { type: string }
              summary: { type: string }
              createdAt: { type: string, format: date-time }
        approval:
          type: object
          required: [status, requestedAt]
          properties:
            status: { type: string, enum: [pending, approved, rejected] }
            requestedAt: { type: string, format: date-time }
            requestedBy: { type: string }
            decidedAt: { type: string, format: date-time }
            decidedBy: { type: string }
            note: { type: string, maxLength: 500 }
        verification:
          type: object
          required: [passed, checkedAt]
          properties:
            passed: { type: boolean }
            checkedAt: { type: string, format: date-time }
            checks: { type: object, additionalProperties: { type: [string, number, "null"] } }
            mock: { type: boolean }
        releaseGate:
          type: object
          required: [passed, checkedAt, errors, checks]
          properties:
            passed: { type: boolean }
            checkedAt: { type: string, format: date-time }
            runId: { type: string }
            taskId: { type: string }
            errors: { type: array, items: { type: string } }
            checks: { type: object, additionalProperties: { type: [boolean, string, number, "null"] } }
        versionSwitchFrom: { type: string }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
    TelemetrySample:
      type: object
      required: [t]
      properties:
        t: { type: number, minimum: 0, maximum: 86400 }
        observation: { type: array, maxItems: 4096, items: { type: number } }
        action: { type: array, maxItems: 4096, items: { type: number } }
        reward: { type: number }
        done: { type: boolean }
        fall: { type: boolean }
        cmd_vel:
          type: object
          required: [linear, angular]
          properties:
            linear: { type: number, minimum: -0.3, maximum: 0.3 }
            angular: { type: number, minimum: -1, maximum: 1 }
        actionOutput: { type: string, enum: [physical-twist, normalized-twist] }
        actionScale:
          type: object
          required: [linear, angular]
          properties:
            linear: { type: number, exclusiveMinimum: 0, maximum: 0.3 }
            angular: { type: number, exclusiveMinimum: 0, maximum: 1 }
            units: { type: string, enum: ['m/s,rad/s'] }
        controlHz: { type: integer, minimum: 1, maximum: 50 }
        controlPeriodSeconds: { type: number, minimum: 0.02, maximum: 1 }
        event:
          description: >-
            Board policy-session lifecycle marker. A sample carrying `event`
            must not carry observation/action/control fields; markers are
            excluded from replay statistics and aggregated by
            /runs/{runId}/board-sessions instead.
          type: object
          required: [kind, sessionId]
          properties:
            kind: { type: string, enum: [session-started, session-stopped] }
            sessionId: { type: string, maxLength: 64 }
            startedAt: { type: string, format: date-time }
            stoppedAt: { type: string, format: date-time }
            stopReason: { type: string, maxLength: 120 }
            inferenceCount: { type: integer, minimum: 0 }
            lastInferenceAt: { type: string, format: date-time }
            durationSec: { type: number, minimum: 0, maximum: 86400 }
            inferMs: { type: number, minimum: 0, maximum: 10000 }
            published: { type: integer, minimum: 0 }
            mock: { type: boolean }
            adapterId: { type: string, maxLength: 80 }
            controlHz: { type: integer, minimum: 1, maximum: 50 }
            model:
              type: object
              properties:
                sha256: { type: string, pattern: "^[a-f0-9]{64}$" }
                provider: { type: string, maxLength: 64 }
                inputDim: { type: integer, minimum: 1 }
                outputDim: { type: integer, minimum: 1 }
                bytes: { type: integer, minimum: 0 }
    CorrelationStatistic:
      oneOf:
        - type: object
          required: [value]
          properties:
            value: { type: number }
        - type: object
          required: [value, reason]
          properties:
            value: { const: null }
            reason: { type: string }
    BoardSessionSummary:
      type: object
      required: [sessionId, attested, chunks, events]
      properties:
        sessionId: { type: string }
        startedAt: { type: string, format: date-time }
        stoppedAt: { type: string, format: date-time }
        stopReason: { type: string }
        lastInferenceAt: { type: string, format: date-time }
        inferenceCount: { type: integer, minimum: 0 }
        published: { type: integer, minimum: 0 }
        inferMs: { type: number, minimum: 0 }
        durationSec: { type: number, minimum: 0 }
        mock: { type: boolean }
        adapterId: { type: string }
        controlHz: { type: integer, minimum: 1, maximum: 50 }
        deviceId: { type: string }
        attested: { type: boolean }
        chunks: { type: integer, minimum: 1 }
        events: { type: integer, minimum: 1 }
        model:
          type: object
          properties:
            sha256: { type: string, pattern: "^[a-f0-9]{64}$" }
            provider: { type: string }
            inputDim: { type: integer, minimum: 1 }
            outputDim: { type: integer, minimum: 1 }
            bytes: { type: integer, minimum: 0 }
    TelemetryRequestWithoutRunId:
      type: object
      properties:
        source: { type: string, enum: [board-agent, browser, import, demo-fixture], default: import, description: "demo-fixture 仅表示内置合成演示数据；不会满足真实评测或发布闸门" }
        modelId: { type: string }
        deviceId: { type: string }
        contractId: { type: string }
        sequence: { type: integer, minimum: 0 }
        droppedCount: { type: integer, minimum: 0 }
        samples: { type: array, minItems: 1, maxItems: 5000, items: { $ref: "#/components/schemas/TelemetrySample" } }
        jsonl: { type: string, maxLength: 2000000 }
        idempotencyKey: { type: string, maxLength: 128 }
    TelemetryRequest:
      allOf:
        - $ref: "#/components/schemas/TelemetryRequestWithoutRunId"
        - type: object
          required: [runId]
          properties: { runId: { type: string } }
    WorkspaceSummaryResponse:
      type: object
      required: [ok, schemaVersion, generatedAt, counts, latest]
      properties:
        ok: { const: true }
        schemaVersion: { type: integer, const: 1 }
        generatedAt: { type: string, format: date-time }
        counts:
          type: object
          required: [models, runs, activeRuns, deployments, activeDeployments, devices, connectedDevices, detectedDevices, projects, datasets]
          properties:
            models: { type: integer, minimum: 0 }
            runs: { type: integer, minimum: 0 }
            activeRuns: { type: integer, minimum: 0 }
            deployments: { type: integer, minimum: 0 }
            activeDeployments: { type: integer, minimum: 0 }
            devices: { type: integer, minimum: 0 }
            connectedDevices: { type: integer, minimum: 0 }
            detectedDevices: { type: integer, minimum: 0 }
            projects: { type: integer, minimum: 0 }
            datasets: { type: integer, minimum: 0 }
        latest:
          type: object
          required: [run, deployment]
          properties:
            run:
              oneOf:
                - $ref: "#/components/schemas/WorkspaceRunSummary"
                - type: "null"
            deployment:
              oneOf:
                - $ref: "#/components/schemas/WorkspaceDeploymentSummary"
                - type: "null"
    WorkspaceRunSummary:
      type: object
      required: [id, modelId, backend, status, summary, createdAt]
      properties:
        id: { type: string }
        modelId: { type: string }
        taskId: { type: string }
        backend: { type: string, enum: [browser, local, robogo, contract] }
        status: { type: string }
        summary: { type: string }
        createdAt: { type: string, format: date-time }
        finishedAt: { type: string, format: date-time }
    WorkspaceDeploymentSummary:
      type: object
      required: [id, modelId, deviceId, targetPlatform, mode, status, summary, createdAt, updatedAt]
      properties:
        id: { type: string }
        modelId: { type: string }
        deviceId: { type: string }
        targetPlatform: { type: string }
        mode: { type: string, enum: [preflight, canary, live] }
        status: { type: string }
        summary: { type: string }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
    OverviewResponse:
      type: object
      required: [ok, schemaVersion, productProfiles, selectedProductId, models, runs, deployments, devices, integrations]
      properties:
        ok: { const: true }
        schemaVersion: { type: integer, const: 1 }
        identity: { type: [object, "null"], additionalProperties: true }
        productProfiles: { type: array, items: { type: object, additionalProperties: true } }
        selectedProductId: { type: string, enum: [microduck, rdk-duck] }
        selectedContract:
          oneOf:
            - $ref: "#/components/schemas/Contract"
            - type: "null"
        availableContracts: { type: array, items: { type: object, additionalProperties: true } }
        contracts: { type: object, additionalProperties: true }
        contract: { $ref: "#/components/schemas/Contract" }
        models: { type: array, items: { $ref: "#/components/schemas/Model" } }
        runs: { type: array, items: { $ref: "#/components/schemas/Run" } }
        deployments: { type: array, items: { $ref: "#/components/schemas/Deployment" } }
        devices: { type: array, items: { $ref: "#/components/schemas/DeviceSummary" } }
        integrations: { $ref: "#/components/schemas/Integrations" }
        artifacts:
          type: array
          description: First-class immutable registry artifacts (newest 100) powering the promotion-flow view.
          items: { $ref: "#/components/schemas/ArtifactRecord" }
        evaluations:
          type: array
          description: First-class evaluation evidence records (newest 100) linked to runs and artifacts.
          items: { $ref: "#/components/schemas/EvaluationRecord" }
    DeviceSummary:
      type: object
      required: [id, name, status]
      properties:
        id: { type: string }
        name: { type: string }
        status: { type: string }
        boardPlatform: { type: [string, "null"] }
        boardModel: { type: [string, "null"] }
        connectionMode: { type: string }
        sshReachability: { type: string }
    LocalWorkerIntegration:
      type: object
      required: [available, reachable, healthy, message]
      properties:
        available: { type: boolean, description: Whether the endpoint is configured. }
        reachable: { type: boolean }
        healthy: { type: boolean }
        configured: { type: boolean }
        mock: { type: boolean }
        maxConcurrentJobs: { type: integer, minimum: 0 }
        activeJobs: { type: integer, minimum: 0 }
        queuedJobs: { type: integer, minimum: 0 }
        responseMs: { type: integer, minimum: 0 }
        reason: { type: string }
        message: { type: string }
    Integrations:
      type: object
      required: [simulator, robogo, storage]
      properties:
        simulator:
          type: object
          required: [browser, boardAgent, robogo, local]
          properties:
            browser: { type: object, additionalProperties: true }
            boardAgent: { type: object, additionalProperties: true }
            robogo: { type: object, additionalProperties: true }
            local: { $ref: "#/components/schemas/LocalWorkerIntegration" }
        robogo: { $ref: "#/components/schemas/RobogoIntegration" }
        storage: { $ref: "#/components/schemas/StorageIntegration" }
    RobogoIntegration:
      type: object
      required: [state, clusterQueried, devMachineQueried, message]
      properties:
        state: { type: string, enum: [ready, login_required, unavailable] }
        clusterQueried: { type: boolean }
        devMachineQueried: { type: boolean }
        availableBoardCount: { type: integer, minimum: 0 }
        developmentMachineCount: { type: integer, minimum: 0 }
        message: { type: string }
    StorageIntegration:
      type: object
      required: [mode, writable, message]
      properties:
        mode: { type: string, enum: [local-server, external-required] }
        writable: { type: boolean }
        message: { type: string }
    ValidationResponse:
      type: object
      required: [ok, validation]
      properties:
        ok: { const: true }
        validation: { type: object, additionalProperties: true }
        compatibility: { type: array, items: { $ref: "#/components/schemas/Compatibility" } }
    ModelResponse:
      type: object
      required: [ok, model]
      properties:
        ok: { const: true }
        model: { $ref: "#/components/schemas/Model" }
        compatibility: { type: array, items: { $ref: "#/components/schemas/Compatibility" } }
    RunResponse:
      type: object
      required: [ok, run]
      properties: { ok: { const: true }, run: { $ref: "#/components/schemas/Run" }, idempotentReplay: { type: boolean }, reconciled: { type: boolean } }
    TelemetryResponse:
      type: object
      required: [ok]
      properties: { ok: { const: true }, telemetry: { type: object, additionalProperties: true }, duplicate: { type: boolean }, acceptedSamples: { type: integer } }
    TelemetryListResponse:
      type: object
      required: [ok, runId, telemetry, count]
      properties: { ok: { const: true }, runId: { type: string }, telemetry: { type: array, items: { type: object, additionalProperties: true } }, count: { type: integer } }
    ReplayResponse:
      type: object
      required: [ok, runId, replay, evaluation]
      properties:
        ok: { const: true }
        runId: { type: string }
        replay: { type: object, additionalProperties: true }
        evaluation: { type: object, additionalProperties: true }
        # The replay endpoint returns the accepted raw samples for deterministic
        # frame seeking; keep this in the contract rather than relying on
        # additionalProperties.
        frames: { type: array, items: { $ref: "#/components/schemas/TelemetrySample" } }
    EvaluationResponse:
      type: object
      required: [ok, evaluation]
      properties:
        ok: { const: true }
        run: { $ref: "#/components/schemas/Run" }
        evaluation: { type: object, additionalProperties: true }
        evaluationRecord: { $ref: "#/components/schemas/EvaluationRecord" }
    DeploymentResponse:
      type: object
      required: [ok, deployment]
      properties: { ok: { const: true }, deployment: { $ref: "#/components/schemas/Deployment" }, idempotentReplay: { type: boolean } }
    PreflightResponse:
      type: object
      required: [ok, deployment, preflight]
      properties: { ok: { const: true }, deployment: { $ref: "#/components/schemas/Deployment" }, preflight: { type: object, additionalProperties: true } }