openapi: 3.1.0
info:
  title: Operations Truth Alignment Contract
  version: 1.0.0
  summary: Route and UI truth contract for Spec 178.
components:
  schemas:
    FreshnessState:
      type: string
      enum:
        - fresh_active
        - likely_stale
        - reconciled_failed
        - terminal_normal
        - unknown
    ProblemClass:
      type: string
      enum:
        - none
        - active_stale_attention
        - terminal_follow_up
    OperationsDrillthroughState:
      type: object
      required:
        - workspace_id
        - problemClass
      properties:
        workspace_id:
          type: integer
        tenant_id:
          type:
            - integer
            - 'null'
        problemClass:
          $ref: '#/components/schemas/ProblemClass'
        activeTab:
          type:
            - string
            - 'null'
        navigationContext:
          type:
            - string
            - 'null'
    RunDecisionZoneTruth:
      type: object
      required:
        - freshnessState
        - problemClass
        - isCurrentlyActive
        - isReconciled
        - primaryNextAction
      properties:
        freshnessState:
          $ref: '#/components/schemas/FreshnessState'
        problemClass:
          $ref: '#/components/schemas/ProblemClass'
        isCurrentlyActive:
          type: boolean
        isReconciled:
          type: boolean
        staleLineageNote:
          type:
            - string
            - 'null'
        primaryNextAction:
          type: string
paths:
  /admin:
    get:
      operationId: viewWorkspaceOverview
      summary: Display the workspace overview with aligned operations attention and recency truth.
      responses:
        '200':
          description: Workspace overview rendered successfully.
        '404':
          description: User is not entitled to the current workspace scope.
      x-embedded-surfaces:
        workspaceOperationsAttention:
          surfaceType: embedded_attention_summary
          problemBuckets:
            - active_stale_attention
            - terminal_follow_up
          canonicalCollectionRoute: /admin/operations
          destinationContract:
            $ref: '#/components/schemas/OperationsDrillthroughState'
        workspaceRecentOperations:
          surfaceType: diagnostic_recency_table
          canonicalCollectionRoute: /admin/operations
          canonicalDetailRoute: /admin/operations/{run}
          rowTruth:
            freshnessState:
              $ref: '#/components/schemas/FreshnessState'
            problemClass:
              $ref: '#/components/schemas/ProblemClass'
  /admin/t/{tenant}:
    get:
      operationId: viewTenantDashboard
      summary: Display the tenant dashboard with aligned operations attention, recent activity, and local progress truth.
      parameters:
        - name: tenant
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Tenant dashboard rendered successfully.
        '404':
          description: User is not entitled to the tenant scope.
      x-embedded-surfaces:
        tenantOperationsAttention:
          surfaceType: embedded_attention_summary
          problemBuckets:
            - active_stale_attention
            - terminal_follow_up
          canonicalCollectionRoute: /admin/operations
          destinationContract:
            $ref: '#/components/schemas/OperationsDrillthroughState'
        tenantRecentOperations:
          surfaceType: diagnostic_recency_table
          canonicalCollectionRoute: /admin/operations
          canonicalDetailRoute: /admin/operations/{run}
          rowTruth:
            freshnessState:
              $ref: '#/components/schemas/FreshnessState'
            problemClass:
              $ref: '#/components/schemas/ProblemClass'
        bulkOperationProgress:
          surfaceType: live_progress_indicator
          activeOnly: true
          polling:
            interval: 10s
            activeWhen: active runs exist for the current tenant
            inactiveWhen: no relevant active runs remain
  /admin/operations:
    get:
      operationId: listAdminOperations
      summary: Display the canonical admin operations hub with problem-class-aware filtering.
      parameters:
        - name: tenant_id
          in: query
          required: false
          schema:
            type: integer
        - name: problemClass
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/ProblemClass'
        - name: activeTab
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Operations hub rendered successfully.
        '404':
          description: User is not entitled to the workspace or referenced tenant scope.
      x-ui-surface:
        surfaceType: read_only_registry_report
        displayLabel: Operations
        canonicalDetailRoute: /admin/operations/{run}
        filters:
          active_stale_attention:
            definition: queued or running runs whose freshness state is likely_stale
          terminal_follow_up:
            definition: completed runs whose outcome is blocked, partially_succeeded, or failed; reconciled stale lineage remains visible
        rowTruth:
          freshnessState:
            $ref: '#/components/schemas/FreshnessState'
          problemClass:
            $ref: '#/components/schemas/ProblemClass'
  /admin/operations/{run}:
    get:
      operationId: viewAdminOperation
      summary: Display the canonical admin run detail with decision-zone lifecycle truth.
      parameters:
        - name: run
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Canonical admin run detail rendered successfully.
        '404':
          description: User is not entitled to the workspace or referenced tenant scope.
      x-ui-surface:
        surfaceType: detail_first_operational
        displayLabel: Operation
        decisionZoneTruth:
          $ref: '#/components/schemas/RunDecisionZoneTruth'
        invariant:
          - stale and reconciled lifecycle truth must be visible in the primary decision hierarchy
          - problem class on the destination must confirm the problem class of the origin link
  /system/ops/runs:
    get:
      operationId: listSystemOperations
      summary: Display the platform-wide operations registry with stale/reconciled lineage visible.
      responses:
        '200':
          description: System operations registry rendered successfully.
        '403':
          description: Authenticated platform user lacks operations view capability.
        '404':
          description: Wrong plane or inaccessible system surface.
      x-ui-surface:
        surfaceType: read_only_registry_report
        displayLabel: Operations
        canonicalDetailRoute: /system/ops/runs/{run}
        rowTruth:
          freshnessState:
            $ref: '#/components/schemas/FreshnessState'
          problemClass:
            $ref: '#/components/schemas/ProblemClass'
          staleLineageVisible: true
  /system/ops/failures:
    get:
      operationId: listSystemFailures
      summary: Display the platform failure registry with reconciled stale lineage visible on failed terminal runs.
      responses:
        '200':
          description: System failures registry rendered successfully.
        '403':
          description: Authenticated platform user lacks operations view capability.
        '404':
          description: Wrong plane or inaccessible system surface.
      x-ui-surface:
        surfaceType: read_only_registry_report
        displayLabel: Failed operations
        canonicalDetailRoute: /system/ops/runs/{run}
        filter:
          baseOutcome: failed
        invariant:
          - failed runs that were auto-reconciled from stale state must visibly preserve that lineage
  /system/ops/stuck:
    get:
      operationId: listSystemStuckOperations
      summary: Display active queued/running operations that crossed the lifecycle stuck threshold.
      responses:
        '200':
          description: System stuck registry rendered successfully.
        '403':
          description: Authenticated platform user lacks operations view capability.
        '404':
          description: Wrong plane or inaccessible system surface.
      x-ui-surface:
        surfaceType: read_only_registry_report
        displayLabel: Stuck operations
        canonicalDetailRoute: /system/ops/runs/{run}
        filter:
          problemClass: active_stale_attention
        invariant:
          - the page remains active-only and uses the same lifecycle-policy thresholds as admin stale detection
  /system/ops/runs/{run}:
    get:
      operationId: viewSystemOperation
      summary: Display the platform run detail confirming stale/reconciled lineage and next action.
      parameters:
        - name: run
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: System run detail rendered successfully.
        '403':
          description: Authenticated platform user lacks operations view capability.
        '404':
          description: Wrong plane or inaccessible system surface.
      x-ui-surface:
        surfaceType: detail_first_operational
        displayLabel: Operation
        decisionZoneTruth:
          $ref: '#/components/schemas/RunDecisionZoneTruth'
        invariant:
          - stale/reconciled lineage remains visible even when the run is already terminal