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,256 @@
+# Epic 3 — Transition Engine
+
+## completed deliverables
+
+### 1. workflow graph model
+
+implemented deterministic workflow topology representation.
+
+core structures:
+
+* `WorkflowGraph`
+* `TransitionEdge`
+* `StageId`
+* `TransitionId`
+* `TransitionCondition`
+* `EvaluationContext`
+
+graph characteristics:
+
+* immutable
+* deterministic
+* replay-safe
+* runtime-agnostic
+
+---
+
+## 2. deterministic transition resolution
+
+implemented pure transition evaluation engine.
+
+properties:
+
+* evaluates only outgoing edges from current stage
+* deterministic ordering
+* sequential evaluation only
+* first matching transition wins
+* stable replay behavior
+
+core components:
+
+* `DefaultTransitionResolver`
+* `TransitionConditionEvaluator`
+* `TransitionDecision`
+
+---
+
+## 3. cycle analysis infrastructure
+
+implemented read-only graph cycle analysis.
+
+implemented:
+
+* deterministic adjacency construction
+* DFS-based traversal
+* cycle extraction
+* cycle canonicalization
+* duplicate elimination
+
+important:
+
+* analysis only
+* no runtime execution semantics yet
+* no scheduler/orchestrator coupling
+
+architectural rule:
+
+* cycles are structurally allowed
+* behavior constraints belong to future policy/runtime layers
+
+---
+
+## 4. stage execution contract
+
+defined strict execution boundary between:
+
+* transition engine
+* runtime execution
+
+implemented concepts:
+
+* stage execution request
+* stage execution result
+* deterministic execution semantics
+* execution/event separation
+
+important:
+
+* transitions engine does NOT execute runtime logic
+* transitions engine does NOT orchestrate scheduling
+
+---
+
+## 5. transition event model
+
+added workflow execution events into event system.
+
+implemented events:
+
+* `StageStartedEvent`
+* `StageCompletedEvent`
+* `StageFailedEvent`
+* `TransitionExecutedEvent`
+
+properties:
+
+* serializable
+* append-only compatible
+* replay-safe
+* session-scoped
+
+---
+
+## 6. event-native session integration
+
+reworked session architecture from:
+
+* FSM + lossy mapping
+
+into:
+
+* deterministic event reduction
+
+removed conceptual dependency on:
+
+* collapsed transition semantics
+* imperative FSM mutation
+
+introduced:
+
+* `SessionReducer`
+* `DefaultSessionReducer`
+
+session state now evolves via:
+
+```text id="e1"
+StoredEvent → SessionReducer → SessionState
+```
+
+instead of:
+
+```text id="e2"
+StoredEvent → Mapper → FSM → State
+```
+
+---
+
+## 7. projection architecture alignment
+
+aligned sessions with true event-sourcing semantics.
+
+final rules:
+
+* event stream is single source of truth
+* projections are pure deterministic folds
+* no hidden mutable state
+* no runtime side effects
+* replay reconstructs full state deterministically
+
+---
+
+## 8. replay integration
+
+integrated transition execution into replay pipeline.
+
+final replay flow:
+
+```text id="e3"
+Workflow execution
+→ transition events
+→ EventStore
+→ replay
+→ SessionProjector
+→ SessionState
+```
+
+transition execution now becomes part of durable system history.
+
+---
+
+## 9. testing completed
+
+implemented coverage for:
+
+* reducer semantics
+* deterministic replay
+* projector lifecycle behavior
+* transition resolution
+* transition event serialization
+* replay integration
+
+removed obsolete tests:
+
+* `SessionFsm`
+* `SessionEventMapper`
+* mapper-driven FSM semantics
+
+---
+
+# final architecture after Epic 3
+
+```text id="e4"
+WorkflowGraph
+    ↓
+TransitionResolver
+    ↓
+Stage Execution
+    ↓
+Transition Events
+    ↓
+Event Store
+    ↓
+Replay / Projection
+    ↓
+SessionState
+```
+
+---
+
+# major architectural outcomes
+
+Epic 3 established:
+
+* deterministic workflow execution
+* replay-safe orchestration semantics
+* event-native state derivation
+* strict separation of:
+
+    * execution
+    * transitions
+    * persistence
+    * projections
+    * runtime orchestration
+
+---
+
+# what Epic 3 intentionally does NOT include
+
+not implemented yet:
+
+* retry policies
+* bounded runtime loop enforcement
+* approval gating
+* tool orchestration policies
+* scheduling
+* runtime budgeting
+* adaptive routing logic
+
+those belong to future epics.
+
+---
+
+# final state
+
+Correx now has:
+
+> a deterministic, event-sourced workflow transition engine with replay-consistent session projection and no hidden state mutation.