# Data Model: Record Page Header Discipline & Contextual Navigation

## Overview

This feature introduces no new persisted entity, table, enum, or long-lived artifact. It reuses existing Filament pages, existing action definitions, and existing authorization helpers, while adding a derived planning model for how record-page headers are classified, rendered, and regression-tested.

## Existing Source Truths Reused Without Change

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

- existing resource and page routes
- existing model ownership and scope semantics
- existing capability checks and `UiEnforcement` behavior
- existing confirmation, audit, and `OperationRun` behavior for underlying actions
- existing related-navigation truth from `RelatedNavigationResolver` and related helper methods

This feature changes action hierarchy and placement only.

## New Derived Planning Models

### HeaderSurfaceInventoryEntry

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

| Field | Type | Notes |
|------|------|-------|
| `surfaceKey` | string | Stable identifier such as `baseline_profile_view` or `tenant_edit` |
| `pageClass` | string | Concrete Filament page class under review |
| `panelScope` | string | `admin`, `tenant`, or explicit special context |
| `ownerScope` | string | `workspace-owned` or `tenant-owned` |
| `classification` | string | `remediation_required`, `minor_alignment_only`, `compliant_reference`, or `workflow_heavy_special_type` |
| `canonicalNoun` | string | Stable operator-facing object noun |
| `routeKind` | string | `view` or `edit` |
| `requiresHeaderRemediation` | boolean | Whether the page must change under Spec 192 |
| `exceptionReason` | string or null | Required when classification is special-type |

### RecordHeaderLayoutState

**Type**: derived page render contract  
**Source**: existing page action methods + page state + explicit Spec 192 rules

| Field | Type | Notes |
|------|------|-------|
| `surfaceKey` | string | Links the render state back to the inventory entry |
| `classification` | string | Same classification used by the inventory |
| `primaryActionKey` | string or null | The one visible primary action, if any |
| `primaryActionLabel` | string or null | Operator-facing label for the visible primary action |
| `primaryActionReason` | string | Why this action is primary for the current page state |
| `secondaryGroupLabel` | string or null | Usually `More`, `Actions`, or equivalent grouped-secondary label |
| `hasContextualNavigation` | boolean | Whether pure navigation moved to contextual placement outside the header |
| `hasSeparatedDangerActions` | boolean | Whether dangerous actions are structurally separated |
| `allowsNoPrimaryAction` | boolean | True for compliant reference pages or special types without one dominant next step |

### HeaderActionDescriptor

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

| Field | Type | Notes |
|------|------|-------|
| `actionKey` | string | Action name such as `capture`, `refresh_review`, or `archive` |
| `label` | string | Visible operator-facing label |
| `actionKind` | string | `navigation`, `mutation`, `external_link`, `lifecycle`, or `danger` |
| `placement` | string | `primary_visible`, `secondary_grouped`, `contextual`, or `danger_grouped` |
| `requiresConfirmation` | boolean | Mirrors existing destructive or governance friction |
| `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 |
| `operationScope` | string | `TenantPilot only`, `Microsoft tenant`, `simulation only`, or `read-only` |

### ContextualNavigationContract

**Type**: derived related-navigation placement entry  
**Source**: existing related-navigation resolver output or page-local related links

| Field | Type | Notes |
|------|------|-------|
| `entryKey` | string | Stable identifier for a related destination |
| `label` | string | Operator-facing related-link label |
| `targetUrl` | string or null | Existing target destination |
| `sourceSection` | string | `summary`, `related_context`, `field_context`, or `status_context` |
| `isAvailable` | boolean | Mirrors existing helper availability logic |
| `leaksScopeIfMisplaced` | boolean | True when placing this in the wrong layer could imply broader access |

### WorkflowHeavyHeaderGroup

**Type**: derived grouped-action contract for special-type pages  
**Source**: explicit exception handling for `ViewTenant`

| Field | Type | Notes |
|------|------|-------|
| `surfaceKey` | string | Expected to map to the special-type surface |
| `groupLabel` | string | Visible grouped-action label, usually `Actions` |
| `orderedBuckets` | array<string> | Ordered buckets such as `external_links`, `verification`, `setup`, and `lifecycle`; pure navigation remains contextual outside the header |
| `visiblePrimaryActionKey` | string or null | Optional visible primary action when a dominant next step exists |
| `requiresExplicitException` | boolean | Always true for workflow-heavy special types |

### HeaderRegressionExpectation

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

| Field | Type | Notes |
|------|------|-------|
| `surfaceKey` | string | The page under regression protection |
| `maxVisiblePrimaryActions` | integer | `1` for standard pages, `0..1` for special types, `0..1` for references as documented |
| `requiresGroupedSecondaryActions` | boolean | Whether secondaries must be grouped |
| `allowsPrimaryNavigation` | boolean | Usually false for remediated standard pages |
| `requiresDangerSeparation` | boolean | True when the page contains destructive or governance-sensitive actions |
| `requiresExplicitExceptionReason` | boolean | True for special-type pages |
| `browserSmokeRequired` | boolean | True for remediation-required pages, the explicit special-type exception, and the compliant reference baseline set |

## Resolution Rules

### Standard-page rules

1. A remediation-required standard record/detail/edit page resolves to at most one `primary_visible` action.
2. Pure navigation actions resolve to `contextual`, not to `primary_visible` or header-grouped placement.
3. Rare or administrative mutations resolve to `secondary_grouped`.
4. Destructive or governance-sensitive actions resolve to `danger_grouped` and keep confirmation.

### State-sensitive primary-action rules

- `baseline_profile_view` resolves `capture` as primary when no consumable snapshot exists.
- `baseline_profile_view` resolves `compareNow` as primary when a consumable snapshot exists.
- `tenant_review_view` resolves one of `refresh_review`, `publish_review`, or `export_executive_pack` as primary based on lifecycle state.
- `finding_exception_view` may resolve `renew_exception` as primary only when renewal is valid and visible.
- `tenant_edit` does not introduce a second page-header primary because save/cancel remain the true edit-surface primary affordance.

### Special-type rules

1. `tenant_view` may expose zero visible primaries when no single dominant next step exists.
2. If `tenant_view` exposes one visible primary, all remaining actions still stay grouped and internally ordered.
3. `tenant_view` must always carry an explicit exception reason in the inventory and regression expectations.

### Reference-page rules

1. A compliant reference page may keep a single contextual related-record link or single primary safe action without further restructuring.
2. Reference pages must not be rebuilt only to mimic the remediated pages.

## Relationships

- One `HeaderSurfaceInventoryEntry` maps to one `RecordHeaderLayoutState`.
- One `RecordHeaderLayoutState` contains many `HeaderActionDescriptor` entries.
- A page may contain zero or many `ContextualNavigationContract` entries.
- Only special-type pages use a `WorkflowHeavyHeaderGroup`.
- Every in-scope page must map to one `HeaderRegressionExpectation`.

## Safety Rules

- No derived header 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 placement.
- No grouped secondary structure may become an undocumented exception or empty placeholder.
- No regression expectation may silently exempt a page; every exception must be explicit and justified.