@neuroverseos/nv-sim 0.1.2 → 0.1.5

package/dist/engine/metrics/science.metrics.js

@@ -0,0 +1,335 @@
+"use strict";
+/**
+ * Science Metrics Module — Evaluation Metrics for Autonomous Discovery
+ *
+ * "ScienceClaw explores possibility. NeuroVerse enforces reality."
+ *
+ * These metrics evaluate the quality of governed scientific discovery.
+ * They plug directly into scenarioComparison.ts as EvaluationMetric[].
+ *
+ * The five core science metrics:
+ *   1. Convergence Quality  — are we converging on truth, or on noise?
+ *   2. Reproducibility Score — can findings be independently validated?
+ *   3. Provenance Depth     — how deep is the evidence chain?
+ *   4. Compute Efficiency   — are we burning cycles on dead ends?
+ *   5. False Positive Rate  — how much garbage survives the pipeline?
+ *
+ * Science-specific system state extends the base SystemState with:
+ *   - artifact_density: how many artifacts per round
+ *   - validation_gap: how far behind validation lags discovery
+ *   - citation_circularity: self-referencing chains
+ *   - hypothesis_diversity: breadth of active investigation
+ *   - convergence_velocity: how fast hypotheses collapse to consensus
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCIENCE_INITIAL_STATE = exports.SCIENCE_POLICY_TEXT = exports.SCIENCE_METRICS = void 0;
+exports.interpretScienceState = interpretScienceState;
+// ============================================
+// METRIC EXTRACTORS
+// ============================================
+/**
+ * Extract convergence quality from simulation results.
+ *
+ * Good convergence:
+ *   - Low polarization (hypotheses are consolidating, not fragmenting)
+ *   - Moderate velocity (not too fast = shallow, not too slow = stuck)
+ *   - High trust (findings are reproducible)
+ *
+ * Bad convergence:
+ *   - High polarization (field is fragmenting)
+ *   - Very high velocity (premature consensus without evidence)
+ *   - Low trust (findings can't be reproduced)
+ */
+function extractConvergenceQuality(result) {
+    const state = result.finalState;
+    // Low polarization → hypotheses consolidating (good)
+    const consolidation = 1 - state.polarization;
+    // Moderate velocity is ideal — too fast is shallow, too slow is stuck
+    // Sweet spot: 0.3-0.6
+    const velocityScore = state.informationVelocity >= 0.3 && state.informationVelocity <= 0.6
+        ? 1.0
+        : state.informationVelocity < 0.3
+            ? state.informationVelocity / 0.3 // too slow
+            : 1 - (state.informationVelocity - 0.6) / 0.4; // too fast
+    // High trust → reproducible findings
+    const reproducibility = state.trust;
+    // Low cascade risk → findings aren't propagating unchecked
+    const integrityScore = 1 - state.cascadeRisk;
+    return (consolidation * 0.3 +
+        velocityScore * 0.25 +
+        reproducibility * 0.25 +
+        integrityScore * 0.2);
+}
+/**
+ * Extract reproducibility score.
+ *
+ * In science mode:
+ *   trust = can we reproduce findings?
+ *   low outrage = no publication pressure forcing premature claims
+ *   low cascade risk = bad results aren't propagating through citations
+ */
+function extractReproducibilityScore(result) {
+    const state = result.finalState;
+    // Trust is the primary indicator of reproducibility
+    const trustScore = state.trust;
+    // Low publication pressure (outrage = rush to publish)
+    const pressureScore = 1 - state.outrage;
+    // Low cascade risk = validated results, not propagated noise
+    const validationScore = 1 - state.cascadeRisk;
+    // Governance effectiveness indicates active quality control
+    const govEffectiveness = result.dynamicsGovernance.totalInterventions > 0
+        ? Math.min(1, result.dynamicsGovernance.trustBoosts / Math.max(1, result.dynamicsGovernance.totalRounds) + 0.3)
+        : 0.3;
+    return (trustScore * 0.35 +
+        pressureScore * 0.2 +
+        validationScore * 0.25 +
+        govEffectiveness * 0.2);
+}
+/**
+ * Extract provenance depth score.
+ *
+ * Deeper provenance chains = better evidence foundations.
+ * In the simulation, this maps to:
+ *   - contagionDepth (how deep content propagates = evidence chain depth)
+ *   - Low amplification (not relying on popularity over evidence)
+ *   - Multiple rounds of stable findings (temporal depth)
+ */
+function extractProvenanceDepth(result) {
+    const state = result.finalState;
+    const timeline = result.stateTimeline;
+    // Contagion depth as proxy for evidence chain depth (normalized)
+    // In science: deeper propagation means findings pass through more validation layers
+    const depthScore = Math.min(1, state.contagionDepth / 5);
+    // Low amplification = findings stand on evidence, not popularity
+    const evidenceVsPopularity = Math.max(0, 1 - (state.amplification - 0.5));
+    // Temporal depth: how many rounds did findings persist stably?
+    let stableRounds = 0;
+    for (let i = 1; i < timeline.length; i++) {
+        const delta = Math.abs(timeline[i].trust - timeline[i - 1].trust);
+        if (delta < 0.05)
+            stableRounds++;
+    }
+    const temporalDepth = timeline.length > 1
+        ? stableRounds / (timeline.length - 1)
+        : 0.5;
+    return (depthScore * 0.35 +
+        evidenceVsPopularity * 0.3 +
+        temporalDepth * 0.35);
+}
+/**
+ * Extract compute efficiency.
+ *
+ * Efficient discovery:
+ *   - Not too many governance interventions (focused paths)
+ *   - Good block rate (filtering noise early, not late)
+ *   - Low variance in impact (agents working in coordination, not chaos)
+ */
+function extractComputeEfficiency(result) {
+    const ag = result.actionGovernance;
+    const dg = result.dynamicsGovernance;
+    // Block rate: some blocking is efficient (filtering noise), too much is wasteful
+    const blockRate = ag.totalEvaluations > 0 ? ag.blocked / ag.totalEvaluations : 0;
+    let filterEfficiency;
+    if (blockRate < 0.1)
+        filterEfficiency = 0.4; // too permissive — noise gets through
+    else if (blockRate < 0.3)
+        filterEfficiency = 0.9; // sweet spot
+    else if (blockRate < 0.5)
+        filterEfficiency = 0.7; // slightly aggressive
+    else
+        filterEfficiency = 0.3; // over-filtering — blocking productive work
+    // Intervention density: interventions per round
+    // Some interventions = course correcting (good)
+    // Too many = system is fundamentally unstable
+    const interventionDensity = dg.totalRounds > 0
+        ? dg.totalInterventions / dg.totalRounds
+        : 0;
+    const interventionScore = interventionDensity <= 2
+        ? 0.8 + interventionDensity * 0.1
+        : Math.max(0.2, 1 - (interventionDensity - 2) * 0.15);
+    // Impact consistency: low variance in final reactions = coordinated work
+    const rounds = result.rounds;
+    if (rounds.length === 0)
+        return 0.5;
+    const lastRound = rounds[rounds.length - 1];
+    const impacts = lastRound.finalReactions.map(r => r.impact);
+    const mean = impacts.reduce((s, i) => s + i, 0) / impacts.length;
+    const variance = impacts.reduce((s, i) => s + (i - mean) ** 2, 0) / impacts.length;
+    const coordinationScore = Math.max(0, 1 - variance * 3);
+    return (filterEfficiency * 0.35 +
+        interventionScore * 0.3 +
+        coordinationScore * 0.35);
+}
+/**
+ * Extract false positive rate (inverted — higher returned value = fewer false positives = better).
+ *
+ * False positives in science:
+ *   - High cascade risk = bad results propagating through citation chains
+ *   - High amplification = popular but wrong findings being boosted
+ *   - Low trust = findings can't be reproduced
+ *   - High outrage = publication pressure creating rushed claims
+ */
+function extractFalsePositiveRate(result) {
+    const state = result.finalState;
+    const dg = result.dynamicsGovernance;
+    // Low cascade risk = bad results caught before spreading
+    const cascadeControl = 1 - state.cascadeRisk;
+    // Low amplification = not amplifying unvalidated findings
+    const amplificationControl = Math.max(0, 1 - (state.amplification - 0.5) * 2);
+    // High trust = reproducible findings
+    const trustScore = state.trust;
+    // Cascade breakers fired = system caught and stopped false positives
+    const breakerBonus = dg.cascadeBreakers > 0 ? 0.1 : 0;
+    // Low publication pressure
+    const pressureScore = 1 - state.outrage;
+    const raw = (cascadeControl * 0.3 +
+        amplificationControl * 0.2 +
+        trustScore * 0.25 +
+        pressureScore * 0.15 +
+        breakerBonus);
+    return Math.min(1, raw + 0.1); // slight bias toward positive — governance is working
+}
+// ============================================
+// EXPORTED SCIENCE METRICS
+// ============================================
+/**
+ * Science evaluation metrics — plug directly into scenarioComparison.ts.
+ *
+ * Usage:
+ *   import { SCIENCE_METRICS } from "./metrics/science.metrics"
+ *   const result = await runScenarioMatrix({
+ *     ...config,
+ *     evaluationMetrics: SCIENCE_METRICS,
+ *   })
+ */
+exports.SCIENCE_METRICS = [
+    {
+        id: "convergence_quality",
+        label: "Convergence Quality",
+        weight: 0.25,
+        extractor: extractConvergenceQuality,
+    },
+    {
+        id: "reproducibility",
+        label: "Reproducibility Score",
+        weight: 0.25,
+        extractor: extractReproducibilityScore,
+    },
+    {
+        id: "provenance_depth",
+        label: "Provenance Depth",
+        weight: 0.20,
+        extractor: extractProvenanceDepth,
+    },
+    {
+        id: "compute_efficiency",
+        label: "Compute Efficiency",
+        weight: 0.15,
+        extractor: extractComputeEfficiency,
+    },
+    {
+        id: "false_positive_control",
+        label: "False Positive Control",
+        weight: 0.15,
+        extractor: extractFalsePositiveRate,
+    },
+];
+// ============================================
+// SCIENCE-SPECIFIC DYNAMICS RULES (policy text)
+// ============================================
+/**
+ * Default policy text for scientific discovery governance.
+ * These map to dynamics rules in governDynamics():
+ *   - propagation rules → hypothesis spread control
+ *   - amplification rules → citation amplification dampening
+ *   - cascade rules → false positive cascade breaking
+ *   - trust rules → reproducibility enforcement
+ *   - feedback rules → publication pressure dampening
+ */
+exports.SCIENCE_POLICY_TEXT = [
+    // Propagation control — limit hypothesis spread without evidence
+    "Limit propagation of causal claims that lack multi-source evidence",
+    "Contain unvalidated hypotheses within originating research group",
+    "Quarantine findings that have not passed independent reproduction",
+    // Amplification dampening — prevent citation echo chambers
+    "Dampen amplification of self-citation loops exceeding 3 generations",
+    "Limit influence of popular findings that lack independent validation",
+    "Reduce visibility of papers with high citation velocity but low reproduction rate",
+    // Cascade breaking — stop false positives from compounding
+    "Circuit break when cascade of dependent findings exceeds validation capacity",
+    "Halt chain reaction of derivative conclusions from unvalidated premises",
+    "Break feedback loops between competing research groups amplifying each other",
+    // Trust / reproducibility enforcement
+    "Boost visibility of independently reproduced findings",
+    "Require transparency in methodology for all published artifacts",
+    "Prioritize credibility of findings with transparent provenance chains",
+    // Publication pressure dampening
+    "Dampen rush-to-publish behavior during high-competition periods",
+    "Cool down reactive publication patterns when controversy index rises",
+    "Stabilize publication rate during peer review bottlenecks",
+    // Compute governance
+    "Pause redundant investigation paths when convergence detected",
+    "Halt compute-intensive explorations that show no evidence of progress",
+].join("\n");
+// ============================================
+// SCIENCE STATE INITIALIZATION
+// ============================================
+/**
+ * Initial system state tuned for scientific discovery.
+ *
+ * Differences from behavior simulation:
+ *   - Higher trust baseline (science starts from credibility)
+ *   - Lower outrage (publication pressure starts manageable)
+ *   - Lower amplification (citations start organic)
+ *   - Moderate velocity (discovery is active but not frantic)
+ */
+exports.SCIENCE_INITIAL_STATE = {
+    polarization: 0.15, // Some hypothesis diversity (healthy)
+    outrage: 0.05, // Low publication pressure initially
+    trust: 0.8, // Science starts with high credibility
+    informationVelocity: 0.4, // Active discovery pace
+    amplification: 0.6, // Organic citation patterns
+    cascadeRisk: 0.05, // Low false positive risk initially
+    contagionDepth: 3, // Moderate evidence chain depth
+    coolingPeriod: 0,
+};
+// ============================================
+// SCIENCE STATE INTERPRETER
+// ============================================
+/**
+ * Interpret base SystemState through a science lens.
+ * Maps generic governance metrics to science-specific language.
+ */
+function interpretScienceState(state) {
+    const fragLevel = state.polarization > 0.6 ? "critical" : state.polarization > 0.3 ? "elevated" : "healthy";
+    const pressureLevel = state.outrage > 0.5 ? "dangerous" : state.outrage > 0.2 ? "elevated" : "normal";
+    const reproLevel = state.trust > 0.7 ? "high" : state.trust > 0.4 ? "moderate" : "crisis";
+    const citationLevel = state.amplification > 1.5 ? "echo chamber" : state.amplification > 0.8 ? "amplified" : "organic";
+    const fpRisk = state.cascadeRisk > 0.5 ? "high" : state.cascadeRisk > 0.2 ? "moderate" : "controlled";
+    const velocity = state.informationVelocity > 0.7 ? "frantic" : state.informationVelocity > 0.3 ? "active" : "stalled";
+    let overall;
+    if (state.trust > 0.6 && state.cascadeRisk < 0.3 && state.polarization < 0.4) {
+        overall = "Healthy discovery — findings are converging with evidence support";
+    }
+    else if (state.cascadeRisk > 0.6) {
+        overall = "False positive cascade risk — unvalidated findings propagating through citations";
+    }
+    else if (state.polarization > 0.6) {
+        overall = "Field fragmentation — competing hypotheses without resolution mechanism";
+    }
+    else if (state.trust < 0.3) {
+        overall = "Reproducibility crisis — institutional credibility collapsing";
+    }
+    else {
+        overall = "Active investigation — governance maintaining discovery quality";
+    }
+    return {
+        hypothesisFragmentation: `${fragLevel} (${(state.polarization * 100).toFixed(0)}%)`,
+        publicationPressure: `${pressureLevel} (${(state.outrage * 100).toFixed(0)}%)`,
+        reproducibilityConfidence: `${reproLevel} (${(state.trust * 100).toFixed(0)}%)`,
+        citationHealth: `${citationLevel} (${state.amplification.toFixed(2)}x)`,
+        falsePositiveRisk: `${fpRisk} (${(state.cascadeRisk * 100).toFixed(0)}%)`,
+        discoveryVelocity: `${velocity} (${(state.informationVelocity * 100).toFixed(0)}%)`,
+        overallAssessment: overall,
+    };
+}

package/dist/engine/narrativeInjection.js

@@ -0,0 +1,360 @@
+"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",
+    },
+    // Science / Research
+    search_literature: {
+        id: "search_literature",
+        headline: "Agent searches PubMed for peer-reviewed sources",
+        severity: "minor",
+        targets: ["Research Agent", "Peer Reviewers"],
+        direction: "positive",
+        propagation: "slow",
+        category: "research",
+    },
+    analyze_findings: {
+        id: "analyze_findings",
+        headline: "Agent analyzes findings and extracts key mechanisms",
+        severity: "moderate",
+        targets: ["Research Agent", "Peer Reviewers"],
+        direction: "positive",
+        propagation: "slow",
+        category: "research",
+    },
+    cross_reference: {
+        id: "cross_reference",
+        headline: "Agent cross-references sources for consistency",
+        severity: "moderate",
+        targets: ["Research Agent", "Peer Reviewers", "Journal Editors"],
+        direction: "positive",
+        propagation: "slow",
+        category: "research",
+    },
+    unsupported_claim: {
+        id: "unsupported_claim",
+        headline: "Agent attempts to publish claim without sufficient sources",
+        severity: "major",
+        targets: ["Research Agent", "Public", "Peer Reviewers"],
+        direction: "negative",
+        propagation: "normal",
+        category: "research",
+    },
+    hypothesis_validated: {
+        id: "hypothesis_validated",
+        headline: "Hypothesis validated by multiple independent sources",
+        severity: "major",
+        targets: ["Research Agent", "Peer Reviewers", "Funding Bodies"],
+        direction: "positive",
+        propagation: "normal",
+        category: "research",
+    },
+    publish_result: {
+        id: "publish_result",
+        headline: "Agent submits findings for publication",
+        severity: "major",
+        targets: ["Research Agent", "Journal Editors", "Public", "Peer Reviewers"],
+        direction: "mixed",
+        propagation: "normal",
+        category: "research",
+    },
+};
+// ============================================
+// 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);
+}