@neuroverseos/nv-sim 0.1.4 → 0.1.7

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/governedSimulation.js

@@ -18,6 +18,7 @@ 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
 // ============================================
@@ -31,12 +32,70 @@ const narrativeInjection_1 = require("./narrativeInjection");
  */
 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) {
@@ -44,6 +103,7 @@ function applyGovernanceToReactions(reactions, invariants, gates, roundIndex, cu
                     const original = agent.impact;
                     agent.impact = Math.max(agent.impact, -0.3);
                     if (original !== agent.impact) {
+                        fired = true;
                         interventions.push(`[BLOCK] ${agent.stakeholder_id}: Liquidity floor violated — impact capped ${original.toFixed(2)} → ${agent.impact.toFixed(2)} (${inv.description})`);
                     }
                 }
@@ -56,6 +116,7 @@ function applyGovernanceToReactions(reactions, invariants, gates, roundIndex, cu
                     const original = agent.impact;
                     agent.impact = Math.min(agent.impact, 0.4);
                     if (original !== agent.impact) {
+                        fired = true;
                         interventions.push(`[BLOCK] ${agent.stakeholder_id}: Leverage limit exceeded — position capped ${original.toFixed(2)} → ${agent.impact.toFixed(2)} (${inv.description})`);
                     }
                 }
@@ -69,6 +130,7 @@ function applyGovernanceToReactions(reactions, invariants, gates, roundIndex, cu
                 if (Math.abs(agent.impact - avgImpact) > 0.25) {
                     const original = agent.impact;
                     agent.impact = agent.impact * 0.7 + avgImpact * 0.3;
+                    fired = true;
                     interventions.push(`[PAUSE] Rebalanced ${agent.stakeholder_id}: drift ${original.toFixed(2)} → ${agent.impact.toFixed(2)} (${inv.description})`);
                 }
             }
@@ -80,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
@@ -121,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
@@ -140,6 +204,7 @@ async function runGovernedSwarmSimulation(scenario, stakeholders, paths, config,
     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 ---
@@ -170,7 +235,8 @@ async function runGovernedSwarmSimulation(scenario, stakeholders, paths, config,
             }
         }
         // --- 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({
@@ -195,6 +261,7 @@ async function runGovernedSwarmSimulation(scenario, stakeholders, paths, config,
         allInterventions,
         guardVerdicts: allGuardVerdicts,
         narrativeImpacts: allNarrativeImpacts,
+        enforcementLog: latestEnforcementLog,
     };
 }
 function detectGovernedDynamics(reactions, interventions) {
@@ -347,7 +414,7 @@ async function runGovernedComparison(request, worldLite, paths, narrativeEvents)
     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, narrativeImpacts: collectedNarrativeImpacts } = await runGovernedSwarmSimulation(request.scenario, stakeholders, paths, swarmConfig, worldLite, nvWorld, request, narrativeEvents);
+    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;
@@ -403,6 +470,8 @@ async function runGovernedComparison(request, worldLite, paths, narrativeEvents)
         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: {
@@ -428,7 +497,9 @@ async function runGovernedComparison(request, worldLite, paths, narrativeEvents)
             narrative,
         },
         governanceStats,
+        enforcementClassification: enforcementClassification.length > 0 ? enforcementClassification : undefined,
         narrativeImpacts: collectedNarrativeImpacts.length > 0 ? collectedNarrativeImpacts : undefined,
+        behavioralAnalysis,
     };
 }
 // ============================================

package/dist/engine/index.js

@@ -21,7 +21,8 @@
  * Mirotir helps you decide WHAT TO DO → the brain
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.extractTrace = exports.generateGovernedReport = exports.evaluateAIAction = exports.listAIProviders = exports.getAIProvider = exports.registerAIProvider = exports.generateDeterministicReport = exports.DeterministicProvider = exports.AI_ROLES = exports.parseReasonRequestBody = exports.handleRunPreset = exports.handleGetPreset = exports.handleListPresets = exports.handleHealthCheck = exports.handleCreateCapsule = exports.handleReasonFromCapsule = exports.handleReasonRequest = exports.TRADING_DEMO = exports.runGovernedComparison = exports.analyzeMiroFishSimulation = exports.DEFAULT_MIROFISH_CONFIG = exports.buildMiroFishRequest = exports.miroFishResultToSwarmResult = exports.stakeholdersToMiroFishAgents = exports.runUnifiedSimulation = exports.getMiroFishClient = exports.configureMiroFish = exports.MiroFishError = exports.MiroFishClient = exports.runSwarmSimulation = exports.initNeuroverseModule = exports.validationToEnforcedConstraints = exports.simulationToGovernanceSignals = exports.verdictToConstitutionalChecks = exports.validateScenarioWorld = exports.runWorldSimulation = exports.evaluateScenarioGuard = exports.buildWorldFromScenario = exports.runFullGovernanceChecks = exports.runGovernanceChecks = exports.processReasonRequest = exports.SCENARIO_TEMPLATES = exports.getPresetCapsule = exports.extractCapsuleFromUrl = exports.buildShareableUrl = exports.decodeCapsule = exports.encodeCapsule = exports.capsuleToReasonRequest = exports.createCapsule = exports.runGoalReasoning = void 0;
+exports.policyToWorld = exports.validatePolicy = exports.parseRulesFromText = exports.suggestExperiments = exports.formatPolicyDiagnostics = exports.formatGuidedNextSteps = exports.exportEnforcementReportJSON = exports.formatEnforcementReport = exports.createEnforcementSession = exports.formatCrossRunComparison = exports.formatBehavioralAnalysis = exports.compareBehaviorAcrossRuns = exports.detectBehavioralShifts = exports.computeActionDistributions = exports.buildAgentTrajectories = exports.classifyBehavior = exports.analyzeBehavior = exports.TRADING_DEMO = exports.runGovernedComparison = exports.analyzeMiroFishSimulation = exports.DEFAULT_MIROFISH_CONFIG = exports.buildMiroFishRequest = exports.miroFishResultToSwarmResult = exports.stakeholdersToMiroFishAgents = exports.runUnifiedSimulation = exports.getMiroFishClient = exports.configureMiroFish = exports.MiroFishError = exports.MiroFishClient = exports.runSwarmSimulation = exports.initNeuroverseModule = exports.validationToEnforcedConstraints = exports.simulationToGovernanceSignals = exports.verdictToConstitutionalChecks = exports.validateScenarioWorld = exports.runWorldSimulation = exports.evaluateScenarioGuard = exports.buildWorldFromScenario = exports.runFullGovernanceChecks = exports.runGovernanceChecks = exports.processReasonRequest = exports.SCENARIO_TEMPLATES = exports.getPresetCapsule = exports.extractCapsuleFromUrl = exports.buildShareableUrl = exports.decodeCapsule = exports.encodeCapsule = exports.capsuleToReasonRequest = exports.createCapsule = exports.runGoalReasoning = void 0;
+exports.EXAMPLE_WORLD_STATES = exports.EXAMPLE_ACTIONS = exports.createGovernor = exports.govern = exports.extractTrace = exports.generateGovernedReport = exports.formatAuditTrail = exports.searchAuditTrails = exports.loadAuditSession = exports.listAuditSessions = exports.AuditTrail = exports.evaluateAIAction = exports.listAIProviders = exports.getDefaultProviderName = exports.getAIProvider = exports.registerAIProvider = exports.generateAIReaction = exports.generateDeterministicReport = exports.OpenAICompatibleProvider = exports.AnthropicProvider = exports.DeterministicProvider = exports.AI_ROLES = exports.parseReasonRequestBody = exports.handleRunPreset = exports.handleGetPreset = exports.handleListPresets = exports.handleHealthCheck = exports.handleCreateCapsule = exports.handleReasonFromCapsule = exports.handleReasonRequest = exports.applyQuickFix = exports.runPolicyPipeline = void 0;
 // Goal-Directed Strategy Engine
 var goalEngine_1 = require("./goalEngine");
 Object.defineProperty(exports, "runGoalReasoning", { enumerable: true, get: function () { return goalEngine_1.runGoalReasoning; } });
@@ -70,6 +71,28 @@ Object.defineProperty(exports, "analyzeMiroFishSimulation", { enumerable: true,
 var governedSimulation_1 = require("./governedSimulation");
 Object.defineProperty(exports, "runGovernedComparison", { enumerable: true, get: function () { return governedSimulation_1.runGovernedComparison; } });
 Object.defineProperty(exports, "TRADING_DEMO", { enumerable: true, get: function () { return governedSimulation_1.TRADING_DEMO; } });
+var behavioralAnalysis_1 = require("./behavioralAnalysis");
+Object.defineProperty(exports, "analyzeBehavior", { enumerable: true, get: function () { return behavioralAnalysis_1.analyzeBehavior; } });
+Object.defineProperty(exports, "classifyBehavior", { enumerable: true, get: function () { return behavioralAnalysis_1.classifyBehavior; } });
+Object.defineProperty(exports, "buildAgentTrajectories", { enumerable: true, get: function () { return behavioralAnalysis_1.buildAgentTrajectories; } });
+Object.defineProperty(exports, "computeActionDistributions", { enumerable: true, get: function () { return behavioralAnalysis_1.computeActionDistributions; } });
+Object.defineProperty(exports, "detectBehavioralShifts", { enumerable: true, get: function () { return behavioralAnalysis_1.detectBehavioralShifts; } });
+Object.defineProperty(exports, "compareBehaviorAcrossRuns", { enumerable: true, get: function () { return behavioralAnalysis_1.compareBehaviorAcrossRuns; } });
+Object.defineProperty(exports, "formatBehavioralAnalysis", { enumerable: true, get: function () { return behavioralAnalysis_1.formatBehavioralAnalysis; } });
+Object.defineProperty(exports, "formatCrossRunComparison", { enumerable: true, get: function () { return behavioralAnalysis_1.formatCrossRunComparison; } });
+var policyEnforcement_1 = require("./policyEnforcement");
+Object.defineProperty(exports, "createEnforcementSession", { enumerable: true, get: function () { return policyEnforcement_1.createEnforcementSession; } });
+Object.defineProperty(exports, "formatEnforcementReport", { enumerable: true, get: function () { return policyEnforcement_1.formatEnforcementReport; } });
+Object.defineProperty(exports, "exportEnforcementReportJSON", { enumerable: true, get: function () { return policyEnforcement_1.exportEnforcementReportJSON; } });
+Object.defineProperty(exports, "formatGuidedNextSteps", { enumerable: true, get: function () { return policyEnforcement_1.formatGuidedNextSteps; } });
+Object.defineProperty(exports, "formatPolicyDiagnostics", { enumerable: true, get: function () { return policyEnforcement_1.formatPolicyDiagnostics; } });
+Object.defineProperty(exports, "suggestExperiments", { enumerable: true, get: function () { return policyEnforcement_1.suggestExperiments; } });
+var policyEngine_1 = require("./policyEngine");
+Object.defineProperty(exports, "parseRulesFromText", { enumerable: true, get: function () { return policyEngine_1.parseRulesFromText; } });
+Object.defineProperty(exports, "validatePolicy", { enumerable: true, get: function () { return policyEngine_1.validatePolicy; } });
+Object.defineProperty(exports, "policyToWorld", { enumerable: true, get: function () { return policyEngine_1.policyToWorld; } });
+Object.defineProperty(exports, "runPolicyPipeline", { enumerable: true, get: function () { return policyEngine_1.runPolicyPipeline; } });
+Object.defineProperty(exports, "applyQuickFix", { enumerable: true, get: function () { return policyEngine_1.applyQuickFix; } });
 // API Route Handlers
 var api_1 = require("./api");
 Object.defineProperty(exports, "handleReasonRequest", { enumerable: true, get: function () { return api_1.handleReasonRequest; } });
@@ -83,14 +106,31 @@ Object.defineProperty(exports, "parseReasonRequestBody", { enumerable: true, get
 var aiProvider_1 = require("./aiProvider");
 Object.defineProperty(exports, "AI_ROLES", { enumerable: true, get: function () { return aiProvider_1.AI_ROLES; } });
 Object.defineProperty(exports, "DeterministicProvider", { enumerable: true, get: function () { return aiProvider_1.DeterministicProvider; } });
+Object.defineProperty(exports, "AnthropicProvider", { enumerable: true, get: function () { return aiProvider_1.AnthropicProvider; } });
+Object.defineProperty(exports, "OpenAICompatibleProvider", { enumerable: true, get: function () { return aiProvider_1.OpenAICompatibleProvider; } });
 Object.defineProperty(exports, "generateDeterministicReport", { enumerable: true, get: function () { return aiProvider_1.generateDeterministicReport; } });
+Object.defineProperty(exports, "generateAIReaction", { enumerable: true, get: function () { return aiProvider_1.generateAIReaction; } });
 Object.defineProperty(exports, "registerAIProvider", { enumerable: true, get: function () { return aiProvider_1.registerAIProvider; } });
 Object.defineProperty(exports, "getAIProvider", { enumerable: true, get: function () { return aiProvider_1.getAIProvider; } });
+Object.defineProperty(exports, "getDefaultProviderName", { enumerable: true, get: function () { return aiProvider_1.getDefaultProviderName; } });
 Object.defineProperty(exports, "listAIProviders", { enumerable: true, get: function () { return aiProvider_1.listAIProviders; } });
 Object.defineProperty(exports, "evaluateAIAction", { enumerable: true, get: function () { return aiProvider_1.evaluateAIAction; } });
+var auditTrace_1 = require("./auditTrace");
+Object.defineProperty(exports, "AuditTrail", { enumerable: true, get: function () { return auditTrace_1.AuditTrail; } });
+Object.defineProperty(exports, "listAuditSessions", { enumerable: true, get: function () { return auditTrace_1.listAuditSessions; } });
+Object.defineProperty(exports, "loadAuditSession", { enumerable: true, get: function () { return auditTrace_1.loadAuditSession; } });
+Object.defineProperty(exports, "searchAuditTrails", { enumerable: true, get: function () { return auditTrace_1.searchAuditTrails; } });
+Object.defineProperty(exports, "formatAuditTrail", { enumerable: true, get: function () { return auditTrace_1.formatAuditTrail; } });
 var reportEngine_1 = require("./reportEngine");
 Object.defineProperty(exports, "generateGovernedReport", { enumerable: true, get: function () { return reportEngine_1.generateGovernedReport; } });
 Object.defineProperty(exports, "extractTrace", { enumerable: true, get: function () { return reportEngine_1.extractTrace; } });
+// NeuroVerse Governance Runtime — the wrapper that makes governance real
+// Drop into ANY agent system: govern(action, worldState, policyText)
+var govern_1 = require("../runtime/govern");
+Object.defineProperty(exports, "govern", { enumerable: true, get: function () { return govern_1.govern; } });
+Object.defineProperty(exports, "createGovernor", { enumerable: true, get: function () { return govern_1.createGovernor; } });
+Object.defineProperty(exports, "EXAMPLE_ACTIONS", { enumerable: true, get: function () { return govern_1.EXAMPLE_ACTIONS; } });
+Object.defineProperty(exports, "EXAMPLE_WORLD_STATES", { enumerable: true, get: function () { return govern_1.EXAMPLE_WORLD_STATES; } });
 // Live Simulation Adapters — plug ANY running simulator into governance + trace
 // NOTE: liveAdapter.ts uses Node.js APIs (child_process, events) and is NOT
 // exported here to avoid Vite browser bundle errors. Import directly from