epic-12: after epic audit and init commit

docs/epics/epic-1.md

@@ -0,0 +1,193 @@
+# Epic 1: Event System Core (Append-only Log Foundation)
+
+**status:** accepted
+**date:** 07.05.2026 (May)
+**scope:** `:core:events`
+
+---
+
+## context
+
+Correx is built on deterministic replay of nondeterministic execution. The only reliable source of truth is a structured event log.
+
+To support:
+
+* reproducible session execution
+* crash recovery
+* offline debugging
+* synthetic data generation
+
+the system requires a strict event sourcing foundation.
+
+This epic establishes the minimal, correct event system abstraction before any orchestration logic exists.
+
+---
+
+## goal
+
+Define and implement a **fully functional event sourcing core** that provides:
+
+> an append-only, ordered, immutable event log with deterministic replay capability
+
+---
+
+## scope (what IS included)
+
+### 1. event model definition
+
+Define the canonical event structure:
+
+* `EventEnvelope`
+
+    * `eventId`
+    * `sessionId`
+    * `sequence`
+    * `timestamp`
+    * `version`
+    * `causationId`
+    * `correlationId`
+    * `payload`
+
+### 2. payload abstraction
+
+Define `EventPayload` interface for polymorphic event content.
+
+Implement concrete event types (initial minimal set):
+
+* tool invocation event
+* approval event (minimal placeholder)
+* session lifecycle event (minimal placeholder)
+
+No domain expansion beyond structural needs.
+
+---
+
+### 3. serialization system
+
+Implement deterministic serialization using `kotlinx.serialization`:
+
+* polymorphic module for `EventPayload`
+* stable JSON encoding (`Json`)
+* version field included for forward compatibility
+
+Guarantee:
+
+> identical event → identical serialized form
+
+---
+
+### 4. EventStore interface
+
+Define core contract:
+
+* `append(event)`
+* `appendAll(events)`
+* `read(sessionId): List<EventEnvelope>`
+* `lastSequence(sessionId): Long`
+
+Rules:
+
+* append-only semantics
+* no mutation or update operations
+* ordering guaranteed per session
+
+---
+
+### 5. in-memory EventStore implementation
+
+Provide reference implementation:
+
+* deterministic ordering per session
+* idempotency via eventId deduplication
+* sequence generation per session
+* strict ordering enforcement
+
+Used for:
+
+* contract testing
+* fast execution
+* deterministic simulation
+
+---
+
+### 6. SQLite EventStore implementation (v1 baseline)
+
+Provide persistence-backed implementation:
+
+* append events into SQLite table
+* enforce uniqueness via `event_id`
+* store sequence per session
+* support ordered reads via SQL query
+
+No concurrency guarantees in Epic 1 (deferred to Epic 1.5).
+
+---
+
+### 7. contract test suite (EventStoreContractTest)
+
+Define shared behavior validation:
+
+* ordering is preserved
+* idempotency rules are consistent
+* read returns correct sequence
+* appendAll preserves ordering semantics
+* both implementations behave identically
+
+This becomes the **canonical correctness definition**.
+
+---
+
+## explicit exclusions (important)
+
+Epic 1 does NOT include:
+
+* concurrency safety guarantees
+* snapshotting
+* transaction management hardening
+* session lifecycle logic
+* workflow transitions
+* orchestration kernel
+* distributed storage
+* performance optimization
+* schema migration system
+
+---
+
+## consequences
+
+### positive
+
+* establishes single source of truth for all system state
+* enables deterministic replay foundation
+* allows testing higher-level logic via event streams
+* decouples domain logic from persistence mechanics
+* provides interchangeable storage backends
+
+### negative
+
+* naive SQLite implementation may not reflect production concurrency needs
+* no snapshot support → replay cost increases over time
+* schema evolution is manually managed initially
+* requires strict discipline to avoid leaking mutable state concepts upward
+
+---
+
+## rationale
+
+Event sourcing must be introduced as a **pure, minimal abstraction first**, without mixing:
+
+* orchestration logic
+* concurrency concerns
+* optimization layers
+
+This ensures that all higher-level systems depend on a stable, predictable contract rather than implementation behavior.
+
+---
+
+## status
+
+Epic 1 is the **foundation layer of Correx architecture**.
+
+All subsequent epics (sessions, transitions, kernel, approvals, context) assume:
+
+> EventStore is correct, deterministic, and interchangeable across implementations.