@micheeeeel/yinyangapp 2.5.0 → 2.6.0

package/dist/types/utils/actionPropagation.d.ts

@@ -1,6 +1,5 @@
-import { CauseGraph } from "../interfaces/ICauseGraph";
+import { type CompiledPropagationGraph, type PropagationScope, type SatelliteKey } from "../interfaces/IPropagationGraph";
 import { YinYangComponentNode } from "../interfaces/IYinYangInternalModel";
-import { LocalCuttingEdge, PropagationLayersConfig } from "../interfaces/IPropagationLayers";
 export type Action = {
     id: string;
     name: string;
@@ -9,25 +8,39 @@ export type Action = {
     category: string;
     cost: number;
 };
+/**
+ * Saut de propagation appliqué : une arrivée sur un satellite, le long d'une
+ * arête du graphe unifié (PROP-GRAPH). Toutes les portées — même ODD, autre
+ * ODD, autre facette — sont produites par le même parcours.
+ */
 export type PropagatedActionEdge = {
-    layerType: "inter" | "intra" | "bridge";
+    scope: PropagationScope;
     fromComponentId: string;
     toComponentId: string;
     fromOddId: string;
     toOddId: string;
-    fromCuttingId?: number;
-    toCuttingId?: number;
+    fromCuttingId: number;
+    toCuttingId: number;
     weight: number;
     deltaTo: number;
+    /** Budget porté par l'arrivée précédente (le delta direct pour une sortie
+     *  de la cible directe). */
     baseDelta: number;
-    propagationFactor: number;
+    /** État de la cible directe dans l'instantané : référence du gap (D4). */
     fromState: number;
     toState: number;
     absorption: number;
     gap: number;
     rationale?: string;
-    /** Entry-point cutting carried from the inter-ODD graph edge (used by Phase 6+7). */
-    targetedCutting?: number;
+    /** Index, dans la liste d'arêtes de la résolution, de l'arrivée qui a porté
+     *  le budget de ce saut. Absent pour une sortie du point de départ. Interne
+     *  à une résolution : l'affichage travaille sur des identifiants stables
+     *  (voir controller/force-field/edgeIdentity.ts). */
+    parentEdgeIndex?: number;
+    /** Chemin causal de l'arrivée : satellites traversés depuis le point de
+     *  départ de la résolution, satellite d'arrivée compris. Aucun satellite
+     *  n'y figure deux fois (guard par chemin, PROP-GRAPH-01 révisé). */
+    path: readonly SatelliteKey[];
 };
 export type ProjectedActionStateDetails = {
     oddStates: Record<string, number>;
@@ -36,39 +49,98 @@ export type ProjectedActionStateDetails = {
 type CuttingStateMap = Record<string, Record<number, number>>;
 export declare function clampState(state: number): number;
 export declare function tensionFromState(state: number): number;
+/**
+ * Seuil, en points d'état (échelle 0-100), sous lequel un saut de
+ * propagation n'est ni appliqué ni poursuivi. Il arrête les cascades
+ * atténuées (les cycles, eux, sont coupés par le guard par chemin) et ne
+ * s'applique jamais au delta direct de l'action.
+ *
+ * Calibrage sur le catalogue Yasuní (137 résolutions, 372 sauts locaux) :
+ * le plus petit premier saut vaut 0,45 (delta 2 × w 0,45 × abs 0,5) et le
+ * plus petit deuxième saut 0,21 ; un dixième de point est donc sous tout
+ * saut porteur de sens, et sous la résolution d'affichage (états entiers).
+ * À ce seuil, 17 % des sauts du catalogue sont coupés, tous des queues de
+ * chaîne inférieures à 0,1 point.
+ */
+export declare const MIN_PROPAGATED_DELTA = 0.1;
+/**
+ * Nombre maximal de sauts évalués par résolution (PROP-GRAPH-01, D9). Le
+ * guard par chemin interdit déjà tout cycle : cette borne n'est qu'un filet
+ * contre l'explosion combinatoire d'un graphe très branché. Elle interrompt
+ * le parcours et le signale (voir PropagationTruncation). Une résolution du
+ * catalogue évalue au plus quelques dizaines de sauts.
+ */
+export declare const MAX_HOPS_PER_RESOLUTION = 1000;
+/** Vrai si le saut doit être appliqué et poursuivi : |delta| ≥ seuil, même
+ *  règle pour les deux signes ; un delta nul ou NaN est arrêté. Testé avant
+ *  tout arrondi d'affichage. */
+export declare function isSignificantPropagatedDelta(delta: number): boolean;
+/**
+ * Résolution interrompue par MAX_HOPS_PER_RESOLUTION. Son résultat est alors
+ * partiel : les appelants ne doivent pas le présenter comme complet. Émis
+ * aussi en console.warn.
+ */
+export type PropagationTruncation = {
+    /** Satellite de départ du parcours, `componentId::oddId::cuttingId`. */
+    sourceKey: string;
+    /** Sauts évalués avant l'arrêt (significatifs ou non). */
+    hopsProcessed: number;
+    /** Sauts encore en file, jamais évalués. */
+    hopsPending: number;
+    limit: number;
+};
 export declare function absorptionMultiplier(state: number): number;
 export declare function gapMultiplier(sourceState: number, targetState: number): number;
 export declare function absorptionRuleExplanation(state: number): string;
 export declare function gapRuleExplanation(sourceState: number, targetState: number): string;
 export declare function deriveOddStates(component: YinYangComponentNode): Record<string, number>;
 export declare function deriveCuttingStates(component: YinYangComponentNode): CuttingStateMap;
-/** Find a node in the intra-ODD flat array by toCuttingId (to start AT it). */
-export declare function findNodeInTree(edges: LocalCuttingEdge[], targetId: number): LocalCuttingEdge | null;
-export declare function propagateActionInComponent(component: YinYangComponentNode, graph: CauseGraph, sourceOddId: string, delta: number, k: number): PropagatedActionEdge[];
 export type ActionPropagationDetails = ProjectedActionStateDetails & {
+    /** Sauts appliqués, toutes composantes confondues, dans l'ordre du
+     *  parcours. */
+    edges: PropagatedActionEdge[];
+    /** Résolution interrompue par la garde technique (vide si complète). */
+    truncations: PropagationTruncation[];
+};
+/**
+ * Résolution d'une action : delta direct sur sa cible, puis parcours unique
+ * du graphe unifié (contrat PROP-GRAPH-01 §6).
+ *
+ * Les états retournés sont ceux de `component` (la facette jouée) : les
+ * arêtes vers d'autres facettes sont parcourues et retournées dans `edges`,
+ * mais leurs deltas ne modifient pas l'état de ces facettes (D7).
+ * `allComponents` fournit l'état de base des autres facettes ; sans lui, les
+ * sauts qui sortent de `component` sont ignorés.
+ */
+export declare function computeActionPropagationDetails(component: YinYangComponentNode, graph: CompiledPropagationGraph, sourceOddId: string, sourceCuttingId: number | undefined, delta: number, allComponents?: readonly YinYangComponentNode[]): ActionPropagationDetails;
+/**
+ * Arrivée dans `component` d'une arête venue d'une autre composante, déjà
+ * calculée par la résolution de l'action (voir computeActionPropagationDetails).
+ */
+export type IncomingPropagationEntry = Pick<PropagatedActionEdge, "toOddId" | "deltaTo" | "fromState"> & {
+    toCuttingId?: number;
+    /** Chemin causal de l'arrivée (voir PropagatedActionEdge.path). Absent : le
+     *  chemin se réduit au satellite d'arrivée. */
+    path?: readonly SatelliteKey[];
+};
+export type IncomingLocalContinuation = {
+    /** Sauts dans la composante cible, dans l'ordre du parcours. L'arrivée
+     *  elle-même n'y figure pas : c'est l'arête entrante. */
     edges: PropagatedActionEdge[];
+    truncations: PropagationTruncation[];
 };
 /**
- * Canonical single-pass propagation: runs the 8 phases once and returns both
- * the collected edges AND the final states. propagateForceFieldActionInComponent
- * and projectActionStateDetailsInComponent below are thin wrappers over this —
- * having them as two independently-maintained twins previously let the
- * state-only path silently drift from the edge path: it never passed
- * `allComponents` into the Phase 5 inter-ODD call (so cross-component edges
- * were absent from its internal `interEdges` — with real data this happened
- * to have no effect on the RETURNED states, since Phase 6/7 already only
- * ever applies same-component budgets, but it meant edges/rationale for ~150
- * real cross-component synergies were unavailable to any caller built on top
- * of the state-only path), and it never threaded the Phase 6/7 "global mode"
- * tracking (`targetedOddsWithGlobalMode`) that the edge path has — inert with
- * today's graph/layers data (no same-component edge without a targetedCutting
- * currently targets an ODD that has its own intra chain) but a silent
- * divergence waiting for the next graph data change. One implementation
- * makes both classes of bug structurally impossible instead of just
- * currently-inert.
+ * Suite, dans la composante cible, d'une arête venue d'une autre composante.
+ * Même parcours que la résolution complète, repris depuis le satellite
+ * d'arrivée avec son delta pour budget, la même référence de gap (`fromState`
+ * de l'arrivée, l'état de la cible directe) et l'état de base de la cible ;
+ * il s'arrête au bord de la composante, et le guard part du chemin de
+ * l'arrivée. Le résultat coïncide donc avec les
+ * sauts que la résolution complète produit dans cette composante à la suite
+ * de cette arrivée. Le graphe ne dépend pas de la portée : une arête vers un
+ * autre ODD de la même composante est poursuivie comme une arête locale.
  */
-export declare function computeActionPropagationDetails(component: YinYangComponentNode, graph: CauseGraph, sourceOddId: string, sourceCuttingId: number | undefined, delta: number, k: number, layers?: PropagationLayersConfig, allComponents?: YinYangComponentNode[]): ActionPropagationDetails;
-export declare function propagateForceFieldActionInComponent(component: YinYangComponentNode, graph: CauseGraph, sourceOddId: string, sourceCuttingId: number | undefined, delta: number, k: number, layers?: PropagationLayersConfig, allComponents?: YinYangComponentNode[]): PropagatedActionEdge[];
-export declare function projectActionStateDetailsInComponent(component: YinYangComponentNode, graph: CauseGraph, sourceOddId: string, sourceCuttingId: number | undefined, delta: number, k: number, layers?: PropagationLayersConfig, allComponents?: YinYangComponentNode[]): ProjectedActionStateDetails;
-export declare function projectActionStatesInComponent(component: YinYangComponentNode, graph: CauseGraph, sourceOddId: string, sourceCuttingId: number | undefined, delta: number, k: number, layers?: PropagationLayersConfig, allComponents?: YinYangComponentNode[]): Record<string, number>;
+export declare function computeIncomingLocalContinuation(component: YinYangComponentNode, entry: IncomingPropagationEntry, graph: CompiledPropagationGraph): IncomingLocalContinuation;
+export declare function propagateForceFieldActionInComponent(component: YinYangComponentNode, graph: CompiledPropagationGraph, sourceOddId: string, sourceCuttingId: number | undefined, delta: number, allComponents?: readonly YinYangComponentNode[]): PropagatedActionEdge[];
+export declare function projectActionStateDetailsInComponent(component: YinYangComponentNode, graph: CompiledPropagationGraph, sourceOddId: string, sourceCuttingId: number | undefined, delta: number, allComponents?: readonly YinYangComponentNode[]): ProjectedActionStateDetails;
 export {};

package/dist/types/utils/adverseMode.d.ts

@@ -0,0 +1,14 @@
+import { type ActionDefinition } from "../data/yasuni_actions";
+import { type KeyEventDefinition } from "../data/yasuni_key_events";
+export declare function isAdverseModeActive(): boolean;
+export declare function setAdverseModeActive(active: boolean): void;
+/** Abonnement aux bascules du mode ; renvoie la fonction de désabonnement. */
+export declare function onAdverseModeChange(listener: (active: boolean) => void): () => void;
+/** L'action a-t-elle une surface (bulle, ligne d'arbre) dans le mode courant ? */
+export declare function isActionShownInMode(action: ActionDefinition): boolean;
+/** L'événement a-t-il une surface (bulle du cœur, ligne d'arbre) dans le
+ *  mode courant ? */
+export declare function isKeyEventShownInMode(keyEvent: KeyEventDefinition): boolean;
+/** Catalogue des événements montrés dans le mode courant : Événements Clés
+ *  ordinaires, ou Événements adverses en mode adverse. */
+export declare function keyEventsForMode(): KeyEventDefinition[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@micheeeeel/yinyangapp",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "A program to visualize human activity balance to reach Sustainable Development Objectives",
   "main": "dist/bundle.js",
   "types": "dist/types/main.d.ts",
@@ -12,7 +12,9 @@
     "check:file-lines": "node scripts/check-file-lines.mjs",
     "ci:guard": "npm run check:file-lines",
     "analyze": "ANALYZE=true webpack --mode production && tsc -p tsconfig.types.json",
-    "benchmark:compare": "node benchmarks/compare.js"
+    "benchmark:compare": "node benchmarks/compare.js",
+    "catalogue:matrix": "npx tsx scripts/catalogue-matrix.ts",
+    "propagation:cycles-audit": "npx tsx scripts/propagation-cycles-audit.ts"
   },
   "author": "Thomas MICHEL",
   "license": "UNLICENSED",

package/dist/types/components/controller/utils/forceFieldMetadata.d.ts

@@ -1,4 +0,0 @@
-export declare function getInterOddRationale(componentId: string, fromOddId: string, toOddId: string): string | null;
-export declare function getLayersInvolved(componentId: string, fromOddId: string, toOddId: string): string[];
-export declare function getLocalLayerWeightSummary(componentId: string, fromOddId: string, toOddId: string): string | null;
-export declare function getBridgeLayerWeightSummary(componentId: string, fromOddId: string, toOddId: string): string | null;

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

@@ -1,22 +0,0 @@
-import { CauseGraph } from "../interfaces/ICauseGraph";
-/**
- * Yasuní sparse interconnection matrix W (adjacency list form) — SIGNED.
- *
- * Node format: componentId::oddId (contextualized SDG node).
- * w in [-1..+1], expert-driven bands (absolute value):
- * - 0.2 weak
- * - 0.4 moderate
- * - 0.6 strong
- * - 0.8 structuring
- *
- * Sign convention:
- * - w > 0 : A↑ causes B↑ (same direction)
- * - w < 0 : A↑ causes B↓ (opposite direction)
- *
- * NOTE: This file intentionally includes a few additional contextualized nodes (e.g.,
- * biodiversity_habitat_fragmentation::ODD_2, indigenous_rights::ODD_3/4/11) to show that
- * the node count is not constrained to 17. If your engine builds node state strictly from
- * yasuni_cause.ts, add these nodes there (or have the engine lazily init missing nodes).
- */
-export declare const yasuniInterconnectionGraph: CauseGraph;
-export default yasuniInterconnectionGraph;

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

@@ -1,3 +0,0 @@
-import { PropagationLayersConfig } from "../interfaces/IPropagationLayers";
-export declare const yasuniPropagationLayers: PropagationLayersConfig;
-export default yasuniPropagationLayers;

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

@@ -1,9 +0,0 @@
-export type CauseNodeId = `${string}::${string}`;
-export interface CauseEdge {
-    to: CauseNodeId;
-    w: number;
-    rationale?: string;
-    /** Entry-point cutting in the target ODD's intra chain (Phase 6+7 / incoming-mode entry). */
-    targetedCutting?: number;
-}
-export type CauseGraph = Record<CauseNodeId, CauseEdge[]>;

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

@@ -1,27 +0,0 @@
-export interface LocalCuttingEdgeRef {
-    cuttingId: number;
-    rationale?: string;
-}
-export interface LocalCuttingEdge {
-    toCuttingId: number;
-    w: number;
-    rationale?: string;
-    /** Pointers to next cuttings in the causal chain — resolved from the same flat array. */
-    targetedCuttings?: LocalCuttingEdgeRef[];
-}
-export interface BridgeCuttingEdge {
-    fromComponentId?: string;
-    fromOddId: string;
-    fromCuttingId: number;
-    toComponentId?: string;
-    toOddId: string;
-    toCuttingId: number;
-    w: number;
-    rationale?: string;
-}
-export interface PropagationLayersConfig {
-    intraOddByComponent: Record<string, Record<string, LocalCuttingEdge[]>>;
-    bridgeEdgesByComponent: Record<string, BridgeCuttingEdge[]>;
-    localK?: number;
-    bridgeK?: number;
-}

package/dist/types/utils/causeGraph.d.ts

@@ -1,6 +0,0 @@
-import { Cause } from "../interfaces/ICauseModel";
-import { CauseGraph, CauseNodeId } from "../interfaces/ICauseGraph";
-export declare function makeCauseNodeId(componentId: string, oddId: string): CauseNodeId;
-export declare function listCauseNodeIds(cause: Cause): CauseNodeId[];
-export declare function validateCauseGraph(cause: Cause, graph: CauseGraph): string[];
-export declare function countEdges(graph: CauseGraph): number;