openapi: 3.1.0
info:
  title: Restore Safety Integrity Contracts
  version: 1.0.0
  description: >-
    Internal reference contract for the restore safety surfaces. The routes continue
    to return rendered HTML through Filament and Livewire. The vendor media types below
    document the structured page and mutation models that must be derivable before rendering
    or execution. This is not a public API commitment.
paths:
  /admin/t/{tenant}/restore-runs/create:
    get:
      summary: Restore run wizard page
      description: >-
        Returns the rendered restore wizard. The vendor media type documents the
        safety-integrity page model that the wizard must expose.
      parameters:
        - name: tenant
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Rendered restore wizard page
          content:
            text/html:
              schema:
                type: string
            application/vnd.tenantpilot.restore-safety-wizard+json:
              schema:
                $ref: '#/components/schemas/RestoreSafetyWizardPage'
        '403':
          description: Viewer is in scope but lacks restore execution capability
        '404':
          description: Tenant or restore surface is not visible because tenant membership or workspace context is missing
  /admin/t/{tenant}/restore-runs:
    post:
      summary: Create a restore run or queue a real restore execution
      description: >-
        Internal logical contract for the wizard submission. The real implementation is
        Filament and Livewire driven, but the same validation truth must hold.
      parameters:
        - name: tenant
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/vnd.tenantpilot.restore-run-create+json:
            schema:
              $ref: '#/components/schemas/CreateRestoreRunRequest'
      responses:
        '201':
          description: Restore run created or queued successfully
          content:
            application/vnd.tenantpilot.restore-run-created+json:
              schema:
                $ref: '#/components/schemas/CreateRestoreRunResponse'
        '403':
          description: Viewer is in scope but lacks restore execution capability
        '404':
          description: Tenant or backup scope is not visible because tenant membership or workspace context is missing
        '422':
          description: Preview, checks, scope fingerprint, or hard-confirm validation failed
  /admin/t/{tenant}/restore-runs/{restoreRun}:
    get:
      summary: Restore run detail and result page
      description: >-
        Returns the rendered restore detail page. The vendor media type documents the
        result-attention and basis-truth model that must be available for rendering.
      parameters:
        - name: tenant
          in: path
          required: true
          schema:
            type: integer
        - name: restoreRun
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Rendered restore detail page
          content:
            text/html:
              schema:
                type: string
            application/vnd.tenantpilot.restore-run-detail+json:
              schema:
                $ref: '#/components/schemas/RestoreRunDetailPage'
        '403':
          description: Viewer is in scope but lacks required capability for a linked follow-up action
        '404':
          description: Restore run is not visible because tenant membership or workspace context is missing
  /admin/operations/{run}:
    get:
      summary: Canonical operation detail for a restore-linked run
      description: >-
        Returns the rendered canonical operation detail page. The vendor media type documents
        the restore-specific continuation truth that must remain visible when the run represents
        restore execution.
      parameters:
        - name: run
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Rendered canonical operation detail page
          content:
            text/html:
              schema:
                type: string
            application/vnd.tenantpilot.restore-linked-operation+json:
              schema:
                $ref: '#/components/schemas/RestoreLinkedOperationSurface'
        '403':
          description: Viewer is in scope but lacks a linked follow-up capability
        '404':
          description: Run is not visible because workspace or tenant entitlement is missing
components:
  schemas:
    RestoreSafetyWizardPage:
      type: object
      required:
        - currentScope
        - previewIntegrity
        - checksIntegrity
        - executionReadiness
        - safetyAssessment
        - primaryGuidance
      properties:
        currentScope:
          $ref: '#/components/schemas/ScopeBasis'
        previewIntegrity:
          $ref: '#/components/schemas/IntegrityState'
        checksIntegrity:
          $ref: '#/components/schemas/IntegrityState'
        executionReadiness:
          $ref: '#/components/schemas/ExecutionReadiness'
        safetyAssessment:
          $ref: '#/components/schemas/SafetyAssessment'
        primaryGuidance:
          $ref: '#/components/schemas/PrimaryGuidance'
        lastValidatedAt:
          type:
            - string
            - 'null'
          format: date-time
    CreateRestoreRunRequest:
      type: object
      required:
        - backupSetId
        - scopeMode
        - groupMapping
        - isDryRun
        - scopeFingerprint
      properties:
        backupSetId:
          type: integer
        scopeMode:
          type: string
          enum:
            - all
            - selected
        backupItemIds:
          type: array
          items:
            type: integer
        groupMapping:
          type: object
          additionalProperties:
            type: string
        isDryRun:
          type: boolean
        acknowledgedImpact:
          type: boolean
        tenantConfirm:
          type:
            - string
            - 'null'
        scopeFingerprint:
          type: string
        previewEvidence:
          oneOf:
            - $ref: '#/components/schemas/IntegrityEvidence'
            - type: 'null'
        checksEvidence:
          oneOf:
            - $ref: '#/components/schemas/IntegrityEvidence'
            - type: 'null'
    CreateRestoreRunResponse:
      type: object
      required:
        - restoreRunId
        - status
        - executionMode
        - executionSafetySnapshot
      properties:
        restoreRunId:
          type: integer
        status:
          type: string
        operationRunId:
          type:
            - integer
            - 'null'
        executionMode:
          type: string
          enum:
            - preview_only
            - execute
        executionSafetySnapshot:
          $ref: '#/components/schemas/SafetySnapshot'
    RestoreRunDetailPage:
      type: object
      required:
        - header
        - basisTruth
        - resultAttention
        - primaryNextAction
      properties:
        header:
          $ref: '#/components/schemas/RestoreRunHeader'
        basisTruth:
          $ref: '#/components/schemas/BasisTruth'
        resultAttention:
          $ref: '#/components/schemas/ResultAttention'
        primaryNextAction:
          $ref: '#/components/schemas/PrimaryGuidance'
        itemBreakdown:
          type: array
          items:
            $ref: '#/components/schemas/ResultItem'
        diagnostics:
          type: array
          items:
            $ref: '#/components/schemas/DiagnosticBlock'
        relatedOperation:
          oneOf:
            - $ref: '#/components/schemas/RestoreOperationLink'
            - type: 'null'
    RestoreLinkedOperationSurface:
      type: object
      required:
        - operationLifecycle
        - operationOutcome
        - restoreContinuation
      properties:
        operationLifecycle:
          $ref: '#/components/schemas/Fact'
        operationOutcome:
          $ref: '#/components/schemas/Fact'
        restoreContinuation:
          $ref: '#/components/schemas/RestoreOperationLink'
    ScopeBasis:
      type: object
      required:
        - backupSetId
        - scopeMode
        - selectedItemIds
        - groupMapping
        - fingerprint
      properties:
        backupSetId:
          type: integer
        scopeMode:
          type: string
          enum:
            - all
            - selected
        selectedItemIds:
          type: array
          items:
            type: integer
        groupMapping:
          type: object
          additionalProperties:
            type: string
        fingerprint:
          type: string
    IntegrityState:
      type: object
      required:
        - state
        - rerunRequired
      properties:
        state:
          type: string
          enum:
            - not_generated
            - not_run
            - current
            - stale
            - invalidated
        fingerprint:
          type:
            - string
            - 'null'
        capturedAt:
          type:
            - string
            - 'null'
          format: date-time
        blockingCount:
          type:
            - integer
            - 'null'
        warningCount:
          type:
            - integer
            - 'null'
        invalidationReasons:
          type: array
          items:
            type: string
        rerunRequired:
          type: boolean
        displaySummary:
          type:
            - string
            - 'null'
    IntegrityEvidence:
      type: object
      required:
        - fingerprint
        - capturedAt
      properties:
        fingerprint:
          type: string
        capturedAt:
          type: string
          format: date-time
    ExecutionReadiness:
      type: object
      required:
        - allowed
        - blockingReasons
        - mutationScope
      properties:
        allowed:
          type: boolean
        blockingReasons:
          type: array
          items:
            type: string
        mutationScope:
          type: string
          enum:
            - simulation_only
            - microsoft_tenant
        requiredCapability:
          type:
            - string
            - 'null'
    SafetyAssessment:
      type: object
      required:
        - state
        - positiveClaimSuppressed
      properties:
        state:
          type: string
          enum:
            - blocked
            - risky
            - ready_with_caution
            - ready
        positiveClaimSuppressed:
          type: boolean
        blockerCount:
          type: integer
        warningCount:
          type: integer
        primaryIssueCode:
          type:
            - string
            - 'null'
        primaryNextAction:
          type:
            - string
            - 'null'
    SafetySnapshot:
      type: object
      required:
        - evaluatedAt
        - scopeFingerprint
        - previewState
        - checksState
        - safetyState
      properties:
        evaluatedAt:
          type: string
          format: date-time
        scopeFingerprint:
          type: string
        previewState:
          type: string
        checksState:
          type: string
        safetyState:
          type: string
        blockingCount:
          type: integer
        warningCount:
          type: integer
        primaryIssueCode:
          type:
            - string
            - 'null'
        followUpBoundary:
          type:
            - string
            - 'null'
    RestoreRunHeader:
      type: object
      required:
        - restoreRunId
        - backupSetLabel
        - status
        - executionMode
      properties:
        restoreRunId:
          type: integer
        backupSetLabel:
          type: string
        status:
          $ref: '#/components/schemas/Fact'
        executionMode:
          $ref: '#/components/schemas/Fact'
        requestedBy:
          oneOf:
            - $ref: '#/components/schemas/Fact'
            - type: 'null'
        startedAt:
          type:
            - string
            - 'null'
          format: date-time
        completedAt:
          type:
            - string
            - 'null'
          format: date-time
    BasisTruth:
      type: object
      properties:
        scopeBasis:
          oneOf:
            - $ref: '#/components/schemas/ScopeBasis'
            - type: 'null'
        previewIntegrity:
          oneOf:
            - $ref: '#/components/schemas/IntegrityState'
            - type: 'null'
        checksIntegrity:
          oneOf:
            - $ref: '#/components/schemas/IntegrityState'
            - type: 'null'
        executionSafetySnapshot:
          oneOf:
            - $ref: '#/components/schemas/SafetySnapshot'
            - type: 'null'
    ResultAttention:
      type: object
      required:
        - state
        - followUpRequired
        - primaryCauseFamily
        - summary
        - recoveryClaimBoundary
      properties:
        state:
          type: string
          enum:
            - not_executed
            - completed
            - partial
            - failed
            - completed_with_follow_up
        followUpRequired:
          type: boolean
        primaryCauseFamily:
          type: string
          enum:
            - execution_failure
            - write_gate_or_rbac
            - provider_operability
            - missing_dependency_or_mapping
            - payload_quality
            - scope_mismatch
            - item_level_failure
            - none
        summary:
          type: string
        recoveryClaimBoundary:
          type: string
        counts:
          type: object
          additionalProperties:
            type: integer
    PrimaryGuidance:
      type: object
      required:
        - title
        - body
        - actionLabel
        - actionKind
      properties:
        title:
          type: string
        body:
          type: string
        actionLabel:
          type: string
        actionKind:
          type: string
          enum:
            - rerun_checks
            - regenerate_preview
            - adjust_scope
            - review_warnings
            - execute_preview
            - execute_restore
            - review_result
            - open_operation
            - inspect_blocker
    ResultItem:
      type: object
      required:
        - label
        - status
      properties:
        label:
          type: string
        status:
          type: string
        causeFamily:
          type:
            - string
            - 'null'
        nextAction:
          type:
            - string
            - 'null'
    DiagnosticBlock:
      type: object
      required:
        - title
      properties:
        title:
          type: string
        description:
          type:
            - string
            - 'null'
        collapsible:
          type: boolean
        collapsed:
          type: boolean
    RestoreOperationLink:
      type: object
      required:
        - accessState
      properties:
        restoreRunId:
          type:
            - integer
            - 'null'
        resultAttention:
          oneOf:
            - $ref: '#/components/schemas/ResultAttention'
            - type: 'null'
        restoreDetailUrl:
          type:
            - string
            - 'null'
        accessState:
          type: string
          enum:
            - linked
            - unavailable
            - forbidden_by_scope
        unavailableReason:
          type:
            - string
            - 'null'
    Fact:
      type: object
      required:
        - label
        - value
      properties:
        label:
          type: string
        value:
          type: string