@neuroverseos/nv-sim 0.1.0 → 0.1.4

package/dist/engine/narrativeInjection.js

@@ -0,0 +1,305 @@
+"use strict";
+/**
+ * Narrative Injection — Information Shocks for Agent Simulations
+ *
+ * The third knob: agents + world rules + narrative events.
+ *
+ * Narrative injection models how information shocks propagate through
+ * agent networks. Instead of just changing rules, you inject events
+ * that shift beliefs, trigger reactions, and reorganize clusters.
+ *
+ * Usage:
+ *   nv-sim compare --inject tanker_explosion@5
+ *   nv-sim worlds trading strait_of_hormuz --inject rate_cut@3,sanctions@6
+ *   nv-sim visualize --inject "China begins military exercises"@4
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NARRATIVE_PRESETS = void 0;
+exports.injectNarrative = injectNarrative;
+exports.parseInjectArgs = parseInjectArgs;
+exports.getEventsForRound = getEventsForRound;
+// ============================================
+// SEVERITY → MAGNITUDE MAPPING
+// ============================================
+const SEVERITY_MAGNITUDE = {
+    minor: 0.1,
+    moderate: 0.25,
+    major: 0.45,
+    extreme: 0.7,
+};
+const PROPAGATION_MULTIPLIER = {
+    slow: 0.6,
+    normal: 1.0,
+    viral: 1.4,
+};
+// ============================================
+// NARRATIVE INJECTION ENGINE
+// ============================================
+/**
+ * Apply a narrative event to a set of agent reactions.
+ *
+ * This models how an information shock propagates through the network:
+ * - Targeted agents get the full impact
+ * - Related agents get partial impact (network effect)
+ * - Unrelated agents get minimal impact (background noise)
+ * - Confidence shifts based on event clarity
+ */
+function injectNarrative(reactions, event, stakeholders) {
+    const magnitude = SEVERITY_MAGNITUDE[event.severity];
+    const propagation = PROPAGATION_MULTIPLIER[event.propagation];
+    const direction = event.direction === "positive" ? 1 : event.direction === "negative" ? -1 : 0;
+    const agentShifts = [];
+    const systemEffects = [];
+    systemEffects.push(`EVENT INJECTED: "${event.headline}"`);
+    systemEffects.push(`Severity: ${event.severity} | Propagation: ${event.propagation}`);
+    for (const reaction of reactions) {
+        const stakeholder = stakeholders.find(s => s.id === reaction.stakeholder_id);
+        const isTargeted = event.targets.some(t => reaction.stakeholder_id.toLowerCase().includes(t.toLowerCase()) ||
+            t.toLowerCase().includes(reaction.stakeholder_id.toLowerCase()));
+        // Determine how much this agent is affected
+        let sensitivity;
+        let reason;
+        if (isTargeted) {
+            // Directly targeted — full impact
+            sensitivity = 1.0;
+            reason = `directly targeted by "${event.headline}"`;
+        }
+        else if (stakeholder?.disposition === "hostile") {
+            // Hostile agents are more reactive to shocks
+            sensitivity = 0.6;
+            reason = `hostile disposition amplifies reaction to "${event.headline}"`;
+        }
+        else if (stakeholder?.disposition === "neutral") {
+            // Neutral agents react moderately
+            sensitivity = 0.35;
+            reason = `neutral stance — moderate reaction to "${event.headline}"`;
+        }
+        else {
+            // Supportive or unknown — less reactive to negative shocks
+            sensitivity = 0.2;
+            reason = `indirect exposure to "${event.headline}"`;
+        }
+        // Calculate belief shift
+        let impactShift;
+        if (direction === 0) {
+            // Mixed direction — push toward extremes based on existing position
+            impactShift = reaction.impact > 0
+                ? magnitude * sensitivity * propagation * 0.5
+                : -magnitude * sensitivity * propagation * 0.5;
+            reason += " (mixed signal — amplifies existing position)";
+        }
+        else {
+            impactShift = direction * magnitude * sensitivity * propagation;
+        }
+        // Confidence shift — shocks generally reduce confidence for non-targeted
+        const confidenceShift = isTargeted
+            ? 0.1 * propagation // targeted agents gain conviction
+            : -0.05 * magnitude * propagation; // others become less certain
+        // Apply shifts
+        const newImpact = Math.max(-1, Math.min(1, reaction.impact + impactShift));
+        const newConfidence = Math.max(0.05, Math.min(1, reaction.confidence + confidenceShift));
+        reaction.impact = Number(newImpact.toFixed(3));
+        reaction.confidence = Number(newConfidence.toFixed(3));
+        agentShifts.push({
+            stakeholder_id: reaction.stakeholder_id,
+            impactShift: Number(impactShift.toFixed(3)),
+            confidenceShift: Number(confidenceShift.toFixed(3)),
+            reason,
+        });
+    }
+    // Detect system-level effects
+    const totalShift = agentShifts.reduce((s, a) => s + Math.abs(a.impactShift), 0);
+    if (totalShift > reactions.length * 0.3) {
+        systemEffects.push("NARRATIVE CASCADE: event caused widespread belief shifts");
+    }
+    const polarization = reactions.filter(r => r.impact > 0.3).length > 0 &&
+        reactions.filter(r => r.impact < -0.3).length > 0;
+    if (polarization) {
+        systemEffects.push("POLARIZATION: event split agent consensus");
+    }
+    const consensus = Math.abs(reactions.reduce((s, r) => s + r.impact, 0) / reactions.length);
+    if (consensus > 0.5) {
+        systemEffects.push(`CONSENSUS SHIFT: agents aligned around ${consensus > 0 ? "positive" : "negative"} narrative`);
+    }
+    return { event, agentShifts, systemEffects };
+}
+// ============================================
+// PRESET NARRATIVE EVENTS
+// ============================================
+exports.NARRATIVE_PRESETS = {
+    // Trading / Financial
+    tanker_explosion: {
+        id: "tanker_explosion",
+        headline: "Oil tanker hit by missile in Strait of Hormuz",
+        severity: "extreme",
+        targets: ["Energy", "Traders", "Financial", "Algorithmic"],
+        direction: "negative",
+        propagation: "viral",
+        category: "geopolitical",
+    },
+    rate_cut: {
+        id: "rate_cut",
+        headline: "Federal Reserve announces emergency rate cut",
+        severity: "major",
+        targets: ["Central Banks", "Institutional", "Financial", "Market"],
+        direction: "positive",
+        propagation: "viral",
+        category: "monetary",
+    },
+    bank_collapse: {
+        id: "bank_collapse",
+        headline: "Major bank reports insolvency — contagion fears",
+        severity: "extreme",
+        targets: ["Institutional", "Retail", "Financial", "Market Makers"],
+        direction: "negative",
+        propagation: "viral",
+        category: "financial",
+    },
+    flash_crash_rumor: {
+        id: "flash_crash_rumor",
+        headline: "Rumors of algorithmic trading malfunction spread",
+        severity: "moderate",
+        targets: ["Algorithmic", "Traders", "Retail"],
+        direction: "negative",
+        propagation: "normal",
+        category: "market",
+    },
+    sanctions: {
+        id: "sanctions",
+        headline: "New economic sanctions imposed on major oil producer",
+        severity: "major",
+        targets: ["Energy", "Government", "OPEC", "Oil"],
+        direction: "negative",
+        propagation: "normal",
+        category: "geopolitical",
+    },
+    // Geopolitical
+    taiwan_exercises: {
+        id: "taiwan_exercises",
+        headline: "China begins military exercises near Taiwan",
+        severity: "major",
+        targets: ["Military", "Government", "Financial", "Traders"],
+        direction: "negative",
+        propagation: "viral",
+        category: "geopolitical",
+    },
+    diplomatic_breakthrough: {
+        id: "diplomatic_breakthrough",
+        headline: "Surprise diplomatic agreement reached — tensions ease",
+        severity: "major",
+        targets: ["Government", "Military", "Financial"],
+        direction: "positive",
+        propagation: "normal",
+        category: "geopolitical",
+    },
+    ceasefire: {
+        id: "ceasefire",
+        headline: "Ceasefire announced — shipping lanes reopening",
+        severity: "moderate",
+        targets: ["Energy", "Military", "Government", "Consumers"],
+        direction: "positive",
+        propagation: "normal",
+        category: "geopolitical",
+    },
+    // Political / Regulatory
+    candidate_indicted: {
+        id: "candidate_indicted",
+        headline: "Leading candidate indicted on corruption charges",
+        severity: "major",
+        targets: ["Politicians", "Consumers", "Media"],
+        direction: "mixed",
+        propagation: "viral",
+        category: "political",
+    },
+    regulation_shock: {
+        id: "regulation_shock",
+        headline: "Unexpected strict AI regulation passed overnight",
+        severity: "major",
+        targets: ["Regulators", "EV", "Grid", "AI"],
+        direction: "negative",
+        propagation: "normal",
+        category: "regulatory",
+    },
+    stimulus_package: {
+        id: "stimulus_package",
+        headline: "Emergency fiscal stimulus package announced",
+        severity: "moderate",
+        targets: ["Government", "Consumers", "Financial"],
+        direction: "positive",
+        propagation: "normal",
+        category: "economic",
+    },
+    // Energy
+    grid_failure: {
+        id: "grid_failure",
+        headline: "Regional power grid failure — rolling blackouts",
+        severity: "major",
+        targets: ["Grid", "Consumers", "EV", "Energy"],
+        direction: "negative",
+        propagation: "normal",
+        category: "infrastructure",
+    },
+    oil_discovery: {
+        id: "oil_discovery",
+        headline: "Major new oil field discovered — supply outlook shifts",
+        severity: "moderate",
+        targets: ["Energy", "Oil", "OPEC", "Consumers"],
+        direction: "positive",
+        propagation: "slow",
+        category: "energy",
+    },
+};
+// ============================================
+// CLI ARGUMENT PARSING
+// ============================================
+/**
+ * Parse --inject arguments into NarrativeEvent arrays.
+ *
+ * Format: --inject event_id@round[,event_id@round,...]
+ * Or:     --inject "Custom headline"@round
+ *
+ * Examples:
+ *   --inject tanker_explosion@5
+ *   --inject rate_cut@3,sanctions@6
+ *   --inject "Bank collapses"@8
+ */
+function parseInjectArgs(args) {
+    const injectIdx = args.indexOf("--inject");
+    if (injectIdx === -1 || !args[injectIdx + 1])
+        return [];
+    const injectStr = args[injectIdx + 1];
+    const events = [];
+    for (const part of injectStr.split(",")) {
+        const atIdx = part.lastIndexOf("@");
+        if (atIdx === -1)
+            continue;
+        const eventId = part.slice(0, atIdx).trim();
+        const round = parseInt(part.slice(atIdx + 1), 10);
+        if (isNaN(round))
+            continue;
+        const preset = exports.NARRATIVE_PRESETS[eventId];
+        if (preset) {
+            events.push({ ...preset, round });
+        }
+        else {
+            // Custom headline
+            events.push({
+                id: `custom_${round}`,
+                headline: eventId.replace(/^["']|["']$/g, ""),
+                round,
+                severity: "major",
+                targets: [],
+                direction: "mixed",
+                propagation: "normal",
+                category: "custom",
+            });
+        }
+    }
+    return events;
+}
+/**
+ * Get events scheduled for a specific round.
+ */
+function getEventsForRound(events, round) {
+    return events.filter(e => e.round === round);
+}

package/dist/engine/reasoningEngine.js

@@ -444,13 +444,67 @@ async function processReasonRequest(request) {
         ...governanceResult.enforcedConstraints,
     ];
     // Build NeuroverseOS governance summary
+    // Compute world_health_score from actual simulation dynamics, not static validation
+    let dynamicWorldHealth;
+    if (swarmResult) {
+        const allReactions = swarmResult.rounds.flatMap((r) => r.reactions ?? []);
+        if (allReactions.length > 0) {
+            const allImpacts = allReactions.map((r) => r.impact ?? 0);
+            const avgImpact = allImpacts.reduce((s, i) => s + i, 0) / allImpacts.length;
+            const maxVolatility = Math.max(...allImpacts.map((i) => Math.abs(i)));
+            const impactVariance = allImpacts.reduce((s, i) => s + (i - avgImpact) ** 2, 0) / allImpacts.length;
+            // Stability = f(variance, volatility, trajectory, negative sentiment)
+            let stability = 1 - Math.min(1, impactVariance * 3 + Math.max(0, -avgImpact));
+            if (swarmResult.trajectory === "converging" || swarmResult.trajectory === "stabilizing") {
+                stability = Math.min(1, stability + 0.15);
+            }
+            if (swarmResult.trajectory === "escalating") {
+                stability = Math.max(0, stability - 0.2);
+            }
+            if (swarmResult.trajectory === "diverging") {
+                stability = Math.max(0, stability - 0.15);
+            }
+            // Factor in governance interventions
+            const enforcedCount = enforcedConstraints.length;
+            stability = Math.min(1, stability + enforcedCount * 0.02);
+            dynamicWorldHealth = Math.round(Math.max(0, Math.min(100, stability * 100)));
+        }
+    }
+    // Compute dynamic collapse risk from simulation
+    let dynamicCollapseRisk;
+    if (swarmResult) {
+        const allReactions = swarmResult.rounds.flatMap((r) => r.reactions ?? []);
+        if (allReactions.length > 0) {
+            const allImpacts = allReactions.map((r) => r.impact ?? 0);
+            const avgImpact = allImpacts.reduce((s, i) => s + i, 0) / allImpacts.length;
+            const maxVol = Math.max(...allImpacts.map((i) => Math.abs(i)));
+            let risk = 0;
+            if (swarmResult.trajectory === "escalating")
+                risk += 0.35;
+            if (swarmResult.trajectory === "diverging")
+                risk += 0.25;
+            if (avgImpact < -0.3)
+                risk += 0.25;
+            if (maxVol > 0.7)
+                risk += 0.15;
+            risk = Math.min(0.95, risk);
+            if (risk > 0.5)
+                dynamicCollapseRisk = "high";
+            else if (risk > 0.3)
+                dynamicCollapseRisk = "moderate";
+            else if (risk > 0.1)
+                dynamicCollapseRisk = "low";
+            else
+                dynamicCollapseRisk = "none";
+        }
+    }
     const neuroverseTrace = governanceResult.guardVerdict ? {
         guard_status: governanceResult.guardVerdict.status,
         world_viability: governanceResult.governanceSignals?.viability,
         world_collapsed: governanceResult.governanceSignals?.collapsed,
-        collapse_risk: governanceResult.governanceSignals?.collapseRisk,
-        rules_fired: governanceResult.governanceSignals?.rulesFired,
-        world_health_score: governanceResult.validationReport?.summary.completenessScore,
+        collapse_risk: dynamicCollapseRisk ?? governanceResult.governanceSignals?.collapseRisk,
+        rules_fired: governanceResult.governanceSignals?.rulesFired ?? enforcedConstraints.length,
+        world_health_score: dynamicWorldHealth ?? governanceResult.validationReport?.summary.completenessScore,
         invariant_coverage: governanceResult.validationReport?.summary.invariantCoverage,
     } : undefined;
     const governance = {

package/dist/engine/reportEngine.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * Governed Report Engine
+ *
+ * Generates structured reports from simulation traces.
+ * ALL report generation goes through /world evaluate — even AI-generated reports.
+ *
+ * "Even the AI has to follow the rules."
+ *
+ * Pipeline:
+ *   Trace (ground truth)
+ *     → /world evaluate (ai_analyst actor)
+ *     → governed constraints applied
+ *     → structured report output
+ *     → trace recorded
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractTrace = extractTrace;
+exports.generateGovernedReport = generateGovernedReport;
+const aiProvider_1 = require("./aiProvider");
+// ============================================
+// TRACE EXTRACTION
+// ============================================
+/**
+ * Extract a SimulationTraceInput from a GovernedComparisonResult.
+ * This is the "ground truth" that the report must reference.
+ */
+function extractTrace(comparison) {
+    const governed = comparison.governed;
+    const stats = comparison.governanceStats;
+    const rounds = governed.swarm.rounds.map((r, i) => ({
+        round: r.round,
+        reactions: r.reactions.map(rx => ({
+            agent: rx.stakeholder_id,
+            action: rx.reaction,
+            impact: rx.impact,
+            verdict: undefined,
+        })),
+        interventions: r.emergent_dynamics
+            ?.filter(d => d.includes("[BLOCK]") || d.includes("[PAUSE]") || d.includes("CIRCUIT BREAKER") || d.includes("intervention"))
+            ?? [],
+    }));
+    // Collect all interventions from emergent dynamics
+    const allInterventions = governed.swarm.rounds.flatMap(r => (r.emergent_dynamics ?? []).filter(d => d.includes("[BLOCK]") || d.includes("[PAUSE]") || d.includes("GATE") || d.includes("Rebalanced") || d.includes("Capped")));
+    const metrics = {
+        avgImpact: governed.metrics.avgImpact,
+        collapseProbability: governed.metrics.collapseProbability,
+        stabilityScore: governed.metrics.stabilityScore,
+        maxVolatility: governed.metrics.maxVolatility,
+        peakNegativeSentiment: governed.metrics.peakNegativeSentiment,
+    };
+    return {
+        scenario: comparison.scenario,
+        rounds,
+        metrics,
+        interventions: allInterventions,
+        governanceStats: {
+            totalEvaluations: stats.totalEvaluations,
+            blocks: stats.verdicts.block,
+            pauses: stats.verdicts.pause,
+            allows: stats.verdicts.allow,
+            rulesFired: stats.rulesFired,
+        },
+    };
+}
+/**
+ * Generate a governed report from a simulation comparison.
+ *
+ * This is the main entry point. It:
+ *   1. Extracts the trace (ground truth)
+ *   2. Routes through /world evaluate (ai_analyst actor)
+ *   3. Validates governance constraints
+ *   4. Returns structured report with governance trace
+ */
+async function generateGovernedReport(comparison, options = {}) {
+    const trace = extractTrace(comparison);
+    const aiEnabled = options.aiEnabled ?? false;
+    const providerName = aiEnabled ? (options.provider ?? "deterministic") : "deterministic";
+    const provider = (0, aiProvider_1.getAIProvider)(providerName);
+    // Find the ai_analyst role
+    const analystRole = aiProvider_1.AI_ROLES.find(r => r.id === "ai_analyst");
+    // Route through governance: /world evaluate
+    const governance = await (0, aiProvider_1.evaluateAIAction)(analystRole, "generate_report", async () => {
+        if (aiEnabled && providerName !== "deterministic") {
+            // AI provider generates report — still governed
+            return provider.summarize(trace);
+        }
+        // Deterministic: generate from trace data only
+        return (0, aiProvider_1.generateDeterministicReport)(trace);
+    });
+    return {
+        report: governance.result,
+        governance,
+        aiUsed: aiEnabled && providerName !== "deterministic",
+        provider: providerName,
+    };
+}