core/bible/architecture/runtime-flows.md

Runtime Flows And Invariants

Event Time Source Priority

Use component event time over ingest time whenever possible.

• eventFallbackTime(actual, ingestedAt, collectedAt):

1. actual
2. ingestedAt
3. collectedAt

• collectedFallbackTime(collectedAt, ingestedAt):

1. collectedAt
2. ingestedAt

Status Event Time Parsing Order

parseComponentStatusEventTime resolves time in this order:

1. status_changed_at
2. Latest matching status_history item for current status
3. Latest parseable status_history item
4. status_checked_at

Failure Event Rules

For critical components:

• Timeline event type: COMPONENT_FAILED
• failure_events.failure_time uses resolved failure time (not raw ingest time)
• failure_events.external_id includes the same failure timestamp

First Seen Rules

parts.first_seen_at must be the earliest known ingest-derived component time.

Candidate sources:

1. Parseable status_history[].changed_at
2. status_changed_at
3. status_checked_at
4. eventFallbackTime(nil, ingestedAt, collectedAt)

Persistence rule:

• Keep the minimum value over time.
• If incoming is earlier than stored value, overwrite with incoming value.

Duplicate Component Serial Rules (CSV + JSON Ingest)

If serial numbers are not unique within the same p/n (model) inside one ingest payload:

• First occurrence keeps original vendor_serial.
• Each next duplicate occurrence is assigned a service serial placeholder:
  • Format: NO_SN-XXXXXXXX (8-digit zero-padded global counter).
• If vendor_serial is empty, a service serial placeholder is assigned as well.
• Counter is global for the whole application and stored in id_sequences under entity_type = 'no_sn_placeholder'.

Component Health Computation In UI

Component health is derived only from the latest status event among:

• COMPONENT_FAILED
• COMPONENT_WARNING
• COMPONENT_OK

Non-status timeline events (INSTALLED, REMOVED, FIRMWARE_CHANGED, FIRMWARE_INSTALLED, etc.) must not change health status.

Firmware Timeline Rules

For component firmware observations:

• First observed version -> FIRMWARE_INSTALLED (asset + component timeline pair)
• Later version change -> FIRMWARE_CHANGED (asset + component timeline pair)

Storage details:

• FIRMWARE_INSTALLED stores transition string in timeline_events.firmware_version: - -> <installed_version>
• FIRMWARE_CHANGED stores installed/new firmware value

Detection details:

• Previous observation lookup: ORDER BY observed_at DESC, id DESC LIMIT 1 OFFSET 1

Timeline Color Semantics

• REMOVED -> yellow
• COMPONENT_FAILED -> red
• COMPONENT_WARNING and related warning semantics follow timelineEventClass

Regression Guardrails

Do not reintroduce these regressions:

• Using ingest timestamp when payload provides better event/failure timestamp
• Letting INSTALLED mark failed components as healthy
• Missing Previous Components section on asset page
• Missing installation history on component page
• Missing firmware information on component page timeline