2.3 KiB
2.3 KiB
name, description, depth, links
| name | description | depth | links | |||
|---|---|---|---|---|---|---|
| Adr 0001 Event Sourcing | Decision to use event sourcing as primary persistence model | 2 |
|
ADR 0001: use event sourcing as the foundational state model
status: accepted
date: 07.05.2026 (May)
deciders: Kami
context
Correx orchestrates workflows driven by nondeterministic language models. To achieve reliability, we need:
- full traceability of every decision
- the ability to replay and debug sessions offline
- deterministic recovery after crashes
- a way to generate synthetic training data from execution history
Traditional mutable‑state architectures would make debugging a nightmare: hidden state, race conditions, and the inability to step backward would undermine the core promise of “deterministic‑enough” execution.
decision
We adopt event sourcing as the fundamental persistence and state management pattern.
- All workflow state is derived from an append‑only log of immutable events.
- Projections (the current state of a session) are rebuilt from events on demand or via snapshots.
- No mutable memory exists outside the event stream.
consequences
positive:
- Complete auditability: every state transition, approval, and validation is recorded.
- Replayability: a session can be re‑run from scratch with different models or in “dry” mode.
- Recovery: if the Harness crashes, we can resume by replaying the event log.
- Testability: orchestration logic can be tested with fabricated event streams.
- Synthetic dataset generation: replay can feed other models or evaluations.
negative:
- Eventual storage growth; mitigated by snapshots and configurable retention policies.
- Complexity in designing projections and replay logic; mitigated by clear module boundaries (
:core:events,:core:projections). - Event schema evolution must be handled deliberately; versioning and migration tooling needed.
alternatives considered
- Mutable relational state with audit tables: would still need manual change tracking, harder to guarantee deterministic replay.
- Op log in a distributed database: overkill for local‑first operation; introduces ordering complexity.
status
This decision is foundational and will not be revisited without a complete architectural overhaul.