Voir aussi : Orchestration en graphe · Schéma YAML · DSL de scripting · ADR-016 · Retour à l'index
ADR-018 — Deux moteurs de graphe, une validation de topologie et un vocabulaire de budgets partagés, et un bloc YAML graph:
Statut : Accepté — mis en œuvre · Date : 2026-11-07
· Périmètre : 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). Cet ADR fixe la sémantique et ne livre aucun code ; le travail qui l'applique est FWK-27 (validation, graphe implicite, JsStateGraph) et FWK-28 (le bloc YAML, l'export).
Contexte
Deux boucles de graphe existent.
- Le moteur du Domain (
StateGraph<TState>compilé enGraphRunner<TState>) a les sentinelles__start__et__end__, des arêtes fixes et conditionnelles, et des cycles bornés par uneCircuitBreakerPolicy:MaxTransitions(un nœud ne s'exécute que tant que le nombre de nœuds déjà exécutés est inférieur),MaxStateVisits(contrôlé par nœud, déclenchement quand ses visites dépassent la borne) etMaxTotalDuration.AddEdgeetAddConditionalEdgerefusent une seconde arête sortante depuis un nœud.Compile()ne vérifie que trois choses : START a une arête, chaque nœud a une arête sortante, la cible d'une arête fixe existe. Il ne détecte ni un nœud que rien n'atteint, ni un graphe sans chemin vers END, et une arête conditionnelle est contrôlée à l'exécution contre ses cibles déclarées. JsStateGraphtient sa propre boucle en JavaScript (un trampoline) sur un étatJsValuequelconque, avec les sentinelles__START__et__END__. Sa table d'arêtes est indexée par nœud source : une arête par nœud, par construction.stateGraph(...)rejette un littéral sans arête depuis START, une arête chaîne vers un nœud non déclaré, et un graphe sans chemin statique de START à END (une arête fonction est supposée atteindre END). Ses budgets sontmaxTransitions,maxStateVisitsetmaxRetryCycles: ce dernier compte, sur tout le run, les entrées dans un nœud déjà entré une fois, pas les visites d'un nœud.- Le process Graph n'utilise pas la forme du moteur.
GraphProcessStrategy.BuildCrewGraphconstruitexecute_task→route→ (execute_taskou END) : un seul nœud qui boucle sur une file de tâches. Le YAML d'une équipe n'a pas de blocgraph:, seulementgraphConfig:(maxRetryCycles,circuitBreakerPreset,maxTransitions,maxStateVisits,maxTotalDurationSeconds), et sonmaxRetryCyclesest un retry de tâche échouée, pas une borne de cycles. - Un moteur unique est impossible. SCR-25 T1 a retiré la boucle CLR qui attendait des fonctions JavaScript : Jint n'a qu'un seul drainer, et une boucle CLR se bloquait après le premier
awaitjusqu'à son délai de 10 s. La boucle JavaScript doit rester en JavaScript.
Décision
Deux boucles restent. Le moteur du Domain et la boucle JavaScript ne sont pas fusionnés. Ils partagent une validation de topologie (
GraphTopologyValidator, dansOrkeon.Domain, FWK-27), un vocabulaire (point 2) et un sens des budgets (point 4).Vocabulaire. Un graphe a des nœuds (un id et un corps), un nœud de départ, des arêtes (
from,to) et la sortieEND. Les chaînes sentinelles du Domain et du script diffèrent (__start__/__end__,__START__/__END__) et restent telles quelles ; elles ne sont pas une surface du YAML, où le nœud de départ se nomme parstart:et la sortie est le mot réservéEND.STARTetENDsont refusés comme id de nœud.Le validateur prend une description neutre (ids de nœuds, départ, arêtes
fromvers cibles, chacune marquée fixe ou conditionnelle) et rend toutes les fautes, pas la première. Il vérifie :- un id de nœud est unique, non vide et différent de
START/END; startnomme un nœud ;- une arête part d'un nœud déclaré et arrive à un nœud déclaré ou à
END(un id inconnu est nommé, avec les ids qui existent) ; - un nœud a une arête sortante : rien ne doit pendre à l'exécution ;
- un nœud que START n'atteint pas en suivant toutes les arêtes est orphelin ;
- END est atteignable depuis START, et tout nœud atteignable depuis START peut atteindre END (une arête conditionnelle compte pour toutes ses cibles déclarées ; l'arête fonction d'un script, dont les cibles sont inconnues, est supposée atteindre END, comme
stateGraphle fait aujourd'hui ; une arête conditionnelle du Domain déclarée sanspossibleTargetsest traitée de même). Les texteshas no path from START to ENDet les fautes de nœudghostdes moteurs actuels sont conservés, de sorte que leurs tests tiennent ; - un nœud a au plus une arête sortante fixe, et une arête fixe exclut toute autre depuis le même nœud. Les arêtes d'un nœud qui portent des conditions forment une seule arête conditionnelle (point 6).
Le moteur du Domain l'appelle depuis
Compile()(ses trois contrôles actuels font partie de cette liste), le mapper YAML l'appelle au chargement,JsStateGraphl'appelle à la construction (il remplaceValidateEdgeTargetsetValidateReachability), et l'export l'appelle avant d'écrire. Une faute remonte comme l'exception de la couche appelante (InvalidOperationExceptionpour le Domain, l'erreur de chargement deCrewDefinitionValidatorpour le YAML,InvalidScriptExceptionpour un script) avec le même texte.- un id de nœud est unique, non vide et différent de
Budgets : ceux du Domain.
maxTransitionsetmaxVisits(leMaxStateVisitsdu Domain) sont les deux bornes ;maxTotalDurationSecondsetcircuitBreakerPresetrestent. Les deux moteurs comptent de la même façon : un run exécute au plusmaxTransitionsnœuds, et un nœud entré plus demaxVisitsfois déclenche le disjoncteur. Dans un script,maxStateVisitsest déjà ce budget.maxRetryCyclesest documenté comme le compte, sur tout le run, des revisites du script : il vautmaxVisits - 1pour un graphe qui boucle sur un seul nœud et c'est une borne globale différente pour plusieurs. Il reste dansgraph.d.ts, inchangé, et un test de parité fixe le cas d'un nœud sur les deux moteurs. Les défauts diffèrent aujourd'hui et restent distincts :StateGraphseul prend la politique Strict (50 transitions, 5 visites), uneCircuitBreakerPolicynue vaut 100 et 10, un script 200 transitions sans borne de visites sans préréglage nommé. Pour une équipe, les défauts degraph.maxVisitsetgraph.maxTransitionsgardent la règle deGraphProcessStrategy.ResolvePolicy, dimensionnés sur l'équipe : visites = la somme sur les nœuds de 1 + les retries (attempts - 1) de la tâche du nœud, soit nœuds × (1 + tentatives de retry) quand les tâches réessaient pareil, transitions = 2 × visites + 1 ; une valeur explicite l'emporte. Une équipe de plus de 49 tâches n'est donc pas plafonnée par les chiffres de Strict. FWK-27 documente chaque défaut du script tel qu'il est.Le bloc YAML
graph:. Avecprocess: graph:process: graph graph: start: triage # optionnel : par défaut le premier nœud nodes: # optionnel : absent = le graphe implicite (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 } # sans `when` : le « sinon » - { from: fix, to: END } - { from: escalate, to: END } maxTransitions: 50 maxVisits: 5 circuitBreakerPreset: strict maxTotalDurationSeconds: 600graph:remplace legraphConfig:YAML (retiré,[breaking]: ses clés de budget passent dansgraph:,maxStateVisitsdevenantmaxVisits,maxRetryCyclesdisparaissant). La clégraphConfigdu littéralstateGraph({...})d'un script reste. Ungraph:horsprocess: graphest refusé au chargement, pas lu puis ignoré. Un nœud est{id, task}:tasknomme une tâche de l'équipe. Une tâche est nommée par un seul nœud au plus, et quandnodesest donné une tâche nommée par aucun nœud est refusée au chargement. Un nœud est revisité par une arête qui y revient ; à la revisite, la dernière sortie et le dernier résultat de décision l'emportent, l'état du run et les instantanés étant indexés par id de tâche. Un nœud en échec arrête le run : pas d'aiguillage sur échec (un retry est leretry:de la tâche). Aucune clémaxCyclesn'existe : une borne de cycles estmaxVisits, et un retry de tâche est leretry:de la tâche (FWK-15).Arêtes. Plusieurs
edgesdepuis un mêmefromdeviennent une seuleAddConditionalEdge, évaluée dans l'ordre de déclaration ; la première arête dont lewhentient l'emporte. Unfromqui porte des arêteswhenest une tâche de décision (ADR-016) et a exactement une arête sanswhen, le « sinon », prise quand aucunwhenne tient, ce qui est aussi le cas quand la tâche de décision a pris sa réponse par défaut. Une tâche ordinaire a exactement une arête. Lewhend'une arête suit la grammaire duwhende tâche, avec son préfixe<task>.:<task>.<question>: [option, ...],<task>.<question>: ">= 0.7",<task>.<question>.<option>: ">= 0.25". La tâche doit être la tâchefrom, et les questions sont vérifiées au chargement contre celles qu'elle déclare ;otherwisene s'écrit pas, une arête sanswhenl'est. Sont refusés au chargement, chacun avec un message qui nomme le nœud : unwhensur une arête dont lefromn'est pas une tâche de décision, unfromde décision sans arête sanswhen, deux arêtes sanswhendepuis un nœud, une tâche ordinaire à plusieurs arêtes, et unwhen:ou desdependencies:de tâche dans une équipe qui a des nœuds (les arêtes ordonnent les tâches, un second aiguilleur les contredirait).Le graphe implicite. Sans bloc
graph:, ou avec ungraph:qui ne porte que des budgets,BuildCrewGraphconstruit un nœud par tâche, son id étant le nom de la tâche, enchaînés dans l'ordre où l'équipe exécute ses tâches aujourd'hui, le dernier menant à END. La boucle file-et-aiguillage d'execute_taskdisparaît ; le retry d'une tâche échouée est leretry:de la tâche. Lewhende tâche de l'ADR-016 garde sa sémantique d'omission dans le graphe implicite seulement.edgessansnodesveut dire ce même nœud implicite par tâche, avec les arêtes entre eux.Quel moteur exécute quoi. Le moteur du Domain exécute toute équipe du process Graph, avec ou sans bloc
graph:.JsStateGraphexécutestateGraph(...)dans un script.ork.ts, sur l'état du script. Un script ne peut pas confier un graphe au moteur du Domain et une équipe ne peut pas tourner surJsStateGraph: les deux se rejoignent au validateur, au vocabulaire et aux budgets.État du run et affichage. Le nœud courant et les compteurs de visites du process Graph font partie du checkpoint (FWK-07), de sorte qu'un run repris rentre dans le nœud où il s'était arrêté ; la sérialisation est fixée par FWK-07 et utilisée par FWK-28. Un nœud entré émet un événement
graph.node.entereddepuis les deux moteurs (champnode, plustasketvisitpour le moteur du Domain) ; un client peut dessiner le graphe en lecture seule depuis ces événements. L'export YAML réécrit le blocgraph:, de sorte qu'import, export, import donnent le même graphe.Hors de cet ADR : le handoff. Un agent qui passe une tâche à un autre agent par son nom n'est pas une arête de graphe ; il n'est ici ni spécifié ni refusé.
Conséquences
- Une équipe peut décrire une boucle (un relecteur qui renvoie le travail à un rédacteur) et un embranchement sur une décision, les budgets du moteur étant la seule borne, et une topologie invalide échoue au chargement, pas au milieu d'un run.
- Deux moteurs restent à maintenir ; ce qu'ils ont en commun est testé, pas supposé : le validateur est l'unique chemin de code des fautes de topologie et un test de parité fixe les budgets.
graphConfig:et lemaxRetryCyclesau niveau de l'équipe disparaissent : une équipe qui les écrit est refusée au chargement et déplace ses clés ([breaking], FWK-15 et FWK-28). FWK-28 migre l'exemple09-experimental/102-graph-orchestration(config et README) et les testsCrewFactoryGraphConfigTests,RemovedCircuitBreakerYamlTestsetUnknownCrewYamlKeysTests.- Une équipe du process Graph sans bloc
graph:exécute un nœud par tâche : sa trace et ses événements nomment les tâches, pasexecute_task.
Alternatives écartées
- Un moteur unique, celui du Domain, qui exécute les scripts : écarté. Il recrée la boucle CLR qui attendait des fonctions JavaScript, que SCR-25 T1 a retirée parce que Jint n'a qu'un seul drainer.
- Un moteur unique, celui du script, qui exécute les équipes : écarté. L'état d'une équipe est typé et ses tâches sont des appels CLR attendus ; chaque tâche passerait derrière un trampoline.
- Une clé
maxCycles: écarté. Elle se lirait comme une borne de retry à côté duretry:de la tâche ;maxVisitsborne les cycles etretry:borne les tentatives. - Un
maxRetryCyclesconservé dansgraph:: écarté pour la même confusion, et parce que c'est un compte sur tout le run, pas une borne par nœud. - Des arêtes évaluées comme un script ou une expression : écarté. Un
whenlit les réponses d'une tâche de décision, comme dans l'ADR-016, et rien d'autre.