@neuroverseos/nv-sim 0.1.2 → 0.1.6

package/dist/engine/policyEngine.js

@@ -0,0 +1,799 @@
+"use strict";
+/**
+ * Policy Enforcement Engine
+ *
+ * The full pipeline: Upload → Parse → Validate → Simulate → Compare
+ *
+ * "Drop in your policy. We'll show you what happens.
+ *  Before it actually happens."
+ *
+ * This engine doesn't just parse policy text — it pressure-tests it.
+ * It detects conflicts, weak rules, over-constrained systems,
+ * and shows you baseline vs. policy outcomes with real metrics.
+ *
+ * Diagnostic model inspired by VS Code / GitHub:
+ *   - Errors (red): Conflicts, structural issues that block simulation
+ *   - Warnings (yellow): Overlapping rules, potential issues
+ *   - Info (blue): Advisory-only rules, suggestions
+ *   - Hints (gray): Optimization opportunities
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRulesFromText = parseRulesFromText;
+exports.validatePolicy = validatePolicy;
+exports.applyQuickFix = applyQuickFix;
+exports.policyToWorld = policyToWorld;
+exports.runPolicyPipeline = runPolicyPipeline;
+const governedSimulation_1 = require("./governedSimulation");
+// ============================================
+// RULE PARSING ENGINE
+// ============================================
+/** Intent patterns for classifying rules */
+const INTENT_PATTERNS = [
+    {
+        category: "prohibit",
+        patterns: [
+            /\b(block|prohibit|forbid|prevent|disallow|ban|never|must\s+not|shall\s+not|cannot)\b/i,
+        ],
+        enforcement: "structural",
+    },
+    {
+        category: "limit",
+        patterns: [
+            /\b(limit|cap|restrict|maximum|max|ceiling|no\s+more\s+than|not\s+exceed|threshold)\b/i,
+        ],
+        enforcement: "structural",
+    },
+    {
+        category: "require",
+        patterns: [
+            /\b(require|mandate|must|shall|obligat|enforce|compulsory|necessary)\b/i,
+        ],
+        enforcement: "structural",
+    },
+    {
+        category: "circuit_breaker",
+        patterns: [
+            /\b(circuit\s*breaker|halt|pause|freeze|stop|suspend|emergency|shutdown)\b/i,
+        ],
+        enforcement: "structural",
+    },
+    {
+        category: "monitor",
+        patterns: [
+            /\b(monitor|track|report|audit|log|observe|surveil|watch|alert)\b/i,
+        ],
+        enforcement: "structural",
+    },
+    {
+        category: "encourage",
+        patterns: [
+            /\b(encourage|promote|suggest|recommend|prefer|advise|should|guideline|best\s+practice)\b/i,
+        ],
+        enforcement: "advisory",
+    },
+];
+/** Keywords for variable detection */
+const VARIABLE_KEYWORDS = {
+    liquidity: ["liquidity", "liquid", "cash", "capital", "reserve"],
+    leverage: ["leverage", "leveraged", "margin", "borrowed", "debt"],
+    volatility: ["volatility", "volatile", "vix", "fluctuation", "swing", "spike"],
+    contagion: ["contagion", "spread", "cascade", "chain", "domino", "systemic"],
+    trade: ["trade", "trading", "transaction", "order", "position", "buy", "sell"],
+    price: ["price", "cost", "valuation", "rate", "tariff"],
+    risk: ["risk", "exposure", "hazard", "danger", "threat"],
+    stability: ["stability", "stable", "equilibrium", "balance"],
+    intervention: ["intervention", "intervene", "central bank", "regulator", "authority"],
+    panic: ["panic", "fear", "sentiment", "confidence", "trust"],
+};
+/**
+ * Parse raw policy text into structured rules.
+ *
+ * Handles .txt and .md formats.
+ * Each line or bullet point is treated as a potential rule.
+ */
+function parseRulesFromText(text) {
+    const lines = text.split("\n").filter((l) => l.trim().length > 0);
+    const rules = [];
+    let ruleIndex = 0;
+    for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
+        const raw = lines[lineIdx].trim();
+        // Skip headers, comments, empty lines
+        if (raw.startsWith("#") && raw.length < 80 && !raw.includes("must") && !raw.includes("shall"))
+            continue;
+        if (raw.startsWith("//") || raw.startsWith("<!--"))
+            continue;
+        if (raw.length < 10)
+            continue;
+        // Strip markdown bullets and numbering
+        const cleaned = raw
+            .replace(/^[-*+]\s+/, "")
+            .replace(/^\d+[.)]\s+/, "")
+            .replace(/^>\s+/, "")
+            .replace(/\*\*/g, "")
+            .replace(/\*/g, "")
+            .trim();
+        if (cleaned.length < 10)
+            continue;
+        // Classify intent
+        let matchedCategory = "encourage";
+        let matchedEnforcement = "advisory";
+        let bestConfidence = 0.3;
+        for (const pattern of INTENT_PATTERNS) {
+            for (const regex of pattern.patterns) {
+                if (regex.test(cleaned)) {
+                    matchedCategory = pattern.category;
+                    matchedEnforcement = pattern.enforcement;
+                    bestConfidence = Math.max(bestConfidence, 0.7 + Math.random() * 0.25);
+                    break;
+                }
+            }
+            if (bestConfidence > 0.7)
+                break;
+        }
+        // Detect affected variables
+        const affectedVars = [];
+        const keywords = [];
+        const cleanedLower = cleaned.toLowerCase();
+        for (const [varName, kws] of Object.entries(VARIABLE_KEYWORDS)) {
+            for (const kw of kws) {
+                if (cleanedLower.includes(kw)) {
+                    if (!affectedVars.includes(varName))
+                        affectedVars.push(varName);
+                    if (!keywords.includes(kw))
+                        keywords.push(kw);
+                }
+            }
+        }
+        ruleIndex++;
+        rules.push({
+            id: `RULE-${String(ruleIndex).padStart(3, "0")}`,
+            originalText: raw,
+            description: cleaned,
+            enforcement: matchedEnforcement,
+            category: matchedCategory,
+            confidence: Number(bestConfidence.toFixed(2)),
+            affectedVariables: affectedVars,
+            keywords,
+            sourceLine: lineIdx + 1,
+        });
+    }
+    return {
+        rules,
+        summary: {
+            total: rules.length,
+            enforced: rules.filter((r) => r.enforcement === "structural").length,
+            advisory: rules.filter((r) => r.enforcement === "advisory").length,
+        },
+        sourceText: text,
+    };
+}
+/**
+ * Detect conflicts and overlaps between parsed rules.
+ */
+function detectConflicts(rules) {
+    const conflicts = [];
+    for (let i = 0; i < rules.length; i++) {
+        for (let j = i + 1; j < rules.length; j++) {
+            const a = rules[i];
+            const b = rules[j];
+            // Check for shared variables
+            const sharedVars = a.affectedVariables.filter((v) => b.affectedVariables.includes(v));
+            if (sharedVars.length === 0)
+                continue;
+            // Direct conflict: one blocks, other allows the same thing
+            if ((a.category === "prohibit" && (b.category === "encourage" || b.category === "require")) ||
+                (b.category === "prohibit" && (a.category === "encourage" || a.category === "require"))) {
+                conflicts.push({
+                    ruleA: a,
+                    ruleB: b,
+                    type: "direct_conflict",
+                    description: `${a.id} ${a.category}s ${sharedVars.join(", ")} while ${b.id} ${b.category}s it`,
+                });
+                continue;
+            }
+            // Overlap: both rules constrain the same variable in different ways
+            if (a.category === b.category &&
+                sharedVars.length > 0 &&
+                a.description !== b.description) {
+                conflicts.push({
+                    ruleA: a,
+                    ruleB: b,
+                    type: "overlap",
+                    description: `Both ${a.id} and ${b.id} ${a.category} on "${sharedVars.join(", ")}" — may cause redundancy or conflict`,
+                });
+                continue;
+            }
+            // Subsumption: one rule is broader than the other
+            if (a.affectedVariables.length > b.affectedVariables.length &&
+                b.affectedVariables.every((v) => a.affectedVariables.includes(v))) {
+                conflicts.push({
+                    ruleA: a,
+                    ruleB: b,
+                    type: "subsumption",
+                    description: `${a.id} may already cover what ${b.id} specifies — ${b.id} may be redundant`,
+                });
+            }
+        }
+    }
+    return conflicts;
+}
+// ============================================
+// POLICY VALIDATION (HEALTH CHECK)
+// ============================================
+/**
+ * Run a full policy health check.
+ *
+ * Produces VS Code/GitHub-style diagnostics:
+ *   - Errors: Conflicts that block simulation
+ *   - Warnings: Overlaps, weak enforcement
+ *   - Info: Advisory rules, suggestions
+ *   - Hints: Optimization opportunities
+ */
+function validatePolicy(parsed) {
+    const diagnostics = [];
+    let diagIndex = 0;
+    const nextId = () => `POL-${String(++diagIndex).padStart(3, "0")}`;
+    // --- Conflict detection ---
+    const conflicts = detectConflicts(parsed.rules);
+    for (const conflict of conflicts) {
+        if (conflict.type === "direct_conflict") {
+            // Build merged replacement: keep the more specific rule, add condition
+            const sharedVars = conflict.ruleA.affectedVariables.filter((v) => conflict.ruleB.affectedVariables.includes(v));
+            const mergedText = `Limit ${sharedVars.join(" and ")} during volatility spikes with strict thresholds`;
+            diagnostics.push({
+                id: nextId(),
+                severity: "error",
+                message: `Conflicting rules: ${conflict.ruleA.id} vs ${conflict.ruleB.id}`,
+                detail: conflict.description,
+                relatedRules: [conflict.ruleA.id, conflict.ruleB.id],
+                fix: `Resolve conflict: remove one rule, or add a condition (e.g., "${conflict.ruleB.id} applies only during volatility")`,
+                source: {
+                    startLine: conflict.ruleA.sourceLine,
+                    endLine: conflict.ruleB.sourceLine,
+                },
+                category: "conflict",
+                quickFix: {
+                    label: "Merge into single rule",
+                    operation: "replace",
+                    text: mergedText,
+                    targetLines: [conflict.ruleA.sourceLine, conflict.ruleB.sourceLine],
+                },
+            });
+        }
+        else if (conflict.type === "overlap") {
+            const sharedVars = conflict.ruleA.affectedVariables.filter((v) => conflict.ruleB.affectedVariables.includes(v));
+            const mergedText = `Limit ${sharedVars.join(" and ")} with unified thresholds across all conditions`;
+            diagnostics.push({
+                id: nextId(),
+                severity: "warning",
+                message: `Overlapping enforcement: ${conflict.ruleA.id} and ${conflict.ruleB.id}`,
+                detail: conflict.description,
+                relatedRules: [conflict.ruleA.id, conflict.ruleB.id],
+                fix: "Consider merging into a single rule or adding distinct conditions",
+                source: {
+                    startLine: conflict.ruleA.sourceLine,
+                    endLine: conflict.ruleB.sourceLine,
+                },
+                category: "conflict",
+                quickFix: {
+                    label: "Merge rules",
+                    operation: "replace",
+                    text: mergedText,
+                    targetLines: [conflict.ruleA.sourceLine, conflict.ruleB.sourceLine],
+                },
+            });
+        }
+        else {
+            diagnostics.push({
+                id: nextId(),
+                severity: "hint",
+                message: `${conflict.ruleB.id} may be redundant (subsumed by ${conflict.ruleA.id})`,
+                detail: conflict.description,
+                relatedRules: [conflict.ruleA.id, conflict.ruleB.id],
+                category: "structure",
+                quickFix: {
+                    label: "Remove redundant rule",
+                    operation: "remove",
+                    text: "",
+                    targetLines: [conflict.ruleB.sourceLine],
+                },
+            });
+        }
+    }
+    // --- Weak policy detection ---
+    if (parsed.summary.enforced === 0 && parsed.rules.length > 0) {
+        // Build strengthened versions of the first few advisory rules
+        const strengthened = parsed.rules.slice(0, 3).map((r) => {
+            const desc = r.description.toLowerCase();
+            if (desc.includes("encourage") || desc.includes("promote"))
+                return r.description.replace(/\b(encourage|promote)\b/i, "Require");
+            if (desc.includes("should"))
+                return r.description.replace(/\bshould\b/i, "Must");
+            return `Limit ${r.affectedVariables[0] ?? "system behavior"} to prevent instability`;
+        });
+        diagnostics.push({
+            id: nextId(),
+            severity: "error",
+            message: "Advisory only — no enforceable constraints detected",
+            detail: "This policy contains only advisory guidelines with no structural enforcement. " +
+                "The simulation will run but the policy will have no measurable effect on outcomes.",
+            relatedRules: parsed.rules.map((r) => r.id),
+            fix: 'Add enforceable rules using action verbs: "must", "shall", "limit", "block", "require"',
+            category: "strength",
+            quickFix: {
+                label: "Strengthen enforcement",
+                operation: "insert",
+                text: strengthened.join("\n"),
+            },
+        });
+    }
+    else if (parsed.summary.enforced < parsed.summary.total * 0.3 && parsed.rules.length > 2) {
+        // Upgrade the first advisory rule as an example
+        const firstAdvisory = parsed.rules.find((r) => r.enforcement === "advisory");
+        const upgraded = firstAdvisory
+            ? firstAdvisory.description.replace(/\b(encourage|promote|suggest|recommend|should)\b/i, "Require")
+            : "Require compliance with all governance constraints";
+        diagnostics.push({
+            id: nextId(),
+            severity: "warning",
+            message: `Weak enforcement: only ${parsed.summary.enforced}/${parsed.summary.total} rules are enforceable`,
+            detail: "Most rules in this policy are advisory. Simulations may show limited governance effect.",
+            relatedRules: parsed.rules.filter((r) => r.enforcement === "advisory").map((r) => r.id),
+            fix: "Strengthen advisory rules with specific thresholds and action verbs",
+            category: "strength",
+            quickFix: firstAdvisory ? {
+                label: "Strengthen weakest rule",
+                operation: "replace",
+                text: upgraded,
+                targetLines: [firstAdvisory.sourceLine],
+            } : {
+                label: "Add enforced rule",
+                operation: "insert",
+                text: upgraded,
+            },
+        });
+    }
+    // --- Over-constrained detection ---
+    const prohibitCount = parsed.rules.filter((r) => r.category === "prohibit").length;
+    const limitCount = parsed.rules.filter((r) => r.category === "limit").length;
+    const restrictiveRatio = (prohibitCount + limitCount) / Math.max(parsed.rules.length, 1);
+    if (restrictiveRatio > 0.8 && parsed.rules.length > 3) {
+        diagnostics.push({
+            id: nextId(),
+            severity: "warning",
+            message: "Policy may over-restrict system behavior",
+            detail: `${Math.round(restrictiveRatio * 100)}% of rules are prohibitive/restrictive. ` +
+                "This may cause system freeze where most actions are blocked, reducing the system's ability to respond to crises.",
+            relatedRules: parsed.rules
+                .filter((r) => r.category === "prohibit" || r.category === "limit")
+                .map((r) => r.id),
+            fix: "Balance restrictive rules with permissive ones: add monitoring, encourage, or conditional allowance rules",
+            category: "constraint",
+            quickFix: {
+                label: "Add flexibility rules",
+                operation: "insert",
+                text: "Allow normal trading activity under standard market conditions\nMonitor and report unusual activity patterns before restricting",
+            },
+        });
+    }
+    // --- Coverage analysis ---
+    const coveredVariables = new Set(parsed.rules.flatMap((r) => r.affectedVariables));
+    const criticalVariables = ["liquidity", "leverage", "volatility", "risk", "stability"];
+    const uncovered = criticalVariables.filter((v) => !coveredVariables.has(v));
+    if (uncovered.length > 0 && parsed.rules.length > 0) {
+        // Generate a rule for each uncovered variable
+        const coverageRules = uncovered.map((v) => {
+            switch (v) {
+                case "liquidity": return "Maintain minimum liquidity floor — no agent may drain liquidity below 15% of baseline";
+                case "leverage": return "Limit maximum leverage to 5x during elevated volatility conditions";
+                case "volatility": return "Halt automated trading when volatility index exceeds critical threshold";
+                case "risk": return "Require risk assessment reporting for all positions exceeding normal thresholds";
+                case "stability": return "Require rebalancing when system stability drops below acceptable levels";
+                default: return `Monitor and limit ${v} to prevent systemic issues`;
+            }
+        });
+        diagnostics.push({
+            id: nextId(),
+            severity: "info",
+            message: `Uncovered critical areas: ${uncovered.join(", ")}`,
+            detail: `The policy does not address: ${uncovered.join(", ")}. ` +
+                "These are common governance targets in financial/systemic scenarios.",
+            relatedRules: [],
+            fix: `Consider adding rules for: ${uncovered.map((v) => v.charAt(0).toUpperCase() + v.slice(1)).join(", ")}`,
+            category: "coverage",
+            quickFix: {
+                label: `Add ${uncovered.length} coverage rule${uncovered.length > 1 ? "s" : ""}`,
+                operation: "insert",
+                text: coverageRules.join("\n"),
+            },
+        });
+    }
+    // --- Low confidence rules ---
+    const lowConfRules = parsed.rules.filter((r) => r.confidence < 0.5);
+    if (lowConfRules.length > 0) {
+        // Rephrase the first low-confidence rule
+        const first = lowConfRules[0];
+        const rephrased = `Require ${first.affectedVariables[0] ?? "compliance"} controls to prevent ${first.keywords[0] ?? "violations"}`;
+        diagnostics.push({
+            id: nextId(),
+            severity: "hint",
+            message: `${lowConfRules.length} rule(s) parsed with low confidence`,
+            detail: "Some lines were difficult to classify. They may be descriptions rather than actionable rules.",
+            relatedRules: lowConfRules.map((r) => r.id),
+            fix: "Rephrase ambiguous rules with clear action verbs and specific thresholds",
+            category: "structure",
+            quickFix: {
+                label: "Rephrase ambiguous rule",
+                operation: "replace",
+                text: rephrased,
+                targetLines: [first.sourceLine],
+            },
+        });
+    }
+    // --- No rules at all ---
+    if (parsed.rules.length === 0) {
+        diagnostics.push({
+            id: nextId(),
+            severity: "error",
+            message: "No rules detected in policy document",
+            detail: "The uploaded document did not contain any recognizable policy rules.",
+            relatedRules: [],
+            fix: "Add policy rules as bullet points or numbered items with clear action verbs",
+            category: "structure",
+            quickFix: {
+                label: "Add starter policy",
+                operation: "insert",
+                text: "Block all large trades during extreme volatility\nLimit maximum leverage to 5x\nHalt automated trading when volatility exceeds critical threshold\nMaintain minimum liquidity floor at 15% of baseline\nMonitor and report all correlated position clusters",
+            },
+        });
+    }
+    // --- Circuit breaker check ---
+    const hasCircuitBreaker = parsed.rules.some((r) => r.category === "circuit_breaker");
+    if (!hasCircuitBreaker && parsed.rules.length > 2) {
+        diagnostics.push({
+            id: nextId(),
+            severity: "info",
+            message: "No circuit breaker / emergency halt rule detected",
+            detail: "The policy has no emergency shutdown mechanism. In extreme scenarios, the system has no last-resort protection.",
+            relatedRules: [],
+            fix: 'Add an emergency rule: "Halt all trading when volatility exceeds critical threshold"',
+            category: "coverage",
+            quickFix: {
+                label: "Add circuit breaker",
+                operation: "insert",
+                text: "Halt all trading when volatility exceeds critical threshold",
+            },
+        });
+    }
+    // Compute summary
+    const counts = {
+        errors: diagnostics.filter((d) => d.severity === "error").length,
+        warnings: diagnostics.filter((d) => d.severity === "warning").length,
+        info: diagnostics.filter((d) => d.severity === "info").length,
+        hints: diagnostics.filter((d) => d.severity === "hint").length,
+    };
+    const hasBlockingErrors = counts.errors > 0 && parsed.rules.length === 0;
+    const healthScore = Math.max(0, 100 - counts.errors * 25 - counts.warnings * 10 - counts.info * 3 - counts.hints * 1);
+    let status;
+    if (counts.errors > 0 && hasBlockingErrors)
+        status = "critical";
+    else if (counts.errors > 0)
+        status = "errors";
+    else if (counts.warnings > 0)
+        status = "warnings";
+    else
+        status = "healthy";
+    return {
+        status,
+        diagnostics,
+        counts,
+        canSimulate: parsed.rules.length > 0,
+        healthScore,
+    };
+}
+// ============================================
+// QUICK FIX APPLICATION
+// ============================================
+/**
+ * Apply a quick fix action to the policy text.
+ * Returns the new text after the fix is applied.
+ */
+function applyQuickFix(policyText, fix) {
+    const lines = policyText.split("\n");
+    switch (fix.operation) {
+        case "insert":
+            // Append new lines at the end
+            return policyText.trimEnd() + "\n" + fix.text;
+        case "replace": {
+            if (!fix.targetLines || fix.targetLines.length === 0)
+                return policyText;
+            // Replace the first target line with the new text, remove the rest
+            const sortedTargets = [...fix.targetLines].sort((a, b) => a - b);
+            const result = [];
+            let replaced = false;
+            for (let i = 0; i < lines.length; i++) {
+                const lineNum = i + 1;
+                if (sortedTargets.includes(lineNum)) {
+                    if (!replaced) {
+                        // Replace the first occurrence with the fix text
+                        result.push(fix.text);
+                        replaced = true;
+                    }
+                    // Skip subsequent target lines (they're merged into one)
+                }
+                else {
+                    result.push(lines[i]);
+                }
+            }
+            return result.join("\n");
+        }
+        case "remove": {
+            if (!fix.targetLines || fix.targetLines.length === 0)
+                return policyText;
+            return lines
+                .filter((_, i) => !fix.targetLines.includes(i + 1))
+                .join("\n");
+        }
+        default:
+            return policyText;
+    }
+}
+// ============================================
+// POLICY → WORLD CONVERSION
+// ============================================
+/**
+ * Convert parsed policy rules into a WorldDefinitionLite for simulation.
+ */
+function policyToWorld(parsed) {
+    const invariants = parsed.rules.map((rule) => ({
+        id: rule.id.replace("RULE", "INV"),
+        description: rule.description,
+        enforceable: rule.enforcement === "structural",
+    }));
+    const gates = [];
+    // Generate gates from circuit breakers and prohibitions
+    for (const rule of parsed.rules) {
+        if (rule.category === "circuit_breaker") {
+            gates.push({
+                id: `GATE-${rule.id}`,
+                label: `Circuit Breaker: ${rule.description.slice(0, 60)}`,
+                condition: buildGateCondition(rule),
+                severity: "critical",
+            });
+        }
+        else if (rule.category === "prohibit") {
+            gates.push({
+                id: `GATE-${rule.id}`,
+                label: `Block: ${rule.description.slice(0, 60)}`,
+                condition: buildGateCondition(rule),
+                severity: "critical",
+            });
+        }
+        else if (rule.category === "limit") {
+            gates.push({
+                id: `GATE-${rule.id}`,
+                label: `Limit: ${rule.description.slice(0, 60)}`,
+                condition: buildGateCondition(rule),
+                severity: "warning",
+            });
+        }
+    }
+    // Infer thesis from the policy
+    const enforced = parsed.rules.filter((r) => r.enforcement === "structural");
+    const thesis = enforced.length > 0
+        ? `Policy enforces ${enforced.length} structural constraints covering ${[...new Set(enforced.flatMap((r) => r.affectedVariables))].join(", ") || "system behavior"}`
+        : "Advisory policy providing guidelines without structural enforcement";
+    // Build state variables from affected variables
+    const allVars = [...new Set(parsed.rules.flatMap((r) => r.affectedVariables))];
+    const stateVars = allVars.map((varName) => ({
+        id: `${varName}_index`,
+        label: varName.charAt(0).toUpperCase() + varName.slice(1).replace(/_/g, " ") + " Index",
+        type: "number",
+        range: { min: 0, max: 100 },
+        default_value: 50,
+    }));
+    return {
+        thesis,
+        state_variables: stateVars,
+        invariants,
+        gates,
+    };
+}
+function buildGateCondition(rule) {
+    const vars = rule.affectedVariables;
+    if (vars.length === 0)
+        return "system_stress > 80";
+    return vars
+        .map((v) => {
+        if (v === "volatility")
+            return "volatility_index > 80";
+        if (v === "liquidity")
+            return "liquidity_index < 15";
+        if (v === "leverage")
+            return "leverage_ratio > 8";
+        if (v === "risk")
+            return "risk_index > 75";
+        if (v === "contagion")
+            return "contagion_spread == systemic";
+        return `${v}_index > 80`;
+    })
+        .join(" || ");
+}
+// ============================================
+// FULL PIPELINE: Upload → Parse → Validate → Simulate → Compare
+// ============================================
+/**
+ * Build default stakeholders for policy simulation.
+ */
+function buildDefaultStakeholders() {
+    return [
+        { id: "Policy Enforcer", disposition: "supportive", priorities: ["compliance", "stability", "risk reduction"] },
+        { id: "Market Participants", disposition: "neutral", priorities: ["profit", "liquidity", "freedom"] },
+        { id: "Regulators", disposition: "supportive", priorities: ["systemic stability", "transparency", "enforcement"] },
+        { id: "Risk Managers", disposition: "neutral", priorities: ["exposure limits", "portfolio protection", "hedging"] },
+    ];
+}
+/**
+ * Build default reasoning paths for policy simulation.
+ */
+function buildDefaultPaths() {
+    return [
+        {
+            id: "path_compliant",
+            label: "Full Compliance",
+            description: "All actors comply with policy rules — system operates within constraints",
+            projected_outcome: "Reduced volatility, slower but stable growth, fewer extreme events",
+            probability: 0.55,
+            risk: "low",
+            tradeoffs: ["Stability vs. opportunity cost", "Compliance cost vs. systemic safety"],
+            benefits_stakeholders: ["Regulators", "Risk Managers"],
+            harms_stakeholders: [],
+        },
+        {
+            id: "path_stress_test",
+            label: "Stress Test",
+            description: "External shock tests policy resilience — cascade events trigger policy rules",
+            projected_outcome: "Policy constraints activate, dampening cascade but limiting response flexibility",
+            probability: 0.65,
+            risk: "high",
+            tradeoffs: ["Protection vs. agility", "Circuit breakers vs. market freeze"],
+            benefits_stakeholders: ["Policy Enforcer"],
+            harms_stakeholders: ["Market Participants"],
+        },
+        {
+            id: "path_evasion",
+            label: "Policy Evasion",
+            description: "Some actors find loopholes or work around constraints",
+            projected_outcome: "Partial effectiveness — compliant actors stabilized, non-compliant create new risks",
+            probability: 0.45,
+            risk: "moderate",
+            tradeoffs: ["Enforcement strictness vs. innovation", "Monitoring cost vs. coverage"],
+            benefits_stakeholders: [],
+            harms_stakeholders: ["Policy Enforcer", "Regulators"],
+        },
+    ];
+}
+/**
+ * Run the complete policy enforcement pipeline.
+ *
+ * 1. Parse policy text into rules
+ * 2. Validate logic (conflicts, coverage, strength)
+ * 3. Convert to world definition
+ * 4. Run baseline vs. policy simulation
+ * 5. Generate impact report with explanation
+ *
+ * Returns everything needed for the UI in one call.
+ */
+async function runPolicyPipeline(policyText, options = {}) {
+    // Step 1: Parse
+    const parsed = parseRulesFromText(policyText);
+    // Step 2: Validate
+    const healthCheck = validatePolicy(parsed);
+    // Step 3: Convert to world
+    const worldLite = policyToWorld(parsed);
+    // Step 4: Build scenario request
+    const scenarioText = options.scenarioText ??
+        "A systemic stress event triggers cascading failures across interconnected markets. " +
+            "Volatility spikes, liquidity evaporates, and contagion threatens to spread. " +
+            "The policy framework is the only structural defense.";
+    const stakeholders = (options.stakeholders ?? buildDefaultStakeholders());
+    const paths = buildDefaultPaths();
+    const request = {
+        scenario: scenarioText,
+        stakeholders,
+        assumptions: {
+            severity: "critical",
+            environmental_hostility: "high",
+            time_pressure: "immediate",
+            regulatory_climate: "strict",
+        },
+        constraints: {
+            time_horizon: "72 hours",
+            risk_tolerance: "conservative",
+        },
+        depth: "full",
+        swarm: {
+            enabled: true,
+            rounds: options.rounds ?? 5,
+            reaction_model: "mixed",
+        },
+    };
+    // Step 5: Run governed comparison
+    const comparison = await (0, governedSimulation_1.runGovernedComparison)(request, worldLite, paths);
+    // Step 6: Compute policy-specific impact
+    const impact = computePolicyImpact(comparison, parsed);
+    // Step 7: Generate explanation
+    const explanation = generatePolicyExplanation(comparison, parsed, impact);
+    return {
+        policy: parsed,
+        healthCheck,
+        comparison,
+        impact,
+        explanation,
+    };
+}
+// ============================================
+// IMPACT COMPUTATION
+// ============================================
+function computePolicyImpact(comparison, parsed) {
+    const baseline = comparison.baseline.metrics;
+    const governed = comparison.governed.metrics;
+    const stats = comparison.governanceStats;
+    const stabilityChange = (governed.stabilityScore - baseline.stabilityScore) * 100;
+    const cascadeRiskChange = (governed.collapseProbability - baseline.collapseProbability) * -100;
+    const totalActions = comparison.governed.swarm.rounds.reduce((sum, r) => sum + r.reactions.length, 0);
+    const actionsBlocked = stats.verdicts.block;
+    const blockedPct = totalActions > 0 ? (actionsBlocked / totalActions) * 100 : 0;
+    // Over-constraint: if >70% actions blocked, policy is too restrictive
+    const overConstraintScore = Math.min(1, blockedPct / 100);
+    return {
+        stabilityChange: Number(stabilityChange.toFixed(1)),
+        cascadeRiskChange: Number(cascadeRiskChange.toFixed(1)),
+        governanceActions: stats.totalEvaluations,
+        actionsBlocked: Number(blockedPct.toFixed(1)),
+        preventedCollapse: baseline.collapseProbability > 0.5 && governed.collapseProbability < 0.3,
+        overConstraintScore: Number(overConstraintScore.toFixed(2)),
+    };
+}
+// ============================================
+// EXPLANATION GENERATION
+// ============================================
+function generatePolicyExplanation(comparison, parsed, impact) {
+    const parts = [];
+    // Opening
+    if (impact.preventedCollapse) {
+        parts.push("The policy prevented system collapse by enforcing structural constraints during the stress test.");
+    }
+    else if (impact.stabilityChange > 5) {
+        parts.push("The policy measurably improved system stability during the simulated stress event.");
+    }
+    else if (impact.stabilityChange < -5) {
+        parts.push("The policy may have reduced system flexibility, leading to lower stability under stress.");
+    }
+    else {
+        parts.push("The policy had a moderate effect on system dynamics during the stress test.");
+    }
+    // Mechanism
+    const circuitBreakers = parsed.rules.filter((r) => r.category === "circuit_breaker");
+    const limits = parsed.rules.filter((r) => r.category === "limit");
+    const prohibitions = parsed.rules.filter((r) => r.category === "prohibit");
+    if (circuitBreakers.length > 0) {
+        parts.push(`Circuit breaker rules (${circuitBreakers.map((r) => r.id).join(", ")}) activated during peak volatility, halting cascading sell-offs.`);
+    }
+    if (limits.length > 0 && impact.cascadeRiskChange > 10) {
+        parts.push(`Limit rules reduced cascade risk by constraining extreme positions and enforcing thresholds.`);
+    }
+    if (prohibitions.length > 0) {
+        parts.push(`Prohibition rules blocked ${impact.actionsBlocked.toFixed(0)}% of actions that violated policy constraints.`);
+    }
+    // Over-constraint warning
+    if (impact.overConstraintScore > 0.7) {
+        parts.push(`WARNING: The policy appears over-constrained — ${impact.actionsBlocked.toFixed(0)}% of actions were blocked, ` +
+            "risking system freeze where legitimate responses are also suppressed.");
+    }
+    // Summary
+    parts.push(`Net effect: ${impact.stabilityChange > 0 ? "+" : ""}${impact.stabilityChange.toFixed(0)}% stability, ` +
+        `${impact.cascadeRiskChange > 0 ? "-" : "+"}${Math.abs(impact.cascadeRiskChange).toFixed(0)}% cascade risk, ` +
+        `${impact.governanceActions} governance actions.`);
+    return parts.join(" ");
+}