openapi: 3.1.0
info:
  title: Canonical Control Catalog Logical Contract
  version: 0.1.0
  description: |
    Logical contract for the first canonical control catalog slice.
    This describes shared internal request and response shapes for catalog lookup
    and control resolution. It is not a commitment to expose public HTTP routes.
paths:
  /logical/canonical-controls/catalog:
    get:
      summary: List the seeded canonical control definitions
      operationId: listCanonicalControls
      responses:
        '200':
          description: Seeded canonical controls
          content:
            application/json:
              schema:
                type: object
                properties:
                  controls:
                    type: array
                    items:
                      $ref: '#/components/schemas/CanonicalControlDefinition'
                required:
                  - controls
  /logical/canonical-controls/resolve:
    post:
      summary: Resolve canonical control metadata for a governed subject or signal context
      operationId: resolveCanonicalControl
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ControlResolutionRequest'
      responses:
        '200':
          description: Control resolution outcome
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ControlResolutionResponse'
components:
  schemas:
    CanonicalControlDefinition:
      type: object
      properties:
        control_key:
          type: string
        name:
          type: string
        domain_key:
          type: string
        subdomain_key:
          type: string
        control_class:
          type: string
        summary:
          type: string
        operator_description:
          type: string
        detectability_class:
          type: string
          enum:
            - direct_technical
            - indirect_technical
            - workflow_attested
            - external_evidence_only
        evaluation_strategy:
          type: string
          enum:
            - state_evaluated
            - signal_inferred
            - workflow_confirmed
            - externally_attested
        evidence_archetypes:
          type: array
          items:
            $ref: '#/components/schemas/EvidenceArchetype'
        artifact_suitability:
          type: object
          properties:
            baseline:
              type: boolean
            drift:
              type: boolean
            finding:
              type: boolean
            exception:
              type: boolean
            evidence:
              type: boolean
            review:
              type: boolean
            report:
              type: boolean
          required:
            - baseline
            - drift
            - finding
            - exception
            - evidence
            - review
            - report
        historical_status:
          type: string
          enum:
            - active
            - retired
      required:
        - control_key
        - name
        - domain_key
        - subdomain_key
        - control_class
        - summary
        - operator_description
        - detectability_class
        - evaluation_strategy
        - evidence_archetypes
        - artifact_suitability
        - historical_status
    ControlResolutionRequest:
      type: object
      description: All supplied discriminator fields combine conjunctively. The resolver narrows bindings by provider, consumer context, and every provided subject-family, workload, or signal value.
      properties:
        provider:
          type: string
          enum:
            - microsoft
        subject_family_key:
          type: string
        workload:
          type: string
        signal_key:
          type: string
        consumer_context:
          type: string
          enum:
            - baseline
            - drift
            - finding
            - evidence
            - exception
            - review
            - report
      anyOf:
        - required:
            - subject_family_key
        - required:
            - workload
        - required:
            - signal_key
      required:
        - provider
        - consumer_context
    BindingContext:
      type: object
      properties:
        provider:
          type: string
          enum:
            - microsoft
        subject_family_key:
          type: string
        workload:
          type: string
        signal_key:
          type: string
        consumer_context:
          type: string
          enum:
            - baseline
            - drift
            - finding
            - evidence
            - exception
            - review
            - report
    EvidenceArchetype:
      type: string
      enum:
        - configuration_snapshot
        - execution_result
        - policy_or_assignment_summary
        - operator_attestation
        - external_artifact_reference
    UnresolvedControlResolutionReasonCode:
      type: string
      enum:
        - missing_binding
        - unsupported_provider
        - unsupported_consumer_context
        - insufficient_context
    AmbiguousControlResolutionReasonCode:
      type: string
      enum:
        - ambiguous_binding
    ResolvedControlResolutionResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - resolved
        control:
          $ref: '#/components/schemas/CanonicalControlDefinition'
      required:
        - status
        - control
    UnresolvedControlResolutionResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - unresolved
        reason_code:
          $ref: '#/components/schemas/UnresolvedControlResolutionReasonCode'
        binding_context:
          $ref: '#/components/schemas/BindingContext'
      required:
        - status
        - reason_code
        - binding_context
    AmbiguousControlResolutionResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - ambiguous
        reason_code:
          $ref: '#/components/schemas/AmbiguousControlResolutionReasonCode'
        candidate_control_keys:
          type: array
          items:
            type: string
        binding_context:
          $ref: '#/components/schemas/BindingContext'
      required:
        - status
        - reason_code
        - candidate_control_keys
        - binding_context
    ControlResolutionResponse:
      oneOf:
        - $ref: '#/components/schemas/ResolvedControlResolutionResponse'
        - $ref: '#/components/schemas/UnresolvedControlResolutionResponse'
        - $ref: '#/components/schemas/AmbiguousControlResolutionResponse'