openapi: 3.1.0
info:
  title: Operator Explanation Layer Contract
  version: 1.0.0
  summary: Logical operator-facing read contract for explanation-first governance surfaces
  description: |
    This contract captures the intended read-model semantics for Spec 161.
    These are logical contracts for existing Filament and Livewire-backed surfaces,
    not a commitment to public REST endpoints.
servers:
  - url: https://tenantpilot.local
tags:
  - name: BaselineCompare
  - name: GovernanceRuns
  - name: GovernanceArtifacts
paths:
  /tenants/{tenantId}/baseline-compare/explanation:
    get:
      tags: [BaselineCompare]
      summary: Read baseline compare explanation model
      description: Returns the operator explanation pattern for the current baseline compare state, including trustworthiness, count semantics, and diagnostics availability.
      parameters:
        - $ref: '#/components/parameters/TenantId'
      responses:
        '200':
          description: Explanation model returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GovernanceResultSurfaceModel'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /operation-runs/{operationRunId}/explanation:
    get:
      tags: [GovernanceRuns]
      summary: Read governance run explanation model
      description: Returns the operator explanation pattern and secondary diagnostics for a governance-oriented operation run.
      parameters:
        - $ref: '#/components/parameters/OperationRunId'
      responses:
        '200':
          description: Run explanation model returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GovernanceResultSurfaceModel'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /governance-artifacts/{artifactType}/{artifactId}/explanation:
    get:
      tags: [GovernanceArtifacts]
      summary: Read governance artifact explanation model
      description: Returns the primary explanation block, secondary truth dimensions, and diagnostics visibility for a governance artifact detail surface.
      parameters:
        - $ref: '#/components/parameters/ArtifactType'
        - $ref: '#/components/parameters/ArtifactId'
      responses:
        '200':
          description: Artifact explanation model returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GovernanceResultSurfaceModel'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

components:
  parameters:
    TenantId:
      name: tenantId
      in: path
      required: true
      schema:
        type: integer
    OperationRunId:
      name: operationRunId
      in: path
      required: true
      schema:
        type: integer
    ArtifactType:
      name: artifactType
      in: path
      required: true
      schema:
        type: string
        enum: [baseline_snapshot, evidence_snapshot, tenant_review, review_pack]
    ArtifactId:
      name: artifactId
      in: path
      required: true
      schema:
        type: integer

  responses:
    Forbidden:
      description: Member lacks the required capability in the already established scope
    NotFound:
      description: Workspace or tenant scope is not entitled, or the requested record is not visible in that scope

  schemas:
    GovernanceResultSurfaceModel:
      type: object
      required:
        - primaryPattern
        - secondaryTruth
        - diagnosticsAvailable
      properties:
        primaryPattern:
          $ref: '#/components/schemas/OperatorExplanationPattern'
        secondaryTruth:
          type: array
          items:
            $ref: '#/components/schemas/TruthDimension'
        diagnosticsAvailable:
          type: boolean
        diagnosticsSummary:
          type: string
          nullable: true
        actions:
          type: array
          items:
            type: object
            required: [label, mutationScope]
            properties:
              label:
                type: string
              mutationScope:
                type: string
                enum: [tenantpilot_only, microsoft_tenant, simulation_only, none]
              enabled:
                type: boolean

    OperatorExplanationPattern:
      type: object
      required:
        - headline
        - executionOutcome
        - evaluationResult
        - reliabilityLevel
        - nextAction
        - countDescriptors
      properties:
        headline:
          type: string
        executionOutcome:
          type: string
          examples: [completed, completed_with_follow_up, failed, blocked]
        evaluationResult:
          type: string
          examples: [full_result, incomplete_result, suppressed_result, no_result, unavailable]
        reliabilityLevel:
          type: string
          enum: [trustworthy, limited_confidence, diagnostic_only, unusable]
        reliabilityStatement:
          type: string
        coverageStatement:
          type: string
          nullable: true
        dominantCause:
          type: object
          nullable: true
          properties:
            code:
              type: string
              nullable: true
            label:
              type: string
            explanation:
              type: string
        nextAction:
          type: object
          required: [category, text]
          properties:
            category:
              type: string
              enum:
                - none
                - observe
                - retry_later
                - fix_prerequisite
                - refresh_or_sync
                - review_evidence_gaps
                - manual_validate
                - escalate
            text:
              type: string
        countDescriptors:
          type: array
          items:
            $ref: '#/components/schemas/CountDescriptor'
        diagnosticsAvailable:
          type: boolean

    CountDescriptor:
      type: object
      required: [label, value, role, visibilityTier]
      properties:
        label:
          type: string
        value:
          type: integer
        role:
          type: string
          enum: [execution, evaluation_output, coverage, reliability_signal]
        qualifier:
          type: string
          nullable: true
        visibilityTier:
          type: string
          enum: [primary, diagnostic]

    TruthDimension:
      type: object
      required: [dimension, value, visibilityTier]
      properties:
        dimension:
          type: string
          examples: [artifact_existence, content, freshness, support_level, publication_readiness, actionability]
        value:
          type: string
        visibilityTier:
          type: string
          enum: [primary, secondary, diagnostic]
        explanation:
          type: string
          nullable: true