@neuroverseos/nv-sim 0.1.0

package/dist/engine/api.js

@@ -0,0 +1,208 @@
+"use strict";
+/**
+ * POST /reason API Route Handler
+ *
+ * The HTTP interface for the Echelon reasoning engine.
+ * This is the "Stripe for reasoning" endpoint that agents and
+ * applications call for structured decision analysis.
+ *
+ * Endpoints:
+ *   POST /api/v1/reason          — Run structured reasoning on a scenario
+ *   POST /api/v1/reason/capsule  — Create a shareable scenario capsule
+ *   GET  /api/v1/reason/health   — Engine health check
+ *   GET  /api/v1/reason/presets   — List preset scenario templates
+ *
+ * Design:
+ *   - Stateless: no data persisted after response
+ *   - BYOK: caller provides their own API key (future)
+ *   - Governance traces in every response (open governance layer)
+ *   - Rate limiting per API key (future)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseReasonRequestBody = parseReasonRequestBody;
+exports.handleReasonRequest = handleReasonRequest;
+exports.handleReasonFromCapsule = handleReasonFromCapsule;
+exports.handleCreateCapsule = handleCreateCapsule;
+exports.handleHealthCheck = handleHealthCheck;
+exports.handleListPresets = handleListPresets;
+exports.handleGetPreset = handleGetPreset;
+exports.handleRunPreset = handleRunPreset;
+const reasoningEngine_1 = require("./reasoningEngine");
+const scenarioCapsule_1 = require("./scenarioCapsule");
+// ============================================
+// REQUEST PARSING
+// ============================================
+/**
+ * Parse and validate a POST /reason request body.
+ */
+function parseReasonRequestBody(body) {
+    if (!body || typeof body !== "object") {
+        return {
+            error: {
+                status: "error",
+                error: {
+                    code: "INVALID_REQUEST",
+                    message: "Request body must be a JSON object",
+                },
+                reasoning_id: `rsn_${Date.now().toString(36)}_err`,
+                timestamp: new Date().toISOString(),
+            },
+        };
+    }
+    const b = body;
+    if (!b.scenario || typeof b.scenario !== "string") {
+        return {
+            error: {
+                status: "error",
+                error: {
+                    code: "INVALID_REQUEST",
+                    message: "\"scenario\" field is required and must be a string",
+                },
+                reasoning_id: `rsn_${Date.now().toString(36)}_err`,
+                timestamp: new Date().toISOString(),
+            },
+        };
+    }
+    // Build the request — the engine validates the rest
+    const request = {
+        scenario: b.scenario,
+        stakeholders: b.stakeholders,
+        assumptions: b.assumptions,
+        constraints: b.constraints,
+        depth: b.depth,
+        questions: b.questions,
+        perspective: b.perspective,
+        swarm: b.swarm,
+    };
+    return { request };
+}
+// ============================================
+// ROUTE HANDLERS
+// ============================================
+/**
+ * POST /api/v1/reason
+ *
+ * Main reasoning endpoint. Accepts a scenario and returns
+ * structured analysis with governance traces.
+ *
+ * This is the endpoint that autonomous agents call.
+ */
+async function handleReasonRequest(body) {
+    const parsed = parseReasonRequestBody(body);
+    if ("error" in parsed) {
+        return parsed.error;
+    }
+    return (0, reasoningEngine_1.processReasonRequest)(parsed.request);
+}
+/**
+ * POST /api/v1/reason (from capsule)
+ *
+ * Run reasoning from a scenario capsule.
+ * The capsule can come from a URL, a file, or another agent.
+ */
+async function handleReasonFromCapsule(capsule) {
+    const request = (0, scenarioCapsule_1.capsuleToReasonRequest)(capsule);
+    return (0, reasoningEngine_1.processReasonRequest)(request);
+}
+function handleCreateCapsule(body) {
+    const capsule = (0, scenarioCapsule_1.createCapsule)(body.title, body.request, {
+        signals: body.signals,
+        tags: body.tags,
+        author: body.author,
+    });
+    return {
+        capsule,
+        encoded: (0, scenarioCapsule_1.encodeCapsule)(capsule),
+        shareable_url: (0, scenarioCapsule_1.buildShareableUrl)(capsule),
+    };
+}
+function handleHealthCheck() {
+    return {
+        status: "healthy",
+        engine_version: "0.1.0",
+        governance_layers: [
+            "echelon-constitutional (proprietary)",
+            "neuroverse-os-governance (open source)",
+        ],
+        capabilities: [
+            "multi-path reasoning",
+            "assumption challenging",
+            "outcome projection",
+            "swarm simulation",
+            "scenario capsules",
+            "governance tracing",
+        ],
+    };
+}
+function handleListPresets() {
+    return {
+        presets: Object.entries(scenarioCapsule_1.SCENARIO_TEMPLATES).map(([id, template]) => ({
+            id,
+            title: template.title,
+            tags: template.tags ?? [],
+            stakeholder_count: template.stakeholders.length,
+        })),
+    };
+}
+/**
+ * GET /api/v1/reason/presets/:id
+ *
+ * Get a specific preset scenario as a capsule, ready to run.
+ */
+function handleGetPreset(presetId) {
+    try {
+        const capsule = (0, scenarioCapsule_1.getPresetCapsule)(presetId);
+        return {
+            capsule,
+            shareable_url: (0, scenarioCapsule_1.buildShareableUrl)(capsule),
+        };
+    }
+    catch {
+        return {
+            status: "error",
+            error: {
+                code: "INVALID_REQUEST",
+                message: `Unknown preset: "${presetId}". Use GET /api/v1/reason/presets for available presets.`,
+            },
+            reasoning_id: `rsn_${Date.now().toString(36)}_err`,
+            timestamp: new Date().toISOString(),
+        };
+    }
+}
+/**
+ * POST /api/v1/reason/preset/:id
+ *
+ * Run reasoning on a preset scenario.
+ * Convenience endpoint — loads the preset and runs it.
+ */
+async function handleRunPreset(presetId, overrides) {
+    try {
+        const capsule = (0, scenarioCapsule_1.getPresetCapsule)(presetId);
+        const baseRequest = (0, scenarioCapsule_1.capsuleToReasonRequest)(capsule);
+        // Apply any overrides
+        const request = {
+            ...baseRequest,
+            ...overrides,
+            assumptions: {
+                ...baseRequest.assumptions,
+                ...overrides?.assumptions,
+            },
+            constraints: {
+                ...baseRequest.constraints,
+                ...overrides?.constraints,
+            },
+        };
+        return (0, reasoningEngine_1.processReasonRequest)(request);
+    }
+    catch {
+        return {
+            status: "error",
+            error: {
+                code: "INVALID_REQUEST",
+                message: `Unknown preset: "${presetId}"`,
+            },
+            reasoning_id: `rsn_${Date.now().toString(36)}_err`,
+            timestamp: new Date().toISOString(),
+        };
+    }
+}

package/dist/engine/chaosEngine.js

@@ -0,0 +1,292 @@
+"use strict";
+/**
+ * Chaos Engine — Automated Stress Testing for Governed Systems
+ *
+ * "Under what conditions does this system break?"
+ *
+ * Runs hundreds of randomized simulations to find:
+ *   - System collapse probability (baseline vs governed)
+ *   - Worst-case volatility
+ *   - Most triggered governance rules
+ *   - Breaking points and fragile assumptions
+ *
+ * Usage:
+ *   npx nv-sim chaos                          # Stress test the trading demo
+ *   npx nv-sim chaos --runs 500               # More iterations
+ *   npx nv-sim chaos strait_of_hormuz         # Test a preset
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runChaosTest = runChaosTest;
+const scenarioCapsule_1 = require("./scenarioCapsule");
+const governedSimulation_1 = require("./governedSimulation");
+// ============================================
+// SCENARIO PERTURBATION
+// ============================================
+/** Simple seeded PRNG for reproducible chaos */
+function createRng(seed) {
+    let s = seed;
+    return () => {
+        s = (s * 1664525 + 1013904223) & 0xffffffff;
+        return (s >>> 0) / 0xffffffff;
+    };
+}
+const DISPOSITIONS = ["hostile", "neutral", "supportive"];
+function perturbStakeholders(stakeholders, rng, intensity) {
+    return stakeholders.map((s) => {
+        // Randomly shift dispositions based on intensity
+        if (rng() < intensity * 0.4) {
+            const newDisp = DISPOSITIONS[Math.floor(rng() * DISPOSITIONS.length)];
+            return { ...s, disposition: newDisp };
+        }
+        return { ...s };
+    });
+}
+function perturbScenario(scenario, rng) {
+    // Add random shock modifiers to the scenario text
+    const shocks = [
+        "A sudden liquidity crisis amplifies all pressures.",
+        "An unexpected regulatory announcement creates panic.",
+        "A major player unexpectedly exits the market.",
+        "Coordinated action by hostile actors intensifies pressure.",
+        "Communication systems experience partial failure.",
+        "Public sentiment shifts dramatically against incumbents.",
+        "A previously hidden risk factor suddenly materializes.",
+        "Cross-market contagion accelerates beyond models.",
+        "A trusted institution's credibility collapses.",
+        "External geopolitical shock compounds the crisis.",
+    ];
+    const numShocks = Math.floor(rng() * 3) + 1;
+    const selected = [];
+    for (let i = 0; i < numShocks; i++) {
+        const idx = Math.floor(rng() * shocks.length);
+        if (!selected.includes(shocks[idx])) {
+            selected.push(shocks[idx]);
+        }
+    }
+    return scenario + " " + selected.join(" ");
+}
+function perturbPaths(paths, rng, intensity) {
+    return paths.map((p) => ({
+        ...p,
+        probability: Math.max(0.05, Math.min(0.95, p.probability + (rng() - 0.5) * intensity * 0.4)),
+        risk: rng() < intensity * 0.3
+            ? ["moderate", "high", "critical"][Math.floor(rng() * 3)]
+            : p.risk,
+    }));
+}
+async function runChaosTest(presetId, options = {}) {
+    const { runs = 100, intensity = 0.6, seed = Date.now(), onProgress, } = options;
+    // Resolve scenario
+    const { request, world, paths } = resolvePreset(presetId);
+    const startTime = Date.now();
+    const rng = createRng(seed);
+    // Collect per-run results
+    const results = [];
+    for (let i = 0; i < runs; i++) {
+        // Perturb the scenario for this run
+        const perturbedRequest = {
+            ...request,
+            scenario: perturbScenario(request.scenario, rng),
+            stakeholders: perturbStakeholders(request.stakeholders, rng, intensity),
+        };
+        const perturbedPaths = perturbPaths(paths, rng, intensity);
+        const result = await (0, governedSimulation_1.runGovernedComparison)(perturbedRequest, world, perturbedPaths);
+        results.push(result);
+        if (onProgress)
+            onProgress(i + 1, runs);
+    }
+    const durationMs = Date.now() - startTime;
+    // Aggregate
+    return aggregateResults(presetId, results, durationMs);
+}
+function resolvePreset(presetId) {
+    if (presetId === "trading" || presetId === "flash_crash") {
+        return {
+            request: governedSimulation_1.TRADING_DEMO.scenario,
+            world: governedSimulation_1.TRADING_DEMO.world,
+            paths: governedSimulation_1.TRADING_DEMO.paths,
+        };
+    }
+    const template = scenarioCapsule_1.SCENARIO_TEMPLATES[presetId];
+    if (!template) {
+        throw new Error(`Unknown preset: ${presetId}. Available: trading, ${Object.keys(scenarioCapsule_1.SCENARIO_TEMPLATES).join(", ")}`);
+    }
+    if (!template.world?.inline_definition) {
+        throw new Error(`Preset "${presetId}" has no world definition for chaos testing.`);
+    }
+    const request = {
+        scenario: template.scenario,
+        stakeholders: template.stakeholders,
+        assumptions: template.assumptions,
+        constraints: template.constraints,
+        depth: template.depth,
+        swarm: template.swarm,
+    };
+    const defaultPaths = [
+        {
+            id: "path_primary",
+            label: "Primary Response",
+            description: "Most likely course of action",
+            projected_outcome: "Moderate disruption with cascading effects",
+            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 prioritizing stability",
+            projected_outcome: "Reduced damage but slower recovery",
+            probability: 0.7,
+            risk: "moderate",
+            tradeoffs: ["Safety vs. opportunity cost"],
+            benefits_stakeholders: template.stakeholders.filter(s => s.disposition !== "hostile").map(s => s.id),
+            harms_stakeholders: [],
+        },
+    ];
+    return { request, world: template.world.inline_definition, paths: defaultPaths };
+}
+// ============================================
+// RESULT AGGREGATION
+// ============================================
+function aggregateResults(scenarioId, results, durationMs) {
+    const n = results.length;
+    // Collapse threshold: collapse probability >= 0.5
+    const COLLAPSE_THRESHOLD = 0.5;
+    // Baseline aggregates
+    const baselineCollapses = results.filter(r => r.baseline.metrics.collapseProbability >= COLLAPSE_THRESHOLD).length;
+    const baselineTrajectories = {};
+    let baselineTotalStability = 0;
+    let baselineMinStability = 1;
+    let baselineTotalVolatility = 0;
+    let baselineMaxVolatility = 0;
+    let baselineTotalCoalitionRisks = 0;
+    for (const r of results) {
+        const m = r.baseline.metrics;
+        baselineTotalStability += m.stabilityScore;
+        baselineMinStability = Math.min(baselineMinStability, m.stabilityScore);
+        baselineTotalVolatility += m.maxVolatility;
+        baselineMaxVolatility = Math.max(baselineMaxVolatility, m.maxVolatility);
+        baselineTotalCoalitionRisks += m.coalitionRisks;
+        const traj = r.baseline.swarm.trajectory;
+        baselineTrajectories[traj] = (baselineTrajectories[traj] ?? 0) + 1;
+    }
+    // Governed aggregates
+    const governedCollapses = results.filter(r => r.governed.metrics.collapseProbability >= COLLAPSE_THRESHOLD).length;
+    const governedTrajectories = {};
+    let governedTotalStability = 0;
+    let governedMinStability = 1;
+    let governedTotalVolatility = 0;
+    let governedMaxVolatility = 0;
+    let governedTotalCoalitionRisks = 0;
+    for (const r of results) {
+        const m = r.governed.metrics;
+        governedTotalStability += m.stabilityScore;
+        governedMinStability = Math.min(governedMinStability, m.stabilityScore);
+        governedTotalVolatility += m.maxVolatility;
+        governedMaxVolatility = Math.max(governedMaxVolatility, m.maxVolatility);
+        governedTotalCoalitionRisks += m.coalitionRisks;
+        const traj = r.governed.swarm.trajectory;
+        governedTrajectories[traj] = (governedTrajectories[traj] ?? 0) + 1;
+    }
+    // Impact aggregates
+    let totalEffectiveness = 0;
+    let improvementCount = 0;
+    let totalStabilityImprovement = 0;
+    let totalVolatilityReduction = 0;
+    for (const r of results) {
+        totalEffectiveness += r.comparison.governanceEffectiveness;
+        totalStabilityImprovement += r.comparison.stabilityImprovement;
+        totalVolatilityReduction += r.comparison.volatilityReduction;
+        if (r.comparison.governanceEffectiveness > 0)
+            improvementCount++;
+    }
+    // Most triggered rules — count gate triggers across all runs
+    const gateTriggerMap = new Map();
+    for (const r of results) {
+        for (const gate of r.worldRules.gates) {
+            const existing = gateTriggerMap.get(gate.id) ?? { label: gate.label, count: 0, severity: gate.severity };
+            existing.count++;
+            gateTriggerMap.set(gate.id, existing);
+        }
+        // Count from governance stats
+        for (const guardId of r.governanceStats.triggeredGuards) {
+            const existing = gateTriggerMap.get(guardId) ?? { label: guardId, count: 0, severity: "guard" };
+            existing.count++;
+            gateTriggerMap.set(guardId, existing);
+        }
+    }
+    const topRules = [...gateTriggerMap.entries()]
+        .map(([id, data]) => ({ ruleId: id, label: data.label, triggerCount: data.count, severity: data.severity }))
+        .sort((a, b) => b.triggerCount - a.triggerCount)
+        .slice(0, 5);
+    // Worst cases — runs with highest baseline collapse + lowest governed stability
+    const worstCases = results
+        .map((r, i) => ({
+        runIndex: i,
+        baselineCollapse: r.baseline.metrics.collapseProbability,
+        governedCollapse: r.governed.metrics.collapseProbability,
+        baselineStability: r.baseline.metrics.stabilityScore,
+        governedStability: r.governed.metrics.stabilityScore,
+        volatility: r.baseline.metrics.maxVolatility,
+    }))
+        .sort((a, b) => b.baselineCollapse - a.baselineCollapse)
+        .slice(0, 3);
+    // Engine stats
+    let totalGuardEvals = 0;
+    const totalVerdicts = { allow: 0, block: 0, pause: 0 };
+    let totalRulesFired = 0;
+    let engineLoaded = false;
+    for (const r of results) {
+        const gs = r.governanceStats;
+        if (gs.engineLoaded)
+            engineLoaded = true;
+        totalGuardEvals += gs.totalEvaluations;
+        totalVerdicts.allow += gs.verdicts.allow;
+        totalVerdicts.block += gs.verdicts.block;
+        totalVerdicts.pause += gs.verdicts.pause;
+        totalRulesFired += gs.rulesFired;
+    }
+    return {
+        scenarioId,
+        runsCompleted: n,
+        durationMs,
+        baseline: {
+            collapseCount: baselineCollapses,
+            collapseProbability: baselineCollapses / n,
+            avgStability: baselineTotalStability / n,
+            minStability: baselineMinStability,
+            avgVolatility: baselineTotalVolatility / n,
+            maxVolatility: baselineMaxVolatility,
+            avgCoalitionRisks: baselineTotalCoalitionRisks / n,
+            trajectories: baselineTrajectories,
+        },
+        governed: {
+            collapseCount: governedCollapses,
+            collapseProbability: governedCollapses / n,
+            avgStability: governedTotalStability / n,
+            minStability: governedMinStability,
+            avgVolatility: governedTotalVolatility / n,
+            maxVolatility: governedMaxVolatility,
+            avgCoalitionRisks: governedTotalCoalitionRisks / n,
+            trajectories: governedTrajectories,
+        },
+        impact: {
+            collapseReduction: (baselineCollapses - governedCollapses) / n * 100,
+            avgStabilityImprovement: totalStabilityImprovement / n,
+            avgVolatilityReduction: totalVolatilityReduction / n,
+            avgEffectiveness: totalEffectiveness / n,
+            improvementRate: improvementCount / n,
+        },
+        topRules,
+        worstCases,
+        engineStats: {
+            engineLoaded,
+            totalGuardEvals,
+            totalVerdicts,
+            totalRulesFired,
+        },
+    };
+}