See also: Graph orchestration · YAML schema · Scripting DSL · ADR-016 · Back to the index
ADR-018 — Two graph engines, one topology validation and one budget vocabulary, and a YAML graph: block
Status: Accepted — implemented · Date: 2026-11-07
· Scope: Orkeon.Domain (Graph/StateGraph.cs, GraphRunner.cs, Configuration/GraphConfig.cs), Orkeon.Infrastructure (Crew/Strategies/GraphProcessStrategy.cs, Configuration/Yaml/), Orkeon.Scripting (Orchestration/JsStateGraph.cs, Bindings/StateGraphBinding.cs, Typings/graph.d.ts). This ADR fixes semantics and ships no code; the work that implements it is FWK-27 (validation, implicit graph, JsStateGraph) and FWK-28 (the YAML block, export).
Context
Two graph loops exist.
- The Domain engine (
StateGraph<TState>compiled into aGraphRunner<TState>) has the sentinels__start__and__end__, fixed and conditional edges, and cycles bounded by aCircuitBreakerPolicy:MaxTransitions(a node runs only while the count of nodes already run is under it),MaxStateVisits(checked per node, a trip when its visits exceed it) andMaxTotalDuration.AddEdgeandAddConditionalEdgerefuse a second outgoing edge from a node.Compile()checks three things only: START has an edge, every node has an outgoing edge, and the target of a fixed edge exists. It does not detect a node that nothing reaches or a graph with no path to END, and a conditional edge is checked at run time against its declared targets. JsStateGraphruns its own loop in JavaScript (a trampoline) over an arbitraryJsValuestate, with the sentinels__START__and__END__. Its edge map is keyed by source node, so one edge per node holds by construction.stateGraph(...)rejects a literal with no START edge, a string edge to an undeclared node, and a graph with no static path from START to END (a function edge is assumed to reach END). Its budgets aremaxTransitions,maxStateVisitsandmaxRetryCycles: the last one counts, over the whole run, the entries into a node already entered once, not the visits of one node.- The Graph process does not use the engine's shape.
GraphProcessStrategy.BuildCrewGraphbuildsexecute_task→route→ (execute_taskor END): one node that loops over a queue of tasks. A crew's YAML has nograph:block, onlygraphConfig:(maxRetryCycles,circuitBreakerPreset,maxTransitions,maxStateVisits,maxTotalDurationSeconds), and itsmaxRetryCyclesis a retry of a failed task, not a bound on cycles. - A single engine is not possible. SCR-25 T1 removed the CLR loop that awaited JavaScript functions: Jint has one drainer, and a CLR loop blocked after the first
awaituntil its 10 s timeout. The JavaScript loop must stay in JavaScript.
Decision
Two loops stay. The Domain engine and the JavaScript loop are not merged. They share one topology validation (
GraphTopologyValidator, inOrkeon.Domain, FWK-27), one vocabulary (point 2) and one budget meaning (point 4).Vocabulary. A graph has nodes (an id and a body), a start node, edges (
from,to) and the exitEND. The Domain's and the script's sentinel strings differ (__start__/__end__,__START__/__END__) and stay as they are; they are not a surface of the YAML, where the start node is named bystart:and the exit is the reserved wordEND.STARTandENDare refused as node ids.The validator takes a neutral description (node ids, start, edges as
fromto targets, each flagged fixed or conditional) and returns every fault, not the first. It checks:- a node id is unique, not empty and not
START/END; startnames a node;- an edge starts at a declared node and ends at a declared node or
END(an unknown id is named, with the ids that exist); - a node has an outgoing edge: nothing may be left hanging at run time;
- a node that START cannot reach by following every edge is an orphan;
- END is reachable from START, and every node reachable from START can reach END (a conditional edge counts for all its declared targets; a script's function edge, whose targets are unknown, is assumed to reach END, as
stateGraphdoes today; a Domain conditional edge declared withoutpossibleTargetsis treated the same way). The textshas no path from START to ENDandghostnode faults of the present engines are kept, so their tests hold; - a node has at most one fixed outgoing edge, and a fixed edge excludes any other from the same node. Edges on one node that carry conditions are one conditional edge (point 6).
The Domain engine calls it from
Compile()(its three present checks are part of this list), the YAML mapper calls it at load,JsStateGraphcalls it at construction (it replacesValidateEdgeTargetsandValidateReachability), and the export calls it before writing. A fault surfaces as the exception of the caller's layer (InvalidOperationExceptionfor the Domain, the load error ofCrewDefinitionValidatorfor the YAML,InvalidScriptExceptionfor a script) with the same text.- a node id is unique, not empty and not
Budgets: those of the Domain.
maxTransitionsandmaxVisits(the Domain'sMaxStateVisits) are the two bounds;maxTotalDurationSecondsandcircuitBreakerPresetstay. The two engines count alike: a run executes at mostmaxTransitionsnodes, and a node entered more thanmaxVisitstimes trips the breaker. In a script,maxStateVisitsis already that budget.maxRetryCyclesis documented as the script's run-wide count of revisits: it equalsmaxVisits - 1for a graph that loops on one node and is a different, global bound for several. It stays ingraph.d.ts, unchanged, and a parity test pins the one-node case on both engines. The defaults differ today and stay distinct:StateGraphalone takes the Strict policy (50 transitions, 5 visits), a bareCircuitBreakerPolicyis 100 and 10, a script is 200 transitions with no visit bound unless a preset is named. For a crew, the defaults ofgraph.maxVisitsandgraph.maxTransitionskeep the rule ofGraphProcessStrategy.ResolvePolicy, sized from the crew: visits = the sum over the nodes of 1 + the retries (attempts - 1) of the node's task, that is nodes × (1 + retry attempts) when the tasks retry alike, transitions = 2 × visits + 1; an explicit value wins. A crew of more than 49 tasks is therefore not capped by the Strict figures. FWK-27 documents each script default as it is.The YAML
graph:block. Withprocess: graph:process: graph graph: start: triage # optional: default the first node nodes: # optional: absent = the implicit graph (point 7) - { id: triage, task: triage } - { id: fix, task: fix } - { id: escalate, task: escalate } edges: - { from: triage, to: fix, when: { triage.category: [bug] } } - { from: triage, to: escalate } # no `when`: the "otherwise" - { from: fix, to: END } - { from: escalate, to: END } maxTransitions: 50 maxVisits: 5 circuitBreakerPreset: strict maxTotalDurationSeconds: 600graph:replaces the YAMLgraphConfig:(removed,[breaking]: its budget keys move intograph:,maxStateVisitsbecomingmaxVisits,maxRetryCyclesdisappearing). ThegraphConfigkey of the script'sstateGraph({...})literal stays. Agraph:outsideprocess: graphis refused at load, not read and ignored. A node is{id, task}:tasknames a task of the crew. A task is named by at most one node, and whennodesis given a task named by no node is refused at load. A node is revisited by an edge leading back to it; on a revisit the latest output and the latest decision outcome win, the run's state and snapshots being keyed by task id. A failed node stops the run: there is no routing on failure (a retry is the task'sretry:). NomaxCycleskey exists: a bound on cycles ismaxVisits, and a retry of a task is the task'sretry:(FWK-15).Edges. Several
edgesfrom onefrombecome oneAddConditionalEdge, evaluated in the order declared; the first edge whosewhenholds wins. Afromthat carrieswhenedges is a decision task (ADR-016) and has exactly one edge withoutwhen, the "otherwise", taken when nowhenholds, which is also the case when the decision task was defaulted. An ordinary task has exactly one edge. Thewhenof an edge uses the grammar of the task-levelwhen, keeping its<task>.prefix:<task>.<question>: [option, ...],<task>.<question>: ">= 0.7",<task>.<question>.<option>: ">= 0.25". The task must be thefromtask, and the questions are checked at load against the ones it declares;otherwiseis not written, an edge withoutwhenis it. These are refused at load, each with a message naming the node: awhenon an edge whosefromis not a decision task, a decisionfromwith no edge withoutwhen, two edges withoutwhenfrom one node, an ordinary task with several edges, and a task-levelwhen:ordependencies:in a crew that has nodes (the edges order the tasks, a second router would contradict them).The implicit graph. Without a
graph:block, or with agraph:that holds only budgets,BuildCrewGraphbuilds one node per task, its id the task name, chained in the order the crew executes its tasks today, the last one leading to END. The queue-and-route loop ofexecute_taskgoes; a retry of a failed task is the task'sretry:. The task-levelwhenof ADR-016 keeps its skip semantics in the implicit graph only.edgeswithoutnodesmeans that same implicit node per task, with the edges between them.Which engine runs what. The Domain engine runs every crew in the Graph process, with a
graph:block or without.JsStateGraphrunsstateGraph(...)in a.ork.tsscript, over the script's state. A script cannot hand a graph to the Domain engine and a crew cannot run onJsStateGraph: the two meet at the validator, the vocabulary and the budgets.Run state and display. The current node and the visit counts of the Graph process are part of the checkpoint (FWK-07), so a resumed run re-enters the node it stopped at; the serialization is fixed by FWK-07 and used by FWK-28. A node entered emits a
graph.node.enteredevent from both engines (fieldnode, plustaskandvisitfor the Domain engine); a client can draw the graph read-only from these events. The YAML export writes thegraph:block back, so that import, export and import give the same graph.Out of this ADR: handoff. An agent handing a task to another agent by name is not a graph edge; it is neither specified nor refused here.
Consequences
- A crew can describe a loop (a reviewer sending work back to a writer) and a branch on a decision, with the engine's budgets as the only bound, and an invalid topology fails at load, not in the middle of a run.
- Two engines keep being maintained; what they have in common is tested, not assumed: the validator is the single code path for topology faults and a parity test pins the budgets.
graphConfig:and the crew-levelmaxRetryCyclesdisappear: a crew that wrote them is refused at load and moves its keys ([breaking], FWK-15 and FWK-28). FWK-28 migrates the example09-experimental/102-graph-orchestration(config and README) and the testsCrewFactoryGraphConfigTests,RemovedCircuitBreakerYamlTestsandUnknownCrewYamlKeysTests.- A crew in the Graph process with no
graph:block runs one node per task, so its trace and events name the tasks, notexecute_task.
Alternatives considered
- One engine, the Domain's, running scripts: rejected. It recreates the CLR loop that awaited JavaScript functions, which SCR-25 T1 removed because Jint has a single drainer.
- One engine, the script's, running crews: rejected. A crew's state is typed and its tasks are awaited CLR calls; every task would sit behind a trampoline.
- A
maxCycleskey: rejected. It would be read as a retry bound next to the task'sretry:;maxVisitsbounds cycles andretry:bounds attempts. - A
maxRetryCycleskept ingraph:: rejected for the same confusion, and because it is a run-wide count, not a per-node bound. - Edges evaluated as a script or an expression: rejected. A
whenreads the answers of a decision task, as in ADR-016, and nothing else.