---
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.