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

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:

StoredEvent → SessionReducer → SessionState

instead of:

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:

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

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.