Identity Resolver Contract¶

Status: CONTRACT

À quoi sert ce contrat ?¶

Le contrat Identity Resolver définit le comportement commun utilisé pour transformer des évidences et des candidats en une décision d'identité explicable.

Dans CMonChoix, le Resolver est le composant qui répond à la question : « avec les informations disponibles, savons-nous à quel produit ou à quelle variante cette observation correspond ? »

Il ne décrit aucune verticale particulière et ne porte aucune écriture persistante.

Pourquoi le Resolver existe-t-il ?¶

Une source marchande peut fournir un titre, une référence, une couleur, une capacité ou d'autres indices sans donner directement l'identité canonique attendue par CMonChoix. Plusieurs produits peuvent aussi sembler compatibles avec les mêmes informations.

Le Resolver centralise cette décision afin que :

la même situation produise la même réponse quel que soit le Runtime ;
une incertitude reste visible au lieu d'être transformée arbitrairement en correspondance ;
les conflits soient traités comme des informations métier ;
chaque décision puisse être auditée et expliquée ;
les règles propres à une verticale restent isolées derrière des contrats explicites.

Position dans l'architecture¶

Données observées
      ↓
Évidences normalisées
      ↓
Candidates
      ↓
Identity Resolver
      ↓
Resolution Decision
      ↓
Canonical Identity / état non résolu

Un Candidate est une identité plausible proposée au moteur. Une évidence est un élément observable ou dérivé qui permet d'évaluer ce candidat. La Resolution Decision est le résultat structuré du Resolver.

Le Resolver est un moteur de décision pur : il consomme des données préparées et retourne une décision sérialisable. Il ne va pas chercher lui-même des données en base et ne persiste pas son résultat.

Entrées¶

Une implémentation conforme reçoit au minimum :

les candidats disponibles ;
les identifiants normalisés ;
les attributs produit et variante ;
les évidences ayant permis de construire chaque candidat ;
les signaux de conflit ;
les contributions optionnelles d'un Vertical Module ;
le contexte d'audit nécessaire à l'explicabilité.

Une évidence doit distinguer autant que possible :

la valeur observée ;
la valeur normalisée ou dérivée ;
la source ;
la règle ayant produit la dérivation ;
le niveau de confiance ;
les éventuels codes de raison.

Cette séparation évite qu'une valeur calculée soit ensuite prise pour une observation brute.

Sortie canonique¶

Le Resolver retourne une décision structurée contenant :

status ;
l'identité retenue lorsqu'elle existe ;
les candidats évalués ;
un score ou niveau de confiance ;
les codes de raison ;
les conflits détectés ;
les évidences principales ;
les métadonnées d'audit utiles.

Le résultat doit pouvoir être sérialisé sans dépendre de WordPress, de SQL ou d'un renderer.

Les quatre statuts à connaître¶

Le vocabulaire canonique est :

Statut	Signification	Ce qu'un mainteneur doit comprendre
`resolved`	Un candidat domine avec une confiance suffisante et sans conflit bloquant.	Une identité peut être retenue selon les règles courantes.
`unknown`	Les informations disponibles ne permettent pas de former une hypothèse exploitable.	Il manque de la preuve ; ce n'est pas une erreur technique.
`ambiguous`	Plusieurs candidats restent plausibles sans preuve suffisante pour les départager.	Il existe des hypothèses, mais aucune ne doit être forcée.
`conflict`	Des évidences incompatibles empêchent volontairement la résolution.	Le système a trouvé une contradiction qui doit rester visible.

Les anciennes valeurs telles que resolved_candidate, conflict_blocking ou invalid doivent être traitées comme des libellés historiques ou des adaptations de transport, pas comme un second vocabulaire métier concurrent.

Exemple de lecture d'une décision¶

Imaginons une offre dont le titre et la référence constructeur pointent vers le même smartphone, mais dont la capacité observée correspond à deux variantes possibles.

Le bon résultat peut être ambiguous plutôt que resolved. Ce résultat signifie que le Resolver fonctionne correctement : il refuse de fabriquer une précision que les données ne permettent pas d'établir.

À l'inverse, si un identifiant constructeur fort désigne un modèle et qu'une autre évidence forte désigne un modèle incompatible, le résultat attendu peut être conflict.

Responsabilités¶

Le Resolver :

compare les candidats sur une base déterministe ;
applique les règles génériques de compatibilité ;
prend en compte les politiques verticales via des contrats explicites ;
détecte les conflits ;
refuse de forcer une décision insuffisamment étayée ;
produit les raisons de sa décision ;
conserve une séparation nette entre produit et variante.

Ce qu'il ne fait jamais¶

Le Resolver ne doit jamais :

lire ou écrire directement en base ;
modifier un feed, une offre ou une projection ;
déclencher le Runtime ;
charger WordPress ;
dépendre du Frontend ;
reconstruire une logique propre à une verticale dans le Core ;
masquer un conflit réel pour améliorer artificiellement un KPI ;
transformer une absence de preuve en preuve positive.

Si une résolution correcte nécessite une donnée supplémentaire, cette donnée doit être préparée en amont ou fournie par un contrat approprié. Il ne faut pas ajouter un accès SQL caché au Resolver.

Déterminisme¶

Pour les mêmes entrées et la même version de règles, le Resolver doit produire :

le même statut ;
le même candidat retenu ;
les mêmes codes de raison ;
le même ordre de classement.

Tout tri doit posséder un départage stable. L'ordre d'arrivée des feeds ou des lignes ne doit pas modifier la décision.

Ce point est essentiel pour les rebuilds, les audits et les comparaisons avant/après : un changement de résultat doit pouvoir être expliqué par un changement de données, de règles ou de version, pas par un ordre accidentel d'exécution.

Conflits¶

Un conflit est une information métier, pas une erreur technique.

Les conflits typiques concernent notamment :

une marque incompatible ;
une famille ou génération incompatible ;
deux modèles distincts ;
une variante impossible ;
des identifiants forts contradictoires.

Une politique verticale peut préciser la gravité d'un conflit, mais elle ne peut pas supprimer l'obligation de l'exposer.

Lors d'un diagnostic, il faut donc distinguer :

erreur technique : le Resolver n'a pas pu s'exécuter correctement ;
conflict métier : le Resolver s'est exécuté et a volontairement refusé une identité en raison de preuves incompatibles.

Relation avec le Quality Scorer¶

Le Resolver décide si une identité peut être retenue.

Le Quality Scorer évalue la qualité et la confiance des informations disponibles.

Le score peut contribuer à la décision, mais il ne remplace ni la politique de conflit ni les garde-fous du Resolver. Un score élevé ne donne donc pas le droit d'effacer une contradiction forte.

Relation avec Media Quality¶

Media Quality n'est pas une résolution d'identité.

Son moteur produit des observations et diagnostics sur la cohérence des médias, notamment l'image principale et les attributs attendus.

Par défaut :

l'analyse est audit-first ;
aucune image n'est supprimée ;
aucune projection n'est mutée ;
un diagnostic unknown, ambiguous ou conflict reste explicite ;
une mutation éventuelle exige un Write Service séparé et une politique opt-in documentée.

Comment diagnostiquer une résolution inattendue¶

Si un cas semble mal résolu, ne commencez pas par modifier les seuils ou ajouter une exception.

Vérifiez dans cet ordre :

les valeurs réellement observées ;
leur normalisation ;
les candidats effectivement construits ;
les évidences associées à chaque candidat ;
les codes de raison produits ;
les conflits détectés ;
la contribution éventuelle du Vertical Module ;
la version des règles utilisée.

Cette démarche permet de déterminer si le défaut se trouve dans l'ingestion, la normalisation, la génération des candidats, la politique verticale ou le Resolver lui-même.

Erreurs fréquentes de maintenance¶

considérer unknown comme un échec à corriger à tout prix ;
transformer automatiquement ambiguous en premier candidat de la liste ;
supprimer un conflit parce qu'il réduit le taux de résolution ;
ajouter une règle smartphone directement dans le Core générique ;
faire dépendre le résultat de l'ordre des feeds ;
confondre score de qualité et décision d'identité ;
écrire directement la décision depuis le Resolver.

Garde-fous¶

Une implémentation conforme doit :

préserver les conflits forts ;
conserver les évidences expliquant la décision ;
refuser les décisions fondées uniquement sur un signal faible ;
séparer les règles génériques des règles verticales ;
signaler les valeurs inconnues au lieu de les inventer ;
produire des métriques réconciliables avec le nombre total de cas évalués.

Tests attendus¶

Les tests doivent au minimum couvrir :

un candidat unique résolu ;
plusieurs candidats équivalents donnant ambiguous ;
des données insuffisantes donnant unknown ;
un conflit fort donnant conflict ;
la stabilité du résultat lorsque l'ordre des entrées change ;
la conservation des codes de raison ;
l'absence d'accès SQL, WordPress ou Runtime ;
la compatibilité des contributions verticales sans dépendance Core vers une verticale concrète.

Invariants¶

Le Resolver reste pur et déterministe.
Toute décision est explicable par des évidences et des codes de raison.
unknown, ambiguous et conflict sont des résultats valides.
Le Resolver n'écrit jamais.
Le Core ne dépend d'aucune verticale concrète.
La qualité ne remplace pas la résolution.
Media Quality reste non destructif par défaut.