epic-12: after epic audit and init commit

2026-05-16 11:42:00 +04:00
commit c77277af0b
461 changed files with 28958 additions and 0 deletions
@@ -0,0 +1,58 @@
+---
+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.