298 lines
6.1 KiB
Markdown
298 lines
6.1 KiB
Markdown
# 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.
|