Aller au contenu

Dump

Status: CONTRACT

À quoi sert un Dump Read Service ?

Un Dump est un Read Service qui expose un état interne de CMonChoix sous une forme structurée et lisible, sans modifier cet état.

Il sert surtout au diagnostic : voir ce que le système connaît réellement à un instant donné, avant d'interpréter un comportement ou de préparer un correctif.

Exemples de données qu'un dump peut exposer :

  • candidats construits pour une identité ;
  • identifiants observés ou normalisés ;
  • reason codes ;
  • états resolved, unknown, ambiguous ou conflict ;
  • données intermédiaires nécessaires à un audit ;
  • structures virtuelles produites par une simulation.
État interne
    ↓
Dump Read Service
    ↓
Structure sérialisable
    ↓
CLI / fichier / inspection humaine

Pourquoi ce composant existe

Un dump évite de diagnostiquer un problème uniquement à partir d'un écran Frontend, d'un log partiel ou d'une valeur finale.

Il rend visibles les données utilisées par les couches métier sans introduire de mutation.

Cette séparation est importante : observer précisément un état ne doit jamais déclencher sa correction.

Place dans l'architecture

Dans CMonChoix, un dump se situe du côté lecture :

Sources / Domain Core / projections
              ↓
          Read Service
              ↓
             Dump
              ↓
      Adapter CLI ou rapport

Le service produit la donnée. La CLI ne fait que recevoir les paramètres, appeler le service et formater le résultat.

Ce qu'un dump peut lire

Selon son contrat, un dump peut lire :

  • des projections persistées ;
  • des données normalisées ;
  • des candidats calculés ;
  • des résultats de Resolver ;
  • des structures issues d'une simulation ;
  • des métadonnées de run ou de feed nécessaires au contexte.

Le périmètre doit être borné par des identifiants ou des filtres explicites.

Ce qu'un dump ne doit jamais faire

Un Dump Read Service ne doit jamais :

  • écrire en base ;
  • corriger une identité ;
  • modifier une projection ;
  • appeler un Write Service ;
  • déclencher une synchronisation ;
  • modifier un feed ;
  • masquer ou transformer un conflit pour rendre la sortie plus lisible ;
  • charger des dépendances inutiles simplement pour afficher le résultat.

Le fait qu'un dump soit utilisé avant une correction ne lui donne aucun droit d'écriture.

Sortie attendue

La sortie doit être suffisamment stable pour être comparée ou archivée.

Elle devrait inclure selon le cas :

  • le type de dump ;
  • la version du format ;
  • le run ou snapshot observé ;
  • les filtres appliqués ;
  • les identifiants stables ;
  • les valeurs observées ;
  • les valeurs normalisées ou dérivées ;
  • les reason codes ;
  • les statuts ;
  • les warnings ;
  • les métadonnées utiles au diagnostic.

Une sortie JSON est particulièrement utile pour automatiser les comparaisons, mais le format d'affichage ne doit pas modifier le calcul.

Dump réel et dump virtuel

Il faut distinguer deux familles.

Dump d'état réel

Il expose ce qui existe réellement dans les données ou projections observées.

Dump virtuel

Il expose le résultat calculé en mémoire par une simulation ou une construction non persistée.

Un dump virtuel ne doit jamais être présenté comme la preuve qu'une écriture a été appliquée.

état réel → dump réel
simulation → dump virtuel

Quand l'utiliser

Un dump est utile lorsque l'on veut :

  • comprendre pourquoi un Resolver retourne un certain statut ;
  • inspecter les candidats avant une comparaison ;
  • vérifier les données réellement disponibles pour une règle ;
  • comparer une structure avant/après une évolution ;
  • produire un exemple reproductible pour un bug ;
  • confirmer qu'une valeur est absente plutôt que seulement non affichée par le Frontend.

Ce qu'il ne faut pas en déduire

Un dump montre un état ou un calcul à un instant donné. Il ne prouve pas à lui seul :

  • que le Pipeline est globalement sain ;
  • qu'une projection est à jour ;
  • qu'une règle est correcte ;
  • que tous les feeds présentent le même comportement ;
  • qu'une mutation a été exécutée ;
  • qu'un problème est situé dans la couche affichée.

Il faut replacer le dump dans son run, son snapshot, sa version de code et son périmètre.

Diagnostic

Si un dump paraît incohérent, vérifier :

  1. le bon run ou snapshot est-il interrogé ?
  2. les filtres sont-ils ceux attendus ?
  3. le dump montre-t-il un état réel ou virtuel ?
  4. la projection observée est-elle à jour ?
  5. les statuts d'incertitude sont-ils conservés ?
  6. la CLI formate-t-elle seulement la sortie, sans refaire le calcul ?

Gouvernance documentaire

La séparation documentaire est la suivante :

  • docs/read-services/* explique le concept et ses invariants ;
  • docs/cli/* documente les commandes réellement exposées.

Les pages CLI doivent donc être consultées pour les syntaxes exactes et les options disponibles.

Pages CLI associées

Pour l'usage pratique, poursuivre avec :

  • docs/cli/candidate-dump.md ;
  • docs/cli/virtual-candidates-dump.md.

Les commandes ne doivent être considérées comme disponibles que si leur présence est vérifiée dans le runtime ou le code actuel.

Tests attendus

Un Dump Read Service important doit vérifier :

  • l'absence d'écriture ;
  • la stabilité du format structuré ;
  • la présence des identifiants nécessaires au diagnostic ;
  • la conservation des statuts unknown, ambiguous et conflict ;
  • le déterminisme de l'ordre de sortie ;
  • la séparation entre calcul du service et formatage CLI.

Invariants

  1. Un dump est read-only.
  2. Il expose un état sans le corriger.
  3. Son périmètre et son contexte sont identifiables.
  4. Les statuts d'incertitude ne sont pas masqués.
  5. Un dump virtuel n'est pas une preuve de persistance.
  6. La CLI ne porte pas la logique métier du dump.
  7. Le format doit rester suffisamment stable pour le diagnostic et la comparaison.

Voir aussi