openapi: 3.1.0
info:
  title: Backup Quality Truth Surface Contracts
  version: 1.0.0
  description: >-
    Internal reference contract for backup-quality truth surfaces. The application
    continues to return rendered HTML through Filament and Livewire. The vendor
    media types below document the structured list, detail, and selection models
    that must be derivable before rendering. This is not a public API commitment.
paths:
  /admin/t/{tenant}/backup-sets:
    get:
      summary: Backup-set list surface
      description: >-
        Returns the rendered backup-set list page. The vendor media type documents
        the quality summary model that each visible row must expose.
      parameters:
        - name: tenant
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Rendered backup-set list page
          content:
            text/html:
              schema:
                type: string
            application/vnd.tenantpilot.backup-set-collection+json:
              schema:
                $ref: '#/components/schemas/BackupSetCollectionSurface'
        '403':
          description: Viewer is in scope but lacks backup or version viewing capability
        '404':
          description: Tenant scope is not visible because workspace or tenant membership is missing
  /admin/t/{tenant}/backup-sets/{backupSet}:
    get:
      summary: Backup-set detail surface
      description: >-
        Returns the rendered backup-set detail page. The vendor media type documents
        the summary-first quality model and the related per-item quality rows.
      parameters:
        - name: tenant
          in: path
          required: true
          schema:
            type: integer
        - name: backupSet
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Rendered backup-set detail page
          content:
            text/html:
              schema:
                type: string
            application/vnd.tenantpilot.backup-set-detail+json:
              schema:
                $ref: '#/components/schemas/BackupSetDetailSurface'
        '403':
          description: Viewer is in scope but lacks required capability for a linked maintenance action
        '404':
          description: Backup set is not visible because workspace or tenant membership is missing
  /admin/t/{tenant}/policy-versions:
    get:
      summary: Policy-version list surface
      description: >-
        Returns the rendered policy-version list page. The vendor media type documents
        the snapshot mode and backup-quality model that each row must expose.
      parameters:
        - name: tenant
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Rendered policy-version list page
          content:
            text/html:
              schema:
                type: string
            application/vnd.tenantpilot.policy-version-collection+json:
              schema:
                $ref: '#/components/schemas/PolicyVersionCollectionSurface'
        '403':
          description: Viewer is in scope but lacks policy-version viewing capability
        '404':
          description: Tenant scope is not visible because workspace or tenant membership is missing
  /admin/t/{tenant}/policy-versions/{policyVersion}:
    get:
      summary: Policy-version detail surface
      description: >-
        Returns the rendered policy-version detail page. The vendor media type documents
        the explicit backup-quality model that must be available before rendering.
      parameters:
        - name: tenant
          in: path
          required: true
          schema:
            type: integer
        - name: policyVersion
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Rendered policy-version detail page
          content:
            text/html:
              schema:
                type: string
            application/vnd.tenantpilot.policy-version-detail+json:
              schema:
                $ref: '#/components/schemas/PolicyVersionDetailSurface'
        '403':
          description: Viewer is in scope but lacks capability for a linked mutation action
        '404':
          description: Policy version is not visible because workspace or tenant membership is missing
  /admin/t/{tenant}/restore-runs/create:
    get:
      summary: Restore selection surface with backup-quality hints
      description: >-
        Returns the rendered restore wizard. The vendor media type documents the
        selection-stage backup-quality hints that must appear before risk checks.
      parameters:
        - name: tenant
          in: path
          required: true
          schema:
            type: integer
        - name: backup_set_id
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Rendered restore wizard page
          content:
            text/html:
              schema:
                type: string
            application/vnd.tenantpilot.restore-selection-quality+json:
              schema:
                $ref: '#/components/schemas/RestoreSelectionSurface'
        '403':
          description: Viewer is in scope but lacks restore capability
        '404':
          description: Restore surface is not visible because workspace or tenant membership is missing
components:
  schemas:
    BackupSetCollectionSurface:
      type: object
      required:
        - rows
      properties:
        rows:
          type: array
          items:
            $ref: '#/components/schemas/BackupSetRow'
    BackupSetRow:
      type: object
      required:
        - id
        - name
        - lifecycleStatus
        - itemCount
        - qualitySummary
      properties:
        id:
          type: integer
        name:
          type: string
        lifecycleStatus:
          $ref: '#/components/schemas/Fact'
        itemCount:
          type: integer
        capturedAt:
          type:
            - string
            - 'null'
          format: date-time
        completedAt:
          type:
            - string
            - 'null'
          format: date-time
        qualitySummary:
          $ref: '#/components/schemas/QualitySummary'
    BackupSetDetailSurface:
      type: object
      required:
        - header
        - qualitySummary
        - itemRows
      properties:
        header:
          $ref: '#/components/schemas/BackupSetHeader'
        qualitySummary:
          $ref: '#/components/schemas/QualitySummary'
        itemRows:
          type: array
          items:
            $ref: '#/components/schemas/BackupItemQualityRow'
        positiveClaimBoundary:
          $ref: '#/components/schemas/Fact'
    BackupSetHeader:
      type: object
      required:
        - id
        - name
        - lifecycleStatus
      properties:
        id:
          type: integer
        name:
          type: string
        lifecycleStatus:
          $ref: '#/components/schemas/Fact'
        archived:
          type: boolean
        itemCount:
          type: integer
    BackupItemQualityRow:
      type: object
      required:
        - id
        - label
        - policyType
        - snapshotCompleteness
        - assignmentCapture
        - hasDegradations
        - summaryMessage
      properties:
        id:
          type: integer
        label:
          type: string
        policyType:
          type: string
        platform:
          type:
            - string
            - 'null'
        versionNumber:
          type:
            - integer
            - 'null'
        snapshotCompleteness:
          $ref: '#/components/schemas/SnapshotCompleteness'
        assignmentCapture:
          $ref: '#/components/schemas/AssignmentCapture'
        integrityWarning:
          type:
            - string
            - 'null'
        hasDegradations:
          type: boolean
        degradationFamilies:
          type: array
          items:
            type: string
        summaryMessage:
          type: string
        nextAction:
          $ref: '#/components/schemas/Fact'
    PolicyVersionCollectionSurface:
      type: object
      required:
        - rows
      properties:
        rows:
          type: array
          items:
            $ref: '#/components/schemas/PolicyVersionRow'
    PolicyVersionRow:
      type: object
      required:
        - id
        - label
        - versionNumber
        - snapshotCompleteness
        - hasDegradations
        - summaryMessage
      properties:
        id:
          type: integer
        label:
          type: string
        versionNumber:
          type: integer
        capturedAt:
          type:
            - string
            - 'null'
          format: date-time
        snapshotCompleteness:
          $ref: '#/components/schemas/SnapshotCompleteness'
        assignmentCapture:
          $ref: '#/components/schemas/AssignmentCapture'
        integrityWarning:
          type:
            - string
            - 'null'
        hasDegradations:
          type: boolean
        degradationFamilies:
          type: array
          items:
            type: string
        summaryMessage:
          type: string
    PolicyVersionDetailSurface:
      type: object
      required:
        - header
        - qualityFact
        - positiveClaimBoundary
      properties:
        header:
          $ref: '#/components/schemas/PolicyVersionHeader'
        qualityFact:
          $ref: '#/components/schemas/QualityFact'
        positiveClaimBoundary:
          $ref: '#/components/schemas/Fact'
    PolicyVersionHeader:
      type: object
      required:
        - id
        - label
        - versionNumber
      properties:
        id:
          type: integer
        label:
          type: string
        versionNumber:
          type: integer
        capturedAt:
          type:
            - string
            - 'null'
          format: date-time
    RestoreSelectionSurface:
      type: object
      required:
        - backupSetOptions
        - positiveClaimBoundary
      properties:
        backupSetOptions:
          type: array
          items:
            $ref: '#/components/schemas/RestoreBackupSetOption'
        itemOptions:
          type: array
          items:
            $ref: '#/components/schemas/RestoreBackupItemOption'
        positiveClaimBoundary:
          $ref: '#/components/schemas/Fact'
    RestoreBackupSetOption:
      type: object
      required:
        - id
        - label
        - qualitySummary
      properties:
        id:
          type: integer
        label:
          type: string
        qualitySummary:
          $ref: '#/components/schemas/QualitySummary'
    RestoreBackupItemOption:
      type: object
      required:
        - id
        - label
        - qualityFact
      properties:
        id:
          type: integer
        label:
          type: string
        qualityFact:
          $ref: '#/components/schemas/QualityFact'
    QualitySummary:
      type: object
      required:
        - hasDegradations
        - degradedItemCount
        - metadataOnlyCount
        - assignmentIssueCount
        - orphanedAssignmentCount
        - summaryLabel
      properties:
        hasDegradations:
          type: boolean
        degradedItemCount:
          type: integer
        metadataOnlyCount:
          type: integer
        assignmentIssueCount:
          type: integer
        orphanedAssignmentCount:
          type: integer
        integrityWarningCount:
          type: integer
        unknownQualityCount:
          type: integer
        degradationFamilies:
          type: array
          items:
            type: string
        summaryLabel:
          type: string
        nextAction:
          $ref: '#/components/schemas/Fact'
    QualityFact:
      type: object
      required:
        - snapshotCompleteness
        - assignmentCapture
        - hasDegradations
        - summaryMessage
      properties:
        snapshotCompleteness:
          $ref: '#/components/schemas/SnapshotCompleteness'
        assignmentCapture:
          $ref: '#/components/schemas/AssignmentCapture'
        integrityWarning:
          type:
            - string
            - 'null'
        hasDegradations:
          type: boolean
        degradationFamilies:
          type: array
          items:
            type: string
        summaryMessage:
          type: string
        nextAction:
          $ref: '#/components/schemas/Fact'
    SnapshotCompleteness:
      type: object
      required:
        - mode
        - badgeLabel
      properties:
        mode:
          type: string
          enum:
            - full
            - metadata_only
            - unknown
        badgeLabel:
          type: string
        sourceSignal:
          type:
            - string
            - 'null'
    AssignmentCapture:
      type: object
      required:
        - issuePresent
        - orphanedAssignments
      properties:
        issuePresent:
          type: boolean
        fetchFailed:
          type: boolean
        captureReason:
          type:
            - string
            - 'null'
        orphanedAssignments:
          type: boolean
        assignmentCount:
          type:
            - integer
            - 'null'
    Fact:
      type: object
      required:
        - label
      properties:
        label:
          type: string
        description:
          type:
            - string
            - 'null'