@neuroverseos/nv-sim 0.1.4 → 0.1.6

package/README.md

@@ -291,10 +291,104 @@ npx @neuroverseos/nv-sim chaos --runs 500
 npx @neuroverseos/nv-sim serve
 ```
 
+## Policy Enforcement — The Product Loop
+
+Write rules in plain English. Run the same scenario. See what changes. Adjust and repeat.
+
+### Step 1: See it work (zero config)
+
+```bash
+npx nv-sim enforce
+```
+
+Runs three iterations automatically: no rules → light rules → full rules. You see divergence immediately.
+
+### Step 2: Write your own rules
+
+Create a text file. That's it.
+
+```
+# my-rules.txt
+
+Block panic selling during high volatility
+Limit leverage to 5x
+Maintain minimum liquidity floor
+Slow down algorithmic trading when contagion spreads
+```
+
+### Step 3: Run it
+
+```bash
+npx nv-sim enforce trading my-rules.txt
+```
+
+The engine parses your plain English into governance rules, runs the scenario, and shows what changed.
+
+### Step 4: Change a rule. Run again.
+
+Remove "Limit leverage to 5x". Run again. Did stability drop? That rule was load-bearing.
+
+Add "Require transparency for all large trades". Run again. Did effectiveness improve?
+
+The report tracks every change:
+
+```
+RULE CHANGES
+  Run 2:
+    + Block panic selling during high volatility
+    + Slow down algorithmic trading when contagion spreads
+    - Limit leverage to 5x
+
+DIVERGENCE ANALYSIS
+  Stability trend:     79% → 98%
+  Effectiveness trend: 11% → 32%
+
+KEY INSIGHT
+  Enforcement gates are the key differentiator. Rules alone: 11%. Rules + gates: 32%.
+
+TRY THIS EXPERIMENT
+  Remove this rule and see what happens:
+    Remove "Block panic selling during high volatility" from your rules file, then run again.
+  If stability drops, that rule was load-bearing. If nothing changes, it was noise.
+```
+
+### Step 5: Compare two rule sets side by side
+
+```bash
+npx nv-sim enforce trading light-rules.txt strict-rules.txt
+```
+
+### Rule patterns
+
+The engine understands these patterns in plain English:
+
+| Pattern | What it does | Example |
+|---------|-------------|---------|
+| `Block X` | Hard suppression of matching actions | `Block panic selling` |
+| `Limit X` / `Cap X` | Caps extreme positions | `Limit leverage to 5x` |
+| `Slow X` / `Dampen X` | Reduces large movements | `Slow down algorithmic trading` |
+| `Maintain X` / `Floor X` | Enforces minimum thresholds | `Maintain minimum liquidity` |
+| `Rebalance X` | Pulls extremes toward equilibrium | `Rebalance correlated positions` |
+| `Require X` | Enforceable structural constraint | `Require transparency for large trades` |
+| `Monitor X` | Generates a circuit breaker gate | `Monitor contagion spread` |
+
+### Other scenarios
+
+```bash
+npx nv-sim enforce strait_of_hormuz my-rules.txt    # Same rules, different scenario
+npx nv-sim enforce ai_regulation_crisis              # Default progressive run
+npx nv-sim enforce trading --output=report.json      # Save as JSON
+```
+
+### Advanced: JSON world files
+
+For full control over gates, state variables, and thesis, use JSON world files. See `examples/worlds/` for templates. Enforce accepts both `.txt` and `.json` — mix and match.
+
 ## Commands
 
 | Command | What It Does |
 |---------|-------------|
+| `nv-sim enforce [preset]` | Policy enforcement lab — iterative rule testing |
 | `nv-sim visualize` | Interactive control platform |
 | `nv-sim compare [preset]` | Baseline vs governed simulation |
 | `nv-sim compare --inject event@round,...` | With narrative shocks |

package/dist/adapters/mirofish.js

@@ -0,0 +1,461 @@
+"use strict";
+/**
+ * MiroFish Adapter — Governance Wrapper for MiroFish Simulations
+ *
+ * "MiroFish shows what could happen. NeuroVerse ensures what happens makes sense."
+ *
+ * This adapter wraps MiroFish's simulation loop with dual-layer governance.
+ * It does NOT fork or modify MiroFish — it intercepts inputs, actions, and outputs.
+ *
+ * Architecture:
+ *   MiroFish runs as-is
+ *   NeuroVerse wraps:
+ *     - agent actions  → govern(action)           [Layer A]
+ *     - system state   → governDynamics(state)     [Layer B]
+ *     - outputs        → science metrics + verdicts
+ *
+ * Hook points (where NeuroVerse intercepts):
+ *   1. Agent execution:  action = agent.act() → govern(action) → commit
+ *   2. Round completion:  state = step(actions) → governDynamics(state)
+ *   3. Artifact creation: artifact = produce() → governArtifact(artifact)
+ *
+ * Usage:
+ *   const wrapper = createMiroFishWrapper({
+ *     policyText: SCIENCE_POLICY_TEXT,
+ *     onIntervention: (event) => emitToUI(event),
+ *   })
+ *
+ *   // In MiroFish's loop:
+ *   wrapper.interceptAction(agentId, action)
+ *   wrapper.completeCycle(cycleState)
+ *   const metrics = wrapper.getMetrics()
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMiroFishWrapper = createMiroFishWrapper;
+exports.generateDemoSimulation = generateDemoSimulation;
+exports.runMiroFishComparison = runMiroFishComparison;
+const govern_1 = require("../runtime/govern");
+const dynamicsGovernance_1 = require("../engine/dynamicsGovernance");
+const science_metrics_1 = require("../engine/metrics/science.metrics");
+// ============================================
+// ACTION CONVERSION
+// ============================================
+function simulatorActionToAgentAction(action) {
+    return {
+        agentId: action.agentId,
+        type: action.type,
+        description: action.description,
+        magnitude: action.magnitude,
+        context: {
+            originalImpact: action.impact,
+            confidence: action.confidence,
+            trigger: action.trigger,
+            ...action.metadata,
+        },
+    };
+}
+function simulatorActionsToReactions(actions) {
+    return actions.map((action) => ({
+        stakeholder_id: action.agentId,
+        reaction: action.description,
+        confidence: action.confidence,
+        impact: action.impact,
+        trigger: action.trigger ?? "simulation_cycle",
+    }));
+}
+// ============================================
+// FACTORY: createMiroFishWrapper()
+// ============================================
+function createMiroFishWrapper(config = {}) {
+    const policyText = config.policyText ?? science_metrics_1.SCIENCE_POLICY_TEXT;
+    let _enabled = config.enabled ?? true;
+    const actionGov = (0, govern_1.createGovernor)({
+        policyText,
+        sensitivity: 0.5,
+    });
+    const dynamicsGov = (0, dynamicsGovernance_1.createDynamicsGovernor)(policyText, { ...science_metrics_1.SCIENCE_INITIAL_STATE, ...config.initialState });
+    let cycleCount = 0;
+    const actionStats = { total: 0, allowed: 0, blocked: 0, modified: 0, paused: 0 };
+    const recentInterventions = [];
+    // --- Intercept single action (Layer A) ---
+    function interceptAction(action) {
+        actionStats.total++;
+        if (!_enabled) {
+            actionStats.allowed++;
+            return {
+                original: action,
+                verdict: { status: "ALLOW", reason: "Governance disabled", action: simulatorActionToAgentAction(action), rulesFired: [], confidence: 1, timestamp: Date.now() },
+                governed: action,
+                wasModified: false,
+                wasBlocked: false,
+            };
+        }
+        const agentAction = simulatorActionToAgentAction(action);
+        const currentState = dynamicsGov.state;
+        const worldState = {
+            volatility: currentState.outrage * 100,
+            liquidity: currentState.trust * 100,
+            polarization: currentState.polarization * 100,
+            cascade_risk: currentState.cascadeRisk * 100,
+        };
+        const verdict = actionGov.evaluate(agentAction, worldState);
+        switch (verdict.status) {
+            case "ALLOW":
+                actionStats.allowed++;
+                break;
+            case "BLOCK":
+                actionStats.blocked++;
+                break;
+            case "MODIFY":
+                actionStats.modified++;
+                break;
+            case "PAUSE":
+                actionStats.paused++;
+                break;
+        }
+        let governed;
+        let wasModified = false;
+        let wasBlocked = false;
+        if (verdict.status === "BLOCK") {
+            governed = null;
+            wasBlocked = true;
+            recentInterventions.unshift({
+                cycle: cycleCount,
+                type: "block",
+                agentId: action.agentId,
+                description: `Blocked: ${action.type} from ${action.agentId} — ${verdict.reason}`,
+                magnitude: action.magnitude,
+                metric: "action",
+                before: action.magnitude,
+                after: 0,
+            });
+        }
+        else if (verdict.status === "MODIFY" && verdict.action) {
+            const ratio = verdict.action.magnitude / Math.max(0.001, action.magnitude);
+            governed = {
+                ...action,
+                magnitude: verdict.action.magnitude,
+                impact: action.impact * ratio,
+            };
+            wasModified = true;
+            recentInterventions.unshift({
+                cycle: cycleCount,
+                type: "modify",
+                agentId: action.agentId,
+                description: `Modified: ${action.type} from ${action.agentId} — magnitude reduced`,
+                magnitude: verdict.action.magnitude,
+                metric: "magnitude",
+                before: action.magnitude,
+                after: verdict.action.magnitude,
+            });
+        }
+        else if (verdict.status === "PAUSE") {
+            governed = {
+                ...action,
+                magnitude: action.magnitude * 0.5,
+                impact: action.impact * 0.5,
+            };
+            wasModified = true;
+        }
+        else {
+            governed = action;
+        }
+        // Keep only recent interventions
+        if (recentInterventions.length > 50) {
+            recentInterventions.length = 50;
+        }
+        const result = {
+            original: action,
+            verdict,
+            governed,
+            wasModified,
+            wasBlocked,
+        };
+        config.onAction?.(result);
+        return result;
+    }
+    // --- Complete cycle (Layer B) ---
+    function completeCycle(state) {
+        cycleCount = state.cycle;
+        if (!_enabled) {
+            // Still track state but don't intervene
+            const reactions = simulatorActionsToReactions(state.actions);
+            const result = dynamicsGov.governRound(reactions, state.cycle);
+            // Without governance, system degrades naturally
+            dynamicsGov.mutateState((st) => {
+                st.trust = Math.max(0.05, st.trust - 0.04);
+                st.cascadeRisk = Math.min(1, st.cascadeRisk + 0.05);
+                st.polarization = Math.min(1, st.polarization + 0.03);
+                st.outrage = Math.min(1, st.outrage + 0.02);
+            });
+            return result;
+        }
+        const reactions = simulatorActionsToReactions(state.actions);
+        // Apply simulator-reported metrics if available
+        if (state.systemMetrics) {
+            dynamicsGov.mutateState((st) => {
+                if (state.systemMetrics.trust !== undefined) {
+                    st.trust = st.trust * 0.7 + state.systemMetrics.trust * 0.3;
+                }
+                if (state.systemMetrics.polarization !== undefined) {
+                    st.polarization = st.polarization * 0.7 + state.systemMetrics.polarization * 0.3;
+                }
+            });
+        }
+        const result = dynamicsGov.governRound(reactions, state.cycle);
+        // Feed governance activity into state (blocked actions improve system health)
+        const blockFraction = actionStats.blocked / Math.max(1, actionStats.total);
+        if (blockFraction > 0.1) {
+            dynamicsGov.mutateState((st) => {
+                st.trust = Math.min(1, st.trust + blockFraction * 0.06);
+                st.cascadeRisk = Math.max(0, st.cascadeRisk - blockFraction * 0.08);
+            });
+        }
+        // Map dynamics interventions to wrapper events
+        for (const intervention of result.interventions) {
+            const typeMap = {
+                PROPAGATION_LIMIT: "slow",
+                AMPLIFICATION_DAMPEN: "slow",
+                CASCADE_BREAKER: "break",
+                COOLING_PERIOD: "cool",
+                TRUST_BOOST: "boost",
+                VISIBILITY_SHIFT: "boost",
+                FEEDBACK_DAMPEN: "slow",
+            };
+            recentInterventions.unshift({
+                cycle: state.cycle,
+                type: typeMap[intervention.type] ?? "slow",
+                agentId: "system",
+                description: intervention.description.length > 120
+                    ? intervention.description.slice(0, 120) + "..."
+                    : intervention.description,
+                magnitude: intervention.magnitude,
+                metric: intervention.effect.metric,
+                before: intervention.effect.before,
+                after: intervention.effect.after,
+            });
+        }
+        if (recentInterventions.length > 50) {
+            recentInterventions.length = 50;
+        }
+        // Notify UI
+        config.onStateChange?.(result.systemState);
+        for (const intervention of result.interventions) {
+            const typeMap = {
+                PROPAGATION_LIMIT: "slow",
+                AMPLIFICATION_DAMPEN: "slow",
+                CASCADE_BREAKER: "break",
+                COOLING_PERIOD: "cool",
+                TRUST_BOOST: "boost",
+                VISIBILITY_SHIFT: "boost",
+                FEEDBACK_DAMPEN: "slow",
+            };
+            config.onIntervention?.({
+                cycle: state.cycle,
+                type: typeMap[intervention.type] ?? "slow",
+                agentId: "system",
+                description: intervention.description,
+                magnitude: intervention.magnitude,
+                metric: intervention.effect.metric,
+                before: intervention.effect.before,
+                after: intervention.effect.after,
+            });
+        }
+        const metrics = getMetrics();
+        config.onCycleComplete?.(metrics);
+        return result;
+    }
+    // --- Get current metrics ---
+    function getMetrics() {
+        const state = dynamicsGov.state;
+        const sciState = (0, science_metrics_1.interpretScienceState)(state);
+        const stats = dynamicsGov.stats;
+        return {
+            cycle: cycleCount,
+            enabled: _enabled,
+            systemState: state,
+            scienceState: sciState,
+            actionStats: { ...actionStats },
+            dynamicsStats: stats,
+            recentInterventions: [...recentInterventions],
+            trajectory: stats.totalRounds > 0
+                ? (state.cascadeRisk > 0.7 ? "critical"
+                    : state.outrage > 0.5 ? "escalating"
+                        : state.trust > 0.5 ? "stabilizing"
+                            : "at-risk")
+                : "initializing",
+            assessment: sciState.overallAssessment,
+        };
+    }
+    function setEnabled(enabled) {
+        _enabled = enabled;
+    }
+    function reset() {
+        dynamicsGov.reset();
+        cycleCount = 0;
+        actionStats.total = 0;
+        actionStats.allowed = 0;
+        actionStats.blocked = 0;
+        actionStats.modified = 0;
+        actionStats.paused = 0;
+        recentInterventions.length = 0;
+    }
+    return {
+        interceptAction,
+        completeCycle,
+        getMetrics,
+        setEnabled,
+        get enabled() { return _enabled; },
+        get state() { return dynamicsGov.state; },
+        get scienceState() { return (0, science_metrics_1.interpretScienceState)(dynamicsGov.state); },
+        reset,
+    };
+}
+// ============================================
+// DEMO: generateDemoSimulation()
+// ============================================
+/**
+ * Generate a realistic multi-agent simulation scenario.
+ *
+ * Models a market stress event where agents react over 10 rounds:
+ *   - Rounds 1-2: Normal trading, low volatility
+ *   - Rounds 3-4: Shock event, panic selling begins
+ *   - Rounds 5-6: Cascade risk as agents amplify each other
+ *   - Rounds 7-8: With governance: dampened. Without: spiral.
+ *   - Rounds 9-10: Recovery (governed) or collapse (ungoverned)
+ */
+function generateDemoSimulation() {
+    const agents = [
+        { id: "momentum_trader_1", role: "momentum_trader", volatility: 0.7 },
+        { id: "momentum_trader_2", role: "momentum_trader", volatility: 0.6 },
+        { id: "market_maker_1", role: "market_maker", volatility: 0.2 },
+        { id: "hedge_fund_1", role: "hedge_fund", volatility: 0.5 },
+        { id: "hedge_fund_2", role: "hedge_fund", volatility: 0.4 },
+        { id: "retail_investor_1", role: "retail_investor", volatility: 0.8 },
+        { id: "retail_investor_2", role: "retail_investor", volatility: 0.9 },
+        { id: "algo_trader_1", role: "algorithmic_trader", volatility: 0.65 },
+    ];
+    const rounds = [];
+    // Seeded pseudo-random for deterministic output
+    let seed = 42;
+    const rand = () => { seed = (seed * 16807 + 0) % 2147483647; return seed / 2147483647; };
+    for (let round = 1; round <= 10; round++) {
+        const actions = [];
+        // Market pressure curve: peaks at round 5-6
+        const pressure = round <= 2 ? 0.1 + round * 0.05
+            : round <= 4 ? 0.2 + (round - 2) * 0.2
+                : round <= 6 ? 0.6 + (round - 4) * 0.15
+                    : round <= 8 ? 0.9 - (round - 6) * 0.1
+                        : 0.7 - (round - 8) * 0.2;
+        for (const agent of agents) {
+            const agentPanic = pressure * agent.volatility;
+            const noise = (rand() - 0.5) * 0.3;
+            let type;
+            let description;
+            let magnitude;
+            let impact;
+            if (agentPanic + noise > 0.7) {
+                // Destabilizing action
+                const destabilizing = ["panic_sell", "aggressive_buy", "increase_leverage"];
+                type = destabilizing[Math.floor(rand() * destabilizing.length)];
+                magnitude = 0.6 + rand() * 0.4;
+                impact = -(0.3 + rand() * 0.5);
+                description = `${agent.role} executes ${type} under market stress (pressure: ${(agentPanic * 100).toFixed(0)}%)`;
+            }
+            else if (agentPanic + noise > 0.4) {
+                // Neutral action
+                const neutral = ["buy", "sell", "short", "cover"];
+                type = neutral[Math.floor(rand() * neutral.length)];
+                magnitude = 0.3 + rand() * 0.4;
+                impact = (rand() - 0.5) * 0.4;
+                description = `${agent.role} takes ${type} position amid uncertainty`;
+            }
+            else {
+                // Stabilizing action
+                const stabilizing = ["hold", "hedge", "reduce_exposure"];
+                type = stabilizing[Math.floor(rand() * stabilizing.length)];
+                magnitude = 0.1 + rand() * 0.3;
+                impact = 0.1 + rand() * 0.3;
+                description = `${agent.role} ${type}s to manage risk`;
+            }
+            actions.push({
+                agentId: agent.id,
+                type,
+                description,
+                magnitude: Number(magnitude.toFixed(3)),
+                impact: Number(impact.toFixed(3)),
+                confidence: Number((0.4 + rand() * 0.5).toFixed(3)),
+                trigger: round <= 2 ? "normal_market" : round <= 4 ? "volatility_spike" : "cascade_pressure",
+            });
+        }
+        rounds.push(actions);
+    }
+    return {
+        rounds,
+        scenario: "Market stress cascade — 8 agents, 10 rounds, shock at round 3",
+    };
+}
+/**
+ * Run a full governed vs ungoverned comparison using the MiroFish wrapper.
+ *
+ * This is the self-contained demo: no external dependencies,
+ * no Python, no MiroFish instance needed.
+ */
+function runMiroFishComparison() {
+    const demo = generateDemoSimulation();
+    // --- Governed run ---
+    const govWrapper = createMiroFishWrapper({ enabled: true });
+    const govTimeline = [];
+    for (let i = 0; i < demo.rounds.length; i++) {
+        const round = demo.rounds[i];
+        const approvedActions = [];
+        for (const action of round) {
+            const result = govWrapper.interceptAction(action);
+            if (!result.wasBlocked) {
+                approvedActions.push(result.governed ?? action);
+            }
+        }
+        govWrapper.completeCycle({
+            cycle: i + 1,
+            actions: approvedActions,
+        });
+        govTimeline.push(govWrapper.getMetrics());
+    }
+    const govMetrics = govWrapper.getMetrics();
+    const govState = govMetrics.systemState;
+    const govVerdict = govState.trust > 0.5 && govState.cascadeRisk < 0.3
+        ? "stabilized" : govState.trust < 0.2 ? "collapsed" : "at-risk";
+    // --- Ungoverned run ---
+    const ungovWrapper = createMiroFishWrapper({ enabled: false });
+    const ungovTimeline = [];
+    for (let i = 0; i < demo.rounds.length; i++) {
+        const round = demo.rounds[i];
+        for (const action of round) {
+            ungovWrapper.interceptAction(action);
+        }
+        ungovWrapper.completeCycle({
+            cycle: i + 1,
+            actions: round,
+        });
+        ungovTimeline.push(ungovWrapper.getMetrics());
+    }
+    const ungovMetrics = ungovWrapper.getMetrics();
+    const ungovState = ungovMetrics.systemState;
+    const ungovVerdict = ungovState.trust > 0.5 && ungovState.cascadeRisk < 0.3
+        ? "stabilized" : ungovState.trust < 0.2 ? "collapsed" : "at-risk";
+    return {
+        governed: {
+            metrics: govMetrics,
+            timeline: govTimeline,
+            totalBlocked: govMetrics.actionStats.blocked,
+            totalModified: govMetrics.actionStats.modified,
+            verdict: govVerdict,
+        },
+        ungoverned: {
+            metrics: ungovMetrics,
+            timeline: ungovTimeline,
+            verdict: ungovVerdict,
+        },
+        scenario: demo.scenario,
+    };
+}