correx/docs/epics/epic-1-resolution.md

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:

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:

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

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.