openapi: 3.1.0
info:
  title: Canonical Operation Type Source of Truth Logical Contract
  version: 0.1.0
  description: |
    Logical internal contract for converging operation identity on one canonical
    dotted `operation_type` vocabulary. It describes shared shapes for resolving
    raw values, normalizing onboarding bootstrap selections, and reading
    provider-backed operation definitions under the same platform-owned truth.
    Current-release writers must emit canonical dotted values directly. Legacy
    aliases are only valid on read-side resolution, filter matching, queued-run
    reauthorization, and onboarding draft normalization paths where
    `write_allowed` remains false.
    It is not a commitment to expose public HTTP routes.
paths:
  /logical/operation-types/resolve/{rawValue}:
    get:
      summary: Resolve a raw operation value to one canonical operation contract
      operationId: resolveOperationType
      parameters:
        - name: rawValue
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Canonical operation type resolution
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationTypeResolution'
  /logical/operation-types/filter-options:
    post:
      summary: Build canonical filter options from observed raw operation values
      operationId: buildOperationTypeFilterOptions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OperationTypeFilterOptionsRequest'
      responses:
        '200':
          description: Canonical filter options and historical query values
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationTypeFilterOptionsResponse'
  /logical/onboarding/bootstrap-operation-types/normalize:
    post:
      summary: Normalize onboarding bootstrap selections to canonical operation types
      operationId: normalizeOnboardingBootstrapOperationTypes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnboardingBootstrapNormalizationRequest'
      responses:
        '200':
          description: Canonical onboarding bootstrap selection result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingBootstrapNormalizationResponse'
  /logical/provider-operation-definitions/{operationType}:
    get:
      summary: Read provider-backed operation definition for a canonical operation type
      description: |
        Provider operation definitions are keyed by canonical dotted operation
        codes only. Supplying a legacy alias is outside the write-time/provider
        registry contract and must fail before any OperationRun is started.
      operationId: getProviderOperationDefinition
      parameters:
        - name: operationType
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Provider-backed operation definition and binding status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderOperationDefinitionResponse'
components:
  schemas:
    WriteTruthStatus:
      type: string
      enum:
        - canonical_only
        - read_side_compatibility_only
        - unknown
    AliasStatus:
      type: string
      enum:
        - canonical
        - legacy_alias
        - unknown
    CanonicalOperationType:
      type: object
      properties:
        canonical_code:
          type: string
        display_label:
          type: string
        domain_key:
          type: string
          nullable: true
        expected_duration_seconds:
          type: integer
          nullable: true
        supports_operator_explanation:
          type: boolean
        write_truth_status:
          $ref: '#/components/schemas/WriteTruthStatus'
      required:
        - canonical_code
        - display_label
        - supports_operator_explanation
        - write_truth_status
    HistoricalOperationTypeAlias:
      type: object
      properties:
        raw_value:
          type: string
        canonical_code:
          type: string
        alias_status:
          $ref: '#/components/schemas/AliasStatus'
        write_allowed:
          type: boolean
        retirement_boundary:
          type: string
          enum:
            - canonical_current_truth
            - read_side_rollout_seam
            - unknown
        retirement_note:
          type: string
          nullable: true
      required:
        - raw_value
        - canonical_code
        - alias_status
        - write_allowed
        - retirement_boundary
    OperationTypeResolution:
      type: object
      properties:
        raw_value:
          type: string
        canonical:
          $ref: '#/components/schemas/CanonicalOperationType'
        alias_status:
          $ref: '#/components/schemas/AliasStatus'
        was_legacy_alias:
          type: boolean
        allowed_query_values:
          type: array
          items:
            type: string
        aliases_considered:
          type: array
          items:
            $ref: '#/components/schemas/HistoricalOperationTypeAlias'
      required:
        - raw_value
        - canonical
        - alias_status
        - was_legacy_alias
        - allowed_query_values
        - aliases_considered
    OperationTypeFilterOption:
      type: object
      properties:
        operation_type:
          type: string
        label:
          type: string
        raw_query_values:
          type: array
          items:
            type: string
      required:
        - operation_type
        - label
        - raw_query_values
    OperationTypeFilterOptionsRequest:
      type: object
      properties:
        observed_raw_values:
          type: array
          items:
            type: string
      required:
        - observed_raw_values
    OperationTypeFilterOptionsResponse:
      type: object
      properties:
        options:
          type: array
          items:
            $ref: '#/components/schemas/OperationTypeFilterOption'
      required:
        - options
    OnboardingBootstrapNormalizationRequest:
      type: object
      properties:
        bootstrap_operation_types:
          type: array
          items:
            type: string
      required:
        - bootstrap_operation_types
    OnboardingBootstrapNormalizationResponse:
      type: object
      properties:
        canonical_operation_types:
          type: array
          items:
            type: string
        dropped_values:
          type: array
          items:
            type: string
        write_truth_status:
          $ref: '#/components/schemas/WriteTruthStatus'
      required:
        - canonical_operation_types
        - dropped_values
        - write_truth_status
    ProviderOperationDefinition:
      type: object
      properties:
        operation_type:
          type: string
        module:
          type: string
        label:
          type: string
        required_capability:
          type: string
      required:
        - operation_type
        - module
        - label
        - required_capability
    ProviderOperationBinding:
      type: object
      properties:
        provider:
          type: string
        binding_status:
          type: string
          enum:
            - active
            - unsupported
        write_truth_status:
          $ref: '#/components/schemas/WriteTruthStatus'
      required:
        - provider
        - binding_status
        - write_truth_status
    ProviderOperationDefinitionResponse:
      type: object
      properties:
        definition:
          $ref: '#/components/schemas/ProviderOperationDefinition'
        binding:
          $ref: '#/components/schemas/ProviderOperationBinding'
      required:
        - definition
        - binding
