Files

T

kami c77277af0b epic-12: after epic audit and init commit

2026-05-17 03:19:39 +04:00

6.1 KiB

Raw Blame History

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:

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:

StoredEvent → SessionReducer → SessionState

instead of:

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.

6.1 KiB Raw Blame History