# 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.