Fiabilité, idempotence et provenance
Une extension doit rester sûre lorsque les appels sont rejoués, que des événements arrivent en retard ou qu’une tentative échoue après un effet externe. La fiabilité est une propriété du contrat, pas une hypothèse sur le transport.
Idempotence
Ne déclarez pas une opération idempotente simplement parce qu’elle est habituellement appelée une fois. Identifiez la clé stable qui représente l’intention métier et la façon dont un retry retrouve l’effet déjà produit.
- réutilisez l’identité publique Ormuz lorsqu’elle représente déjà l’opération ;
- utilisez un mapping durable pour retrouver une ressource externe créée depuis un objet plateforme ;
- après un timeout post-soumission, recherchez l’effet existant avant de recommencer une mutation ;
- ne créez pas une seconde primitive d’idempotence lorsqu’une identité canonique suffit.
Replay et événements entrants
La normalisation d’un événement entrant peut être rejouée. Elle ne doit donc produire aucun effet de bord non idempotent simplement parce qu’un webhook a été reçu une nouvelle fois.
L’ordre d’arrivée d’événements externes ne doit pas remplacer les règles de lifecycle canoniques. Une transition invalide reste invalide même si son timestamp est plus récent ; un état non terminal ne doit pas faire régresser un terminal.
Warnings
Un warning décrit une exécution réussie mais dégradée ou notable. Il ne doit jamais servir à maquiller une erreur bloquante.
- utilisez un code machine stable en
snake_case; - écrivez un message sûr pour l’opérateur, sans secret ni payload brut ;
- gardez les warnings hors du contrat métier des outputs ;
- ne transformez pas un succès en échec uniquement parce qu’un warning est présent.
Erreurs actionnables
Une erreur publique doit permettre au processus, à l’Agent ou à l’opérateur de comprendre la nature du problème sans exposer de détails internes ou de credentials.
Distinguez autant que possible les erreurs de validation, d’autorité, de permission, de ressource introuvable, de conflit de lifecycle et d’indisponibilité partenaire. Une erreur technique vague ne doit pas remplacer un résultat métier prévu par le contrat.
Provenance et corrélation
Conservez l’identité qui permet de relier une opération Ormuz à son effet externe, mais ne transformez pas cette corrélation en nouveau système de mastership.
Les références de provenance, mappings et identités d’événements doivent permettre d’expliquer et de dédupliquer les effets sans dupliquer l’objet métier ni perdre son histoire.