TenantAtlas/specs/193-monitoring-action-hierarchy/data-model.md

Data Model: Monitoring Surface Action Hierarchy and Workbench Semantics

Overview

This feature introduces no new persisted entity, table, enum, or long-lived artifact. It reuses existing Filament pages, existing action definitions, existing authorization helpers, and existing run or audit truth, while adding a derived planning model for how monitoring and workbench surfaces are inventoried, layered, and regression-tested.

Existing Source Truths Reused Without Change

The following truths remain authoritative and are not redefined by this feature:

• existing page and resource routes
• existing model ownership and scope semantics
• existing capability checks and UiEnforcement behavior
• existing confirmation, audit, and OperationRun behavior for underlying actions
• existing OperateHubShell, CanonicalNavigationContext, and tenant-filter state behavior
• existing page-local visibility rules for selected-object actions and run follow-up behavior

This feature changes action hierarchy and placement only.

New Derived Planning Models

MonitoringSurfaceInventoryEntry

Type: spec and guard inventory entry
Source: explicit Spec 193 classification matrix + action-surface regression guard

Field	Type	Notes
surfaceKey	string	Stable identifier such as finding_exceptions_queue or tenantless_operation_run_viewer
pageClass	string	Concrete Filament page or resource page class under review
panelScope	string	admin or tenant
ownerScope	string	workspace-owned, workspace-visible-tenant-owned, or tenant-owned
surfaceKind	string	queue_workbench, monitoring_detail, monitoring_landing, read_only_report, or diagnostic_exception
classification	string	remediation_required, minor_alignment_only, compliant_no_op, or special_type_acceptable
sharedPattern	string or null	e.g. OperateHubShell, cluster_entry, or none
requiresHeaderRemediation	boolean	Whether the surface must change under Spec 193
requiresExplicitDeclaration	boolean	Whether the page must carry an explicit actionSurfaceDeclaration()
exceptionReason	string or null	Required only for the special-type exception
browserSmokeRequired	boolean	Whether browser smoke must cover the surface

ActionLayerDescriptor

Type: derived page render contract
Source: existing page action methods + explicit Spec 193 rules

Field	Type	Notes
surfaceKey	string	Links the layer state back to the inventory entry
layerKey	string	scope_context, navigation, surface_utility, selection_focused, or related_drilldown
isPresent	boolean	Whether the layer exists on this surface
isPrimaryWorkLayer	boolean	True when the layer represents the current next-action lane
mustRemainQuiet	boolean	True for scope and navigation layers when work actions exist
visibilityRule	string	Human-readable rule for when the layer is shown or emphasized

MonitoringSurfaceActionDescriptor

Type: derived action classification entry
Source: existing Filament action definitions on the target page

Field	Type	Notes
actionKey	string	Action name such as approve_selected_exception or refresh
label	string	Visible operator-facing label
actionKind	string	context, navigation, utility, mutation, drilldown, repair, or governance
layer	string	One of the Spec 193 layers
visibleInStates	array	Surface states where the action may be visible
requiresConfirmation	boolean	Mirrors existing confirmation behavior
usesUiEnforcement	boolean	Whether the action is wrapped with a central enforcement helper
capabilityKey	string or null	Canonical capability requirement when applicable
writesAuditLog	boolean	Whether the underlying mutation writes audit truth
mutationScope	string	TenantPilot only, Microsoft tenant, simulation only, or read-only

WorkbenchStateContract

Type: derived work-state entry
Source: explicit queue or viewer state rules in the spec

Field	Type	Notes
surfaceKey	string	The workbench or monitoring surface
stateKey	string	no_selection_monitoring, focused_selection, global_monitoring, related_drilldown, or diagnostic_exception
dominantQuestion	string	The operator question the state must answer
prominentActionKeys	array	Actions allowed to read as the current next step
quietLayerKeys	array	Layers that must remain visible but subordinate
allowsNoProminentAction	boolean	True for calm reference or exception states

ScopeSignalContract

Type: derived context entry
Source: OperateHubShell, route-bound tenant context, and canonical navigation helpers

Field	Type	Notes
surfaceKey	string	The surface that shows the scope signal
label	string	Operator-facing scope label
source	string	OperateHubShell, CanonicalNavigationContext, tenant_route, or local_filter_state
isContextOnly	boolean	True when the signal must not read as a CTA
changesSurfaceScope	boolean	True only when interacting with the signal resets or broadens scope
leaksScopeIfMisplaced	boolean	True when wrong placement could imply broader access or actionability

MonitoringSurfaceRegressionExpectation

Type: guard and test expectation entry
Source: Spec 193 regression-protection requirements

Field	Type	Notes
surfaceKey	string	The page under regression protection
forbidsScopeAsPeerCta	boolean	Scope must not read as a peer CTA
forbidsFlatGlobalSelectionMix	boolean	Global and selected-object actions must not flatten into one lane
requiresNoSelectionQuietState	boolean	Workbench pages must render a calm state when no object is selected
requiresExplicitExceptionReason	boolean	True only for TenantDiagnostics
allowsMinorAlignmentOnly	boolean	True for audit-only surfaces that should not be rebuilt without a specific finding
browserSmokeRequired	boolean	Whether browser smoke must cover this surface

Resolution Rules

Monitoring and workbench remediation rules

1. A remediation-required monitoring or workbench surface resolves actions into explicit layers rather than a single flat header strip.
2. Scope and context signals resolve to scope_context and must remain visibly subordinate to live work actions.
3. Back, return, show-all, and origin links resolve to navigation, not to the active work lane.
4. Refresh, clear filters, and other page controls resolve to surface_utility.
5. Selection-bound or focused-object actions resolve to selection_focused and may become prominent only in states where a valid selection exists.
6. Drilldowns and related opens resolve to related_drilldown, not to the same peer level as scope or work actions.

Work-state rules

• finding_exceptions_queue resolves to no_selection_monitoring when no exception is selected and to focused_selection when a pending exception is selected.
• tenantless_operation_run_viewer resolves to global_monitoring plus optional related_drilldown or focused follow-up states depending on run context and resumable behavior.
• operations resolves to global_monitoring even when tenant-prefiltered; scope reset remains utility, not primary work.

Bounded-scope reference rules

1. A compliant or no-op surface may keep one narrow utility or drilldown affordance without being forced into extra layers.
2. Reference surfaces must not be rebuilt only to mimic the remediated workbench pages.

Special-type exception rules

1. tenant_diagnostics may expose repair actions only when the corresponding diagnostic defect exists.
2. tenant_diagnostics must always carry an explicit exception reason in inventory and regression expectations.
3. The exception does not create a general allowance for other monitoring pages to promote repair or mutation actions in the same way.

Relationships

• One MonitoringSurfaceInventoryEntry maps to one or more ActionLayerDescriptor entries.
• One MonitoringSurfaceInventoryEntry may contain many MonitoringSurfaceActionDescriptor entries.
• A workbench or viewer surface may contain multiple WorkbenchStateContract entries.
• Every surface may contain zero or many ScopeSignalContract entries.
• Every in-scope surface must map to one MonitoringSurfaceRegressionExpectation.

Safety Rules

• No derived model may widen tenant or workspace visibility beyond existing route and helper semantics.
• No action may lose UiEnforcement, confirmation, audit, or OperationRun behavior when it changes layer.
• No scope signal may be promoted into a peer CTA when it is informational only.
• No selection-focused lane may remain prominent when the selected object is absent or no longer valid.
• No exception may remain undocumented in the inventory and regression layer.