ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
d5bb564ee7
TenantAtlas/specs/193-monitoring-action-hierarchy/data-model.md
ahmido bef9020159 feat: implement spec 193 monitoring action hierarchy (#227) 
## Summary
- codify Spec 193 as an explicit monitoring/workbench surface inventory with validator and guard coverage
- refactor the Finding Exceptions Queue, Operations landing, and tenantless operation viewer into clearer context, navigation, utility, drilldown, and focused-work lanes
- align Alerts, Audit Log, and Alert Deliveries with quiet origin-context handling while preserving calm reference surfaces and the explicit Tenant Diagnostics exception
- add focused feature coverage, guard coverage, browser smoke coverage, and the full spec artifacts for Spec 193

## Verification
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/ActionSurfaceContractTest.php tests/Feature/Guards/ActionSurfaceValidatorTest.php tests/Feature/Guards/Spec193MonitoringSurfaceHierarchyGuardTest.php tests/Feature/OpsUx/OperateHubShellTest.php tests/Feature/Operations/TenantlessOperationRunViewerTest.php tests/Feature/Monitoring/FindingExceptionsQueueHierarchyTest.php tests/Browser/Spec193MonitoringSurfaceHierarchySmokeTest.php`
- `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`
- integrated-browser smoke pass over queue, operations, operation detail, alerts, audit log, and tenant diagnostics

## Notes
- Livewire v4 / Filament v5 stack unchanged
- no provider-registration changes; Laravel 11+ provider registration remains in `bootstrap/providers.php`
- no new global-search behavior was introduced
- destructive and governance-changing actions keep their existing confirmation and authorization semantics
- no new assets or migrations were added

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #227
2026-04-12 10:48:00 +00:00

158 lines
9.1 KiB
Markdown
Raw Blame History

# 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.
Reference in New Issue View Git Blame Copy Permalink