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<string> | 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<string> | Actions allowed to read as the current next step |
| `quietLayerKeys` | array<string> | 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.