openapi: 3.1.0
info:
  title: Governance Artifact Truth Internal Contract
  version: 0.1.0
  summary: Internal planning contract for Spec 158 operator-surface read models.
  description: |
    This contract documents the normalized truth-envelope expected by the first
    implementation slice for baseline snapshots, evidence snapshots, tenant
    reviews, review packs, and artifact-targeted operation runs. These paths map
    to existing Filament surfaces and internal action handlers; they are not a
    commitment to a public JSON API.
servers:
  - url: /admin
paths:
  /baseline-snapshots:
    get:
      summary: List workspace baseline snapshots with normalized truth summaries
      operationId: listBaselineSnapshotsWithTruth
      responses:
        '200':
          description: Baseline snapshot list rows
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactCollectionResponse'
  /baseline-snapshots/{snapshotId}:
    get:
      summary: Read one workspace baseline snapshot with truth envelope and diagnostics
      operationId: viewBaselineSnapshotWithTruth
      parameters:
        - $ref: '#/components/parameters/SnapshotId'
      responses:
        '200':
          description: Baseline snapshot detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactDetailResponse'
  /evidence/overview:
    get:
      summary: List canonical workspace evidence rows limited to entitled tenants
      operationId: listEvidenceOverviewWithTruth
      parameters:
        - in: query
          name: tenant_id
          schema:
            type: integer
          required: false
      responses:
        '200':
          description: Canonical evidence overview rows
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactCollectionResponse'
  /t/{tenantId}/evidence:
    get:
      summary: List tenant evidence snapshots with truth summaries
      operationId: listEvidenceSnapshotsWithTruth
      parameters:
        - $ref: '#/components/parameters/TenantId'
      responses:
        '200':
          description: Evidence snapshot list rows
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactCollectionResponse'
  /t/{tenantId}/evidence/{snapshotId}:
    get:
      summary: Read one evidence snapshot with truth envelope, per-dimension state, and diagnostics
      operationId: viewEvidenceSnapshotWithTruth
      parameters:
        - $ref: '#/components/parameters/TenantId'
        - $ref: '#/components/parameters/SnapshotId'
      responses:
        '200':
          description: Evidence snapshot detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactDetailResponse'
  /reviews:
    get:
      summary: List canonical review register rows limited to entitled tenants
      operationId: listReviewRegisterWithTruth
      parameters:
        - in: query
          name: tenant_id
          schema:
            type: integer
          required: false
      responses:
        '200':
          description: Canonical review register rows
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactCollectionResponse'
  /t/{tenantId}/reviews:
    get:
      summary: List tenant reviews with lifecycle, completeness, and publication truth
      operationId: listTenantReviewsWithTruth
      parameters:
        - $ref: '#/components/parameters/TenantId'
      responses:
        '200':
          description: Tenant review list rows
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactCollectionResponse'
  /t/{tenantId}/reviews/{reviewId}:
    get:
      summary: Read one tenant review with truth envelope and blocker explanations
      operationId: viewTenantReviewWithTruth
      parameters:
        - $ref: '#/components/parameters/TenantId'
        - $ref: '#/components/parameters/ReviewId'
      responses:
        '200':
          description: Tenant review detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactDetailResponse'
  /t/{tenantId}/review-packs:
    get:
      summary: List review packs with lifecycle and provenance truth
      operationId: listReviewPacksWithTruth
      parameters:
        - $ref: '#/components/parameters/TenantId'
      responses:
        '200':
          description: Review-pack list rows
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactCollectionResponse'
  /t/{tenantId}/review-packs/{packId}:
    get:
      summary: Read one review pack with truth envelope, provenance, and diagnostics
      operationId: viewReviewPackWithTruth
      parameters:
        - $ref: '#/components/parameters/TenantId'
        - $ref: '#/components/parameters/PackId'
      responses:
        '200':
          description: Review-pack detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactDetailResponse'
  /operations/{runId}:
    get:
      summary: Read canonical artifact-targeted run detail with normalized artifact result
      operationId: viewArtifactRunWithTruth
      parameters:
        - $ref: '#/components/parameters/RunId'
      responses:
        '200':
          description: Operation-run detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactRunDetailResponse'
components:
  parameters:
    TenantId:
      in: path
      name: tenantId
      required: true
      schema:
        type: integer
    SnapshotId:
      in: path
      name: snapshotId
      required: true
      schema:
        type: integer
    ReviewId:
      in: path
      name: reviewId
      required: true
      schema:
        type: integer
    PackId:
      in: path
      name: packId
      required: true
      schema:
        type: integer
    RunId:
      in: path
      name: runId
      required: true
      schema:
        type: integer
  schemas:
    ArtifactCollectionResponse:
      type: object
      required:
        - rows
      properties:
        rows:
          type: array
          items:
            $ref: '#/components/schemas/ArtifactSummaryRow'
    ArtifactDetailResponse:
      type: object
      required:
        - artifact
        - truth
      properties:
        artifact:
          type: object
          additionalProperties: true
        truth:
          $ref: '#/components/schemas/ArtifactTruthEnvelope'
        diagnostics:
          type: object
          additionalProperties: true
    ArtifactRunDetailResponse:
      allOf:
        - $ref: '#/components/schemas/ArtifactDetailResponse'
        - type: object
          properties:
            run:
              type: object
              additionalProperties: true
    ArtifactSummaryRow:
      type: object
      required:
        - artifactKey
        - artifactFamily
        - truth
      properties:
        artifactKey:
          type: string
        artifactFamily:
          type: string
          enum:
            - baseline_snapshot
            - evidence_snapshot
            - tenant_review
            - review_pack
            - artifact_run
        displayTitle:
          type: string
        tenantName:
          type:
            - string
            - 'null'
        truth:
          $ref: '#/components/schemas/ArtifactTruthEnvelope'
    ArtifactTruthEnvelope:
      type: object
      required:
        - artifactFamily
        - artifactExistence
        - contentState
        - freshnessState
        - supportState
        - actionability
        - primaryLabel
      properties:
        artifactFamily:
          type: string
        executionOutcome:
          type:
            - string
            - 'null'
          enum:
            - pending
            - succeeded
            - partially_succeeded
            - blocked
            - failed
            - null
        artifactExistence:
          type: string
          enum:
            - not_created
            - historical_only
            - created
            - created_but_not_usable
        contentState:
          type: string
          enum:
            - trusted
            - partial
            - missing_input
            - metadata_only
            - reference_only
            - empty
            - unsupported
        freshnessState:
          type: string
          enum:
            - current
            - stale
            - unknown
        publicationReadiness:
          type:
            - string
            - 'null'
          enum:
            - not_applicable
            - internal_only
            - publishable
            - blocked
            - null
        supportState:
          type: string
          enum:
            - normal
            - limited_support
        actionability:
          type: string
          enum:
            - none
            - optional
            - required
        primaryLabel:
          type: string
        primaryExplanation:
          type:
            - string
            - 'null'
        reason:
          $ref: '#/components/schemas/ArtifactTruthCause'
        nextAction:
          $ref: '#/components/schemas/ArtifactTruthNextAction'
        dimensions:
          type: array
          items:
            $ref: '#/components/schemas/ArtifactTruthDimension'
    ArtifactTruthDimension:
      type: object
      required:
        - axis
        - state
        - label
        - classification
      properties:
        axis:
          type: string
          enum:
            - execution_outcome
            - artifact_existence
            - content_fidelity
            - data_freshness
            - publication_readiness
            - support_maturity
            - operator_actionability
        state:
          type: string
        label:
          type: string
        classification:
          type: string
          enum:
            - primary
            - secondary
            - diagnostic
        badgeDomain:
          type:
            - string
            - 'null'
        badgeState:
          type:
            - string
            - 'null'
    ArtifactTruthCause:
      type: object
      properties:
        reasonCode:
          type:
            - string
            - 'null'
        operatorLabel:
          type:
            - string
            - 'null'
        shortExplanation:
          type:
            - string
            - 'null'
        diagnosticCode:
          type:
            - string
            - 'null'
        nextSteps:
          type: array
          items:
            type: string
    ArtifactTruthNextAction:
      type: object
      properties:
        label:
          type:
            - string
            - 'null'
        url:
          type:
            - string
            - 'null'
        required:
          type: boolean