# 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.