250 lines
5.5 KiB
Markdown
250 lines
5.5 KiB
Markdown
# 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.
|