194 lines
4.1 KiB
Markdown
194 lines
4.1 KiB
Markdown
# 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.
|