openapi: 3.1.0
info:
  title: Monitoring Surface Action Hierarchy Internal Contract
  version: 0.1.0
  summary: Internal logical contract for Spec 193 monitoring and workbench surface hierarchy
  description: |
    This contract is an internal planning artifact for Spec 193. The affected
    surfaces continue to render HTML through Filament and Livewire. The schemas
    below define the bounded render contract and regression expectations for
    monitoring/workbench action layers, selection-aware prominence, calm
    bounded-scope references, and the explicit diagnostic exception.
servers:
  - url: /internal
x-monitoring-action-hierarchy-consumers:
  - surface: remediation-required-workbench-pages
    sourceFiles:
      - apps/platform/app/Filament/Pages/Monitoring/FindingExceptionsQueue.php
      - apps/platform/app/Filament/Pages/Monitoring/Operations.php
      - apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php
    mustRender:
      - explicit_action_layers
      - quiet_scope_and_navigation_layers
      - selection_or_focus_actions_only_when_active
      - no_selection_quiet_state_when_applicable
    mustNotRender:
      - flat_scope_navigation_selection_strip
      - scope_as_peer_cta
      - mixed_global_and_selection_actions_in_one_lane
  - surface: shared-pattern-audit-pages
    sourceFiles:
      - apps/platform/app/Filament/Pages/Monitoring/Alerts.php
      - apps/platform/app/Filament/Pages/Monitoring/AuditLog.php
      - apps/platform/app/Filament/Resources/AlertDeliveryResource/Pages/ListAlertDeliveries.php
    mustRender:
      - explicit_inventory_classification
      - quiet_operate_hub_scope_usage
    mustNotRender:
      - undocumented_exemption
  - surface: calm-reference-pages
    sourceFiles:
      - apps/platform/app/Filament/Pages/Monitoring/EvidenceOverview.php
      - apps/platform/app/Filament/Pages/BaselineCompareLanding.php
      - apps/platform/app/Filament/Pages/BaselineCompareMatrix.php
      - apps/platform/app/Filament/Pages/Reviews/ReviewRegister.php
    mustRender:
      - bounded_scope_semantics
      - no_forced_extra_layers
    mustNotRender:
      - cosmetic_normalization_without_finding
  - surface: special-type-exception
    sourceFiles:
      - apps/platform/app/Filament/Pages/TenantDiagnostics.php
    mustRender:
      - explicit_exception_reason
      - repair_actions_only_when_defect_exists
    mustNotRender:
      - silent_exception
  - surface: regression-guards
    sourceFiles:
      - apps/platform/app/Support/Ui/ActionSurface/ActionSurfaceExemptions.php
      - apps/platform/app/Support/Ui/ActionSurface/ActionSurfaceValidator.php
      - apps/platform/tests/Feature/Guards/ActionSurfaceContractTest.php
      - apps/platform/tests/Feature/Guards/ActionSurfaceValidatorTest.php
paths:
  /internal/action-surfaces/monitoring/{surface}:
    get:
      summary: Return the logical action-layer contract for an in-scope monitoring surface
      operationId: getMonitoringSurfaceActionHierarchyContract
      parameters:
        - name: surface
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/SurfaceKey'
      responses:
        '200':
          description: Logical render contract and regression expectations for the requested surface
          content:
            application/vnd.tenantpilot.monitoring-action-hierarchy+json:
              schema:
                $ref: '#/components/schemas/MonitoringSurfaceContract'
        '404':
          description: Requested surface is not in the Spec 193 inventory
components:
  schemas:
    SurfaceKey:
      type: string
      enum:
        - finding_exceptions_queue
        - tenantless_operation_run_viewer
        - operations
        - alerts
        - audit_log
        - alert_deliveries
        - evidence_overview
        - baseline_compare_matrix
        - baseline_compare_landing
        - review_register
        - tenant_diagnostics
    SurfaceClassification:
      type: string
      enum:
        - remediation_required
        - minor_alignment_only
        - compliant_no_op
        - special_type_acceptable
    SurfaceKind:
      type: string
      enum:
        - queue_workbench
        - monitoring_detail
        - monitoring_landing
        - read_only_report
        - diagnostic_exception
    ActionLayer:
      type: string
      enum:
        - scope_context
        - navigation
        - surface_utility
        - selection_focused
        - related_drilldown
    SurfaceState:
      type: string
      enum:
        - no_selection_monitoring
        - focused_selection
        - global_monitoring
        - related_drilldown
        - diagnostic_exception
    ActionKind:
      type: string
      enum:
        - context
        - navigation
        - utility
        - mutation
        - drilldown
        - repair
        - governance
    MutationScope:
      type: string
      enum:
        - TenantPilot only
        - Microsoft tenant
        - simulation only
        - read-only
    ScopeSignal:
      type: object
      additionalProperties: false
      required:
        - label
        - source
        - isContextOnly
        - changesSurfaceScope
      properties:
        label:
          type: string
        source:
          type: string
          enum:
            - OperateHubShell
            - CanonicalNavigationContext
            - tenant_route
            - local_filter_state
        isContextOnly:
          type: boolean
        changesSurfaceScope:
          type: boolean
        leaksScopeIfMisplaced:
          type: boolean
    MonitoringSurfaceAction:
      type: object
      additionalProperties: false
      required:
        - actionKey
        - label
        - actionKind
        - layer
        - visibleInStates
        - requiresConfirmation
        - usesUiEnforcement
        - mutationScope
      properties:
        actionKey:
          type: string
        label:
          type: string
        actionKind:
          $ref: '#/components/schemas/ActionKind'
        layer:
          $ref: '#/components/schemas/ActionLayer'
        visibleInStates:
          type: array
          items:
            $ref: '#/components/schemas/SurfaceState'
        requiresConfirmation:
          type: boolean
        usesUiEnforcement:
          type: boolean
        capabilityKey:
          type:
            - string
            - 'null'
        writesAuditLog:
          type: boolean
        mutationScope:
          $ref: '#/components/schemas/MutationScope'
    MonitoringLayerContract:
      type: object
      additionalProperties: false
      required:
        - layer
        - isPresent
        - isPrimaryWorkLayer
        - visibilityRule
      properties:
        layer:
          $ref: '#/components/schemas/ActionLayer'
        isPresent:
          type: boolean
        isPrimaryWorkLayer:
          type: boolean
        mustRemainQuiet:
          type: boolean
        visibilityRule:
          type: string
    StateContract:
      type: object
      additionalProperties: false
      required:
        - stateKey
        - dominantQuestion
        - prominentActionKeys
        - allowsNoProminentAction
      properties:
        stateKey:
          $ref: '#/components/schemas/SurfaceState'
        dominantQuestion:
          type: string
        prominentActionKeys:
          type: array
          items:
            type: string
        quietLayerKeys:
          type: array
          items:
            $ref: '#/components/schemas/ActionLayer'
        allowsNoProminentAction:
          type: boolean
    MonitoringSurfaceRegressionExpectation:
      type: object
      additionalProperties: false
      required:
        - forbidsScopeAsPeerCta
        - forbidsFlatGlobalSelectionMix
        - requiresExplicitExceptionReason
        - browserSmokeRequired
      properties:
        forbidsScopeAsPeerCta:
          type: boolean
        forbidsFlatGlobalSelectionMix:
          type: boolean
        requiresNoSelectionQuietState:
          type: boolean
        requiresExplicitExceptionReason:
          type: boolean
        allowsMinorAlignmentOnly:
          type: boolean
        browserSmokeRequired:
          type: boolean
    MonitoringSurfaceContract:
      type: object
      additionalProperties: false
      required:
        - surfaceKey
        - surfaceKind
        - classification
        - canonicalNoun
        - primaryQuestion
        - scopeSignals
        - layers
        - actions
        - states
        - regressionExpectation
      properties:
        surfaceKey:
          $ref: '#/components/schemas/SurfaceKey'
        surfaceKind:
          $ref: '#/components/schemas/SurfaceKind'
        classification:
          $ref: '#/components/schemas/SurfaceClassification'
        canonicalNoun:
          type: string
        primaryQuestion:
          type: string
        scopeSignals:
          type: array
          items:
            $ref: '#/components/schemas/ScopeSignal'
        layers:
          type: array
          items:
            $ref: '#/components/schemas/MonitoringLayerContract'
        actions:
          type: array
          items:
            $ref: '#/components/schemas/MonitoringSurfaceAction'
        states:
          type: array
          items:
            $ref: '#/components/schemas/StateContract'
        explicitExceptionReason:
          type:
            - string
            - 'null'
        regressionExpectation:
          $ref: '#/components/schemas/MonitoringSurfaceRegressionExpectation'