4.1 KiB
Epic 1.5: Event Store Hardening (Concurrency, Integrity, and Replay Safety)
status: proposed
date: 08.05.2026 (May)
scope: :core:events, :infrastructure:persistence
context
Epic 1 establishes a functional event-sourced storage system (in-memory + SQLite) with correct basic semantics: append, read, ordering, and idempotency.
However, current implementation assumes ideal conditions:
- single-threaded or externally synchronized writes
- stable event schema
- no replay pressure under large histories
- no concurrent access patterns
These assumptions do not hold once the system is integrated into orchestration (:core:kernel) and async execution (coroutines, CLI + server).
Epic 1.5 introduces hard guarantees required for real execution environments, without changing the external EventStore contract.
goal
Make the event store:
deterministic, concurrency-safe, replay-stable, and schema-resilient under real execution conditions
scope (what IS included)
1. concurrency model definition
Define and enforce:
- single-writer guarantee per EventStore instance
- behavior under concurrent
append/appendAll - read consistency rules during writes
deliverable:
- documented concurrency contract in
EventStore
2. SQLite transactional correctness
Ensure SQLite implementation guarantees:
- atomic
appendAll(single transaction boundary) - no partial writes on failure
- deterministic ordering under concurrent calls (within single instance constraints)
work:
- explicit transaction wrapping
BEGIN/COMMIT/ROLLBACKsafety handling- removal of implicit autocommit ambiguity
3. sequence integrity under concurrency
Guarantee:
- per-session sequence monotonicity
- no race-condition-based sequence duplication
- consistent
lastSequence()computation under concurrent writes
possible approaches:
- synchronized write lock per session
- or single global write lock (simpler, acceptable for v1)
4. contract test hardening (EventStoreContractTest upgrade)
Expand contract tests to include:
- concurrent append simulation
- appendAll atomicity verification
- read consistency during write bursts
- deterministic replay under repeated execution
5. snapshot preparation layer (interface only)
Introduce:
SnapshotStoreinterface (no full implementation required yet)- hook points in EventStore for snapshot triggers
This is structural preparation only.
6. event schema version discipline
Enforce:
versionfield is mandatory and meaningful- serialization must be version-aware
- unknown version behavior defined (fail fast initially)
No migration logic yet, only rules.
7. replay determinism guarantee
Formalize:
replay of the same event stream must produce identical projections regardless of store implementation
This becomes a top-level invariant.
explicit exclusions (important)
Epic 1.5 does NOT include:
- sessions / FSM logic
- transitions / graph engine
- approval system evolution
- context processing
- inference orchestration
- distributed storage (Kafka, Redis, etc.)
consequences
positive
- removes race-condition ambiguity in kernel integration
- guarantees EventStore correctness under async execution
- makes replay safe for debugging and dataset generation
- stabilizes foundation for all higher-level epics
negative
- introduces stricter constraints on store implementations
- adds concurrency complexity to SQLite layer
- increases test surface area significantly
- forces early clarity on threading model (good, but non-trivial)
rationale
Without this layer, higher-level systems will assume inconsistent event semantics depending on:
- execution timing
- store implementation
- concurrency patterns in kernel
This breaks the core promise of Correx:
deterministic replayable execution over nondeterministic inference systems
Epic 1.5 ensures the event layer is not just correct, but operationally invariant.
status
Recommended immediately after Epic 1 completion and before introduction of:
:core:sessions:core:kernel:core:transitions