core/bible-local/architecture/data-model.md

# 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`
- Asset sensor readings: `machine_sensor_readings`
- Asset logs: `machine_event_logs`
- 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`

## Sensor Readings

`machine_sensor_readings` is a last-known-value projection for hardware sensors per asset.

- Primary key: `(machine_id, sensor_type, sensor_name)`.
- `sensor_type` is one of: `fan`, `power`, `temperature`, `other`.
- `value_json` stores type-specific numeric readings (see JSON import contract).
- Updated on every ingest — not history-backed (no events, no snapshots).
- `collected_at` reflects the source observation time, not ingest time.

## Asset Event Logs

`machine_event_logs` is a deduplicated append/update read model for host/BMC/Redfish logs per asset.

- Scope: operational log entries shown in dedicated asset log views, not timeline/history.
- Logical identity is a normalized log fingerprint, not the raw ingest row.
- Required stored dimensions:
  - `machine_id`
  - `log_source` (`host`, `bmc`, `redfish`)
  - `fingerprint`
  - `event_time`
  - `severity`
  - `message_id`
  - `message`
  - `component_ref`
  - `raw_payload_json`
  - `first_seen_at`
  - `last_seen_at`
  - `seen_count`
- Upsert rule:
  - new fingerprint for same asset/source -> insert new log row
  - repeated fingerprint -> update `last_seen_at`, increment `seen_count`, refresh mutable presentation fields if needed
- Not history-backed:
  - no `asset_change_events`
  - no `component_change_events`
  - no `timeline_events`
- `raw_payload_json` is retained for diagnostics and vendor-specific fields.

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`.
- Timeline UI/filter denormalized facets were added in migration `0018_timeline_ui_facets`.
- Installation slot/location (`installations.slot_name`) was added in migration `0019_installation_slot_name`.
- History-first `component_type` projection/storage backfill was introduced in migration `0020_component_type_history_first`.

## 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.
- `observations` is a raw ingest trace/audit store and must not be used as source-of-truth for current component/asset state in runtime UI/API flows.
- `parts.component_type` and `installations.slot_name` are the runtime-readable projections for component type and current slot/location (not `observations.details`).

## 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.

`timeline_events` also stores denormalized UI/filter facets (projection-only, rebuildable from history + registry state), including:

- `source_type`
- `visual_action`
- `component_serial`
- `component_model` (used as v1 `part_number`)
- `asset_serial`
- `asset_name_cached`
- `slot_name`
- `device_name`
- `changed_fields_json`

These fields are not canonical state and must be treated as timeline projection helpers only.

## Installation Slot (Current Components UI)

- `installations.slot_name` is the canonical editable slot/location for a component attached to a server.
- Asset page `Current Components` bulk actions (`Add / Edit / Remove`) read/write slot through history-driven component installation state (`installation.slot_name` in component snapshots) and synchronize projection `installations.slot_name`.
- Runtime invariant (app-level validation):
  - for the same `machine_id`, open installations (`removed_at IS NULL`) must not share the same non-empty `slot_name`.
- Projection-update nuance:
  - slot uniqueness validation must only block writes when `slot_name` is actually changing for the installation row (status-only edits must not fail because of pre-existing duplicate slot data).