Table of Contents

🇬🇧 English version

Voir aussi : Guide comparatif ProcessTypes · Schéma YAML · Retour à l'index

Moteur de machine à états finis (FSM)

Vue d'ensemble

Orkeon fournit un framework de machine à états finis générique (StateMachine<TState, TEvent>) dans la couche Domain, avec un circuit breaker intégré (CircuitBreakerPolicy) qui arrête une boucle emballée. C'est une brique pour votre propre code et pour trois consommateurs livrés :

  • orkeon forge dĂ©roule le cycle de sa session (brief → blueprint → rendu → validation → test → diagnostic → verdict) sur une StateMachine<ForgeState, ForgeTrigger> (ForgeStateMachineFactory).
  • Le mode Graph borne les runs de son StateGraph avec une CircuitBreakerPolicy construite depuis le bloc graph: de la crew.
  • Le graphe RAG correctif (CorrectiveRagPipeline) borne sa boucle rĂ©cupĂ©rer → Ă©valuer → rĂ©gĂ©nĂ©rer avec sa propre CircuitBreakerPolicy.

Pas de machine à états de tâche. Les tâches d'une crew ne passent par aucune FSM. Ce qui borne une tâche, c'est sa boucle d'agent : le maxIter de l'agent, un arrêt après 3 erreurs d'outil identiques consécutives, et les reprises de validation de sortie (un agent à deux itérations de son plafond en est prévenu une fois ; celui qui atteint maxIter reçoit un dernier tour sans outil, et sa tâche porte le drapeau endedOnIterationCap ; c'est la boucle d'agent principale, les boucles de repli native et textuelle héritée ne font ni l'un ni l'autre et finissent toujours sur le plafond). Un bloc YAML circuitBreaker:, à la racine de la crew ou sur une tâche, est refusé au chargement. En YAML, le seul réglage de circuit breaker est le bloc graph: d'une crew Graph (voir Schéma YAML).

Architecture

Les composants du framework se trouvent dans Orkeon.Domain.Common.StateMachine :

Classe RĂ´le
StateMachine<TState, TEvent> Moteur FSM thread-safe (lock) avec circuit breaker intégré
StateMachineBuilder<TState, TEvent> API fluent pour déclarer le graphe d'états
CircuitBreakerPolicy Configuration des seuils de protection, presets Strict / Default / Permissive
CircuitBreakerStatus Instantané du disjoncteur (même fichier que la policy)
TransitionResult<TState, TEvent> Résultat d'une transition (états, déclencheur, ordinal, horodatage)
IStateMachine<TState, TEvent> Interface lecture seule pour l'observation
IMutableStateMachine<TState, TEvent> Interface avec Fire(), TryFire(), ResetCircuitBreaker(), événements
CircuitBrokenException, InvalidTransitionException<TState, TEvent> Disjoncteur déclenché ; aucune transition pour cet état + événement

CircuitBreakerPolicyFactory (Orkeon.Infrastructure.Configuration) transforme le bloc graph: d'une crew Graph en policy (ResolveGraph).

Circuit breaker

Le circuit breaker est intégré directement dans StateMachine<TState, TEvent> et vérifie quatre conditions avant chaque transition :

Mécanismes de protection

Mécanisme Paramètre Description
Transitions max MaxTransitions Nombre total de transitions autorisées
Timeout par état StateTimeout Temps maximal depuis la dernière transition (TimeSpan.Zero le désactive)
Détection de cycles MaxStateVisits Nombre maximal de visites d'un même état (0 le désactive)
Durée totale MaxTotalDuration Durée de vie maximale depuis la première transition (TimeSpan.Zero la désactive)

Quand une condition est violée, deux comportements sont possibles selon UseDegradedMode :

  • false : une CircuitBrokenException est levĂ©e avec un CircuitBreakerStatus dĂ©taillĂ©
  • true : la machine passe dans l'Ă©tat dĂ©gradĂ© dĂ©clarĂ© avec WithDegradedState(...) ; sans Ă©tat dĂ©gradĂ© dĂ©clarĂ©, elle lève l'exception comme ci-dessus

TryFire() renvoie false au lieu de lever, pour un disjoncteur déclenché comme pour une transition absente. Un guard qui rejette toutes les transitions candidates se traduit par une InvalidTransitionException. ResetCircuitBreaker() efface le déclenchement et les compteurs.

Presets

Trois presets sont fournis via CircuitBreakerPolicy :

Preset MaxTransitions StateTimeout MaxStateVisits MaxTotalDuration DegradedMode
Strict 50 2 min 5 10 min true
Default 100 5 min 10 30 min false
Permissive 1000 30 min 50 2 h false

new CircuitBreakerPolicy() équivaut à Default. Strict est le repli de StateGraph et de CircuitBreakerPolicyFactory.ResolveGraph quand graph: ne nomme aucun preset (ou un preset inconnu).

Observabilité

La machine expose deux événements :

  • OnTransition : levĂ© après chaque transition rĂ©ussie, avec un TransitionResult (FromState, ToState, Trigger, TransitionOrdinal, Timestamp, StateChanged)
  • OnCircuitBroken : levĂ© quand le circuit se dĂ©clenche, avec un CircuitBreakerStatus incluant un histogramme des visites par Ă©tat

CircuitBreakerStatus fournit un instantané complet : IsBroken, BrokenReason, TotalTransitions, TimeInCurrentState, CurrentStateVisitCount, TotalElapsed, StateVisitHistogram. L'interface en lecture seule offre aussi CurrentState, IsTerminal, TransitionCount, GetPermittedEvents() et CanFire(event).

Guards typés

Une transition peut porter un guard sur un contexte typé — WithGuard<TContext>(prédicat, description) — et une action. Fire(event, context) évalue les guards des transitions candidates dans l'ordre de déclaration et retient la première qui passe ; quand tous les guards refusent, l'appel lève une InvalidTransitionException (TryFire renvoie false).

Utilisation en code C#

Construire une machine à états

Le framework permet de définir n'importe quel graphe d'états :

var fsm = new StateMachineBuilder<MyState, MyEvent>()
    .WithInitialState(MyState.Idle)
    .WithTerminalStates(MyState.Done, MyState.Error)
    .WithDegradedState(MyState.Error)
    .WithCircuitBreaker(new CircuitBreakerPolicy
    {
        MaxTransitions = 50,
        StateTimeout = TimeSpan.FromMinutes(2),
        MaxStateVisits = 5,
        UseDegradedMode = true
    })
    .When(MyState.Idle, MyEvent.Start)
        .TransitionTo(MyState.Processing)
        .WithGuard<MyContext>(ctx => ctx.IsReady, "Must be ready")
        .WithAction((from, to) => Log($"{from} -> {to}"))
        .Done()
    .When(MyState.Processing, MyEvent.Complete)
        .TransitionTo(MyState.Done)
        .Done()
    .Build();

AddTransition(from, trigger, to) est le raccourci pour une transition sans guard ni action ; WithStateKey / WithEventKey fournissent les fonctions de clé quand TState / TEvent ne sont pas des enums.

Le DSL de scripting a son propre littéral stateMachine() (fsm.d.ts), une implémentation JavaScript distincte sans circuit breaker — voir Scripting.

Relation avec l'existant

États de cycle de vie

Les états de cycle de vie des agents, des tâches et des crews (AgentStatus, TaskStatus, CrewStatus : Pending → InProgress → Completed…) sont gardés par les agrégats eux-mêmes — une tâche qui n'est pas Pending refuse de démarrer — et un run les fait avancer au fil de l'exécution (Événements). Ils n'utilisent pas ce moteur.

Stratégies de process

Les implémentations de IProcessStrategy exécutent une tâche via IAgentExecutionService et sa boucle d'agent ; aucune ne construit de machine à états. Le mode Graph est la seule stratégie qui applique une CircuitBreakerPolicy, au runner de son StateGraph.

Tests

Fichier de test Couverture
Orkeon.Domain.Tests/Common/StateMachine/StateMachineTests.cs Transitions valides/invalides, états terminaux, cycle complet
Orkeon.Domain.Tests/Common/StateMachine/StateMachineGuardTests.cs Guards typés, priorité des guards, actions sur transition
Orkeon.Domain.Tests/Common/StateMachine/CircuitBreakerTests.cs Transitions max, détection de cycles, mode dégradé, reset, histogramme
Orkeon.Infrastructure.Tests/Configuration/CircuitBreakerPolicyFactoryGraphTests.cs graph: → policy : presets, surcharges, repli
Orkeon.Scripting.Cli.Tests/Forge/ForgeStateMachineTests.cs Les coups légaux du cycle forge
dotnet test tests/core/Orkeon.Domain.Tests/Orkeon.Domain.Tests.csproj --filter "FullyQualifiedName~StateMachine"