@micheeeeel/yinyangapp 2.5.0 → 2.6.0

package/dist/types/config/propagationCometConfig.d.ts

@@ -1,41 +1,14 @@
+import type { PropagationCometVizConfig } from "./propagationCometVizConfig";
 /**
- * Réglages (mutables, panneau Debug « Comète de propagation ») de l'animation
- * de propagation : une comète qui parcourt les champs de force de la source
- * jusqu'aux feuilles, avec une queue fondue, un halo doux et des anneaux
- * discrets à chaque satellite atteint. Jouée en boucle sur l'action en focus
- * (YinYangController.flashSourcePropagationTree) et au clic sur une ligne du
- * panneau (flashChildCuttings). Lue à chaque frame : un changement de valeur
- * s'applique à la passe en cours.
+ * Réglages (mutables, panneau Debug « Comète de l'action en focus ») de la
+ * comète rejouée en boucle sur l'action en focus (FocusPropagationLoop).
+ * Même lecteur et mêmes trajets que la comète des listes Source / Bilan
+ * (PropagationCometPlayer, propagationVizModel) ; seuls le rythme et
+ * l'aspect diffèrent : plus calme, et d'une autre couleur pour qu'on ne la
+ * confonde pas avec celle d'un clic.
  */
-export declare const propagationCometConfig: {
-    /** Pause entre deux passes de la boucle de l'action en focus. */
+export declare const propagationCometConfig: PropagationCometVizConfig & {
+    /** Pause entre deux passes de la boucle. */
     loopGapMs: number;
-    /** Vitesse de croisière de la comète le long du chemin (px/s). Le chemin
-     *  entier est joué d'un seul mouvement (accélération/décélération douces
-     *  aux deux bouts, pas d'arrêt aux étapes intermédiaires). */
-    speedPxPerSec: number;
-    /** Durée minimale d'une traversée, pour qu'un chemin très court reste
-     *  lisible. */
-    minTravelMs: number;
-    /** Rayon du noyau de la comète (px). */
-    dotRadius: number;
-    /** Opacité maximale de l'ensemble (noyau, queue, halo). */
-    opacity: number;
-    /** Longueur de la queue, exprimée en temps de trajet (ms) : la queue est
-     *  l'ombre des positions récentes, elle suit donc les virages aux étapes. */
-    tailMs: number;
-    /** Épaisseur de la queue à sa base (px), décroissante vers la pointe. */
-    tailWidth: number;
-    /** Intensité du halo flouté et du glow (0 = aucun, 1 = nominal). */
-    glow: number;
-    /** Fondu d'apparition au départ et d'extinction à l'arrivée (ms). */
-    fadeMs: number;
-    /** Opacité de départ des anneaux à chaque satellite atteint (0 = aucun). */
-    ringOpacity: number;
-    /** true : la comète prend la couleur de l'action (item de la pile) ; false :
-     *  couleur fixe ci-dessous. */
-    useItemColor: boolean;
-    /** Couleur fixe (et couleur de repli quand aucune action n'est identifiable). */
-    color: string;
 };
 export type PropagationCometConfig = typeof propagationCometConfig;

package/dist/types/config/propagationCometVizConfig.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Réglages (mutables, panneau Debug « Comète des listes Source / Bilan ») de
+ * la comète jouée au clic sur une ligne ou un en-tête de liste des cartes
+ * Source et Bilan (PROP-VIZ-01, PropagationCometPlayer). Le rythme (vitesse,
+ * durée minimale d'un saut, rafale) est lu au lancement ; l'aspect à chaque
+ * frame. Indépendants des réglages de la boucle de l'action en focus
+ * (propagationCometConfig.ts).
+ */
+export declare const propagationCometVizConfig: {
+    /** Vitesse de la tête le long des sauts (px/s), constante : les branches
+     *  issues d'un même embranchement repartent ensemble. */
+    speedPxPerSec: number;
+    /** Durée minimale d'un saut, pour qu'un saut très court reste visible. */
+    minHopMs: number;
+    /** Intervalle entre deux départs d'une rafale (clic sur l'en-tête). */
+    burstGapMs: number;
+    /** Rayon du noyau (px). */
+    dotRadius: number;
+    /** Longueur de la queue, en temps de trajet (ms). */
+    tailMs: number;
+    /** Épaisseur de la queue à sa base (px). */
+    tailWidth: number;
+    /** Intensité du halo (0 = aucun). */
+    glow: number;
+    /** Extinction de la tête à l'arrivée sur le dernier satellite (ms). */
+    fadeMs: number;
+    /** Opacité des anneaux à chaque satellite atteint (0 = aucun). */
+    ringOpacity: number;
+    /** true : couleur de l'action du bloc (item de la pile) quand elle existe ;
+     *  false : couleur fixe ci-dessous. */
+    useBlockColor: boolean;
+    color: string;
+};
+export type PropagationCometVizConfig = typeof propagationCometVizConfig;

package/dist/types/data/activeDiagram.d.ts

@@ -1,8 +1,7 @@
 import { type Composante, type Sphere } from "./yasuni_cause";
 import { type ActionDefinition } from "./yasuni_actions";
 import { type KeyEventDefinition } from "./yasuni_key_events";
-import type { CauseGraph } from "../interfaces/ICauseGraph";
-import type { PropagationLayersConfig } from "../interfaces/IPropagationLayers";
+import type { CompiledPropagationGraph } from "../interfaces/IPropagationGraph";
 export declare const YASUNI_DIAGRAM_ID = "yasuni";
 /** Paramètre d'URL qui choisit le diagramme dans la page standalone. */
 export declare const DIAGRAM_URL_PARAM = "diagram";
@@ -19,8 +18,8 @@ export interface DiagramData {
     /** Événements Clés ET adverses, par id. */
     keyEventMap: Map<string, KeyEventDefinition>;
     adverseKeyEvents: KeyEventDefinition[];
-    interconnectionGraph: CauseGraph;
-    propagationLayers: PropagationLayersConfig;
+    /** Graphe unifié de propagation, compilé depuis les satellites. */
+    propagationGraph: CompiledPropagationGraph;
 }
 export interface DiagramOption {
     id: string;
@@ -56,5 +55,4 @@ export declare const activeActions: ActionDefinition[];
 export declare const activeKeyEvents: KeyEventDefinition[];
 export declare const activeKeyEventMap: Map<string, KeyEventDefinition>;
 export declare const activeAdverseKeyEvents: KeyEventDefinition[];
-export declare const activeInterconnectionGraph: CauseGraph;
-export declare const activePropagationLayers: PropagationLayersConfig;
+export declare const activePropagationGraph: CompiledPropagationGraph;

package/dist/types/data/adverse-action-planner.d.ts

@@ -7,6 +7,16 @@ import type { ComboSlot } from "./yasuni_actions";
  * `{ id, delayedEffect: keyEvent }` (elle porte directement
  * targetedActionIds/withinNextN).
  */
+/** Satellite éligible à une menace — la définition de catalogue d'une
+ *  menace générique (adv_gen_*) en déclare plusieurs, une menace spécifique
+ *  (adv_spec_*) un seul ; l'instance insérée n'en garde toujours qu'un. */
+export interface AdverseTarget {
+    componentId: string;
+    oddId: string;
+    cuttingIndex: number;
+}
+/** Identifiant stable d'un satellite cible : composante::odd::index. */
+export declare function adverseTargetId(target: AdverseTarget): string;
 export interface AdverseCandidate {
     id: string;
     combos?: ComboSlot[];
@@ -14,6 +24,11 @@ export interface AdverseCandidate {
         targetedActionIds: string[];
         withinNextN?: number;
     };
+    /** Satellites sur lesquels cette menace peut être insérée. Absent pour un
+     *  Événement adverse (pas de satellite). Une action adverse SANS cible
+     *  éligible (liste vide) n'est jamais sélectionnée : elle ne pourrait
+     *  produire aucun delta direct. */
+    eligibleTargets?: AdverseTarget[];
 }
 export interface PlannerStackItem {
     actionId: string;
@@ -24,6 +39,13 @@ export interface AdversePlacement {
     /** Slot d'insertion au moment où cette insertion est appliquée (les
      *  précédentes du plan étant déjà faites) — pas un slot final. */
     slotIndex: number;
+    /** Cible résolue, choisie parmi `eligibleTargets` au moment de
+     *  l'insertion (tirage déterministe via rng) — une seule par instance,
+     *  donc un seul delta direct. Absente pour un Événement adverse. */
+    target?: AdverseTarget;
+    /** `adverseTargetId(target)` — stocké explicitement pour la
+     *  journalisation et les tests. */
+    targetSatelliteId?: string;
 }
 export interface PlanAdverseInsertionsParams {
     /** Items adverses disponibles (pas encore dans la pile). */

package/dist/types/data/catalogue-coverage.d.ts

@@ -0,0 +1,26 @@
+import type { ActionDefinition } from "./yasuni_actions";
+export interface SatelliteCoverage {
+    componentId: string;
+    componentName: string;
+    oddId: string;
+    cuttingId: number;
+    name: string;
+    protective: string[];
+    adverse: string[];
+    unknown: string[];
+}
+/** Fenêtres temporelles admises (bandes normalisées, voir ComboCondition). */
+export declare const ALLOWED_WINDOWS: readonly [4, 5, 6, 8, 9, 10, 12, 13, 14];
+export declare function buildCoverageMatrix(): SatelliteCoverage[];
+export declare function actionUsage(): Map<string, string[]>;
+/**
+ * Toutes les violations du catalogue, sous forme de messages lisibles —
+ * vide si la configuration est acceptable. Reprend les contrôles de
+ * démarrage de main.ts et y ajoute les règles de l'audit : pas de
+ * satellite orphelin (ni action protectrice ni menace directe), une relation causale par interprétation, aucun
+ * combo réciproque, fenêtres normalisées, identifiants de combo uniques.
+ */
+export declare function catalogueViolations(): string[];
+/** Rendu texte de la matrice, une ligne par satellite. */
+export declare function renderCoverageMatrix(): string;
+export declare function protectiveActions(): ActionDefinition[];

package/dist/types/data/combo-engine.d.ts

@@ -1,4 +1,4 @@
-import type { ActionDefinition } from "./yasuni_actions";
+import type { ActionDefinition, ComboEffect } from "./yasuni_actions";
 /**
  * Intervalles du multiplicateur combo.
  *
@@ -7,22 +7,35 @@ import type { ActionDefinition } from "./yasuni_actions";
  *
  *     m = plancher + (plafond − plancher) × prereqAvgRatio
  *
- * Les deux types partagent la même largeur d'intervalle (1) et se touchent en
- * ×1, le point neutre "rien de spécial ne se passe" :
+ * Tous les intervalles se touchent en ×1, le point neutre "rien de spécial
+ * ne se passe", et chaque famille a sa propre temporalité de jeu :
  *
- *   - bonus     [1, 2] → m = 1 + avgRatio
- *       Les requires sont des DÉCLENCHEURS. Aucun joué → ×1 (neutre, pas de
- *       malus) ; tous parfaits et bien placés → ×2.
- *   - dangereux [0, 1] → m = avgRatio
+ *   - preparation [1, 2] → m = 1 + avgRatio
+ *       Les requires sont des DÉCLENCHEURS. Investir tôt pour ouvrir une
+ *       suite plus forte. Jamais éligible aux chaînes non plafonnées.
+ *   - exploitation [1, 2] → m = 1 + avgRatio
+ *       Choisir le bon moment pour encaisser la valeur accumulée. Seule
+ *       famille pouvant recevoir une performance chaînée supérieure à 1
+ *       (slots marqués uncappedEligible) : m n'a alors plus de plafond.
+ *   - securisation [0, 1] → m = avgRatio
  *       Les requires sont des PROTECTEURS et le risque est permanent
  *       (triggered = true en continu). Protection parfaite → ×1 (risque
  *       annulé) ; aucune protection → ×0 (l'action ne rapporte plus rien).
+ *       Avec le réglage dédié, une surperformance des protecteurs peut
+ *       produire un léger dividende, plafonné à ×1,25.
+ *   - stabilisation → m = 1, toujours
+ *       Les requires sont des DÉCLENCHEURS mais le slot ne multiplie rien :
+ *       déclenché, il crée un BOUCLIER de stabilité persistant sur le
+ *       satellite ciblé (voir stability-shield.ts), appliqué après la
+ *       propagation aux résolutions négatives ultérieures.
  *
- * Largeurs égales de part et d'autre : un bonus et un risque de qualité égale
- * s'annulent exactement dans composeEffectiveDelta, ce qui rend l'arbitrage
- * lisible sans avoir à connaître un barème. Le multiplicateur affiché EST
- * l'avgRatio (au décalage de plancher près) — aucune traduction mentale.
+ * Le multiplicateur affiché reste une lecture directe de l'avgRatio (au
+ * plancher de la famille près) ; composeEffectiveDelta
+ * additionne ensuite les écarts à 1 de chaque slot.
  */
+/** Plafond du multiplicateur d'une sécurisation dont les protecteurs
+ *  surperforment (réglage dangerousComboCanBecomeBonus actif). */
+export declare const SECURISATION_OVERPERFORMANCE_CAP = 1.25;
 /** Détail de la contribution d'un prérequis au multiplicateur combo. */
 export interface PrereqBreakdown {
     id: string;
@@ -35,31 +48,60 @@ export interface PrereqBreakdown {
      *  (ratio/positional = 0 par convention, sans signification réelle) d'un
      *  prérequis réellement joué mais sous-performant. */
     played: boolean;
+    /** Protecteur d'une sécurisation SUPPOSÉ joué (mode RECHERCHE, voir
+     *  EvaluateComboOptions.assumeSecurisationProtected) : ratio, position et
+     *  facteur valent 1 par convention, sans que l'action ait été jouée. */
+    assumed?: boolean;
 }
 /** Réglages "Combos" du panneau de contrôle — voir YinYangControllerState.combos.
  *  Bornés (false) par défaut : comportement actuel. */
 export interface ComboEngineSettings {
-    /** Lève le plafond à 1 sur le ratio des prérequis DÉCLENCHEURS (non
-     *  dangereux), autorisant une cascade de combos à dépasser ×2. */
+    /** Lève le plafond à 1 sur le ratio des prérequis DÉCLENCHEURS — mais
+     *  uniquement pour les slots `exploitation` explicitement marqués
+     *  `uncappedEligible` : ce sont les seules chaînes autorisées à dépasser
+     *  ×2. Les préparations et les stabilisations restent maîtrisées. */
     uncappedChainedPerformance?: boolean;
-    /** Lève le plafond à 1 sur le ratio des prérequis PROTECTEURS d'un combo
-     *  dangereux, permettant à m = avgRatio de dépasser ×1. */
+    /** Lève le plafond à 1 sur le ratio des PROTECTEURS d'une sécurisation,
+     *  permettant à m = avgRatio de dépasser ×1 — jusqu'à
+     *  SECURISATION_OVERPERFORMANCE_CAP. */
     dangerousComboCanBecomeBonus?: boolean;
 }
+/** Options d'évaluation hors réglages du panneau de contrôle. */
+export interface EvaluateComboOptions {
+    /** Mode RECHERCHE : l'action est montrée hors pile, sans historique. Une
+     *  sécurisation y serait toujours à ×0 (aucun protecteur joué) et
+     *  masquerait toute propagation ; on suppose donc ses protecteurs joués
+     *  à leur nominal (m = 1, risque annulé). Les autres familles restent
+     *  évaluées sur l'historique réel. */
+    assumeSecurisationProtected?: boolean;
+}
 export interface ComboResult {
     triggered: boolean;
     name?: string;
     comboId?: string;
     description?: string;
-    type?: string;
+    type?: ComboEffect["type"];
     effectiveDelta: number;
     baseDelta: number;
     deltaMultiplier: number;
     maxDeltaMultiplier: number;
+    /** Exploitation uncappedEligible avec le réglage uncappedChainedPerformance
+     *  actif : la performance chaînée des déclencheurs n'est plus plafonnée à 1,
+     *  m peut dépasser maxDeltaMultiplier — qui n'est alors plus un plafond. */
+    uncapped?: boolean;
     prereqAvgRatio?: number;
     prereqBreakdowns?: PrereqBreakdown[];
     requires?: string[];
     withinLastN?: number;
+    /** Stabilisation déclenchée : points de bouclier créés sur le satellite
+     *  ciblé, actifs jusqu'à la fin de la mission (voir stability-shield.ts). */
+    shield?: number;
+    /** Sécurisation évaluée avec ses protecteurs supposés joués
+     *  (EvaluateComboOptions.assumeSecurisationProtected). */
+    assumedProtected?: boolean;
+    /** Recopie de ComboEffect.backfire : ce slot autorise un retournement
+     *  négatif du multiplicateur composé (voir composeEffectiveDelta). */
+    backfire?: boolean;
 }
 /**
  * Évalue tous les slots combo d'une action et retourne ceux qui sont déclenchés.
@@ -70,23 +112,36 @@ export interface ComboResult {
  * @param prereqRatioMap  (optionnel) actionId → ratio de performance (actualDelta / baseDelta,
  *                        clampé dans [0, 1]). Si fourni, le multiplicateur est pondéré par la
  *                        performance réelle des prérequis :
- *                          effectiveDm = (dangereux ? 0 : 1) + avg(ratio × Beta(t))
+ *                          effectiveDm = plancher + avg(ratio × Beta(t))
  *                        où t est la position normalisée du prérequis dans la fenêtre.
  * @returns               Tableau de ComboResult pour chaque slot (vide si aucun combo défini)
  */
-export declare function evaluateCombo(action: ActionDefinition, playedHistory: string[], prereqRatioMap?: Map<string, number>, settings?: ComboEngineSettings): ComboResult[];
+export declare function evaluateCombo(action: ActionDefinition, playedHistory: string[], prereqRatioMap?: Map<string, number>, settings?: ComboEngineSettings, options?: EvaluateComboOptions): ComboResult[];
 /**
  * Compose le delta effectif à partir de plusieurs résultats combo (formule additive centrée).
  * Chaque multiplicateur exprime un écart par rapport à 1 (neutre).
  *
- * Formule : baseDelta × (Σ multiplicateurs − (n − 1))
+ * Formule : baseDelta × (1 + Σ (mᵢ − 1))
  *
  * Exemples :
  *   - 1 combo ×1.4            → baseDelta × 1.4
- *   - 2 combos ×1.4 + ×-0.5  → baseDelta × (1.4 + (−0.5)) = baseDelta × 0.9
- *   - aucun combo              → baseDelta × 1 = baseDelta
+ *   - 2 combos ×1.4 + ×0.5    → baseDelta × (1 + 0.4 − 0.5) = baseDelta × 0.9
+ *   - bonus parfait ×2 + sécurisation sans protection ×0 → baseDelta × 1
+ *   - aucun combo             → baseDelta × 1 = baseDelta
+ *
+ * Le multiplicateur composé est borné à 0 : une convergence de sécurisations
+ * faibles ne transforme jamais silencieusement une action protectrice en
+ * menace. Seul un slot déclaré `backfire: true` (annoncé au joueur comme un
+ * effet pervers possible) autorise un retournement négatif.
  */
 export declare function composeEffectiveDelta(baseDelta: number, results: ComboResult[]): number;
+/**
+ * Bouclier de stabilité créé par une action à partir de ses résultats combo :
+ * le plus fort de ses slots de stabilisation déclenchés, 0 sinon. Un seul
+ * bouclier par satellite — c'est la projection qui arbitre ensuite entre
+ * plusieurs actions ciblant le même satellite (voir stability-shield.ts).
+ */
+export declare function stabilityShieldFromResults(results: ComboResult[] | undefined): number;
 /**
  * Retourne true si l'action donnée est requise par au moins
  * une autre action dans le catalogue.

package/dist/types/data/contacts/buildContactSphere.d.ts

@@ -6,22 +6,41 @@ export interface ContactSatelliteValue {
     /** Prédominance du trait dans le profil, entier 0–10. */
     weight: number;
 }
-export interface ContactProfile {
+/**
+ * Profil d'un contact tel que l'APPLICATION HÔTE le fournit (yvy-frontend le
+ * lit sur l'API de yvy-backend, seule source des profils) : la lib n'y
+ * ajoute que la grille universelle. Ni rôle ni organisme : le texte présenté
+ * sous le nom est `description`, composé par l'hôte.
+ */
+export interface ContactProfileData {
     /** Identifiant stable, utilisé par le frontend pour sélectionner le graphe. */
     id: string;
     name: string;
-    role: string;
-    organisation: string;
     /** Profil sans identité/biographie définitive : calibration à revoir. */
     provisional?: boolean;
+    /** Présentation du contact (titre au repos, panneau de détails). */
     description?: string;
+    /** Une valeur par satellite de la grille universelle, ni plus ni moins. */
     values: Record<SatelliteKey, ContactSatelliteValue>;
 }
+/** Profil EMBARQUÉ (fixtures `profiles/<id>.ts`, page standalone et
+ *  `getContactCause` dépréciée) : identité complète de la calibration. */
+export interface ContactProfile extends ContactProfileData {
+    role: string;
+    organisation: string;
+}
+/**
+ * Vérifie un profil reçu de l'hôte AVANT de construire sa sphère : une clé
+ * de satellite manquante ou inconnue, un score ou un poids non fini ou hors
+ * bornes lèvent une erreur qui nomme le contact et la clé — jamais de valeur
+ * par défaut silencieuse.
+ */
+export declare function validateContactProfile(profile: ContactProfileData): void;
 /**
  * Le moteur lit `score` comme une tension (affichage = (1 − score) × 100 %) :
  * un satellite de qualité 72 % est donc stocké 0.28.
  */
 export declare function qualityPercentToTension(percent: number): number;
-export declare function buildContactSphere(profile: ContactProfile): Sphere;
+export declare function buildContactSphere(profile: ContactProfileData): Sphere;
 /** Valeurs identiques pour les 38 satellites — gabarit de profil non calibré. */
 export declare function uniformContactValues(score: number, weight: number): Record<SatelliteKey, ContactSatelliteValue>;

package/dist/types/data/contacts/index.d.ts

@@ -1,11 +1,14 @@
 import type { Sphere } from "../yasuni_cause";
-import { type ContactProfile } from "./buildContactSphere";
+import { type ContactProfile, type ContactProfileData } from "./buildContactSphere";
 export declare const contactProfiles: readonly ContactProfile[];
 export declare const CONTACT_IDS: readonly string[];
 export declare function getContactProfile(contactId: string): ContactProfile | undefined;
+/** Le profil embarqué `contactId` au format injectable, présenté comme
+ *  avant 2.6.0 (« rôle — organisme ») ; lève une erreur si l'id est inconnu. */
+export declare function getEmbeddedContactProfileData(contactId: string): ContactProfileData;
 /** Sphere fraîchement construite du contact ; lève une erreur si l'id est inconnu. */
 export declare function getContactSphere(contactId: string): Sphere;
-export { buildContactSphere, qualityPercentToTension } from "./buildContactSphere";
-export type { ContactProfile, ContactSatelliteValue } from "./buildContactSphere";
+export { buildContactSphere, qualityPercentToTension, validateContactProfile, } from "./buildContactSphere";
+export type { ContactProfile, ContactProfileData, ContactSatelliteValue, } from "./buildContactSphere";
 export { UNIVERSAL_FACETS, CONTACT_CATEGORIES } from "./universalFacets";
 export type { SatelliteKey, ContactFacetId, ContactCategoryId } from "./universalFacets";

package/dist/types/data/propagation-graph.d.ts

@@ -0,0 +1,16 @@
+import { type CompiledEdge, type CompiledPropagationGraph, type PropagationGraphDiagnostic, type SatelliteKey } from "../interfaces/IPropagationGraph";
+import { type Composante } from "./yasuni_cause";
+/** Gain maximal d'un saut hors poids : absorption 1,2 × gap 1,2
+ *  (absorptionMultiplier / gapMultiplier de utils/actionPropagation.ts). */
+export declare const MAX_HOP_GAIN = 1.44;
+/** Cycles élémentaires du graphe (sources ordonnées, chaque cycle énuméré
+ *  une seule fois depuis son plus petit nœud). Taille du catalogue : quelques
+ *  dizaines de satellites, énumération directe. Utilisé par V7 et par
+ *  l'audit d'équilibrage (scripts/propagation-cycles-audit.ts). */
+export declare function elementaryCycles(outgoing: ReadonlyMap<SatelliteKey, readonly CompiledEdge[]>): CompiledEdge[][];
+export declare function compilePropagationGraph(cause: Composante[]): CompiledPropagationGraph;
+export declare function formatPropagationGraphDiagnostics(diagnostics: readonly PropagationGraphDiagnostic[]): string;
+/** Graphe du catalogue Yasuní. Les diagnostics sont signalés sans bloquer le
+ *  démarrage : les arêtes en erreur sont déjà exclues ; un test exige zéro
+ *  diagnostic sur le catalogue. */
+export declare const yasuniPropagationGraph: CompiledPropagationGraph;

package/dist/types/data/stability-shield.d.ts

@@ -0,0 +1,21 @@
+/** Coefficient de conversion du delta de l'action en points de bouclier. */
+export declare const STABILITY_SHIELD_FACTOR = 0.5;
+/**
+ * Valeur du bouclier créé par une stabilisation déclenchée :
+ *     bouclier = max(1, arrondi(baseDelta × r × 0,5))
+ * où r est la performance moyenne des prérequis, plafonnée à 1. Un
+ * baseDelta négatif ou nul (action adverse, action sans effet) ne crée
+ * jamais de bouclier — une menace ne protège pas.
+ */
+export declare function computeStabilityShield(baseDelta: number, prereqAvgRatio: number): number;
+/**
+ * Réduction unique d'un total négatif par le bouclier. Un total positif
+ * ou nul est rendu tel quel ; un total négatif remonte d'au plus
+ * `shield` points, borné à 0 (jamais transformé en bonus).
+ */
+export declare function applyStabilityShield(aggregatedDelta: number, shield: number): number;
+/**
+ * Un seul bouclier par satellite : le plus fort remplace le précédent, un
+ * bouclier plus faible ne dégrade jamais celui déjà en place.
+ */
+export declare function mergeStabilityShield(current: number | undefined, incoming: number): number;

package/dist/types/data/yasuni_actions.d.ts

@@ -1,18 +1,51 @@
 export interface ComboCondition {
     requires?: string[];
+    /**
+     * Fenêtre temporelle (undefined = session entière). Bandes normalisées :
+     *   4 à 6   → enchaînement opérationnel immédiat ;
+     *   8 à 10  → préparation tactique ou institutionnelle ;
+     *   12 à 14 → transformation structurelle longue, réservée aux chaînes majeures.
+     */
     withinLastN?: number;
 }
+/**
+ * Une relation causale = une seule interprétation. Si le prérequis
+ * conditionne la réussite de l'action courante, la relation est une
+ * `securisation` ; s'il consolide un gain obtenu contre une menace future,
+ * c'est une `stabilisation`. Une même relation ne figure jamais dans les
+ * deux familles, ni dans les deux sens chronologiques : c'est la seconde
+ * action, celle qui complète réellement la séquence, qui porte le combo.
+ */
 export interface ComboEffect {
     /**
-     * Seul `type` décide de l'amplitude : "dangereux" parcourt [0, 1] (les
-     * requires sont des protecteurs), les autres [1, 2] (les requires sont des
-     * déclencheurs). Le curseur dans l'intervalle est la performance réelle des
-     * prérequis — voir combo-engine.ts. Pas de palier à choisir au cas par cas.
+     * Seul `type` décide de l'amplitude — voir combo-engine.ts :
+     *   - "preparation" / "exploitation" : [1, 2], les requires sont des
+     *     déclencheurs ;
+     *   - "securisation" : [0, 1], les requires sont des protecteurs évalués
+     *     en continu (l'action conserve de 0 à 100 % de son effet) ;
+     *   - "stabilisation" : ×1, et un bouclier persistant sur le satellite
+     *     ciblé (voir stability-shield.ts) à la place du multiplicateur.
+     * Le curseur dans l'intervalle est la performance réelle des prérequis.
+     * Pas de palier à choisir au cas par cas.
      */
-    type: "preparation" | "exploitation" | "stabilisation" | "dangereux";
+    type: "preparation" | "exploitation" | "stabilisation" | "securisation";
     name: string;
     comboId: string;
     description: string;
+    /**
+     * Autorise ce slot à retourner le multiplicateur composé en négatif
+     * (effet pervers annoncé au joueur). Par défaut le composé est borné à 0 :
+     * une convergence de sécurisations faibles ne transforme jamais une action
+     * protectrice en menace.
+     */
+    backfire?: boolean;
+    /**
+     * Exploitation explicitement éligible aux performances chaînées non
+     * plafonnées (réglage uncappedChainedPerformance) : seuls ces slots
+     * transmettent un ratio de prérequis supérieur à 1. Sans effet sur les
+     * autres types.
+     */
+    uncappedEligible?: boolean;
 }
 export interface ComboSlot {
     condition: ComboCondition;

package/dist/types/data/yasuni_cause.d.ts

@@ -1,3 +1,4 @@
+import type { PropagationTarget } from "../interfaces/IPropagationGraph";
 export interface Cutting {
     id: number;
     name: string;
@@ -7,6 +8,12 @@ export interface Cutting {
     /** Présentation succincte du problème ou enjeu représenté par ce cutting. */
     description?: string;
     actionIds: string[];
+    /**
+     * PROP-GRAPH — sorties pondérées de ce satellite vers d'autres satellites,
+     * quelle que soit leur portée (même ODD, autre ODD, autre facette). Absent
+     * = feuille. Compilées et validées par data/propagation-graph.ts.
+     */
+    propagationTargets?: PropagationTarget[];
 }
 export interface ODD {
     id: string;

package/dist/types/data/yasuni_key_events.d.ts

@@ -1,7 +1,8 @@
 export interface KeyEventEffect {
     /**
-     * Bonus ADDITIF de score (en points), au pic de la fenêtre positionnelle —
-     * réduit vers 0 aux bords, voir positionalBonus (amplifier-engine.ts).
+     * Bonus additif nominal au pic de la fenêtre. Pour un slot occupé éligible,
+     * pondération positionnelle avec plancher 0,15 ; aucun effet si la cible est
+     * absente ou hors fenêtre. Voir positionalBonus (amplifier-engine.ts).
      * Appliqué dans la direction du delta effectif de l'action (après combos),
      * jamais sur une action au delta nul. Additif et non multiplicatif : un
      * ratio réduit par la position devenait fractionnaire et se faisait

package/dist/types/interfaces/IPropagationGraph.d.ts

@@ -0,0 +1,39 @@
+/** Référence complète d'un satellite du catalogue. */
+export type SatelliteRef = {
+    componentId: string;
+    oddId: string;
+    cuttingId: number;
+};
+/** Clé canonique `componentId::oddId::cuttingId`, seule clé de résolution. */
+export type SatelliteKey = string;
+export declare function satelliteRefKey(ref: SatelliteRef): SatelliteKey;
+/** Sortie pondérée d'un satellite. */
+export interface PropagationTarget {
+    /** Destination complète, toujours explicite : pas de composante implicite. */
+    to: SatelliteRef;
+    /** Influence signée, finie, 0 < |w| ≤ 1. Propre à l'arête, jamais héritée
+     *  du nœud cible. */
+    w: number;
+    rationale: string;
+}
+/** Portée dérivée de from/to, pour l'affichage seulement — jamais stockée,
+ *  jamais lue par le calcul. */
+export type PropagationScope = "local" | "inter-odd" | "inter-facette";
+export type CompiledEdge = PropagationTarget & {
+    from: SatelliteRef;
+    scope: PropagationScope;
+};
+export type PropagationGraphRule = "V1" | "V2" | "V3" | "V4" | "V5" | "V6" | "V7";
+export type PropagationGraphDiagnostic = {
+    severity: "error" | "warning";
+    rule: PropagationGraphRule;
+    from: SatelliteKey;
+    to?: SatelliteKey;
+    message: string;
+};
+export type CompiledPropagationGraph = {
+    /** Sorties valides par satellite source. Une arête en erreur n'y figure
+     *  pas : aucune contribution, aucun repli, aucune redirection. */
+    outgoing: ReadonlyMap<SatelliteKey, readonly CompiledEdge[]>;
+    diagnostics: readonly PropagationGraphDiagnostic[];
+};

package/dist/types/interfaces/IYinYangController.d.ts

@@ -70,12 +70,12 @@ export interface IYinYangController {
     setChildrenContextLabelsVisible(isVisible: boolean): void;
     /**
      * Lève le plafond à 1 sur le ratio de performance des prérequis
-     * déclencheurs (combos non dangereux), autorisant une cascade de combos à
+     * déclencheurs (exploitations éligibles), autorisant une cascade de combos à
      * dépasser ×2.
      */
     setComboUncappedChainedPerformance(isEnabled: boolean): void;
     /**
-     * Permet à un combo dangereux de devenir un bonus net : lève le plafond à
+     * Permet à un sécurisation de devenir un bonus net : lève le plafond à
      * 1 sur le ratio de performance des prérequis protecteurs, autorisant
      * m = avgRatio à dépasser ×1.
      */