openapi: 3.1.0
info:
  title: Provider Boundary Hardening Logical Contract
  version: 0.1.0
  description: |
    Logical internal contract for the first provider-boundary hardening slice.
    It describes shared shapes for listing seam ownership, resolving operation
    definition versus provider binding, and evaluating touched boundary changes.
    It is not a commitment to expose public HTTP routes.
paths:
  /logical/provider-boundaries/seams:
    get:
      summary: List the first-slice provider boundary seam ownership catalog
      operationId: listProviderBoundarySeams
      responses:
        '200':
          description: Boundary seam catalog
          content:
            application/json:
              schema:
                type: object
                properties:
                  seams:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProviderBoundarySeam'
                required:
                  - seams
  /logical/provider-boundaries/operations/{operationType}:
    get:
      summary: Read platform-core operation definition and current provider binding
      operationId: getProviderBoundaryOperation
      parameters:
        - name: operationType
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Operation definition and binding
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderOperationBoundaryResponse'
  /logical/provider-boundaries/evaluate:
    post:
      summary: Evaluate whether a touched change respects the declared boundary
      operationId: evaluateProviderBoundaryChange
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProviderBoundaryEvaluationRequest'
      responses:
        '200':
          description: Boundary evaluation outcome
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderBoundaryCheckResult'
components:
  schemas:
    ProviderBoundaryOwner:
      type: string
      enum:
        - provider_owned
        - platform_core
    ProviderBoundarySeam:
      type: object
      properties:
        seam_key:
          type: string
        owner:
          $ref: '#/components/schemas/ProviderBoundaryOwner'
        description:
          type: string
        implementation_paths:
          type: array
          items:
            type: string
        neutral_terms:
          type: array
          items:
            type: string
        retained_provider_semantics:
          type: array
          items:
            type: string
        follow_up_action:
          type: string
          enum:
            - none
            - document-in-feature
            - follow-up-spec
      required:
        - seam_key
        - owner
        - description
        - implementation_paths
        - neutral_terms
        - retained_provider_semantics
        - follow_up_action
    ProviderOperationDefinition:
      type: object
      properties:
        operation_type:
          type: string
        module_key:
          type: string
        label:
          type: string
        required_capability:
          type: string
      required:
        - operation_type
        - module_key
        - label
        - required_capability
    ProviderOperationBinding:
      type: object
      properties:
        operation_type:
          type: string
        provider:
          type: string
        binding_status:
          type: string
          enum:
            - active
            - unsupported
        handler_notes:
          type: string
        exception_notes:
          type: string
      required:
        - operation_type
        - provider
        - binding_status
    ProviderOperationBoundaryResponse:
      type: object
      properties:
        definition:
          $ref: '#/components/schemas/ProviderOperationDefinition'
        binding:
          $ref: '#/components/schemas/ProviderOperationBinding'
      required:
        - definition
        - binding
    ProviderBoundaryEvaluationRequest:
      type: object
      properties:
        seam_key:
          type: string
        file_path:
          type: string
        proposed_owner:
          $ref: '#/components/schemas/ProviderBoundaryOwner'
        provider_specific_terms:
          type: array
          items:
            type: string
        introduces_new_binding:
          type: boolean
      required:
        - seam_key
        - file_path
        - proposed_owner
        - provider_specific_terms
        - introduces_new_binding
    ProviderBoundaryCheckResult:
      type: object
      properties:
        status:
          type: string
          enum:
            - allowed
            - review_required
            - blocked
        seam_key:
          type: string
        file_path:
          type: string
        violation_code:
          type: string
          enum:
            - none
            - platform_core_provider_leak
            - undeclared_exception
            - missing_provider_binding
            - provider_binding_as_primary_truth
        message:
          type: string
        suggested_follow_up:
          type: string
          enum:
            - none
            - document-in-feature
            - follow-up-spec
      required:
        - status
        - seam_key
        - file_path
        - violation_code
        - message
        - suggested_follow_up