openapi: 3.1.0
info:
  title: Provider Capability Registry Logical Contract
  version: 0.1.0
  description: >-
    Logical contract for the derived provider capability registry and its
    consumer surfaces. This models shared capability truth only; it does not
    declare new persisted resources or public API commitments.
x-logical-contract: true
x-initial-capability-inventory:
  provider_connection_check:
    label: Provider connection check
    operationTypes:
      - provider.connection.check
    providerRequirementKeys:
      - permissions.admin_consent
  inventory_read:
    label: Inventory read
    operationTypes:
      - inventory.sync
    providerRequirementKeys:
      - permissions.intune_configuration
      - permissions.intune_apps
  configuration_read:
    label: Configuration read
    operationTypes:
      - compliance.snapshot
    providerRequirementKeys:
      - permissions.intune_configuration
  restore_execute:
    label: Restore execute
    operationTypes:
      - restore.execute
    providerRequirementKeys:
      - permissions.intune_configuration
      - permissions.intune_rbac_assignments
  directory_groups_read:
    label: Directory groups read
    operationTypes:
      - directory.groups.sync
    providerRequirementKeys:
      - permissions.directory_groups
  directory_role_definitions_read:
    label: Directory role definitions read
    operationTypes:
      - directory.role_definitions.sync
    providerRequirementKeys:
      - provider.directory_role_definitions
      - permissions.admin_consent
paths:
  /logical/provider-connections/{providerConnectionId}/capabilities:
    get:
      summary: Resolve capability summary for one provider connection
      operationId: getProviderConnectionCapabilities
      parameters:
        - name: providerConnectionId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Capability summary for provider-connections and related context
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderConnectionCapabilitySummary'
  /logical/managed-environments/{managedEnvironmentId}/required-permission-capabilities:
    get:
      summary: Resolve capability-grouped required-permissions diagnostics
      operationId: getRequiredPermissionCapabilityGroups
      parameters:
        - name: managedEnvironmentId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Capability groups with nested permission evidence
          content:
            application/json:
              schema:
                type: object
                required:
                  - groups
                properties:
                  groups:
                    type: array
                    items:
                      $ref: '#/components/schemas/RequiredPermissionsCapabilityGroup'
  /logical/managed-environments/{managedEnvironmentId}/onboarding-provider-capability-assist:
    get:
      summary: Resolve onboarding capability assist for the current managed environment
      operationId: getOnboardingProviderCapabilityAssist
      parameters:
        - name: managedEnvironmentId
          in: path
          required: true
          schema:
            type: integer
        - name: providerConnectionId
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Capability-first onboarding assist payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingCapabilityAssist'
  /logical/provider-operations/{operationType}/capability-gate:
    post:
      summary: Evaluate provider capability requirements before provider-operation start
      operationId: evaluateProviderOperationCapabilityGate
      parameters:
        - name: operationType
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - managedEnvironmentId
              properties:
                managedEnvironmentId:
                  type: integer
                providerConnectionId:
                  type: integer
                  nullable: true
      responses:
        '200':
          description: Capability gate result for operation start
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationCapabilityGateResult'
  /logical/provider-capability-explanations:
    post:
      summary: Translate a provider blocker into a capability-first explanation
      operationId: getProviderCapabilityExplanation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - providerCapabilityKey
              properties:
                providerCapabilityKey:
                  $ref: '#/components/schemas/ProviderCapabilityKey'
                reasonCode:
                  type: string
                  nullable: true
                managedEnvironmentId:
                  type: integer
                  nullable: true
                providerConnectionId:
                  type: integer
                  nullable: true
      responses:
        '200':
          description: Capability-first support or contextual-help explanation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderCapabilityExplanation'
components:
  schemas:
    ProviderCapabilityKey:
      type: string
      enum:
        - provider_connection_check
        - inventory_read
        - configuration_read
        - restore_execute
        - directory_groups_read
        - directory_role_definitions_read
    ProviderCapabilityStatus:
      type: string
      enum:
        - supported
        - missing
        - blocked
        - unknown
        - not_applicable
    ProviderCapabilityDefinition:
      type: object
      required:
        - key
        - label
        - operationTypes
        - providerRequirementKeys
      properties:
        key:
          $ref: '#/components/schemas/ProviderCapabilityKey'
        label:
          type: string
        operationTypes:
          type: array
          items:
            type: string
        providerRequirementKeys:
          type: array
          items:
            type: string
        primaryReasonCodes:
          type: array
          items:
            type: string
        remediationRouteKind:
          type: string
    ProviderCapabilityResult:
      type: object
      required:
        - providerCapabilityKey
        - status
        - providerRequirementKeys
        - primaryMessage
      properties:
        providerCapabilityKey:
          $ref: '#/components/schemas/ProviderCapabilityKey'
        status:
          $ref: '#/components/schemas/ProviderCapabilityStatus'
        reasonCode:
          type: string
          nullable: true
        providerRequirementKeys:
          type: array
          items:
            type: string
        lastCheckedAt:
          type: string
          format: date-time
          nullable: true
        primaryMessage:
          type: string
        providerHint:
          type: string
          nullable: true
        evidenceCounts:
          type: object
          additionalProperties:
            type: integer
    PermissionEvidenceRow:
      type: object
      required:
        - key
        - type
        - status
      properties:
        key:
          type: string
        type:
          type: string
          enum:
            - application
            - delegated
        status:
          type: string
          enum:
            - granted
            - missing
            - error
        description:
          type: string
          nullable: true
        features:
          type: array
          items:
            type: string
    RequiredPermissionsCapabilityGroup:
      type: object
      required:
        - providerCapabilityKey
        - label
        - status
        - summary
        - rows
      properties:
        providerCapabilityKey:
          $ref: '#/components/schemas/ProviderCapabilityKey'
        label:
          type: string
        status:
          $ref: '#/components/schemas/ProviderCapabilityStatus'
        summary:
          type: string
        missingRequirementKeys:
          type: array
          items:
            type: string
        rows:
          type: array
          items:
            $ref: '#/components/schemas/PermissionEvidenceRow'
    ProviderConnectionCapabilitySummary:
      type: object
      required:
        - providerConnectionId
        - primaryCapabilityKey
        - primaryCapabilitySelectionRule
        - capabilities
        - nextStep
      properties:
        providerConnectionId:
          type: integer
        primaryCapabilityKey:
          $ref: '#/components/schemas/ProviderCapabilityKey'
        primaryCapabilitySelectionRule:
          type: string
          enum:
            - highest_risk_then_surface_relevance
        capabilities:
          type: array
          items:
            $ref: '#/components/schemas/ProviderCapabilityResult'
        nextStep:
          type: string
          nullable: true
    OnboardingCapabilityAssist:
      type: object
      required:
        - managedEnvironmentId
        - capabilities
      properties:
        managedEnvironmentId:
          type: integer
        providerConnectionId:
          type: integer
          nullable: true
        primaryCapabilityKey:
          $ref: '#/components/schemas/ProviderCapabilityKey'
        capabilities:
          type: array
          items:
            $ref: '#/components/schemas/ProviderCapabilityResult'
        nextStep:
          type: string
          nullable: true
    OperationCapabilityGateResult:
      type: object
      required:
        - operationType
        - requiredProviderCapabilityKeys
        - capabilities
        - decision
      properties:
        operationType:
          type: string
        requiredProviderCapabilityKeys:
          type: array
          items:
            $ref: '#/components/schemas/ProviderCapabilityKey'
        capabilities:
          type: array
          items:
            $ref: '#/components/schemas/ProviderCapabilityResult'
        decision:
          type: string
          enum:
            - allow
            - block
            - unknown
        nextStep:
          type: string
          nullable: true
    ProviderCapabilityExplanation:
      type: object
      required:
        - providerCapabilityKey
        - primaryMessage
      properties:
        providerCapabilityKey:
          $ref: '#/components/schemas/ProviderCapabilityKey'
        reasonCode:
          type: string
          nullable: true
        primaryMessage:
          type: string
        providerHint:
          type: string
          nullable: true
        requiredPermissionsUrl:
          type: string
          nullable: true