@neuroverseos/nv-sim 0.1.0

package/dist/engine/cli.js

@@ -0,0 +1,803 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * nv-sim — NeuroVerse Simulation CLI
+ *
+ * "Simulators show what agents might do.
+ *  NeuroVerse shows what happens when systems have rules."
+ *
+ * Usage:
+ *   npx nv-sim compare                     # Flash crash demo (default)
+ *   npx nv-sim compare strait_of_hormuz    # Geopolitical demo
+ *   npx nv-sim analyze simulation.json     # Analyze a simulation file
+ *   npx nv-sim preset strait_of_hormuz     # Run reasoning preset
+ *   npx nv-sim presets                     # List available presets
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const analyzer_1 = require("./analyzer");
+const api_1 = require("./api");
+const governedSimulation_1 = require("./governedSimulation");
+const chaosEngine_1 = require("./chaosEngine");
+const scenarioCapsule_1 = require("./scenarioCapsule");
+const fs = __importStar(require("fs"));
+const http = __importStar(require("http"));
+// ============================================
+// CLI ARGUMENT PARSING
+// ============================================
+const args = process.argv.slice(2);
+const command = args[0];
+async function main() {
+    // Initialize the real @neuroverseos/governance engine (lazy-loaded)
+    const { initNeuroverseModule } = await Promise.resolve().then(() => __importStar(require("./worldBridge")));
+    const governanceLoaded = await initNeuroverseModule();
+    if (governanceLoaded) {
+        console.log("  [nv-engine] @neuroverseos/governance loaded ✓");
+    }
+    switch (command) {
+        case "compare": {
+            const presetId = args[1] || "trading";
+            console.log(`\n  NV-SIM — Governed Simulation Comparison\n`);
+            console.log(`  "We ran the same simulation twice.`);
+            console.log(`   The only difference was the world rules."\n`);
+            console.log("  " + "=".repeat(60));
+            let result;
+            let worldId;
+            if (presetId === "trading" || presetId === "flash_crash") {
+                console.log(`  Scenario: Flash Crash — Algorithmic Cascade\n`);
+                worldId = "trading-flash-crash";
+                result = await (0, governedSimulation_1.runGovernedComparison)(governedSimulation_1.TRADING_DEMO.scenario, governedSimulation_1.TRADING_DEMO.world, governedSimulation_1.TRADING_DEMO.paths);
+            }
+            else {
+                // Try to use an existing preset
+                const template = scenarioCapsule_1.SCENARIO_TEMPLATES[presetId];
+                if (!template) {
+                    console.error(`  Unknown preset: ${presetId}`);
+                    console.error(`  Available: trading, flash_crash, ${Object.keys(scenarioCapsule_1.SCENARIO_TEMPLATES).join(", ")}`);
+                    process.exit(1);
+                }
+                if (!template.world?.inline_definition) {
+                    console.error(`  Preset "${presetId}" has no world definition for comparison.`);
+                    process.exit(1);
+                }
+                console.log(`  Scenario: ${template.title}\n`);
+                worldId = template.world.world_id;
+                const request = {
+                    scenario: template.scenario,
+                    stakeholders: template.stakeholders,
+                    assumptions: template.assumptions,
+                    constraints: template.constraints,
+                    depth: template.depth,
+                    swarm: template.swarm,
+                };
+                const paths = [
+                    {
+                        id: "path_primary",
+                        label: "Primary Response",
+                        description: "The most likely course of action given the scenario",
+                        projected_outcome: "Moderate disruption with cascading effects",
+                        probability: 0.6,
+                        risk: "high",
+                        tradeoffs: ["Speed vs. thoroughness", "Short-term vs. long-term"],
+                        benefits_stakeholders: template.stakeholders.filter(s => s.disposition === "supportive").map(s => s.id),
+                        harms_stakeholders: template.stakeholders.filter(s => s.disposition === "hostile").map(s => s.id),
+                    },
+                    {
+                        id: "path_defensive",
+                        label: "Defensive Posture",
+                        description: "Conservative approach prioritizing stability over opportunity",
+                        projected_outcome: "Reduced damage but slower recovery",
+                        probability: 0.7,
+                        risk: "moderate",
+                        tradeoffs: ["Safety vs. opportunity cost", "Coordination cost vs. independence"],
+                        benefits_stakeholders: template.stakeholders.filter(s => s.disposition !== "hostile").map(s => s.id),
+                        harms_stakeholders: [],
+                    },
+                ];
+                result = await (0, governedSimulation_1.runGovernedComparison)(request, template.world.inline_definition, paths);
+            }
+            printComparisonResults(result, worldId);
+            break;
+        }
+        case "analyze": {
+            const filePath = args[1];
+            let input;
+            if (filePath) {
+                if (!fs.existsSync(filePath)) {
+                    console.error(`File not found: ${filePath}`);
+                    process.exit(1);
+                }
+                input = fs.readFileSync(filePath, "utf-8");
+            }
+            else {
+                const chunks = [];
+                for await (const chunk of process.stdin) {
+                    chunks.push(chunk);
+                }
+                input = Buffer.concat(chunks).toString("utf-8");
+            }
+            if (!input.trim()) {
+                console.error("No simulation data provided.");
+                console.error("Usage: npx nv-sim analyze simulation.json");
+                console.error("   or: cat simulation.json | npx nv-sim analyze");
+                process.exit(1);
+            }
+            console.log("\n  NV-SIM — Analyzing simulation...\n");
+            const result = await (0, analyzer_1.analyzeMiroFishSimulation)({
+                simulation: input,
+                question: args[2],
+            });
+            if ("error" in result && result.status === "error") {
+                console.error(`  Error: ${result.error.message}`);
+                if (result.error.detail) {
+                    console.error(`  Detail: ${result.error.detail}`);
+                }
+                process.exit(1);
+            }
+            const analysis = "reasoning" in result ? result : null;
+            if (!analysis || !("simulation_insights" in analysis)) {
+                console.error("  Unexpected response format");
+                process.exit(1);
+            }
+            // Print narrative
+            console.log("  NARRATIVE");
+            console.log("  " + "=".repeat(60));
+            console.log(`  ${analysis.simulation_insights.narrative}\n`);
+            // Print emergent patterns
+            if (analysis.simulation_insights.emergent_patterns.length > 0) {
+                console.log("  EMERGENT PATTERNS");
+                console.log("  " + "-".repeat(40));
+                for (const pattern of analysis.simulation_insights.emergent_patterns) {
+                    console.log(`  [${pattern.strength.toUpperCase()}] ${pattern.pattern}`);
+                    console.log(`         ${pattern.significance}\n`);
+                }
+            }
+            // Print dominant strategies
+            console.log("  DOMINANT STRATEGIES");
+            console.log("  " + "-".repeat(40));
+            for (const strategy of analysis.simulation_insights.dominant_strategies) {
+                console.log(`  ${strategy.agent_id}: ${strategy.strategy}`);
+                console.log(`         Effectiveness: ${(strategy.effectiveness * 100).toFixed(0)}% — ${strategy.why_it_works}\n`);
+            }
+            // Print coalitions
+            if (analysis.simulation_insights.coalitions.length > 0) {
+                console.log("  COALITIONS");
+                console.log("  " + "-".repeat(40));
+                for (const coalition of analysis.simulation_insights.coalitions) {
+                    console.log(`  ${coalition.members.join(" + ")} (strength: ${(coalition.strength * 100).toFixed(0)}%)`);
+                    console.log(`         Basis: ${coalition.basis}`);
+                    if (coalition.threat_to.length > 0) {
+                        console.log(`         Threatens: ${coalition.threat_to.join(", ")}\n`);
+                    }
+                }
+            }
+            // Print power dynamics
+            console.log("  POWER DYNAMICS");
+            console.log("  " + "-".repeat(40));
+            for (const dynamic of analysis.simulation_insights.power_dynamics) {
+                console.log(`  ${dynamic.agent_id}: ${dynamic.role.toUpperCase()} (influence: ${(dynamic.influence * 100).toFixed(0)}%)`);
+            }
+            console.log();
+            // Print equilibrium
+            console.log("  EQUILIBRIUM");
+            console.log("  " + "-".repeat(40));
+            console.log(`  Status: ${analysis.simulation_insights.equilibrium.type.toUpperCase()}`);
+            console.log(`  Stability: ${(analysis.simulation_insights.equilibrium.stability * 100).toFixed(0)}%`);
+            console.log(`  ${analysis.simulation_insights.equilibrium.description}\n`);
+            // Print fragile points
+            if (analysis.simulation_insights.fragile_points.length > 0) {
+                console.log("  FRAGILE POINTS");
+                console.log("  " + "-".repeat(40));
+                for (const fp of analysis.simulation_insights.fragile_points) {
+                    console.log(`  [${fp.fragility.toUpperCase()}] ${fp.assumption}`);
+                    console.log(`         ${fp.what_breaks}\n`);
+                }
+            }
+            // Print recommendations
+            console.log("  RECOMMENDATIONS");
+            console.log("  " + "=".repeat(60));
+            for (const rec of analysis.reasoning.analysis.recommendations) {
+                console.log(`  ${rec.priority}. ${rec.action}`);
+                console.log(`     ${rec.rationale}`);
+                console.log(`     Timeframe: ${rec.timeframe}\n`);
+            }
+            console.log("  Powered by NeuroVerse Governance\n");
+            break;
+        }
+        case "chaos":
+        case "stress": {
+            // Parse args: first non-flag arg after command is presetId
+            const chaosArgs = args.slice(1);
+            let presetId = "trading";
+            let runs = 100;
+            let seed;
+            for (let i = 0; i < chaosArgs.length; i++) {
+                if (chaosArgs[i] === "--runs" && chaosArgs[i + 1]) {
+                    runs = parseInt(chaosArgs[++i], 10);
+                }
+                else if (chaosArgs[i] === "--seed" && chaosArgs[i + 1]) {
+                    seed = parseInt(chaosArgs[++i], 10);
+                }
+                else if (!chaosArgs[i].startsWith("--")) {
+                    presetId = chaosArgs[i];
+                }
+            }
+            console.log(`\n  NV-SIM CHAOS TEST\n`);
+            console.log(`  "Under what conditions does this system break?"\n`);
+            console.log("  " + "=".repeat(60));
+            console.log(`  Scenario: ${presetId}`);
+            console.log(`  Runs: ${runs}${seed !== undefined ? ` (seed: ${seed})` : ""}\n`);
+            const startMsg = `  Running ${runs} randomized simulations...`;
+            process.stdout.write(startMsg);
+            let lastPct = 0;
+            const result = await (0, chaosEngine_1.runChaosTest)(presetId, {
+                runs,
+                seed,
+                onProgress: (completed, total) => {
+                    const pct = Math.floor(completed / total * 100);
+                    if (pct > lastPct) {
+                        process.stdout.write(`\r  Running ${runs} randomized simulations... ${pct}%`);
+                        lastPct = pct;
+                    }
+                },
+            });
+            process.stdout.write(`\r  Completed ${runs} simulations in ${(result.durationMs / 1000).toFixed(1)}s      \n\n`);
+            printChaosResults(result);
+            break;
+        }
+        case "visualize":
+        case "view": {
+            const presetId = args[1] || "trading";
+            console.log(`\n  NV-SIM — Running simulation for visualization...\n`);
+            let comparisonResult;
+            if (presetId === "trading" || presetId === "flash_crash") {
+                comparisonResult = await (0, governedSimulation_1.runGovernedComparison)(governedSimulation_1.TRADING_DEMO.scenario, governedSimulation_1.TRADING_DEMO.world, governedSimulation_1.TRADING_DEMO.paths);
+            }
+            else {
+                const template = scenarioCapsule_1.SCENARIO_TEMPLATES[presetId];
+                if (!template || !template.world?.inline_definition) {
+                    console.error(`  Unknown or incomplete preset: ${presetId}`);
+                    process.exit(1);
+                }
+                const request = {
+                    scenario: template.scenario,
+                    stakeholders: template.stakeholders,
+                    assumptions: template.assumptions,
+                    constraints: template.constraints,
+                    depth: template.depth,
+                    swarm: template.swarm,
+                };
+                const paths = [
+                    {
+                        id: "path_primary", label: "Primary Response",
+                        description: "Most likely course of action",
+                        projected_outcome: "Moderate disruption", probability: 0.6,
+                        risk: "high", tradeoffs: ["Speed vs. thoroughness"],
+                        benefits_stakeholders: template.stakeholders.filter(s => s.disposition === "supportive").map(s => s.id),
+                        harms_stakeholders: template.stakeholders.filter(s => s.disposition === "hostile").map(s => s.id),
+                    },
+                    {
+                        id: "path_defensive", label: "Defensive Posture",
+                        description: "Conservative approach", projected_outcome: "Reduced damage",
+                        probability: 0.7, risk: "moderate", tradeoffs: ["Safety vs. opportunity"],
+                        benefits_stakeholders: template.stakeholders.filter(s => s.disposition !== "hostile").map(s => s.id),
+                        harms_stakeholders: [],
+                    },
+                ];
+                comparisonResult = await (0, governedSimulation_1.runGovernedComparison)(request, template.world.inline_definition, paths);
+            }
+            console.log("  Starting local visualizer...\n");
+            await startVisualizer(comparisonResult, presetId);
+            break;
+        }
+        case "preset": {
+            const presetId = args[1];
+            if (!presetId) {
+                console.error("Usage: npx nv-sim preset <preset_id>");
+                console.error("Run `npx nv-sim presets` to see available presets.");
+                process.exit(1);
+            }
+            console.log(`\n  NV-SIM — Running preset: ${presetId}...\n`);
+            const result = await (0, api_1.handleRunPreset)(presetId);
+            if ("error" in result && result.status === "error") {
+                console.error(`  Error: ${result.error.message}`);
+                process.exit(1);
+            }
+            console.log(JSON.stringify(result, null, 2));
+            break;
+        }
+        case "presets": {
+            const presets = (0, api_1.handleListPresets)();
+            console.log("\n  NV-SIM — Available Scenario Presets\n");
+            console.log("  " + "-".repeat(50));
+            for (const preset of presets.presets) {
+                console.log(`  ${preset.id}`);
+                console.log(`    ${preset.title}`);
+                console.log(`    Tags: ${preset.tags.join(", ")} | Stakeholders: ${preset.stakeholder_count}\n`);
+            }
+            console.log("  Usage: npx nv-sim preset <preset_id>\n");
+            break;
+        }
+        case "help":
+        case "--help":
+        case "-h":
+        default: {
+            console.log(`
+  NV-SIM — NeuroVerse Simulation CLI
+
+  "Simulators show what agents might do.
+   NeuroVerse shows what happens when systems have rules."
+
+  COMMANDS:
+
+    compare [preset]     Run governed simulation comparison (the killer demo)
+    chaos [preset]       Stress test — find the breaking point (the viral command)
+    visualize [preset]   Launch local simulation viewer in browser
+    analyze <file>       Analyze a simulation from file or stdin
+    preset <id>          Run reasoning on a preset scenario
+    presets              List available preset scenarios
+    help                 Show this help message
+
+  PRESETS:
+
+    trading              Flash crash — algorithmic cascade (default)
+    strait_of_hormuz     Geopolitical energy crisis
+    gas_price_spike      Economic energy shock
+    ai_regulation_crisis AI regulation impact
+
+  EXAMPLES:
+
+    npx nv-sim compare                          # Run the trading demo
+    npx nv-sim chaos                            # Stress test (100 runs)
+    npx nv-sim chaos trading --runs 500         # 500 randomized runs
+    npx nv-sim visualize                        # Open local viewer
+    npx nv-sim compare strait_of_hormuz         # Run geopolitical demo
+    npx nv-sim analyze simulation.json
+    npx nv-sim preset strait_of_hormuz
+
+  Simulate the future. Govern the outcomes.
+`);
+            break;
+        }
+    }
+}
+// ============================================
+// COMPARISON OUTPUT FORMATTING
+// ============================================
+function printComparisonResults(result, worldId) {
+    const b = result.baseline.metrics;
+    const g = result.governed.metrics;
+    const c = result.comparison;
+    // World rules
+    console.log(`\n  WORLD RULES APPLIED`);
+    console.log("  " + "-".repeat(50));
+    console.log(`  Thesis: ${result.worldRules.thesis}\n`);
+    console.log(`  Invariants:`);
+    for (const inv of result.worldRules.invariants) {
+        console.log(`    [${inv.id}] ${inv.description}`);
+    }
+    console.log(`\n  Gates:`);
+    for (const gate of result.worldRules.gates) {
+        console.log(`    [${gate.severity.toUpperCase()}] ${gate.label}`);
+    }
+    // Side-by-side metrics
+    console.log(`\n  SIMULATION A — No Governance (Baseline)`);
+    console.log("  " + "=".repeat(50));
+    console.log(`  Trajectory:            ${result.baseline.swarm.trajectory.toUpperCase()}`);
+    console.log(`  Collapse probability:  ${(b.collapseProbability * 100).toFixed(0)}%`);
+    console.log(`  System stability:      ${(b.stabilityScore * 100).toFixed(0)}%`);
+    console.log(`  Peak volatility:       ${(b.maxVolatility * 100).toFixed(0)}%`);
+    console.log(`  Coalition risks:       ${b.coalitionRisks}`);
+    console.log(`  Polarization events:   ${b.polarizationEvents}`);
+    console.log(`  Peak negative impact:  ${(b.peakNegativeSentiment * 100).toFixed(0)}%`);
+    console.log(`\n  SIMULATION B — With World Rules (Governed)`);
+    console.log("  " + "=".repeat(50));
+    console.log(`  Trajectory:            ${result.governed.swarm.trajectory.toUpperCase()}`);
+    console.log(`  Collapse probability:  ${(g.collapseProbability * 100).toFixed(0)}%`);
+    console.log(`  System stability:      ${(g.stabilityScore * 100).toFixed(0)}%`);
+    console.log(`  Peak volatility:       ${(g.maxVolatility * 100).toFixed(0)}%`);
+    console.log(`  Coalition risks:       ${g.coalitionRisks}`);
+    console.log(`  Polarization events:   ${g.polarizationEvents}`);
+    console.log(`  Peak negative impact:  ${(g.peakNegativeSentiment * 100).toFixed(0)}%`);
+    // Delta
+    console.log(`\n  GOVERNANCE IMPACT`);
+    console.log("  " + "=".repeat(50));
+    const collapseArrow = c.collapseReduction > 0 ? "\u2193" : "\u2191";
+    const stabilityArrow = c.stabilityImprovement > 0 ? "\u2191" : "\u2193";
+    const volatilityArrow = c.volatilityReduction > 0 ? "\u2193" : "\u2191";
+    console.log(`  Collapse probability:    ${collapseArrow} ${Math.abs(c.collapseReduction).toFixed(1)} percentage points`);
+    console.log(`  System stability:        ${stabilityArrow} ${Math.abs(c.stabilityImprovement).toFixed(1)} percentage points`);
+    console.log(`  Volatility:              ${volatilityArrow} ${Math.abs(c.volatilityReduction).toFixed(1)}%`);
+    console.log(`  Coalition risks:         ${c.coalitionRiskReduction > 0 ? "\u2193" : "="} ${c.coalitionRiskReduction} eliminated`);
+    console.log(`  Governance effectiveness:  ${(c.governanceEffectiveness * 100).toFixed(0)}%`);
+    // Narrative
+    console.log(`\n  ANALYSIS`);
+    console.log("  " + "=".repeat(50));
+    const words = c.narrative.split(" ");
+    let line = "  ";
+    for (const word of words) {
+        if (line.length + word.length > 72) {
+            console.log(line);
+            line = "  " + word;
+        }
+        else {
+            line += (line.trim() ? " " : "") + word;
+        }
+    }
+    if (line.trim())
+        console.log(line);
+    // Governance mechanics footer
+    const invariantCount = result.worldRules.invariants.length;
+    const criticalGates = result.worldRules.gates.filter(g => g.severity === "critical");
+    const warningGates = result.worldRules.gates.filter(g => g.severity === "warning");
+    const gs = result.governanceStats;
+    console.log(`\n  GOVERNANCE MECHANICS`);
+    console.log("  " + "-".repeat(50));
+    console.log(`  World:            ${worldId}.nv-world.md`);
+    console.log(`  Engine:           ${gs.engineLoaded ? "@neuroverseos/governance ✓" : "heuristic fallback"}`);
+    console.log(`  Invariants:       ${invariantCount} enforced`);
+    console.log(`  Gates triggered:  ${criticalGates.map(g => g.label).join(", ") || "none"}`);
+    if (warningGates.length > 0) {
+        console.log(`  Warnings:         ${warningGates.map(g => g.label).join(", ")}`);
+    }
+    console.log(`  Guard evals:      ${gs.totalEvaluations} (${gs.verdicts.allow} allow, ${gs.verdicts.block} block, ${gs.verdicts.pause} pause)`);
+    if (gs.triggeredGuards.length > 0) {
+        console.log(`  Guards fired:     ${gs.triggeredGuards.join(", ")}`);
+    }
+    console.log(`  Rules fired:      ${gs.rulesFired}`);
+    console.log(`  World viability:  ${gs.finalViability}${gs.worldCollapsed ? " (COLLAPSED)" : ""}`);
+    console.log(`  Agents:           ${result.baseline.swarm.rounds[0]?.reactions.length ?? 0}`);
+    console.log(`  Rounds:           ${result.baseline.swarm.rounds.length}`);
+    // Key message
+    console.log(`\n  ${"=".repeat(60)}`);
+    console.log(`  NeuroVerse doesn't just stop bad actions.`);
+    console.log(`  It changes the structure of the system itself.`);
+    console.log(`  ${"=".repeat(60)}`);
+    console.log(`\n  Simulate the future. Govern the outcomes.`);
+    console.log(`  neuroverse-simulations | @neuroverseos\n`);
+}
+// ============================================
+// CHAOS TEST OUTPUT FORMATTING
+// ============================================
+function printChaosResults(r) {
+    console.log("  SYSTEM COLLAPSE PROBABILITY");
+    console.log("  " + "=".repeat(50));
+    console.log(`  Baseline:    ${(r.baseline.collapseProbability * 100).toFixed(0)}%  (${r.baseline.collapseCount}/${r.runsCompleted} runs)`);
+    console.log(`  Governed:    ${(r.governed.collapseProbability * 100).toFixed(0)}%  (${r.governed.collapseCount}/${r.runsCompleted} runs)`);
+    if (r.impact.collapseReduction > 0) {
+        console.log(`  Reduction:   ${r.impact.collapseReduction.toFixed(0)} percentage points`);
+    }
+    console.log(`\n  STABILITY`);
+    console.log("  " + "-".repeat(50));
+    console.log(`  Baseline avg:    ${(r.baseline.avgStability * 100).toFixed(0)}%  (worst: ${(r.baseline.minStability * 100).toFixed(0)}%)`);
+    console.log(`  Governed avg:    ${(r.governed.avgStability * 100).toFixed(0)}%  (worst: ${(r.governed.minStability * 100).toFixed(0)}%)`);
+    console.log(`  Improvement:     +${r.impact.avgStabilityImprovement.toFixed(1)} percentage points`);
+    console.log(`\n  VOLATILITY`);
+    console.log("  " + "-".repeat(50));
+    console.log(`  Baseline avg:    ${(r.baseline.avgVolatility * 100).toFixed(0)}%  (worst: ${(r.baseline.maxVolatility * 100).toFixed(0)}%)`);
+    console.log(`  Governed avg:    ${(r.governed.avgVolatility * 100).toFixed(0)}%  (worst: ${(r.governed.maxVolatility * 100).toFixed(0)}%)`);
+    console.log(`  Reduction:       ${r.impact.avgVolatilityReduction.toFixed(1)}%`);
+    if (r.topRules.length > 0) {
+        console.log(`\n  MOST TRIGGERED RULES`);
+        console.log("  " + "-".repeat(50));
+        for (const rule of r.topRules) {
+            console.log(`  ${rule.label}  (${rule.triggerCount} times)`);
+        }
+    }
+    if (r.worstCases.length > 0) {
+        console.log(`\n  WORST-CASE SCENARIOS`);
+        console.log("  " + "-".repeat(50));
+        for (const wc of r.worstCases) {
+            console.log(`  Run #${wc.runIndex + 1}: baseline collapse ${(wc.baselineCollapse * 100).toFixed(0)}% → governed ${(wc.governedCollapse * 100).toFixed(0)}%  (volatility: ${(wc.volatility * 100).toFixed(0)}%)`);
+        }
+    }
+    console.log(`\n  TRAJECTORY DISTRIBUTION`);
+    console.log("  " + "-".repeat(50));
+    const allTrajs = new Set([...Object.keys(r.baseline.trajectories), ...Object.keys(r.governed.trajectories)]);
+    for (const traj of allTrajs) {
+        const bl = r.baseline.trajectories[traj] ?? 0;
+        const gv = r.governed.trajectories[traj] ?? 0;
+        console.log(`  ${traj.padEnd(14)} baseline: ${bl}  governed: ${gv}`);
+    }
+    console.log(`\n  GOVERNANCE ENGINE`);
+    console.log("  " + "-".repeat(50));
+    console.log(`  Engine:           ${r.engineStats.engineLoaded ? "@neuroverseos/governance ✓" : "heuristic fallback"}`);
+    console.log(`  Guard evals:      ${r.engineStats.totalGuardEvals}`);
+    console.log(`  Verdicts:         ${r.engineStats.totalVerdicts.allow} allow, ${r.engineStats.totalVerdicts.block} block, ${r.engineStats.totalVerdicts.pause} pause`);
+    console.log(`  Effectiveness:    ${(r.impact.avgEffectiveness * 100).toFixed(0)}%`);
+    console.log(`  Improvement rate: ${(r.impact.improvementRate * 100).toFixed(0)}% of runs`);
+    // Conclusion
+    console.log(`\n  ${"=".repeat(60)}`);
+    const reductionPct = r.baseline.collapseProbability > 0
+        ? ((r.baseline.collapseProbability - r.governed.collapseProbability) / r.baseline.collapseProbability * 100).toFixed(0)
+        : "N/A";
+    if (r.baseline.collapseProbability > r.governed.collapseProbability) {
+        console.log(`  Governance reduced catastrophic failure risk by ${reductionPct}%.`);
+    }
+    else {
+        console.log(`  System remained stable across all ${r.runsCompleted} scenarios.`);
+    }
+    console.log(`  Tested with nv-sim chaos (${r.runsCompleted} runs, ${(r.durationMs / 1000).toFixed(1)}s)`);
+    console.log(`  ${"=".repeat(60)}`);
+    console.log(`\n  Simulate the future. Govern the outcomes.`);
+    console.log(`  neuroverse-simulations | @neuroverseos\n`);
+}
+// ============================================
+// LOCAL VISUALIZER
+// ============================================
+async function startVisualizer(data, scenarioId) {
+    const html = buildVisualizerHtml(data, scenarioId);
+    const server = http.createServer((_req, res) => {
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(html);
+    });
+    const port = 3456;
+    server.listen(port, () => {
+        const url = `http://localhost:${port}`;
+        console.log(`  Visualizer running at ${url}\n`);
+        console.log("  Press Ctrl+C to stop.\n");
+        // Try to open browser
+        const { exec } = require("child_process");
+        const openCmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+        exec(`${openCmd} ${url}`, () => { });
+    });
+}
+function buildVisualizerHtml(data, scenarioId) {
+    const rounds = data.baseline.swarm.rounds;
+    const governedRounds = data.governed.swarm.rounds;
+    // Build per-round data for charts
+    const roundData = rounds.map((r, i) => {
+        const gr = governedRounds[i];
+        const blAvg = r.reactions.reduce((s, rx) => s + rx.impact, 0) / r.reactions.length;
+        const gvAvg = gr ? gr.reactions.reduce((s, rx) => s + rx.impact, 0) / gr.reactions.length : 0;
+        const blVol = Math.max(...r.reactions.map(rx => Math.abs(rx.impact)));
+        const gvVol = gr ? Math.max(...gr.reactions.map(rx => Math.abs(rx.impact))) : 0;
+        return { round: i, blAvg, gvAvg, blVol, gvVol };
+    });
+    // Agent data
+    const agents = rounds[0]?.reactions.map(r => r.stakeholder_id) ?? [];
+    const agentTimelines = agents.map(agentId => ({
+        id: agentId,
+        baseline: rounds.map(r => {
+            const rx = r.reactions.find(a => a.stakeholder_id === agentId);
+            return rx ? rx.impact : 0;
+        }),
+        governed: governedRounds.map(r => {
+            const rx = r.reactions.find(a => a.stakeholder_id === agentId);
+            return rx ? rx.impact : 0;
+        }),
+    }));
+    // Governance interventions per round
+    const dynamics = governedRounds.map(r => r.emergent_dynamics ?? []);
+    const jsonData = JSON.stringify({ roundData, agentTimelines, dynamics, scenarioId, data });
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>NV-SIM Visualizer — ${scenarioId}</title>
+<style>
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body { font-family: 'SF Mono', 'Fira Code', 'Cascadia Code', monospace; background: #0a0a0a; color: #e0e0e0; padding: 24px; }
+  h1 { font-size: 18px; color: #fff; margin-bottom: 4px; }
+  .subtitle { color: #888; font-size: 13px; margin-bottom: 24px; }
+  .grid { display: grid; grid-template-columns: 1fr 1fr; gap: 20px; margin-bottom: 20px; }
+  .card { background: #141414; border: 1px solid #222; border-radius: 8px; padding: 16px; }
+  .card h2 { font-size: 13px; color: #888; text-transform: uppercase; letter-spacing: 1px; margin-bottom: 12px; }
+  .metric { display: flex; justify-content: space-between; padding: 4px 0; font-size: 13px; }
+  .metric .label { color: #999; }
+  .metric .value { color: #fff; font-weight: 600; }
+  .metric .value.good { color: #4ade80; }
+  .metric .value.bad { color: #f87171; }
+  .metric .value.neutral { color: #fbbf24; }
+  canvas { width: 100% !important; height: 200px !important; }
+  .full-width { grid-column: 1 / -1; }
+  .agent-row { display: flex; align-items: center; gap: 8px; padding: 6px 0; border-bottom: 1px solid #1a1a1a; font-size: 12px; }
+  .agent-name { width: 160px; color: #999; flex-shrink: 0; }
+  .bar-container { flex: 1; display: flex; gap: 2px; align-items: center; }
+  .bar { height: 20px; border-radius: 3px; min-width: 1px; transition: width 0.3s; }
+  .bar.baseline { background: #ef4444; opacity: 0.6; }
+  .bar.governed { background: #4ade80; opacity: 0.8; }
+  .dynamics-list { font-size: 12px; color: #999; }
+  .dynamics-list .round-label { color: #fbbf24; font-weight: 600; }
+  .dynamics-list p { padding: 3px 0; }
+  .tag { display: inline-block; padding: 2px 8px; border-radius: 4px; font-size: 11px; margin: 2px; }
+  .tag.allow { background: #052e16; color: #4ade80; }
+  .tag.block { background: #2d0606; color: #f87171; }
+  .tag.pause { background: #2d2006; color: #fbbf24; }
+  .footer { text-align: center; color: #444; font-size: 12px; padding: 24px 0; }
+  .sparkline { display: flex; align-items: flex-end; gap: 1px; height: 40px; }
+  .spark-bar { flex: 1; border-radius: 2px 2px 0 0; min-width: 3px; }
+</style>
+</head>
+<body>
+<h1>NV-SIM Visualizer</h1>
+<div class="subtitle">${scenarioId} — Baseline vs Governed Comparison</div>
+
+<div class="grid">
+  <div class="card">
+    <h2>Simulation A — Baseline (No Governance)</h2>
+    <div id="baseline-metrics"></div>
+  </div>
+  <div class="card">
+    <h2>Simulation B — Governed (World Rules)</h2>
+    <div id="governed-metrics"></div>
+  </div>
+
+  <div class="card">
+    <h2>Impact Timeline — Average Impact Per Round</h2>
+    <canvas id="impactChart"></canvas>
+  </div>
+  <div class="card">
+    <h2>Volatility Timeline — Peak Volatility Per Round</h2>
+    <canvas id="volatilityChart"></canvas>
+  </div>
+
+  <div class="card full-width">
+    <h2>Agent Behavior — Baseline vs Governed (Final Round)</h2>
+    <div id="agent-bars"></div>
+  </div>
+
+  <div class="card">
+    <h2>Governance Interventions</h2>
+    <div id="dynamics" class="dynamics-list"></div>
+  </div>
+  <div class="card">
+    <h2>Governance Engine Stats</h2>
+    <div id="engine-stats"></div>
+  </div>
+</div>
+
+<div class="footer">
+  nv-sim visualize — local simulation inspector<br>
+  neuroverse-simulations | @neuroverseos
+</div>
+
+<script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.4/dist/chart.umd.min.js"><\/script>
+<script>
+const SIM = ${jsonData};
+
+// Metrics
+function renderMetrics(containerId, metrics, trajectory) {
+  const el = document.getElementById(containerId);
+  const rows = [
+    ['Trajectory', trajectory.toUpperCase(), trajectory === 'converging' || trajectory === 'stabilizing' ? 'good' : trajectory === 'escalating' ? 'bad' : 'neutral'],
+    ['Collapse Probability', (metrics.collapseProbability * 100).toFixed(0) + '%', metrics.collapseProbability < 0.2 ? 'good' : metrics.collapseProbability > 0.5 ? 'bad' : 'neutral'],
+    ['Stability', (metrics.stabilityScore * 100).toFixed(0) + '%', metrics.stabilityScore > 0.7 ? 'good' : metrics.stabilityScore < 0.4 ? 'bad' : 'neutral'],
+    ['Peak Volatility', (metrics.maxVolatility * 100).toFixed(0) + '%', metrics.maxVolatility < 0.4 ? 'good' : metrics.maxVolatility > 0.7 ? 'bad' : 'neutral'],
+    ['Coalition Risks', metrics.coalitionRisks, metrics.coalitionRisks === 0 ? 'good' : 'bad'],
+    ['Polarization Events', metrics.polarizationEvents, metrics.polarizationEvents === 0 ? 'good' : 'neutral'],
+  ];
+  el.innerHTML = rows.map(([label, value, cls]) =>
+    '<div class="metric"><span class="label">' + label + '</span><span class="value ' + cls + '">' + value + '</span></div>'
+  ).join('');
+}
+
+renderMetrics('baseline-metrics', SIM.data.baseline.metrics, SIM.data.baseline.swarm.trajectory);
+renderMetrics('governed-metrics', SIM.data.governed.metrics, SIM.data.governed.swarm.trajectory);
+
+// Charts
+const labels = SIM.roundData.map(d => 'R' + d.round);
+
+if (typeof Chart !== 'undefined') {
+  new Chart(document.getElementById('impactChart'), {
+    type: 'line',
+    data: {
+      labels,
+      datasets: [
+        { label: 'Baseline', data: SIM.roundData.map(d => d.blAvg), borderColor: '#ef4444', backgroundColor: 'rgba(239,68,68,0.1)', fill: true, tension: 0.3 },
+        { label: 'Governed', data: SIM.roundData.map(d => d.gvAvg), borderColor: '#4ade80', backgroundColor: 'rgba(74,222,128,0.1)', fill: true, tension: 0.3 },
+      ]
+    },
+    options: {
+      responsive: true,
+      plugins: { legend: { labels: { color: '#888', font: { family: 'monospace' } } } },
+      scales: {
+        x: { ticks: { color: '#666' }, grid: { color: '#1a1a1a' } },
+        y: { ticks: { color: '#666' }, grid: { color: '#1a1a1a' }, min: -1, max: 1 }
+      }
+    }
+  });
+
+  new Chart(document.getElementById('volatilityChart'), {
+    type: 'bar',
+    data: {
+      labels,
+      datasets: [
+        { label: 'Baseline', data: SIM.roundData.map(d => d.blVol), backgroundColor: 'rgba(239,68,68,0.6)' },
+        { label: 'Governed', data: SIM.roundData.map(d => d.gvVol), backgroundColor: 'rgba(74,222,128,0.6)' },
+      ]
+    },
+    options: {
+      responsive: true,
+      plugins: { legend: { labels: { color: '#888', font: { family: 'monospace' } } } },
+      scales: {
+        x: { ticks: { color: '#666' }, grid: { color: '#1a1a1a' } },
+        y: { ticks: { color: '#666' }, grid: { color: '#1a1a1a' }, min: 0, max: 1 }
+      }
+    }
+  });
+}
+
+// Agent bars (final round comparison)
+const agentBars = document.getElementById('agent-bars');
+const lastRoundIdx = SIM.agentTimelines[0]?.baseline.length - 1 || 0;
+agentBars.innerHTML = SIM.agentTimelines.map(agent => {
+  const blImpact = agent.baseline[lastRoundIdx] || 0;
+  const gvImpact = agent.governed[lastRoundIdx] || 0;
+  const blWidth = Math.abs(blImpact) * 100;
+  const gvWidth = Math.abs(gvImpact) * 100;
+  const blColor = blImpact >= 0 ? '#4ade80' : '#ef4444';
+  const gvColor = gvImpact >= 0 ? '#4ade80' : '#3b82f6';
+  return '<div class="agent-row">' +
+    '<span class="agent-name">' + agent.id + '</span>' +
+    '<div class="bar-container">' +
+    '<div class="bar" style="width:' + blWidth + '%;background:' + blColor + ';opacity:0.4" title="Baseline: ' + blImpact.toFixed(2) + '"></div>' +
+    '</div>' +
+    '<div class="bar-container">' +
+    '<div class="bar" style="width:' + gvWidth + '%;background:' + gvColor + '" title="Governed: ' + gvImpact.toFixed(2) + '"></div>' +
+    '</div>' +
+    '</div>';
+}).join('');
+
+// Dynamics
+const dynamicsEl = document.getElementById('dynamics');
+dynamicsEl.innerHTML = SIM.dynamics.map((roundDyn, i) =>
+  roundDyn.length > 0
+    ? '<p><span class="round-label">Round ' + i + ':</span> ' + roundDyn.join('; ') + '</p>'
+    : ''
+).filter(Boolean).join('') || '<p>No interventions triggered.</p>';
+
+// Engine stats
+const gs = SIM.data.governanceStats;
+const engineEl = document.getElementById('engine-stats');
+engineEl.innerHTML = [
+  ['Engine', gs.engineLoaded ? '@neuroverseos/governance' : 'heuristic fallback', gs.engineLoaded ? 'good' : 'neutral'],
+  ['Guard Evaluations', gs.totalEvaluations, ''],
+  ['Verdicts', '<span class="tag allow">' + gs.verdicts.allow + ' allow</span><span class="tag block">' + gs.verdicts.block + ' block</span><span class="tag pause">' + gs.verdicts.pause + ' pause</span>', ''],
+  ['Rules Fired', gs.rulesFired, ''],
+  ['World Viability', gs.finalViability + (gs.worldCollapsed ? ' (COLLAPSED)' : ''), gs.worldCollapsed ? 'bad' : 'good'],
+  ['Invariants Checked', gs.invariantsChecked, ''],
+].map(([label, value, cls]) =>
+  '<div class="metric"><span class="label">' + label + '</span><span class="value ' + cls + '">' + value + '</span></div>'
+).join('');
+<\/script>
+</body>
+</html>`;
+}
+main().catch((err) => {
+    console.error("Error:", err.message);
+    process.exit(1);
+});