core/claude.md

Reanimator AI Memory (Timeline + UI Rules)

This file is the source of truth for timeline behavior, status logic, and related UI expectations. Any future AI change must preserve these rules unless explicitly changed by user request.

1. Event Time Source Priority

Use the real component event time, not ingest time, whenever available.

• eventFallbackTime(actual, ingestedAt, collectedAt) priority:

1. actual (status/event timestamp from payload)
2. ingestedAt
3. collectedAt (last fallback)

• collectedFallbackTime(collectedAt, ingestedAt) is only for collected timestamp fields:

1. collectedAt
2. ingestedAt

2. Status Event Time Parsing

Component status event time must be resolved in this order:

1. status_changed_at
2. latest matching entry in status_history for current status
3. latest parseable entry in status_history
4. status_checked_at

3. Failure Event Time Rules

For Critical components:

• timeline status event type: COMPONENT_FAILED
• failure_events.failure_time must use resolved failure time (not raw ingest time)
• failure external_id includes that same failure time

4. First Seen Logic

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

• Candidate timestamps:

1. status_history[].changed_at (all parseable entries)
2. status_changed_at
3. status_checked_at
4. fallback via eventFallbackTime(nil, ingestedAt, collectedAt) if none exists

• DB update rule: keep minimum value over time
• If existing value is newer, overwrite with earlier incoming value

5. Component Status Calculation (UI)

INSTALLED and other non-status timeline events must never "heal" a failed component.

• Component status is computed only from the latest status event among:
  • COMPONENT_FAILED
  • COMPONENT_WARNING
  • COMPONENT_OK
• INSTALLED, REMOVED, FIRMWARE_CHANGED, FIRMWARE_INSTALLED, etc. do not change component health state.

6. Firmware Timeline Events

For component firmware events:

• First observed firmware version: create FIRMWARE_INSTALLED (asset + component timeline pair)
• Later version change: create FIRMWARE_CHANGED (asset + component timeline pair)

Details:

• For FIRMWARE_INSTALLED, timeline_events.firmware_version stores transition string:
  • - -> <installed_version>
• For FIRMWARE_CHANGED, timeline_events.firmware_version stores installed/new version value.
• Firmware change detection reads previous observation with:
  • ORDER BY observed_at DESC, id DESC LIMIT 1 OFFSET 1
  • (current observation is already inserted in the same ingest transaction)

7. Timeline Visual Semantics

Color coding requirements:

• REMOVED must be yellow
• COMPONENT_FAILED must be red
• Warning/failure classes follow existing timelineEventClass rules

8. Asset Page Structure

Asset page must contain:

1. Current Components
2. Previous Components (directly below Current Components)
3. Movement & Events

Previous Components includes components previously installed on this asset and currently removed.

9. Component Page Requirements

Component page must include:

• Component card with current Firmware
• Installation history table:
  • Asset
  • Installed At
  • Removed At
• Timeline metadata equivalent to asset timeline:
  • Type
  • Location
  • Model
  • Firmware (with fallback to latest known component firmware)

10. Repository APIs Added for This Behavior

• timeline.EventRepository.ListLatestBySubjectsAndEventTypes(...)
• registry.InstallationRepository.ListPreviousComponentsByAsset(...)
• registry.InstallationRepository.ListInstallationHistoryByComponent(...)

These methods are part of expected data flow for UI and status logic.

11. Regression Guardrails

Do not reintroduce any of these regressions:

• using ingest timestamp instead of real failure/event time when payload has a better 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