318 lines
9.4 KiB
YAML
318 lines
9.4 KiB
YAML
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' |