openapi: 3.1.0
info:
  title: Operation Run Active-State Visibility Logical Contract
  version: 1.0.0
  description: |
    Internal logical contract for Spec 233. This does not introduce a new public API.
    It documents the operator-visible active-state payload semantics that existing
    Filament and Livewire surfaces derive from current OperationRun lifecycle truth.
servers:
  - url: https://logical.tenantpilot.internal
    description: Logical contract namespace only
tags:
  - name: TenantActivity
  - name: WorkspaceMonitoring
  - name: CanonicalRunDetail
paths:
  /admin/t/{tenant}/dashboard:
    get:
      tags: [TenantActivity]
      summary: Logical tenant activity summary contract
      description: |
        Represents the active-state payload that tenant dashboard activity and attention
        surfaces must expose. Actual implementation is HTML/Filament, not JSON.
      operationId: getTenantDashboardOperationActivitySummary
      x-logical-contract: true
      parameters:
        - $ref: '#/components/parameters/TenantId'
      responses:
        '200':
          description: Active-state summary for tenant-visible runs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantActivityOperationsSummary'
        '404':
          description: Tenant not visible to the current operator
  /admin/t/{tenant}/operations/progress:
    get:
      tags: [TenantActivity]
      summary: Logical tenant active-progress overlay contract
      description: |
        Represents the visible-active payload used by the tenant-local progress overlay.
        Stale-active runs remain active for visibility and polling purposes, and
        their compact elevation is rendered through the shared badge and Ops UX presenter path.
      operationId: getTenantOperationProgressOverlay
      x-logical-contract: true
      parameters:
        - $ref: '#/components/parameters/TenantId'
      responses:
        '200':
          description: Active progress payload for tenant-scoped runs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantOperationProgressOverlay'
        '403':
          description: Operator is a member but lacks capability to view operation runs
        '404':
          description: Tenant not visible to the current operator
  /admin/operations:
    get:
      tags: [WorkspaceMonitoring]
      summary: Logical canonical operations list contract
      description: |
        Represents the row-level semantics required by the canonical operations list.
        Existing tenant prefilter continuity may be preserved, but active-state meaning
        must match the unfiltered list.
      operationId: listWorkspaceOperationsWithActiveStateMeaning
      x-logical-contract: true
      parameters:
        - $ref: '#/components/parameters/TenantFilter'
        - $ref: '#/components/parameters/ActiveTab'
        - $ref: '#/components/parameters/ProblemClass'
      responses:
        '200':
          description: Workspace operations list row contract
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationRunCollectionContract'
        '404':
          description: Workspace scope not visible to the current operator
  /admin/operations/{run}:
    get:
      tags: [CanonicalRunDetail]
      summary: Logical canonical run-detail contract
      description: |
        Represents the top-level summary semantics for a canonical operation-run detail page.
        The page remains diagnostic-first while preserving the same active-state meaning seen
        on compact tenant and workspace surfaces.
      operationId: getCanonicalOperationRunDetailActiveStateSummary
      x-logical-contract: true
      parameters:
        - $ref: '#/components/parameters/RunId'
      responses:
        '200':
          description: Canonical operation-run detail summary contract
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationRunDetailContract'
        '403':
          description: Operator is a member of scope but lacks required capability
        '404':
          description: Run not visible to the current operator or tenant scope
components:
  parameters:
    TenantId:
      name: tenant
      in: path
      required: true
      schema:
        type: integer
        minimum: 1
    RunId:
      name: run
      in: path
      required: true
      schema:
        type: integer
        minimum: 1
    TenantFilter:
      name: tenant
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
      description: Optional tenant prefilter preserved from tenant-context navigation
    ActiveTab:
      name: activeTab
      in: query
      required: false
      schema:
        type: string
      description: Existing canonical monitoring tab selection
    ProblemClass:
      name: problemClass
      in: query
      required: false
      schema:
        type: string
        enum:
          - none
          - active_stale_attention
          - terminal_follow_up
  schemas:
    OperationRunActiveStateProjection:
      type: object
      additionalProperties: false
      required:
        - freshness_state
        - problem_class
        - surface_category
        - is_currently_active
        - is_reconciled
        - show_in_active_progress
        - keep_active_polling
      properties:
        freshness_state:
          type: string
          enum:
            - fresh_active
            - likely_stale
            - reconciled_failed
            - terminal_normal
            - unknown
        problem_class:
          type: string
          enum:
            - none
            - active_stale_attention
            - terminal_follow_up
        surface_category:
          type: string
          enum:
            - healthy_active
            - past_expected_lifecycle
            - likely_stale
            - no_longer_active
            - unknown
          description: |
            Derived operator-facing category. Compact surfaces may use
            `past_expected_lifecycle` where canonical detail uses `likely_stale`
            over the same stale truth.
        compact_label:
          type: string
          nullable: true
        diagnostic_label:
          type: string
          nullable: true
        lifecycle_label:
          type: string
          nullable: true
        guidance:
          type: string
          nullable: true
        stale_lineage_note:
          type: string
          nullable: true
        is_currently_active:
          type: boolean
        is_reconciled:
          type: boolean
        show_in_active_progress:
          type: boolean
        keep_active_polling:
          type: boolean
    OperationRunSurfaceItem:
      type: object
      additionalProperties: false
      required:
        - run_id
        - operation_label
        - active_state
      properties:
        run_id:
          type: integer
          minimum: 1
        tenant_id:
          type: integer
          minimum: 1
          nullable: true
        tenant_label:
          type: string
          nullable: true
        operation_label:
          type: string
        status_label:
          type: string
          nullable: true
        outcome_label:
          type: string
          nullable: true
        active_state:
          $ref: '#/components/schemas/OperationRunActiveStateProjection'
        detail_url:
          type: string
          nullable: true
    TenantActivityOperationsSummary:
      type: object
      additionalProperties: false
      required:
        - tenant_id
        - items
      properties:
        tenant_id:
          type: integer
          minimum: 1
        items:
          type: array
          items:
            $ref: '#/components/schemas/OperationRunSurfaceItem'
    TenantOperationProgressOverlay:
      type: object
      additionalProperties: false
      required:
        - tenant_id
        - has_visible_active_runs
        - poll_interval
        - items
      properties:
        tenant_id:
          type: integer
          minimum: 1
        has_visible_active_runs:
          type: boolean
        poll_interval:
          type: string
          nullable: true
          enum:
            - 10s
        items:
          type: array
          items:
            $ref: '#/components/schemas/OperationRunSurfaceItem'
    OperationRunCollectionContract:
      type: object
      additionalProperties: false
      required:
        - items
      properties:
        tenant_filter:
          type: integer
          minimum: 1
          nullable: true
        active_tab:
          type: string
          nullable: true
        problem_class:
          type: string
          nullable: true
        items:
          type: array
          items:
            $ref: '#/components/schemas/OperationRunSurfaceItem'
    OperationRunDetailContract:
      type: object
      additionalProperties: false
      required:
        - run_id
        - operation_label
        - active_state
      properties:
        run_id:
          type: integer
          minimum: 1
        operation_label:
          type: string
        active_state:
          $ref: '#/components/schemas/OperationRunActiveStateProjection'
        top_summary:
          type: string
          nullable: true
        diagnostics_visible_after_summary:
          type: boolean
          const: true