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

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:

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

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.