TenantAtlas/specs/197-shared-detail-contract/data-model.md

# Phase 1 Data Model: Shared Detail Micro-UI Contract

## Overview

This feature adds no database table, no persisted UI artifact, and no new state family. It formalizes two existing shared detail families as runtime contracts with explicit host-variation boundaries.

## Persistent Source Truths

### OperationRun

**Purpose**: Supplies stored verification status, timing, target scope, failure summary, and the raw verification report payload already used by the current verification hosts.

**Key fields**:

- `id`
- `workspace_id`
- `tenant_id`
- `type`
- `status`
- `outcome`
- `started_at`
- `completed_at`
- `context.verification_report`
- `context.target_scope`
- `failure_summary`

**Validation rules**:

- Verification family rendering remains DB-only and derives only from stored run data.
- No host may introduce a second source of verification truth outside the run payload and existing support helpers.

### Policy and PolicyVersion snapshot truth

**Purpose**: Supplies the source payloads for normalized settings and version-to-version diffs.

**Key fields**:

- `policies.id`
- `policies.tenant_id`
- `policies.policy_type`
- `policies.platform`
- `policy_versions.id`
- `policy_versions.policy_id`
- `policy_versions.snapshot`
- `policy_versions.policy_type`
- `policy_versions.platform`

**Validation rules**:

- The settings and diff families remain derived from current normalized snapshot truth.
- No new persisted “surface state” may be added to remember tabs, expanded sections, or unavailable-state decisions.

### Finding drift evidence

**Purpose**: Supplies the source references and availability reasons for diff rendering on drift findings.

**Key fields**:

- `findings.id`
- `findings.tenant_id`
- `findings.finding_type`
- `findings.evidence_jsonb.summary.kind`
- `findings.evidence_jsonb.baseline.policy_version_id`
- `findings.evidence_jsonb.current.policy_version_id`

**Validation rules**:

- Diff availability remains derived from referenced versions and current tenant context.
- The shared diff family must express unavailable or partial state from these sources instead of letting each host improvise new rules.

## Existing Runtime Source Objects

### VerificationReportViewer

**Purpose**: Existing support seam that extracts and validates the verification report, computes fingerprints, and resolves previous runs.

**Current responsibilities already present**:

- `report()`
- `fingerprint()`
- `previousRun()`
- `shouldRenderForRun()`
- `redactionNotes()`

**Relationship to this feature**:

- It becomes the narrow verification-family contract seam rather than being replaced.
- It should grow family-owned shaping helpers instead of remaining only a payload extractor.

### PolicyNormalizer, VersionDiff, and DriftFindingDiffBuilder

**Purpose**: Existing domain truth builders that already normalize settings and derive diffs.

**Relationship to this feature**:

- They remain the domain truth source.
- The new family contracts sit after these builders and before host rendering.
- The feature must not create a second normalization pipeline.

### SettingsCatalogSettingsTable

**Purpose**: Existing Livewire renderer for the settings-catalog table subtype.

**Relationship to this feature**:

- It remains the renderer for one settings subtype.
- The settings family wrapper decides when it appears and with what shared wrapper semantics.

## New Derived Runtime Contracts

### VerificationReportSurfaceContract

**Purpose**: One runtime contract that defines the verification family’s shared zones and allowed host variations.

#### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `host_kind` | enum(`operation_run_detail`,`onboarding_wizard`,`tenant_widget`) | yes | Current host family consumer |
| `core_state` | enum(`unavailable`,`completed`) | yes | Shared family core state after host-owned no-run or in-progress framing |
| `summary` | object | yes | Overall badge, counts, and change-indicator data |
| `issue_groups` | array | yes | Grouped blockers, failures, warnings, and acknowledged issues |
| `passed_checks` | array | yes | Checks rendered under the passed zone |
| `diagnostics` | object | yes | Fingerprint, run identity, previous-run link, and related technical details |
| `view_zones` | array | yes | Ordered family view or tab definitions |
| `next_steps` | array | yes | Shared next-step items derived from report checks |
| `host_actions` | array | no | Host-owned actions such as assist, acknowledge, refresh, or open operation |
| `optional_zones` | array | no | Family-recognized zones that may be absent, such as technical details |
| `empty_state` | object nullable | no | Family-owned unavailable-state explanation when no valid report payload exists |

#### Validation rules

- The contract must own one tab or view model across all completed or unavailable verification surfaces.
- Hosts may append actions and framing, but may not redefine issue grouping, passed-check grouping, or diagnostics ownership.
- Host actions must declare whether they are shared navigation, host assist, or host mutation.

### VerificationReportHostVariation

**Purpose**: Declares the bounded host-owned differences for a verification-family consumer.

#### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `owns_no_run_state` | bool | yes | Whether the host frames its own pre-run state |
| `owns_active_state` | bool | yes | Whether the host frames its own in-progress state |
| `supports_acknowledge` | bool | yes | Whether the host may surface acknowledgement mutations |
| `supports_assist` | bool | yes | Whether the host may route next steps through assist actions |
| `supports_technical_details_trigger` | bool | yes | Whether the host exposes a dedicated technical-details trigger outside the family core |

#### Validation rules

- Host variation may extend actions and framing only.
- Host variation must never add a second structural tab system or redefine the diagnostics contract.

### NormalizedSettingsSurfaceContract

**Purpose**: One runtime contract that defines the normalized settings family’s wrapper ownership, subtype selection, warnings, and empty-state behavior.

#### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `host_kind` | enum(`policy`,`policy_version`) | yes | Host context for the settings family |
| `context` | enum(`policy`,`version`) | yes | Existing context string used for table query-string isolation and titles |
| `variant` | enum(`settings_catalog_table`,`standard_blocks`) | yes | Explicit subtype used by the shared family |
| `warnings` | array | no | Warning list displayed by the family wrapper |
| `settings_table` | object nullable | no | Table subtype payload when the settings-catalog subtype is active |
| `blocks` | array | no | Standard block payload for general, table, or key-value sections |
| `section_behavior` | object | yes | Shared section-order, expansion, and empty-state ownership rules for the settings family |
| `render_expectations` | object | yes | Explicit wrapper expectations for warnings, subtype delegation, and host-framing boundaries |
| `empty_state` | object nullable | no | Family-owned empty or unavailable message when no settings payload exists |
| `title_policy` | object | yes | Rules for whether wrapper or subtype titles are shown |

#### Validation rules

- Hosts may not choose sibling top-level settings blades once the family contract exists.
- Subtypes must be explicit family variations, not host-selected main variants.
- Warning and empty-state behavior must come from the family wrapper, not from host-specific text entries.
- Section order, expansion behavior, and wrapper expectations must be explicit so hosts do not silently redefine how the family reads.

### NormalizedDiffSurfaceContract

**Purpose**: One runtime contract that defines normalized diff summary, grouped rendering, unavailable behavior, and zero-diff messaging.

#### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `host_kind` | enum(`policy_version`,`finding`) | yes | Host context for the diff family |
| `availability_state` | enum(`available`,`unavailable`,`partial`) | yes | Family-owned availability state |
| `summary` | object | yes | Added, removed, changed counts and summary message |
| `view_modes` | array | yes | Explicit diff-family modes or views that the host may expose without redefining the family |
| `section_behavior` | object | yes | Shared grouped-section order, expansion, and fullscreen rules |
| `render_expectations` | object | yes | Explicit ownership of availability, zero-diff messaging, and host-framing boundaries |
| `groups` | array | no | Changed, added, and removed groups with ordered row payloads |
| `script_rendering` | object | no | Script-highlighting flags and grammar hints |
| `empty_state` | object nullable | no | Family-owned zero-diff or unavailable-state explanation |

#### Validation rules

- Hosts may not prepend separate unavailable-state entries for the same normalized diff concept.
- The family must own both true unavailable and zero-diff informational states.
- Rich script rendering remains allowed, but it must live inside the family contract.
- View modes, grouped-section behavior, and render expectations must be explicit so a policy-version diff and a finding diff cannot drift into separate interaction models.

## Consumer Mapping

| Consumer | Family | Shared-family responsibility | Local host responsibility |
|---|---|---|---|
| `OperationRunResource` verification section | Verification report | Completed and unavailable verification core, tab contract, diagnostics, grouped issues | Section placement inside enterprise detail, record authorization, no new mutation behavior |
| `ManagedTenantOnboardingWizard` verify step | Verification report | Completed and unavailable verification core, grouped issues, diagnostics, shared view zones | No-run and active-state framing, assist routing, acknowledge action, verify-step workflow actions |
| `TenantVerificationReport` widget | Verification report | Completed and unavailable verification core | Widget no-run and active-state framing, start-verification CTA, tenant operability copy |
| `PolicyResource` settings tab or fallback section | Normalized settings | Warnings, empty state, subtype ownership, wrapper structure | Tab framing, route context, surrounding policy detail layout |
| `PolicyVersionResource` normalized settings tab | Normalized settings | Same settings family contract as policy detail | Tab framing and version-specific surrounding detail layout |
| `PolicyVersionResource` diff tab | Normalized diff | Summary, grouped diff rendering, zero-diff and unavailable semantics | Tab framing and raw diff sidecar JSON |
| `FindingResource` diff section | Normalized diff | Same diff family contract as policy-version diff | Surrounding drift-specific sections, version resolution, and domain-specific sibling diff viewers kept out of scope |

## Derived Lifecycle

1. A host resolves current domain truth using existing run, normalization, or diff builders.
2. The host passes that truth through the appropriate shared family contract seam.
3. The family contract shapes shared zones, states, and subtype markers.
4. The host renders the shared family core and attaches only its allowed host-owned variations.
5. Tests assert that a new host cannot redefine family structure outside those variations.

## Migration Notes

- No database migration is required.
- `policy-settings-standard.blade.php` must stop acting as a sibling top-level host choice and become an internal subtype or be absorbed.
- Existing verification DB-only and tenant widget tests remain the primary regression base for the verification family.
- Existing policy-version and drift-diff tests remain the primary regression base for normalized detail families.