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.