openapi: 3.1.0
info:
  title: Verification Report Family Internal Surface Contract
  version: 0.1.0
  summary: Internal logical contract for the shared Verification Report family
  description: |
    This contract is an internal planning artifact for Spec 197. It documents the
    family-owned verification surface used across operation detail, onboarding,
    and tenant verification widget hosts. Rendered routes still return HTML.
    The structured schemas below describe the internal surface contract and the
    allowed host-variation boundaries. This does not add a public HTTP API.
servers:
  - url: /internal
x-family-consumers:
  - surface: operation_run_detail
    source: verification_report_surface
    accessPattern: detail_safe
    guardScope:
      - apps/platform/app/Filament/Resources/OperationRunResource.php
      - apps/platform/resources/views/filament/components/verification-report-viewer.blade.php
    requiredMarkers:
      - VerificationReportViewer::surface
      - data-shared-detail-family="verification-report"
      - data-host-kind="operation_run_detail"
      - data-shared-zone="summary"
      - data-shared-zone="diagnostics"
  - surface: onboarding_verification_step
    source: verification_report_surface
    accessPattern: form_embedded_safe
    guardScope:
      - apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php
      - apps/platform/resources/views/filament/forms/components/managed-tenant-onboarding-verification-report.blade.php
    requiredMarkers:
      - VerificationReportViewer::surface
      - data-shared-detail-family="verification-report"
      - data-host-kind="onboarding_wizard"
      - assistActionName
      - technicalDetailsActionName
    x-forbiddenMarkers:
      - needle: "x-data=\"{ tab: 'issues' }\""
        max: 0
  - surface: tenant_verification_widget
    source: verification_report_surface
    accessPattern: widget_safe
    guardScope:
      - apps/platform/app/Filament/Widgets/Tenant/TenantVerificationReport.php
      - apps/platform/resources/views/filament/widgets/tenant/tenant-verification-report.blade.php
    requiredMarkers:
      - VerificationReportViewer::surface
      - data-shared-detail-family="verification-report"
      - data-host-kind="tenant_widget"
      - data-shared-zone="summary"
      - data-shared-zone="diagnostics"
paths:
  /ui-contracts/verification-report/resolve:
    get:
      summary: Resolve the shared Verification Report family contract for one host
      operationId: resolveVerificationReportSurface
      parameters:
        - name: host
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/VerificationHostKind'
        - name: runId
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Shared Verification Report surface contract resolved for the current host context
          content:
            application/vnd.tenantpilot.verification-report-surface+json:
              schema:
                $ref: '#/components/schemas/VerificationReportSurfaceContract'
        '403':
          description: Actor is in scope but lacks the capability required for host-owned actions
        '404':
          description: Run or tenant scope is not visible in the current workspace or tenant context
  /admin/onboarding:
    get:
      summary: Onboarding verification host using the shared Verification Report family
      operationId: viewOnboardingVerificationHost
      responses:
        '200':
          description: Rendered onboarding verification step with shared verification family core
          content:
            text/html:
              schema:
                type: string
  /admin/t/{tenant}:
    get:
      summary: Tenant verification widget host using the shared Verification Report family
      operationId: viewTenantVerificationWidgetHost
      parameters:
        - name: tenant
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Rendered tenant detail page containing the shared verification family widget
          content:
            text/html:
              schema:
                type: string
components:
  schemas:
    VerificationHostKind:
      type: string
      enum:
        - operation_run_detail
        - onboarding_wizard
        - tenant_widget
    VerificationCoreState:
      type: string
      enum:
        - unavailable
        - completed
    VerificationActionKind:
      type: string
      enum:
        - navigation
        - assist
        - acknowledge
        - refresh
        - technical_details
    VerificationHostVariation:
      type: object
      additionalProperties: false
      required:
        - ownsNoRunState
        - ownsActiveState
        - supportsAssist
        - supportsAcknowledge
        - supportsTechnicalDetailsTrigger
      properties:
        ownsNoRunState:
          type: boolean
        ownsActiveState:
          type: boolean
        supportsAssist:
          type: boolean
        supportsAcknowledge:
          type: boolean
        supportsTechnicalDetailsTrigger:
          type: boolean
    VerificationAction:
      type: object
      additionalProperties: false
      required:
        - kind
        - label
        - ownedByHost
      properties:
        kind:
          $ref: '#/components/schemas/VerificationActionKind'
        label:
          type: string
        ownedByHost:
          type: boolean
    VerificationViewZone:
      type: object
      additionalProperties: false
      required:
        - key
        - label
        - defaultVisible
      properties:
        key:
          type: string
        label:
          type: string
        defaultVisible:
          type: boolean
        optional:
          type: boolean
    VerificationNextStepPlacement:
      type: string
      enum:
        - shared_zone
        - host_action_zone
    VerificationNextStep:
      type: object
      additionalProperties: false
      required:
        - label
        - placement
        - ownedByHost
      properties:
        label:
          type: string
        placement:
          $ref: '#/components/schemas/VerificationNextStepPlacement'
        ownedByHost:
          type: boolean
        actionKind:
          oneOf:
            - $ref: '#/components/schemas/VerificationActionKind'
            - type: 'null'
    VerificationOptionalZone:
      type: string
      enum:
        - technical_details
        - change_indicator
        - previous_run_context
    VerificationIssueGroup:
      type: object
      additionalProperties: false
      required:
        - label
        - checks
      properties:
        label:
          type: string
        checks:
          type: array
          items:
            type: object
    VerificationDiagnostics:
      type: object
      additionalProperties: false
      required:
        - hasTechnicalZone
      properties:
        hasTechnicalZone:
          type: boolean
        fingerprint:
          type:
            - string
            - 'null'
        previousRunUrl:
          type:
            - string
            - 'null'
        operationRunId:
          type:
            - integer
            - 'null'
    VerificationReportSurfaceContract:
      type: object
      additionalProperties: false
      required:
        - hostKind
        - coreState
        - summary
        - issueGroups
        - passedChecks
        - diagnostics
        - viewZones
        - nextSteps
        - hostVariation
      properties:
        hostKind:
          $ref: '#/components/schemas/VerificationHostKind'
        coreState:
          $ref: '#/components/schemas/VerificationCoreState'
        summary:
          type: object
          additionalProperties: false
          required:
            - overallLabel
            - counts
          properties:
            overallLabel:
              type: string
            counts:
              type: object
              additionalProperties:
                type: integer
        issueGroups:
          type: array
          items:
            $ref: '#/components/schemas/VerificationIssueGroup'
        passedChecks:
          type: array
          items:
            type: object
        diagnostics:
          $ref: '#/components/schemas/VerificationDiagnostics'
        viewZones:
          type: array
          items:
            $ref: '#/components/schemas/VerificationViewZone'
        nextSteps:
          type: array
          items:
            $ref: '#/components/schemas/VerificationNextStep'
        hostActions:
          type: array
          items:
            $ref: '#/components/schemas/VerificationAction'
        hostVariation:
          $ref: '#/components/schemas/VerificationHostVariation'
        optionalZones:
          type: array
          items:
            $ref: '#/components/schemas/VerificationOptionalZone'
        emptyState:
          type:
            - object
            - 'null'