openapi: 3.1.0
info:
  title: Governance Outcome Compression Surfaces Contract
  version: 1.0.0
  description: >-
    Internal reference contract for the rendered HTML surfaces affected by Spec 214.
    These routes continue to return HTML through Filament and Livewire. The vendor
    media types below document the structured compressed-outcome payloads that must
    be derivable before rendering. This is not a public API commitment.
paths:
  /admin/baseline-snapshots:
    get:
      summary: Baseline snapshot list
      responses:
        '200':
          description: Rendered baseline snapshot list page
          content:
            text/html:
              schema:
                type: string
            application/vnd.tenantpilot.baseline-snapshot-list+json:
              schema:
                $ref: '#/components/schemas/BaselineSnapshotListPage'
        '404':
          description: Workspace context is missing or the viewer is not entitled to the relevant scope
  /admin/baseline-snapshots/{record}:
    get:
      summary: Baseline snapshot detail
      parameters:
        - name: record
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Rendered baseline snapshot detail page
          content:
            text/html:
              schema:
                type: string
            application/vnd.tenantpilot.baseline-snapshot-detail+json:
              schema:
                $ref: '#/components/schemas/GovernanceArtifactDetailPage'
        '404':
          description: Snapshot is not visible because it does not exist or workspace entitlement is missing
  /admin/t/{tenant}/evidence/{snapshot}:
    get:
      summary: Evidence snapshot detail
      parameters:
        - name: tenant
          in: path
          required: true
          schema:
            type: string
        - name: snapshot
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Rendered evidence snapshot detail page
          content:
            text/html:
              schema:
                type: string
            application/vnd.tenantpilot.evidence-snapshot-detail+json:
              schema:
                $ref: '#/components/schemas/GovernanceArtifactDetailPage'
        '403':
          description: Viewer is in tenant scope but lacks required manage capability for actions
        '404':
          description: Snapshot is not visible because it does not exist or tenant entitlement is missing
  /admin/t/{tenant}/evidence:
    get:
      summary: Evidence snapshot list
      parameters:
        - name: tenant
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Rendered evidence snapshot list page
          content:
            text/html:
              schema:
                type: string
            application/vnd.tenantpilot.tenant-evidence-list+json:
              schema:
                $ref: '#/components/schemas/TenantArtifactListPage'
        '403':
          description: Viewer is in tenant scope but lacks required capability for list inspection
        '404':
          description: Tenant is not visible because it does not exist or tenant entitlement is missing
  /admin/t/{tenant}/reviews:
    get:
      summary: Tenant review list
      parameters:
        - name: tenant
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Rendered tenant review list page
          content:
            text/html:
              schema:
                type: string
            application/vnd.tenantpilot.tenant-review-list+json:
              schema:
                $ref: '#/components/schemas/TenantArtifactListPage'
        '403':
          description: Viewer is in tenant scope but lacks required capability for list inspection
        '404':
          description: Tenant is not visible because it does not exist or tenant entitlement is missing
  /admin/t/{tenant}/reviews/{review}:
    get:
      summary: Tenant review detail
      parameters:
        - name: tenant
          in: path
          required: true
          schema:
            type: string
        - name: review
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Rendered tenant review detail page
          content:
            text/html:
              schema:
                type: string
            application/vnd.tenantpilot.tenant-review-detail+json:
              schema:
                $ref: '#/components/schemas/GovernanceArtifactDetailPage'
        '403':
          description: Viewer is in tenant scope but lacks required manage capability for actions
        '404':
          description: Review is not visible because it does not exist or tenant entitlement is missing
  /admin/t/{tenant}/review-packs:
    get:
      summary: Review pack list
      parameters:
        - name: tenant
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Rendered review pack list page
          content:
            text/html:
              schema:
                type: string
            application/vnd.tenantpilot.review-pack-list+json:
              schema:
                $ref: '#/components/schemas/TenantArtifactListPage'
        '403':
          description: Viewer is in tenant scope but lacks required capability for list inspection
        '404':
          description: Tenant is not visible because it does not exist or tenant entitlement is missing
  /admin/t/{tenant}/review-packs/{pack}:
    get:
      summary: Review pack detail
      parameters:
        - name: tenant
          in: path
          required: true
          schema:
            type: string
        - name: pack
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Rendered review pack detail page
          content:
            text/html:
              schema:
                type: string
            application/vnd.tenantpilot.review-pack-detail+json:
              schema:
                $ref: '#/components/schemas/GovernanceArtifactDetailPage'
        '403':
          description: Viewer is in tenant scope but lacks required manage capability for actions
        '404':
          description: Pack is not visible because it does not exist or tenant entitlement is missing
  /admin/reviews:
    get:
      summary: Canonical review register
      responses:
        '200':
          description: Rendered review register page
          content:
            text/html:
              schema:
                type: string
            application/vnd.tenantpilot.review-register+json:
              schema:
                $ref: '#/components/schemas/ReviewRegisterPage'
        '404':
          description: Workspace context is missing or the viewer is not entitled to the relevant scope
  /admin/evidence/overview:
    get:
      summary: Canonical evidence overview
      responses:
        '200':
          description: Rendered evidence overview page
          content:
            text/html:
              schema:
                type: string
            application/vnd.tenantpilot.evidence-overview+json:
              schema:
                $ref: '#/components/schemas/EvidenceOverviewPage'
        '404':
          description: Workspace context is missing or the viewer is not entitled to the relevant scope
  /admin/operations/{run}:
    get:
      summary: Artifact-oriented operation run detail
      parameters:
        - name: run
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Rendered operation run detail page
          content:
            text/html:
              schema:
                type: string
            application/vnd.tenantpilot.artifact-operation-run-detail+json:
              schema:
                $ref: '#/components/schemas/OperationRunDetailPage'
        '403':
          description: Viewer is in scope but lacks required capability for related actions
        '404':
          description: Run is not visible because it does not exist or entitlement is missing
components:
  schemas:
    Badge:
      type: object
      required:
        - label
      properties:
        label:
          type: string
        color:
          type:
            - string
            - 'null'
        icon:
          type:
            - string
            - 'null'
        iconColor:
          type:
            - string
            - 'null'
    SecondaryFact:
      type: object
      required:
        - label
        - value
      properties:
        label:
          type: string
        value:
          type: string
        badge:
          anyOf:
            - $ref: '#/components/schemas/Badge'
            - type: 'null'
    CompressedGovernanceOutcome:
      type: object
      required:
        - surfaceFamily
        - decisionDirection
        - primaryLabel
        - primaryReason
        - nextActionText
        - primaryBadge
        - diagnosticsAvailable
      properties:
        surfaceFamily:
          type: string
          enum:
            - baseline_snapshot
            - evidence_snapshot
            - tenant_review
            - review_pack
            - review_register
            - evidence_overview
            - operation_run_artifact
        decisionDirection:
          type: string
          enum:
            - usable
            - publishable
            - internal_only
            - stale
            - blocked
            - follow_up_needed
            - historical_only
        primaryLabel:
          type: string
        primaryReason:
          type: string
        nextActionText:
          type: string
        primaryBadge:
          $ref: '#/components/schemas/Badge'
        secondaryFacts:
          type: array
          maxItems: 3
          items:
            $ref: '#/components/schemas/SecondaryFact'
        diagnosticsAvailable:
          type: boolean
        diagnosticsSummary:
          type:
            - string
            - 'null'
    GovernanceRow:
      type: object
      required:
        - recordId
        - subjectLabel
        - compressedOutcome
      properties:
        recordId:
          type: integer
        tenantId:
          type:
            - integer
            - 'null'
        subjectLabel:
          type: string
        viewUrl:
          type:
            - string
            - 'null'
        compressedOutcome:
          $ref: '#/components/schemas/CompressedGovernanceOutcome'
    BaselineSnapshotListPage:
      type: object
      required:
        - rows
      properties:
        rows:
          type: array
          items:
            $ref: '#/components/schemas/GovernanceRow'
    TenantArtifactListPage:
      type: object
      required:
        - rows
      properties:
        rows:
          type: array
          items:
            $ref: '#/components/schemas/GovernanceRow'
    EvidenceOverviewPage:
      type: object
      required:
        - rows
      properties:
        rows:
          type: array
          items:
            $ref: '#/components/schemas/GovernanceRow'
    ReviewRegisterPage:
      type: object
      required:
        - rows
      properties:
        rows:
          type: array
          items:
            $ref: '#/components/schemas/GovernanceRow'
    GovernanceArtifactDetailPage:
      type: object
      required:
        - recordId
        - canonicalNoun
        - compressedOutcome
      properties:
        recordId:
          type: integer
        canonicalNoun:
          type: string
        compressedOutcome:
          $ref: '#/components/schemas/CompressedGovernanceOutcome'
        diagnosticsSections:
          type: array
          items:
            type: string
    OperationRunDetailPage:
      type: object
      required:
        - runId
        - executionOutcome
        - compressedOutcome
      properties:
        runId:
          type: integer
        executionOutcome:
          $ref: '#/components/schemas/Badge'
        compressedOutcome:
          $ref: '#/components/schemas/CompressedGovernanceOutcome'
        relatedArtifactUrl:
          type:
            - string
            - 'null'
