@neuroverseos/nv-sim 0.1.2 → 0.1.6

package/dist/engine/fullGovernedLoop.js

@@ -0,0 +1,367 @@
+"use strict";
+/**
+ * Full Governed Simulation Loop — govern() + governDynamics()
+ *
+ * The complete simulation architecture:
+ *
+ *   for each round:
+ *     for each agent:
+ *       action → govern(action) → commit         ← Layer A (action governance)
+ *     updateState()
+ *     governDynamics(state, trajectory, history)  ← Layer B (dynamics governance)
+ *
+ * "We don't just control what agents do.
+ *  We control how their actions shape the system over time."
+ *
+ * This module combines the existing govern() with the new governDynamics()
+ * into a unified simulation runner that produces rich, traceable output.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runFullGovernedSimulation = runFullGovernedSimulation;
+const swarmSimulation_1 = require("./swarmSimulation");
+const govern_1 = require("../runtime/govern");
+const dynamicsGovernance_1 = require("./dynamicsGovernance");
+const narrativeInjection_1 = require("./narrativeInjection");
+// ============================================
+// AGENT REACTION → ACTION ADAPTER
+// ============================================
+/**
+ * Convert a SwarmAgentReaction into an AgentAction for govern().
+ *
+ * This is the bridge between MiroFish/Swarm output and NeuroVerse governance.
+ * It infers action type, magnitude, and description from the reaction content.
+ */
+function reactionToAction(reaction) {
+    const desc = reaction.reaction.toLowerCase();
+    // Infer action type from reaction content
+    let type = "communication";
+    if (desc.includes("sell") || desc.includes("buy") || desc.includes("trade"))
+        type = "trade";
+    if (desc.includes("post") || desc.includes("share") || desc.includes("publish"))
+        type = "post";
+    if (desc.includes("comment") || desc.includes("reply") || desc.includes("respond"))
+        type = "comment";
+    if (desc.includes("follow") || desc.includes("join") || desc.includes("coalition"))
+        type = "coalition";
+    if (desc.includes("withdraw") || desc.includes("exit") || desc.includes("leave"))
+        type = "withdrawal";
+    if (desc.includes("intervene") || desc.includes("inject") || desc.includes("regulate"))
+        type = "intervention";
+    if (desc.includes("amplif") || desc.includes("boost") || desc.includes("promote"))
+        type = "amplification";
+    if (desc.includes("attack") || desc.includes("accuse") || desc.includes("denounce"))
+        type = "hostile";
+    // Magnitude is the absolute impact
+    const magnitude = Math.abs(reaction.impact);
+    return {
+        agentId: reaction.stakeholder_id,
+        type,
+        description: reaction.reaction,
+        magnitude: Number(magnitude.toFixed(3)),
+        context: {
+            originalImpact: reaction.impact,
+            confidence: reaction.confidence,
+            trigger: reaction.trigger,
+        },
+    };
+}
+/**
+ * Apply a governance verdict back to a reaction.
+ */
+function applyVerdictToReaction(reaction, verdict) {
+    if (verdict.status === "BLOCK") {
+        return {
+            ...reaction,
+            impact: Number((reaction.impact * 0.1).toFixed(3)),
+            confidence: Number((Math.max(0.05, reaction.confidence * 0.3)).toFixed(3)),
+        };
+    }
+    if (verdict.status === "PAUSE") {
+        return {
+            ...reaction,
+            impact: Number((reaction.impact * 0.5).toFixed(3)),
+            confidence: Number((Math.max(0.1, reaction.confidence * 0.6)).toFixed(3)),
+        };
+    }
+    if (verdict.status === "MODIFY" && verdict.action) {
+        const ratio = verdict.action.magnitude / Math.max(0.001, Math.abs(reaction.impact));
+        return {
+            ...reaction,
+            impact: Number((reaction.impact * ratio).toFixed(3)),
+            confidence: Number(reaction.confidence.toFixed(3)),
+        };
+    }
+    // ALLOW — no change
+    return reaction;
+}
+// ============================================
+// DETECT EMERGENT DYNAMICS
+// ============================================
+function detectEmergentDynamics(reactions, dynamicsInterventions, systemState) {
+    const dynamics = [];
+    const avgImpact = reactions.reduce((s, r) => s + r.impact, 0) / reactions.length;
+    if (Math.abs(avgImpact) > 0.5) {
+        dynamics.push(avgImpact > 0
+            ? "Strong positive consensus — governance channeled energy constructively"
+            : "Negative consensus persists despite governance intervention");
+    }
+    else if (Math.abs(avgImpact) < 0.12) {
+        dynamics.push("Near-equilibrium achieved — agent positions stabilized by governance");
+    }
+    const positive = reactions.filter((r) => r.impact > 0.2).length;
+    const negative = reactions.filter((r) => r.impact < -0.2).length;
+    if (positive > 0 && negative > 0 && Math.abs(positive - negative) <= 1) {
+        dynamics.push("Polarization detected but contained by dynamics governance");
+    }
+    if (systemState.coolingPeriod > 0) {
+        dynamics.push(`Cooling period active — reactive posting suppressed for ${systemState.coolingPeriod} more round(s)`);
+    }
+    if (systemState.cascadeRisk > 0.7) {
+        dynamics.push(`CASCADE WARNING: risk at ${(systemState.cascadeRisk * 100).toFixed(0)}% — circuit breakers engaged`);
+    }
+    if (systemState.trust < 0.3) {
+        dynamics.push(`TRUST CRISIS: institutional trust at ${(systemState.trust * 100).toFixed(0)}% — visibility shift active`);
+    }
+    if (dynamicsInterventions.length > 0) {
+        dynamics.push(`${dynamicsInterventions.length} dynamics intervention(s) applied this round`);
+    }
+    return dynamics;
+}
+// ============================================
+// MAIN: runFullGovernedSimulation()
+// ============================================
+/**
+ * Run a simulation with BOTH governance layers:
+ *   Layer A: govern() — per-action, per-agent
+ *   Layer B: governDynamics() — per-round, system-level
+ *
+ * This is the complete Prime Radiant simulation loop.
+ */
+async function runFullGovernedSimulation(config) {
+    // --- Initialize both governors ---
+    const actionGovernor = (0, govern_1.createGovernor)({
+        policyText: config.policyText,
+        sensitivity: 0.5,
+    });
+    const dynamicsGovernor = (0, dynamicsGovernance_1.createDynamicsGovernor)(config.policyText, config.initialSystemState);
+    // Build policy text from world definition invariants + explicit policy
+    const fullPolicyText = [
+        config.policyText,
+        ...config.worldDef.invariants.map((inv) => inv.description),
+    ].join("\n");
+    // Re-create action governor with full policy
+    const fullActionGovernor = (0, govern_1.createGovernor)({
+        policyText: fullPolicyText,
+        sensitivity: 0.5,
+    });
+    // --- Run raw simulation ---
+    const rawResult = await (0, swarmSimulation_1.runSwarmSimulation)(config.scenario, config.stakeholders, config.paths, config.swarmConfig);
+    // --- Process each round through both governance layers ---
+    const rounds = [];
+    const allDynamicsInterventions = [];
+    const allNarrativeImpacts = [];
+    const actionStats = {
+        totalEvaluations: 0,
+        allowed: 0,
+        blocked: 0,
+        modified: 0,
+        paused: 0,
+        totalReduction: 0,
+        rulesFired: 0,
+    };
+    for (const rawRound of rawResult.rounds) {
+        // === LAYER A: Action Governance ===
+        const actionVerdicts = [];
+        const actionGovernedReactions = [];
+        for (const reaction of rawRound.reactions) {
+            // Convert reaction to action
+            const action = reactionToAction(reaction);
+            // Build world state from current dynamics state
+            const currentState = dynamicsGovernor.state;
+            const worldState = {
+                volatility: currentState.outrage * 100,
+                liquidity: currentState.trust * 100,
+                polarization: currentState.polarization * 100,
+                cascade_risk: currentState.cascadeRisk * 100,
+            };
+            // Evaluate through action governor
+            const verdict = fullActionGovernor.evaluate(action, worldState);
+            actionStats.totalEvaluations++;
+            switch (verdict.status) {
+                case "ALLOW":
+                    actionStats.allowed++;
+                    break;
+                case "BLOCK":
+                    actionStats.blocked++;
+                    break;
+                case "MODIFY":
+                    actionStats.modified++;
+                    break;
+                case "PAUSE":
+                    actionStats.paused++;
+                    break;
+            }
+            actionStats.rulesFired += verdict.rulesFired.filter((r) => r.effect !== "monitored").length;
+            if (verdict.action) {
+                const reduction = 1 - (verdict.action.magnitude / Math.max(0.001, action.magnitude));
+                actionStats.totalReduction += reduction;
+            }
+            else {
+                actionStats.totalReduction += 1;
+            }
+            // Apply verdict to reaction
+            const governedReaction = applyVerdictToReaction(reaction, verdict);
+            actionGovernedReactions.push(governedReaction);
+            actionVerdicts.push({
+                agentId: reaction.stakeholder_id,
+                status: verdict.status,
+                originalMagnitude: action.magnitude,
+                governedMagnitude: verdict.action?.magnitude ?? null,
+                rulesFired: verdict.rulesFired.length,
+                reason: verdict.reason,
+            });
+        }
+        // === NARRATIVE INJECTION (between Layer A and Layer B) ===
+        if (config.narrativeEvents && config.narrativeEvents.length > 0) {
+            const roundEvents = (0, narrativeInjection_1.getEventsForRound)(config.narrativeEvents, rawRound.round);
+            for (const event of roundEvents) {
+                const impact = (0, narrativeInjection_1.injectNarrative)(actionGovernedReactions, event, config.stakeholders);
+                allNarrativeImpacts.push(impact);
+            }
+        }
+        // === LAYER B: Dynamics Governance ===
+        const dynamicsResult = dynamicsGovernor.governRound(actionGovernedReactions, rawRound.round, config.agentTypes);
+        allDynamicsInterventions.push(...dynamicsResult.interventions);
+        // Detect emergent dynamics
+        const emergentDynamics = detectEmergentDynamics(dynamicsResult.reactions, dynamicsResult.interventions, dynamicsResult.systemState);
+        rounds.push({
+            round: rawRound.round,
+            rawReactions: rawRound.reactions,
+            actionGovernedReactions,
+            finalReactions: dynamicsResult.reactions,
+            actionVerdicts,
+            dynamicsInterventions: dynamicsResult.interventions,
+            dynamicsTrajectory: dynamicsResult.trajectory,
+            systemState: dynamicsResult.systemState,
+            emergentDynamics,
+            predictedRisk: dynamicsResult.predictedRisk,
+        });
+    }
+    // --- Compute aggregate metrics ---
+    const finalState = dynamicsGovernor.state;
+    const stateTimeline = finalState.history;
+    // Overall trajectory
+    const trajectory = computeOverallTrajectory(rounds);
+    // System health score (0-100)
+    const systemHealthScore = computeSystemHealth(finalState, actionStats, dynamicsGovernor.stats);
+    // Inflection points
+    const inflectionPoints = findInflectionPoints(rounds);
+    const avgReduction = actionStats.totalEvaluations > 0
+        ? actionStats.totalReduction / actionStats.totalEvaluations
+        : 0;
+    return {
+        scenario: config.scenario,
+        policyText: config.policyText,
+        worldRules: {
+            thesis: config.worldDef.thesis,
+            invariantCount: config.worldDef.invariants.length,
+            gateCount: config.worldDef.gates?.length ?? 0,
+        },
+        rounds,
+        stateTimeline,
+        actionGovernance: {
+            totalEvaluations: actionStats.totalEvaluations,
+            allowed: actionStats.allowed,
+            blocked: actionStats.blocked,
+            modified: actionStats.modified,
+            paused: actionStats.paused,
+            avgReduction: Number(avgReduction.toFixed(3)),
+            rulesFired: actionStats.rulesFired,
+        },
+        dynamicsGovernance: dynamicsGovernor.stats,
+        allDynamicsInterventions,
+        narrativeImpacts: allNarrativeImpacts,
+        trajectory,
+        systemHealthScore,
+        inflectionPoints,
+        finalState,
+    };
+}
+// ============================================
+// HELPERS
+// ============================================
+function computeOverallTrajectory(rounds) {
+    if (rounds.length < 2)
+        return "stabilizing";
+    const avgImpacts = rounds.map((r) => r.finalReactions.reduce((s, rx) => s + rx.impact, 0) / r.finalReactions.length);
+    const trend = avgImpacts[avgImpacts.length - 1] - avgImpacts[0];
+    const mean = avgImpacts.reduce((s, x) => s + x, 0) / avgImpacts.length;
+    const variance = avgImpacts.reduce((s, v) => s + (v - mean) ** 2, 0) / avgImpacts.length;
+    if (variance > 0.15)
+        return "diverging";
+    if (Math.abs(trend) < 0.1 && variance < 0.05)
+        return "converging";
+    if (trend < -0.2)
+        return "escalating";
+    return "stabilizing";
+}
+function computeSystemHealth(finalState, actionStats, dynamicsStats) {
+    let score = 50; // baseline
+    // Trust contribution (+/- 20)
+    score += (finalState.trust - 0.5) * 40;
+    // Low outrage is good (+/- 15)
+    score += (0.5 - finalState.outrage) * 30;
+    // Low polarization is good (+/- 10)
+    score += (0.5 - finalState.polarization) * 20;
+    // Low cascade risk is good (+/- 10)
+    score += (0.5 - finalState.cascadeRisk) * 20;
+    // Governance activity is neutral-positive (shows the system is working)
+    if (dynamicsStats.totalInterventions > 0) {
+        score += 5; // System was active
+    }
+    // Over-blocking is bad
+    const blockRate = actionStats.totalEvaluations > 0
+        ? actionStats.blocked / actionStats.totalEvaluations
+        : 0;
+    if (blockRate > 0.7)
+        score -= 15; // Over-constrained
+    return Math.max(0, Math.min(100, Math.round(score)));
+}
+function findInflectionPoints(rounds) {
+    const points = [];
+    for (let i = 1; i < rounds.length; i++) {
+        const prev = rounds[i - 1];
+        const curr = rounds[i];
+        // System state transitions
+        if (prev.dynamicsTrajectory !== curr.dynamicsTrajectory) {
+            points.push(`Round ${i}: Trajectory shifted ${prev.dynamicsTrajectory} → ${curr.dynamicsTrajectory}`);
+        }
+        // Cascade breaker activation
+        const cascadeBreaker = curr.dynamicsInterventions.find((d) => d.type === "CASCADE_BREAKER");
+        if (cascadeBreaker) {
+            points.push(`Round ${i}: CASCADE CIRCUIT BREAKER activated — ${cascadeBreaker.description}`);
+        }
+        // Cooling period start
+        if (prev.systemState.coolingPeriod === 0 && curr.systemState.coolingPeriod > 0) {
+            points.push(`Round ${i}: Cooling period triggered — system entering dampened state`);
+        }
+        // Trust crisis
+        if (prev.systemState.trust >= 0.3 && curr.systemState.trust < 0.3) {
+            points.push(`Round ${i}: TRUST CRISIS — institutional trust dropped below 30%`);
+        }
+        // Trust recovery
+        if (prev.systemState.trust < 0.3 && curr.systemState.trust >= 0.3) {
+            points.push(`Round ${i}: Trust recovery — institutional trust climbed back above 30%`);
+        }
+        // Major sentiment shift
+        const prevAvg = prev.finalReactions.reduce((s, r) => s + r.impact, 0) / prev.finalReactions.length;
+        const currAvg = curr.finalReactions.reduce((s, r) => s + r.impact, 0) / curr.finalReactions.length;
+        if (Math.abs(currAvg - prevAvg) > 0.3) {
+            points.push(`Round ${i}: Major sentiment shift (${(Math.abs(currAvg - prevAvg) * 100).toFixed(0)}% swing)`);
+        }
+    }
+    if (points.length === 0) {
+        points.push("Governance prevented major inflection points — smooth trajectory maintained");
+    }
+    return points;
+}

package/dist/engine/governance.js

@@ -110,10 +110,15 @@ function runFullGovernanceChecks(request, worldLite) {
         // Convert verdict to constitutional checks
         const nvChecks = (0, worldBridge_1.verdictToConstitutionalChecks)(guardVerdict);
         results.push(...nvChecks);
-        // If guard blocks, stop reasoning
+        // If guard blocks, note the intervention but continue in advisory mode
+        // (Reasoning continues so user can see what governance changed)
         if (guardVerdict.status === "BLOCK") {
-            allowed = false;
-            blockReason = `NeuroverseOS governance: ${guardVerdict.reason ?? "Action blocked by guard"}`;
+            results.push({
+                rule_id: "NV-BLOCK",
+                rule: "NeuroverseOS guard issued BLOCK — governance intervention active",
+                passed: false,
+                detail: `Guard blocked: ${guardVerdict.reason ?? "Action blocked by guard"}. Continuing in governed advisory mode.`,
+            });
         }
         // If guard pauses, note it but continue (reasoning is advisory)
         if (guardVerdict.status === "PAUSE") {

package/dist/engine/governedSimulation.js

@@ -17,6 +17,8 @@ exports.TRADING_DEMO = void 0;
 exports.runGovernedComparison = runGovernedComparison;
 const swarmSimulation_1 = require("./swarmSimulation");
 const worldBridge_1 = require("./worldBridge");
+const narrativeInjection_1 = require("./narrativeInjection");
+const behavioralAnalysis_1 = require("./behavioralAnalysis");
 // ============================================
 // GOVERNED REACTION MODEL
 // ============================================
@@ -30,20 +32,79 @@ const worldBridge_1 = require("./worldBridge");
  */
 function applyGovernanceToReactions(reactions, invariants, gates, roundIndex, cumulativeAvgImpact) {
     const interventions = [];
+    const enforcementLog = [];
     const governed = reactions.map((r) => ({ ...r }));
     // --- Invariant enforcement ---
-    // Enforceable invariants act as behavioral constraints
-    const enforceableInvariants = invariants.filter((inv) => inv.enforceable);
-    for (const inv of enforceableInvariants) {
+    for (const inv of invariants) {
         const desc = inv.description.toLowerCase();
+        let fired = false;
+        if (!inv.enforceable) {
+            // Advisory invariants: log but don't reshape
+            enforcementLog.push({ id: inv.id, description: inv.description, level: "advisory", fired: false });
+            if (roundIndex === 0) {
+                interventions.push(`[ADVISORY] ${inv.description} — monitored, not enforced`);
+            }
+            continue;
+        }
+        // === Block/prohibit patterns (user language: "Block panic selling") ===
+        // Hard block: cap matching actions to near-zero impact
+        if (desc.includes("block") || desc.includes("prohibit") || desc.includes("prevent") || desc.includes("forbid") || desc.includes("ban") || desc.includes("stop")) {
+            for (const agent of governed) {
+                // Match the blocked action pattern against agent reactions
+                const reactionLower = agent.reaction?.toLowerCase() ?? "";
+                const actionTerms = desc.replace(/\b(block|prohibit|prevent|forbid|ban|stop)\b/g, "").trim().split(/\s+/).filter(t => t.length > 2);
+                const matches = actionTerms.some(term => reactionLower.includes(term)) || agent.impact < -0.3;
+                if (matches) {
+                    const original = agent.impact;
+                    agent.impact = agent.impact * 0.15; // Hard suppression
+                    agent.confidence = Math.max(0.1, agent.confidence * 0.4);
+                    if (Math.abs(original - agent.impact) > 0.01) {
+                        fired = true;
+                        interventions.push(`[BLOCK] ${agent.stakeholder_id}: "${inv.description}" — impact crushed ${original.toFixed(2)} → ${agent.impact.toFixed(2)}`);
+                    }
+                }
+            }
+        }
+        // === Panic / cascade / contagion patterns ===
+        // Circuit breaker: dampen all agents when panic conditions detected
+        if (desc.includes("panic") || desc.includes("cascade") || desc.includes("contagion") || desc.includes("runaway") || desc.includes("crash")) {
+            const negativeCount = governed.filter(a => a.impact < -0.2).length;
+            const panicThreshold = Math.max(1, Math.floor(governed.length * 0.4));
+            if (negativeCount >= panicThreshold || cumulativeAvgImpact < -0.2) {
+                const dampingFactor = 0.3;
+                for (const agent of governed) {
+                    if (agent.impact < -0.15) {
+                        const original = agent.impact;
+                        agent.impact = agent.impact * dampingFactor;
+                        fired = true;
+                    }
+                }
+                interventions.push(`[BLOCK] PANIC CIRCUIT BREAKER: "${inv.description}" — ${negativeCount} agents in panic, negative impacts crushed by ${((1 - dampingFactor) * 100).toFixed(0)}%`);
+            }
+        }
+        // === Slow / cool / gradual patterns ===
+        // Dampening: reduce all extreme movements
+        if (desc.includes("slow") || desc.includes("cool") || desc.includes("gradual") || desc.includes("dampen") || desc.includes("reduce volatility")) {
+            for (const agent of governed) {
+                if (Math.abs(agent.impact) > 0.3) {
+                    const original = agent.impact;
+                    agent.impact = agent.impact * 0.65;
+                    if (Math.abs(original - agent.impact) > 0.01) {
+                        fired = true;
+                        interventions.push(`[PAUSE] ${agent.stakeholder_id}: "${inv.description}" — dampened ${original.toFixed(2)} → ${agent.impact.toFixed(2)}`);
+                    }
+                }
+            }
+        }
         // Cap extreme negative impacts (e.g., "maintain liquidity floor")
         if (desc.includes("floor") || desc.includes("maintain") || desc.includes("minimum")) {
             for (const agent of governed) {
-                if (agent.impact < -0.6) {
+                if (agent.impact < -0.35) {
                     const original = agent.impact;
-                    agent.impact = Math.max(agent.impact, -0.5);
+                    agent.impact = Math.max(agent.impact, -0.3);
                     if (original !== agent.impact) {
-                        interventions.push(`[${inv.id}] Capped ${agent.stakeholder_id} negative impact: ${original.toFixed(2)} → ${agent.impact.toFixed(2)} (${inv.description})`);
+                        fired = true;
+                        interventions.push(`[BLOCK] ${agent.stakeholder_id}: Liquidity floor violated — impact capped ${original.toFixed(2)} → ${agent.impact.toFixed(2)} (${inv.description})`);
                     }
                 }
             }
@@ -51,11 +112,12 @@ function applyGovernanceToReactions(reactions, invariants, gates, roundIndex, cu
         // Limit excessive positive speculation (e.g., "no leverage > 5x")
         if (desc.includes("leverage") || desc.includes("limit") || desc.includes("cap") || desc.includes("restrict")) {
             for (const agent of governed) {
-                if (agent.impact > 0.7) {
+                if (agent.impact > 0.45) {
                     const original = agent.impact;
-                    agent.impact = Math.min(agent.impact, 0.6);
+                    agent.impact = Math.min(agent.impact, 0.4);
                     if (original !== agent.impact) {
-                        interventions.push(`[${inv.id}] Capped ${agent.stakeholder_id} excessive position: ${original.toFixed(2)} → ${agent.impact.toFixed(2)} (${inv.description})`);
+                        fired = true;
+                        interventions.push(`[BLOCK] ${agent.stakeholder_id}: Leverage limit exceeded — position capped ${original.toFixed(2)} → ${agent.impact.toFixed(2)} (${inv.description})`);
                     }
                 }
             }
@@ -65,10 +127,11 @@ function applyGovernanceToReactions(reactions, invariants, gates, roundIndex, cu
             // Pull extreme reactions toward the mean
             const avgImpact = governed.reduce((s, a) => s + a.impact, 0) / governed.length;
             for (const agent of governed) {
-                if (Math.abs(agent.impact - avgImpact) > 0.4) {
+                if (Math.abs(agent.impact - avgImpact) > 0.25) {
                     const original = agent.impact;
                     agent.impact = agent.impact * 0.7 + avgImpact * 0.3;
-                    interventions.push(`[${inv.id}] Rebalanced ${agent.stakeholder_id}: ${original.toFixed(2)} → ${agent.impact.toFixed(2)} (${inv.description})`);
+                    fired = true;
+                    interventions.push(`[PAUSE] Rebalanced ${agent.stakeholder_id}: drift ${original.toFixed(2)} → ${agent.impact.toFixed(2)} (${inv.description})`);
                 }
             }
         }
@@ -79,11 +142,13 @@ function applyGovernanceToReactions(reactions, invariants, gates, roundIndex, cu
                     const original = agent.impact;
                     agent.impact = agent.impact * 0.8; // 20% reduction in hostility
                     if (Math.abs(original - agent.impact) > 0.01) {
+                        fired = true;
                         interventions.push(`[${inv.id}] Trust gate dampened ${agent.stakeholder_id} hostility: ${original.toFixed(2)} → ${agent.impact.toFixed(2)}`);
                     }
                 }
             }
         }
+        enforcementLog.push({ id: inv.id, description: inv.description, level: "full", fired });
     }
     // --- Gate enforcement ---
     // Gates trigger systemic interventions when thresholds are crossed
@@ -92,7 +157,7 @@ function applyGovernanceToReactions(reactions, invariants, gates, roundIndex, cu
         if (gate.severity === "critical") {
             // Critical gates act as circuit breakers — compress all impacts toward zero
             const avgAbsImpact = governed.reduce((s, a) => s + Math.abs(a.impact), 0) / governed.length;
-            if (avgAbsImpact > 0.5 || cumulativeAvgImpact < -0.3) {
+            if (avgAbsImpact > 0.3 || cumulativeAvgImpact < -0.15) {
                 const dampingFactor = 0.6;
                 for (const agent of governed) {
                     const original = agent.impact;
@@ -120,7 +185,7 @@ function applyGovernanceToReactions(reactions, invariants, gates, roundIndex, cu
         agent.impact = Number(agent.impact.toFixed(2));
         agent.confidence = Number(agent.confidence.toFixed(2));
     }
-    return { reactions: governed, interventions };
+    return { reactions: governed, interventions, enforcementLog };
 }
 // ============================================
 // GOVERNED SWARM SIMULATION
@@ -131,13 +196,15 @@ function applyGovernanceToReactions(reactions, invariants, gates, roundIndex, cu
  * Same agents, same scenario, same reaction model —
  * but world rules reshape the outcomes.
  */
-async function runGovernedSwarmSimulation(scenario, stakeholders, paths, config, worldDef, nvWorld, request) {
+async function runGovernedSwarmSimulation(scenario, stakeholders, paths, config, worldDef, nvWorld, request, narrativeEvents) {
     // First run the unmodified simulation to get raw reactions
     const rawResult = await (0, swarmSimulation_1.runSwarmSimulation)(scenario, stakeholders, paths, config);
     // Now re-run applying governance to each round
     const governedRounds = [];
     const allInterventions = [];
     const allGuardVerdicts = [];
+    const allNarrativeImpacts = [];
+    let latestEnforcementLog = [];
     let cumulativeAvgImpact = 0;
     for (const round of rawResult.rounds) {
         // --- Real governance engine: evaluate each agent's action ---
@@ -159,8 +226,17 @@ async function runGovernedSwarmSimulation(scenario, stakeholders, paths, config,
                 }
             }
         }
+        // --- Narrative injection: information shocks ---
+        if (narrativeEvents && narrativeEvents.length > 0) {
+            const roundEvents = (0, narrativeInjection_1.getEventsForRound)(narrativeEvents, round.round);
+            for (const event of roundEvents) {
+                const impact = (0, narrativeInjection_1.injectNarrative)(round.reactions, event, stakeholders);
+                allNarrativeImpacts.push(impact);
+            }
+        }
         // --- Heuristic governance: invariant/gate enforcement (always applied) ---
-        const { reactions: governedReactions, interventions } = applyGovernanceToReactions(round.reactions, worldDef.invariants, worldDef.gates ?? [], round.round, cumulativeAvgImpact);
+        const { reactions: governedReactions, interventions, enforcementLog } = applyGovernanceToReactions(round.reactions, worldDef.invariants, worldDef.gates ?? [], round.round, cumulativeAvgImpact);
+        latestEnforcementLog = [...enforcementLog];
         // Recompute emergent dynamics with governed reactions
         const emergentDynamics = detectGovernedDynamics(governedReactions, interventions);
         governedRounds.push({
@@ -184,6 +260,8 @@ async function runGovernedSwarmSimulation(scenario, stakeholders, paths, config,
         },
         allInterventions,
         guardVerdicts: allGuardVerdicts,
+        narrativeImpacts: allNarrativeImpacts,
+        enforcementLog: latestEnforcementLog,
     };
 }
 function detectGovernedDynamics(reactions, interventions) {
@@ -323,7 +401,7 @@ function buildComparisonNarrative(baseline, governed, worldThesis) {
  *   3. Compare metrics
  *   4. Generate narrative
  */
-async function runGovernedComparison(request, worldLite, paths) {
+async function runGovernedComparison(request, worldLite, paths, narrativeEvents) {
     const stakeholders = (request.stakeholders ?? []).map((s) => typeof s === "string" ? { id: s, disposition: "unknown" } : s);
     const swarmConfig = request.swarm ?? {
         enabled: true,
@@ -336,7 +414,7 @@ async function runGovernedComparison(request, worldLite, paths) {
     const baselineSwarm = await (0, swarmSimulation_1.runSwarmSimulation)(request.scenario, stakeholders, paths, swarmConfig);
     const baselineMetrics = computeMetrics(baselineSwarm);
     // Step 2: Governed — same scenario, world rules applied (real engine + heuristics)
-    const { swarm: governedSwarm, guardVerdicts } = await runGovernedSwarmSimulation(request.scenario, stakeholders, paths, swarmConfig, worldLite, nvWorld, request);
+    const { swarm: governedSwarm, guardVerdicts, narrativeImpacts: collectedNarrativeImpacts, enforcementLog: enforcementClassification } = await runGovernedSwarmSimulation(request.scenario, stakeholders, paths, swarmConfig, worldLite, nvWorld, request, narrativeEvents);
     const governedMetrics = computeMetrics(governedSwarm);
     // Step 3: Build world simulation (deterministic state evolution via real engine)
     let worldSimulation;
@@ -392,6 +470,8 @@ async function runGovernedComparison(request, worldLite, paths) {
         invariantsChecked,
         triggeredGuards: [...triggeredGuardIds],
     };
+    // Step 6: Behavioral analysis — what agents did differently
+    const behavioralAnalysis = (0, behavioralAnalysis_1.analyzeBehavior)(baselineSwarm.rounds, governedSwarm.rounds);
     return {
         scenario: request.scenario,
         worldRules: {
@@ -417,6 +497,9 @@ async function runGovernedComparison(request, worldLite, paths) {
             narrative,
         },
         governanceStats,
+        enforcementClassification: enforcementClassification.length > 0 ? enforcementClassification : undefined,
+        narrativeImpacts: collectedNarrativeImpacts.length > 0 ? collectedNarrativeImpacts : undefined,
+        behavioralAnalysis,
     };
 }
 // ============================================
@@ -478,6 +561,20 @@ exports.TRADING_DEMO = {
             { id: "GATE-002", label: "Contagion Warning", condition: "contagion_spread == systemic", severity: "critical" },
             { id: "GATE-003", label: "Leverage Warning", condition: "leverage_ratio > 8", severity: "warning" },
         ],
+        ai_roles: [
+            {
+                id: "ai_translator",
+                type: "ai",
+                permissions: ["translate_input"],
+                constraints: ["must_output_valid_schema", "no_invention_of_events", "confidence_must_be_provided"],
+            },
+            {
+                id: "ai_analyst",
+                type: "ai",
+                permissions: ["generate_report", "summarize_trace"],
+                constraints: ["must_reference_trace", "must_include_blocked_actions", "must_include_metrics", "no_unverifiable_claims"],
+            },
+        ],
     },
     paths: [
         {