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	State keys intentionally restorable by reload, back, or shared link
localOnlyStateKeys	array	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	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	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	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	Filter and sort keys currently driving the rendered matrix
draftFilterKeys	array	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	Applied filters, supported mode, and focus state only
localOnlySlices	array	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.