Contrats¶

Statut : CONTRACT

À quoi servent les contrats ?¶

Les Contracts définissent les frontières stables entre les grandes couches de CMonChoix.

Un contrat répond à une question simple :

Si un composant demande quelque chose à un autre composant, quelles entrées sont acceptées et quel résultat peut-il attendre ?

Le contrat décrit donc ce qui est garanti, sans imposer comment c'est techniquement réalisé.

Exemple simple¶

Imaginons que le moteur applicatif ait besoin de résoudre l'identité d'un produit.

Il ne devrait pas connaître toutes les classes internes du moteur d'identité. Il utilise un contrat :

Entrées normalisées
       ↓
Identity Resolver Contract
       ↓
Résultat explicite

Le contrat peut garantir un statut, un niveau de confiance, des raisons et des preuves. L'implémentation interne peut ensuite évoluer tant qu'elle continue de respecter ce contrat.

Pourquoi c'est important¶

Sans contrats stables, chaque couche finit par connaître les détails internes des autres.

On obtient alors des dépendances fragiles : un changement SQL casse la CLI, une modification du Runtime casse le Domain, ou un refactoring interne oblige à modifier le Frontend.

Les contrats servent à éviter ce couplage.

Position dans l'architecture¶

Apps / Adapters / Runtime / Pipeline
                ↓
           Application
                ↓
            Contracts
                ↓
          Domain / Services
                ↓
        Implémentations concrètes

Le schéma exprime des responsabilités logiques, pas forcément des dossiers physiques stricts.

Ce qu'un contrat peut définir¶

Selon le besoin, un Contract peut préciser :

les données d'entrée ;
le résultat retourné ;
les statuts possibles ;
les codes de raison ;
les preuves ou diagnostics ;
les préconditions ;
les erreurs explicites ;
les garanties d'idempotence ;
les règles de compatibilité entre versions.

Ce qu'un contrat ne doit pas contenir¶

Un Contract ne doit pas :

exécuter du SQL ;
appeler directement WordPress ;
gérer un cron ou un worker ;
afficher du HTML ;
contenir une règle propre à une verticale ;
masquer une mutation ;
dépendre d'une implémentation technique concrète.

Contrats importants de la plateforme¶

Contrat	Rôle expliqué simplement
Identity Resolver	Transformer les preuves disponibles en décision d'identité explicable.
Conflict Policy	Détecter et classifier les incompatibilités sans les cacher.
Quality Scorer	Mesurer une qualité ou une confiance sans décider seul de l'identité.
Projection Builder	Construire une vue dérivée déterministe sans persister directement.
Write Service	Encadrer une mutation explicitement demandée et auditable.

Comprendre le modèle de résultat¶

Un résultat important devrait pouvoir exposer des éléments comme :

status
confidence
reason_codes[]
evidence[]
diagnostics{}

`status`¶

Indique l'état de la décision.

Les états fréquents sont :

resolved : décision établie ;
unknown : pas assez d'informations ;
ambiguous : plusieurs interprétations restent possibles ;
conflict : les preuves se contredisent.

`confidence`¶

Indique le niveau de confiance dans la décision. Une forte confiance ne doit jamais faire disparaître un conflit réel.

`reason_codes`¶

Ce sont des codes stables permettant de comprendre et de tester pourquoi une décision a été prise.

`evidence`¶

Ce sont les preuves utilisées : identifiants, attributs, observations ou autres signaux autorisés.

`diagnostics`¶

Informations techniques ou détaillées utiles aux audits et investigations.

Lecture et écriture¶

Cette distinction est essentielle.

Contrat de lecture¶

Un contrat read-only garantit qu'aucune donnée n'est modifiée.

Il peut servir à :

auditer ;
comparer ;
simuler ;
produire un diagnostic.

Contrat d'écriture¶

Un contrat d'écriture doit annoncer clairement :

ce qui sera modifié ;
sur quel périmètre ;
sous quelles préconditions ;
comment l'opération peut être rejouée ou reprise ;
quel résultat a effectivement été appliqué.

Une commande présentée comme « audit » ne doit jamais cacher une écriture.

Contrats et verticales¶

Les verticales peuvent fournir des règles spécialisées derrière les interfaces prévues.

Par exemple, Smartphone peut interpréter certaines capacités ou variantes. Mais le contrat générique ne doit pas devenir dépendant de Smartphone.

La direction reste :

Contrat générique
      ↑
Extension prévue
      ↑
Verticale spécialisée

Contrats et Media Quality¶

Media Quality suit exactement la même discipline :

Évidences
   ↓
Décision qualité
   ↓
Audit / diagnostic
   ↓
Éventuelle mutation explicite séparée

Par défaut, l'analyse ne doit rien détruire ni remplacer.

Comment diagnostiquer un problème de contrat¶

Pose ces questions :

Les données entrantes respectent-elles le format prévu ?
Le résultat retourné contient-il les statuts et raisons attendus ?
L'implémentation a-t-elle ajouté un comportement non prévu par le contrat ?
Une couche consommatrice dépend-elle de détails internes qui ne devraient pas être publics ?
Une ancienne compatibilité est-elle devenue par erreur la nouvelle API canonique ?

Maturité documentaire¶

Les statuts utilisés dans le projet sont notamment :

DRAFT : exploration ;
CONTRACT : comportement normatif actuel ;
DEPRECATED : compatibilité temporaire à ne plus promouvoir ;
HISTORICAL : document conservé pour comprendre le passé.

Un fichier marqué DRAFT ne doit pas être pris automatiquement pour une capacité active en production.

Tests attendus¶

Un Contract important doit être protégé par :

des tests de comportement ;
des cas limites ;
des tests de déterminisme ;
des tests de sérialisation ;
des tests d'architecture sur les dépendances interdites ;
une preuve de non-mutation pour les contrats read-only ;
des tests d'idempotence pour les écritures.

Règle de transmission¶

Si tu modifies un composant et que plusieurs autres parties du projet dépendent directement de ses classes internes, demande-toi s'il manque un Contract stable.

Un bon contrat permet de comprendre la collaboration sans devoir lire toute l'implémentation.

Invariants¶

Un Contract décrit une frontière, pas une technologie.
Les décisions importantes restent explicables.
Les états non résolus restent visibles.
Un contrat read-only n'écrit jamais.
Toute écriture est explicite et traçable.
Une verticale ne redéfinit pas le contrat générique.
Les compatibilités anciennes restent identifiables comme telles.