openapi: 3.1.0
info:
  title: System Operations Surface Alignment Contract
  version: 1.0.0
  summary: Route and UI contract for Spec 170.
paths:
  /system/ops/runs:
    get:
      operationId: listSystemRuns
      summary: Display the platform-wide operations registry.
      responses:
        '200':
          description: System runs list 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
        canonicalNoun:
          collection: Operations
          singular: Operation
        inspectAffordance: clickable_row
        canonicalDetailRoute: /system/ops/runs/{run}
        headerActions:
          - name: go_to_runbooks
            label: Go to runbooks
            type: navigation
        rowActions: []
        bulkActions: []
        emptyStateCta:
          name: go_to_runbooks
          label: Go to runbooks
        requiredCapabilities:
          - platform.operations.view
        defaultVisibleTruth:
          - status
          - outcome
          - operation
          - workspace
          - tenant
          - initiator
          - activity_time
  /system/ops/failures:
    get:
      operationId: listSystemFailures
      summary: Display failed operations as a read-only registry.
      responses:
        '200':
          description: Failed-runs list 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
        canonicalNoun:
          collection: Operations
          singular: Operation
        inspectAffordance: clickable_row
        canonicalDetailRoute: /system/ops/runs/{run}
        headerActions:
          - name: show_all_operations
            label: Show all operations
            type: navigation
            url: /system/ops/runs
        rowActions: []
        bulkActions: []
        emptyStateCta:
          name: show_all_operations
          label: Show all operations
        requiredCapabilities:
          - platform.operations.view
        filter:
          status: completed
          outcome: failed
        defaultVisibleTruth:
          - status
          - outcome
          - operation
          - workspace
          - tenant
          - activity_time
  /system/ops/stuck:
    get:
      operationId: listSystemStuckRuns
      summary: Display queued or running operations that exceed the stuck threshold.
      responses:
        '200':
          description: Stuck-runs list 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
        canonicalNoun:
          collection: Operations
          singular: Operation
        inspectAffordance: clickable_row
        canonicalDetailRoute: /system/ops/runs/{run}
        headerActions:
          - name: show_all_operations
            label: Show all operations
            type: navigation
            url: /system/ops/runs
        rowActions: []
        bulkActions: []
        emptyStateCta:
          name: show_all_operations
          label: Show all operations
        requiredCapabilities:
          - platform.operations.view
        derivedFields:
          - stuck_class
        defaultVisibleTruth:
          - status
          - stuck_class
          - operation
          - workspace
          - tenant
          - activity_time
  /system/ops/runs/{run}:
    get:
      operationId: viewSystemRun
      summary: Display one system operation detail surface.
      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
        canonicalNoun:
          collection: Operations
          singular: Operation
        requiredCapabilities:
          - platform.operations.view
        headerActions:
          - name: show_all_operations
            label: Show all operations
            type: navigation
            url: /system/ops/runs
          - name: go_to_runbooks
            label: Go to runbooks
            type: navigation
          - name: retry
            label: Retry
            type: mutation
            requiredCapabilities:
              - platform.operations.manage
            confirmationRequired: true
            visibleWhen:
              status: completed
              outcome: failed
              retryableType: true
          - name: cancel
            label: Cancel
            type: destructive_mutation
            requiredCapabilities:
              - platform.operations.manage
            confirmationRequired: true
            visibleWhen:
              statusIn:
                - queued
                - running
              cancelableType: true
          - name: mark_investigated
            label: Mark investigated
            type: mutation
            requiredCapabilities:
              - platform.operations.manage
            confirmationRequired: true
            form:
              fields:
                - name: reason
                  type: textarea
                  required: true
                  minLength: 5
                  maxLength: 500