epic-12: after epic audit and init commit
This commit is contained in:
@@ -0,0 +1,297 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user