core/bible/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
• 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.