Runtime#
The runtime receives a compiled plan and state, then advances execution to an observable state boundary. The compiler that builds a plan and the runtime that advances it have separate responsibilities.
ExecutionRuntime’s role#
ExecutionRuntime connects an ExecutablePlan to an execution position and state, and orders StatePatch values, events, and waits.
Contract compatibility and service resolution belong to the Compiler; the Runtime does not repair an unverified Graph.
RuntimeSession owns the current state and execution position, while StateStore owns persistent values.
ExecutablePlan and ExecutionRuntime#
ExecutablePlan is a verified representation of a ComponentGraph that carries required runtime capabilities and diagnostics.
ExecutionRuntime is the protocol for initializing a plan, advancing state by one step, and handling requests such as completion or recompilation.
The runtime applies StatePatch values, events, and commands from node results in order.
RuntimeSession and RuntimeStep#
RuntimeSession is a resumable session containing the plan, current state, execution position, and completion status.
RuntimeStep is the result of one advance operation and returns the next session, state, and observability.
This separation lets checkpoints and asynchronous-evaluation waits use the same execution model.
Only a boundary where StatePatches have been applied, events delivered, and commands processed is exposed as the next step.
Value |
Information held |
|---|---|
|
|
|
Updated state, executed nodes, |
ExecutionRuntime.initialize(plan, state) creates a session, and advance(session) returns one RuntimeStep.
Applications use the step’s finished, observable, and session fields to choose the next operation or resume position.
PipelineRuntime and asynchronous waiting#
PipelineRuntime executes an ordinary pipeline in order, while AsyncPipelineRuntime handles wait states for submitting and collecting asynchronous evaluations.
Because a submitted asynchronous request may not complete immediately, the runtime retains its state and returns to the next poll.
When evaluation completes, it applies the resulting update as a patch before resuming later stages.
RuntimeSession retains this wait position, and RuntimeStep reports whether progress occurred and returns the next session.
AsyncEvaluator and the scheduler implement asynchronous evaluation; AsyncPipelineRuntime connects them to the plan’s execution boundary.
Runner#
Runner obtains a plan and initial state from Optimizer, iterates the runtime, and exposes only state boundaries as a thin internal implementation.
Treat it as an internal component for driving the execution runtime, not as a stable configuration API for applications.
For ordinary use, call minimize(), maximize(), Optimizer.run(), or Optimizer.iterate().
Construction time and use time#
ExecutionRuntime.initialize(plan, state) creates a session, and advance(session) returns one RuntimeStep.
RuntimeSession is an immutable execution snapshot; the Runtime makes the resume position explicit by returning the next session.
Invariants and diagnostics#
The Runtime verifies that the environment provides the capabilities required by the plan, that NodeResult StatePatches stay within declared state effects, and that a waiting request is not applied twice.
Plan diagnostics, undeclared state writes, invalid execution positions, and uncollectable asynchronous requests stop execution and are reported as Diagnostics or failure results.
Missing runtime capabilities become the Compiler diagnostic missing_runtime_capability.
Extension points#
When adding an execution capability or wait state, define the execution contract in ComponentContract together with the RuntimeSession transition.
When integrating an existing Stage, connect its OptimizationState boundary through an adapter and keep it distinct from a graph-native Component’s StateView boundary.