# Epic 1.5 — Store Invariants, Replay Contracts & Projection Enforcement Layer

## completed deliverables

### 1. event store invariants formalization

extended and hardened the EventStore correctness model beyond basic append/read semantics.

formalized invariants:

* append-only enforcement as strict storage rule
* idempotency via `eventId` uniqueness
* monotonic per-session sequencing
* total ordering guarantee per session stream
* deterministic read consistency across implementations

this clarified EventStore as a **strict correctness boundary**, not just a persistence abstraction.

---

### 2. replay contract system (cross-store determinism)

introduced a unified contract layer for verifying replay correctness across all EventStore implementations.

contract guarantees:

* identical event streams MUST produce identical replay outputs
* ordering must be preserved independent of storage backend
* partial replay (cursor-based) must remain deterministic
* replay must be stateless and side-effect free

covered implementations:

* in-memory event store
* sqlite event store
* future persistence adapters

---

### 3. projection contract enforcement layer

defined formal constraints for projection systems to ensure deterministic state reconstruction.

projection invariants:

* projection MUST be a pure function: `EventStream → State`
* projections MUST NOT retain or mutate internal state
* projections MUST NOT depend on external systems
* identical inputs MUST produce identical outputs

introduced projection-level contract tests to enforce:

* determinism across repeated builds
* correct handling of empty streams
* correct ordering sensitivity
* stable state reconstruction semantics

---

### 4. test fixtures & reusable contract infrastructure

introduced shared testing primitives to enforce consistency across modules.

components:

* deterministic `stored()` / `event()` builders
* reusable EventStore contract test suite
* reusable replay contract test suite
* projection contract test base class

ensures:

> correctness rules are defined once and enforced everywhere

---

### 5. concurrency correctness validation layer

formalized and tested concurrency guarantees for EventStore implementations.

validated properties:

* safe concurrent appends
* absence of race-condition-based sequence corruption
* uniqueness enforcement under parallel writes
* deterministic final stream state under concurrent load

introduced stress-style test utilities for reproducible concurrency validation.

---

### 6. projection infrastructure alignment

aligned projection system with replay engine from Epic 2 while maintaining strict separation of concerns.

ensured:

* projections depend only on event stream abstraction
* projections remain implementation-agnostic
* replay engine is the only execution driver
* no direct store coupling inside projection logic

this created a clean boundary:

```text id="p1"
EventStore → EventReplayer → Projection → State
```

---

### 7. event system boundary tightening

refined event system usage rules across all layers:

* event payload remains the only domain extension point
* metadata is strictly non-semantic
* sequence is the only ordering primitive
* causality is informational only (not execution-driving)

ensured event system remains the **single authoritative truth layer** without semantic leakage.

---

### 8. architectural separation enforcement

formalized module separation rules:

* `core/events` → source of truth + replay primitives
* `core/events/projections` → deterministic state builders
* `infrastructure/persistence` → storage implementations only
* `testing/contracts` → cross-module correctness enforcement

enforced rule:

> no module may assume correctness of another without contract validation

---

### 9. replay correctness guarantee foundation

strengthened replay guarantees introduced in Epic 2:

* deterministic replay across time and environment
* backend-independent state reconstruction
* full reproducibility of session state from event stream
* elimination of hidden state assumptions in projection lifecycle

Epic 1.5 made replay correctness **explicitly testable and enforced**, not implicit.

---

# final architecture after Epic 1.5

```text id="epic15"
EventStore (contract-enforced)
    ↓
StoredEvent stream (ordered, idempotent)
    ↓
EventReplayer (deterministic engine)
    ↓
Projection contracts (pure functions)
    ↓
State (reconstructed, disposable)
```

---

# major architectural outcomes

Epic 1.5 established:

* formal correctness contracts for EventStore and replay systems
* deterministic projection enforcement layer
* reusable cross-module test contract infrastructure
* concurrency-safe event persistence validation
* strict replay determinism guarantees across implementations
* hardened separation between storage, replay, and projection layers

---

# what Epic 1.5 intentionally does NOT include

not implemented:

* session lifecycle FSM (Epic 2)
* transition engine execution semantics (Epic 3)
* workflow orchestration
* runtime kernel
* tool execution system
* policy/approval integration

those systems are explicitly higher-level and depend on this layer being stable.

---

# final state

Correx now has:

> a formally contract-enforced event sourcing foundation with deterministic replay, validated projection semantics, and strict cross-implementation guarantees ensuring that all state reconstruction logic is reproducible, testable, and backend-independent.