# Epic 3: Transition Engine (Deterministic Workflow Graph + Event-Driven Execution)

**status:** proposed
**date:** 09.05.2026 (May)
**scope:** `:core:transitions` (depends on `:core:events`, `:core:sessions`)

---

## context

With deterministic replay and session projection already implemented (Epic 2 complete), Correx now needs a workflow execution model capable of describing and evaluating structured agent pipelines.

A session lifecycle alone is insufficient for orchestration semantics.

The system now requires:

* workflow topology
* transition rules
* deterministic execution flow
* replay-safe workflow progression

Without a transition engine:

* sessions cannot evolve through structured workflows
* stage progression remains implicit
* orchestration semantics cannot be reconstructed from history

---

## goal

Introduce a **deterministic workflow transition engine**:

> a pure graph evaluation system that resolves workflow transitions and emits replay-safe execution events

The transition engine must remain:

* deterministic
* stateless
* replay-safe
* runtime-agnostic

It is NOT a scheduler or orchestration kernel.

---

## scope (what IS included)

### 1. workflow graph model

Define immutable workflow topology structures:

* `WorkflowGraph`
* `TransitionEdge`
* `StageId`
* `TransitionId`

Graph structure:

```kotlin
data class WorkflowGraph(
    val stages: Set<StageId>,
    val transitions: Set<TransitionEdge>,
    val start: StageId
)
```

Properties:

* immutable
* deterministic
* runtime-independent
* replay-safe

---

### 2. deterministic transition evaluation

Implement deterministic transition resolution.

Core concepts:

* `TransitionCondition`
* `EvaluationContext`
* `TransitionConditionEvaluator`
* `TransitionDecision`
* `DefaultTransitionResolver`

Rules:

* evaluate only outgoing transitions from current stage
* deterministic ordering only
* sequential evaluation only
* first matching transition wins
* no implicit randomness or parallelism

Transition evaluation must behave identically under replay.

---

### 3. graph analysis and cycle detection

Implement read-only graph validation and analysis.

Includes:

* deterministic adjacency construction
* DFS-based traversal
* cycle extraction
* cycle canonicalization
* duplicate cycle elimination
* unreachable node detection

Important:

* cycles are structurally allowed
* cycle analysis is informational in Epic 3
* runtime loop policies are NOT part of this epic

Cycle handling remains deterministic and replay-safe.

---

### 4. stage execution contract

Define strict execution boundary between transition evaluation and runtime execution.

Introduce:

* stage execution request model
* stage execution result model
* deterministic execution semantics

Important:

* transition engine does NOT execute runtime logic
* transition engine does NOT schedule work
* transition engine does NOT manage concurrency

It only evaluates graph progression.

---

### 5. transition execution events

Introduce workflow execution events into the event system.

Implemented events:

* `StageStartedEvent`
* `StageCompletedEvent`
* `StageFailedEvent`
* `TransitionExecutedEvent`

Properties:

* append-only compatible
* serializable
* replay-safe
* deterministic

Workflow progression becomes part of durable event history.

---

### 6. event-native session integration

Integrate workflow execution into session state reconstruction.

Introduce:

* `SessionReducer`
* `DefaultSessionReducer`

Session state now evolves via deterministic event reduction:

```text
StoredEvent → SessionReducer → SessionState
```

instead of:

```text
StoredEvent → Mapper → FSM → State
```

Rules:

* transition engine never mutates session state directly
* events are the single source of truth
* projections derive state from full semantic event stream
* no lossy event collapsing is allowed

---

### 7. replay-safe projection architecture

Align projections with true event-sourcing semantics.

Projection rules:

* projections are pure deterministic folds
* no side effects
* no runtime clocks
* no mutable hidden state
* replay must reconstruct identical state from identical streams

Transition execution history becomes replayable system truth.

---

### 8. deterministic testing coverage

Implement coverage for:

* transition resolution determinism
* graph analysis correctness
* cycle extraction stability
* transition event serialization
* replay determinism
* reducer semantics
* session reconstruction from workflow events

End-to-end replay consistency is a required invariant.

---

## explicit exclusions

Epic 3 does NOT include:

* scheduling
* runtime orchestration kernel
* retry policies
* runtime loop enforcement
* approval gating
* tool execution policies
* adaptive routing logic
* budget enforcement
* concurrency control
* distributed execution

Those belong to future orchestration/runtime layers.

---

## consequences

### positive

* introduces deterministic workflow semantics
* makes workflow progression replayable
* formalizes orchestration topology
* separates workflow evaluation from runtime execution
* enables future policy/runtime layers
* preserves strict event-sourcing guarantees

---

### negative

* introduces graph complexity into core architecture
* deterministic guarantees constrain future runtime flexibility
* workflow semantics now depend heavily on projection correctness
* cycle handling will require future runtime policy enforcement
* event semantics become significantly richer and more difficult to evolve

---

## rationale

Sessions alone describe lifecycle state, but not workflow progression.

A transition engine is required to:

> translate workflow topology into deterministic event-driven execution semantics

This moves Correx from:

* “stateful session replay”
  to
* “deterministic workflow execution replay”

Workflow behavior now becomes reconstructible from history.

---

## status

Epic 3 becomes valid only after:

* Epic 1 is complete ✔
* Epic 2 is complete ✔
* replay determinism is verified ✔
* session projection infrastructure exists ✔

It is the first orchestration-oriented layer in Correx and establishes the deterministic execution substrate required for future runtime and policy systems.