Virtual Candidates Dump¶

Status: CURRENT

À quoi sert ce dump ?¶

Le Virtual Candidates Dump est un Read Service de diagnostic qui expose, pour un cas donné, les candidats, évidences et raisons utilisés autour d'une décision d'identité.

Il sert à répondre à des questions comme :

quels candidats existaient réellement ?
quels identifiants et attributs les distinguaient ?
quels conflits ont été détectés ?
pourquoi un candidat a-t-il été retenu, rejeté ou laissé ambigu ?

Il rend le raisonnement observable sans modifier l'état de la Platform.

Données normalisées
      ↓
Construction des candidats / Resolver
      ↓
Virtual Candidates Dump
      ↓
Vue détaillée des candidats + évidences + reason codes

Différence avec le Resolution Status Audit¶

Le Resolution Status Audit mesure la répartition globale des statuts resolved, unknown, ambiguous et conflict.

Le Virtual Candidates Dump descend au niveau d'un cas ou d'un petit ensemble de cas pour expliquer le contenu ayant mené à la décision.

Resolution Status Audit = combien et dans quels statuts ?
Virtual Candidates Dump = pourquoi ce cas a-t-il produit ce résultat ?

Entrées¶

Une exécution utile doit identifier :

l'offre, le produit, la Canonical Identity ou l'identifiant ciblé ;
le run ou snapshot ;
la verticale ;
la version des règles ;
les filtres appliqués ;
le périmètre exact du dump.

Le service peut lire, selon l'implémentation :

identifiants normalisés ;
attributs produit et variante ;
candidats ;
scores ou niveaux de confiance ;
reason codes ;
évidences ;
conflits ;
décision finale déjà calculée.

Sorties attendues¶

Pour chaque candidat, le dump devrait exposer autant que possible :

identifiant stable du candidat ;
origine ;
identifiants utilisés ;
attributs comparés ;
évidences positives et négatives ;
score ou confiance si le contrat en prévoit ;
conflits ;
reason codes ;
statut ou résultat de l'évaluation ;
ordre de classement déterministe.

Le dump doit aussi rappeler le résultat global : resolved, unknown, ambiguous ou conflict.

Lecture seule¶

Le Virtual Candidates Dump peut :

lire des données persistées ;
reconstruire en mémoire une représentation de diagnostic ;
trier et sérialiser les candidats ;
produire une sortie humaine ou machine.

Il ne doit jamais :

modifier une Canonical Identity ;
modifier un candidat persisté ;
écrire une projection ;
appeler un Write Service ;
corriger un conflit ;
lancer une synchronisation ;
transformer un dump en recalcul persistant.

Attention au mot « Virtual »¶

Virtual signifie ici que la représentation est produite pour l'observation et le diagnostic.

Cela ne signifie pas que le service peut modifier temporairement la base puis annuler ensuite. Le contrat attendu reste read-only de bout en bout.

Comment diagnostiquer un mauvais résultat¶

Pour un cas mal résolu ou surprenant :

vérifier les données marchandes brutes ;
vérifier les valeurs normalisées ;
vérifier que les candidats attendus existent ;
vérifier qu'aucun candidat inattendu n'a été créé ;
comparer les identifiants forts ;
examiner les conflits et reason codes ;
vérifier le départage déterministe ;
seulement ensuite déterminer si la règle générale ou verticale doit évoluer.

Cette séquence évite de modifier le Resolver lorsque le problème vient de la normalisation ou de la donnée source.

Ce qu'il ne faut pas en déduire¶

Un candidat avec le score le plus élevé n'est pas nécessairement résoluble.

Un conflit bloquant peut légitimement empêcher la décision. De même, plusieurs candidats proches peuvent conduire à ambiguous, et l'absence de preuve exploitable à unknown.

Le dump montre des éléments de décision ; il ne doit pas être utilisé pour forcer manuellement le candidat « qui semble le meilleur » sans respecter le contrat du Resolver.

Reproductibilité¶

À mêmes données et même version de règles, le dump doit présenter :

les mêmes candidats ;
les mêmes reason codes ;
le même classement ;
les mêmes conflits ;
le même statut métier.

L'ordre d'arrivée des feeds ou des lignes SQL ne doit pas modifier le résultat.

Volume et données sensibles¶

Un dump peut devenir volumineux. L'outil doit donc prévoir un périmètre borné et éviter de produire sans nécessité :

des milliers de candidats non filtrés ;
des données inutiles au diagnostic ;
des sorties impossibles à comparer entre deux runs.

Pour un audit global, préférer les services agrégés. Le dump est surtout un outil d'explication détaillée.

Tests attendus¶

Les tests doivent couvrir :

absence d'écriture ;
stabilité du format ;
déterminisme de l'ordre ;
candidat unique ;
plusieurs candidats donnant ambiguous ;
absence de candidat exploitable donnant unknown ;
conflit fort donnant conflict ;
conservation des reason codes et évidences.

Invariants¶

Le dump est read-only.
Le cas et le dataset observés sont identifiés.
Les candidats et leurs raisons restent explicables.
L'ordre est déterministe.
Les quatre statuts canoniques restent visibles.
Le dump n'applique jamais de correction.
Une décision ne doit pas être déduite d'un score seul.