@neuroverseos/nv-sim 0.1.2 → 0.1.6

package/dist/engine/dynamicsGovernance.js

@@ -0,0 +1,588 @@
+"use strict";
+/**
+ * Dynamics Governance Engine — System-Level Per-Round Control
+ *
+ * This is the second govern() call.
+ *
+ * Layer A: govern(action) — controls what agents DO (per-action, already built)
+ * Layer B: governDynamics() — controls how actions COMPOUND (per-round, this file)
+ *
+ * "We don't just control what agents do.
+ *  We control how their actions shape the system over time."
+ *
+ * Three dynamics controllers:
+ *   1. Propagation Controller — governs how far actions spread
+ *   2. Amplification Engine — governs media/influence weight modulation
+ *   3. Cascade Circuit Breaker — governs feedback loops and system-level states
+ *   4. Trust-Responsive Visibility — governs the information environment
+ *
+ * Usage:
+ *   const dynamics = createDynamicsGovernor(policyText)
+ *   for (const round of simulation) {
+ *     // ... agents act, govern() filters actions ...
+ *     const result = dynamics.governRound(reactions, systemState, round)
+ *     // result.reactions — modified by dynamics rules
+ *     // result.systemState — updated state after dynamics
+ *     // result.interventions — what dynamics did this round
+ *   }
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDynamicsGovernor = createDynamicsGovernor;
+exports.governDynamics = governDynamics;
+const policyEngine_1 = require("./policyEngine");
+// ============================================
+// SYSTEM STATE COMPUTATION
+// ============================================
+function computeSystemMetrics(reactions, prevState) {
+    const impacts = reactions.map((r) => r.impact);
+    const avgImpact = impacts.reduce((s, i) => s + i, 0) / impacts.length;
+    const variance = impacts.reduce((s, i) => s + (i - avgImpact) ** 2, 0) / impacts.length;
+    // Polarization: high when agents are split into opposing camps
+    const positive = impacts.filter((i) => i > 0.2).length;
+    const negative = impacts.filter((i) => i < -0.2).length;
+    const total = impacts.length;
+    const polarization = total > 0
+        ? Math.min(1, (Math.min(positive, negative) / (total * 0.5)) * (variance * 4))
+        : 0;
+    // Outrage: high when there's strong negative sentiment
+    const negativeIntensity = impacts
+        .filter((i) => i < 0)
+        .reduce((s, i) => s + Math.abs(i), 0) / Math.max(1, impacts.length);
+    const outrage = Math.min(1, negativeIntensity * 1.5);
+    return { polarization, outrage, avgImpact, variance };
+}
+function detectTrend(history, metric, lookback = 3) {
+    if (history.length < 2)
+        return "stable";
+    const recent = history.slice(-lookback);
+    if (recent.length < 2)
+        return "stable";
+    const first = recent[0][metric];
+    const last = recent[recent.length - 1][metric];
+    const delta = last - first;
+    if (delta > 0.1)
+        return "rising";
+    if (delta < -0.1)
+        return "falling";
+    return "stable";
+}
+// ============================================
+// DYNAMICS RULE PARSING
+// ============================================
+function parseDynamicsRules(policyText) {
+    const parsed = (0, policyEngine_1.parseRulesFromText)(policyText);
+    const rules = [];
+    let ruleIdx = 0;
+    for (const rule of parsed.rules) {
+        const desc = rule.description.toLowerCase();
+        // Propagation rules
+        if (desc.includes("spread") || desc.includes("propagat") ||
+            desc.includes("viral") || desc.includes("limit reach") ||
+            desc.includes("contain") || desc.includes("quarantine")) {
+            rules.push({
+                id: `DYN-PROP-${++ruleIdx}`,
+                description: rule.description,
+                type: "propagation",
+                threshold: 0.6,
+                strength: rule.category === "prohibit" ? 0.8 : rule.category === "limit" ? 0.5 : 0.3,
+                monitors: "informationVelocity",
+                active: true,
+            });
+        }
+        // Amplification rules
+        if (desc.includes("amplif") || desc.includes("media") ||
+            desc.includes("influence") || desc.includes("boost") ||
+            desc.includes("visibil") || desc.includes("platform")) {
+            rules.push({
+                id: `DYN-AMP-${++ruleIdx}`,
+                description: rule.description,
+                type: "amplification",
+                threshold: 0.5,
+                strength: rule.category === "prohibit" ? 0.7 : 0.4,
+                monitors: "amplification",
+                active: true,
+            });
+        }
+        // Cascade / circuit breaker rules
+        if (desc.includes("cascade") || desc.includes("circuit") ||
+            desc.includes("runaway") || desc.includes("feedback") ||
+            desc.includes("spiral") || desc.includes("chain reaction") ||
+            desc.includes("contagion") || desc.includes("panic")) {
+            rules.push({
+                id: `DYN-CASC-${++ruleIdx}`,
+                description: rule.description,
+                type: "cascade",
+                threshold: 0.7,
+                strength: 0.9,
+                monitors: "cascadeRisk",
+                active: true,
+            });
+        }
+        // Trust rules
+        if (desc.includes("trust") || desc.includes("legitim") ||
+            desc.includes("credib") || desc.includes("transparen") ||
+            desc.includes("accountab") || desc.includes("institution")) {
+            rules.push({
+                id: `DYN-TRUST-${++ruleIdx}`,
+                description: rule.description,
+                type: "trust",
+                threshold: 0.4,
+                strength: 0.5,
+                monitors: "trust",
+                active: true,
+            });
+        }
+        // Feedback dampening rules
+        if (desc.includes("dampen") || desc.includes("cool") ||
+            desc.includes("de-escalat") || desc.includes("moderate") ||
+            desc.includes("calm") || desc.includes("stabiliz")) {
+            rules.push({
+                id: `DYN-FEED-${++ruleIdx}`,
+                description: rule.description,
+                type: "feedback",
+                threshold: 0.5,
+                strength: 0.6,
+                monitors: "outrage",
+                active: true,
+            });
+        }
+        // Cooling period rules
+        if (desc.includes("pause") || desc.includes("halt") ||
+            desc.includes("freeze") || desc.includes("cooling") ||
+            desc.includes("moratorium") || desc.includes("waiting period")) {
+            rules.push({
+                id: `DYN-COOL-${++ruleIdx}`,
+                description: rule.description,
+                type: "cooling",
+                threshold: 0.7,
+                strength: 0.8,
+                monitors: "outrage",
+                active: true,
+            });
+        }
+    }
+    // Always add baseline dynamics rules if none were parsed
+    if (rules.length === 0) {
+        rules.push({
+            id: "DYN-BASE-1",
+            description: "Default propagation control — limit information spread during high outrage",
+            type: "propagation",
+            threshold: 0.7,
+            strength: 0.4,
+            monitors: "informationVelocity",
+            active: true,
+        }, {
+            id: "DYN-BASE-2",
+            description: "Default cascade protection — activate circuit breaker during crisis",
+            type: "cascade",
+            threshold: 0.8,
+            strength: 0.7,
+            monitors: "cascadeRisk",
+            active: true,
+        });
+    }
+    return rules;
+}
+// ============================================
+// CORE: createDynamicsGovernor()
+// ============================================
+function createDynamicsGovernor(policyText, initialState, options) {
+    const dynamicsRules = options?.skipRules ? [] : parseDynamicsRules(policyText);
+    let state = {
+        polarization: 0.1,
+        outrage: 0.1,
+        trust: 0.7,
+        informationVelocity: 0.3,
+        amplification: 1.0,
+        cascadeRisk: 0.1,
+        contagionDepth: 2,
+        coolingPeriod: 0,
+        history: [],
+        ...initialState,
+    };
+    const stats = {
+        totalRounds: 0,
+        totalInterventions: 0,
+        propagationLimits: 0,
+        amplificationDampens: 0,
+        cascadeBreakers: 0,
+        coolingPeriods: 0,
+        trustBoosts: 0,
+        peakOutrage: 0,
+        peakPolarization: 0,
+        peakCascadeRisk: 0,
+        trustSum: 0,
+    };
+    function governRound(reactions, round, agentTypes) {
+        stats.totalRounds++;
+        const interventions = [];
+        const rulesFired = [];
+        const governed = reactions.map((r) => ({ ...r }));
+        // --- Step 1: Compute current system metrics from reactions ---
+        const metrics = computeSystemMetrics(reactions, state);
+        // Update state from observed metrics
+        state.polarization = state.polarization * 0.6 + metrics.polarization * 0.4;
+        state.outrage = state.outrage * 0.5 + metrics.outrage * 0.5;
+        state.informationVelocity = Math.min(1, 0.3 + metrics.variance * 2);
+        state.cascadeRisk = Math.min(1, state.outrage * 0.3 +
+            state.polarization * 0.2 +
+            state.informationVelocity * 0.2 +
+            (1 - state.trust) * 0.3);
+        // Trust erodes when outrage is high, recovers when calm
+        if (state.outrage > 0.5) {
+            state.trust = Math.max(0.05, state.trust - 0.05 * state.outrage);
+        }
+        else if (state.outrage < 0.2) {
+            state.trust = Math.min(1, state.trust + 0.02);
+        }
+        // Track peaks
+        stats.peakOutrage = Math.max(stats.peakOutrage, state.outrage);
+        stats.peakPolarization = Math.max(stats.peakPolarization, state.polarization);
+        stats.peakCascadeRisk = Math.max(stats.peakCascadeRisk, state.cascadeRisk);
+        stats.trustSum += state.trust;
+        // --- Step 2: Apply cooling period (from previous round's cascade breaker) ---
+        if (state.coolingPeriod > 0) {
+            const coolingStrength = 0.4 + (state.coolingPeriod * 0.1);
+            for (const agent of governed) {
+                if (agent.impact < -0.1) {
+                    const before = agent.impact;
+                    agent.impact = agent.impact * (1 - coolingStrength);
+                    agent.confidence = Math.max(0.1, agent.confidence * 0.7);
+                }
+            }
+            interventions.push({
+                type: "COOLING_PERIOD",
+                description: `Cooling period active (${state.coolingPeriod} rounds remaining) — reactive posting dampened by ${(coolingStrength * 100).toFixed(0)}%`,
+                triggeredBy: "COOLING_PERIOD",
+                agentsAffected: governed.filter((a) => a.impact < -0.1).length,
+                magnitude: coolingStrength,
+                effect: { metric: "outrage", before: state.outrage, after: state.outrage * (1 - coolingStrength * 0.3) },
+            });
+            state.coolingPeriod--;
+            stats.coolingPeriods++;
+        }
+        // --- Step 3: Apply each dynamics rule ---
+        for (const rule of dynamicsRules) {
+            if (!rule.active)
+                continue;
+            const currentValue = state[rule.monitors];
+            switch (rule.type) {
+                // ========== PROPAGATION CONTROL ==========
+                case "propagation": {
+                    if (state.informationVelocity > rule.threshold || state.outrage > 0.6) {
+                        const dampFactor = 1 - (rule.strength * 0.5);
+                        let affected = 0;
+                        // Limit propagation depth
+                        const prevDepth = state.contagionDepth;
+                        state.contagionDepth = Math.max(1, Math.floor(state.contagionDepth * dampFactor));
+                        // Reduce the impact of agents whose reactions are extreme
+                        // (simulates limiting how far their content spreads)
+                        for (const agent of governed) {
+                            if (Math.abs(agent.impact) > 0.4) {
+                                const before = agent.impact;
+                                agent.impact = agent.impact * dampFactor;
+                                affected++;
+                            }
+                        }
+                        if (affected > 0) {
+                            const beforeVelocity = state.informationVelocity;
+                            state.informationVelocity *= dampFactor;
+                            interventions.push({
+                                type: "PROPAGATION_LIMIT",
+                                description: `Propagation limited: spread depth ${prevDepth} → ${state.contagionDepth}, ${affected} extreme agents dampened (${rule.description})`,
+                                triggeredBy: rule.id,
+                                agentsAffected: affected,
+                                magnitude: rule.strength,
+                                effect: { metric: "informationVelocity", before: beforeVelocity, after: state.informationVelocity },
+                            });
+                            rulesFired.push(rule.id);
+                            stats.propagationLimits++;
+                            stats.totalInterventions++;
+                        }
+                    }
+                    break;
+                }
+                // ========== AMPLIFICATION DAMPENING ==========
+                case "amplification": {
+                    const polarizationTrend = detectTrend(state.history, "polarization");
+                    if (state.polarization > rule.threshold || polarizationTrend === "rising") {
+                        const dampFactor = 1 - (rule.strength * 0.4);
+                        let affected = 0;
+                        // Reduce amplification for media/influencer type agents
+                        for (const agent of governed) {
+                            const agentType = agentTypes?.get(agent.stakeholder_id) ?? "";
+                            const isAmplifier = agentType.toLowerCase().includes("media") ||
+                                agentType.toLowerCase().includes("influencer") ||
+                                agent.stakeholder_id.toLowerCase().includes("media") ||
+                                agent.stakeholder_id.toLowerCase().includes("记者") || // journalist (Chinese)
+                                agent.stakeholder_id.toLowerCase().includes("媒") || // media (Chinese)
+                                Math.abs(agent.impact) > 0.6; // or any agent with extreme impact
+                            if (isAmplifier) {
+                                const before = agent.impact;
+                                agent.impact = agent.impact * dampFactor;
+                                agent.confidence = Math.max(0.15, agent.confidence * 0.8);
+                                affected++;
+                            }
+                        }
+                        if (affected > 0) {
+                            const beforeAmp = state.amplification;
+                            state.amplification *= dampFactor;
+                            interventions.push({
+                                type: "AMPLIFICATION_DAMPEN",
+                                description: `Amplification dampened: ${affected} high-influence agents reduced by ${((1 - dampFactor) * 100).toFixed(0)}% (polarization ${state.polarization.toFixed(2)}, trend: ${polarizationTrend}) — ${rule.description}`,
+                                triggeredBy: rule.id,
+                                agentsAffected: affected,
+                                magnitude: rule.strength,
+                                effect: { metric: "amplification", before: beforeAmp, after: state.amplification },
+                            });
+                            rulesFired.push(rule.id);
+                            stats.amplificationDampens++;
+                            stats.totalInterventions++;
+                        }
+                    }
+                    break;
+                }
+                // ========== CASCADE CIRCUIT BREAKER ==========
+                case "cascade": {
+                    if (state.cascadeRisk > rule.threshold) {
+                        const outrageRising = detectTrend(state.history, "outrage") === "rising";
+                        const breakerStrength = outrageRising ? rule.strength : rule.strength * 0.6;
+                        let affected = 0;
+                        // Compress ALL negative reactions toward zero
+                        for (const agent of governed) {
+                            if (agent.impact < -0.15) {
+                                const before = agent.impact;
+                                agent.impact = agent.impact * (1 - breakerStrength);
+                                agent.confidence = Math.max(0.1, agent.confidence * (1 - breakerStrength * 0.5));
+                                affected++;
+                            }
+                        }
+                        // Activate cooling period
+                        if (state.coolingPeriod === 0 && outrageRising) {
+                            state.coolingPeriod = 2; // 2 rounds of cooling
+                        }
+                        const beforeCascade = state.cascadeRisk;
+                        state.cascadeRisk *= (1 - breakerStrength * 0.4);
+                        interventions.push({
+                            type: "CASCADE_BREAKER",
+                            description: `CASCADE CIRCUIT BREAKER: ${affected} agents compressed, cascade risk ${beforeCascade.toFixed(2)} → ${state.cascadeRisk.toFixed(2)}${outrageRising ? " + cooling period activated" : ""} — ${rule.description}`,
+                            triggeredBy: rule.id,
+                            agentsAffected: affected,
+                            magnitude: breakerStrength,
+                            effect: { metric: "cascadeRisk", before: beforeCascade, after: state.cascadeRisk },
+                        });
+                        rulesFired.push(rule.id);
+                        stats.cascadeBreakers++;
+                        stats.totalInterventions++;
+                    }
+                    break;
+                }
+                // ========== TRUST-RESPONSIVE VISIBILITY ==========
+                case "trust": {
+                    if (state.trust < rule.threshold) {
+                        let affected = 0;
+                        // Boost official/institutional agents, dampen hostile/unknown ones
+                        for (const agent of governed) {
+                            const agentType = agentTypes?.get(agent.stakeholder_id) ?? "";
+                            const isOfficial = agentType.toLowerCase().includes("official") ||
+                                agentType.toLowerCase().includes("government") ||
+                                agentType.toLowerCase().includes("institution") ||
+                                agent.stakeholder_id.toLowerCase().includes("regulator") ||
+                                agent.stakeholder_id.toLowerCase().includes("central") ||
+                                agent.stakeholder_id.toLowerCase().includes("official") ||
+                                agent.stakeholder_id.toLowerCase().includes("管理") || // management (Chinese)
+                                agent.stakeholder_id.toLowerCase().includes("官方"); // official (Chinese)
+                            if (isOfficial && agent.impact > -0.2) {
+                                // Boost visibility of official sources
+                                const before = agent.impact;
+                                agent.impact = Math.min(1, agent.impact * 1.3 + 0.1);
+                                agent.confidence = Math.min(1, agent.confidence * 1.2);
+                                affected++;
+                            }
+                            else if (!isOfficial && agent.impact < -0.3) {
+                                // Reduce visibility of unverified negative claims
+                                agent.impact = agent.impact * 0.7;
+                                affected++;
+                            }
+                        }
+                        if (affected > 0) {
+                            const beforeTrust = state.trust;
+                            state.trust = Math.min(1, state.trust + 0.03 * rule.strength);
+                            interventions.push({
+                                type: "TRUST_BOOST",
+                                description: `Trust-responsive visibility: official sources boosted, unverified claims dampened (trust ${beforeTrust.toFixed(2)} → ${state.trust.toFixed(2)}) — ${rule.description}`,
+                                triggeredBy: rule.id,
+                                agentsAffected: affected,
+                                magnitude: rule.strength,
+                                effect: { metric: "trust", before: beforeTrust, after: state.trust },
+                            });
+                            rulesFired.push(rule.id);
+                            stats.trustBoosts++;
+                            stats.totalInterventions++;
+                        }
+                    }
+                    break;
+                }
+                // ========== FEEDBACK DAMPENING ==========
+                case "feedback": {
+                    const outrageTrend = detectTrend(state.history, "outrage");
+                    if (state.outrage > rule.threshold && outrageTrend === "rising") {
+                        const dampFactor = 1 - (rule.strength * 0.35);
+                        let affected = 0;
+                        // Reduce ALL reactive behavior — pull everything toward zero
+                        for (const agent of governed) {
+                            if (Math.abs(agent.impact) > 0.2) {
+                                const before = agent.impact;
+                                agent.impact = agent.impact * dampFactor;
+                                affected++;
+                            }
+                        }
+                        if (affected > 0) {
+                            const beforeOutrage = state.outrage;
+                            state.outrage *= dampFactor;
+                            interventions.push({
+                                type: "FEEDBACK_DAMPEN",
+                                description: `Feedback loop dampened: ${affected} reactive agents moderated, outrage ${beforeOutrage.toFixed(2)} → ${state.outrage.toFixed(2)} (trend: ${outrageTrend}) — ${rule.description}`,
+                                triggeredBy: rule.id,
+                                agentsAffected: affected,
+                                magnitude: rule.strength,
+                                effect: { metric: "outrage", before: beforeOutrage, after: state.outrage },
+                            });
+                            rulesFired.push(rule.id);
+                            stats.totalInterventions++;
+                        }
+                    }
+                    break;
+                }
+                // ========== COOLING PERIOD TRIGGER ==========
+                case "cooling": {
+                    if (state.outrage > rule.threshold && state.coolingPeriod === 0) {
+                        state.coolingPeriod = Math.ceil(rule.strength * 3); // 1-3 rounds
+                        interventions.push({
+                            type: "COOLING_PERIOD",
+                            description: `Cooling period triggered: ${state.coolingPeriod} round(s) of dampened reactive posting (outrage: ${state.outrage.toFixed(2)}) — ${rule.description}`,
+                            triggeredBy: rule.id,
+                            agentsAffected: 0,
+                            magnitude: rule.strength,
+                            effect: { metric: "outrage", before: state.outrage, after: state.outrage },
+                        });
+                        rulesFired.push(rule.id);
+                        stats.coolingPeriods++;
+                        stats.totalInterventions++;
+                    }
+                    break;
+                }
+            }
+        }
+        // --- Step 4: Reclamp all impacts ---
+        for (const agent of governed) {
+            agent.impact = Math.max(-1, Math.min(1, agent.impact));
+            agent.impact = Number(agent.impact.toFixed(3));
+            agent.confidence = Math.max(0.05, Math.min(1, agent.confidence));
+            agent.confidence = Number(agent.confidence.toFixed(3));
+        }
+        // --- Step 5: Record state snapshot ---
+        const postMetrics = computeSystemMetrics(governed, state);
+        state.history.push({
+            round,
+            polarization: Number(state.polarization.toFixed(3)),
+            outrage: Number(state.outrage.toFixed(3)),
+            trust: Number(state.trust.toFixed(3)),
+            amplification: Number(state.amplification.toFixed(3)),
+            cascadeRisk: Number(state.cascadeRisk.toFixed(3)),
+            avgImpact: Number(postMetrics.avgImpact.toFixed(3)),
+            agentCount: governed.length,
+        });
+        // --- Step 6: Determine trajectory ---
+        let trajectory;
+        if (state.coolingPeriod > 0) {
+            trajectory = "cooling";
+        }
+        else if (state.cascadeRisk > 0.7) {
+            trajectory = "critical";
+        }
+        else if (detectTrend(state.history, "outrage") === "rising" || detectTrend(state.history, "polarization") === "rising") {
+            trajectory = "escalating";
+        }
+        else if (detectTrend(state.history, "outrage") === "falling" && detectTrend(state.history, "polarization") === "falling") {
+            trajectory = "de-escalating";
+        }
+        else {
+            trajectory = "stable";
+        }
+        // Predict next-round risk
+        const predictedRisk = Math.min(1, state.cascadeRisk * 0.4 +
+            state.outrage * 0.3 +
+            state.polarization * 0.2 +
+            state.informationVelocity * 0.1);
+        return {
+            reactions: governed,
+            systemState: { ...state, history: [...state.history] },
+            interventions,
+            rulesFired,
+            trajectory,
+            predictedRisk: Number(predictedRisk.toFixed(3)),
+        };
+    }
+    function reset() {
+        state = {
+            polarization: 0.1,
+            outrage: 0.1,
+            trust: 0.7,
+            informationVelocity: 0.3,
+            amplification: 1.0,
+            cascadeRisk: 0.1,
+            contagionDepth: 2,
+            coolingPeriod: 0,
+            history: [],
+            ...initialState,
+        };
+        stats.totalRounds = 0;
+        stats.totalInterventions = 0;
+        stats.propagationLimits = 0;
+        stats.amplificationDampens = 0;
+        stats.cascadeBreakers = 0;
+        stats.coolingPeriods = 0;
+        stats.trustBoosts = 0;
+        stats.peakOutrage = 0;
+        stats.peakPolarization = 0;
+        stats.peakCascadeRisk = 0;
+        stats.trustSum = 0;
+    }
+    return {
+        governRound,
+        get state() { return { ...state, history: [...state.history] }; },
+        /** Mutate the internal state directly (used by adapters for governance feedback) */
+        mutateState(fn) { fn(state); },
+        get rules() { return [...dynamicsRules]; },
+        get stats() {
+            return {
+                totalRounds: stats.totalRounds,
+                totalInterventions: stats.totalInterventions,
+                propagationLimits: stats.propagationLimits,
+                amplificationDampens: stats.amplificationDampens,
+                cascadeBreakers: stats.cascadeBreakers,
+                coolingPeriods: stats.coolingPeriods,
+                trustBoosts: stats.trustBoosts,
+                peakOutrage: stats.peakOutrage,
+                peakPolarization: stats.peakPolarization,
+                peakCascadeRisk: stats.peakCascadeRisk,
+                averageTrust: stats.totalRounds > 0 ? Number((stats.trustSum / stats.totalRounds).toFixed(3)) : 0.7,
+            };
+        },
+        reset,
+    };
+}
+// ============================================
+// CONVENIENCE: governDynamics() one-shot
+// ============================================
+/**
+ * One-shot dynamics governance for a single round.
+ *
+ * For repeated calls, use createDynamicsGovernor() instead.
+ * This is mainly useful for testing/playground.
+ */
+function governDynamics(reactions, policyText, systemState) {
+    const governor = createDynamicsGovernor(policyText, systemState);
+    return governor.governRound(reactions, 0);
+}