Aller au contenu

Identity Resolver Contract

Status: CONTRACT

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

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

Position dans l'architecture

Observed data
      ↓
Normalized evidence
      ↓
Candidates
      ↓
Identity Resolver
      ↓
Resolution Decision
      ↓
Canonical Identity / unresolved state

Le Resolver est un moteur de décision pur. Il consomme des données préparées et retourne une décision sérialisable.

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.

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.

Statuts

Le vocabulaire canonique est :

Statut Signification
resolved Un candidat domine avec une confiance suffisante et sans conflit bloquant.
unknown Les informations disponibles ne permettent pas de former une hypothèse exploitable.
ambiguous Plusieurs candidats restent plausibles sans preuve suffisante pour les départager.
conflict Des évidences incompatibles empêchent volontairement la résolution.

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.

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.

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.

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.

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.

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.

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

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

Voir aussi