4.1 KiB
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:
-
EventEnvelopeeventIdsessionIdsequencetimestampversioncausationIdcorrelationIdpayload
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.