openapi: 3.1.0
info:
  title: Monitoring Page-State Internal Contract
  version: 0.1.0
  summary: Internal logical contract for Spec 198 monitoring page-state behavior
  description: |
    This contract is an internal planning artifact for Spec 198. The affected
    surfaces continue to render HTML through Filament and Livewire. The schemas
    below define the bounded contract for contextual prefilter state, active
    state, draft state, inspect state, shareable/restorable state, and
    deterministic hydration rules across the in-scope monitoring family.
servers:
  - url: /internal
x-monitoring-page-state-consumers:
  - surface: operations
    sourceFiles:
      - apps/platform/app/Filament/Pages/Monitoring/Operations.php
      - apps/platform/resources/views/filament/pages/monitoring/operations.blade.php
    mustDeclare:
      - contextual_prefilter
      - active
      - shareable_restorable
    mustNotDeclare:
      - draft
      - competing_same_page_inspect_model
  - surface: audit_log
    sourceFiles:
      - apps/platform/app/Filament/Pages/Monitoring/AuditLog.php
      - apps/platform/resources/views/filament/pages/monitoring/audit-log.blade.php
      - apps/platform/resources/views/filament/pages/monitoring/partials/audit-log-inspect-event.blade.php
    mustDeclare:
      - contextual_prefilter
      - active
      - inspect
      - shareable_restorable
    mustNotDeclare:
      - draft
      - parallel_inspect_world
  - surface: finding_exceptions_queue
    sourceFiles:
      - apps/platform/app/Filament/Pages/Monitoring/FindingExceptionsQueue.php
      - apps/platform/resources/views/filament/pages/monitoring/finding-exceptions-queue.blade.php
    mustDeclare:
      - contextual_prefilter
      - active
      - inspect
      - shareable_restorable
    mustNotDeclare:
      - draft
      - parallel_inspect_world
  - surface: evidence_overview
    sourceFiles:
      - apps/platform/app/Filament/Pages/Monitoring/EvidenceOverview.php
      - apps/platform/resources/views/filament/pages/monitoring/evidence-overview.blade.php
    mustDeclare:
      - contextual_prefilter
      - active
      - shareable_restorable
    mustNotDeclare:
      - draft
      - same_page_selected_record_state
  - surface: baseline_compare_matrix
    sourceFiles:
      - apps/platform/app/Filament/Pages/BaselineCompareMatrix.php
      - apps/platform/resources/views/filament/pages/baseline-compare-matrix.blade.php
    mustDeclare:
      - contextual_prefilter
      - active
      - draft
      - inspect
      - shareable_restorable
    mustNotDeclare:
      - forced_direct_active_filter_model
  - surface: baseline_compare_landing
    sourceFiles:
      - apps/platform/app/Filament/Pages/BaselineCompareLanding.php
      - apps/platform/resources/views/filament/pages/baseline-compare-landing.blade.php
    mustDeclare:
      - contextual_prefilter
      - active
    mustNotDeclare:
      - competing_applied_compare_owner
paths:
  /internal/page-state/{surface}:
    get:
      summary: Return the logical page-state contract for an in-scope monitoring surface
      operationId: getMonitoringPageStateContract
      parameters:
        - name: surface
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/SurfaceKey'
      responses:
        '200':
          description: Logical state contract and hydration rules for the requested surface
          content:
            application/vnd.tenantpilot.monitoring-page-state+json:
              schema:
                $ref: '#/components/schemas/SurfaceContract'
        '404':
          description: Requested surface is not in the Spec 198 inventory
components:
  schemas:
    SurfaceKey:
      type: string
      enum:
        - operations
        - audit_log
        - finding_exceptions_queue
        - evidence_overview
        - baseline_compare_matrix
        - baseline_compare_landing
    SurfaceType:
      type: string
      enum:
        - simple_monitoring
        - selected_record_monitoring
        - draft_apply_analysis
        - launch_context_support
    StateClass:
      type: string
      enum:
        - contextual_prefilter
        - active
        - draft
        - inspect
        - shareable_restorable
    QueryRole:
      type: string
      enum:
        - initialization_only
        - durable_restorable
        - scoped_deeplink
        - unsupported
    StateCarrier:
      type: string
      enum:
        - query_param
        - session
        - livewire_property
        - route_context
        - derived_render_state
    InvalidFallback:
      type: string
      enum:
        - discard_and_continue
        - clear_selection_and_continue
        - reset_to_default_scope
        - ignore_unapplied_draft
        - deny_not_found
    InspectPresentation:
      type: string
      enum:
        - none
        - inline_detail
        - queue_summary
        - focused_matrix
        - navigate_to_canonical_detail
    StateFieldDescriptor:
      type: object
      additionalProperties: false
      required:
        - stateKey
        - stateClass
        - carrier
        - queryRole
        - shareable
        - restorableOnRefresh
        - invalidFallback
      properties:
        stateKey:
          type: string
        stateClass:
          $ref: '#/components/schemas/StateClass'
        carrier:
          $ref: '#/components/schemas/StateCarrier'
        queryRole:
          $ref: '#/components/schemas/QueryRole'
        shareable:
          type: boolean
        restorableOnRefresh:
          type: boolean
        tenantSensitive:
          type: boolean
        invalidFallback:
          $ref: '#/components/schemas/InvalidFallback'
    HydrationRule:
      type: object
      additionalProperties: false
      required:
        - precedenceOrder
        - appliesOnInitialMountOnly
        - activeStateBecomesAuthoritativeAfterMount
        - invalidRequestedStateFallback
      properties:
        precedenceOrder:
          type: array
          items:
            type: string
            enum:
              - query
              - session
              - default
        appliesOnInitialMountOnly:
          type: boolean
        activeStateBecomesAuthoritativeAfterMount:
          type: boolean
        clearsOnTenantSwitch:
          type: array
          items:
            type: string
        invalidRequestedStateFallback:
          $ref: '#/components/schemas/InvalidFallback'
    InspectContract:
      type: object
      additionalProperties: false
      required:
        - primaryModel
        - selectedStateKey
        - openedBy
        - presentation
        - shareable
        - invalidSelectionFallback
      properties:
        primaryModel:
          type: string
          enum:
            - none
            - selected_record_inline
            - selected_record_workbench
            - focused_subject
        selectedStateKey:
          type:
            - string
            - 'null'
        openedBy:
          type: array
          items:
            type: string
            enum:
              - query_param
              - inspect_action
              - row_selection
              - cell_focus
              - landing_context
        presentation:
          $ref: '#/components/schemas/InspectPresentation'
        shareable:
          type: boolean
        invalidSelectionFallback:
          $ref: '#/components/schemas/InvalidFallback'
    SurfaceContract:
      type: object
      additionalProperties: false
      required:
        - surfaceKey
        - surfaceType
        - stateFields
        - hydrationRule
        - inspectContract
        - shareableStateKeys
        - localOnlyStateKeys
      properties:
        surfaceKey:
          $ref: '#/components/schemas/SurfaceKey'
        surfaceType:
          $ref: '#/components/schemas/SurfaceType'
        stateFields:
          type: array
          items:
            $ref: '#/components/schemas/StateFieldDescriptor'
        hydrationRule:
          $ref: '#/components/schemas/HydrationRule'
        inspectContract:
          $ref: '#/components/schemas/InspectContract'
        shareableStateKeys:
          type: array
          items:
            type: string
        localOnlyStateKeys:
          type: array
          items:
            type: string