ADR-0004 — Labo d'hypothèses : nœuds en lecture, pas de câblage Blueprint¶


Statut	✅ Accepté — 2026-06-10
Portée	Frontend (Studio DBO et ses extensions), `actuariat_lib` (mode trace), backend
Décision	L'environnement d'expérimentation de l'actuaire est un labo de scénarios (fork/diff/comparaison de jeux d'hypothèses, sensibilités) doublé d'un graphe de calcul explorable en lecture ; le câblage libre de nœuds façon Blueprint (Unreal) est écarté
Réf.	Formalisation v2 du moteur DBO ; oracle K1 ; ADR-0001

🎯 À retenir

Le Labo d'hypothèses = graphe de calcul explorable en lecture (nœuds-explication, jamais un langage de programmation) + gestion de scénarios (fork, diff, calcul en lot, sensibilités). Le câblage libre façon Blueprint est écarté : le pipeline DBO est fixe et certifié CIMA, l'actuaire fait varier les valeurs, pas la topologie. Prérequis : un mode trace dans actuariat_lib (la lib reste pure, la trace est une valeur de retour).

Contexte¶

L'environnement de travail de l'actuaire (expert ou junior) doit être un laboratoire d'expérimentation : générer des jeux d'hypothèses, les tester, en créer des variantes, voir les équations, voir les calculs intermédiaires, et observer des interprétations pour chacun. C'est le besoin exprimé par la Direction au lendemain de la livraison de la persistance (Jalon 2 : JeuHypotheses, Dossier, calcul par sélection dans le Studio).

L'idée initialement proposée : un système de programmation visuelle par nœuds graphiques à relier, dans l'esprit du Blueprint Visual Scripting d'Unreal Engine.

Analyse First Principles du besoin. La programmation visuelle par câblage excelle quand l'utilisateur doit recomposer la topologie du calcul (shaders, synthèse audio, ETL : chaque utilisateur construit un graphe différent). Or le pipeline DBO est fixe et formalisé (formalisation v2, gardé par l'oracle K1) : salaire projeté → IFC → probabilités de présence → actualisation → DBO. L'actuaire ne recâble pas cette chaîne — il fait varier les valeurs qui y entrent (taux, table de mortalité, grille IFC, rotation). Le besoin réel se décompose en deux features, et aucune n'exige du câblage :

Voir / comprendre : équations, intermédiaires, interprétations → visualisation du DAG fixe.
Expérimenter : variantes, comparaisons, sensibilités → gestion de scénarios.

Options considérées¶

A — Labo de scénarios + graphe explorable en lecture : le DAG fixe du moteur est affiché ; cliquer un nœud montre l'équation (LaTeX), les valeurs intermédiaires pour le couple (jeu, dossier) sélectionné, et une interprétation métier. À côté : fork/clonage de jeux, versionnement, diff entre jeux, calcul en lot (1 dossier × N jeux), tables comparatives, tornado de sensibilité.
B — Éditeur de nœuds façon Blueprint : ports typés, câblage libre, validation, exécution et persistance de graphes arbitraires (p. ex. avec React Flow).
C — Rien de visuel : formulaires seuls, comparaison par export.

Comparatif pour / contre¶

Critère	A — Scénarios + lecture	B — Blueprint	C — Formulaires seuls
Couvre « voir équations/calculs/interprétations »	✅ directement	⚠️ possible mais noyé	❌ non
Couvre « générer/tester des variantes »	✅ fork/diff/sensibilités	⚠️ indirectement	⚠️ pauvrement
Degré de liberté offert vs besoin métier	✅ paramètres (le vrai besoin)	❌ topologie (besoin inexistant)	⚠️ paramètres, sans comparaison
Auditabilité / conformité CIMA	✅ méthode fixe, certifiée	❌ graphes arbitraires ≠ méthode prescrite	✅
Coût de construction (équipe d'1 personne)	⚠️ modéré	❌ semaines d'UI, maintenance lourde	✅ quasi nul
Valeur pédagogique (actuaire junior)	✅ DAG + équations + interprétations	⚠️ courbe d'apprentissage de l'outil	❌

Pourquoi B est écarté. (1) Il offre un degré de liberté — recomposer la méthode — qui n'existe pas dans le métier au stade actuel et qui, en contexte CIMA où les méthodes sont prescrites, est même un anti-feature : un graphe librement recâblé peut ne correspondre à aucune méthode certifiée, ruinant l'auditabilité (fil rouge K1). (2) Coût/valeur : l'effort UI d'un éditeur de câblage digne de ce nom absorberait les jalons à venir (Jalon 1, versionnement, MinIO) pour une valeur actuarielle marginale — le risque classique étant que la métaphore visuelle devienne le produit.

Décision¶

Option A. Le Labo d'hypothèses se construit sur deux piliers :

Graphe de calcul explorable (nœuds en lecture). Le DAG fixe du moteur est rendu visuellement ; chaque nœud expose son équation, ses valeurs intermédiaires pour la sélection courante, et une interprétation en langage métier. Les nœuds sont un véhicule d'explication, jamais un langage de programmation.
Gestion de scénarios. Fork d'un jeu d'hypothèses, versionnement (le champ version existe, à activer), diff entre jeux, calcul en lot d'un dossier sous N jeux, table comparative, analyses de sensibilité.

Prérequis moteur : un mode trace dans actuariat_lib — le calcul retourne ses intermédiaires (la lib reste pure : la trace est une valeur de retour, pas un effet de bord). Bénéfice collatéral direct pour l'audit.

Conséquences¶

actuariat_lib s'enrichit d'un mode trace (intermédiaires nommés, alignés sur la formalisation v2) — gardé par K1 comme le reste.
Le Studio évolue vers le labo : la persistance du Jalon 2 (jeux + dossiers) en est la fondation ; fork/diff/lot s'appuient dessus.
Aucune dépendance à un moteur de graphe généraliste n'est introduite ; le rendu du DAG fixe peut être un SVG statique interactif ou un layout maison trivial (topologie connue d'avance).
Doc. La formalisation v2 devient la source des équations affichées (une seule vérité).

Déclencheur de réexamen (pré-enregistré)¶

Si ActuaryLab devient une fabrique de produits où l'expert définit de nouveaux régimes avec des flux de prestations inédits — c'est-à-dire le jour où la topologie du calcul varie réellement d'un produit à l'autre — rouvrir la question de la composition (nœuds contraints à briques certifiées, ou DSL de formules, souvent supérieur). D'ici là, tout besoin d'expérimentation se traite par les paramètres, pas par la méthode.