58 lines
2.3 KiB
Markdown
58 lines
2.3 KiB
Markdown
---
|
||
name: "Adr 0001 Event Sourcing"
|
||
description: "Decision to use event sourcing as primary persistence model"
|
||
depth: 2
|
||
links: ["../index.md", "../architecture/event-model.md", "./adr-0000-invariants.md"]
|
||
---
|
||
|
||
# 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. |