# Data Model And Migration Boundaries

## Naming Model

- Internal canonical naming uses `Machine` and `Part`.
- API/UI compatibility keeps `asset` and `component` terminology where already exposed.
- In domain aliases:
  - `type Asset = Machine`
  - `type Component = Part`

## Core Persistence Areas

- Asset registry: `machines`
- Component registry: `parts`
- Installations: `installations`
- Observations: `observations`
- Timeline: `timeline_events`
- Failures: `failure_events`
- Asset firmware state: `machine_firmware_states`
- Component history (canonical): `component_change_events`, `component_state_snapshots`
- Asset history (canonical): `asset_change_events`, `asset_state_snapshots`
- History jobs/audit: `history_recompute_jobs`, `history_admin_audit`

Out of active model:
- `projects` is legacy and not used by runtime handlers/contracts.

## Migration Policy

- Migrations are stored in `migrations/`.
- Schema migrations are applied at startup.
- Legacy entities removed in migration `0016_remove_legacy_features` remain out of active scope.
- History architecture was introduced in migration `0017_history_core`.

## Canonical State Model (History-First)

- `parts` and `machines` are current-state projections optimized for reads.
- `component_change_events` / `asset_change_events` are canonical state-change logs.
- `component_state_snapshots` / `asset_state_snapshots` store full after-state snapshots for each state-changing event.
- `timeline_events`, `installations`, `failure_events`, and `machine_firmware_states` are projections and may be rebuilt from history.

## History Event Storage Rules

- History events are versioned per entity (`version` is monotonic per component/asset).
- State-changing writes persist:
1. change event
2. after-state snapshot
3. projection updates (`parts` / `machines` and related projections)
4. timeline projection rows
- History event deletion is soft-delete (`is_deleted`) for normal user/admin flow.
- Hard restore is destructive for future history rows and is audited in `history_admin_audit`.

## Timeline Projection Linkage

`timeline_events` includes logical linkage back to history:

- `logical_entity_type`
- `logical_event_id`
- `correlation_id`
- `is_deleted`

This linkage is required for recompute, rollback/delete propagation, and paired asset/component timeline rendering.