TenantAtlas/specs/198-monitoring-page-state/data-model.md

# Data Model: Monitoring Page-State Contract

## Overview

This feature introduces no new persisted entity, table, enum, or long-lived artifact. It standardizes the derived page-state contract of existing Filament pages so the same operator questions have the same answers across the monitoring family.

## Existing Source Truths Reused Without Change

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

- existing page routes and panel scope
- existing workspace and tenant entitlement checks
- existing page-local Livewire properties
- existing request query parameters and navigation-context payloads
- existing session-backed table filter, search, and sort persistence
- existing compare-builder and matrix-rendering truth
- existing approval, audit, and destructive-action safety behavior

This feature changes page-state semantics and documentation only.

## New Derived Planning Models

### MonitoringPageStateContract

**Type**: derived per-surface contract entry  
**Source**: explicit Spec 198 contract plus page-local declarations on the affected pages

| Field | Type | Notes |
|------|------|-------|
| `surfaceKey` | string | Stable identifier such as `operations` or `baseline_compare_matrix` |
| `pageClass` | string | Concrete Filament page class that owns the state |
| `surfaceType` | string | `simple_monitoring`, `selected_record_monitoring`, `draft_apply_analysis`, or `launch_context_support` |
| `usesContextualPrefilter` | boolean | Whether external launch or query context can seed the page |
| `usesDraftState` | boolean | True only when draft state is intentionally separate from active state |
| `usesInspectState` | boolean | Whether the page owns a selected-record or focused inspect contract |
| `shareableStateKeys` | array<string> | State keys intentionally restorable by reload, back, or shared link |
| `localOnlyStateKeys` | array<string> | State keys that never restore from shared or reopened entry |
| `invalidRequestedStateFallback` | string | Predictable fallback behavior when requested state is invalid or unauthorized |

### StateFieldDescriptor

**Type**: derived state-slice descriptor  
**Source**: explicit state-role mapping for a surface

| Field | Type | Notes |
|------|------|-------|
| `surfaceKey` | string | Links back to the owning surface |
| `stateKey` | string | Stable field or semantic slice such as `activeTab`, `selectedAuditLogId`, or `draftSelectedPolicyTypes` |
| `stateClass` | string | `contextual_prefilter`, `active`, `draft`, `inspect`, or `shareable_restorable` |
| `carrier` | string | `query_param`, `session`, `livewire_property`, `route_context`, or `derived_render_state` |
| `queryRole` | string | `initialization_only`, `durable_restorable`, `scoped_deeplink`, or `unsupported` |
| `shareable` | boolean | Whether the state may appear in a shared or bookmarked URL |
| `restorableOnRefresh` | boolean | Whether refresh or reopen recreates the state |
| `tenantSensitive` | boolean | Whether tenant change must clear or recompute the state |
| `invalidFallback` | string | What happens if the requested value is invalid or inaccessible |

### HydrationRule

**Type**: derived precedence rule  
**Source**: page mount logic plus the standardized Spec 198 precedence model

| Field | Type | Notes |
|------|------|-------|
| `surfaceKey` | string | The owning surface |
| `precedenceOrder` | array<string> | Ordered sources such as `query`, `session`, `default` |
| `appliesOnInitialMountOnly` | boolean | Whether the rule applies only during initial hydration |
| `activeStateBecomesAuthoritativeAfterMount` | boolean | True for all in-scope surfaces |
| `clearsOnTenantSwitch` | array<string> | State keys that must be reset when tenant context changes |
| `invalidRequestedStateFallback` | string | Surface-specific fallback behavior |

### InspectStateContract

**Type**: derived selected-record or focus contract  
**Source**: Audit Log, Finding Exceptions Queue, and Baseline Compare Matrix

| Field | Type | Notes |
|------|------|-------|
| `surfaceKey` | string | The owning surface |
| `primaryModel` | string | `selected_record_inline`, `selected_record_workbench`, `focused_subject`, or `none` |
| `selectedStateKey` | string | Backing property such as `selectedAuditLogId` or `focusedSubjectKey` |
| `openedBy` | array<string> | Supported entry modes such as `query_param`, `inspect_action`, or `cell_focus` |
| `inlinePresentation` | string | `inline_detail`, `summary_panel`, `focused_matrix`, or `navigate_to_detail` |
| `shareable` | boolean | Whether the selected state is intentionally bookmarkable or shareable |
| `invalidSelectionFallback` | string | Required clear-state or fallback behavior |

### CompareMatrixStateSlice

**Type**: derived special-case state descriptor  
**Source**: Baseline Compare Matrix page-local compare logic

| Field | Type | Notes |
|------|------|-------|
| `appliedFilterKeys` | array<string> | Filter and sort keys currently driving the rendered matrix |
| `draftFilterKeys` | array<string> | Pending filter and sort keys that do not affect the rendered matrix until apply |
| `presentationModeKey` | string | The current matrix presentation mode if present |
| `focusKey` | string | Focused subject or cell key |
| `shareableSlices` | array<string> | Applied filters, supported mode, and focus state only |
| `localOnlySlices` | array<string> | Unapplied draft state |

## Relationships

- One `MonitoringPageStateContract` owns many `StateFieldDescriptor` entries.
- One `MonitoringPageStateContract` owns exactly one `HydrationRule`.
- A surface that supports inspect state owns one `InspectStateContract`.
- `BaselineCompareMatrix` owns one `CompareMatrixStateSlice` in addition to the standard surface contract.
- `BaselineCompareLanding` participates as `launch_context_support` and seeds a separate surface rather than owning the downstream applied state.

## Resolution Rules

### Shared rules

1. Supported query or deeplink input hydrates first on initial mount.
2. Session participates only for state the page already persists intentionally.
3. Invalid or unauthorized requested state is discarded or cleared predictably.
4. After mount, active local state becomes authoritative.
5. Any state not explicitly declared shareable or restorable is treated as local-only.

### Simple monitoring rules

- `operations` and `evidence_overview` follow the simple monitoring pattern: contextual prefilter plus active state, with no same-page selected-record inspect state.
- Their shareable or restorable state is limited to explicitly supported filter, tab, and context fields.

### Selected-record monitoring rules

- `audit_log` and `finding_exceptions_queue` each have exactly one selected-record contract.
- Inspect actions, selected summaries, and selected-record query parameters must all point to the same selected state.
- If selection becomes invalid or filtered out, the surface returns to the unselected state without stale action or summary state.

### Compare matrix rules

- `baseline_compare_matrix` is the only in-scope surface with draft state.
- Draft state never becomes shareable or restorable.
- Applied compare state and supported focus state are the only durable slices.
- `baseline_compare_landing` may seed matrix launch context but never competes with the matrix for applied state ownership.

## Safety Rules

- No derived contract may widen workspace or tenant visibility beyond existing route and policy semantics.
- No selected-record or focus state may survive refresh, reopen, or filter change if the record or subject is invalid or unauthorized.
- No surface may expose two competing primary inspect models for the same operator function.
- No draft state may silently leak into shared URLs or refresh restoration unless the contract explicitly allows it.
- No shell or global context concern may be solved inside this feature without an explicit handoff decision for Spec 199.