worker-protocol-api.openapi.yaml

openapi: 3.1.0
info:
  title: durable-workflow.v2.worker-protocol-api
  version: "23"
  summary: Durable Workflow worker-plane HTTP+JSON API
  description: >
    Normative OpenAPI specification for the worker-plane HTTP+JSON API:
    worker registration, graceful worker deregistration, worker heartbeat,
    worker-session lifecycle,
    long-poll task acquisition, task history paging, task heartbeat,
    task completion, and task failure. Long-poll timing, cancellation,
    and lease semantics are specified by durable-workflow.v2.worker-protocol-stream.
    The server advertises its current 1.N version and accepts request headers
    from the same major whose minor is less than or equal to N.
x-durable-workflow-worker-protocol-negotiation:
  advertised_version_path: worker_protocol.version
  default_advertised_version: "1.19"
  request_header_rule: same_major_and_minor_less_than_or_equal_to_advertised
  accepted_request_versions_by_default: ["1.0", "1.1", "1.2", "1.3", "1.4", "1.5", "1.6", "1.7", "1.8", "1.9", "1.10", "1.11", "1.12", "1.13", "1.14", "1.15", "1.16", "1.17", "1.18", "1.19"]
  response_version: advertised_version
  fail_closed_on: [missing_header, malformed_version, different_major, minor_greater_than_advertised]
x-durable-workflow-catalog-entry: worker_protocol_api
x-durable-workflow-catalog-schema: durable-workflow.v2.platform-protocol-specs.catalog
x-durable-workflow-catalog-version: 16
x-durable-workflow-evolution-rule: additive_minor_breaking_major
x-durable-workflow-message-streams-contract:
  discovery_path: /cluster/info#/message_streams_contract
  minimum_protocol_version: "1.15"
  worker_capability: message_streams
  completion_fields: [message_stream_cursors, message_stream_waits]
  cursor_advancement: highest_contiguous_consumed_position
  replay_identity: [stream_name, message_id, position]
  payload_envelope:
    field: payload_envelope
    worker_delivery: inline_avro_blob
    persistence: exact_inline_bytes_or_external_storage_reference
  version_gate:
    workers_below_minimum:
      advertise_capability: forbidden
      submit_completion_fields: forbidden
    workers_at_or_above_minimum:
      advertise_capability: allowed
      submit_completion_fields: allowed
    rejection_status: 409
    rejection_reason: message_streams_unavailable
x-durable-workflow-workflow-memo-update-contract:
  minimum_protocol_version: "1.14"
  worker_capability: memo_upserts
  capability_enforcement:
    registration_below_floor: { status: 409, reason: workflow_metadata_capability_protocol_mismatch }
    completion_without_capability: { status: 409, reason: workflow_metadata_capability_not_advertised, recorded: false }
    replay_routing: requires_active_lease_owner_registration_capability
    protocol_and_capability_checks: independent
  command:
    type: upsert_memo
    required_fields: [type, entries]
    entries: payload-envelope<avro-map<string, Value|null>>
  merge: replace_named_keys_delete_null_preserve_others
  canonical_order: lexicographic_key_order
  structural_limits:
    max_entries_per_run: 100
    max_value_size_bytes: 10240
    max_total_size_bytes: 65536
    size_measurement: avro_single_object_bytes
    runtime_configured_total_limit: workflows.v2.structural_limits.memo_size_bytes
  validation_failures:
    invalid_command: { status: 422, reason: workflow_memo_validation_failed, recorded: false }
    configured_limit: { status: 422, reason: structural_limit_exceeded, recorded: false }
    unsupported_runtime: { status: 409, reason: workflow_memo_updates_unavailable, recorded: false }
  history_event:
    type: MemoUpserted
    required_fields: [sequence, entries, merged]
    replay_identity: [sequence, entries]
  task_fence: [workflow_task_id, workflow_task_attempt]
  duplicate_completion: does_not_append_or_apply
  continue_as_new: merged_memo_is_inherited
  external_payload_resolution_owner: runtime
  sdk_storage_drivers: false
  published_artifact_conformance:
    worker_languages: [php, python, rust]
    runtime_targets: [standalone_server, managed_cloud]
    required_observations:
      - capability_discovered
      - memo_update_completed
      - waiting_describe_merged
      - completed_describe_merged
      - replay_does_not_duplicate
x-durable-workflow-typed-search-attributes-contract:
  minimum_protocol_version: "1.16"
  worker_capability: typed_search_attributes
  capability_enforcement:
    registration_below_floor: { status: 409, reason: workflow_metadata_capability_protocol_mismatch }
    explicit_completion_without_capability: { status: 409, reason: workflow_metadata_capability_not_advertised, recorded: false }
    typed_history_routing: requires_active_lease_owner_registration_capability
    legacy_untyped_history_routing: capability_not_required
    protocol_and_capability_checks: independent
  canonical_type_names: [string, keyword, keyword_list, int, float, bool, datetime]
  completion_field: commands[].attribute_types
  declaration_identity: [key, canonical_type, json_value]
  server_boundary:
    validate: [declared_key, declared_type, declared_value, namespace_registered_type]
    malformed_or_conflicting_declaration_status: 422
    malformed_or_conflicting_declaration_reason: validation_failed
    inference_after_invalid_declaration: forbidden
  history:
    event_type: SearchAttributesUpserted
    payload_field: attribute_types
    new_event_rule: canonical_effective_type_required_for_every_non_deleted_attribute
    full_and_paginated_history: identical
    replay_identity: [sequence, attributes, attribute_types]
    legacy_missing_metadata: unknown_type_identity_compare_value_only
  version_gate:
    workers_below_minimum:
      submit_attribute_types: forbidden
    workers_at_or_above_minimum:
      submit_attribute_types: allowed
    rejection_status: 409
    rejection_reason: typed_search_attributes_unavailable
x-durable-workflow-condition-wait-occurrence-identity-contract:
  minimum_protocol_version: "1.17"
  command:
    type: open_condition_wait
    field: condition_wait_occurrence_id
  authoring_gate:
    workers_below_minimum: forbidden
    rejection_status: 409
    rejection_reason: condition_wait_occurrence_identity_unavailable
    recorded: false
  replay_gate:
    history_with_occurrence_identity: requires_minimum_worker_protocol_version
    history_without_occurrence_identity: compatible_older_workers_allowed
    applies_to: [cold_replay, cached_poll, redelivery]
  history:
    field: condition_wait_occurrence_id
    event_types: [ConditionWaitOpened, ConditionWaitSatisfied, ConditionWaitTimedOut, TimerScheduled, TimerFired, TimerCancelled]
  version_independence:
    server_below_minimum_rejects_worker_1_17: ahead_request_version
    server_at_minimum_accepts_worker_1_16_for_unaffected_history: true
x-durable-workflow-portable-worker-affinity-contract:
  minimum_protocol_version: "1.18"
  worker_capabilities: [local_activities, worker_sessions, sticky_execution]
  capability_manifest:
    required_feature_entries: [local_activities, worker_sessions, sticky_execution]
    supported_entry_must_match_flat_capability: true
  local_activities:
    command_type: record_local_activity
    attempt_reports_required_from_protocol_version: "1.19"
    retained_nested_object_unknown_fields: ignore
    strict_nested_object_shape_from_protocol_version: "1.19"
    attempt_sequence: contiguous_one_based
    maximum_attempts: 100
    maximum_heartbeats_per_attempt: 1000
    maximum_total_heartbeats: 1000
    terminal_attempt_outcome: matches_command_outcome
    non_final_outcomes: [failed, timed_out]
    durable_attempt_id_authority: server
    worker_attempt_id_preserved: true
    replay: recorded_terminal_side_effect_is_reused_without_execution
  worker_sessions:
    lifecycle_verbs: [create, heartbeat, close]
    holder_loss: replacement_worker_reacquires_and_rebuilds_process_local_state
  sticky_execution:
    cache_owner: worker_process
    cache_key_fields: [workflow_id, run_id, build_id]
    correctness_fallback: cold_replay
  version_gate:
    workers_below_minimum:
      advertise_capabilities: forbidden
      submit_portable_affinity_fields: forbidden
    workers_at_or_above_minimum:
      advertise_only_implemented_capabilities: required
    rejection_status: 409
    recorded: false
x-durable-workflow-object-families:
  - name: worker_registration_request
    owner_repo: durable-workflow/server
  - name: worker_deregistration_result
    owner_repo: durable-workflow/server
  - name: worker_task_poll_request
    owner_repo: durable-workflow/server
  - name: worker_task_result
    owner_repo: durable-workflow/server
  - name: worker_query_task_poll_request
    owner_repo: durable-workflow/server
  - name: worker_query_task_result
    owner_repo: durable-workflow/server
  - name: external_task_input_contract
    owner_repo: durable-workflow/server
  - name: external_task_result_contract
    owner_repo: durable-workflow/server
servers:
  - url: /api
security:
  - durableWorkerAuth: []
paths:
  /worker/register:
    post:
      operationId: registerWorker
      tags: [worker-lifecycle]
      parameters: [{ $ref: "#/components/parameters/WorkerProtocolVersionHeader" }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/WorkerRegistrationRequest" }
      responses:
        "201": { $ref: "#/components/responses/WorkerRegistrationEnvelope" }
        "400": { $ref: "#/components/responses/WorkerError" }
        "409": { $ref: "#/components/responses/WorkerRegistrationFailure" }
        "422": { $ref: "#/components/responses/WorkerError" }
        "503": { $ref: "#/components/responses/WorkerServiceUnavailable" }
  /worker/registrations/{workerId}:
    delete:
      operationId: deregisterWorker
      summary: Gracefully deregister a worker
      description: >
        Removes the named worker registration in the resolved namespace and
        recovers its outstanding workflow-task leases for replacement workers.
        This worker-plane lifecycle operation requires the worker role; it is
        distinct from the administrator-only worker-management endpoint.
      tags: [worker-lifecycle]
      x-durable-workflow-required-role: worker
      parameters:
        - $ref: "#/components/parameters/WorkerProtocolVersionHeader"
        - $ref: "#/components/parameters/WorkerIdPath"
      responses:
        "200": { $ref: "#/components/responses/WorkerDeregistrationEnvelope" }
        "400": { $ref: "#/components/responses/WorkerError" }
        "401": { $ref: "#/components/responses/WorkerError" }
        "403": { $ref: "#/components/responses/WorkerError" }
        "404": { $ref: "#/components/responses/WorkerError" }
        "409": { $ref: "#/components/responses/WorkerError" }
  /worker/heartbeat:
    post:
      operationId: heartbeatWorker
      tags: [worker-lifecycle]
      parameters: [{ $ref: "#/components/parameters/WorkerProtocolVersionHeader" }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/WorkerHeartbeatRequest" }
      responses:
        "200": { $ref: "#/components/responses/WorkerEnvelope" }
        "404": { $ref: "#/components/responses/WorkerError" }
        "503": { $ref: "#/components/responses/WorkerServiceUnavailable" }
  /worker/sessions:
    post:
      operationId: createWorkerSession
      tags: [worker-sessions]
      parameters: [{ $ref: "#/components/parameters/WorkerProtocolVersionHeader" }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "./worker-sessions-runtime.schema.json#/$defs/workerSessionCreateRequest" }
      responses:
        "200": { $ref: "#/components/responses/WorkerSessionOperation" }
        "201": { $ref: "#/components/responses/WorkerSessionOperation" }
        "409": { $ref: "#/components/responses/WorkerError" }
        "412": { $ref: "#/components/responses/WorkerError" }
        "422": { $ref: "#/components/responses/WorkerError" }
  /worker/sessions/{sessionId}/heartbeat:
    post:
      operationId: heartbeatWorkerSession
      tags: [worker-sessions]
      parameters:
        - $ref: "#/components/parameters/WorkerProtocolVersionHeader"
        - $ref: "#/components/parameters/SessionIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "./worker-sessions-runtime.schema.json#/$defs/workerSessionHeartbeatRequest" }
      responses:
        "200": { $ref: "#/components/responses/WorkerSessionOperation" }
        "404": { $ref: "#/components/responses/WorkerError" }
        "409": { $ref: "#/components/responses/WorkerError" }
  /worker/sessions/{sessionId}:
    delete:
      operationId: closeWorkerSession
      tags: [worker-sessions]
      parameters:
        - $ref: "#/components/parameters/WorkerProtocolVersionHeader"
        - $ref: "#/components/parameters/SessionIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "./worker-sessions-runtime.schema.json#/$defs/workerSessionCloseRequest" }
      responses:
        "200": { $ref: "#/components/responses/WorkerSessionOperation" }
        "404": { $ref: "#/components/responses/WorkerError" }
        "409": { $ref: "#/components/responses/WorkerError" }
  /worker/workflow-tasks/poll:
    post:
      operationId: pollWorkflowTask
      tags: [workflow-tasks]
      parameters: [{ $ref: "#/components/parameters/WorkerProtocolVersionHeader" }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/WorkflowTaskPollRequest" }
      responses:
        "200":
          description: A claimed workflow task, an empty long-poll result, or a draining-worker response.
          headers: { X-Durable-Workflow-Protocol-Version: { schema: { $ref: "#/components/schemas/AdvertisedWorkerProtocolVersion" } } }
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowTaskPollResponse"
        "400": { $ref: "#/components/responses/WorkerError" }
        "429": { $ref: "#/components/responses/WorkerPollBackpressure" }
        "409": { $ref: "#/components/responses/WorkflowTaskPollConflict" }
        "422": { $ref: "#/components/responses/WorkerError" }
        "503": { $ref: "#/components/responses/WorkerServiceUnavailable" }
  /worker/workflow-tasks/{taskId}/history:
    post:
      operationId: getWorkflowTaskHistoryPage
      tags: [workflow-tasks]
      parameters:
        - $ref: "#/components/parameters/WorkerProtocolVersionHeader"
        - $ref: "#/components/parameters/TaskIdPath"
      requestBody:
        required: false
        content:
          application/json:
            schema: { $ref: "#/components/schemas/HistoryPageRequest" }
      responses:
        "200": { $ref: "#/components/responses/WorkerEnvelope" }
        "404": { $ref: "#/components/responses/WorkerError" }
        "409": { $ref: "#/components/responses/WorkerError" }
  /worker/workflow-tasks/{taskId}/heartbeat:
    post:
      operationId: heartbeatWorkflowTask
      tags: [workflow-tasks]
      parameters:
        - $ref: "#/components/parameters/WorkerProtocolVersionHeader"
        - $ref: "#/components/parameters/TaskIdPath"
      requestBody:
        required: false
        content:
          application/json:
            schema: { $ref: "#/components/schemas/TaskHeartbeatRequest" }
      responses:
        "200": { $ref: "#/components/responses/WorkerEnvelope" }
        "404": { $ref: "#/components/responses/WorkerError" }
        "409": { $ref: "#/components/responses/WorkerError" }
        "503": { $ref: "#/components/responses/WorkerServiceUnavailable" }
  /worker/workflow-tasks/{taskId}/complete:
    post:
      operationId: completeWorkflowTask
      tags: [workflow-tasks]
      parameters:
        - $ref: "#/components/parameters/WorkerProtocolVersionHeader"
        - $ref: "#/components/parameters/TaskIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/WorkflowTaskCompleteRequest" }
      responses:
        "200": { $ref: "#/components/responses/WorkflowTaskCompletion" }
        "409": { $ref: "#/components/responses/WorkflowTaskCompletionFailure" }
        "422": { $ref: "#/components/responses/WorkerError" }
  /worker/workflow-tasks/{taskId}/fail:
    post:
      operationId: failWorkflowTask
      tags: [workflow-tasks]
      parameters:
        - $ref: "#/components/parameters/WorkerProtocolVersionHeader"
        - $ref: "#/components/parameters/TaskIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/TaskFailureRequest" }
      responses:
        "200": { $ref: "#/components/responses/WorkerEnvelope" }
        "409": { $ref: "#/components/responses/WorkerError" }
  /worker/update-validation-tasks/poll:
    post:
      operationId: pollUpdateValidationTask
      tags: [update-validation-tasks]
      parameters: [{ $ref: "#/components/parameters/WorkerProtocolVersionHeader" }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/UpdateValidationTaskPollRequest" }
      responses:
        "200":
          description: A claimed update-validation task or an empty long-poll result.
          headers: { X-Durable-Workflow-Protocol-Version: { schema: { $ref: "#/components/schemas/AdvertisedWorkerProtocolVersion" } } }
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/UpdateValidationTaskClaim"
                  - $ref: "#/components/schemas/EmptyPoll"
        "400": { $ref: "#/components/responses/WorkerError" }
        "409": { $ref: "#/components/responses/WorkerError" }
        "429": { $ref: "#/components/responses/WorkerPollBackpressure" }
        "422": { $ref: "#/components/responses/WorkerError" }
        "503": { $ref: "#/components/responses/WorkerServiceUnavailable" }
  /worker/update-validation-tasks/{taskId}/approve:
    post:
      operationId: approveUpdateValidationTask
      tags: [update-validation-tasks]
      parameters:
        - $ref: "#/components/parameters/WorkerProtocolVersionHeader"
        - $ref: "#/components/parameters/TaskIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/UpdateValidationTaskCompletionRequest" }
      responses:
        "200": { $ref: "#/components/responses/UpdateValidationTaskCompletion" }
        "404": { $ref: "#/components/responses/UpdateValidationTaskCompletionFailure" }
        "409": { $ref: "#/components/responses/UpdateValidationTaskCompletionFailure" }
        "422": { $ref: "#/components/responses/WorkerError" }
  /worker/update-validation-tasks/{taskId}/reject:
    post:
      operationId: rejectUpdateValidationTask
      tags: [update-validation-tasks]
      parameters:
        - $ref: "#/components/parameters/WorkerProtocolVersionHeader"
        - $ref: "#/components/parameters/TaskIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/UpdateValidationTaskRejectionRequest" }
      responses:
        "200": { $ref: "#/components/responses/UpdateValidationTaskCompletion" }
        "404": { $ref: "#/components/responses/UpdateValidationTaskCompletionFailure" }
        "409": { $ref: "#/components/responses/UpdateValidationTaskCompletionFailure" }
        "422": { $ref: "#/components/responses/WorkerError" }
  /worker/query-tasks/poll:
    post:
      operationId: pollQueryTask
      tags: [query-tasks]
      parameters: [{ $ref: "#/components/parameters/WorkerProtocolVersionHeader" }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/PollRequest" }
      responses:
        "200": { $ref: "#/components/responses/WorkerEnvelope" }
        "429": { $ref: "#/components/responses/WorkerPollBackpressure" }
        "503": { $ref: "#/components/responses/WorkerServiceUnavailable" }
  /worker/query-tasks/{queryTaskId}/complete:
    post:
      operationId: completeQueryTask
      tags: [query-tasks]
      parameters:
        - $ref: "#/components/parameters/WorkerProtocolVersionHeader"
        - name: queryTaskId
          in: path
          required: true
          schema: { type: string, minLength: 1 }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/QueryTaskCompleteRequest" }
      responses:
        "200": { $ref: "#/components/responses/WorkerEnvelope" }
        "409": { $ref: "#/components/responses/WorkerError" }
  /worker/query-tasks/{queryTaskId}/fail:
    post:
      operationId: failQueryTask
      tags: [query-tasks]
      parameters:
        - $ref: "#/components/parameters/WorkerProtocolVersionHeader"
        - name: queryTaskId
          in: path
          required: true
          schema: { type: string, minLength: 1 }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/TaskFailureRequest" }
      responses:
        "200": { $ref: "#/components/responses/WorkerEnvelope" }
        "409": { $ref: "#/components/responses/WorkerError" }
  /worker/activity-tasks/poll:
    post:
      operationId: pollActivityTask
      tags: [activity-tasks]
      parameters: [{ $ref: "#/components/parameters/WorkerProtocolVersionHeader" }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/PollRequest" }
      responses:
        "200":
          description: A claimed activity task, an empty long-poll result, or a draining-worker response.
          headers: { X-Durable-Workflow-Protocol-Version: { schema: { $ref: "#/components/schemas/AdvertisedWorkerProtocolVersion" } } }
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/ActivityTaskClaim"
                  - $ref: "#/components/schemas/EmptyPoll"
                  - $ref: "#/components/schemas/DrainingPoll"
        "429": { $ref: "#/components/responses/WorkerPollBackpressure" }
        "503": { $ref: "#/components/responses/WorkerServiceUnavailable" }
  /worker/activity-tasks/{taskId}/heartbeat:
    post:
      operationId: heartbeatActivityTask
      tags: [activity-tasks]
      parameters:
        - $ref: "#/components/parameters/WorkerProtocolVersionHeader"
        - $ref: "#/components/parameters/TaskIdPath"
      requestBody:
        required: false
        content:
          application/json:
            schema: { $ref: "#/components/schemas/TaskHeartbeatRequest" }
      responses:
        "200": { $ref: "#/components/responses/WorkerEnvelope" }
        "409": { $ref: "#/components/responses/WorkerError" }
  /worker/activity-tasks/{taskId}/complete:
    post:
      operationId: completeActivityTask
      tags: [activity-tasks]
      description: >
        An unknown backend outcome returns a retryable 503 fenced by task_id,
        activity_attempt_id and lease_owner. Retry the same result without
        rerunning the activity. A committed first attempt can return 409
        stale_attempt with completed activity, attempt and task statuses.
      parameters:
        - $ref: "#/components/parameters/WorkerProtocolVersionHeader"
        - $ref: "#/components/parameters/TaskIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/ActivityTaskCompleteRequest" }
      responses:
        "200": { $ref: "#/components/responses/WorkerEnvelope" }
        "409": { $ref: "#/components/responses/WorkerError" }
        "503": { $ref: "#/components/responses/WorkerServiceUnavailable" }
  /worker/activity-tasks/{taskId}/fail:
    post:
      operationId: failActivityTask
      tags: [activity-tasks]
      parameters:
        - $ref: "#/components/parameters/WorkerProtocolVersionHeader"
        - $ref: "#/components/parameters/TaskIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/TaskFailureRequest" }
      responses:
        "200": { $ref: "#/components/responses/WorkerEnvelope" }
        "409": { $ref: "#/components/responses/WorkerError" }
components:
  securitySchemes:
    durableWorkerAuth:
      type: apiKey
      in: header
      name: Authorization
  parameters:
    WorkerProtocolVersionHeader:
      name: X-Durable-Workflow-Protocol-Version
      in: header
      required: true
      description: >
        Worker-selected protocol version. The default server advertises 1.19
        and accepts same-major versions whose minor is no newer than 19.
        Missing, malformed, different-major, and ahead-of-server values fail closed.
      schema: { $ref: "#/components/schemas/AcceptedWorkerProtocolRequestVersion" }
    TaskIdPath:
      name: taskId
      in: path
      required: true
      schema: { type: string, minLength: 1 }
    SessionIdPath:
      name: sessionId
      in: path
      required: true
      schema: { type: string, minLength: 1, maxLength: 255 }
    WorkerIdPath:
      name: workerId
      in: path
      required: true
      description: Worker registration identity in the resolved namespace.
      schema: { type: string, minLength: 1, maxLength: 255 }
  responses:
    WorkerEnvelope:
      description: Worker-protocol response envelope.
      headers:
        X-Durable-Workflow-Protocol-Version:
          schema: { $ref: "#/components/schemas/AdvertisedWorkerProtocolVersion" }
      content:
        application/json:
          schema: { $ref: "#/components/schemas/WorkerEnvelope" }
    WorkerError:
      description: Machine-readable worker-protocol error envelope.
      headers:
        X-Durable-Workflow-Protocol-Version:
          schema: { $ref: "#/components/schemas/AdvertisedWorkerProtocolVersion" }
      content:
        application/json:
          schema: { $ref: "#/components/schemas/WorkerError" }
    WorkerServiceUnavailable:
      description: >
        Temporary database connection loss returns backend_unavailable with an
        unknown operation outcome. Retry with bounded backoff and the identical
        worker, queue and poll_request_id; task=null does not prove that no task
        was claimed. Registration and worker heartbeat likewise do not acknowledge or
        reject an operation whose result is unknown. A workflow-task heartbeat
        carries task_id, lease_owner, and workflow_task_attempt so a worker can
        retry the same lease fence; a later 409 still revokes that lease. An
        activity completion carries task_id, activity_attempt_id and lease_owner
        to retry the same immutable result. Other
        503 errors retain their own contracts and are not automatically retryable. Optional
        storage admission returns storage_pressure or storage_admission_unavailable
        before admitting a request or a new poll claim. Retain the poll ID on
        retry: refusal of this attempt does not describe an earlier outcome.
      headers:
        X-Durable-Workflow-Protocol-Version:
          schema: { $ref: "#/components/schemas/AdvertisedWorkerProtocolVersion" }
        Retry-After:
          schema: { type: integer, minimum: 1 }
      content:
        application/json:
          schema:
            anyOf:
              - $ref: "#/components/schemas/WorkerBackendUnavailable"
              - $ref: "#/components/schemas/WorkerStorageAdmissionRefusal"
              - $ref: "#/components/schemas/WorkerError"
    WorkerPollBackpressure:
      description: The node has no capacity for another held long poll; retry after the advertised delay.
      headers:
        X-Durable-Workflow-Protocol-Version:
          schema: { $ref: "#/components/schemas/AdvertisedWorkerProtocolVersion" }
        Retry-After:
          schema: { type: integer, minimum: 1 }
      content:
        application/json:
          schema: { $ref: "#/components/schemas/WorkerPollBackpressure" }
    WorkerRegistrationEnvelope:
      description: Accepted worker registration and its authoritative capabilities.
      headers:
        X-Durable-Workflow-Protocol-Version:
          schema: { $ref: "#/components/schemas/AdvertisedWorkerProtocolVersion" }
      content:
        application/json:
          schema: { $ref: "#/components/schemas/WorkerRegistrationEnvelope" }
    WorkerRegistrationFailure:
      description: A worker registration boundary rejection.
      headers:
        X-Durable-Workflow-Protocol-Version:
          schema: { $ref: "#/components/schemas/AdvertisedWorkerProtocolVersion" }
      content:
        application/json:
          schema:
            anyOf:
              - $ref: "#/components/schemas/WorkflowMetadataCapabilityFailure"
              - $ref: "#/components/schemas/PortableWorkerAffinityFailure"
              - $ref: "#/components/schemas/WorkerError"
    WorkflowMetadataCapabilityFailure:
      description: A metadata capability registration or completion boundary rejection.
      headers:
        X-Durable-Workflow-Protocol-Version:
          schema: { $ref: "#/components/schemas/AdvertisedWorkerProtocolVersion" }
      content:
        application/json:
          schema: { $ref: "#/components/schemas/WorkflowMetadataCapabilityFailure" }
    WorkflowTaskCompletion:
      description: A fenced workflow-task completion result.
      headers:
        X-Durable-Workflow-Protocol-Version:
          schema: { $ref: "#/components/schemas/AdvertisedWorkerProtocolVersion" }
      content:
        application/json:
          schema: { $ref: "#/components/schemas/WorkflowTaskCompletionResult" }
    WorkflowTaskCompletionFailure:
      description: A workflow-task completion boundary rejection.
      headers:
        X-Durable-Workflow-Protocol-Version:
          schema: { $ref: "#/components/schemas/AdvertisedWorkerProtocolVersion" }
      content:
        application/json:
          schema:
            anyOf:
              - $ref: "#/components/schemas/WorkflowMetadataCapabilityFailure"
              - $ref: "#/components/schemas/ConditionWaitOccurrenceIdentityFailure"
              - $ref: "#/components/schemas/PortableWorkerAffinityFailure"
              - $ref: "#/components/schemas/WorkerError"
    WorkflowTaskPollConflict:
      description: The poll request is unsupported, its idempotency identity conflicts with a previously bound task-kind set, or a cached task cannot be replayed within the requested task-kind set.
      headers:
        X-Durable-Workflow-Protocol-Version:
          schema: { $ref: "#/components/schemas/AdvertisedWorkerProtocolVersion" }
      content:
        application/json:
          schema:
            oneOf:
              - $ref: "#/components/schemas/PollRequestTaskKindsConflict"
              - $ref: "#/components/schemas/CachedPollTaskKindConflict"
              - $ref: "#/components/schemas/UpdateValidationCapabilityConflict"
    UpdateValidationTaskCompletion:
      description: A fenced update-validation task approval or rejection result.
      headers:
        X-Durable-Workflow-Protocol-Version:
          schema: { $ref: "#/components/schemas/AdvertisedWorkerProtocolVersion" }
      content:
        application/json:
          schema: { $ref: "#/components/schemas/UpdateValidationTaskCompletionResult" }
    UpdateValidationTaskCompletionFailure:
      description: A typed update-validation completion fence rejection.
      headers:
        X-Durable-Workflow-Protocol-Version:
          schema: { $ref: "#/components/schemas/AdvertisedWorkerProtocolVersion" }
      content:
        application/json:
          schema: { $ref: "#/components/schemas/UpdateValidationTaskCompletionFailure" }
    WorkerSessionOperation:
      description: Worker-session lifecycle admission or renewal result.
      headers:
        X-Durable-Workflow-Protocol-Version:
          schema: { $ref: "#/components/schemas/AdvertisedWorkerProtocolVersion" }
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/WorkerEnvelope"
              - $ref: "./worker-sessions-runtime.schema.json#/$defs/workerSessionOperationResult"
    WorkerDeregistrationEnvelope:
      description: Graceful worker-deregistration result in the WorkerProtocol success envelope.
      headers:
        X-Durable-Workflow-Protocol-Version:
          schema: { $ref: "#/components/schemas/AdvertisedWorkerProtocolVersion" }
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/WorkerEnvelope"
              - $ref: "#/components/schemas/WorkerDeregistrationResult"
  schemas:
    AcceptedWorkerProtocolRequestVersion:
      type: string
      enum: ["1.0", "1.1", "1.2", "1.3", "1.4", "1.5", "1.6", "1.7", "1.8", "1.9", "1.10", "1.11", "1.12", "1.13", "1.14", "1.15", "1.16", "1.17", "1.18", "1.19"]
      description: >
        Request versions accepted by a server using the default advertised
        version 1.19. If deployment configuration changes the advertised
        version to 1.N, the accepted set is 1.0 through 1.N.
    AdvertisedWorkerProtocolVersion:
      type: string
      const: "1.19"
      description: Default worker protocol version advertised by responses implementing the Durable Workflow 2.0 protocol contract.
    WorkerEnvelope:
      type: object
      additionalProperties: true
      required: [protocol_version, server_capabilities]
      properties:
        protocol_version: { $ref: "#/components/schemas/AdvertisedWorkerProtocolVersion" }
        server_capabilities: { $ref: "#/components/schemas/WorkerServerCapabilities" }
    WorkerError:
      type: object
      additionalProperties: true
      required: [protocol_version, server_capabilities]
      properties:
        protocol_version: { $ref: "#/components/schemas/AdvertisedWorkerProtocolVersion" }
        error: { type: string }
        reason: { type: [string, "null"] }
        remediation: { type: [string, "null"] }
        server_capabilities: { $ref: "#/components/schemas/WorkerServerCapabilities" }
    WorkerStorageAdmissionRefusal:
      allOf:
        - $ref: "#/components/schemas/WorkerError"
        - type: object
          required: [reason, storage_state, retryable, retry_after_seconds]
          properties:
            reason: { type: string, enum: [storage_pressure, storage_admission_unavailable] }
            storage_state: { type: string, enum: [draining, fenced] }
            request_admitted:
              type: boolean
              const: false
              description: Present only when admission refused before entering the handler. Does not describe previous requests.
            retryable: { type: boolean, const: true }
            retry_after_seconds: { type: integer, minimum: 1 }
          if:
            required: [poll_status]
          then:
            required: [task, claim_admitted, poll_request_id, retry_same_poll_request_id]
            properties:
              task: { type: "null" }
              claim_admitted: { type: boolean, const: false }
              poll_status: { type: string, enum: [storage_pressure, storage_admission_unavailable] }
              poll_request_id: { type: [string, "null"], minLength: 1, maxLength: 255 }
              retry_same_poll_request_id: { type: boolean, const: true }
    WorkerBackendUnavailable:
      allOf:
        - $ref: "#/components/schemas/WorkerError"
        - type: object
          required: [reason, operation, outcome, worker_id, task_queue, retryable, retry_after_seconds]
          properties:
            reason: { type: string, const: backend_unavailable }
            operation:
              type: string
              enum: [register_worker, heartbeat_worker, heartbeat_workflow_task, complete_workflow_task, complete_activity_task, poll_workflow_task, poll_activity_task, poll_query_task, poll_update_validation_task]
            outcome: { type: string, const: unknown }
            worker_id: { type: [string, "null"], minLength: 1, maxLength: 255 }
            task_queue: { type: [string, "null"], minLength: 1, maxLength: 255 }
            task_id: { type: [string, "null"], minLength: 1, maxLength: 255 }
            lease_owner: { type: [string, "null"], minLength: 1, maxLength: 255 }
            workflow_task_attempt: { type: [integer, "null"], minimum: 1 }
            activity_attempt_id: { type: [string, "null"], minLength: 1, maxLength: 255 }
            retryable: { type: boolean }
            retry_after_seconds: { type: integer, minimum: 1 }
          if:
            properties:
              operation: { enum: [poll_workflow_task, poll_activity_task, poll_query_task, poll_update_validation_task] }
          then:
            required: [task, poll_status, poll_request_id, retry_same_poll_request_id]
            properties:
              task: { type: "null" }
              poll_status: { type: string, const: backend_unavailable }
              poll_request_id: { type: [string, "null"], minLength: 1, maxLength: 255 }
              retry_same_poll_request_id: { type: boolean, const: true }
          else:
            if:
              properties:
                operation: { enum: [heartbeat_workflow_task, complete_workflow_task] }
            then:
              required: [task_id, lease_owner, workflow_task_attempt]
            else:
              if:
                properties:
                  operation: { const: complete_activity_task }
              then:
                required: [task_id, lease_owner, activity_attempt_id]
    WorkerPollBackpressure:
      allOf:
        - $ref: "#/components/schemas/WorkerError"
        - type: object
          required: [task, poll_status, error, reason, namespace, task_queue, task_kind, wait_pool, retry_after_seconds, retryable]
          properties:
            task: { type: "null" }
            poll_status: { type: string, const: long_poll_capacity_exhausted }
            reason: { type: string, const: long_poll_capacity_exhausted }
            namespace: { type: string, minLength: 1 }
            task_queue: { type: string, minLength: 1 }
            task_kind: { type: string, enum: [workflow_task, activity_task, query_task, update_validation_task] }
            wait_pool: { type: string, enum: [worker, query] }
            retry_after_seconds: { type: integer, minimum: 1 }
            retryable: { type: boolean, const: true }
    WorkerRegistrationEnvelope:
      allOf:
        - $ref: "#/components/schemas/WorkerEnvelope"
        - type: object
          required: [worker_id, registered, namespace, task_queue, runtime, capabilities, capability_manifest, status, heartbeat_interval_seconds]
          properties:
            worker_id: { type: string, minLength: 1 }
            registered: { type: boolean, const: true }
            namespace: { type: string, minLength: 1 }
            task_queue: { type: string, minLength: 1 }
            runtime: { type: string, enum: [php, python, rust, typescript, go, java, external] }
            build_id: { type: [string, "null"] }
            capabilities:
              type: array
              uniqueItems: true
              items: { type: string }
            capability_manifest:
              $ref: "#/components/schemas/PortableWorkerCapabilityManifest"
            status: { type: string, minLength: 1 }
            heartbeat_interval_seconds: { type: integer, minimum: 1 }
    WorkflowMetadataCapabilityFailure:
      allOf:
        - $ref: "#/components/schemas/WorkerError"
        - type: object
          required: [reason, capability, minimum_protocol_version]
          properties:
            reason:
              type: string
              enum: [workflow_metadata_capability_protocol_mismatch, workflow_metadata_capability_not_advertised]
            capability:
              type: string
              enum: [memo_upserts, typed_search_attributes]
            minimum_protocol_version: { type: string, enum: ["1.14", "1.16"] }
          oneOf:
            - required: [registered, requested_version]
              properties:
                registered: { type: boolean, const: false }
                requested_version: { type: string }
            - required: [task_id, workflow_task_attempt, outcome, recorded, command_type]
              properties:
                task_id: { type: string, minLength: 1 }
                workflow_task_attempt: { type: integer, minimum: 1 }
                outcome: { type: string, const: rejected }
                recorded: { type: boolean, const: false }
                command_type: { type: string, enum: [upsert_memo, upsert_search_attributes] }
    ConditionWaitOccurrenceIdentityFailure:
      allOf:
        - $ref: "#/components/schemas/WorkerError"
        - type: object
          required: [task_id, workflow_task_attempt, outcome, recorded, reason, requested_version, minimum_protocol_version, command_type, command_field]
          properties:
            task_id: { type: string, minLength: 1 }
            workflow_task_attempt: { type: integer, minimum: 1 }
            outcome: { type: string, const: rejected }
            recorded: { type: boolean, const: false }
            reason: { type: string, const: condition_wait_occurrence_identity_unavailable }
            requested_version: { type: string }
            minimum_protocol_version: { type: string, const: "1.17" }
            command_type: { type: string, const: open_condition_wait }
            command_field: { type: string, const: condition_wait_occurrence_id }
    PortableWorkerAffinityFailure:
      allOf:
        - $ref: "#/components/schemas/WorkerError"
        - type: object
          required: [reason, capability, minimum_protocol_version]
          properties:
            reason:
              type: string
              enum:
                - worker_capability_manifest_mismatch
                - worker_capability_protocol_floor_mismatch
                - portable_worker_affinity_protocol_floor_unavailable
                - worker_capability_not_supported
                - sticky_cache_identity_mismatch
            capability:
              type: string
              enum: [local_activities, worker_sessions, sticky_execution]
            requested_version: { type: [string, "null"] }
            minimum_protocol_version: { type: string, const: "1.18" }
          oneOf:
            - required: [registered]
              properties:
                registered: { type: boolean, const: false }
            - required: [task_id, workflow_task_attempt, outcome, recorded]
              properties:
                task_id: { type: string, minLength: 1 }
                workflow_task_attempt: { type: integer, minimum: 1 }
                outcome: { type: string, const: rejected }
                recorded: { type: boolean, const: false }
    WorkerServerCapabilities:
      type: object
      additionalProperties: true
      required: [supported_workflow_task_commands, workflow_task_poll_request_idempotency, workflow_memo_updates, message_streams, typed_search_attributes, condition_wait_occurrence_identity, update_validation_tasks, synchronous_update_validation, local_activities, sticky_execution]
      properties:
        supported_workflow_task_commands:
          type: array
          uniqueItems: true
          items: { type: string }
        workflow_task_poll_request_idempotency: { type: boolean, const: true }
        workflow_memo_updates:
          $ref: "#/components/schemas/WorkflowMemoUpdateCapability"
        message_streams:
          $ref: "#/components/schemas/MessageStreamsCapability"
        typed_search_attributes:
          $ref: "#/components/schemas/TypedSearchAttributesCapability"
        condition_wait_occurrence_identity:
          $ref: "#/components/schemas/ConditionWaitOccurrenceIdentityCapability"
        update_validation_tasks: { type: boolean, const: true }
        synchronous_update_validation:
          $ref: "#/components/schemas/SynchronousUpdateValidationCapability"
        worker_session_verbs:
          type: array
          items: { type: string, enum: [create, heartbeat, close] }
          minItems: 3
        worker_sessions:
          $ref: "./worker-sessions-runtime.schema.json#/$defs/workerSessionRuntimeContract"
        local_activities:
          $ref: "#/components/schemas/LocalActivityCapability"
        sticky_execution:
          $ref: "#/components/schemas/StickyExecutionCapability"
    PortableWorkerCapabilityManifest:
      type: object
      additionalProperties: true
      required: [local_activities, worker_sessions, sticky_execution]
      properties:
        local_activities: { $ref: "#/components/schemas/PortableWorkerCapabilityDeclaration" }
        worker_sessions: { $ref: "#/components/schemas/PortableWorkerCapabilityDeclaration" }
        sticky_execution: { $ref: "#/components/schemas/PortableWorkerCapabilityDeclaration" }
    PortableWorkerCapabilityDeclaration:
      type: object
      additionalProperties: false
      required: [supported, minimum_protocol_version]
      properties:
        supported: { type: boolean }
        minimum_protocol_version: { type: string, pattern: "^1\\.[0-9]+$" }
        implementation: { type: string, minLength: 1, maxLength: 255 }
        reason: { type: string, minLength: 1, maxLength: 255 }
    LocalActivityCapability:
      type: object
      additionalProperties: true
      required: [schema, version, supported, worker_capability, minimum_worker_protocol_version, execution, retry, timeouts, visibility]
      properties:
        schema: { type: string, const: durable-workflow.v2.local-activity.contract }
        version: { type: integer, const: 1 }
        supported: { type: boolean }
        worker_capability: { type: string, const: local_activities }
        minimum_worker_protocol_version: { type: string, const: "1.18" }
        execution: { type: object, additionalProperties: true }
        retry: { type: object, additionalProperties: true }
        timeouts: { type: object, additionalProperties: true }
        visibility: { type: object, additionalProperties: true }
    StickyExecutionCapability:
      type: object
      additionalProperties: true
      required: [feature, supported, worker_capability, minimum_worker_protocol_version, cache_key_fields, correctness_fallback, metrics]
      properties:
        feature: { type: string, const: sticky_execution }
        supported: { type: boolean }
        worker_capability: { type: string, const: sticky_execution }
        minimum_worker_protocol_version: { type: string, const: "1.18" }
        cache_key_fields:
          type: array
          prefixItems: [{ const: workflow_id }, { const: run_id }, { const: build_id }]
          minItems: 3
          maxItems: 3
        correctness_fallback: { type: string, const: cold_replay }
        metrics:
          type: array
          uniqueItems: true
          items: { type: string, enum: [hit, miss, eviction, forced_cold_replay] }
    MessageStreamsCapability:
      type: object
      additionalProperties: true
      required: [schema, version, capability_flag, minimum_worker_protocol_version, supported]
      properties:
        schema: { type: string, const: durable-workflow.v2.message-streams.contract }
        version: { type: integer, const: 1 }
        capability_flag: { type: string, const: message_streams }
        minimum_worker_protocol_version: { type: string, const: "1.15" }
        supported: { type: boolean }
    WorkflowMemoUpdateCapability:
      type: object
      additionalProperties: true
      required: [supported, type, minimum_protocol_version, worker_capability, required_fields, entries, merge, history, idempotency, continue_as_new, external_payloads]
      properties:
        supported: { type: boolean }
        type: { type: string, const: upsert_memo }
        minimum_protocol_version: { type: string, const: "1.14" }
        worker_capability: { type: string, const: memo_upserts }
        required_fields:
          type: array
          prefixItems: [{ const: type }, { const: entries }]
          minItems: 2
          maxItems: 2
        entries: { type: object, additionalProperties: true }
        merge: { type: object, additionalProperties: true }
        history: { type: object, additionalProperties: true }
        idempotency: { type: object, additionalProperties: true }
        continue_as_new: { type: string, const: "merged memo is inherited before commands on the continued run" }
        external_payloads: { type: object, additionalProperties: true }
    MemoEntriesPayloadEnvelope:
      oneOf:
        - $ref: "#/components/schemas/InlineMemoEntriesPayloadEnvelope"
        - $ref: "./external-payload-transport.openapi.yaml#/components/schemas/RuntimeExternalPayloadEnvelope"
    InlineMemoEntriesPayloadEnvelope:
      type: object
      additionalProperties: false
      required: [codec, blob]
      properties:
        codec: { type: string, const: avro }
        blob: { type: string, contentEncoding: base64 }
    TypedSearchAttributesCapability:
      type: object
      additionalProperties: true
      required: [supported, minimum_worker_protocol_version, worker_capability, canonical_types, command_field, history_field, legacy_history_rule]
      properties:
        supported: { type: boolean }
        minimum_worker_protocol_version: { type: string, const: "1.16" }
        worker_capability: { type: string, const: typed_search_attributes }
        canonical_types:
          type: array
          uniqueItems: true
          minItems: 7
          maxItems: 7
          items: { $ref: "#/components/schemas/SearchAttributeType" }
        command_field: { type: string, const: attribute_types }
        history_field: { type: string, const: attribute_types }
        legacy_history_rule: { type: string, const: absent_metadata_is_unknown_type_identity }
    ConditionWaitOccurrenceIdentityCapability:
      type: object
      additionalProperties: true
      required: [supported, minimum_worker_protocol_version, command_type, command_field, history_field, history_events, history_routing]
      properties:
        supported: { type: boolean, const: true }
        minimum_worker_protocol_version: { type: string, const: "1.17" }
        command_type: { type: string, const: open_condition_wait }
        command_field: { type: string, const: condition_wait_occurrence_id }
        history_field: { type: string, const: condition_wait_occurrence_id }
        history_events:
          type: array
          uniqueItems: true
          minItems: 6
          maxItems: 6
          items: { type: string, enum: [ConditionWaitOpened, ConditionWaitSatisfied, ConditionWaitTimedOut, TimerScheduled, TimerFired, TimerCancelled] }
        history_routing: { type: string, const: requires_minimum_worker_protocol_version }
    WorkerRegistrationRequest:
      type: object
      additionalProperties: true
      required: [task_queue, runtime, capability_manifest]
      properties:
        worker_id: { type: [string, "null"], minLength: 1 }
        build_id: { type: [string, "null"] }
        task_queue: { type: string, minLength: 1 }
        runtime: { type: string, enum: [php, python, rust, typescript, go, java, external] }
        supported_workflow_types: { type: array, items: { type: string } }
        supported_activity_types: { type: array, items: { type: string } }
        workflow_definition_fingerprints: { type: object, additionalProperties: { type: string } }
        capabilities:
          type: array
          uniqueItems: true
          items: { type: string }
          x-durable-workflow-version-gated-values:
            memo_upserts: "1.14"
            message_streams: "1.15"
            typed_search_attributes: "1.16"
            local_activities: "1.18"
            worker_sessions: "1.18"
            sticky_execution: "1.18"
        capability_manifest:
          $ref: "#/components/schemas/PortableWorkerCapabilityManifest"
    WorkerHeartbeatRequest:
      type: object
      additionalProperties: true
      required: [worker_id]
      properties:
        worker_id: { type: string, minLength: 1 }
        task_queues: { type: array, items: { type: string } }
        active_slots: { type: integer, minimum: 0 }
    WorkerDeregistrationResult:
      type: object
      additionalProperties: true
      required: [worker_id, outcome, recovered_workflow_task_count]
      properties:
        worker_id: { type: string, minLength: 1 }
        outcome: { type: string, const: deregistered }
        recovered_workflow_task_count: { type: integer, minimum: 0 }
    PollRequest:
      type: object
      additionalProperties: true
      required: [worker_id, task_queues]
      properties:
        worker_id: { type: string, minLength: 1 }
        task_queues: { type: array, minItems: 1, items: { type: string, minLength: 1 } }
        build_id: { type: [string, "null"] }
        poll_timeout_seconds: { type: integer, minimum: 0 }
    WorkflowTaskPollRequest:
      type: object
      additionalProperties: true
      required: [worker_id, task_queue]
      properties:
        worker_id: { type: string, minLength: 1 }
        task_queue: { type: string, minLength: 1 }
        build_id: { type: [string, "null"] }
        poll_request_id:
          type: [string, "null"]
          minLength: 1
          maxLength: 255
          description: Idempotency identity bound to the normalized task_kinds set for the binding TTL.
        timeout_seconds: { type: integer, minimum: 0, maximum: 60 }
        history_page_size: { type: integer, minimum: 1, maximum: 1000 }
        accept_history_encoding: { type: [string, "null"], maxLength: 64 }
        task_kinds:
          type: array
          minItems: 1
          maxItems: 2
          uniqueItems: true
          default: [workflow]
          items: { type: string, enum: [workflow, update_validation] }
          description: Reordering does not change the normalized request shape; changing the effective set for a bound poll_request_id returns poll_request_task_kinds_conflict.
    UpdateValidationTaskPollRequest:
      type: object
      additionalProperties: true
      required: [worker_id, task_queue]
      properties:
        worker_id: { type: string, minLength: 1 }
        task_queue: { type: string, minLength: 1 }
        timeout_seconds: { type: integer, minimum: 0, maximum: 60 }
    WorkflowTaskPollResponse:
      oneOf:
        - $ref: "#/components/schemas/MultiplexedWorkflowTaskClaim"
        - $ref: "#/components/schemas/EmptyPoll"
        - $ref: "#/components/schemas/DrainingPoll"
      x-durable-workflow-discriminator: task.task_kind
    EmptyPoll:
      allOf:
        - $ref: "#/components/schemas/WorkerEnvelope"
        - type: object
          required: [task]
          properties:
            task: { type: "null" }
            poll_status: { type: string, enum: [timeout, empty] }
    DrainingPoll:
      allOf:
        - $ref: "#/components/schemas/WorkerEnvelope"
        - type: object
          required: [task, poll_status]
          properties:
            task: { type: "null" }
            poll_status: { type: string, const: draining }
            drain_reason: { type: [string, "null"] }
    WorkflowTaskClaim:
      allOf:
        - $ref: "#/components/schemas/WorkerEnvelope"
        - type: object
          required: [task, poll_status]
          properties:
            poll_status: { type: string, const: leased }
            task:
              $ref: "#/components/schemas/WorkflowTask"
    MultiplexedWorkflowTaskClaim:
      allOf:
        - $ref: "#/components/schemas/WorkerEnvelope"
        - type: object
          required: [task, poll_status]
          properties:
            poll_status: { type: string, const: leased }
            task:
              $ref: "#/components/schemas/MultiplexedWorkflowTask"
    UpdateValidationTaskClaim:
      allOf:
        - $ref: "#/components/schemas/WorkerEnvelope"
        - type: object
          required: [task, poll_status]
          properties:
            poll_status: { type: string, const: leased }
            task:
              $ref: "#/components/schemas/UpdateValidationTask"
    MultiplexedWorkflowTask:
      oneOf:
        - $ref: "#/components/schemas/WorkflowTask"
        - $ref: "#/components/schemas/UpdateValidationTask"
      discriminator:
        propertyName: task_kind
        mapping:
          workflow: "#/components/schemas/WorkflowTask"
          update_validation: "#/components/schemas/UpdateValidationTask"
    WorkflowTask:
      type: object
      additionalProperties: true
      required: [task_kind, task_id, workflow_id, run_id, workflow_task_attempt, history_events, lease_owner, lease_expires_at]
      properties:
        task_kind: { type: string, const: workflow }
        task_id: { type: string, minLength: 1 }
        workflow_id: { type: string, minLength: 1 }
        run_id: { type: string, minLength: 1 }
        workflow_task_attempt: { type: integer, minimum: 1 }
        lease_owner: { type: string, minLength: 1 }
        lease_expires_at: { type: string, format: date-time }
        history_events: { type: array, items: { $ref: "#/components/schemas/WorkerHistoryEvent" } }
    WorkerHistoryEvent:
      type: object
      additionalProperties: true
      properties:
        event_type: { type: string }
        payload: { type: object, additionalProperties: true }
      allOf:
        - if:
            required: [event_type]
            properties:
              event_type: { const: SearchAttributesUpserted }
          then:
            required: [payload]
            properties:
              payload: { $ref: "#/components/schemas/SearchAttributesUpsertedHistoryPayload" }
    SearchAttributesUpsertedHistoryPayload:
      type: object
      additionalProperties: true
      required: [sequence, attributes, merged]
      properties:
        sequence: { type: integer, minimum: 0 }
        attributes: { type: object, additionalProperties: true }
        merged: { type: object, additionalProperties: true }
        attribute_types:
          $ref: "#/components/schemas/SearchAttributeTypeMap"
          description: >
            Required on newly recorded events. Absence identifies legacy history
            whose type identity is unknown; it does not prove a typed match.
    UpdateValidationTask:
      type: object
      additionalProperties: true
      required:
        - task_kind
        - update_validation_task_id
        - update_id
        - update_validation_attempt
        - workflow_id
        - run_id
        - workflow_type
        - update_name
        - update_arguments
        - payload_codec
        - task_queue
        - lease_owner
        - lease_expires_at
      properties:
        task_kind: { type: string, const: update_validation }
        update_validation_task_id: { type: string, minLength: 1 }
        update_id: { type: string, minLength: 1 }
        update_validation_attempt: { type: integer, minimum: 1 }
        workflow_id: { type: string, minLength: 1 }
        run_id: { type: string, minLength: 1 }
        workflow_type: { type: string, minLength: 1 }
        compatibility: { type: [string, "null"] }
        update_name: { type: string, minLength: 1 }
        update_arguments: { type: object, additionalProperties: true }
        payload_codec: { type: string, enum: [avro] }
        task_queue: { type: string, minLength: 1 }
        lease_owner: { type: string, minLength: 1 }
        lease_expires_at: { type: string, format: date-time }
    PollRequestTaskKindsConflict:
      allOf:
        - $ref: "#/components/schemas/WorkerError"
        - type: object
          required: [task, poll_status, reason, error, poll_request_id, requested_task_kinds, bound_task_kinds]
          properties:
            task: { type: "null" }
            poll_status: { type: string, const: conflict }
            reason: { type: string, const: poll_request_task_kinds_conflict }
            error: { type: string, minLength: 1 }
            poll_request_id: { type: string, minLength: 1, maxLength: 255 }
            requested_task_kinds:
              type: array
              minItems: 1
              maxItems: 2
              uniqueItems: true
              items: { type: string, enum: [workflow, update_validation] }
            bound_task_kinds:
              type: array
              minItems: 1
              maxItems: 2
              uniqueItems: true
              items: { type: string, enum: [workflow, update_validation] }
    CachedPollTaskKindConflict:
      allOf:
        - $ref: "#/components/schemas/WorkerError"
        - type: object
          required: [task, poll_status, reason, error, poll_request_id, requested_task_kinds, cached_task_kind, cached_task_kind_state]
          properties:
            task: { type: "null" }
            poll_status: { type: string, const: conflict }
            reason: { type: string, const: poll_cached_task_kind_conflict }
            error: { type: string, minLength: 1 }
            poll_request_id: { type: string, minLength: 1, maxLength: 255 }
            requested_task_kinds:
              type: array
              minItems: 1
              maxItems: 2
              uniqueItems: true
              items: { type: string, enum: [workflow, update_validation] }
            cached_task_kind: { type: [string, "null"], minLength: 1 }
            cached_task_kind_state:
              type: string
              enum: [legacy_missing_discriminator, unrequested_discriminator]
          oneOf:
            - properties:
                cached_task_kind: { type: "null" }
                cached_task_kind_state: { const: legacy_missing_discriminator }
            - properties:
                cached_task_kind: { type: string, minLength: 1 }
                cached_task_kind_state: { const: unrequested_discriminator }
    UpdateValidationCapabilityConflict:
      allOf:
        - $ref: "#/components/schemas/WorkerError"
        - type: object
          required: [task, poll_status, reason, error]
          properties:
            task: { type: "null" }
            poll_status: { type: string, const: unsupported }
            reason: { type: string, const: update_validation_capability_not_advertised }
            error: { type: string, minLength: 1 }
    SynchronousUpdateValidationCapability:
      type: object
      additionalProperties: true
      required: [supported, acceptance_boundary, worker_capability, workflow_contract_field, task_poll, completion]
      properties:
        supported: { type: boolean, const: true }
        minimum_protocol_version: { type: string, const: "1.13" }
        acceptance_boundary: { type: string, const: validator_approved }
        worker_capability: { type: string, const: update_validation_tasks }
        workflow_contract_field: { type: string, const: update_validators }
        task_poll:
          type: object
          additionalProperties: true
          required: [strategy, endpoint, request_field, task_kinds, default_task_kinds, response_discriminator, poll_request_id_binding, poll_request_id_conflict_reason]
          properties:
            strategy: { type: string, const: multiplexed }
            endpoint: { type: string, const: /worker/workflow-tasks/poll }
            request_field: { type: string, const: task_kinds }
            task_kinds:
              type: array
              const: [workflow, update_validation]
            default_task_kinds:
              type: array
              const: [workflow]
            response_discriminator: { type: string, const: task.task_kind }
            poll_request_id_binding: { type: string, const: normalized_task_kind_set }
            poll_request_id_conflict_reason: { type: string, const: poll_request_task_kinds_conflict }
        completion:
          type: object
          additionalProperties: true
          required: [approve_endpoint, reject_endpoint, fence_fields, typed_failure_reasons]
          properties:
            approve_endpoint: { type: string, const: "/worker/update-validation-tasks/{taskId}/approve" }
            reject_endpoint: { type: string, const: "/worker/update-validation-tasks/{taskId}/reject" }
            fence_fields:
              type: array
              const: [lease_owner, update_validation_attempt]
            typed_failure_reasons:
              type: array
              minItems: 7
              uniqueItems: true
              items:
                type: string
                enum:
                  - update_validation_task_not_found
                  - duplicate_update_validation_completion
                  - update_validation_task_not_leased
                  - update_validation_lease_owner_mismatch
                  - stale_update_validation_completion
                  - update_validation_lease_expired
                  - update_validator_worker_lost
    UpdateValidationTaskCompletionRequest:
      type: object
      additionalProperties: true
      required: [lease_owner, update_validation_attempt]
      properties:
        lease_owner: { type: string, minLength: 1 }
        update_validation_attempt: { type: integer, minimum: 1 }
    UpdateValidationTaskRejectionRequest:
      allOf:
        - $ref: "#/components/schemas/UpdateValidationTaskCompletionRequest"
        - type: object
          required: [failure]
          properties:
            failure:
              $ref: "#/components/schemas/UpdateValidationFailure"
    UpdateValidationFailure:
      type: object
      additionalProperties: true
      required: [message]
      properties:
        message: { type: string, minLength: 1 }
        reason: { type: [string, "null"] }
        type: { type: [string, "null"] }
        stack_trace: { type: [string, "null"] }
        validation_errors:
          type: object
          additionalProperties:
            type: array
            items: { type: string }
    UpdateValidationTaskCompletionResult:
      allOf:
        - $ref: "#/components/schemas/WorkerEnvelope"
        - type: object
          required: [update_validation_task_id, update_id, update_validation_attempt, outcome, status]
          properties:
            update_validation_task_id: { type: string, minLength: 1 }
            update_id: { type: string, minLength: 1 }
            update_validation_attempt: { type: integer, minimum: 1 }
            outcome: { type: string, enum: [approved, rejected, failed] }
            reason: { type: [string, "null"] }
            status: { type: integer, const: 200 }
    UpdateValidationTaskCompletionFailure:
      allOf:
        - $ref: "#/components/schemas/WorkerError"
        - type: object
          required: [update_validation_task_id, update_id, outcome, reason, error, status]
          properties:
            update_validation_task_id: { type: string, minLength: 1 }
            update_id: { type: string, minLength: 1 }
            update_validation_attempt: { type: integer, minimum: 1 }
            outcome: { type: string, const: rejected }
            reason:
              type: string
              enum:
                - update_validation_task_not_found
                - duplicate_update_validation_completion
                - update_validation_task_not_leased
                - update_validation_lease_owner_mismatch
                - stale_update_validation_completion
                - update_validation_lease_expired
                - update_validator_worker_lost
            error: { type: string, minLength: 1 }
            status: { type: integer, enum: [404, 409] }
    ActivityTaskClaim:
      allOf:
        - $ref: "#/components/schemas/WorkerEnvelope"
        - type: object
          required: [task]
          properties:
            task:
              type: object
              additionalProperties: true
              required: [task_id, activity_type, attempt]
              properties:
                task_id: { type: string }
                activity_type: { type: string }
                attempt: { type: integer, minimum: 1 }
                worker_session:
                  $ref: "./worker-sessions-runtime.schema.json#/$defs/workerSessionTaskAffinity"
    HistoryPageRequest:
      type: object
      additionalProperties: true
      properties:
        page_token: { type: [string, "null"] }
        page_size: { type: integer, minimum: 1 }
    TaskHeartbeatRequest:
      type: object
      additionalProperties: true
      properties:
        worker_id: { type: string }
        progress: true
    WorkflowTaskCompleteRequest:
      type: object
      additionalProperties: true
      required: [lease_owner, workflow_task_attempt, commands]
      properties:
        lease_owner: { type: string, minLength: 1 }
        workflow_task_attempt: { type: integer, minimum: 1 }
        commands:
          type: array
          items:
            $ref: "#/components/schemas/WorkflowCommand"
        message_stream_cursors:
          type: array
          maxItems: 100
          x-durable-workflow-minimum-protocol-version: "1.15"
          items: { $ref: "#/components/schemas/MessageStreamCursorAdvance" }
        message_stream_waits:
          type: array
          maxItems: 100
          x-durable-workflow-minimum-protocol-version: "1.15"
          items: { $ref: "#/components/schemas/MessageStreamWait" }
        sticky_cache:
          $ref: "#/components/schemas/StickyCacheClaim"
          x-durable-workflow-minimum-protocol-version: "1.18"
          x-durable-workflow-worker-capability: sticky_execution
    StickyCacheClaim:
      type: object
      additionalProperties: false
      required: [worker_id, workflow_id, run_id, build_id, ttl_seconds]
      properties:
        worker_id: { type: string, minLength: 1, maxLength: 255 }
        workflow_id: { type: string, minLength: 1, maxLength: 255 }
        run_id: { type: string, minLength: 1, maxLength: 255 }
        build_id: { type: string, minLength: 1, maxLength: 255 }
        ttl_seconds: { type: integer, minimum: 1, maximum: 3600 }
        metrics:
          $ref: "#/components/schemas/StickyCacheMetrics"
    StickyCacheMetrics:
      type: object
      additionalProperties: false
      properties:
        hit: { type: integer, minimum: 0 }
        miss: { type: integer, minimum: 0 }
        eviction: { type: integer, minimum: 0 }
        forced_cold_replay: { type: integer, minimum: 0 }
    MessageStreamCursorAdvance:
      type: object
      additionalProperties: false
      required: [stream_name, through_position]
      properties:
        stream_name: { type: string, pattern: "^[A-Za-z0-9._:-]{1,128}$" }
        through_position: { type: integer, minimum: 0 }
    MessageStreamWait:
      type: object
      additionalProperties: false
      required: [stream_name, after_position]
      properties:
        stream_name: { type: string, pattern: "^[A-Za-z0-9._:-]{1,128}$" }
        after_position: { type: integer, minimum: 0 }
    WorkflowCommand:
      type: object
      additionalProperties: true
      required: [type]
      properties:
        type: { type: string }
      allOf:
        - if:
            properties:
              type: { const: upsert_memo }
            required: [type]
          then:
            required: [entries]
            properties:
              entries: { $ref: "#/components/schemas/MemoEntriesPayloadEnvelope" }
        - if:
            properties:
              type: { const: upsert_search_attributes }
            required: [type]
          then:
            required: [attributes]
            properties:
              attributes: { type: object, additionalProperties: true, minProperties: 1 }
              attribute_types:
                $ref: "#/components/schemas/SearchAttributeTypeMap"
                x-durable-workflow-minimum-protocol-version: "1.16"
                description: >
                  Optional for value-inferred commands. When present, every key
                  must name an attribute in this command and every declaration
                  is validated without inference fallback.
        - if:
            properties:
              type: { const: open_condition_wait }
            required: [type]
          then:
            properties:
              condition_wait_occurrence_id:
                type: [string, "null"]
                x-durable-workflow-minimum-protocol-version: "1.17"
                description: SDK-authored stable identity for one logical condition-wait occurrence.
        - if:
            properties:
              type: { const: record_local_activity }
            required: [type]
          then:
            required: [activity_type, outcome, attempts]
            x-durable-workflow-minimum-protocol-version: "1.18"
            x-durable-workflow-worker-capability: local_activities
            x-durable-workflow-attempt-sequence: contiguous_one_based
            x-durable-workflow-attempt-count-limit: retry_policy.max_attempts_default_1
            x-durable-workflow-final-attempt-outcome: matches_command_outcome
            x-durable-workflow-retry-prefix-outcomes: [failed, timed_out]
            properties:
              activity_type: { type: string, minLength: 1 }
              arguments: true
              result: true
              payload_codec: { type: string, minLength: 1 }
              outcome: { type: string, enum: [completed, failed, timed_out, cancelled] }
              message: { type: string }
              exception_type: { type: [string, "null"], maxLength: 255 }
              non_retryable: { type: boolean }
              timeout_kind: { type: string, enum: [start_to_close, schedule_to_close, heartbeat] }
              attempts:
                type: array
                minItems: 1
                maxItems: 100
                x-durable-workflow-minimum-protocol-version: "1.19"
                x-durable-workflow-max-total-heartbeats: 1000
                items: { $ref: "#/components/schemas/LocalActivityAttemptReport" }
              retry_policy: { $ref: "#/components/schemas/LocalActivityRetryPolicy" }
              start_to_close_timeout: { type: integer, minimum: 1 }
              schedule_to_close_timeout: { type: integer, minimum: 1 }
              heartbeat_timeout: { type: integer, minimum: 1 }
              execution_mode: { type: string, const: local }
            allOf:
              - if:
                  properties:
                    outcome: { const: completed }
                then:
                  required: [result]
              - if:
                  properties:
                    outcome: { enum: [failed, timed_out, cancelled] }
                then:
                  required: [message]
              - if:
                  properties:
                    outcome: { const: timed_out }
                then:
                  required: [timeout_kind]
    LocalActivityAttemptReport:
      type: object
      additionalProperties: false
      x-durable-workflow-minimum-protocol-version: "1.19"
      required: [attempt_number, outcome]
      properties:
        attempt_id:
          type: string
          minLength: 1
          maxLength: 255
          description: Worker-reported attempt identity preserved separately from the Server-owned durable attempt ID.
        attempt_number: { type: integer, minimum: 1, maximum: 100 }
        outcome: { type: string, enum: [completed, failed, timed_out, cancelled] }
        duration_ms: { type: integer, minimum: 0 }
        message: { type: string }
        exception_type: { type: string, maxLength: 255 }
        non_retryable: { type: boolean }
        timeout_kind: { type: string, enum: [start_to_close, schedule_to_close, heartbeat] }
        retry_reason: { type: string, enum: [failure, timeout, cold_replay] }
        backoff_seconds: { type: integer, minimum: 0 }
        heartbeats:
          type: array
          maxItems: 1000
          items: { $ref: "#/components/schemas/LocalActivityHeartbeatReport" }
    LocalActivityHeartbeatReport:
      type: object
      additionalProperties: false
      x-durable-workflow-minimum-protocol-version: "1.19"
      required: [elapsed_ms]
      properties:
        details:
          oneOf:
            - { type: array }
            - { type: object, additionalProperties: true }
        elapsed_ms: { type: integer, minimum: 0 }
    LocalActivityRetryPolicy:
      type: object
      additionalProperties: false
      x-durable-workflow-minimum-protocol-version: "1.19"
      properties:
        max_attempts: { type: integer, minimum: 1, maximum: 100 }
        backoff_seconds:
          type: array
          maxItems: 99
          items: { type: integer, minimum: 0 }
    WorkflowTaskCompletionResult:
      allOf:
        - $ref: "#/components/schemas/WorkerEnvelope"
        - type: object
          required: [task_id, workflow_task_attempt, outcome, recorded, run_id, run_status, created_task_ids, reason]
          properties:
            task_id: { type: string, minLength: 1 }
            workflow_task_attempt: { type: integer, minimum: 1 }
            outcome: { type: string, const: completed }
            recorded: { type: boolean }
            run_id: { type: string, minLength: 1 }
            run_status: { type: [string, "null"] }
            created_task_ids: { type: array, items: { type: string } }
            reason: { type: [string, "null"] }
    SearchAttributeTypeMap:
      type: object
      additionalProperties: { $ref: "#/components/schemas/SearchAttributeType" }
      propertyNames: { pattern: "^[A-Za-z][A-Za-z0-9_]{0,127}$" }
    SearchAttributeType:
      type: string
      enum: [string, keyword, keyword_list, int, float, bool, datetime]
    QueryTaskCompleteRequest:
      type: object
      additionalProperties: true
      required: [worker_id]
      properties:
        worker_id: { type: string, minLength: 1 }
        result: true
    ActivityTaskCompleteRequest:
      type: object
      additionalProperties: true
      required: [worker_id]
      properties:
        worker_id: { type: string, minLength: 1 }
        result: true
    TaskFailureRequest:
      type: object
      additionalProperties: true
      required: [worker_id]
      properties:
        worker_id: { type: string, minLength: 1 }
        error: { type: [string, "null"] }
        exception_type: { type: [string, "null"] }
        message: { type: [string, "null"] }
        non_retryable: { type: [boolean, "null"] }