openapi: 3.1.0
info:
  title: Governance Operation Run Summaries Contract
  version: 1.0.0
  description: >-
    Internal reference contract for Spec 220. These routes continue to return
    HTML through Filament and Livewire. The vendor media types below document
    the logical summary payloads that must be derivable before rendering. This
    is not a public API commitment.
paths:
  /admin/operations:
    get:
      summary: Canonical operations list entry point
      responses:
        '200':
          description: Rendered canonical operations list page
          content:
            text/html:
              schema:
                type: string
            application/vnd.tenantpilot.governance-operations-list+json:
              schema:
                $ref: '#/components/schemas/GovernanceOperationsListPage'
        '404':
          description: Workspace context is missing or the viewer is not entitled to the canonical monitoring scope
  /admin/operations/{run}:
    get:
      summary: Canonical governance operation run detail
      parameters:
        - name: run
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Rendered canonical governance run-detail page
          content:
            text/html:
              schema:
                type: string
            application/vnd.tenantpilot.governance-operation-run-detail+json:
              schema:
                $ref: '#/components/schemas/GovernanceOperationRunDetailPage'
        '403':
          description: Viewer is in scope but lacks required capability for a related action
        '404':
          description: Run is not visible because it does not exist or entitlement is missing
components:
  schemas:
    GovernanceOperationsListPage:
      type: object
      required:
        - activeContext
        - rowInspectModel
      properties:
        activeContext:
          type: object
          properties:
            workspaceScope:
              type: string
            tenantContextActive:
              type: boolean
        rowInspectModel:
          type: string
          enum:
            - row_click
        canonicalDetailRoute:
          type: string
          example: /admin/operations/44
    GovernanceOperationRunDetailPage:
      type: object
      required:
        - runId
        - canonicalOperationType
        - summary
        - diagnosticsAvailable
      properties:
        runId:
          type: integer
        canonicalOperationType:
          type: string
          enum:
            - baseline.capture
            - baseline.compare
            - tenant.evidence.snapshot.generate
            - tenant.review.compose
            - tenant.review_pack.generate
        artifactFamily:
          type:
            - string
            - 'null'
          enum:
            - baseline_snapshot
            - evidence_snapshot
            - tenant_review
            - review_pack
            - null
        summary:
          $ref: '#/components/schemas/GovernanceRunDiagnosticSummary'
        relatedNavigation:
          type: array
          items:
            $ref: '#/components/schemas/RelatedNavigationLink'
        diagnosticsAvailable:
          type: boolean
        diagnosticsSections:
          type: array
          items:
            $ref: '#/components/schemas/DiagnosticsSection'
    GovernanceRunDiagnosticSummary:
      type: object
      required:
        - headline
        - executionOutcomeLabel
        - artifactImpactLabel
        - primaryReason
        - nextActionText
      properties:
        headline:
          type: string
        executionOutcomeLabel:
          type: string
        artifactImpactLabel:
          type: string
        primaryReason:
          type: string
        affectedScaleCue:
          $ref: '#/components/schemas/AffectedScaleCue'
        nextActionText:
          type: string
        dominantCause:
          $ref: '#/components/schemas/DominantCauseBreakdown'
        secondaryFacts:
          type: array
          items:
            $ref: '#/components/schemas/SummaryFact'
    DominantCauseBreakdown:
      type: object
      required:
        - primaryLabel
        - primaryExplanation
      properties:
        primaryCode:
          type:
            - string
            - 'null'
        primaryLabel:
          type: string
        primaryExplanation:
          type: string
        secondaryCauses:
          type: array
          items:
            type: string
    AffectedScaleCue:
      type: object
      required:
        - label
        - value
        - source
      properties:
        label:
          type: string
        value:
          type: string
        source:
          type: string
          enum:
            - summary_counts
            - context
            - related_artifact_truth
        confidence:
          type: string
          enum:
            - exact
            - bounded
            - best_available
    SummaryFact:
      type: object
      required:
        - label
        - value
      properties:
        label:
          type: string
        value:
          type: string
        emphasis:
          type: string
          enum:
            - neutral
            - caution
            - blocked
    RelatedNavigationLink:
      type: object
      required:
        - label
        - visible
      properties:
        label:
          type: string
        href:
          type:
            - string
            - 'null'
        visible:
          type: boolean
        deniedReason:
          type:
            - string
            - 'null'
    DiagnosticsSection:
      type: object
      required:
        - title
        - kind
      properties:
        title:
          type: string
        kind:
          type: string
          enum:
            - supporting_detail
            - count_diagnostics
            - failure_payload
            - evidence_gap_detail
            - type_specific_detail
        collapsedByDefault:
          type: boolean