SLICE-002: Persistent Run History

• Status: Draft
• Date: 2026-04-14
• Depends on: Requirements, ADR-001: Use Central App State Store, ADR-002: File-Backed Run History Store Before Database Persistence

Goal

Persist terminal run summaries across application restarts and expose a usable run history view so operators and developers can review more than the single most recent run.

Why This Slice

The first slice already creates RunSummary objects and projects a single LastRunSummary into the UI.

This slice extends that foundation without reopening the core workflow semantics:

• persistence becomes durable
• history becomes visible
• the architecture gains a practical storage seam

Requirements Coverage

This slice extends or activates these requirement areas:

• Section 7.11 Logging and Diagnostics
• Section 7.12 Run Summary
• Section 8.2 Diagnostics View
• Section 9.3 Architectural Boundaries
• Section 9.5 App State Management
• Section 9.10 Testability
• Section 10.3 Observability
• Section 10.4 Maintainability
• Section 16 Future Expansion Areas

In Scope

• persist run summaries beyond the in-memory lifetime of the app
• load stored run history on startup
• expose a RunHistory collection in canonical app state
• keep LastRunSummary aligned with the newest history item
• show recent run history in the UI
• tolerate missing history files gracefully
• handle corrupted history files safely enough for a prototype
• keep the storage boundary behind an application abstraction

Out of Scope

• database persistence
• full reporting and analytics
• advanced filtering, search, or export
• multi-machine history
• distributed synchronization

Runtime Behavior

History Model

The system must preserve terminal RunSummary records for:

• Completed
• Stopped
• Aborted
• Faulted

History must be represented separately from the currently active run.

Startup Hydration

On application startup:

• the history store is queried
• previously persisted run summaries are loaded into canonical app state
• LastRunSummary becomes the newest history entry if one exists
• missing storage must not fail app startup

Persistence On Terminal Run

When a run reaches a terminal state:

• the run summary is written to the history store
• duplicate entries for the same RunId must not be created
• app state history is updated so the UI reflects the new record

Ordering

For the first persisted-history slice:

• the history shown in app state and UI should be newest first
• the newest item should match LastRunSummary

Failure Handling

If the history store cannot load or save:

• the app must add diagnostics or log entries
• the failure must not crash the entire app
• the user may continue using the runtime even if history persistence is degraded

For a corrupted history file:

• the app must fail safely
• the corruption must be surfaced through diagnostics or logs
• the exact recovery policy should be documented in implementation

UI Expectations

The UI for this slice should add:

• a recent run history list or panel
• enough information to distinguish status, recipe, time, and defect count per run
• a clear indication when no history exists yet

The UI does not need advanced filtering or separate navigation for this slice.

Layer Boundaries

This slice must preserve the same architectural boundaries as the first slice:

• application defines the history abstraction and state projection rules
• infrastructure implements the file-backed store
• presentation consumes canonical app state
• UI does not read files directly

Acceptance Criteria

This slice is satisfied only if all of the following are true:

1. On startup, previously persisted run summaries are loaded into app state when history exists.
2. When no history file exists, the app starts normally and shows an empty history state.
3. After a terminal run, the new run summary is persisted and appears in both LastRunSummary and RunHistory.
4. The history list is ordered newest first.
5. Duplicate history entries are not created for the same RunId.
6. A corrupted or unreadable history file does not crash the app and produces diagnostics or logs.
7. The UI shows recent run history with enough detail to identify recipe, terminal status, timing, and defect count.
8. Core history behavior is testable without launching the full UI.

Verification Notes

The implementation task for this spec must include verification for:

• startup hydration with existing history
• empty history startup behavior
• successful append or upsert after terminal runs
• ordering and duplication rules
• corrupted file handling