@neuroverseos/nv-sim 0.1.0

package/dist/engine/governedSimulation.js

@@ -0,0 +1,529 @@
+"use strict";
+/**
+ * Governed Simulation — Baseline vs. Governed Comparison
+ *
+ * The killer demo: Run the same simulation twice.
+ *   Simulation A — No governance (agents behave freely)
+ *   Simulation B — With world rules (governance constrains behavior)
+ *
+ * "We ran the same simulation twice.
+ *  The only difference was the world rules."
+ *
+ * This proves that NeuroVerse doesn't just stop bad actions —
+ * it changes the structure of the system itself.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TRADING_DEMO = void 0;
+exports.runGovernedComparison = runGovernedComparison;
+const swarmSimulation_1 = require("./swarmSimulation");
+const worldBridge_1 = require("./worldBridge");
+// ============================================
+// GOVERNED REACTION MODEL
+// ============================================
+/**
+ * Apply governance constraints to a set of swarm reactions.
+ *
+ * This is where the magic happens: world rules reshape agent behavior.
+ * - Invariants cap extreme impacts (circuit breakers)
+ * - Gates trigger interventions that dampen volatility
+ * - Rebalancing rules pull extreme reactions toward equilibrium
+ */
+function applyGovernanceToReactions(reactions, invariants, gates, roundIndex, cumulativeAvgImpact) {
+    const interventions = [];
+    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) {
+        const desc = inv.description.toLowerCase();
+        // Cap extreme negative impacts (e.g., "maintain liquidity floor")
+        if (desc.includes("floor") || desc.includes("maintain") || desc.includes("minimum")) {
+            for (const agent of governed) {
+                if (agent.impact < -0.6) {
+                    const original = agent.impact;
+                    agent.impact = Math.max(agent.impact, -0.5);
+                    if (original !== agent.impact) {
+                        interventions.push(`[${inv.id}] Capped ${agent.stakeholder_id} negative impact: ${original.toFixed(2)} → ${agent.impact.toFixed(2)} (${inv.description})`);
+                    }
+                }
+            }
+        }
+        // Limit excessive positive speculation (e.g., "no leverage > 5x")
+        if (desc.includes("leverage") || desc.includes("limit") || desc.includes("cap") || desc.includes("restrict")) {
+            for (const agent of governed) {
+                if (agent.impact > 0.7) {
+                    const original = agent.impact;
+                    agent.impact = Math.min(agent.impact, 0.6);
+                    if (original !== agent.impact) {
+                        interventions.push(`[${inv.id}] Capped ${agent.stakeholder_id} excessive position: ${original.toFixed(2)} → ${agent.impact.toFixed(2)} (${inv.description})`);
+                    }
+                }
+            }
+        }
+        // Rebalancing rules (e.g., "coalition must rebalance every N ticks")
+        if (desc.includes("rebalance") || desc.includes("equilibrium") || desc.includes("correlat")) {
+            // Pull extreme reactions toward the mean
+            const avgImpact = governed.reduce((s, a) => s + a.impact, 0) / governed.length;
+            for (const agent of governed) {
+                if (Math.abs(agent.impact - avgImpact) > 0.4) {
+                    const original = agent.impact;
+                    agent.impact = agent.impact * 0.7 + avgImpact * 0.3;
+                    interventions.push(`[${inv.id}] Rebalanced ${agent.stakeholder_id}: ${original.toFixed(2)} → ${agent.impact.toFixed(2)} (${inv.description})`);
+                }
+            }
+        }
+        // Trust / transparency rules dampen hostility
+        if (desc.includes("trust") || desc.includes("transparen") || desc.includes("accountab")) {
+            for (const agent of governed) {
+                if (agent.impact < -0.3) {
+                    const original = agent.impact;
+                    agent.impact = agent.impact * 0.8; // 20% reduction in hostility
+                    if (Math.abs(original - agent.impact) > 0.01) {
+                        interventions.push(`[${inv.id}] Trust gate dampened ${agent.stakeholder_id} hostility: ${original.toFixed(2)} → ${agent.impact.toFixed(2)}`);
+                    }
+                }
+            }
+        }
+    }
+    // --- Gate enforcement ---
+    // Gates trigger systemic interventions when thresholds are crossed
+    for (const gate of gates) {
+        const condLower = gate.condition.toLowerCase();
+        if (gate.severity === "critical") {
+            // Critical gates act as circuit breakers — compress all impacts toward zero
+            const avgAbsImpact = governed.reduce((s, a) => s + Math.abs(a.impact), 0) / governed.length;
+            if (avgAbsImpact > 0.5 || cumulativeAvgImpact < -0.3) {
+                const dampingFactor = 0.6;
+                for (const agent of governed) {
+                    const original = agent.impact;
+                    agent.impact = agent.impact * dampingFactor;
+                }
+                interventions.push(`[${gate.id}] CIRCUIT BREAKER: ${gate.label} — all impacts dampened by ${((1 - dampingFactor) * 100).toFixed(0)}%`);
+            }
+        }
+        if (gate.severity === "warning") {
+            // Warning gates increase caution — reduce confidence of extreme actors
+            for (const agent of governed) {
+                if (Math.abs(agent.impact) > 0.4) {
+                    const original = agent.confidence;
+                    agent.confidence = Math.max(0.2, agent.confidence * 0.8);
+                }
+            }
+            if (roundIndex > 0) {
+                interventions.push(`[${gate.id}] WARNING: ${gate.label} — agent confidence reduced for extreme positions`);
+            }
+        }
+    }
+    // Reclamp all impacts to [-1, 1]
+    for (const agent of governed) {
+        agent.impact = Math.max(-1, Math.min(1, agent.impact));
+        agent.impact = Number(agent.impact.toFixed(2));
+        agent.confidence = Number(agent.confidence.toFixed(2));
+    }
+    return { reactions: governed, interventions };
+}
+// ============================================
+// GOVERNED SWARM SIMULATION
+// ============================================
+/**
+ * Run a swarm simulation with governance constraints applied each round.
+ *
+ * Same agents, same scenario, same reaction model —
+ * but world rules reshape the outcomes.
+ */
+async function runGovernedSwarmSimulation(scenario, stakeholders, paths, config, worldDef, nvWorld, request) {
+    // First run the unmodified simulation to get raw reactions
+    const rawResult = await (0, swarmSimulation_1.runSwarmSimulation)(scenario, stakeholders, paths, config);
+    // Now re-run applying governance to each round
+    const governedRounds = [];
+    const allInterventions = [];
+    const allGuardVerdicts = [];
+    let cumulativeAvgImpact = 0;
+    for (const round of rawResult.rounds) {
+        // --- Real governance engine: evaluate each agent's action ---
+        if (nvWorld && request) {
+            for (const reaction of round.reactions) {
+                const verdict = (0, worldBridge_1.evaluateScenarioGuard)({
+                    ...request,
+                    scenario: `[Round ${round.round}] ${reaction.stakeholder_id}: ${reaction.reaction} (impact: ${reaction.impact})`,
+                }, nvWorld, { trace: true, level: "standard" });
+                allGuardVerdicts.push(verdict);
+                // If the real engine blocks an action, force its impact toward zero
+                if (verdict.status === "BLOCK") {
+                    reaction.impact = reaction.impact * 0.2;
+                    reaction.confidence = Math.max(0.1, reaction.confidence * 0.5);
+                }
+                else if (verdict.status === "PAUSE") {
+                    reaction.impact = reaction.impact * 0.6;
+                    reaction.confidence = Math.max(0.2, reaction.confidence * 0.7);
+                }
+            }
+        }
+        // --- Heuristic governance: invariant/gate enforcement (always applied) ---
+        const { reactions: governedReactions, interventions } = applyGovernanceToReactions(round.reactions, worldDef.invariants, worldDef.gates ?? [], round.round, cumulativeAvgImpact);
+        // Recompute emergent dynamics with governed reactions
+        const emergentDynamics = detectGovernedDynamics(governedReactions, interventions);
+        governedRounds.push({
+            round: round.round,
+            reactions: governedReactions,
+            emergent_dynamics: emergentDynamics,
+        });
+        allInterventions.push(interventions);
+        // Update cumulative impact
+        const roundAvg = governedReactions.reduce((s, r) => s + r.impact, 0) / governedReactions.length;
+        cumulativeAvgImpact = (cumulativeAvgImpact * round.round + roundAvg) / (round.round + 1);
+    }
+    // Recompute trajectory and inflection points
+    const trajectory = computeTrajectory(governedRounds);
+    const inflectionPoints = computeInflectionPoints(governedRounds);
+    return {
+        swarm: {
+            rounds: governedRounds,
+            trajectory,
+            inflection_points: inflectionPoints,
+        },
+        allInterventions,
+        guardVerdicts: allGuardVerdicts,
+    };
+}
+function detectGovernedDynamics(reactions, interventions) {
+    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 constraints channeled energy constructively"
+            : "Negative consensus persists despite governance intervention");
+    }
+    else if (Math.abs(avgImpact) < 0.15) {
+        dynamics.push("Governance rules achieved near-equilibrium — agent positions stabilized");
+    }
+    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 dampened by governance constraints");
+    }
+    if (interventions.length > 0) {
+        dynamics.push(`${interventions.length} governance intervention(s) applied this round`);
+    }
+    return dynamics;
+}
+function computeTrajectory(rounds) {
+    if (rounds.length < 2)
+        return "stabilizing";
+    const avgImpacts = rounds.map((r) => r.reactions.reduce((s, rx) => s + rx.impact, 0) / r.reactions.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 computeInflectionPoints(rounds) {
+    const points = [];
+    for (let i = 1; i < rounds.length; i++) {
+        const prevAvg = rounds[i - 1].reactions.reduce((s, r) => s + r.impact, 0) /
+            rounds[i - 1].reactions.length;
+        const currAvg = rounds[i].reactions.reduce((s, r) => s + r.impact, 0) /
+            rounds[i].reactions.length;
+        const shift = Math.abs(currAvg - prevAvg);
+        if (shift > 0.3) {
+            points.push(`Round ${i}: Significant sentiment shift (${(shift * 100).toFixed(0)}% swing)`);
+        }
+    }
+    if (points.length === 0) {
+        points.push("Governance constraints prevented major inflection points — smooth trajectory");
+    }
+    return points;
+}
+// ============================================
+// METRICS COMPUTATION
+// ============================================
+function computeMetrics(swarm) {
+    const allReactions = swarm.rounds.flatMap((r) => r.reactions);
+    const allImpacts = allReactions.map((r) => r.impact);
+    const avgImpact = allImpacts.reduce((s, i) => s + i, 0) / allImpacts.length;
+    const maxVolatility = Math.max(...allImpacts.map((i) => Math.abs(i)));
+    const peakNegativeSentiment = Math.min(...allImpacts);
+    // Collapse probability: based on trajectory, negative sentiment, and volatility
+    let collapseProbability = 0;
+    if (swarm.trajectory === "escalating")
+        collapseProbability += 0.35;
+    if (swarm.trajectory === "diverging")
+        collapseProbability += 0.25;
+    if (avgImpact < -0.3)
+        collapseProbability += 0.25;
+    if (maxVolatility > 0.7)
+        collapseProbability += 0.15;
+    collapseProbability = Math.min(0.95, collapseProbability);
+    // Stability score: inverse of volatility and negative sentiment
+    const impactVariance = allImpacts.reduce((s, i) => s + (i - avgImpact) ** 2, 0) / allImpacts.length;
+    let stabilityScore = 1 - Math.min(1, impactVariance * 3 + Math.max(0, -avgImpact));
+    if (swarm.trajectory === "converging" || swarm.trajectory === "stabilizing") {
+        stabilityScore = Math.min(1, stabilityScore + 0.15);
+    }
+    stabilityScore = Math.max(0, Math.min(1, stabilityScore));
+    // Count dynamics
+    const allDynamics = swarm.rounds.flatMap((r) => r.emergent_dynamics ?? []);
+    const coalitionRisks = allDynamics.filter((d) => d.toLowerCase().includes("coalition")).length;
+    const polarizationEvents = allDynamics.filter((d) => d.toLowerCase().includes("polariz")).length;
+    const consensusRounds = swarm.rounds.filter((r) => {
+        const avg = r.reactions.reduce((s, rx) => s + rx.impact, 0) / r.reactions.length;
+        return Math.abs(avg) > 0.4;
+    }).length;
+    return {
+        avgImpact: Number(avgImpact.toFixed(3)),
+        collapseProbability: Number(collapseProbability.toFixed(2)),
+        stabilityScore: Number(stabilityScore.toFixed(2)),
+        coalitionRisks,
+        polarizationEvents,
+        peakNegativeSentiment: Number(peakNegativeSentiment.toFixed(2)),
+        consensusRounds,
+        maxVolatility: Number(maxVolatility.toFixed(2)),
+    };
+}
+function buildComparisonNarrative(baseline, governed, worldThesis) {
+    const parts = [];
+    const collapseReduction = baseline.collapseProbability - governed.collapseProbability;
+    if (collapseReduction > 0.1) {
+        parts.push(`Collapse probability dropped from ${(baseline.collapseProbability * 100).toFixed(0)}% to ${(governed.collapseProbability * 100).toFixed(0)}% — a ${(collapseReduction * 100).toFixed(0)} percentage point reduction.`);
+    }
+    const stabilityGain = governed.stabilityScore - baseline.stabilityScore;
+    if (stabilityGain > 0.05) {
+        parts.push(`System stability improved from ${(baseline.stabilityScore * 100).toFixed(0)}% to ${(governed.stabilityScore * 100).toFixed(0)}%.`);
+    }
+    if (baseline.coalitionRisks > governed.coalitionRisks) {
+        parts.push(`Coalition risks reduced from ${baseline.coalitionRisks} to ${governed.coalitionRisks}.`);
+    }
+    if (baseline.maxVolatility > governed.maxVolatility) {
+        const reduction = ((baseline.maxVolatility - governed.maxVolatility) / baseline.maxVolatility * 100);
+        parts.push(`Peak volatility reduced by ${reduction.toFixed(0)}%.`);
+    }
+    if (parts.length === 0) {
+        parts.push("Governance constraints had minimal measurable effect on this scenario.");
+    }
+    else {
+        parts.unshift(`World thesis: "${worldThesis}"`);
+        parts.push("Rules reshape emergent behavior — governance changes the structure of the system, not just individual actions.");
+    }
+    return parts.join(" ");
+}
+// ============================================
+// MAIN COMPARISON ENGINE
+// ============================================
+/**
+ * Run the governed simulation comparison.
+ *
+ * This is the demo entry point:
+ *   1. Run baseline simulation (no governance)
+ *   2. Run governed simulation (same agents, world rules applied)
+ *   3. Compare metrics
+ *   4. Generate narrative
+ */
+async function runGovernedComparison(request, worldLite, paths) {
+    const stakeholders = (request.stakeholders ?? []).map((s) => typeof s === "string" ? { id: s, disposition: "unknown" } : s);
+    const swarmConfig = request.swarm ?? {
+        enabled: true,
+        rounds: 5,
+        reaction_model: "mixed",
+    };
+    // Build the full NVWorldDefinition for real governance engine calls
+    const nvWorld = (0, worldBridge_1.buildWorldFromScenario)(request, worldLite);
+    // Step 1: Baseline — no governance
+    const baselineSwarm = await (0, swarmSimulation_1.runSwarmSimulation)(request.scenario, stakeholders, paths, swarmConfig);
+    const baselineMetrics = computeMetrics(baselineSwarm);
+    // Step 2: Governed — same scenario, world rules applied (real engine + heuristics)
+    const { swarm: governedSwarm, guardVerdicts } = await runGovernedSwarmSimulation(request.scenario, stakeholders, paths, swarmConfig, worldLite, nvWorld, request);
+    const governedMetrics = computeMetrics(governedSwarm);
+    // Step 3: Build world simulation (deterministic state evolution via real engine)
+    let worldSimulation;
+    try {
+        worldSimulation = (0, worldBridge_1.runWorldSimulation)(nvWorld, { steps: 5 });
+    }
+    catch {
+        // World simulation is optional — continue without it
+    }
+    // Step 4: Compare
+    const collapseReduction = baselineMetrics.collapseProbability - governedMetrics.collapseProbability;
+    const stabilityImprovement = governedMetrics.stabilityScore - baselineMetrics.stabilityScore;
+    const volatilityReduction = baselineMetrics.maxVolatility > 0
+        ? (baselineMetrics.maxVolatility - governedMetrics.maxVolatility) / baselineMetrics.maxVolatility
+        : 0;
+    const coalitionRiskReduction = baselineMetrics.coalitionRisks - governedMetrics.coalitionRisks;
+    // Overall effectiveness: weighted composite
+    const governanceEffectiveness = Math.min(1, Math.max(0, collapseReduction * 0.4 +
+        stabilityImprovement * 0.3 +
+        Math.max(0, volatilityReduction) * 0.2 +
+        Math.max(0, coalitionRiskReduction * 0.1)));
+    const narrative = buildComparisonNarrative(baselineMetrics, governedMetrics, worldLite.thesis);
+    // Step 5: Collect real governance stats
+    const verdictCounts = { allow: 0, block: 0, pause: 0 };
+    const triggeredGuardIds = new Set();
+    let invariantsChecked = 0;
+    for (const v of guardVerdicts) {
+        const status = v.status.toLowerCase();
+        if (status in verdictCounts)
+            verdictCounts[status]++;
+        if (v.ruleId)
+            triggeredGuardIds.add(v.ruleId);
+        if (v.evidence?.invariantChecks) {
+            invariantsChecked += v.evidence.invariantChecks.length;
+        }
+        if (v.evidence?.guardChecks) {
+            for (const gc of v.evidence.guardChecks) {
+                if (gc.triggered)
+                    triggeredGuardIds.add(gc.guardId);
+            }
+        }
+    }
+    const totalRulesFired = worldSimulation
+        ? worldSimulation.steps.reduce((s, step) => s + step.rulesFired, 0)
+        : 0;
+    const governanceStats = {
+        engineLoaded: guardVerdicts.length > 0 && guardVerdicts[0].reason !== "NeuroverseOS guard not loaded — permissive fallback",
+        totalEvaluations: guardVerdicts.length,
+        verdicts: verdictCounts,
+        rulesFired: totalRulesFired,
+        worldCollapsed: worldSimulation?.collapsed ?? false,
+        finalViability: worldSimulation?.finalViability ?? "UNKNOWN",
+        invariantsChecked,
+        triggeredGuards: [...triggeredGuardIds],
+    };
+    return {
+        scenario: request.scenario,
+        worldRules: {
+            thesis: worldLite.thesis,
+            invariants: worldLite.invariants,
+            gates: worldLite.gates ?? [],
+        },
+        baseline: {
+            swarm: baselineSwarm,
+            metrics: baselineMetrics,
+        },
+        governed: {
+            swarm: governedSwarm,
+            metrics: governedMetrics,
+            worldSimulation,
+        },
+        comparison: {
+            collapseReduction: Number((collapseReduction * 100).toFixed(1)),
+            stabilityImprovement: Number((stabilityImprovement * 100).toFixed(1)),
+            volatilityReduction: Number((volatilityReduction * 100).toFixed(1)),
+            coalitionRiskReduction,
+            governanceEffectiveness: Number(governanceEffectiveness.toFixed(2)),
+            narrative,
+        },
+        governanceStats,
+    };
+}
+// ============================================
+// PRESET: TRADING SCENARIO
+// ============================================
+/**
+ * Built-in trading world for the killer demo.
+ *
+ * Scenario: Flash crash triggered by algorithmic cascade.
+ * Without governance: Market panic, coalition collapse, system instability.
+ * With governance: Circuit breakers, risk limits, and rebalancing stabilize the system.
+ */
+exports.TRADING_DEMO = {
+    scenario: {
+        scenario: "A major algorithmic trading firm's risk model fails during a volatility spike, " +
+            "triggering a cascade of automated sell-offs across interconnected markets. " +
+            "Liquidity evaporates in key sectors. Contagion spreads to sovereign debt markets. " +
+            "Central banks are caught between rate decisions.",
+        stakeholders: [
+            { id: "Algorithmic Traders", disposition: "hostile", priorities: ["risk management", "position unwinding", "survival"] },
+            { id: "Institutional Investors", disposition: "neutral", priorities: ["portfolio protection", "liquidity access", "fiduciary duty"] },
+            { id: "Retail Investors", disposition: "hostile", priorities: ["savings protection", "market access", "information"] },
+            { id: "Central Banks", disposition: "neutral", priorities: ["systemic stability", "inflation mandate", "credibility"] },
+            { id: "Market Makers", disposition: "supportive", priorities: ["spread capture", "inventory management", "obligation fulfillment"] },
+            { id: "Regulators", disposition: "neutral", priorities: ["market integrity", "investor protection", "systemic risk"] },
+        ],
+        assumptions: {
+            severity: "critical",
+            environmental_hostility: "high",
+            time_pressure: "immediate",
+            regulatory_climate: "strict",
+        },
+        constraints: {
+            time_horizon: "72 hours",
+            regulatory: ["SEC circuit breakers", "Basel III liquidity requirements", "Dodd-Frank systemic risk"],
+            risk_tolerance: "conservative",
+        },
+        depth: "full",
+        swarm: { enabled: true, rounds: 6, reaction_model: "mixed" },
+    },
+    world: {
+        thesis: "Market stability requires structural constraints on leverage, liquidity, and automated behavior to prevent cascading failures",
+        state_variables: [
+            { id: "liquidity_index", label: "Market Liquidity Index", type: "number", range: { min: 0, max: 100 }, default_value: 25 },
+            { id: "leverage_ratio", label: "System Leverage Ratio", type: "number", range: { min: 1, max: 30 }, default_value: 12 },
+            { id: "volatility_index", label: "Volatility Index (VIX-like)", type: "number", range: { min: 10, max: 100 }, default_value: 65 },
+            { id: "contagion_spread", label: "Cross-Market Contagion", type: "enum", enum_values: ["contained", "spreading", "systemic"], default_value: "spreading" },
+            { id: "central_bank_intervention", label: "Central Bank Intervention Active", type: "boolean", default_value: false },
+        ],
+        invariants: [
+            { id: "INV-001", description: "Maintain minimum liquidity floor — no agent may drain liquidity below 15% of baseline", enforceable: true },
+            { id: "INV-002", description: "Maximum leverage limit — no position may exceed 5x leverage during elevated volatility", enforceable: true },
+            { id: "INV-003", description: "Coalition rebalancing — correlated positions must rebalance when concentration exceeds threshold", enforceable: true },
+            { id: "INV-004", description: "Transparency requirement — all large position changes must be reported, reducing trust deficit", enforceable: true },
+            { id: "INV-005", description: "Algorithmic trading circuit breaker — automated strategies must pause during extreme volatility", enforceable: true },
+        ],
+        gates: [
+            { id: "GATE-001", label: "Market Panic Circuit Breaker", condition: "volatility_index > 80 || liquidity_index < 10", severity: "critical" },
+            { id: "GATE-002", label: "Contagion Warning", condition: "contagion_spread == systemic", severity: "critical" },
+            { id: "GATE-003", label: "Leverage Warning", condition: "leverage_ratio > 8", severity: "warning" },
+        ],
+    },
+    paths: [
+        {
+            id: "path_cascade_selloff",
+            label: "Cascade Sell-off",
+            description: "Automated systems trigger chain reaction of liquidations across interconnected positions",
+            projected_outcome: "Market drops 15-25% in hours. Liquidity crisis in sovereign debt. Multiple fund failures.",
+            probability: 0.65,
+            risk: "critical",
+            tradeoffs: [
+                "Speed of contagion vs. available response time",
+                "Individual firm survival vs. systemic stability",
+                "Regulatory intervention risk vs. free market correction",
+            ],
+            benefits_stakeholders: [],
+            harms_stakeholders: ["Algorithmic Traders", "Retail Investors", "Institutional Investors"],
+        },
+        {
+            id: "path_coordinated_response",
+            label: "Coordinated Response",
+            description: "Central banks and regulators coordinate emergency measures: rate cuts, liquidity injection, trading halts",
+            projected_outcome: "Market stabilizes within 48 hours. Moral hazard concerns. Political backlash.",
+            probability: 0.55,
+            risk: "moderate",
+            tradeoffs: [
+                "Systemic stability vs. moral hazard",
+                "Short-term calm vs. long-term market distortion",
+                "Central bank credibility vs. political pressure",
+            ],
+            benefits_stakeholders: ["Market Makers", "Institutional Investors"],
+            harms_stakeholders: ["Retail Investors"],
+        },
+        {
+            id: "path_selective_contagion",
+            label: "Selective Contagion",
+            description: "Contagion spreads to specific sectors but circuit breakers prevent total market failure",
+            projected_outcome: "Targeted sector collapse with 2-3 major fund failures. Broader market recovers in weeks.",
+            probability: 0.45,
+            risk: "high",
+            tradeoffs: [
+                "Sector sacrifice vs. systemic preservation",
+                "Speed of containment vs. fairness of outcome",
+                "Regulatory precedent set for future crises",
+            ],
+            benefits_stakeholders: ["Central Banks", "Regulators"],
+            harms_stakeholders: ["Algorithmic Traders"],
+        },
+    ],
+};

package/dist/engine/index.js

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * Echelon Reason API — Public Exports
+ *
+ * The POST /reason API makes Echelon reasoning infrastructure.
+ * This is the "Stripe for reasoning" layer that agents,
+ * applications, and the Mirotir UI all consume.
+ *
+ * Architecture:
+ *   Mirotir UI (showcase) ──→ POST /reason ──→ Echelon kernel (proprietary)
+ *   Autonomous agents     ──→ POST /reason ──→ Echelon kernel
+ *   Third-party apps      ──→ POST /reason ──→ Echelon kernel
+ *                                    │
+ *                                    ├── Governance traces (open, auditable)
+ *                                    ├── MiroFish swarm simulation (when available)
+ *                                    ├── Echelon-native simulation (fallback)
+ *                                    ├── World files (reasoning models)
+ *                                    └── Scenario capsules (shareable, portable)
+ *
+ * MiroFish shows WHAT might happen → the spectacle
+ * Mirotir helps you decide WHAT TO DO → the brain
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+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;
+// Goal-Directed Strategy Engine
+var goalEngine_1 = require("./goalEngine");
+Object.defineProperty(exports, "runGoalReasoning", { enumerable: true, get: function () { return goalEngine_1.runGoalReasoning; } });
+var scenarioCapsule_1 = require("./scenarioCapsule");
+Object.defineProperty(exports, "createCapsule", { enumerable: true, get: function () { return scenarioCapsule_1.createCapsule; } });
+Object.defineProperty(exports, "capsuleToReasonRequest", { enumerable: true, get: function () { return scenarioCapsule_1.capsuleToReasonRequest; } });
+Object.defineProperty(exports, "encodeCapsule", { enumerable: true, get: function () { return scenarioCapsule_1.encodeCapsule; } });
+Object.defineProperty(exports, "decodeCapsule", { enumerable: true, get: function () { return scenarioCapsule_1.decodeCapsule; } });
+Object.defineProperty(exports, "buildShareableUrl", { enumerable: true, get: function () { return scenarioCapsule_1.buildShareableUrl; } });
+Object.defineProperty(exports, "extractCapsuleFromUrl", { enumerable: true, get: function () { return scenarioCapsule_1.extractCapsuleFromUrl; } });
+Object.defineProperty(exports, "getPresetCapsule", { enumerable: true, get: function () { return scenarioCapsule_1.getPresetCapsule; } });
+Object.defineProperty(exports, "SCENARIO_TEMPLATES", { enumerable: true, get: function () { return scenarioCapsule_1.SCENARIO_TEMPLATES; } });
+// Reasoning Engine
+var reasoningEngine_1 = require("./reasoningEngine");
+Object.defineProperty(exports, "processReasonRequest", { enumerable: true, get: function () { return reasoningEngine_1.processReasonRequest; } });
+// Governance (Echelon constitutional + NeuroverseOS guard/validate/simulate)
+var governance_1 = require("./governance");
+Object.defineProperty(exports, "runGovernanceChecks", { enumerable: true, get: function () { return governance_1.runGovernanceChecks; } });
+Object.defineProperty(exports, "runFullGovernanceChecks", { enumerable: true, get: function () { return governance_1.runFullGovernanceChecks; } });
+// NeuroverseOS World Bridge
+// Converts between Echelon scenarios and NeuroverseOS WorldDefinition
+var worldBridge_1 = require("./worldBridge");
+Object.defineProperty(exports, "buildWorldFromScenario", { enumerable: true, get: function () { return worldBridge_1.buildWorldFromScenario; } });
+Object.defineProperty(exports, "evaluateScenarioGuard", { enumerable: true, get: function () { return worldBridge_1.evaluateScenarioGuard; } });
+Object.defineProperty(exports, "runWorldSimulation", { enumerable: true, get: function () { return worldBridge_1.runWorldSimulation; } });
+Object.defineProperty(exports, "validateScenarioWorld", { enumerable: true, get: function () { return worldBridge_1.validateScenarioWorld; } });
+Object.defineProperty(exports, "verdictToConstitutionalChecks", { enumerable: true, get: function () { return worldBridge_1.verdictToConstitutionalChecks; } });
+Object.defineProperty(exports, "simulationToGovernanceSignals", { enumerable: true, get: function () { return worldBridge_1.simulationToGovernanceSignals; } });
+Object.defineProperty(exports, "validationToEnforcedConstraints", { enumerable: true, get: function () { return worldBridge_1.validationToEnforcedConstraints; } });
+Object.defineProperty(exports, "initNeuroverseModule", { enumerable: true, get: function () { return worldBridge_1.initNeuroverseModule; } });
+// Swarm Simulation (Echelon-native)
+var swarmSimulation_1 = require("./swarmSimulation");
+Object.defineProperty(exports, "runSwarmSimulation", { enumerable: true, get: function () { return swarmSimulation_1.runSwarmSimulation; } });
+var mirofish_1 = require("./mirofish");
+Object.defineProperty(exports, "MiroFishClient", { enumerable: true, get: function () { return mirofish_1.MiroFishClient; } });
+Object.defineProperty(exports, "MiroFishError", { enumerable: true, get: function () { return mirofish_1.MiroFishError; } });
+Object.defineProperty(exports, "configureMiroFish", { enumerable: true, get: function () { return mirofish_1.configureMiroFish; } });
+Object.defineProperty(exports, "getMiroFishClient", { enumerable: true, get: function () { return mirofish_1.getMiroFishClient; } });
+Object.defineProperty(exports, "runUnifiedSimulation", { enumerable: true, get: function () { return mirofish_1.runUnifiedSimulation; } });
+Object.defineProperty(exports, "stakeholdersToMiroFishAgents", { enumerable: true, get: function () { return mirofish_1.stakeholdersToMiroFishAgents; } });
+Object.defineProperty(exports, "miroFishResultToSwarmResult", { enumerable: true, get: function () { return mirofish_1.miroFishResultToSwarmResult; } });
+Object.defineProperty(exports, "buildMiroFishRequest", { enumerable: true, get: function () { return mirofish_1.buildMiroFishRequest; } });
+Object.defineProperty(exports, "DEFAULT_MIROFISH_CONFIG", { enumerable: true, get: function () { return mirofish_1.DEFAULT_MIROFISH_CONFIG; } });
+var analyzer_1 = require("./analyzer");
+Object.defineProperty(exports, "analyzeMiroFishSimulation", { enumerable: true, get: function () { return analyzer_1.analyzeMiroFishSimulation; } });
+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; } });
+// API Route Handlers
+var api_1 = require("./api");
+Object.defineProperty(exports, "handleReasonRequest", { enumerable: true, get: function () { return api_1.handleReasonRequest; } });
+Object.defineProperty(exports, "handleReasonFromCapsule", { enumerable: true, get: function () { return api_1.handleReasonFromCapsule; } });
+Object.defineProperty(exports, "handleCreateCapsule", { enumerable: true, get: function () { return api_1.handleCreateCapsule; } });
+Object.defineProperty(exports, "handleHealthCheck", { enumerable: true, get: function () { return api_1.handleHealthCheck; } });
+Object.defineProperty(exports, "handleListPresets", { enumerable: true, get: function () { return api_1.handleListPresets; } });
+Object.defineProperty(exports, "handleGetPreset", { enumerable: true, get: function () { return api_1.handleGetPreset; } });
+Object.defineProperty(exports, "handleRunPreset", { enumerable: true, get: function () { return api_1.handleRunPreset; } });
+Object.defineProperty(exports, "parseReasonRequestBody", { enumerable: true, get: function () { return api_1.parseReasonRequestBody; } });