State machine, ou les transitions qu'on rend impossiblesState machine, or the transitions we make impossible

Un état stocké dans un champ libre. Quelles transitions devraient être impossibles ?State stored in a free field. Which transitions should be impossible?

status est une chaîne, et n'importe quelle méthode lui assigne n'importe quelle valeur. La commande a pourtant un cycle de vie réel : on ne livre pas une commande annulée, on ne rembourse pas ce qui n'a pas été payé. Ce sont des règles — mais elles ne vivent nulle part en un seul endroit. Elles sont éparpillées en gardes partielles, supposées plus que vérifiées. Ce qui varie, ce n'est pas l'état lui-même : c'est l'ensemble des transitions légales d'un état vers un autre. Le réflexe : faire de l'état un ensemble fini, et des transitions une déclaration explicite — pour qu'une transition illégale soit impossible à exprimer, pas seulement déconseillée.status is a string, and any method assigns it any value. The order has a real lifecycle, though: you don't ship a cancelled order, you don't refund what was never paid. These are rules — but they live nowhere in one place. They're scattered as partial guards, assumed more than enforced. What varies isn't the state itself: it's the set of legal transitions from one state to another. The reflex: make the state a finite set, and the transitions an explicit declaration — so that an illegal transition is impossible to express, not merely discouraged.

# l'état est un champ libre — n'importe quel code peut y écrire n'importe quoi
class Order:
    status: str = "pending"          # une simple chaîne : aucune contrainte

    def ship(self):    self.status = "shipped"      # aucune vérification d'où l'on vient
    def cancel(self):  self.status = "cancelled"    # … on peut annuler une commande expédiée
    def refund(self):  self.status = "refunded"     # … rembourser sans avoir payé

# rien n'empêche : ship() puis cancel() puis ship() à nouveau.
# « une commande expédiée ne s'annule pas » est une RÈGLE — mais elle n'est
# écrite nulle part. Les transitions illégales ne sont pas impossibles :
# elles sont juste « pas censées arriver ». Et un jour, elles arrivent.

L'illégal arrive en prod, et personne ne sait dire ce qui peut suivre.The illegal reaches prod, and no one can say what may come next.

Laisser l'état dans un champ libre a trois coûts qui se renforcent. Les transitions illégales arrivent : rien n'empêche d'annuler une commande expédiée, alors un jour un appel mal ordonné le fait, et la base contient un état que le métier jurait impossible. Les règles de transition se dispersent : « on ne rembourse que ce qui a été payé » vit en gardes éparses, recopiées dans chaque méthode, jamais réunies. Et on ne peut pas répondre à « que peut-il se passer ensuite ? » : la seule façon de connaître les suites légales d'un état est de relire tout le code qui mute status — il n'existe nulle part une carte du cycle de vie.Leaving state in a free field has three costs that reinforce each other. Illegal transitions happen: nothing stops cancelling a shipped order, so one day a mis-ordered call does it, and the database holds a state the domain swore impossible. Transition rules scatter: 'refund only what was paid' lives in scattered guards, recopied in each method, never gathered. And you can't answer 'what may happen next?': the only way to know an state's legal successors is to reread every line that mutates status — nowhere is there a map of the lifecycle.

order.status = "shipped"              # 💥 dans le service d'expédition
order.status = "cancelled"            # 💥 dans le handler d'annulation — même si expédié
order.status = req.body["status"]     # 💥 dans un endpoint d'admin : N'IMPORTE QUELLE chaîne
order.status = "refunded"             # 💥 dans le webhook de paiement — sans vérifier "paid"
# la règle « expédié ne s'annule pas » : nulle part. Quatre écritures, zéro carte.

On ferme l'ensemble des états, puis on ne câble que les passages légaux.Close the set of states, then wire only the legal passages.

La machine à états transforme un champ libre en cycle de vie déclaré. L'animation part du champ où toutes les flèches existent — y compris les interdites —, ferme l'ensemble en états finis nommés, câble en un seul endroit les transitions permises, puis montre l'essentiel : une transition absente de la table n'est pas refusée, elle est irreprésentable. À chaque marche, ce qui était une règle dans une tête devient une structure que le code, les tests et le diagramme partagent.A state machine turns a free field into a declared lifecycle. The animation starts from the field where every arrow exists — including the forbidden ones —, closes the set into named finite states, wires the permitted transitions in one place, then shows the essential: a transition absent from the table isn't refused, it's unrepresentable. At each step, what was a rule in someone's head becomes a structure the code, the tests and the diagram share.

# les transitions permises, déclarées en UN endroit — c'est toute la règle
TRANSITIONS = {▸ à toiyour turn — déclare les passages permis, en UN endroit : pending→paid→shipped, plus les deux sorties (cancel depuis pending, refund depuis paid)declare the permitted passages, in ONE place: pending→paid→shipped, plus the two exits (cancel from pending, refund from paid) · cliquer pour révélerclick to reveal}                              # "shipped" n'a aucune sortie : il est terminal

def apply(state, event):       # la SEULE porte vers un changement d'état
    key = (state, event)▸ à toiyour turn — une clé (état, événement) absente de la table — quelle garde la rejette ?a (state, event) key absent from the table — which guard rejects it? · cliquer pour révélerclick to reveal        raise IllegalTransition(state, event)   # rebondit à l'entrée, pas en base▸ à toiyour turn — le passage est légal : que renvoie la seule porte ?the passage is legal: what does the sole door return? · cliquer pour révélerclick to reveal

Une machine qu'on peut contourner ne garde rien. La porte dérobée.A machine you can bypass guards nothing. The back door.

Le piège n'est pas la machine — c'est la porte qu'on laisse ouverte à côté. La dérive principale : une machine à états « décorative ». On déclare des transitions, on écrit apply(), mais l'état reste public et la moitié du code continue d'assigner order.state = '…' directement, « parce que c'était plus simple ». La garde existe et ne sert à rien : l'illégal reste atteignable par la fenêtre. L'excès inverse guette aussi : sur-modéliser un statechart à douze états pour un booléen, payer la cérémonie d'une machine là où un drapeau suffisait. Bascule le toggle : cherche l'écriture qui contourne l'unique porte.The trap isn't the machine — it's the door you leave open beside it. The main drift: a 'decorative' state machine. You declare transitions, you write apply(), but the state stays public and half the code keeps assigning order.state = '…' directly, 'because it was simpler'. The guard exists and is useless: the illegal stays reachable through the window. The opposite excess lurks too: over-modeling a twelve-state statechart for a boolean, paying a machine's ceremony where a flag sufficed. Flip the toggle: hunt the write that bypasses the only door.

# la machine est la SEULE porte : aucun setter public, aucune mutation directe
class Order:
    def __init__(self):
        self._state = "pending"        # privé : personne n'écrit _state de l'extérieur

    def apply(self, event):            # l'unique entrée
        self._state = transition(self._state, event)   # lève si la flèche n'existe pas

# ailleurs dans le code, on ne peut QUE :
order.apply("pay"); order.apply("ship")
# order._state = "refunded"   ← ne se fait pas : l'état illégal est inatteignable par erreur.
# la table des transitions EST la règle métier, en un seul endroit auditable.

Un champ qu'on espère correct, ou une table où l'illégal n'existe pas.A field you hope is correct, or a table where the illegal doesn't exist.

Quand ne pas faire de machineWhen not to build a machine

La machine a un loyer : une table à tenir, une seule porte à défendre, une indirection de plus. On reste avec un simple champ — et c'est correct — quand :The machine has rent: a table to maintain, a single door to defend, one more indirection. Stay with a plain field — and that's fine — when:

• il n'y a que deux états sans transition coûteuse : un drapeau actif/inactif, lu/non-lu. Un booléen dit tout ; une machine ici n'est que de la cérémonie (YAGNI, Vol 0 #3) — la sur-modélisation du chapitre 4.there are only two states with no costly transition: an active/inactive, read/unread flag. A boolean says it all; a machine here is mere ceremony (YAGNI, Vol 0 #3) — chapter 4's over-modeling.
• aucune transition n'est réellement interdite : si tout état peut légitimement suivre tout autre, il n'y a pas de règle à protéger, donc rien que la machine rende impossible. Elle n'a de valeur que par les flèches qu'elle absente.no transition is truly forbidden: if any state can legitimately follow any other, there's no rule to protect, so nothing the machine makes impossible. It's only worth the arrows it leaves out.
• le cycle de vie est ouvert ou inconnu : si les états apparaissent et disparaissent au gré du produit, figer une table trop tôt, c'est se battre contre le changement à chaque release. Attends que la forme se stabilise avant de la sceller.the lifecycle is open or unknown: if states come and go with the product, freezing a table too early means fighting change at every release. Wait for the shape to stabilize before sealing it.

Le réflexe n'est donc pas « modélise toujours une machine à états, c'est plus rigoureux » : c'est « existe-t-il un cycle de vie fini avec des passages interdits ? Alors une table, et une seule porte. Sinon, un champ honnête vaut mieux qu'une machine qu'on contourne. »So the reflex isn't 'always model a state machine, it's more rigorous': it's 'is there a finite lifecycle with forbidden passages? Then a table, and a single door. Otherwise, an honest field beats a machine you bypass.'

Mot de l'éditeurFrom the editor

Ce numéro tire « State » de la parenthèse où le #1 l'avait laissé, parce que son réflexe — rendre les états illégaux impossibles — est l'un des plus transférables de toute la série. La leçon n'est pas « apprends le pattern State du GoF » : c'est « ne laisse pas une règle de transition vivre à l'état de vœu pieux ». Un champ libre espère que le code se tiendra bien ; une machine à états le rend incapable de mal se tenir. La nuance qui sauve : la machine ne vaut que si elle est la seule porte — une garde qu'on peut contourner ne garde rien.This issue pulls 'State' out of the parenthesis #1 left it in, because its reflex — making illegal states impossible — is one of the most transferable in the whole series. The lesson isn't 'learn the GoF State pattern': it's 'don't let a transition rule live as a pious wish'. A free field hopes the code behaves; a state machine makes it unable to misbehave. The saving nuance: the machine is only worth it if it's the only door — a guard you can bypass guards nothing.

Avec lui se referme le Vol 3, les patterns d'objets dont le réflexe survit : Strategy injectait un comportement à la place d'un if/else, et State n'en est que le cas particulier où le comportement, c'est l'état lui-même et ses passages. On boucle aussi le fil rouge fonctionnel tendu depuis le début : le pattern State du GoF — une classe par état, du polymorphisme partout — s'effondre, en programmation fonctionnelle, en une seule fonction pure (état, événement) → état. Tout l'échafaudage objet n'était qu'une manière de transporter cette fonction. La suite quitte l'objet pour le système : le Vol 4 ouvre la communication entre composants, où la première question n'est plus quelle transition est légale, mais « ai-je besoin d'une réponse maintenant, ou seulement que ce soit fait un jour ? ».With it Vol 3 closes, the object patterns whose reflex survives: Strategy injected a behavior in place of an if/else, and State is just the special case where the behavior is the state itself and its passages. We also close the functional thread strung from the start: the GoF State pattern — one class per state, polymorphism everywhere — collapses, in functional programming, into a single pure function (state, event) → state. All the object scaffolding was just a way to carry that function. What follows leaves the object for the system: Vol 4 opens communication between components, where the first question is no longer which transition is legal, but 'do I need an answer now, or only that it gets done someday?'.

Les voisins que ce numéro débloqueThe neighbors this issue unlocks

• State (GoF) — la version objet : une classe par état, chacune sachant vers quels états elle peut transiter. Utile quand chaque état porte beaucoup de comportement propre ; mais souvent plus lourd qu'une table, et c'est lui qui s'effondre en (état, événement) → état dès qu'on raisonne en fonctions.the object version: one class per state, each knowing which states it can transition to. Useful when each state carries a lot of its own behavior; but often heavier than a table, and it's the one that collapses into (state, event) → state once you reason in functions.
• Statecharts — la machine à états poussée : états imbriqués, états parallèles, gardes et actions sur les transitions. Indispensable pour une UI ou un protocole riche ; le danger est exactement celui du chapitre 4 — sur-modéliser, et payer un statechart là où une table plate suffisait.the state machine scaled up: nested states, parallel states, guards and actions on transitions. Indispensable for a rich UI or protocol; the danger is exactly chapter 4's — over-model, and pay for a statechart where a flat table sufficed.
• Type-state — la forme la plus forte : chaque état est un type distinct, et les transitions illégales ne compilent pas. L'« état illégal » n'a plus de représentation du tout — c'est « rendre les états illégaux irreprésentables » porté jusqu'au système de types. La fin du voyage commencé au chapitre 1.the strongest form: each state is a distinct type, and illegal transitions don't compile. The 'illegal state' has no representation at all — it's 'make illegal states unrepresentable' carried into the type system. The end of the journey begun in chapter 1.

Le kata — écris-le, ne le relis pasThe kata — write it, don't reread it

# test_order_state.py — la spec EST le harnais : fais-le passer au vert.
# un ensemble fini d'états, une table de transitions permises, et apply() pour
# seule porte. l'illégal n'est pas refusé : il est absent de la table.

def test_le_chemin_nominal_traverse_les_etats():
    o = Order()                               # démarre "pending"
    o.apply("pay"); o.apply("ship")
    assert o.state == "shipped"

def test_une_transition_illegale_est_rejetee():
    o = Order()                               # "pending"
    with raises(IllegalTransition):
        o.apply("ship")                       # on ne livre pas une commande non payée

def test_l_illegale_ne_corrompt_pas_l_etat():
    o = Order()
    try: o.apply("ship")                      # rejetée…
    except IllegalTransition: pass
    assert o.state == "pending"               # …et l'état n'a pas bougé d'un pouce

def test_un_evenement_inconnu_echoue_pareil():
    o = Order()
    with raises(IllegalTransition):
        o.apply("teleport")                   # pas dans la table = illégal, point

def test_les_deux_sorties_partent_des_bons_etats():
    assert Order().apply("cancel").state == "cancelled"     # cancel depuis pending : ok
    paid = Order(); paid.apply("pay")
    assert paid.apply("refund").state == "refunded"         # refund depuis paid : ok

def test_l_etat_terminal_n_a_aucune_sortie():
    # LE test du pattern : "shipped" est terminal — AUCUN événement ne l'en sort.
    # une machine juste se juge autant à ses flèches absentes qu'à ses flèches présentes.
    o = Order(); o.apply("pay"); o.apply("ship")            # → shipped
    for ev in ["pay", "ship", "cancel", "refund"]:
        with raises(IllegalTransition): o.apply(ev)
    assert o.state == "shipped"