remora/docs/api/openapi.yaml

openapi: 3.2.0
info:
  title: Remora API
  version: 1.0.0
  description: Mutable implementation contract for public job management and service-authenticated worker operations.
tags: []
paths:
  /internal/v1/attempts/{attempt_id}/activate:
    post:
      operationId: activateAttempt
      parameters:
        - $ref: "#/components/parameters/Parameters.AttemptId"
      responses:
        "200":
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActivationResponse"
        "409":
          description: The request conflicts with the current state of the server.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
        default:
          description: Structured error with user-safe detail only.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AttemptActivateRequest"
      security:
        - serviceAuth: []
  /internal/v1/attempts/{attempt_id}/checkpoint:
    post:
      operationId: persistAttemptCheckpoint
      parameters:
        - $ref: "#/components/parameters/Parameters.AttemptId"
      responses:
        "204":
          description: There is no content to send for this request, but the headers may be useful.
        "409":
          description: The request conflicts with the current state of the server.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
        default:
          description: Structured error with user-safe detail only.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AttemptCheckpointRequest"
      security:
        - serviceAuth: []
  /internal/v1/attempts/{attempt_id}/outcome:
    post:
      operationId: reportAttemptOutcome
      parameters:
        - $ref: "#/components/parameters/Parameters.AttemptId"
      responses:
        "200":
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobPhaseProjection"
        "409":
          description: The request conflicts with the current state of the server.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
        default:
          description: Structured error with user-safe detail only.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AttemptOutcomeRequest"
      security:
        - serviceAuth: []
  /internal/v1/attempts/{attempt_id}/progress:
    post:
      operationId: reportAttemptProgress
      parameters:
        - $ref: "#/components/parameters/Parameters.AttemptId"
      responses:
        "204":
          description: There is no content to send for this request, but the headers may be useful.
        "409":
          description: The request conflicts with the current state of the server.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
        default:
          description: Structured error with user-safe detail only.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AttemptProgressRequest"
      security:
        - serviceAuth: []
  /internal/v1/attempts/{attempt_id}/renew:
    post:
      operationId: renewAttempt
      parameters:
        - $ref: "#/components/parameters/Parameters.AttemptId"
      responses:
        "200":
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LeaseProjection"
        "409":
          description: The request conflicts with the current state of the server.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
        default:
          description: Structured error with user-safe detail only.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AttemptRenewRequest"
      security:
        - serviceAuth: []
  /internal/v1/attempts/{attempt_id}/resolved-source:
    post:
      operationId: pinAttemptResolvedSource
      parameters:
        - $ref: "#/components/parameters/Parameters.AttemptId"
      responses:
        "204":
          description: There is no content to send for this request, but the headers may be useful.
        "409":
          description: The request conflicts with the current state of the server.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
        default:
          description: Structured error with user-safe detail only.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AttemptResolvedSourceRequest"
      security:
        - serviceAuth: []
  /internal/v1/attempts/{attempt_id}/staging/multipart:
    post:
      operationId: registerAttemptStagingMultipart
      parameters:
        - $ref: "#/components/parameters/Parameters.AttemptId"
      responses:
        "204":
          description: There is no content to send for this request, but the headers may be useful.
        "409":
          description: The request conflicts with the current state of the server.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
        default:
          description: Structured error with user-safe detail only.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AttemptStagingMultipartRequest"
      security:
        - serviceAuth: []
  /internal/v1/attempts/{attempt_id}/staging/object:
    post:
      operationId: registerAttemptStagingObject
      parameters:
        - $ref: "#/components/parameters/Parameters.AttemptId"
      responses:
        "204":
          description: There is no content to send for this request, but the headers may be useful.
        "409":
          description: The request conflicts with the current state of the server.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
        default:
          description: Structured error with user-safe detail only.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AttemptStagingObjectRequest"
      security:
        - serviceAuth: []
  /internal/v1/attempts/{attempt_id}/staging/write-intent:
    post:
      operationId: registerAttemptStagingWriteIntent
      parameters:
        - $ref: "#/components/parameters/Parameters.AttemptId"
      responses:
        "204":
          description: There is no content to send for this request, but the headers may be useful.
        "409":
          description: The request conflicts with the current state of the server.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
        default:
          description: Structured error with user-safe detail only.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AttemptStagingWriteIntentRequest"
      security:
        - serviceAuth: []
  /internal/v1/attempts/{attempt_id}/stop:
    post:
      operationId: stopAttempt
      parameters:
        - $ref: "#/components/parameters/Parameters.AttemptId"
      responses:
        "204":
          description: There is no content to send for this request, but the headers may be useful.
        "409":
          description: The request conflicts with the current state of the server.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
        default:
          description: Structured error with user-safe detail only.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AttemptStopRequest"
      security:
        - serviceAuth: []
  /internal/v1/jobs/{job_id}/claim:
    post:
      operationId: claimJob
      parameters:
        - $ref: "#/components/parameters/Parameters.JobId"
      responses:
        "200":
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClaimResponse"
        "409":
          description: The request conflicts with the current state of the server.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
        default:
          description: Structured error with user-safe detail only.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ClaimRequest"
      security:
        - serviceAuth: []
  /v1/deletions/{operation_id}:
    get:
      operationId: getDeletionOperation
      parameters:
        - name: operation_id
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/OpaqueId"
      responses:
        "200":
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeletionOperation"
        "404":
          description: The server cannot find the requested resource.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
        default:
          description: Structured error with user-safe detail only.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /v1/event-tickets:
    post:
      operationId: createEventTicket
      description: Creates an independent short-lived, single-use browser WebSocket credential bound to the authenticated principal and request origin. This ephemeral authentication exchange does not enter the public domain mutation idempotency ledger.
      parameters: []
      responses:
        "201":
          description: The request has succeeded and a new resource has been created as a result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventTicket"
        default:
          description: Structured error with user-safe detail only.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /v1/events:
    get:
      operationId: connectEvents
      parameters:
        - name: ticket
          in: query
          required: false
          description: Short-lived single-use browser credential created by createEventTicket. Native clients may use OIDC bearer authentication instead.
          schema:
            $ref: "#/components/schemas/OpaqueId"
        - name: cursor
          in: query
          required: false
          description: Opaque authorization-bound replay cursor from an HTTP snapshot or prior frame.
          schema:
            type: string
            minLength: 16
            maxLength: 2048
      responses:
        "101":
          description: Informational
        default:
          description: Structured error with user-safe detail only.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
      security:
        - oidc: []
        - eventTicket: []
  /v1/jobs:
    get:
      operationId: listJobs
      parameters:
        - $ref: "#/components/parameters/Parameters.Cursor"
        - $ref: "#/components/parameters/Parameters.Limit"
        - name: include_deleted
          in: query
          required: false
          schema:
            type: boolean
      responses:
        "200":
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobPage"
        default:
          description: Structured error with user-safe detail only.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
    post:
      operationId: submitJob
      parameters:
        - $ref: "#/components/parameters/Parameters.IdempotencyKey"
      responses:
        "202":
          description: The request has been accepted for processing, but processing has not yet completed.
          headers:
            Idempotency-Expires-At:
              required: false
              description: Earliest time at which the server may forget this key.
              schema:
                type: string
                format: http-date
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Job"
        "409":
          description: The request conflicts with the current state of the server.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
        default:
          description: Structured error with user-safe detail only.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/JobSubmission"
  /v1/jobs/{job_id}:
    get:
      operationId: getJob
      parameters:
        - $ref: "#/components/parameters/Parameters.JobId"
      responses:
        "200":
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobResource"
        "404":
          description: The server cannot find the requested resource.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
        default:
          description: Structured error with user-safe detail only.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /v1/jobs/{job_id}/attempts:
    get:
      operationId: listJobAttempts
      parameters:
        - $ref: "#/components/parameters/Parameters.JobId"
        - $ref: "#/components/parameters/Parameters.Cursor"
        - $ref: "#/components/parameters/Parameters.Limit"
      responses:
        "200":
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AttemptPage"
        "404":
          description: The server cannot find the requested resource.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
        default:
          description: Structured error with user-safe detail only.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /v1/jobs/{job_id}/cancel:
    post:
      operationId: cancelJob
      parameters:
        - $ref: "#/components/parameters/Parameters.JobId"
        - $ref: "#/components/parameters/Parameters.IdempotencyKey"
      responses:
        "202":
          description: The request has been accepted for processing, but processing has not yet completed.
          headers:
            Idempotency-Expires-At:
              required: false
              description: Earliest time at which the server may forget this key.
              schema:
                type: string
                format: http-date
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Job"
        default:
          description: Structured error with user-safe detail only.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /v1/jobs/{job_id}/hard-delete:
    post:
      operationId: hardDeleteJob
      parameters:
        - $ref: "#/components/parameters/Parameters.JobId"
        - $ref: "#/components/parameters/Parameters.IdempotencyKey"
      responses:
        "202":
          description: The request has been accepted for processing, but processing has not yet completed.
          headers:
            Idempotency-Expires-At:
              required: false
              description: Earliest time at which the server may forget this key.
              schema:
                type: string
                format: http-date
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeletionOperation"
        default:
          description: Structured error with user-safe detail only.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /v1/jobs/{job_id}/restore:
    post:
      operationId: restoreJob
      parameters:
        - $ref: "#/components/parameters/Parameters.JobId"
        - $ref: "#/components/parameters/Parameters.IdempotencyKey"
      responses:
        "200":
          description: The request has succeeded.
          headers:
            Idempotency-Expires-At:
              required: false
              description: Earliest time at which the server may forget this key.
              schema:
                type: string
                format: http-date
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Job"
        default:
          description: Structured error with user-safe detail only.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /v1/jobs/{job_id}/result:
    get:
      operationId: getJobResult
      parameters:
        - $ref: "#/components/parameters/Parameters.JobId"
      responses:
        "200":
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResultDescriptor"
        "404":
          description: The server cannot find the requested resource.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "409":
          description: The request conflicts with the current state of the server.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
        default:
          description: Structured error with user-safe detail only.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /v1/jobs/{job_id}/result/members:
    get:
      operationId: listJobResultMembers
      description: Enumerates members only from the visible committed result.
      parameters:
        - $ref: "#/components/parameters/Parameters.JobId"
        - $ref: "#/components/parameters/Parameters.Cursor"
        - $ref: "#/components/parameters/Parameters.Limit"
      responses:
        "200":
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResultMemberPage"
        "404":
          description: The server cannot find the requested resource.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "409":
          description: The request conflicts with the current state of the server.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
        default:
          description: Structured error with user-safe detail only.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /v1/jobs/{job_id}/result/members/{member_id}/content:
    get:
      operationId: accessJobResultMember
      description: Revalidates current authorization and returns a non-cacheable time-limited URL for the exact committed member identity.
      parameters:
        - $ref: "#/components/parameters/Parameters.JobId"
        - name: member_id
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/OpaqueId"
      responses:
        "200":
          description: The request has succeeded.
          headers:
            Cache-Control:
              required: true
              description: Prevents caching of the credential-bearing response.
              schema:
                type: string
                enum:
                  - no-store
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResultMemberAccess"
        "404":
          description: The server cannot find the requested resource.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "409":
          description: The request conflicts with the current state of the server.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
        default:
          description: Structured error with user-safe detail only.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /v1/jobs/{job_id}/revoke:
    post:
      operationId: revokeJobExecutionGrant
      description: Administrator-only revocation of an accepted execution grant.
      parameters:
        - $ref: "#/components/parameters/Parameters.JobId"
        - $ref: "#/components/parameters/Parameters.IdempotencyKey"
      responses:
        "202":
          description: The request has been accepted for processing, but processing has not yet completed.
          headers:
            Idempotency-Expires-At:
              required: false
              description: Earliest time at which the server may forget this key.
              schema:
                type: string
                format: http-date
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Job"
        default:
          description: Structured error with user-safe detail only.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /v1/jobs/{job_id}/soft-delete:
    post:
      operationId: softDeleteJob
      parameters:
        - $ref: "#/components/parameters/Parameters.JobId"
        - $ref: "#/components/parameters/Parameters.IdempotencyKey"
      responses:
        "200":
          description: The request has succeeded.
          headers:
            Idempotency-Expires-At:
              required: false
              description: Earliest time at which the server may forget this key.
              schema:
                type: string
                format: http-date
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Job"
        default:
          description: Structured error with user-safe detail only.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /v1/source-credentials:
    get:
      operationId: listSourceCredentials
      parameters:
        - $ref: "#/components/parameters/Parameters.Cursor"
        - $ref: "#/components/parameters/Parameters.Limit"
      responses:
        "200":
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SourceCredentialPage"
        default:
          description: Structured error with user-safe detail only.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
    post:
      operationId: createSourceCredential
      parameters:
        - $ref: "#/components/parameters/Parameters.IdempotencyKey"
      responses:
        "201":
          description: The request has succeeded and a new resource has been created as a result.
          headers:
            Idempotency-Expires-At:
              required: false
              description: Earliest time at which the server may forget this key.
              schema:
                type: string
                format: http-date
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SourceCredential"
        "409":
          description: The request conflicts with the current state of the server.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
        default:
          description: Structured error with user-safe detail only.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SourceCredentialCreate"
  /v1/source-credentials/{credential_id}:
    get:
      operationId: getSourceCredential
      parameters:
        - $ref: "#/components/parameters/Parameters.CredentialIdParameter"
      responses:
        "200":
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SourceCredential"
        "404":
          description: The server cannot find the requested resource.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
        default:
          description: Structured error with user-safe detail only.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /v1/source-credentials/{credential_id}/revoke:
    post:
      operationId: revokeSourceCredential
      parameters:
        - $ref: "#/components/parameters/Parameters.CredentialIdParameter"
        - $ref: "#/components/parameters/Parameters.IdempotencyKey"
      responses:
        "200":
          description: The request has succeeded.
          headers:
            Idempotency-Expires-At:
              required: false
              description: Earliest time at which the server may forget this key.
              schema:
                type: string
                format: http-date
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SourceCredential"
        "404":
          description: The server cannot find the requested resource.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "409":
          description: The request conflicts with the current state of the server.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
        default:
          description: Structured error with user-safe detail only.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /v1/source-credentials/{credential_id}/versions:
    post:
      operationId: rotateSourceCredential
      parameters:
        - $ref: "#/components/parameters/Parameters.CredentialIdParameter"
        - $ref: "#/components/parameters/Parameters.IdempotencyKey"
      responses:
        "201":
          description: The request has succeeded and a new resource has been created as a result.
          headers:
            Idempotency-Expires-At:
              required: false
              description: Earliest time at which the server may forget this key.
              schema:
                type: string
                format: http-date
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SourceCredential"
        "404":
          description: The server cannot find the requested resource.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "409":
          description: The request conflicts with the current state of the server.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
        default:
          description: Structured error with user-safe detail only.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ApiError"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SourceCredentialRotate"
components:
  parameters:
    Parameters.AttemptId:
      name: attempt_id
      in: path
      required: true
      schema:
        $ref: "#/components/schemas/OpaqueId"
    Parameters.CredentialIdParameter:
      name: credential_id
      in: path
      required: true
      schema:
        $ref: "#/components/schemas/CredentialId"
    Parameters.Cursor:
      name: cursor
      in: query
      required: false
      schema:
        type: string
        minLength: 16
        maxLength: 2048
    Parameters.IdempotencyKey:
      name: idempotency-key
      in: header
      required: true
      description: Subject- and operation-scoped key retained for at least 24 hours.
      schema:
        type: string
        pattern: ^[A-Za-z0-9._~-]{16,128}$
    Parameters.JobId:
      name: job_id
      in: path
      required: true
      schema:
        $ref: "#/components/schemas/OpaqueId"
    Parameters.Limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 50
  schemas:
    ActivationResponse:
      type: object
      required:
        - authority
        - execution
        - lease
      properties:
        authority:
          $ref: "#/components/schemas/AttemptAuthority"
        execution:
          $ref: "#/components/schemas/ExecutionEnvelope"
        lease:
          $ref: "#/components/schemas/LeaseProjection"
    ApiError:
      type: object
      required:
        - code
        - message
        - request_id
      properties:
        code:
          type: string
          enum:
            - invalid_request
            - unauthenticated
            - forbidden
            - not_found
            - idempotency_conflict
            - precondition_failed
            - cursor_invalid
            - cursor_expired
            - rate_limited
            - unavailable
            - internal
        message:
          type: string
          maxLength: 500
        request_id:
          $ref: "#/components/schemas/OpaqueId"
        fields:
          type: array
          items:
            type: object
            properties:
              pointer:
                type: string
                maxLength: 500
              code:
                type: string
                maxLength: 100
            required:
              - pointer
              - code
          maxItems: 100
    AttemptActivateRequest:
      type: object
      required:
        - operation_id
        - fence
        - worker_incarnation
      properties:
        operation_id:
          $ref: "#/components/schemas/OpaqueId"
        fence:
          type: integer
          minimum: 1
        worker_incarnation:
          $ref: "#/components/schemas/OpaqueId"
    AttemptAuthority:
      type: object
      required:
        - attempt_id
        - fence
        - worker_incarnation
      properties:
        attempt_id:
          $ref: "#/components/schemas/OpaqueId"
        fence:
          type: integer
          minimum: 1
        worker_incarnation:
          $ref: "#/components/schemas/OpaqueId"
    AttemptCheckpointRequest:
      type: object
      required:
        - operation_id
        - fence
        - worker_incarnation
        - checkpoint_ref
        - resolved_source_id
        - validated_bytes
        - validated_members
      properties:
        operation_id:
          $ref: "#/components/schemas/OpaqueId"
        fence:
          type: integer
          minimum: 1
        worker_incarnation:
          $ref: "#/components/schemas/OpaqueId"
        checkpoint_ref:
          $ref: "#/components/schemas/CheckpointDescriptorRef"
        resolved_source_id:
          $ref: "#/components/schemas/OpaqueId"
        validated_bytes:
          type: integer
          minimum: 0
        validated_members:
          type: integer
          minimum: 0
        staging_multipart:
          $ref: "#/components/schemas/StagingMultipartIdentity"
    AttemptMutation:
      type: object
      required:
        - operation_id
        - fence
        - worker_incarnation
      properties:
        operation_id:
          $ref: "#/components/schemas/OpaqueId"
        fence:
          type: integer
          minimum: 1
        worker_incarnation:
          $ref: "#/components/schemas/OpaqueId"
    AttemptOutcomeRequest:
      type: object
      required:
        - operation_id
        - fence
        - worker_incarnation
        - outcome
      properties:
        operation_id:
          $ref: "#/components/schemas/OpaqueId"
        fence:
          type: integer
          minimum: 1
        worker_incarnation:
          $ref: "#/components/schemas/OpaqueId"
        outcome:
          oneOf:
            - type: object
              properties:
                kind:
                  type: string
                  enum:
                    - success
                result:
                  $ref: "#/components/schemas/ResultDescriptor"
              required:
                - kind
                - result
            - type: object
              properties:
                kind:
                  type: string
                  enum:
                    - failure
                failure:
                  $ref: "#/components/schemas/AttemptRuntimeFailure"
              required:
                - kind
                - failure
    AttemptPage:
      type: object
      required:
        - items
        - next_cursor
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/AttemptRecord"
        next_cursor:
          anyOf:
            - type: string
            - type: "null"
    AttemptProgressRequest:
      type: object
      required:
        - operation_id
        - fence
        - worker_incarnation
        - progress
      properties:
        operation_id:
          $ref: "#/components/schemas/OpaqueId"
        fence:
          type: integer
          minimum: 1
        worker_incarnation:
          $ref: "#/components/schemas/OpaqueId"
        progress:
          $ref: "#/components/schemas/ProgressValue"
    AttemptRecord:
      type: object
      required:
        - id
        - fence
        - worker_incarnation
        - state
        - progress
        - result
        - failure
        - created_at
        - updated_at
      properties:
        id:
          $ref: "#/components/schemas/OpaqueId"
        fence:
          type: integer
          minimum: 1
        worker_incarnation:
          $ref: "#/components/schemas/OpaqueId"
        state:
          type: string
          enum:
            - AttemptAuthorized
            - AttemptExecuting
            - AttemptStopped
            - AttemptCommitted
        progress:
          oneOf:
            - $ref: "#/components/schemas/Progress"
            - type: "null"
        result:
          oneOf:
            - $ref: "#/components/schemas/ResultDescriptor"
            - type: "null"
        failure:
          oneOf:
            - $ref: "#/components/schemas/JobFailure"
            - type: "null"
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    AttemptRenewRequest:
      type: object
      required:
        - operation_id
        - fence
        - worker_incarnation
      properties:
        operation_id:
          $ref: "#/components/schemas/OpaqueId"
        fence:
          type: integer
          minimum: 1
        worker_incarnation:
          $ref: "#/components/schemas/OpaqueId"
    AttemptResolvedSourceRequest:
      type: object
      required:
        - operation_id
        - fence
        - worker_incarnation
        - resolved_source_ref
      properties:
        operation_id:
          $ref: "#/components/schemas/OpaqueId"
        fence:
          type: integer
          minimum: 1
        worker_incarnation:
          $ref: "#/components/schemas/OpaqueId"
        resolved_source_ref:
          $ref: "#/components/schemas/ResolvedSourceDescriptorRef"
    AttemptRuntimeFailure:
      type: object
      required:
        - class
        - message
      properties:
        class:
          type: string
          enum:
            - authorization
            - source_not_found
            - source_changed
            - transient_source
            - transient_target
            - integrity
            - capacity
            - internal
        message:
          type: string
          maxLength: 500
        safe_details:
          type: object
          unevaluatedProperties:
            $ref: "#/components/schemas/SafeDetailValue"
    AttemptStagingMultipartRequest:
      type: object
      required:
        - operation_id
        - fence
        - worker_incarnation
        - multipart
      properties:
        operation_id:
          $ref: "#/components/schemas/OpaqueId"
        fence:
          type: integer
          minimum: 1
        worker_incarnation:
          $ref: "#/components/schemas/OpaqueId"
        multipart:
          $ref: "#/components/schemas/StagingMultipartIdentity"
    AttemptStagingObjectRequest:
      type: object
      required:
        - operation_id
        - fence
        - worker_incarnation
        - object
      properties:
        operation_id:
          $ref: "#/components/schemas/OpaqueId"
        fence:
          type: integer
          minimum: 1
        worker_incarnation:
          $ref: "#/components/schemas/OpaqueId"
        object:
          $ref: "#/components/schemas/StagingObjectIdentity"
        completed_upload_id:
          type: string
          minLength: 1
    AttemptStagingWriteIntentRequest:
      type: object
      required:
        - operation_id
        - fence
        - worker_incarnation
        - intent
      properties:
        operation_id:
          $ref: "#/components/schemas/OpaqueId"
        fence:
          type: integer
          minimum: 1
        worker_incarnation:
          $ref: "#/components/schemas/OpaqueId"
        intent:
          $ref: "#/components/schemas/StagingWriteIntent"
    AttemptStopRequest:
      type: object
      required:
        - operation_id
        - fence
        - worker_incarnation
      properties:
        operation_id:
          $ref: "#/components/schemas/OpaqueId"
        fence:
          type: integer
          minimum: 1
        worker_incarnation:
          $ref: "#/components/schemas/OpaqueId"
    BasicAuthCredentialCreate:
      type: object
      required:
        - label
        - kind
        - material
      properties:
        label:
          type: string
          minLength: 1
          maxLength: 200
        kind:
          type: string
          enum:
            - basic_auth
        material:
          $ref: "#/components/schemas/BasicAuthMaterial"
    BasicAuthMaterial:
      type: object
      required:
        - username
        - password
      properties:
        username:
          type: string
          minLength: 1
          maxLength: 1024
        password:
          type: string
          minLength: 1
          maxLength: 16384
    BearerTokenCredentialCreate:
      type: object
      required:
        - label
        - kind
        - material
      properties:
        label:
          type: string
          minLength: 1
          maxLength: 200
        kind:
          type: string
          enum:
            - bearer_token
        material:
          $ref: "#/components/schemas/TokenMaterial"
    BucketName:
      type: string
      pattern: ^(?!.*\.\.)[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$
    CheckpointDescriptorRef:
      type: object
      required:
        - id
        - kind
        - schema_version
        - byte_length
        - checksum
      properties:
        id:
          $ref: "#/components/schemas/OpaqueId"
        kind:
          type: string
          enum:
            - checkpoint
        schema_version:
          type: integer
          minimum: 1
        byte_length:
          type: integer
          minimum: 0
        item_count:
          type: integer
          minimum: 0
        checksum:
          $ref: "#/components/schemas/Sha256Digest"
    CheckpointProjection:
      type: object
      required:
        - reusable
        - validated_bytes
        - validated_members
      properties:
        reusable:
          type: boolean
        validated_bytes:
          type: integer
          minimum: 0
        validated_members:
          type: integer
          minimum: 0
    ClaimRequest:
      type: object
      required:
        - operation_id
        - worker_incarnation
      properties:
        operation_id:
          $ref: "#/components/schemas/OpaqueId"
        worker_incarnation:
          $ref: "#/components/schemas/OpaqueId"
    ClaimResponse:
      type: object
      required:
        - authority
        - execution
      properties:
        authority:
          $ref: "#/components/schemas/AttemptAuthority"
        execution:
          $ref: "#/components/schemas/ExecutionEnvelope"
    CredentialGrantVersion:
      type: object
      required:
        - credential_id
        - version_id
      properties:
        credential_id:
          $ref: "#/components/schemas/CredentialId"
        version_id:
          $ref: "#/components/schemas/CredentialVersionId"
    CredentialId:
      type: string
      pattern: ^[A-Za-z0-9][A-Za-z0-9_-]{7,127}$
      description: Owner-authorized source credential registry identifier.
    CredentialMaterial:
      oneOf:
        - $ref: "#/components/schemas/BasicAuthMaterial"
        - $ref: "#/components/schemas/TokenMaterial"
        - $ref: "#/components/schemas/HttpHeadersMaterial"
        - $ref: "#/components/schemas/ObjectStoreCredentialMaterial"
      description: Write-only material whose closed shape must match the credential kind. Values are never returned or logged.
    CredentialVersionId:
      type: string
      pattern: ^[A-Za-z0-9][A-Za-z0-9_-]{7,127}$
      description: Immutable application credential-version identifier; backend secret-store coordinates are never exposed.
    DeletionChanged:
      type: object
      required:
        - kind
        - job_id
        - operation_id
        - state
      properties:
        kind:
          type: string
          enum:
            - deletion_changed
        job_id:
          $ref: "#/components/schemas/OpaqueId"
        operation_id:
          $ref: "#/components/schemas/OpaqueId"
        state:
          type: string
          enum:
            - queued
            - running
            - retry_wait
            - blocked
            - completed
      allOf:
        - $ref: "#/components/schemas/EventBase"
    DeletionOperation:
      type: object
      required:
        - id
        - job_id
        - state
        - problem
        - created_at
        - updated_at
      properties:
        id:
          $ref: "#/components/schemas/OpaqueId"
        job_id:
          $ref: "#/components/schemas/OpaqueId"
        state:
          type: string
          enum:
            - queued
            - running
            - retry_wait
            - blocked
            - completed
        problem:
          oneOf:
            - $ref: "#/components/schemas/DeletionProblem"
            - type: "null"
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    DeletionProblem:
      type: object
      required:
        - class
        - message
      properties:
        class:
          type: string
          enum:
            - authorization
            - target_unavailable
            - configuration
            - internal
        message:
          type: string
          maxLength: 500
    DurableDescriptorRef:
      type: object
      required:
        - id
        - kind
        - schema_version
        - byte_length
        - checksum
      properties:
        id:
          $ref: "#/components/schemas/OpaqueId"
        kind:
          type: string
          enum:
            - resolved_source
            - checkpoint
        schema_version:
          type: integer
          minimum: 1
        byte_length:
          type: integer
          minimum: 0
        item_count:
          type: integer
          minimum: 0
        checksum:
          $ref: "#/components/schemas/Sha256Digest"
    EventAttempt:
      type: object
      required:
        - attempt_id
        - fence
      properties:
        attempt_id:
          $ref: "#/components/schemas/OpaqueId"
        fence:
          type: integer
          minimum: 1
    EventBase:
      type: object
      required:
        - schema_version
        - event_id
        - sequence
        - cursor
        - occurred_at
      properties:
        schema_version:
          type: number
          enum:
            - 1
        event_id:
          $ref: "#/components/schemas/OpaqueId"
        sequence:
          type: integer
          minimum: 1
        cursor:
          $ref: "#/components/schemas/EventCursor"
        occurred_at:
          type: string
          format: date-time
    EventCursor:
      type: string
      minLength: 16
      maxLength: 2048
    EventFrame:
      type: object
      oneOf:
        - $ref: "#/components/schemas/JobChanged"
        - $ref: "#/components/schemas/DeletionChanged"
        - $ref: "#/components/schemas/ResyncRequired"
        - $ref: "#/components/schemas/Heartbeat"
      discriminator:
        propertyName: kind
        mapping:
          job_changed: "#/components/schemas/JobChanged"
          deletion_changed: "#/components/schemas/DeletionChanged"
          resync_required: "#/components/schemas/ResyncRequired"
          heartbeat: "#/components/schemas/Heartbeat"
    EventProgress:
      type: object
      required:
        - attempt_id
        - fence
        - completed_bytes
        - completed_members
      properties:
        attempt_id:
          $ref: "#/components/schemas/OpaqueId"
        fence:
          type: integer
          minimum: 1
        completed_bytes:
          type: integer
          minimum: 0
        total_bytes:
          anyOf:
            - type: integer
            - type: "null"
          minimum: 0
        completed_members:
          type: integer
          minimum: 0
        total_members:
          anyOf:
            - type: integer
            - type: "null"
          minimum: 0
    EventTicket:
      type: object
      required:
        - ticket
        - expires_at
      properties:
        ticket:
          $ref: "#/components/schemas/OpaqueId"
        expires_at:
          type: string
          format: date-time
    ExecutionEnvelope:
      type: object
      required:
        - id
        - job_id
        - attempt_id
        - fence
        - worker_incarnation
        - source
        - sensitive_source_ref
        - credential_version
        - resolved_source_ref
        - target
        - staging_target
        - execution_grant_ref
        - checkpoint_ref
      properties:
        id:
          $ref: "#/components/schemas/OpaqueId"
        job_id:
          $ref: "#/components/schemas/OpaqueId"
        attempt_id:
          $ref: "#/components/schemas/OpaqueId"
        fence:
          type: integer
          minimum: 1
        worker_incarnation:
          $ref: "#/components/schemas/OpaqueId"
        source:
          $ref: "#/components/schemas/SourceProjection"
        sensitive_source_ref:
          $ref: "#/components/schemas/OpaqueId"
          description: Opaque grant-bound reference to the complete accepted source input; credential_version identifies any pinned credential separately.
        credential_version:
          oneOf:
            - $ref: "#/components/schemas/CredentialGrantVersion"
            - type: "null"
        resolved_source_ref:
          oneOf:
            - $ref: "#/components/schemas/DurableDescriptorRef"
            - type: "null"
        target:
          $ref: "#/components/schemas/Target"
        staging_target:
          $ref: "#/components/schemas/StagingTarget"
        execution_grant_ref:
          $ref: "#/components/schemas/OpaqueId"
        checkpoint_ref:
          oneOf:
            - $ref: "#/components/schemas/DurableDescriptorRef"
            - type: "null"
    Heartbeat:
      type: object
      required:
        - kind
      properties:
        kind:
          type: string
          enum:
            - heartbeat
      allOf:
        - $ref: "#/components/schemas/EventBase"
    HttpHeadersCredentialCreate:
      type: object
      required:
        - label
        - kind
        - material
      properties:
        label:
          type: string
          minLength: 1
          maxLength: 200
        kind:
          type: string
          enum:
            - http_headers
        material:
          $ref: "#/components/schemas/HttpHeadersMaterial"
    HttpHeadersMaterial:
      type: object
      required:
        - headers
      properties:
        headers:
          type: object
          unevaluatedProperties:
            type: string
          description: Canonical lowercase end-to-end headers. Connection-nominated and routing, framing, cookie, proxy, and authentication headers are rejected.
    HttpSourceProjection:
      type: object
      required:
        - kind
        - display_url
        - result_path
      properties:
        kind:
          type: string
          enum:
            - http
        display_url:
          type: string
          format: uri
          maxLength: 8192
          description: Sanitized URL without userinfo, sensitive query values, or fragments.
        result_path:
          $ref: "#/components/schemas/ResultPath"
        credential_id:
          $ref: "#/components/schemas/CredentialId"
    HttpSourceSubmission:
      type: object
      required:
        - kind
        - url
        - result_path
      properties:
        kind:
          type: string
          enum:
            - http
        url:
          type: string
          format: uri
          maxLength: 8192
          description: Sensitive execution input. Public projections expose only display_url.
        result_path:
          $ref: "#/components/schemas/ResultPath"
        credential_id:
          $ref: "#/components/schemas/CredentialId"
    HuggingFaceCredentialCreate:
      type: object
      required:
        - label
        - kind
        - material
      properties:
        label:
          type: string
          minLength: 1
          maxLength: 200
        kind:
          type: string
          enum:
            - hugging_face
        material:
          $ref: "#/components/schemas/TokenMaterial"
    HuggingFaceRepositoryId:
      type: string
      pattern: ^[A-Za-z0-9._-]+/[A-Za-z0-9._-]+$
    HuggingFaceSelection:
      type: object
      properties:
        paths:
          type: array
          items:
            $ref: "#/components/schemas/ResultPath"
          maxItems: 10000
        prefixes:
          type: array
          items:
            $ref: "#/components/schemas/ResultPath"
          maxItems: 10000
    HuggingFaceSourceProjection:
      type: object
      required:
        - kind
        - repository_type
        - repository_id
        - revision
      properties:
        kind:
          type: string
          enum:
            - hugging_face
        repository_type:
          type: string
          enum:
            - model
            - dataset
            - space
        repository_id:
          $ref: "#/components/schemas/HuggingFaceRepositoryId"
        revision:
          type: string
          minLength: 1
          maxLength: 256
        selection:
          $ref: "#/components/schemas/HuggingFaceSelection"
        credential_id:
          $ref: "#/components/schemas/CredentialId"
    HuggingFaceSourceSubmission:
      type: object
      required:
        - kind
        - repository_type
        - repository_id
        - revision
      properties:
        kind:
          type: string
          enum:
            - hugging_face
        repository_type:
          type: string
          enum:
            - model
            - dataset
            - space
        repository_id:
          $ref: "#/components/schemas/HuggingFaceRepositoryId"
        revision:
          type: string
          minLength: 1
          maxLength: 256
        selection:
          $ref: "#/components/schemas/HuggingFaceSelection"
        credential_id:
          $ref: "#/components/schemas/CredentialId"
    Job:
      type: object
      required:
        - resource_kind
        - id
        - owner
        - label
        - revision
        - phase
        - lifecycle
        - source
        - target
        - authoritative_attempt
        - progress
        - checkpoint
        - result
        - failure
        - created_at
        - updated_at
        - event_cursor
      properties:
        resource_kind:
          type: string
          enum:
            - job
        id:
          $ref: "#/components/schemas/OpaqueId"
        owner:
          $ref: "#/components/schemas/PrincipalId"
        label:
          anyOf:
            - type: string
            - type: "null"
          minLength: 1
          maxLength: 200
        revision:
          type: integer
          minimum: 1
        phase:
          $ref: "#/components/schemas/JobPhase"
        lifecycle:
          $ref: "#/components/schemas/JobLifecycle"
        source:
          $ref: "#/components/schemas/SourceProjection"
        target:
          $ref: "#/components/schemas/Target"
        authoritative_attempt:
          oneOf:
            - $ref: "#/components/schemas/AttemptAuthority"
            - type: "null"
        progress:
          oneOf:
            - $ref: "#/components/schemas/Progress"
            - type: "null"
        checkpoint:
          oneOf:
            - $ref: "#/components/schemas/CheckpointProjection"
            - type: "null"
        result:
          oneOf:
            - $ref: "#/components/schemas/ResultDescriptor"
            - type: "null"
        failure:
          oneOf:
            - $ref: "#/components/schemas/JobFailure"
            - type: "null"
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        event_cursor:
          type: string
          minLength: 16
    JobChanged:
      type: object
      required:
        - kind
        - job_id
        - job_revision
        - phase
        - lifecycle
        - authoritative_attempt
        - progress
      properties:
        kind:
          type: string
          enum:
            - job_changed
        job_id:
          $ref: "#/components/schemas/OpaqueId"
        job_revision:
          type: integer
          minimum: 1
        phase:
          $ref: "#/components/schemas/JobPhase"
        lifecycle:
          $ref: "#/components/schemas/JobLifecycle"
        authoritative_attempt:
          oneOf:
            - $ref: "#/components/schemas/EventAttempt"
            - type: "null"
        progress:
          oneOf:
            - $ref: "#/components/schemas/EventProgress"
            - type: "null"
      allOf:
        - $ref: "#/components/schemas/EventBase"
    JobFailure:
      oneOf:
        - $ref: "#/components/schemas/PermanentJobFailure"
        - $ref: "#/components/schemas/RetryableJobFailure"
    JobLifecycle:
      type: string
      enum:
        - visible
        - soft_deleted
        - hard_deleting
        - hard_deleted
    JobPage:
      type: object
      required:
        - items
        - next_cursor
        - event_cursor
        - management_capabilities
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/JobResource"
        next_cursor:
          anyOf:
            - type: string
            - type: "null"
        event_cursor:
          type: string
          minLength: 16
        management_capabilities:
          $ref: "#/components/schemas/ManagementCapabilities"
    JobPhase:
      type: string
      enum:
        - Queued
        - Running
        - RetryWait
        - Cancelling
        - Succeeded
        - Failed
        - Cancelled
    JobPhaseProjection:
      type: object
      required:
        - phase
      properties:
        phase:
          $ref: "#/components/schemas/JobPhase"
    JobResource:
      type: object
      oneOf:
        - $ref: "#/components/schemas/Job"
        - $ref: "#/components/schemas/JobTombstone"
      discriminator:
        propertyName: resource_kind
        mapping:
          job: "#/components/schemas/Job"
          tombstone: "#/components/schemas/JobTombstone"
    JobSubmission:
      type: object
      required:
        - source
      properties:
        source:
          $ref: "#/components/schemas/SourceSubmission"
        target:
          $ref: "#/components/schemas/TargetOverride"
          description: Fields omitted here are taken from the configured default target before authorization.
        label:
          type: string
          minLength: 1
          maxLength: 200
    JobTombstone:
      type: object
      required:
        - resource_kind
        - id
        - owner
        - target
        - terminal_phase
        - deletion_operation_id
        - created_at
        - hard_delete_started_at
        - updated_at
        - event_cursor
      properties:
        resource_kind:
          type: string
          enum:
            - tombstone
        id:
          $ref: "#/components/schemas/OpaqueId"
        owner:
          $ref: "#/components/schemas/PrincipalId"
        target:
          $ref: "#/components/schemas/Target"
        terminal_phase:
          $ref: "#/components/schemas/TerminalJobPhase"
        deletion_operation_id:
          $ref: "#/components/schemas/OpaqueId"
        created_at:
          type: string
          format: date-time
        hard_delete_started_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        event_cursor:
          type: string
          minLength: 16
    LeaseProjection:
      type: object
      required:
        - expires_at
        - renew_after
      properties:
        expires_at:
          type: string
          format: date-time
          description: Expiry of the exact coordination lease established for this authority.
        renew_after:
          type: string
          format: date-time
          description: Earliest recommended renewal time, strictly before expires_at.
    ManagementCapabilities:
      type: object
      required:
        - revoke_execution_grants
      properties:
        revoke_execution_grants:
          type: boolean
          description: Current caller may administratively revoke accepted execution grants.
    ObjectIdentity:
      type: object
      required:
        - store
        - bucket
        - key
        - checksum
        - size
      properties:
        store:
          type: string
        bucket:
          type: string
        key:
          type: string
        version_id:
          type: string
        checksum:
          $ref: "#/components/schemas/Sha256Digest"
        size:
          type: integer
          minimum: 0
    ObjectStoreCredentialCreate:
      type: object
      required:
        - label
        - kind
        - material
      properties:
        label:
          type: string
          minLength: 1
          maxLength: 200
        kind:
          type: string
          enum:
            - object_store
        material:
          $ref: "#/components/schemas/ObjectStoreCredentialMaterial"
    ObjectStoreCredentialMaterial:
      type: object
      required:
        - access_key_id
        - secret_access_key
      properties:
        access_key_id:
          type: string
          minLength: 1
          maxLength: 1024
        secret_access_key:
          type: string
          minLength: 1
          maxLength: 16384
        session_token:
          type: string
          minLength: 1
          maxLength: 16384
    ObjectStoreSourceProjection:
      type: object
      required:
        - kind
        - store
        - bucket
        - key
        - result_path
      properties:
        kind:
          type: string
          enum:
            - object_store
        store:
          type: string
          minLength: 1
          maxLength: 128
        bucket:
          type: string
          minLength: 3
          maxLength: 63
        key:
          type: string
          minLength: 1
          maxLength: 4096
        version_id:
          type: string
          maxLength: 1024
        result_path:
          $ref: "#/components/schemas/ResultPath"
        credential_id:
          $ref: "#/components/schemas/CredentialId"
    ObjectStoreSourceSubmission:
      type: object
      required:
        - kind
        - store
        - bucket
        - key
        - result_path
      properties:
        kind:
          type: string
          enum:
            - object_store
        store:
          type: string
          minLength: 1
          maxLength: 128
        bucket:
          type: string
          minLength: 3
          maxLength: 63
        key:
          type: string
          minLength: 1
          maxLength: 4096
        version_id:
          type: string
          maxLength: 1024
        result_path:
          $ref: "#/components/schemas/ResultPath"
        credential_id:
          $ref: "#/components/schemas/CredentialId"
    OpaqueId:
      type: string
      pattern: ^[A-Za-z0-9][A-Za-z0-9_-]{7,127}$
    PermanentJobFailure:
      type: object
      required:
        - class
        - retryable
        - message
      properties:
        class:
          type: string
          enum:
            - validation
            - authorization
            - source_not_found
            - source_changed
            - cancelled
        retryable:
          type: boolean
          enum:
            - false
        message:
          type: string
          maxLength: 500
        safe_details:
          type: object
          unevaluatedProperties:
            $ref: "#/components/schemas/SafeDetailValue"
    PrincipalId:
      type: string
      pattern: ^[A-Za-z0-9][A-Za-z0-9_-]{7,127}$
      description: Internal stable principal identifier mapped to one exact OIDC issuer and subject pair.
    Progress:
      type: object
      required:
        - attempt_id
        - fence
        - completed_bytes
        - completed_members
        - observed_at
      properties:
        attempt_id:
          $ref: "#/components/schemas/OpaqueId"
        fence:
          type: integer
          minimum: 1
        completed_bytes:
          type: integer
          minimum: 0
        total_bytes:
          anyOf:
            - type: integer
            - type: "null"
          minimum: 0
        completed_members:
          type: integer
          minimum: 0
        total_members:
          anyOf:
            - type: integer
            - type: "null"
          minimum: 0
        observed_at:
          type: string
          format: date-time
    ProgressValue:
      type: object
      required:
        - completed_bytes
        - completed_members
      properties:
        completed_bytes:
          type: integer
          minimum: 0
        total_bytes:
          anyOf:
            - type: integer
            - type: "null"
          minimum: 0
        completed_members:
          type: integer
          minimum: 0
        total_members:
          anyOf:
            - type: integer
            - type: "null"
          minimum: 0
    ResolvedSourceDescriptorRef:
      type: object
      required:
        - id
        - kind
        - schema_version
        - byte_length
        - checksum
      properties:
        id:
          $ref: "#/components/schemas/OpaqueId"
        kind:
          type: string
          enum:
            - resolved_source
        schema_version:
          type: integer
          minimum: 1
        byte_length:
          type: integer
          minimum: 0
        item_count:
          type: integer
          minimum: 0
        checksum:
          $ref: "#/components/schemas/Sha256Digest"
    ResultDescriptor:
      type: object
      required:
        - kind
        - manifest_id
        - schema_version
        - manifest
        - member_count
        - total_bytes
      properties:
        kind:
          type: string
          enum:
            - manifest
        manifest_id:
          $ref: "#/components/schemas/OpaqueId"
        schema_version:
          type: integer
          minimum: 1
        manifest:
          $ref: "#/components/schemas/ObjectIdentity"
        member_count:
          type: integer
          minimum: 1
        total_bytes:
          type: integer
          minimum: 0
    ResultMember:
      type: object
      required:
        - id
        - path
        - size
        - object
      properties:
        id:
          $ref: "#/components/schemas/OpaqueId"
        path:
          type: string
          minLength: 1
          maxLength: 4096
          description: NFC-normalized relative POSIX path validated under architecture.md.
        size:
          type: integer
          minimum: 0
        object:
          $ref: "#/components/schemas/ObjectIdentity"
    ResultMemberAccess:
      type: object
      required:
        - url
        - expires_at
      properties:
        url:
          type: string
          format: uri
          pattern: ^https?://
          description: Sensitive time-limited HTTP(S) exact-object URL.
        expires_at:
          type: string
          format: date-time
    ResultMemberPage:
      type: object
      required:
        - items
        - next_cursor
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/ResultMember"
        next_cursor:
          anyOf:
            - type: string
            - type: "null"
    ResultPath:
      type: string
      minLength: 1
      maxLength: 4096
      description: NFC-normalized relative POSIX path validated under architecture.md.
    ResyncRequired:
      type: object
      required:
        - kind
        - reason
      properties:
        kind:
          type: string
          enum:
            - resync_required
        reason:
          type: string
          enum:
            - cursor_absent
            - cursor_invalid
            - cursor_expired
            - authorization_changed
            - history_unavailable
      allOf:
        - $ref: "#/components/schemas/EventBase"
    RetryableJobFailure:
      type: object
      required:
        - class
        - retryable
        - message
      properties:
        class:
          type: string
          enum:
            - transient_source
            - transient_target
            - integrity
            - capacity
            - internal
            - lost_attempt
        retryable:
          type: boolean
          enum:
            - true
        message:
          type: string
          maxLength: 500
        safe_details:
          type: object
          unevaluatedProperties:
            $ref: "#/components/schemas/SafeDetailValue"
    SafeDetailValue:
      anyOf:
        - type: string
        - type: integer
          format: int64
        - type: boolean
        - type: "null"
    Sha256Digest:
      type: string
      pattern: ^sha256:[a-f0-9]{64}$
    SourceCredential:
      type: object
      required:
        - id
        - owner
        - label
        - kind
        - status
        - active_version
        - created_at
        - updated_at
      properties:
        id:
          $ref: "#/components/schemas/CredentialId"
        owner:
          $ref: "#/components/schemas/PrincipalId"
        label:
          type: string
          minLength: 1
          maxLength: 200
        kind:
          $ref: "#/components/schemas/SourceCredentialKind"
        status:
          type: string
          enum:
            - active
            - revoked
        active_version:
          oneOf:
            - $ref: "#/components/schemas/SourceCredentialVersion"
            - type: "null"
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    SourceCredentialCreate:
      type: object
      oneOf:
        - $ref: "#/components/schemas/BasicAuthCredentialCreate"
        - $ref: "#/components/schemas/BearerTokenCredentialCreate"
        - $ref: "#/components/schemas/HttpHeadersCredentialCreate"
        - $ref: "#/components/schemas/ObjectStoreCredentialCreate"
        - $ref: "#/components/schemas/HuggingFaceCredentialCreate"
      discriminator:
        propertyName: kind
        mapping:
          basic_auth: "#/components/schemas/BasicAuthCredentialCreate"
          bearer_token: "#/components/schemas/BearerTokenCredentialCreate"
          http_headers: "#/components/schemas/HttpHeadersCredentialCreate"
          object_store: "#/components/schemas/ObjectStoreCredentialCreate"
          hugging_face: "#/components/schemas/HuggingFaceCredentialCreate"
    SourceCredentialKind:
      type: string
      enum:
        - basic_auth
        - bearer_token
        - http_headers
        - object_store
        - hugging_face
    SourceCredentialPage:
      type: object
      required:
        - items
        - next_cursor
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/SourceCredential"
        next_cursor:
          anyOf:
            - type: string
            - type: "null"
    SourceCredentialRotate:
      type: object
      required:
        - material
      properties:
        material:
          $ref: "#/components/schemas/CredentialMaterial"
      description: The material shape must match the stored credential kind; rotation never changes kind.
    SourceCredentialVersion:
      type: object
      required:
        - id
        - created_at
      properties:
        id:
          $ref: "#/components/schemas/CredentialVersionId"
        created_at:
          type: string
          format: date-time
    SourceProjection:
      type: object
      oneOf:
        - $ref: "#/components/schemas/HttpSourceProjection"
        - $ref: "#/components/schemas/ObjectStoreSourceProjection"
        - $ref: "#/components/schemas/HuggingFaceSourceProjection"
      discriminator:
        propertyName: kind
        mapping:
          http: "#/components/schemas/HttpSourceProjection"
          object_store: "#/components/schemas/ObjectStoreSourceProjection"
          hugging_face: "#/components/schemas/HuggingFaceSourceProjection"
    SourceSubmission:
      type: object
      oneOf:
        - $ref: "#/components/schemas/HttpSourceSubmission"
        - $ref: "#/components/schemas/ObjectStoreSourceSubmission"
        - $ref: "#/components/schemas/HuggingFaceSourceSubmission"
      discriminator:
        propertyName: kind
        mapping:
          http: "#/components/schemas/HttpSourceSubmission"
          object_store: "#/components/schemas/ObjectStoreSourceSubmission"
          hugging_face: "#/components/schemas/HuggingFaceSourceSubmission"
    StagingMultipartIdentity:
      type: object
      required:
        - store
        - bucket
        - key
        - upload_id
      properties:
        store:
          type: string
          minLength: 1
        bucket:
          type: string
          minLength: 1
        key:
          type: string
          minLength: 1
        upload_id:
          type: string
          minLength: 1
    StagingObjectIdentity:
      type: object
      required:
        - store
        - bucket
        - key
      properties:
        store:
          type: string
          minLength: 1
        bucket:
          type: string
          minLength: 1
        key:
          type: string
          minLength: 1
        version_id:
          type: string
          minLength: 1
    StagingTarget:
      type: object
      required:
        - store
        - bucket
        - prefix
      properties:
        store:
          type: string
          minLength: 1
          maxLength: 128
        bucket:
          $ref: "#/components/schemas/BucketName"
        prefix:
          type: string
          minLength: 1
          maxLength: 1024
          description: Exact attempt-scoped internal prefix selected by the service.
    StagingWriteIntent:
      type: object
      required:
        - store
        - bucket
        - key
      properties:
        store:
          type: string
          minLength: 1
        bucket:
          type: string
          minLength: 1
        key:
          type: string
          minLength: 1
    Target:
      type: object
      required:
        - store
        - bucket
        - prefix
      properties:
        store:
          type: string
          minLength: 1
          maxLength: 128
        bucket:
          $ref: "#/components/schemas/BucketName"
        prefix:
          type: string
          maxLength: 1024
          description: NFC-normalized target segments; semantic validation follows architecture.md.
    TargetOverride:
      type: object
      properties:
        bucket:
          $ref: "#/components/schemas/BucketName"
        prefix:
          type: string
          maxLength: 1024
          description: NFC-normalized target segments; semantic validation follows architecture.md.
    TerminalJobPhase:
      type: string
      enum:
        - Succeeded
        - Failed
        - Cancelled
    TokenMaterial:
      type: object
      required:
        - token
      properties:
        token:
          type: string
          minLength: 1
          maxLength: 16384
  securitySchemes:
    oidc:
      type: openIdConnect
      openIdConnectUrl: https://identity.invalid/.well-known/openid-configuration
    serviceAuth:
      type: mutualTLS
    eventTicket:
      type: apiKey
      in: query
      name: ticket
servers:
  - url: /api
    variables: {}
security:
  - oidc: []