epic-12: after epic audit and init commit

2026-05-16 11:42:00 +04:00
commit c77277af0b
461 changed files with 28958 additions and 0 deletions
@@ -0,0 +1,200 @@
+# 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.