openapi: 3.1.0
info:
  title: Baseline Summary Surface Contract
  version: 1.0.0
  description: >-
    Internal contract for baseline compare summary semantics across tenant dashboard,
    Baseline Compare landing, findings-adjacent warning surfaces, and canonical run-detail alignment.
servers:
  - url: /
paths:
  /admin:
    get:
      summary: Tenant dashboard baseline summary contract
      description: >-
        HTML tenant dashboard surface whose embedded baseline summary semantics must obey the shared summary assessment.
      responses:
        '200':
          description: Dashboard rendered with an embedded baseline summary assessment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantDashboardBaselineSummary'
  /admin/baseline-compare:
    get:
      summary: Baseline Compare landing summary contract
      description: >-
        Landing surface for the latest baseline compare result. The primary summary must not exceed the trust carried by the underlying explanation.
      responses:
        '200':
          description: Landing page rendered with primary summary assessment and diagnostics links
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaselineLandingSummary'
  /admin/findings:
    get:
      summary: Findings-adjacent baseline warning contract
      description: >-
        Findings context that may display a coverage or evidence caution banner derived from the same summary assessment.
      responses:
        '200':
          description: Findings page rendered with optional baseline summary caution
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaselineBannerSummary'
  /admin/operations/{run}:
    get:
      summary: Canonical baseline compare run-detail reference contract
      description: >-
        Canonical run detail remains the deepest truth surface. Compact summaries may not be more optimistic than this contract.
      parameters:
        - name: run
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Run detail rendered with baseline compare truth semantics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaselineRunDetailReference'
components:
  schemas:
    SummaryStateFamily:
      type: string
      enum:
        - positive
        - caution
        - stale
        - action_required
        - unavailable
        - in_progress
    TrustworthinessLevel:
      type: string
      enum:
        - trustworthy
        - limited_confidence
        - diagnostic_only
        - unusable
    EvaluationResult:
      type: string
      description: >-
        `failed_result` represents a compare execution that completed without a usable decision-grade artifact
        and therefore must map to an investigation-oriented `action_required` summary state rather than
        `unavailable`.
      enum:
        - full_result
        - no_result
        - incomplete_result
        - failed_result
        - suppressed_result
        - unavailable
    EvidenceImpact:
      type: string
      enum:
        - none
        - coverage_warning
        - evidence_gap
        - stale_result
        - suppressed_output
        - unavailable
    NextAction:
      type: object
      required:
        - label
        - target
      properties:
        label:
          type: string
        target:
          type: string
          enum:
            - landing
            - findings
            - run
            - none
    BaselineSummaryAssessment:
      type: object
      description: >-
        Shared compact-summary contract. If `evaluationResult` is `failed_result`, `stateFamily` must be
        `action_required` and `nextAction.target` must not be `none`.
      required:
        - stateFamily
        - headline
        - positiveClaimAllowed
        - trustworthinessLevel
        - evaluationResult
        - evidenceImpact
        - nextAction
      properties:
        stateFamily:
          $ref: '#/components/schemas/SummaryStateFamily'
        headline:
          type: string
        supportingMessage:
          type: string
          nullable: true
        tone:
          type: string
        positiveClaimAllowed:
          type: boolean
        trustworthinessLevel:
          $ref: '#/components/schemas/TrustworthinessLevel'
        evaluationResult:
          $ref: '#/components/schemas/EvaluationResult'
        evidenceImpact:
          $ref: '#/components/schemas/EvidenceImpact'
        findingsVisibleCount:
          type: integer
          minimum: 0
        highSeverityCount:
          type: integer
          minimum: 0
        reasonCode:
          type: string
          nullable: true
        lastComparedLabel:
          type: string
          nullable: true
        nextAction:
          $ref: '#/components/schemas/NextAction'
    TenantDashboardBaselineSummary:
      type: object
      required:
        - widget
        - needsAttention
      properties:
        widget:
          $ref: '#/components/schemas/BaselineSummaryAssessment'
        needsAttention:
          $ref: '#/components/schemas/BaselineSummaryAssessment'
        kpiCards:
          type: array
          description: Quantitative indicators only; not claim-bearing semantics.
          items:
            type: object
            required:
              - label
              - value
            properties:
              label:
                type: string
              value:
                type: integer
                minimum: 0
    BaselineLandingSummary:
      type: object
      required:
        - primarySummary
      properties:
        primarySummary:
          $ref: '#/components/schemas/BaselineSummaryAssessment'
        diagnosticsAvailable:
          type: boolean
        runLinkAvailable:
          type: boolean
        findingsLinkAvailable:
          type: boolean
    BaselineBannerSummary:
      type: object
      required:
        - shouldShow
      properties:
        shouldShow:
          type: boolean
        bannerSummary:
          allOf:
            - $ref: '#/components/schemas/BaselineSummaryAssessment'
          nullable: true
    BaselineRunDetailReference:
      type: object
      required:
        - primarySummary
      properties:
        primarySummary:
          $ref: '#/components/schemas/BaselineSummaryAssessment'
        semanticCeiling:
          type: boolean
          description: Always true for the canonical detail; compact surfaces may not exceed this confidence.
x-tenantpilot-notes:
  - These routes render HTML in practice; the schema models the internal summary payload that their views must honor.
  - No new HTTP endpoints are introduced by this feature.