TenantAtlas/specs/141-shared-diff-presentation-foundation/data-model.md

# Data Model: Shared Diff Presentation Foundation

## Overview

This feature adds presentation-layer value objects and support types only. No database schema or persisted business record changes are introduced.

## Entities

### 1. DiffRowStatus

- **Type**: PHP backed enum
- **Purpose**: Canonical presentation-state vocabulary for shared diff rendering
- **Values**:
  - `unchanged`
  - `changed`
  - `added`
  - `removed`
- **Rules**:
  - Treated as a presentation concern only
  - Drives summary counts, badge semantics, icons, and row-state rendering
  - Must remain reusable outside any single resource or domain service

### 2. DiffRow

- **Type**: Immutable value object / DTO
- **Purpose**: Render-ready representation of one compare row
- **Fields**:
  - `key`: string
  - `label`: string
  - `status`: `DiffRowStatus`
  - `oldValue`: mixed
  - `newValue`: mixed
  - `isListLike`: bool
  - `addedItems`: array<int, mixed>
  - `removedItems`: array<int, mixed>
  - `unchangedItems`: array<int, mixed>
  - `meta`: array<string, scalar|array|null>
- **Validation rules**:
  - `key` must be non-empty
  - `label` must be non-empty
  - `status` must be one of the enum values
  - List fragment arrays must be present as empty arrays when not used
  - `meta` must stay presentation-safe and serializable for view consumption

### 3. DiffSummary

- **Type**: Immutable value object / DTO
- **Purpose**: Shared summary counts and high-level message context for a rendered compare block
- **Fields**:
  - `changedCount`: int
  - `addedCount`: int
  - `removedCount`: int
  - `unchangedCount`: int
  - `hasRows`: bool
  - `message`: ?string
- **Validation rules**:
  - Counts are non-negative integers
  - `hasRows` is derived from total count
  - `message` is optional and consumer-supplied or presenter-generated fallback copy

### 4. DiffPresentation

- **Type**: Immutable value object / DTO
- **Purpose**: Stable wrapper returned by `DiffPresenter` so consumers can pass one object containing summary and ordered rows into shared partials or downstream adapters
- **Fields**:
  - `summary`: `DiffSummary`
  - `rows`: array<int, DiffRow>
- **Validation rules**:
  - `summary` must always be present
  - `rows` must preserve deterministic ordering
  - Empty compares are represented as an empty `rows` collection plus an explicit summary state

### 5. StructuredCompareInput

- **Type**: Internal input shape consumed by `DiffPresenter`
- **Purpose**: Minimal adaptation contract for simple compare payloads
- **Fields**:
  - `baseline`: array<string, mixed>
  - `current`: array<string, mixed>
  - `changedKeys`: array<int, string>
  - `labels`: array<string, string>
  - `meta`: array<string, array<string, scalar|array|null>>
- **Rules**:
  - `baseline` and `current` may each omit keys that exist on the other side
  - `changedKeys` is optional hint data; presenter can still derive state from values
  - `labels` is optional and must not block rendering when absent

### 6. InlineListFragments

- **Type**: Derived presentation fragment embedded in `DiffRow`
- **Purpose**: Simple inline list diff rendering for string or scalar lists
- **Fields**:
  - `addedItems`: array<int, mixed>
  - `removedItems`: array<int, mixed>
  - `unchangedItems`: array<int, mixed>
- **Rules**:
  - Built only when both values are simple list-like collections appropriate for inline comparison
  - Ordering should remain deterministic for stable rendering and tests
  - Not intended for token-level or line-level diff logic

## Relationships

- One `DiffSummary` describes a collection of `DiffRow` instances.
- Each `DiffRow` has exactly one `DiffRowStatus`.
- `DiffPresenter` converts one `StructuredCompareInput` into one `DiffPresentation`, containing one `DiffSummary` plus an ordered list of `DiffRow` instances.
- `ValueStringifier` formats `DiffRow.oldValue`, `DiffRow.newValue`, and inline list items for display, but can also be used independently by specialized views.

## State transitions

### Row classification

- Missing in baseline + present in current → `added`
- Present in baseline + missing in current → `removed`
- Present on both sides + materially equal → `unchanged`
- Present on both sides + materially different → `changed`

### Summary derivation

- Summary counts are derived from the final `DiffRow` list.
- Empty compare input produces either an empty summary or a no-data state, but never synthetic changes.

## Non-persistent boundaries

- None of these entities map to database tables.
- None of these entities may fetch models or rely on Livewire runtime state.
- None of these entities define authoritative business drift, compare, or restore logic.