openapi: 3.1.0
info:
  title: Provider Identity & Target Scope Neutrality Logical Contract
  version: 0.1.0
  description: |
    Logical internal contract for the provider connection target-scope neutrality
    slice. It describes the normalized shared target-scope descriptor, the
    operator-facing surface summary, and the bounded neutrality guard result.
    It is not a commitment to expose public HTTP routes.
    Review stop: shared provider connection surfaces must use neutral target
    scope truth by default, carry provider-owned Microsoft identity only as
    contextual metadata, and resolve remaining provider-boundary drift through
    document-in-feature or follow-up-spec disposition instead of silent shared
    platform truth.
paths:
  /logical/provider-connections/{connectionId}/target-scope:
    get:
      summary: Read the normalized target-scope descriptor for an existing provider connection
      operationId: getProviderConnectionTargetScope
      parameters:
        - name: connectionId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Normalized target-scope descriptor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderConnectionTargetScopeDescriptor'
  /logical/provider-connections/target-scope/normalize:
    post:
      summary: Normalize create or edit input into shared target-scope truth plus contextual provider metadata
      operationId: normalizeProviderConnectionTargetScope
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProviderConnectionTargetScopeInput'
      responses:
        '200':
          description: Normalized descriptor and optional shared-surface preview
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderConnectionTargetScopeNormalizationSuccess'
        '422':
          description: Unsupported provider-scope combination or missing provider context
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderConnectionTargetScopeNormalizationFailure'
  /logical/provider-connections/{connectionId}/surface-summary:
    get:
      summary: Read the default-visible operator-facing summary for a shared provider connection surface
      operationId: getProviderConnectionSurfaceSummary
      parameters:
        - name: connectionId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Shared-surface summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderConnectionSurfaceSummary'
  /logical/provider-connections/neutrality/evaluate:
    post:
      summary: Evaluate whether a touched shared provider-connection path preserves neutral target-scope truth
      operationId: evaluateProviderConnectionNeutrality
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProviderConnectionNeutralityEvaluationRequest'
      responses:
        '200':
          description: Neutrality evaluation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderConnectionNeutralityCheckResult'
components:
  schemas:
    ProviderConnectionSupportedScopeKind:
      type: string
      enum:
        - tenant
    ProviderIdentityContextVisibility:
      type: string
      enum:
        - contextual_only
        - audit_only
        - troubleshooting_only
    ProviderIdentityContextMetadata:
      type: object
      properties:
        provider:
          type: string
        detail_key:
          type: string
        detail_label:
          type: string
        detail_value:
          type: string
        visibility:
          $ref: '#/components/schemas/ProviderIdentityContextVisibility'
      required:
        - provider
        - detail_key
        - detail_label
        - detail_value
        - visibility
    ProviderConnectionTargetScopeDescriptor:
      type: object
      properties:
        provider:
          type: string
        scope_kind:
          $ref: '#/components/schemas/ProviderConnectionSupportedScopeKind'
        scope_identifier:
          type: string
        scope_display_name:
          type: string
        shared_label:
          type: string
        shared_help_text:
          type: string
      required:
        - provider
        - scope_kind
        - scope_identifier
        - scope_display_name
        - shared_label
        - shared_help_text
    ProviderConnectionTargetScopeInput:
      type: object
      properties:
        provider:
          type: string
        scope_kind:
          $ref: '#/components/schemas/ProviderConnectionSupportedScopeKind'
        scope_identifier:
          type: string
        scope_display_name:
          type: string
        provider_specific_identity:
          type: object
          additionalProperties:
            type: string
      required:
        - provider
        - scope_kind
        - scope_identifier
        - scope_display_name
    ProviderConnectionTargetScopeNormalizationSuccess:
      type: object
      properties:
        status:
          type: string
          enum:
            - normalized
        provider:
          type: string
        scope_kind:
          $ref: '#/components/schemas/ProviderConnectionSupportedScopeKind'
        target_scope:
          $ref: '#/components/schemas/ProviderConnectionTargetScopeDescriptor'
        contextual_identity_details:
          type: array
          items:
            $ref: '#/components/schemas/ProviderIdentityContextMetadata'
        failure_code:
          type: string
          enum:
            - none
        message:
          type: string
        preview_summary:
          oneOf:
            - $ref: '#/components/schemas/ProviderConnectionSurfaceSummary'
            - type: 'null'
      required:
        - status
        - provider
        - scope_kind
        - target_scope
        - contextual_identity_details
        - failure_code
        - message
        - preview_summary
    ProviderConnectionTargetScopeNormalizationFailure:
      type: object
      properties:
        status:
          type: string
          enum:
            - blocked
        provider:
          type: string
        scope_kind:
          $ref: '#/components/schemas/ProviderConnectionSupportedScopeKind'
        failure_code:
          type: string
          enum:
            - unsupported_provider_scope_combination
            - missing_provider_context
        message:
          type: string
      required:
        - status
        - provider
        - scope_kind
        - failure_code
        - message
    ProviderConnectionSurfaceSummary:
      type: object
      properties:
        provider:
          type: string
        target_scope:
          $ref: '#/components/schemas/ProviderConnectionTargetScopeDescriptor'
        consent_state:
          type: string
        verification_state:
          type: string
        readiness_summary:
          type: string
        contextual_identity_details:
          type: array
          items:
            $ref: '#/components/schemas/ProviderIdentityContextMetadata'
      required:
        - provider
        - target_scope
        - consent_state
        - verification_state
        - readiness_summary
        - contextual_identity_details
    ProviderConnectionNeutralityEvaluationRequest:
      type: object
      properties:
        surface_key:
          type: string
        path:
          type: string
        surface_ownership:
          type: string
          enum:
            - platform_core
            - provider_owned
        default_labels:
          type: array
          items:
            type: string
        required_fields:
          type: array
          items:
            type: string
        filter_labels:
          type: array
          items:
            type: string
        validation_messages:
          type: array
          items:
            type: string
        helper_copy:
          type: array
          items:
            type: string
        audit_prose:
          type: array
          items:
            type: string
        allowed_exception_classes:
          type: array
          items:
            type: string
        provider:
          type: string
        provider_owned_context:
          type: array
          items:
            type: string
      required:
        - surface_key
        - path
        - surface_ownership
        - default_labels
        - required_fields
        - filter_labels
        - validation_messages
        - helper_copy
        - audit_prose
        - allowed_exception_classes
        - provider
        - provider_owned_context
    ProviderConnectionNeutralityCheckResult:
      type: object
      description: |
        Guard result for touched shared provider connection surfaces. A blocked
        or review_required result must name whether the issue is a default
        label, filter, required field, validation message, helper copy, audit
        prose, or missing target-scope descriptor, and must route the close-out
        through document-in-feature or follow-up-spec.
      properties:
        status:
          type: string
          enum:
            - allowed
            - review_required
            - blocked
        surface_key:
          type: string
        path:
          type: string
        surface_ownership:
          type: string
          enum:
            - platform_core
            - provider_owned
        allowed_exception_classes:
          type: array
          items:
            type: string
        violation_code:
          type: string
          enum:
            - none
            - provider_specific_default_label
            - provider_specific_default_filter
            - provider_specific_required_field
            - provider_specific_validation_message
            - provider_specific_default_helper_copy
            - provider_specific_default_audit_prose
            - missing_target_scope_descriptor
        message:
          type: string
        suggested_follow_up:
          type: string
          enum:
            - none
            - document-in-feature
            - follow-up-spec
      required:
        - status
        - surface_key
        - path
        - surface_ownership
        - allowed_exception_classes
        - violation_code
        - message
        - suggested_follow_up