# Epic 1 — Event System (Append-Only Event Backbone)

## completed deliverables

### 1. event identity and metadata model

implemented a strict identity and causality model for all events in the system.

final structures:

* `EventId`
* `SessionId`
* `CorrelationId`
* `CausationId`
* `EventMetadata`

key properties:

* immutable identifiers
* replay-safe metadata
* explicit causality tracking (no implicit execution order semantics outside sequence)

metadata is strictly separated from payload.

---

### 2. event payload model (domain-agnostic core)

introduced polymorphic event payload system as the root domain abstraction.

final structure:

* `EventPayload` (sealed polymorphic interface)
* domain events:

    * `ToolInvokedEvent`
    * `ApprovalGrantedEvent`
    * `SessionStartedEvent`
    * `SessionPausedEvent`
    * `SessionResumedEvent`
    * `SessionCompletedEvent`
    * `SessionFailedEvent`

properties:

* domain-extensible
* serialization-safe via kotlinx.serialization module
* no infrastructure coupling
* no persistence awareness

---

### 3. event envelope model

implemented a strict separation between event metadata and payload.

final structure:

```text id="e1"
StoredEvent
 ├── metadata (identity + causality + timestamp)
 ├── sequence (per-session ordering)
 └── payload (domain event)
```

envelope guarantees:

* complete event immutability
* replay-safe structure
* strict ordering contract support
* backend-agnostic representation

---

### 4. event store abstraction (core contract)

introduced append-only event store contract as system backbone.

interface guarantees:

* append-only semantics
* deterministic ordering per session
* idempotent writes via `eventId`
* read consistency guarantees
* replay-safe retrieval model

core operations:

```text id="e2"
append(event)
appendAll(events)
read(sessionId)
readFrom(sessionId, sequence)
lastSequence(sessionId)
```

store is the **single source of truth** in the system.

---

### 5. in-memory event store (reference implementation)

implemented deterministic in-memory store for contract validation and testing.

properties:

* thread-safe append operations
* per-session sequencing via atomic counters
* duplicate event protection (eventId-based idempotency)
* deterministic read ordering guarantees

used as baseline correctness oracle for all other stores.

---

### 6. persistence alignment (sqlite implementation foundation)

introduced SQLite-based event store as infrastructure implementation.

responsibilities:

* persistent event storage
* enforcement of append-only constraints at DB level
* deterministic reconstruction of event streams
* compatibility with core event envelope model

ensures parity with in-memory reference implementation via contract tests.

---

### 7. serialization system

implemented deterministic serialization layer for event persistence.

components:

* `JsonEventSerializer`
* `SerializersModule` with polymorphic `EventPayload`
* `eventJson` configuration instance

guarantees:

* stable cross-run serialization
* replay-safe encoding/decoding
* polymorphic payload correctness
* strict schema versioning support

serialization is treated as **infrastructure concern only**, not domain logic.

---

### 8. contract-based enforcement system

introduced contract test framework to enforce event system invariants across implementations.

enforced invariants:

* append-only behavior
* idempotency via eventId
* strict per-session ordering
* deterministic read output
* cross-implementation parity (in-memory vs sqlite)

contract layer ensures:

> correctness is enforced structurally, not assumed per implementation

---

### 9. concurrency and ordering guarantees

validated event store behavior under concurrent access conditions.

guarantees established:

* safe concurrent appends per session
* deterministic sequence assignment
* protection against race-condition-induced ordering violations
* linearized per-session event streams

ensures event log integrity under multi-threaded execution.

---

### 10. replay readiness foundation (implicit but critical outcome)

Epic 1 established the foundational requirement for all higher systems:

> any state must be reconstructable from the event stream alone

achieved via:

* strict envelope model
* deterministic ordering guarantees
* immutable event storage
* idempotent append semantics

this directly enables Epic 2 projection and replay system.

---

# final architecture after Epic 1

```text id="e3"
EventStore (append-only, ordered, idempotent)
    ↓
StoredEvent (metadata + sequence + payload)
    ↓
Polymorphic EventPayload system
    ↓
Serialization layer (kotlinx.serialization)
```

---

# major architectural outcomes

Epic 1 established:

* append-only event-sourced backbone
* strict identity + causality model
* polymorphic domain event system
* deterministic persistence contract
* replay-safe serialization layer
* cross-backend contract enforcement
* concurrency-safe event ordering

---

# what Epic 1 intentionally does NOT include

not implemented:

* projections / state reconstruction
* FSM / session lifecycle logic
* workflow execution engine
* transition system
* kernel orchestration
* runtime execution model

those are explicitly deferred to Epic 2+

---

# final state

Correx now has:

> a deterministic, append-only event backbone with strict identity, causality, and ordering guarantees, fully replay-ready and validated through cross-implementation contract tests, serving as the foundational truth layer for all higher-level system behavior.