openapi: 3.1.0
info:
  title: Operator State Presentation Logical Contract
  version: 0.1.0
  summary: Logical contract for resolving raw domain state into operator-facing state under the shared taxonomy.
  description: |
    This contract is logical rather than transport-prescriptive. It describes the
    expected behavior of existing badge mappers, presenters, notifications, and
    Filament surfaces that consume the shared operator outcome taxonomy.
    Runtime badge implementations currently expose the resolved severity band
    through Filament badge colors with the same enum values.
servers:
  - url: https://tenantpilot.local
paths:
  /contracts/operator-state/resolve:
    post:
      summary: Resolve one raw domain state into operator-facing presentation
      operationId: resolveOperatorState
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StateResolutionRequest'
      responses:
        '200':
          description: Taxonomy-backed state presentation resolved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StateResolutionResponse'
              examples:
                blockedOperation:
                  value:
                    axis: execution_outcome
                    primaryLabel: Blocked by prerequisite
                    severity: warning
                    classificationLevel: primary
                    nextActionPolicy: required
                    explanationRequired: true
                    diagnosticLabel: null
                    legacyAliases:
                      - Blocked
                    notes: Execution could not start or continue until a prerequisite is fixed.
  /contracts/operator-state/validate-adoption:
    post:
      summary: Validate that an adopted surface only uses allowed taxonomy mappings
      operationId: validateAdoptionTarget
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdoptionValidationRequest'
      responses:
        '200':
          description: Adoption validation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdoptionValidationResponse'
components:
  schemas:
    StateResolutionRequest:
      type: object
      additionalProperties: false
      required:
        - domain
        - rawValue
        - surfaceType
      properties:
        domain:
          type: string
          example: operation_run_outcome
        rawValue:
          type: string
          example: blocked
        surfaceType:
          type: string
          enum:
            - badge
            - summary_line
            - notification
            - infolist
            - widget
        tenantScoped:
          type: boolean
          default: true
        includeDiagnostics:
          type: boolean
          default: false
    StateResolutionResponse:
      type: object
      additionalProperties: false
      required:
        - axis
        - primaryLabel
        - severity
        - classificationLevel
        - nextActionPolicy
        - explanationRequired
        - notes
      properties:
        axis:
          type: string
          example: execution_outcome
        primaryLabel:
          type: string
          example: Blocked by prerequisite
        severity:
          type: string
          description: Operator-facing severity band. In runtime badge mappings this is the Filament badge color.
          enum:
            - gray
            - info
            - success
            - warning
            - danger
            - primary
        classificationLevel:
          type: string
          enum:
            - primary
            - diagnostic
        nextActionPolicy:
          type: string
          enum:
            - required
            - optional
            - none
        explanationRequired:
          type: boolean
        diagnosticLabel:
          type:
            - string
            - 'null'
          example: Fallback renderer
        legacyAliases:
          type: array
          items:
            type: string
        notes:
          type: string
          example: Execution could not start or continue until a prerequisite is fixed.
    AdoptionValidationRequest:
      type: object
      additionalProperties: false
      required:
        - target
        - entries
      properties:
        target:
          type: string
          example: operations
        entries:
          type: array
          items:
            $ref: '#/components/schemas/StateResolutionResponse'
    AdoptionValidationResponse:
      type: object
      additionalProperties: false
      required:
        - valid
        - violations
      properties:
        valid:
          type: boolean
        violations:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - code
              - message
            properties:
              code:
                type: string
                enum:
                  - diagnostic_severity_violation
                  - missing_next_action_policy
                  - unqualified_overloaded_term
                  - unauthorized_scope_leak_risk
              message:
                type: string
                example: Diagnostic taxonomy entries cannot use warning or danger severity.