openapi: 3.1.0
info:
  title: Provider Dispatch Gate Start Contract
  version: 1.0.0
  description: >-
    Internal reference contract for the operator-triggered provider-backed start
    surfaces covered by Spec 216. The real implementation remains Filament and
    Livewire HTML actions. The vendor media types below document the structured
    start-result and accepted-run payloads that must be derivable before
    rendering. This is not a public API commitment.
paths:
  /admin/t/{tenant}/provider-actions/{operation}/start:
    post:
      summary: Start a tenant-scoped provider-backed operation
      parameters:
        - name: tenant
          in: path
          required: true
          schema:
            type: string
        - name: operation
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProviderStartRequest'
      responses:
        '200':
          description: Rendered Livewire action response for the start attempt
          content:
            text/html:
              schema:
                type: string
            application/vnd.tenantpilot.provider-start-outcome+json:
              schema:
                $ref: '#/components/schemas/ProviderStartOutcome'
        '403':
          description: Tenant member lacks the required capability for the operation
        '404':
          description: Tenant is not visible because workspace or tenant entitlement is missing
  /admin/provider-connections/{connection}/actions/{operation}/start:
    post:
      summary: Start a provider-connection-scoped operation
      parameters:
        - name: connection
          in: path
          required: true
          schema:
            type: integer
        - name: operation
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Rendered Livewire action response for the connection-scoped start attempt
          content:
            text/html:
              schema:
                type: string
            application/vnd.tenantpilot.provider-start-outcome+json:
              schema:
                $ref: '#/components/schemas/ProviderStartOutcome'
        '403':
          description: Viewer is in scope but lacks the required capability for the action
        '404':
          description: Provider connection is not visible because entitlement is missing
  /admin/t/{tenant}/restore-runs/{restoreRun}/execute:
    post:
      summary: Execute a restore through the canonical provider start gate
      parameters:
        - name: tenant
          in: path
          required: true
          schema:
            type: string
        - name: restoreRun
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Rendered restore execute action response
          content:
            text/html:
              schema:
                type: string
            application/vnd.tenantpilot.provider-start-outcome+json:
              schema:
                $ref: '#/components/schemas/ProviderStartOutcome'
        '403':
          description: Tenant member lacks restore execution capability after membership is established
        '404':
          description: Restore run is not visible because entitlement is missing
  /admin/t/{tenant}/directory/groups/sync:
    post:
      summary: Start directory groups sync
      parameters:
        - name: tenant
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DirectoryGroupsSyncRequest'
      responses:
        '200':
          description: Rendered directory groups sync action response
          content:
            text/html:
              schema:
                type: string
            application/vnd.tenantpilot.provider-start-outcome+json:
              schema:
                $ref: '#/components/schemas/ProviderStartOutcome'
        '403':
          description: Tenant member lacks sync capability after membership is established
        '404':
          description: Tenant is not visible because entitlement is missing
  /admin/t/{tenant}/directory/role-definitions/sync:
    post:
      summary: Start role definitions sync
      parameters:
        - name: tenant
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Rendered role definitions sync action response
          content:
            text/html:
              schema:
                type: string
            application/vnd.tenantpilot.provider-start-outcome+json:
              schema:
                $ref: '#/components/schemas/ProviderStartOutcome'
        '403':
          description: Tenant member lacks the required capability after membership is established
        '404':
          description: Tenant is not visible because entitlement is missing
  /admin/onboarding/{session}/provider-actions/{operation}/start:
    post:
      summary: Start an onboarding provider verification action
      parameters:
        - name: session
          in: path
          required: true
          schema:
            type: integer
        - name: operation
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnboardingProviderStartRequest'
      responses:
        '200':
          description: Rendered onboarding verification action response
          content:
            text/html:
              schema:
                type: string
            application/vnd.tenantpilot.provider-start-outcome+json:
              schema:
                $ref: '#/components/schemas/ProviderStartOutcome'
        '403':
          description: Workspace member lacks the required capability after scope is established
        '404':
          description: Onboarding session is not visible because entitlement is missing
  /admin/onboarding/{session}/provider-bootstrap/start:
    post:
      summary: Start onboarding bootstrap work under sequential protected-scope admission
      parameters:
        - name: session
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnboardingBootstrapStartRequest'
      responses:
        '200':
          description: Rendered onboarding bootstrap action response
          content:
            text/html:
              schema:
                type: string
            application/vnd.tenantpilot.onboarding-bootstrap-start-outcome+json:
              schema:
                $ref: '#/components/schemas/OnboardingBootstrapStartOutcome'
        '403':
          description: Workspace member lacks the required capability after scope is established
        '404':
          description: Onboarding session is not visible because entitlement is missing
  /admin/operations/{run}:
    get:
      summary: Canonical provider-backed operation run detail
      parameters:
        - name: run
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Rendered Monitoring → Operations run detail page
          content:
            text/html:
              schema:
                type: string
            application/vnd.tenantpilot.provider-backed-run-detail+json:
              schema:
                $ref: '#/components/schemas/ProviderBackedRunDetail'
        '403':
          description: Viewer is in scope but lacks permission for related actions
        '404':
          description: Run is not visible because workspace or tenant entitlement is missing
components:
  schemas:
    ProviderStartRequest:
      type: object
      properties:
        providerConnectionId:
          type: integer
          nullable: true
        sourceSurface:
          type: string
        targetContext:
          type: object
          additionalProperties: true
    DirectoryGroupsSyncRequest:
      type: object
      properties:
        selectionKey:
          type: string
          default: all_groups_v1
        providerConnectionId:
          type: integer
          nullable: true
    OnboardingProviderStartRequest:
      type: object
      properties:
        providerConnectionId:
          type: integer
          nullable: true
        step:
          type: string
    OnboardingBootstrapStartRequest:
      type: object
      required:
        - providerConnectionId
        - selectedOperations
      properties:
        providerConnectionId:
          type: integer
        selectedOperations:
          type: array
          minItems: 1
          items:
            type: string
        sourceSurface:
          type: string
          default: onboarding.bootstrap
    ProviderStartOutcome:
      type: object
      description: >-
        Canonical start-result shape derived before queue admission for every
        route-bounded provider-backed start covered by Spec 216.
      required:
        - status
        - operationType
        - operatorMessage
      properties:
        status:
          type: string
          enum:
            - accepted
            - deduped
            - scope_busy
            - blocked
        operationType:
          type: string
        operatorVerb:
          type: string
        operatorTarget:
          type: string
        operatorMessage:
          type: string
        shortReason:
          type: string
          nullable: true
        providerConnection:
          $ref: '#/components/schemas/ProviderConnectionContext'
        run:
          $ref: '#/components/schemas/RunReference'
        nextSteps:
          type: array
          items:
            $ref: '#/components/schemas/NextStep'
        actions:
          type: array
          items:
            $ref: '#/components/schemas/ActionLink'
    OnboardingBootstrapStartOutcome:
      allOf:
        - $ref: '#/components/schemas/ProviderStartOutcome'
        - type: object
          properties:
            acceptedOperation:
              type: string
              nullable: true
            pendingOperations:
              type: array
              items:
                type: string
    ProviderConnectionContext:
      type: object
      properties:
        id:
          type: integer
        provider:
          type: string
        label:
          type: string
    RunReference:
      type: object
      properties:
        id:
          type: integer
        url:
          type: string
        status:
          type: string
    NextStep:
      type: object
      required:
        - label
      properties:
        label:
          type: string
        description:
          type: string
          nullable: true
        href:
          type: string
          nullable: true
        actionType:
          type: string
          nullable: true
    ActionLink:
      type: object
      required:
        - label
        - href
      properties:
        label:
          type: string
        href:
          type: string
        kind:
          type: string
          nullable: true
    ProviderBackedRunDetail:
      type: object
      description: >-
        Canonical Monitoring run detail contract for accepted provider-backed
        work. The rendered page must reuse the same translated reason family
        for operator-triggered and scheduled or system-initiated runs, while
        terminal notifications remain initiator-only.
      required:
        - runId
        - operationType
        - executionStatus
      properties:
        runId:
          type: integer
        operationType:
          type: string
        executionStatus:
          type: string
        outcome:
          type: string
          nullable: true
        providerConnection:
          $ref: '#/components/schemas/ProviderConnectionContext'
        protectedScope:
          type: object
          additionalProperties: true
        shortReason:
          type: string
          nullable: true
        nextSteps:
          type: array
          items:
            $ref: '#/components/schemas/NextStep'
        diagnosticsAvailable:
          type: boolean