@neuroverseos/nv-sim 0.1.0

package/dist/engine/goalEngine.js

@@ -0,0 +1,559 @@
+"use strict";
+/**
+ * Goal-Directed Strategy Engine
+ *
+ * "Find the path through the swarm."
+ *
+ * When a user specifies a desired outcome, this engine works BACKWARD
+ * from the goal to generate candidate strategies, then tests each one
+ * against the swarm simulation to rank feasibility.
+ *
+ * Two modes of Mirotir:
+ *   EXPLORE: "What might happen?"  → forward simulation → discovery
+ *   GOAL:    "How do I get here?"  → backward reasoning → strategy design
+ *
+ * Architecture:
+ *   goal state
+ *       ↓
+ *   infer required levers
+ *       ↓
+ *   generate candidate strategies
+ *       ↓
+ *   swarm tests each strategy
+ *       ↓
+ *   evaluate: which path reaches the goal?
+ *       ↓
+ *   rank paths by success probability
+ *       ↓
+ *   recommend the best path that respects red lines
+ *
+ * This is backcasting / goal-conditioned reasoning — used in military
+ * strategy, corporate planning, policy design, and game AI.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runGoalReasoning = runGoalReasoning;
+const mirofish_1 = require("./mirofish");
+// ============================================
+// LEVER INFERENCE
+// ============================================
+/**
+ * Infer available levers from the scenario and stakeholders
+ * when the user hasn't specified them explicitly.
+ */
+function inferLevers(scenario, stakeholders, goal) {
+    const levers = [];
+    const scenarioLower = scenario.toLowerCase();
+    const goalLower = goal.outcome.toLowerCase();
+    // Energy/economic levers
+    if (scenarioLower.includes("oil") ||
+        scenarioLower.includes("gas") ||
+        scenarioLower.includes("energy") ||
+        scenarioLower.includes("price")) {
+        levers.push("Strategic petroleum reserve release", "Fuel tax adjustment", "Refinery capacity incentives", "Alternative energy subsidies", "Import diversification");
+    }
+    // Geopolitical levers
+    if (scenarioLower.includes("strait") ||
+        scenarioLower.includes("military") ||
+        scenarioLower.includes("war") ||
+        scenarioLower.includes("conflict") ||
+        scenarioLower.includes("sanctions")) {
+        levers.push("Diplomatic engagement", "Coalition building", "Sanctions/trade policy", "Military posture adjustment", "Back-channel communication");
+    }
+    // Regulatory levers
+    if (scenarioLower.includes("regulation") ||
+        scenarioLower.includes("law") ||
+        scenarioLower.includes("compliance") ||
+        scenarioLower.includes("policy")) {
+        levers.push("Lobbying and advocacy", "Compliance framework investment", "Industry coalition formation", "Public comment campaigns", "Alternative regulatory proposals");
+    }
+    // Crisis levers
+    if (scenarioLower.includes("breach") ||
+        scenarioLower.includes("crisis") ||
+        scenarioLower.includes("scandal") ||
+        scenarioLower.includes("reputation")) {
+        levers.push("Transparent disclosure", "Stakeholder communication plan", "Third-party audit/investigation", "Remediation program", "Leadership accountability");
+    }
+    // Market/business levers
+    if (scenarioLower.includes("market") ||
+        scenarioLower.includes("company") ||
+        scenarioLower.includes("business") ||
+        scenarioLower.includes("startup")) {
+        levers.push("Pricing strategy", "Partnership/acquisition", "Market positioning pivot", "Capital allocation", "Talent/team restructuring");
+    }
+    // Generic levers if nothing specific matched
+    if (levers.length === 0) {
+        levers.push("Stakeholder engagement", "Resource reallocation", "Communication strategy", "Policy change", "Coalition building");
+    }
+    return levers;
+}
+// ============================================
+// STRATEGY GENERATION
+// ============================================
+/**
+ * Generate candidate strategies to reach the goal state.
+ *
+ * This is the core of goal-directed reasoning:
+ * Work backward from the desired outcome and identify paths.
+ */
+function generateStrategies(scenario, goal, stakeholders, levers) {
+    const strategies = [];
+    const priority = goal.priority ?? "important";
+    const redLines = goal.red_lines ?? [];
+    // Strategy 1: Direct path (most levers, fastest)
+    strategies.push({
+        id: "strategy_direct",
+        label: "Direct Path",
+        description: `Aggressive, multi-lever approach to reach "${goal.outcome}" as quickly as possible. ` +
+            "Uses the most available levers simultaneously for maximum force.",
+        steps: buildDirectSteps(goal, levers),
+        levers_used: levers.slice(0, 3),
+        success_probability: priority === "critical" ? 0.55 : 0.45,
+        estimated_timeframe: goal.timeframe ?? "30 days",
+        risk: "high",
+        red_line_violations: assessRedLineViolations("direct", redLines, levers.slice(0, 3)),
+        dependencies: [
+            "Multiple levers must be available simultaneously",
+            "Stakeholders must not coordinate opposition",
+            "No secondary crisis emerges during execution",
+        ],
+        failure_modes: [
+            "Aggressive action triggers backlash coalition",
+            "Resource overcommitment leaves no fallback",
+            "Speed creates execution errors",
+        ],
+        likely_allies: stakeholders
+            .filter((s) => s.disposition === "supportive")
+            .map((s) => s.id),
+        likely_opponents: stakeholders
+            .filter((s) => s.disposition === "hostile")
+            .map((s) => s.id),
+    });
+    // Strategy 2: Coalition path (build alliances first)
+    const allies = stakeholders.filter((s) => s.disposition === "supportive" || s.disposition === "neutral");
+    strategies.push({
+        id: "strategy_coalition",
+        label: "Coalition Path",
+        description: `Build a stakeholder coalition first, then apply coordinated pressure toward "${goal.outcome}". ` +
+            "Slower but more sustainable — collective action is harder to resist.",
+        steps: buildCoalitionSteps(goal, levers, allies),
+        levers_used: ["Coalition building", ...levers.slice(0, 2)],
+        success_probability: 0.6,
+        estimated_timeframe: extendTimeframe(goal.timeframe ?? "30 days", 1.5),
+        risk: "moderate",
+        red_line_violations: assessRedLineViolations("coalition", redLines, ["Coalition building", ...levers.slice(0, 2)]),
+        dependencies: [
+            "Key neutral stakeholders are persuadable",
+            "Coalition members maintain alignment throughout execution",
+            "No external shock dissolves the coalition",
+        ],
+        failure_modes: [
+            "Coalition fractures under pressure",
+            "Opponents form counter-coalition faster",
+            "Consensus-building delays miss the window",
+        ],
+        likely_allies: allies.map((s) => s.id),
+        likely_opponents: stakeholders
+            .filter((s) => s.disposition === "hostile")
+            .map((s) => s.id),
+    });
+    // Strategy 3: Incremental path (low risk, slow)
+    strategies.push({
+        id: "strategy_incremental",
+        label: "Incremental Path",
+        description: `Move toward "${goal.outcome}" through small, reversible steps. ` +
+            "Each step is tested before committing further. Preserves optionality.",
+        steps: buildIncrementalSteps(goal, levers),
+        levers_used: levers.slice(0, 2),
+        success_probability: 0.65,
+        estimated_timeframe: extendTimeframe(goal.timeframe ?? "30 days", 2),
+        risk: "low",
+        red_line_violations: [],
+        dependencies: [
+            "Sufficient time to iterate",
+            "Each step produces measurable feedback",
+            "The goal remains viable throughout the process",
+        ],
+        failure_modes: [
+            "Window of opportunity closes before full execution",
+            "Incremental moves are individually too small to create momentum",
+            "Competitors move faster with bolder strategies",
+        ],
+        likely_allies: stakeholders
+            .filter((s) => s.disposition !== "hostile")
+            .map((s) => s.id),
+    });
+    // Strategy 4: Asymmetric path (find the non-obvious lever)
+    if (levers.length >= 3) {
+        strategies.push({
+            id: "strategy_asymmetric",
+            label: "Asymmetric Path",
+            description: `Find the one lever that has outsized impact on achieving "${goal.outcome}". ` +
+                "Instead of pushing many levers, find the fulcrum.",
+            steps: buildAsymmetricSteps(goal, levers),
+            levers_used: [levers[levers.length - 1]],
+            success_probability: 0.35,
+            estimated_timeframe: goal.timeframe ?? "30 days",
+            risk: "moderate",
+            red_line_violations: assessRedLineViolations("asymmetric", redLines, [levers[levers.length - 1]]),
+            dependencies: [
+                "The identified fulcrum lever actually has the projected influence",
+                "Opponents don't anticipate this approach",
+                "No defensive positions are pre-established against this lever",
+            ],
+            failure_modes: [
+                "The fulcrum lever doesn't have the expected effect",
+                "Narrow approach is easily countered once recognized",
+                "Success depends on a single point of leverage that may not hold",
+            ],
+        });
+    }
+    return strategies;
+}
+// ============================================
+// STRATEGY STEP BUILDERS
+// ============================================
+function buildDirectSteps(goal, levers) {
+    const steps = [];
+    const timeframe = goal.timeframe ?? "30 days";
+    steps.push({
+        order: 1,
+        action: "Deploy primary lever immediately",
+        timeframe: "Day 1-3",
+        lever: levers[0] ?? "Primary action",
+        expected_effect: "Establish momentum and signal commitment to the goal",
+        risk: "Early commitment before full information",
+    });
+    if (levers.length >= 2) {
+        steps.push({
+            order: 2,
+            action: "Activate secondary lever to create pressure from a different angle",
+            timeframe: "Day 3-7",
+            lever: levers[1],
+            expected_effect: "Create multi-directional pressure that's harder to resist",
+            risk: "Resource strain from parallel execution",
+        });
+    }
+    if (levers.length >= 3) {
+        steps.push({
+            order: 3,
+            action: "Apply tertiary lever to close remaining gaps",
+            timeframe: "Day 7-14",
+            lever: levers[2],
+            expected_effect: "Address residual resistance and accelerate toward goal",
+            risk: "Overextension if earlier levers haven't produced results",
+        });
+    }
+    steps.push({
+        order: steps.length + 1,
+        action: "Evaluate progress against success criteria and adjust",
+        timeframe: `Day 14-${timeframe}`,
+        lever: "Assessment and adjustment",
+        expected_effect: "Course correction based on actual results vs. projections",
+        risk: "Sunk cost bias may prevent necessary pivots",
+    });
+    return steps;
+}
+function buildCoalitionSteps(goal, levers, allies) {
+    return [
+        {
+            order: 1,
+            action: `Build coalition with ${allies.length > 0 ? allies.map((a) => a.id).slice(0, 3).join(", ") : "key neutral stakeholders"}`,
+            timeframe: "Week 1-2",
+            lever: "Coalition building",
+            expected_effect: "Create collective leverage that exceeds individual power",
+            risk: "Coalition formation takes time; window may narrow",
+        },
+        {
+            order: 2,
+            action: "Align coalition on shared strategy and communication",
+            timeframe: "Week 2-3",
+            lever: "Coordination",
+            expected_effect: "Unified messaging prevents opponents from dividing the coalition",
+            risk: "Internal disagreements may surface during alignment",
+        },
+        {
+            order: 3,
+            action: "Execute coordinated lever deployment",
+            timeframe: "Week 3-4",
+            lever: levers[0] ?? "Primary collective action",
+            expected_effect: `Coalition moves together toward "${goal.outcome}"`,
+            risk: "Weakest coalition member may defect under pressure",
+        },
+        {
+            order: 4,
+            action: "Sustain pressure and consolidate gains",
+            timeframe: "Week 4+",
+            lever: levers[1] ?? "Sustained engagement",
+            expected_effect: "Lock in progress and prevent rollback",
+            risk: "Coalition fatigue and attention drift",
+        },
+    ];
+}
+function buildIncrementalSteps(goal, levers) {
+    return [
+        {
+            order: 1,
+            action: "Take smallest possible step toward the goal to test feasibility",
+            timeframe: "Week 1",
+            lever: levers[0] ?? "Pilot action",
+            expected_effect: "Generate signal about whether this direction works",
+            risk: "Minimal — designed to be reversible",
+        },
+        {
+            order: 2,
+            action: "Evaluate step 1 results against success criteria",
+            timeframe: "Week 2",
+            lever: "Assessment",
+            expected_effect: "Determine if the approach is viable before scaling",
+            risk: "May not be enough data for confident evaluation",
+        },
+        {
+            order: 3,
+            action: "Scale up if step 1 produced positive signal; pivot if not",
+            timeframe: "Week 3-4",
+            lever: levers[1] ?? levers[0] ?? "Scaled action",
+            expected_effect: "Either accelerate a proven approach or redirect resources",
+            risk: "Competitors may move faster with bolder approaches",
+        },
+        {
+            order: 4,
+            action: "Continue test-and-scale cycle until success criteria met",
+            timeframe: "Ongoing",
+            lever: "Iterative execution",
+            expected_effect: "Converge toward the goal through validated learning",
+            risk: "Window of opportunity may close before iteration completes",
+        },
+    ];
+}
+function buildAsymmetricSteps(goal, levers) {
+    const fulcrum = levers[levers.length - 1];
+    return [
+        {
+            order: 1,
+            action: `Identify the highest-leverage point in the system — test "${fulcrum}"`,
+            timeframe: "Day 1-5",
+            lever: "Analysis and targeting",
+            expected_effect: "Find the single point where minimal force creates maximum effect",
+            risk: "Analysis may identify the wrong fulcrum",
+        },
+        {
+            order: 2,
+            action: `Prepare and execute asymmetric move using ${fulcrum}`,
+            timeframe: "Day 5-10",
+            lever: fulcrum,
+            expected_effect: "Disproportionate impact through a single, well-targeted intervention",
+            risk: "If the fulcrum doesn't hold, there's no backup in progress",
+        },
+        {
+            order: 3,
+            action: "Exploit the opening created by the asymmetric move",
+            timeframe: "Day 10-20",
+            lever: "Exploitation of advantage",
+            expected_effect: "Convert initial disruption into sustained progress toward goal",
+            risk: "Opponents may adapt quickly once they understand the approach",
+        },
+    ];
+}
+// ============================================
+// RED LINE ASSESSMENT
+// ============================================
+function assessRedLineViolations(strategyType, redLines, leversUsed) {
+    const violations = [];
+    for (const redLine of redLines) {
+        const rl = redLine.toLowerCase();
+        for (const lever of leversUsed) {
+            const lv = lever.toLowerCase();
+            // Check for obvious conflicts
+            if ((rl.includes("military") && lv.includes("military")) ||
+                (rl.includes("tax") && lv.includes("tax")) ||
+                (rl.includes("force") && lv.includes("force")) ||
+                (rl.includes("sanctions") && lv.includes("sanction"))) {
+                violations.push(`Strategy "${strategyType}" uses "${lever}" which may conflict with red line: "${redLine}"`);
+            }
+        }
+    }
+    return violations;
+}
+// ============================================
+// TIMEFRAME UTILITIES
+// ============================================
+function extendTimeframe(base, multiplier) {
+    const match = base.match(/(\d+)\s*(day|week|month|year)/i);
+    if (!match)
+        return base;
+    const num = parseInt(match[1]);
+    const unit = match[2].toLowerCase();
+    return `${Math.ceil(num * multiplier)} ${unit}s`;
+}
+// ============================================
+// SWARM STRATEGY TESTING
+// ============================================
+/**
+ * Test a strategy against the swarm simulation.
+ * Runs the simulation with the strategy as context and
+ * evaluates whether the goal is reached.
+ */
+async function testStrategyAgainstSwarm(strategy, scenario, goal, stakeholders, swarmConfig) {
+    // Build a modified scenario that includes the strategy being attempted
+    const strategyScenario = `${scenario} [Strategy being tested: ${strategy.label} — ${strategy.description}]`;
+    // Create reasoning paths from strategy for swarm consumption
+    const strategyPath = {
+        id: strategy.id,
+        label: strategy.label,
+        description: strategy.description,
+        projected_outcome: `Goal: ${goal.outcome}`,
+        probability: strategy.success_probability,
+        risk: strategy.risk,
+        tradeoffs: strategy.failure_modes.map((f) => f),
+        benefits_stakeholders: strategy.likely_allies,
+        harms_stakeholders: strategy.likely_opponents,
+    };
+    // Run the simulation
+    const unified = await (0, mirofish_1.runUnifiedSimulation)(strategyScenario, stakeholders, [strategyPath], swarmConfig);
+    const result = unified.result;
+    // Evaluate goal proximity from swarm results
+    const avgImpact = result.rounds.length > 0
+        ? result.rounds[result.rounds.length - 1].reactions.reduce((s, r) => s + r.impact, 0) / result.rounds[result.rounds.length - 1].reactions.length
+        : 0;
+    // Positive average impact = moving toward goal
+    const goalProximity = Math.max(0, Math.min(1, (avgImpact + 1) / 2));
+    const goalReached = goalProximity > 0.7;
+    // Check for red line crossings
+    const redLinesCrossed = [];
+    for (const violation of strategy.red_line_violations) {
+        redLinesCrossed.push(violation);
+    }
+    // Detect unintended consequences from emergent dynamics
+    const unintendedConsequences = [];
+    for (const round of result.rounds) {
+        if (round.emergent_dynamics) {
+            for (const dynamic of round.emergent_dynamics) {
+                if (dynamic.toLowerCase().includes("opposition") ||
+                    dynamic.toLowerCase().includes("polariz") ||
+                    dynamic.toLowerCase().includes("coalition risk")) {
+                    unintendedConsequences.push(dynamic);
+                }
+            }
+        }
+    }
+    // Get final round reactions
+    const finalReactions = result.rounds.length > 0
+        ? result.rounds[result.rounds.length - 1].reactions
+        : [];
+    return {
+        strategy_id: strategy.id,
+        goal_reached: goalReached,
+        goal_proximity: Number(goalProximity.toFixed(2)),
+        steps_to_goal: goalReached
+            ? result.rounds.length
+            : "not_reached",
+        stakeholder_reactions: finalReactions,
+        unintended_consequences: unintendedConsequences,
+        red_lines_crossed: redLinesCrossed,
+    };
+}
+// ============================================
+// MAIN GOAL ENGINE
+// ============================================
+/**
+ * Run goal-directed reasoning.
+ *
+ * "How do I get here?"
+ *
+ * 1. Infer or use provided levers
+ * 2. Generate candidate strategies
+ * 3. Test each strategy against the swarm
+ * 4. Rank by success probability respecting red lines
+ * 5. Recommend the best path
+ */
+async function runGoalReasoning(request, stakeholders) {
+    const goal = request.goal;
+    // 1. Determine available levers
+    const levers = goal.available_levers && goal.available_levers.length > 0
+        ? goal.available_levers
+        : inferLevers(request.scenario, stakeholders, goal);
+    // 2. Generate candidate strategies
+    const strategies = generateStrategies(request.scenario, goal, stakeholders, levers);
+    // 3. Test each strategy against the swarm (if swarm is enabled)
+    let swarmTests = [];
+    if (request.swarm?.enabled && stakeholders.length > 0) {
+        const testPromises = strategies.map((strategy) => testStrategyAgainstSwarm(strategy, request.scenario, goal, stakeholders, request.swarm));
+        swarmTests = await Promise.all(testPromises);
+    }
+    else {
+        // Generate synthetic test results without swarm
+        swarmTests = strategies.map((strategy) => ({
+            strategy_id: strategy.id,
+            goal_reached: strategy.success_probability > 0.5,
+            goal_proximity: strategy.success_probability,
+            steps_to_goal: strategy.success_probability > 0.5
+                ? Math.ceil(3 / strategy.success_probability)
+                : "not_reached",
+            stakeholder_reactions: [],
+            unintended_consequences: strategy.risk === "high"
+                ? ["High-risk strategies may trigger unforeseen opposition"]
+                : [],
+            red_lines_crossed: strategy.red_line_violations,
+        }));
+    }
+    // 4. Rank strategies — highest success probability that respects red lines
+    const rankedStrategies = [...strategies].sort((a, b) => {
+        const aTest = swarmTests.find((t) => t.strategy_id === a.id);
+        const bTest = swarmTests.find((t) => t.strategy_id === b.id);
+        // Penalize red line violations
+        const aViolations = aTest?.red_lines_crossed.length ?? 0;
+        const bViolations = bTest?.red_lines_crossed.length ?? 0;
+        if (aViolations > 0 && bViolations === 0)
+            return 1;
+        if (bViolations > 0 && aViolations === 0)
+            return -1;
+        // Then sort by goal proximity
+        const aProximity = aTest?.goal_proximity ?? a.success_probability;
+        const bProximity = bTest?.goal_proximity ?? b.success_probability;
+        return bProximity - aProximity;
+    });
+    const recommended = rankedStrategies[0];
+    const recommendedTest = swarmTests.find((t) => t.strategy_id === recommended.id);
+    // 5. Build rationale
+    const rationale = buildRecommendationRationale(recommended, recommendedTest, goal, rankedStrategies);
+    // 6. Identify rejected strategies
+    const rejected = rankedStrategies.slice(1).map((s) => {
+        const test = swarmTests.find((t) => t.strategy_id === s.id);
+        let reason;
+        if ((test?.red_lines_crossed.length ?? 0) > 0) {
+            reason = `Violates red line: ${test.red_lines_crossed[0]}`;
+        }
+        else if ((test?.goal_proximity ?? 0) < 0.3) {
+            reason = `Low goal proximity (${((test?.goal_proximity ?? 0) * 100).toFixed(0)}%)`;
+        }
+        else {
+            reason = `Lower overall success probability than recommended path`;
+        }
+        return { label: s.label, reason };
+    });
+    return {
+        goal,
+        strategies: rankedStrategies,
+        swarm_tests: swarmTests,
+        recommended_strategy_id: recommended.id,
+        recommendation_rationale: rationale,
+        immediate_next_step: recommended.steps[0]?.action ?? "Begin assessment",
+        rejected_strategies: rejected,
+    };
+}
+function buildRecommendationRationale(strategy, test, goal, allStrategies) {
+    const parts = [];
+    parts.push(`"${strategy.label}" is recommended because it offers the best risk-adjusted path toward "${goal.outcome}".`);
+    if (test?.goal_reached) {
+        parts.push(`Swarm simulation shows this strategy reaching the goal with ${(test.goal_proximity * 100).toFixed(0)}% proximity.`);
+    }
+    else if (test) {
+        parts.push(`Swarm simulation shows ${(test.goal_proximity * 100).toFixed(0)}% proximity to the goal — partial success is likely.`);
+    }
+    if (strategy.red_line_violations.length === 0) {
+        parts.push("This strategy respects all stated red lines.");
+    }
+    const alternativeCount = allStrategies.length - 1;
+    parts.push(`${alternativeCount} alternative ${alternativeCount === 1 ? "strategy was" : "strategies were"} evaluated and ranked lower.`);
+    return parts.join(" ");
+}