openapi: 3.1.0
info:
  title: Baseline Compare Matrix Operator Mode Internal Surface Contract
  version: 0.2.0
  summary: Internal logical contract for adaptive operator-density rendering on the existing baseline compare matrix route
  description: |
    This contract is an internal planning artifact for Spec 191. The affected surface
    still renders HTML through Filament and Livewire. The schemas below define the
    bounded request-scoped presentation models and staged filter interactions that must
    be derivable from existing Spec 190 matrix truth before the operator-density
    refactor can render safely.
servers:
  - url: /internal
x-baseline-compare-operator-mode-consumers:
  - surface: baseline.compare.matrix
    sourceFiles:
      - apps/platform/app/Filament/Pages/BaselineCompareMatrix.php
      - apps/platform/resources/views/filament/pages/baseline-compare-matrix.blade.php
    mustRender:
      - reference
      - requested_vs_resolved_mode
      - presentation_state
      - support_surface_state
      - applied_filters
      - draft_filters
      - staged_filter_changes
      - tenant_summaries
      - dense_rows_or_compact_results
      - last_updated_at
      - auto_refresh_state
    mustAccept:
      - mode
      - policy_type
      - state
      - severity
      - tenant_sort
      - subject_sort
      - subject_key
    mustStage:
      - selectedPolicyTypes
      - selectedStates
      - selectedSeverities
      - tenantSort
      - subjectSort
paths:
  /admin/baseline-profiles/{profile}/compare-matrix:
    get:
      summary: Render the existing baseline compare matrix using adaptive operator-density presentation
      operationId: viewBaselineCompareOperatorMode
      parameters:
        - name: profile
          in: path
          required: true
          schema:
            type: integer
        - name: mode
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/PresentationMode'
        - name: policy_type
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
        - name: state
          in: query
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/MatrixCellState'
        - name: severity
          in: query
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/FindingSeverity'
        - name: tenant_sort
          in: query
          required: false
          schema:
            type: string
        - name: subject_sort
          in: query
          required: false
          schema:
            type: string
        - name: subject_key
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Rendered matrix plus adaptive operator-density read models
          content:
            text/html:
              schema:
                type: string
            application/vnd.tenantpilot.baseline-compare-operator-mode+json:
              schema:
                $ref: '#/components/schemas/BaselineCompareOperatorModeBundle'
        '403':
          description: Actor is in scope but lacks workspace baseline view capability
        '404':
          description: Workspace or baseline profile is outside actor scope
  /internal/workspaces/{workspace}/baseline-profiles/{profile}/compare-matrix/apply-filters:
    post:
      summary: Apply staged heavy filters to the operator-density matrix route
      operationId: applyBaselineCompareOperatorFilters
      parameters:
        - name: workspace
          in: path
          required: true
          schema:
            type: integer
        - name: profile
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MatrixFilterDraft'
      responses:
        '200':
          description: Updated operator-density bundle using the applied filter state
          content:
            application/vnd.tenantpilot.baseline-compare-operator-mode+json:
              schema:
                $ref: '#/components/schemas/BaselineCompareOperatorModeBundle'
        '403':
          description: Actor is in scope but lacks workspace baseline view capability
        '404':
          description: Workspace or baseline profile is outside actor scope
  /internal/workspaces/{workspace}/baseline-profiles/{profile}/compare-matrix/reset-filters:
    post:
      summary: Reset staged and applied heavy filters for the operator-density matrix route
      operationId: resetBaselineCompareOperatorFilters
      parameters:
        - name: workspace
          in: path
          required: true
          schema:
            type: integer
        - name: profile
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Updated operator-density bundle with default filter state restored
          content:
            application/vnd.tenantpilot.baseline-compare-operator-mode+json:
              schema:
                $ref: '#/components/schemas/BaselineCompareOperatorModeBundle'
        '403':
          description: Actor is in scope but lacks workspace baseline view capability
        '404':
          description: Workspace or baseline profile is outside actor scope
components:
  schemas:
    PresentationMode:
      type: string
      enum:
        - auto
        - dense
        - compact
    MatrixCellState:
      type: string
      enum:
        - match
        - differ
        - missing
        - ambiguous
        - not_compared
        - stale_result
    FindingSeverity:
      type: string
      enum:
        - low
        - medium
        - high
        - critical
    FreshnessState:
      type: string
      enum:
        - fresh
        - stale
        - never_compared
        - unknown
    TrustLevel:
      type: string
      enum:
        - trustworthy
        - limited_confidence
        - diagnostic_only
        - unusable
    AttentionLevel:
      type: string
      enum:
        - aligned
        - review
        - refresh_recommended
        - needs_attention
    MatrixReference:
      type: object
      additionalProperties: false
      required:
        - baselineProfileId
        - baselineProfileName
        - referenceState
        - assignedTenantCount
        - visibleTenantCount
      properties:
        baselineProfileId:
          type: integer
        baselineProfileName:
          type: string
        referenceSnapshotId:
          type:
            - integer
            - 'null'
        referenceState:
          type: string
        assignedTenantCount:
          type: integer
        visibleTenantCount:
          type: integer
    MatrixFilterDraft:
      type: object
      additionalProperties: false
      required:
        - selectedPolicyTypes
        - selectedStates
        - selectedSeverities
        - tenantSort
        - subjectSort
      properties:
        selectedPolicyTypes:
          type: array
          items:
            type: string
        selectedStates:
          type: array
          items:
            $ref: '#/components/schemas/MatrixCellState'
        selectedSeverities:
          type: array
          items:
            $ref: '#/components/schemas/FindingSeverity'
        tenantSort:
          type: string
        subjectSort:
          type: string
        focusedSubjectKey:
          type:
            - string
            - 'null'
    MatrixPresentationState:
      type: object
      additionalProperties: false
      required:
        - requestedMode
        - resolvedMode
        - visibleTenantCount
        - activeFilterCount
        - hasStagedFilterChanges
        - autoRefreshActive
        - lastUpdatedAt
        - canOverrideMode
        - compactModeAvailable
      properties:
        requestedMode:
          $ref: '#/components/schemas/PresentationMode'
        resolvedMode:
          type: string
          enum:
            - dense
            - compact
          description: |
            Final render mode after evaluating the requested route mode against the
            visible tenant count. A requested `compact` mode may still resolve to
            `dense` when more than one visible tenant remains in scope.
        visibleTenantCount:
          type: integer
        activeFilterCount:
          type: integer
        hasStagedFilterChanges:
          type: boolean
        autoRefreshActive:
          type: boolean
        lastUpdatedAt:
          type:
            - string
            - 'null'
          format: date-time
        canOverrideMode:
          type: boolean
        compactModeAvailable:
          type: boolean
    MatrixTenantSummary:
      type: object
      additionalProperties: false
      required:
        - tenantId
        - tenantName
        - freshnessState
        - differingCount
        - missingCount
        - ambiguousCount
        - trustLevel
      properties:
        tenantId:
          type: integer
        tenantName:
          type: string
        freshnessState:
          $ref: '#/components/schemas/FreshnessState'
        lastComparedAt:
          type:
            - string
            - 'null'
          format: date-time
        differingCount:
          type: integer
        missingCount:
          type: integer
        ambiguousCount:
          type: integer
        trustLevel:
          $ref: '#/components/schemas/TrustLevel'
        maxSeverity:
          type:
            - string
            - 'null'
    DenseCellView:
      type: object
      additionalProperties: false
      required:
        - tenantId
        - subjectKey
        - state
        - freshnessState
        - trustLevel
        - attentionLevel
      properties:
        tenantId:
          type: integer
        subjectKey:
          type: string
        state:
          $ref: '#/components/schemas/MatrixCellState'
        freshnessState:
          $ref: '#/components/schemas/FreshnessState'
        trustLevel:
          $ref: '#/components/schemas/TrustLevel'
        severity:
          type:
            - string
            - 'null'
        attentionLevel:
          $ref: '#/components/schemas/AttentionLevel'
        reasonSummary:
          type:
            - string
            - 'null'
        primaryDrilldownUrl:
          type:
            - string
            - 'null'
        secondaryDrilldownUrls:
          type: object
          additionalProperties:
            type: string
    DenseSubjectRowView:
      type: object
      additionalProperties: false
      required:
        - subjectKey
        - displayName
        - policyType
        - deviationBreadth
        - missingBreadth
        - ambiguousBreadth
        - trustLevel
        - cells
      properties:
        subjectKey:
          type: string
        displayName:
          type: string
        policyType:
          type: string
        baselineExternalId:
          type:
            - string
            - 'null'
        deviationBreadth:
          type: integer
        missingBreadth:
          type: integer
        ambiguousBreadth:
          type: integer
        maxSeverity:
          type:
            - string
            - 'null'
        trustLevel:
          $ref: '#/components/schemas/TrustLevel'
        cells:
          type: array
          items:
            $ref: '#/components/schemas/DenseCellView'
    CompactSubjectResultView:
      type: object
      additionalProperties: false
      required:
        - tenantId
        - subjectKey
        - displayName
        - policyType
        - state
        - freshnessState
        - trustLevel
      properties:
        tenantId:
          type: integer
        subjectKey:
          type: string
        displayName:
          type: string
        policyType:
          type: string
        state:
          $ref: '#/components/schemas/MatrixCellState'
        freshnessState:
          $ref: '#/components/schemas/FreshnessState'
        trustLevel:
          $ref: '#/components/schemas/TrustLevel'
        severity:
          type:
            - string
            - 'null'
        reasonSummary:
          type:
            - string
            - 'null'
        primaryDrilldownUrl:
          type:
            - string
            - 'null'
        runUrl:
          type:
            - string
            - 'null'
    MatrixSupportSurfaceState:
      type: object
      additionalProperties: false
      required:
        - legendMode
        - showActiveFilterSummary
        - showLastUpdated
        - showAutoRefreshHint
        - showBlockingRefreshState
      properties:
        legendMode:
          type: string
        showActiveFilterSummary:
          type: boolean
        showLastUpdated:
          type: boolean
        showAutoRefreshHint:
          type: boolean
        showBlockingRefreshState:
          type: boolean
    BaselineCompareOperatorModeBundle:
      type: object
      additionalProperties: false
      required:
        - reference
        - presentation
        - supportSurface
        - appliedFilters
        - draftFilters
        - tenantSummaries
      properties:
        reference:
          $ref: '#/components/schemas/MatrixReference'
        presentation:
          $ref: '#/components/schemas/MatrixPresentationState'
        supportSurface:
          $ref: '#/components/schemas/MatrixSupportSurfaceState'
        appliedFilters:
          $ref: '#/components/schemas/MatrixFilterDraft'
        draftFilters:
          $ref: '#/components/schemas/MatrixFilterDraft'
        tenantSummaries:
          type: array
          items:
            $ref: '#/components/schemas/MatrixTenantSummary'
        denseRows:
          type: array
          items:
            $ref: '#/components/schemas/DenseSubjectRowView'
        compactResults:
          type: array
          items:
            $ref: '#/components/schemas/CompactSubjectResultView'
            $ref: '#/components/schemas/CompactSubjectResultView'