Contracts¶

Status: CONTRACT

Rôle¶

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

Ils précisent :

les entrées acceptées ;
les sorties garanties ;
les statuts et codes de raison ;
les responsabilités de chaque composant ;
les dépendances autorisées ;
les invariants testables.

Un Contract décrit un comportement observable. Il ne porte ni orchestration runtime, ni SQL, ni rendu frontend, ni règle métier propre à une verticale.

Position dans l’architecture¶

Adapters / Runtime / Pipeline
            │
            ▼
       Application
            │
            ▼
         Contracts
            │
            ▼
       Domain Core
            │
            ▼
 Vertical Modules / Infrastructure

Les Contracts empêchent les couches externes de dépendre de détails d’implémentation internes.

Principes¶

Stabilité¶

Un Contract ne change pas silencieusement. Toute évolution incompatible doit être versionnée, migrée ou accompagnée d’une stratégie de compatibilité explicite.

Déterminisme¶

À entrées identiques, une implémentation conforme doit produire les mêmes résultats métier, statuts et raisons.

Explicabilité¶

Toute décision importante doit pouvoir exposer des preuves, des codes de raison ou des diagnostics structurés.

Neutralité technique¶

Un Contract ne dépend pas directement de WordPress, de $wpdb, d’un transport HTTP, d’une commande WP-CLI ou d’un renderer.

Séparation lecture / écriture¶

Les contrats read-only ne déclenchent aucune mutation. Les contrats d’écriture doivent annoncer explicitement leur portée, leurs préconditions et leur résultat.

Contrats canoniques¶

Contract	Responsabilité
Identity Resolver	Transformer des évidences et candidats en décision d’identité explicable
Conflict Policy	Classifier les incompatibilités sans masquer un conflit réel
Quality Scorer	Évaluer une qualité ou une confiance sans prendre la décision d’identité
Projection Builder	Construire une vue déterministe sans persister ni altérer la vérité métier
Write Service	Encadrer une mutation explicite, traçable, idempotente et maîtrisée

Modèle commun de résultat¶

Lorsqu’un composant prend une décision, sa sortie devrait pouvoir représenter au minimum :

status
confidence
reason_codes[]
evidence[]
diagnostics{}

Les statuts exacts dépendent du Contract, mais les états non résolus doivent rester explicites. Ils ne doivent pas être convertis artificiellement en succès.

Les familles courantes sont :

resolved ;
unknown ;
ambiguous ;
conflict.

Les alias historiques ne deviennent pas automatiquement des statuts canoniques. Leur compatibilité doit être documentée au point d’adaptation.

Frontières¶

Les Contracts peuvent dépendre de types métier stables et de value objects génériques.

Ils ne doivent pas :

exécuter de SQL ;
accéder directement aux globals WordPress ;
charger le Pipeline ;
écrire dans une projection ;
rendre du HTML ou du JSON HTTP ;
contenir une règle Smartphone, Photo, TV ou autre verticale ;
transformer une absence de preuve en décision positive.

Les Vertical Modules fournissent des règles ou évidences spécialisées derrière les interfaces prévues. Ils ne redéfinissent pas le mécanisme générique.

Lecture et écriture¶

Un contrat de lecture ou d’analyse doit garantir :

absence de mutation persistante ;
résultats sérialisables ;
métriques réconciliables ;
reproductibilité sur un même jeu de données.

Un contrat d’écriture doit garantir :

action explicitement demandée ;
périmètre identifié ;
préconditions validées ;
idempotence ou stratégie de reprise documentée ;
résultat et erreurs structurés ;
traçabilité opérationnelle.

Media Quality¶

Media Quality applique ces mêmes frontières :

Evidence Engine
      ↓
Quality Decision
      ↓
Audit / diagnostics
      ↓
Optional explicit mutation policy

Le comportement canonique est audit-first :

l’analyse est non destructive par défaut ;
une image incohérente n’est pas supprimée implicitement ;
unknown, ambiguous et conflict restent observables ;
un remplacement éventuel nécessite une politique d’écriture séparée et une confiance suffisante ;
les métriques doivent distinguer observation, décision et mutation.

Voir Media Quality Engine.

Maturité d’un Contract¶

Un Contract doit émerger d’un besoin partagé et prouvé, pas d’une abstraction spéculative.

Les statuts documentaires recommandés sont :

DRAFT : exploration ;
CONTRACT : comportement normatif actuel ;
DEPRECATED : compatibilité temporaire ;
HISTORICAL : décision ancienne conservée pour traçabilité.

La maturité se valide par le code, les tests, les consommateurs réels et la documentation opérationnelle.

Tests attendus¶

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

tests unitaires de comportement ;
cas limites unknown, ambiguous et conflict ;
tests de déterminisme ;
tests de sérialisation des résultats ;
tests d’architecture sur les dépendances interdites ;
preuve de non-mutation pour les contrats read-only ;
tests d’idempotence et de reprise pour les contrats d’écriture.

Invariants¶

Un Contract décrit une frontière, pas une implémentation technique.
Les décisions restent déterministes et explicables.
Les états non résolus ne sont jamais masqués.
Les contrats read-only ne mutent rien.
Toute écriture est explicite, traçable et isolée.
Le Domain Core ne dépend ni de WordPress ni des adapters.
Les règles verticales restent derrière des extensions prévues.
Media Quality reste audit-first et non destructif par défaut.