openapi: 3.1.0
info:
  title: Evidence Review Trust Surfaces Contract
  version: 1.0.0
  description: >-
    Internal reference contract for the rendered HTML surfaces affected by Spec 174.
    These routes continue to return HTML through Filament and Livewire. The vendor
    media types below document the structured truth payloads that must be derivable
    before rendering. This is not a public API commitment.
paths:
  /admin/evidence/overview:
    get:
      summary: Canonical evidence overview
      description: >-
        Returns the rendered evidence overview for entitled tenants in the current workspace.
        The vendor media type documents the derived row contract used to communicate
        artifact truth, freshness, and next steps.
      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/reviews:
    get:
      summary: Canonical review register
      description: >-
        Returns the rendered review register for entitled tenants in the current workspace.
        The vendor media type documents the row-level trust and publication contract.
      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/t/{tenant}/evidence/{snapshot}:
    get:
      summary: Tenant-scoped 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/EvidenceSnapshotDetailPage'
        '403':
          description: Viewer is in tenant scope but lacks the required manage capability for actions
        '404':
          description: Snapshot is not visible because it does not exist or tenant entitlement is missing
  /admin/t/{tenant}/reviews/{review}:
    get:
      summary: Tenant-scoped 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/TenantReviewDetailPage'
        '403':
          description: Viewer is in tenant scope but lacks the 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/{pack}:
    get:
      summary: Tenant-scoped 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/ReviewPackDetailPage'
        '403':
          description: Viewer is in tenant scope but lacks the required manage capability for actions
        '404':
          description: Review pack is not visible because it does not exist or tenant entitlement is missing
components:
  schemas:
    ArtifactTruthSummary:
      type: object
      required:
        - primaryLabel
        - contentState
        - freshnessState
        - actionability
      properties:
        primaryLabel:
          type: string
        primaryExplanation:
          type:
            - string
            - 'null'
        contentState:
          type: string
        freshnessState:
          type: string
          enum:
            - current
            - stale
            - unknown
        publicationReadiness:
          type:
            - string
            - 'null'
          enum:
            - publishable
            - internal_only
            - blocked
        actionability:
          type: string
          enum:
            - none
            - optional
            - required
        nextActionLabel:
          type:
            - string
            - 'null'
        nextActionUrl:
          type:
            - string
            - 'null'
        diagnosticLabel:
          type:
            - string
            - 'null'
    Badge:
      type: object
      required:
        - label
      properties:
        label:
          type: string
        color:
          type:
            - string
            - 'null'
        icon:
          type:
            - string
            - 'null'
    EvidenceOverviewRow:
      type: object
      required:
        - tenantName
        - tenantId
        - snapshotId
        - completenessState
        - artifactTruth
        - freshness
        - nextStep
      properties:
        tenantName:
          type: string
        tenantId:
          type: integer
        snapshotId:
          type: integer
        completenessState:
          type: string
        generatedAt:
          type:
            - string
            - 'null'
          format: date-time
        missingDimensions:
          type: integer
        staleDimensions:
          type: integer
        artifactTruth:
          $ref: '#/components/schemas/ArtifactTruthSummary'
        freshness:
          $ref: '#/components/schemas/Badge'
        nextStep:
          type: string
        viewUrl:
          type:
            - string
            - 'null'
    ReviewRegisterRow:
      type: object
      required:
        - tenantName
        - tenantId
        - reviewId
        - status
        - completenessState
        - artifactTruth
        - publication
        - nextStep
      properties:
        tenantName:
          type: string
        tenantId:
          type: integer
        reviewId:
          type: integer
        status:
          type: string
        completenessState:
          type: string
        generatedAt:
          type:
            - string
            - 'null'
          format: date-time
        publishedAt:
          type:
            - string
            - 'null'
          format: date-time
        artifactTruth:
          $ref: '#/components/schemas/ArtifactTruthSummary'
        publication:
          $ref: '#/components/schemas/Badge'
        nextStep:
          type: string
        viewUrl:
          type:
            - string
            - 'null'
    EvidenceOverviewPage:
      type: object
      required:
        - rows
      properties:
        rows:
          type: array
          items:
            $ref: '#/components/schemas/EvidenceOverviewRow'
    ReviewRegisterPage:
      type: object
      required:
        - rows
      properties:
        rows:
          type: array
          items:
            $ref: '#/components/schemas/ReviewRegisterRow'
    EvidenceSnapshotDetailPage:
      type: object
      required:
        - recordId
        - tenantId
        - completenessState
        - artifactTruth
      properties:
        recordId:
          type: integer
        tenantId:
          type: integer
        status:
          type: string
        completenessState:
          type: string
        generatedAt:
          type:
            - string
            - 'null'
          format: date-time
        artifactTruth:
          $ref: '#/components/schemas/ArtifactTruthSummary'
        linkedReviewUrl:
          type:
            - string
            - 'null'
        linkedRunUrl:
          type:
            - string
            - 'null'
    TenantReviewDetailPage:
      type: object
      required:
        - recordId
        - tenantId
        - status
        - completenessState
        - artifactTruth
      properties:
        recordId:
          type: integer
        tenantId:
          type: integer
        status:
          type: string
        completenessState:
          type: string
        generatedAt:
          type:
            - string
            - 'null'
          format: date-time
        publishedAt:
          type:
            - string
            - 'null'
          format: date-time
        artifactTruth:
          $ref: '#/components/schemas/ArtifactTruthSummary'
        linkedEvidenceUrl:
          type:
            - string
            - 'null'
        linkedPackUrl:
          type:
            - string
            - 'null'
    ReviewPackDetailPage:
      type: object
      required:
        - recordId
        - tenantId
        - status
        - artifactTruth
      properties:
        recordId:
          type: integer
        tenantId:
          type: integer
        status:
          type: string
        generatedAt:
          type:
            - string
            - 'null'
          format: date-time
        expiresAt:
          type:
            - string
            - 'null'
          format: date-time
        artifactTruth:
          $ref: '#/components/schemas/ArtifactTruthSummary'
        linkedReviewUrl:
          type:
            - string
            - 'null'
        linkedEvidenceUrl:
          type:
            - string
            - 'null'