epic-12: after epic audit and init commit

docs/epics/epic-1.5.md

@@ -0,0 +1,178 @@
+# 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/ROLLBACK` safety 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:
+
+* `SnapshotStore` interface (no full implementation required yet)
+* hook points in EventStore for snapshot triggers
+
+This is structural preparation only.
+
+---
+
+### 6. event schema version discipline
+
+Enforce:
+
+* `version` field 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`