Simulations¶

Statut¶

Document canonique des simulations read-only de CMonChoix Platform.

Rôle¶

Une simulation évalue un changement sans modifier l'état persistant de la Platform.

Elle répond à une question explicite du type :

Que se passerait-il si cette règle, cette stratégie ou cette configuration était appliquée ?

La simulation est une capacité d'analyse. Elle n'est ni un Pipeline alternatif, ni un mode d'écriture différé.

État observé
    ↓
Simulation en mémoire
    ↓
Résultat hypothétique
    ↓
Comparaison et décision

Position dans le cycle industriel¶

Le cycle attendu est :

Audit
  ↓
Hypothèse
  ↓
Simulation
  ↓
Comparaison des KPI
  ↓
Décision
  ↓
Micro-correctif éventuel
  ↓
Nouvel audit

Une simulation ne justifie pas à elle seule une mise en production. Elle fournit des éléments mesurables pour décider.

Contrat read-only¶

Une simulation peut :

lire les données persistées ;
reconstruire des calculs en mémoire ;
exécuter plusieurs stratégies sur le même échantillon ;
produire des résultats structurés et sérialisables ;
calculer des KPI, écarts et diagnostics.

Elle ne doit jamais :

écrire dans une table métier ou technique ;
modifier une projection ;
vider ou remplacer image_norm ;
lancer une synchronisation ;
appeler un Write Service ;
déclencher un worker ou un cron ;
masquer une mutation derrière une option prétendument read-only.

Le contrat read-only doit être vérifiable par tests, pas seulement annoncé dans l'aide CLI.

Entrées minimales¶

Une simulation reproductible doit identifier au minimum :

la source de données ou le run_id ;
le périmètre, par exemple feed, verticale, marque ou échantillon ;
la stratégie de référence ;
la stratégie simulée ;
les options susceptibles d'influencer le résultat ;
la version ou l'identifiant de la règle évaluée.

Les valeurs implicites qui changent le résultat doivent être évitées.

Sorties attendues¶

Le résultat doit être structuré afin d'être relu par un humain et exploité par un outil.

Il contient idéalement :

le contexte d'exécution ;
le nombre de lignes scannées et éligibles ;
les décisions par catégorie ;
les différences avec la référence ;
les avertissements ;
les échantillons représentatifs ;
les KPI avant et après ;
un statut final explicite.

Les compteurs doivent être réconciliables. Par exemple, les catégories terminales doivent expliquer l'ensemble des lignes éligibles, hors exclusions explicitement comptabilisées.

Familles de simulations¶

Identité¶

Évalue une nouvelle règle de résolution ou de regroupement et expose :

les candidats retenus ou rejetés ;
les changements de statut ;
les conflits créés, supprimés ou déplacés ;
les faux positifs et faux négatifs potentiels.

Projection¶

Calcule une projection hypothétique sans l'écrire.

Le moteur doit produire un modèle comparable à la projection persistée, mais aucun writer ne doit être invoqué.

Qualité¶

Évalue une règle ou une politique de qualité sur un état régénéré et fiable.

Pour Media Quality, le comportement de référence est audit-first :

collecte d'évidences
    ↓
classification
    ↓
score et raisons
    ↓
aucune mutation par défaut

Une simulation Media Quality peut estimer les remplacements potentiels, mais elle ne doit jamais effacer une image ni effectuer automatiquement un remplacement.

Patch virtuel¶

Rejoue virtuellement un micro-correctif sur un périmètre borné afin de mesurer :

le nombre de lignes touchées ;
les gains attendus ;
les régressions ;
les cas encore ambigus ;
les différences de métriques.

Le patch virtuel reste une simulation tant qu'aucune mutation n'est exécutée.

Comparaison de stratégies¶

Exécute plusieurs stratégies sur les mêmes entrées et utilise les mêmes règles de comptage.

Comparer des échantillons, filtres ou versions de données différents produit un résultat invalide, même si les sorties semblent cohérentes.

Reproductibilité¶

À données, configuration et version de code identiques, une simulation doit produire le même résultat fonctionnel.

Les sorties peuvent contenir des métadonnées variables comme la durée, mais les décisions et compteurs métier doivent rester stables.

Pour garantir cette propriété :

trier explicitement les résultats ;
éviter les sélections SQL sans ordre ;
figer les seuils et options dans le rapport ;
enregistrer le run_id ou la version de projection utilisée ;
ne pas dépendre d'un cache non identifié.

Données historiques et état régénéré¶

Une simulation n'est fiable que si son état de départ est fiable.

Lorsqu'une ancienne implémentation a modifié ou vidé une projection, il faut d'abord reconstruire cette projection avant de mesurer la nouvelle politique.

Dans le cas Media Quality, des métriques calculées sur un run historique où image_norm a déjà été nettoyé de manière destructive ne doivent pas servir de référence. La projection doit être régénérée, puis l'audit ou la simulation relancé.

CLI¶

Les commandes de simulation doivent utiliser la forme WP-CLI canonique du projet :

docker compose exec platform-worker wp ...

Une commande CLI reste un adapter mince :

CLI
  ↓
Service applicatif de simulation
  ↓
Read Services / Domain Core
  ↓
Résultat structuré

La CLI gère le parsing, la validation, la délégation, le formatage et le code de sortie. Elle ne contient pas la règle simulée.

Codes de sortie¶

Convention recommandée :

0 : simulation exécutée et résultat valide ;
1 : résultat valide mais seuil de validation non atteint ;
2 ou plus : erreur d'entrée, d'infrastructure ou contrat inexploitable.

Le code de sortie ne doit pas remplacer le rapport détaillé.

Tests attendus¶

Une simulation importante doit être couverte par :

un test garantissant l'absence d'écriture ;
un test de déterminisme ;
un test de réconciliation des compteurs ;
des cas nominaux, ambigus et inconnus ;
un test de stabilité du format structuré ;
un test vérifiant que la CLI délègue au service applicatif.

Pour une simulation de projection ou de qualité, ajouter un test empêchant l'appel accidentel au writer concerné.

Invariants¶

Une simulation est read-only de bout en bout.
Elle ne déclenche aucun writer, worker, cron ou synchronisation.
Les entrées et la stratégie évaluée sont explicites.
Les résultats sont reproductibles et sérialisables.
Les compteurs sont réconciliables.
Une projection historique altérée est régénérée avant comparaison.
Media Quality reste audit-first et non destructif par défaut.
La CLI orchestre la simulation sans porter la logique métier.
Une simulation informe une décision ; elle n'applique jamais la décision.