@neuroverseos/nv-sim 0.1.2 → 0.1.5

package/dist/engine/policyEnforcement.js

@@ -0,0 +1,1611 @@
+"use strict";
+/**
+ * Policy Enforcement System — The Control Layer
+ *
+ * NeuroVerse is a control layer where users:
+ *   1. Define rules (world files)
+ *   2. Run simulations through it
+ *   3. Change rules between runs
+ *   4. See how those rules change behavior over time
+ *
+ * This is NOT a simulator. This is the governance lab.
+ *
+ * Three pillars:
+ *   CONTROL      — world files, rule definition
+ *   ENFORCEMENT  — interceptAction(), runtime governance
+ *   INSIGHT      — reports, divergence, metrics across iterations
+ *
+ * "Design rules. Run reality. See what changes."
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEnforcementSession = createEnforcementSession;
+exports.formatEnforcementReport = formatEnforcementReport;
+exports.formatGuidedNextSteps = formatGuidedNextSteps;
+exports.suggestExperiments = suggestExperiments;
+exports.governedDetectArchetype = governedDetectArchetype;
+exports.governedSynthesizeStrategy = governedSynthesizeStrategy;
+exports.governedFindSimilar = governedFindSimilar;
+exports.formatPolicyDiagnostics = formatPolicyDiagnostics;
+exports.formatRuleImpactAttribution = formatRuleImpactAttribution;
+exports.detectSystemArchetype = detectSystemArchetype;
+exports.loadExperimentLibrary = loadExperimentLibrary;
+exports.createSavedExperiment = createSavedExperiment;
+exports.formatExperimentLineage = formatExperimentLineage;
+exports.formatSimilarExperiments = formatSimilarExperiments;
+exports.formatBestKnownStrategy = formatBestKnownStrategy;
+exports.formatMultiPatchComparison = formatMultiPatchComparison;
+exports.exportEnforcementReportJSON = exportEnforcementReportJSON;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const governedSimulation_1 = require("./governedSimulation");
+const worldStorage_1 = require("./worldStorage");
+const aiProvider_1 = require("./aiProvider");
+const behavioralAnalysis_1 = require("./behavioralAnalysis");
+/**
+ * Create a new policy enforcement session.
+ *
+ * This is the entry point for the governance lab:
+ *   "Same scenario, different rules, measurable divergence."
+ */
+function createEnforcementSession(scenario, request, paths) {
+    const sessionId = `enforce_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`;
+    const runs = [];
+    function diffRules(prev, next) {
+        const prevIds = new Set(prev.world.invariants.map(i => i.id));
+        const nextIds = new Set(next.world.invariants.map(i => i.id));
+        const prevGateIds = new Set((prev.world.gates ?? []).map(g => g.id));
+        const nextGateIds = new Set((next.world.gates ?? []).map(g => g.id));
+        return {
+            added: next.world.invariants.filter(i => !prevIds.has(i.id)),
+            removed: prev.world.invariants.filter(i => !nextIds.has(i.id)),
+            gatesAdded: (next.world.gates ?? []).filter(g => !prevGateIds.has(g.id)),
+            gatesRemoved: (prev.world.gates ?? []).filter(g => !nextGateIds.has(g.id)),
+            thesisChanged: prev.world.thesis !== next.world.thesis,
+        };
+    }
+    return {
+        id: sessionId,
+        async run(world, narrativeEvents) {
+            const iteration = runs.length + 1;
+            const result = await (0, governedSimulation_1.runGovernedComparison)(request, world.world, paths, narrativeEvents);
+            const ruleChanges = runs.length > 0
+                ? diffRules(runs[runs.length - 1].world, world)
+                : undefined;
+            const run = {
+                id: `${sessionId}_run_${iteration}`,
+                iteration,
+                world,
+                result,
+                timestamp: new Date().toISOString(),
+                ruleChanges,
+            };
+            runs.push(run);
+            return run;
+        },
+        get runs() {
+            return runs;
+        },
+        generateReport() {
+            if (runs.length === 0) {
+                throw new Error("No runs to report on. Run at least one enforcement pass first.");
+            }
+            const summaries = runs.map(r => ({
+                iteration: r.iteration,
+                worldName: r.world.name,
+                ruleCount: r.world.world.invariants.length,
+                gateCount: (r.world.world.gates ?? []).length,
+                metrics: r.result.governed.metrics,
+                comparison: r.result.comparison,
+                governanceStats: r.result.governanceStats,
+                ruleChanges: r.ruleChanges,
+                behavioralSummary: r.result.behavioralAnalysis.summary,
+            }));
+            const divergence = computeDivergence(summaries);
+            // Build cross-run behavioral comparisons
+            const behavioralComparisons = [];
+            for (let i = 1; i < runs.length; i++) {
+                const prev = runs[i - 1];
+                const curr = runs[i];
+                // Describe what rules changed
+                const ruleChanges = curr.ruleChanges;
+                const deltaDesc = ruleChanges
+                    ? [
+                        ...ruleChanges.added.map(r => `+${r.description}`),
+                        ...ruleChanges.removed.map(r => `-${r.description}`),
+                        ...(ruleChanges.thesisChanged ? ["thesis changed"] : []),
+                    ].join("; ") || "no rule changes"
+                    : "first run";
+                behavioralComparisons.push((0, behavioralAnalysis_1.compareBehaviorAcrossRuns)(prev.world.name, prev.result.governed.swarm.rounds, curr.world.name, curr.result.governed.swarm.rounds, deltaDesc));
+            }
+            const recommendation = buildRecommendation(summaries, divergence);
+            return {
+                sessionId,
+                scenario,
+                runs: summaries,
+                divergence,
+                behavioralComparisons,
+                recommendation,
+                generatedAt: new Date().toISOString(),
+            };
+        },
+        forkWorldForNextRun(source, name, modifications) {
+            return (0, worldStorage_1.forkWorld)(source, name, modifications);
+        },
+    };
+}
+// ============================================
+// DIVERGENCE COMPUTATION
+// ============================================
+function computeDivergence(runs) {
+    const stabilityTrend = runs.map(r => r.metrics.stabilityScore);
+    const collapseTrend = runs.map(r => r.metrics.collapseProbability);
+    const effectivenessTrend = runs.map(r => r.comparison.governanceEffectiveness);
+    // Find best and worst by governance effectiveness
+    let bestIteration = 1;
+    let worstIteration = 1;
+    let bestScore = -Infinity;
+    let worstScore = Infinity;
+    for (const run of runs) {
+        const score = run.comparison.governanceEffectiveness;
+        if (score > bestScore) {
+            bestScore = score;
+            bestIteration = run.iteration;
+        }
+        if (score < worstScore) {
+            worstScore = score;
+            worstIteration = run.iteration;
+        }
+    }
+    // Total divergence: sum of absolute changes between consecutive runs
+    let totalDivergence = 0;
+    for (let i = 1; i < runs.length; i++) {
+        const prev = runs[i - 1];
+        const curr = runs[i];
+        totalDivergence += Math.abs(curr.metrics.stabilityScore - prev.metrics.stabilityScore);
+        totalDivergence += Math.abs(curr.metrics.collapseProbability - prev.metrics.collapseProbability);
+        totalDivergence += Math.abs(curr.comparison.governanceEffectiveness - prev.comparison.governanceEffectiveness);
+    }
+    totalDivergence = Number(totalDivergence.toFixed(3));
+    const narrative = buildDivergenceNarrative(runs, bestIteration, worstIteration, totalDivergence);
+    return {
+        stabilityTrend,
+        collapseTrend,
+        effectivenessTrend,
+        bestIteration,
+        worstIteration,
+        totalDivergence,
+        narrative,
+    };
+}
+function buildDivergenceNarrative(runs, bestIteration, worstIteration, totalDivergence) {
+    if (runs.length === 1) {
+        return `Single run — no cross-run divergence. Run additional iterations with different rules to see how governance shapes outcomes.`;
+    }
+    const parts = [];
+    const first = runs[0];
+    const last = runs[runs.length - 1];
+    const stabilityDelta = last.metrics.stabilityScore - first.metrics.stabilityScore;
+    const collapseDelta = first.metrics.collapseProbability - last.metrics.collapseProbability;
+    if (stabilityDelta > 0.05) {
+        parts.push(`Stability improved ${(stabilityDelta * 100).toFixed(0)}pp from run 1 to run ${runs.length}.`);
+    }
+    else if (stabilityDelta < -0.05) {
+        parts.push(`Stability decreased ${(Math.abs(stabilityDelta) * 100).toFixed(0)}pp — later rules may be too restrictive or too loose.`);
+    }
+    if (collapseDelta > 0.05) {
+        parts.push(`Collapse risk reduced ${(collapseDelta * 100).toFixed(0)}pp through rule iteration.`);
+    }
+    parts.push(`Best outcome: iteration ${bestIteration} ("${runs[bestIteration - 1].worldName}").`);
+    if (bestIteration !== worstIteration) {
+        parts.push(`Worst outcome: iteration ${worstIteration} ("${runs[worstIteration - 1].worldName}").`);
+    }
+    parts.push(`Total measurable divergence across ${runs.length} runs: ${totalDivergence.toFixed(2)}.`);
+    // Rule change impact
+    for (let i = 1; i < runs.length; i++) {
+        const r = runs[i];
+        if (r.ruleChanges) {
+            const changes = [];
+            if (r.ruleChanges.added.length > 0)
+                changes.push(`+${r.ruleChanges.added.length} rules`);
+            if (r.ruleChanges.removed.length > 0)
+                changes.push(`-${r.ruleChanges.removed.length} rules`);
+            if (r.ruleChanges.gatesAdded.length > 0)
+                changes.push(`+${r.ruleChanges.gatesAdded.length} gates`);
+            if (r.ruleChanges.gatesRemoved.length > 0)
+                changes.push(`-${r.ruleChanges.gatesRemoved.length} gates`);
+            if (r.ruleChanges.thesisChanged)
+                changes.push(`thesis changed`);
+            if (changes.length > 0) {
+                const effDelta = r.comparison.governanceEffectiveness - runs[i - 1].comparison.governanceEffectiveness;
+                const dir = effDelta > 0 ? "improved" : effDelta < 0 ? "reduced" : "unchanged";
+                parts.push(`Run ${r.iteration} (${changes.join(", ")}): effectiveness ${dir}.`);
+            }
+        }
+    }
+    return parts.join(" ");
+}
+function buildRecommendation(runs, divergence) {
+    if (runs.length === 1) {
+        return `Single run completed. Fork the world, modify rules, and run again to test iterative governance design.`;
+    }
+    const best = runs[divergence.bestIteration - 1];
+    const parts = [];
+    parts.push(`Recommended rule set: "${best.worldName}" (iteration ${divergence.bestIteration}).`);
+    parts.push(`This configuration achieved ${(best.comparison.governanceEffectiveness * 100).toFixed(0)}% governance effectiveness`);
+    parts.push(`with ${(best.metrics.stabilityScore * 100).toFixed(0)}% stability and ${(best.metrics.collapseProbability * 100).toFixed(0)}% collapse probability.`);
+    if (best.ruleCount > 0) {
+        parts.push(`Active rules: ${best.ruleCount} invariants, ${best.gateCount} gates.`);
+    }
+    return parts.join(" ");
+}
+// ============================================
+// FORMATTING — CLI + Report Output
+// ============================================
+/**
+ * Format an enforcement report for CLI output.
+ */
+function formatEnforcementReport(report) {
+    const lines = [];
+    lines.push("");
+    lines.push("  POLICY ENFORCEMENT REPORT");
+    lines.push("  " + "=".repeat(70));
+    lines.push(`  Scenario: ${report.scenario}`);
+    lines.push(`  Iterations: ${report.runs.length}`);
+    lines.push(`  Session: ${report.sessionId}`);
+    lines.push("");
+    // Per-run summary table
+    lines.push("  RUN HISTORY");
+    lines.push("  " + "-".repeat(70));
+    lines.push(`  ${"#".padEnd(4)} ${"World".padEnd(25)} ${"Rules".padEnd(8)} ${"Stability".padEnd(12)} ${"Collapse".padEnd(12)} ${"Effectiveness"}`);
+    lines.push("  " + "-".repeat(70));
+    for (const run of report.runs) {
+        const name = run.worldName.length > 23 ? run.worldName.slice(0, 22) + "…" : run.worldName;
+        lines.push(`  ${String(run.iteration).padEnd(4)} ${name.padEnd(25)} ${String(run.ruleCount + run.gateCount).padEnd(8)} ${(run.metrics.stabilityScore * 100).toFixed(0).padStart(4)}%       ${(run.metrics.collapseProbability * 100).toFixed(0).padStart(4)}%       ${(run.comparison.governanceEffectiveness * 100).toFixed(0)}%`);
+    }
+    // Per-run behavioral summary
+    lines.push("");
+    lines.push("  BEHAVIORAL IMPACT PER RUN");
+    lines.push("  " + "-".repeat(70));
+    for (const run of report.runs) {
+        const bs = run.behavioralSummary;
+        lines.push(`  Run ${run.iteration}: ${bs.headline}`);
+        lines.push(`    Adapted: ${bs.agentsAdapted}/${bs.totalAgents} agents (${(bs.adaptationRate * 100).toFixed(0)}%) | Aggressive: ${bs.aggressiveReduction > 0 ? "-" : "+"}${Math.abs(bs.aggressiveReduction).toFixed(0)}pp | Cooperative: ${bs.cooperativeIncrease > 0 ? "+" : ""}${bs.cooperativeIncrease.toFixed(0)}pp`);
+    }
+    // Rule changes between runs
+    const runsWithChanges = report.runs.filter(r => r.ruleChanges);
+    if (runsWithChanges.length > 0) {
+        lines.push("");
+        lines.push("  RULE CHANGES");
+        lines.push("  " + "-".repeat(70));
+        for (const run of runsWithChanges) {
+            const rc = run.ruleChanges;
+            lines.push(`  Run ${run.iteration}:`);
+            for (const inv of rc.added) {
+                lines.push(`    + ${inv.description}`);
+            }
+            for (const inv of rc.removed) {
+                lines.push(`    - ${inv.description}`);
+            }
+            for (const gate of rc.gatesAdded) {
+                lines.push(`    + [GATE] ${gate.label}: ${gate.condition}`);
+            }
+            for (const gate of rc.gatesRemoved) {
+                lines.push(`    - [GATE] ${gate.label}`);
+            }
+            if (rc.thesisChanged) {
+                lines.push(`    ~ Thesis changed`);
+            }
+        }
+    }
+    // Divergence analysis
+    lines.push("");
+    lines.push("  DIVERGENCE ANALYSIS");
+    lines.push("  " + "-".repeat(70));
+    lines.push(`  Stability trend:     ${report.divergence.stabilityTrend.map(s => `${(s * 100).toFixed(0)}%`).join(" → ")}`);
+    lines.push(`  Collapse trend:      ${report.divergence.collapseTrend.map(s => `${(s * 100).toFixed(0)}%`).join(" → ")}`);
+    lines.push(`  Effectiveness trend: ${report.divergence.effectivenessTrend.map(s => `${(s * 100).toFixed(0)}%`).join(" → ")}`);
+    lines.push(`  Total divergence:    ${report.divergence.totalDivergence}`);
+    lines.push("");
+    lines.push(`  ${report.divergence.narrative}`);
+    // Cross-run behavioral comparisons — the CEO's view
+    if (report.behavioralComparisons.length > 0) {
+        lines.push("");
+        lines.push("  WHAT AGENTS DID DIFFERENTLY");
+        lines.push("  " + "=".repeat(70));
+        for (const comp of report.behavioralComparisons) {
+            lines.push(`  ${comp.runALabel} → ${comp.runBLabel}`);
+            lines.push(`  Rule change: ${comp.rulesDelta}`);
+            lines.push(`  ${comp.headline}`);
+            lines.push("");
+            // Show per-agent behavior changes
+            const changed = comp.agentDifferences.filter(a => a.changed);
+            if (changed.length > 0) {
+                for (const diff of changed) {
+                    lines.push(`    * ${diff.agentId}: ${diff.runABehavior} → ${diff.runBBehavior} (impact: ${diff.runAAvgImpact} → ${diff.runBAvgImpact})`);
+                }
+            }
+            // Key shifts
+            for (const shift of comp.keyShifts) {
+                lines.push(`    [${shift.type.replace(/_/g, " ").toUpperCase()}] ${shift.description}`);
+            }
+            lines.push("  " + "-".repeat(70));
+        }
+    }
+    // Key Insight (the money moment)
+    const insight = extractKeyInsight(report.runs);
+    if (insight) {
+        lines.push("");
+        lines.push("  KEY INSIGHT");
+        lines.push("  " + "-".repeat(70));
+        lines.push(`  ${insight}`);
+    }
+    // Recommendation
+    lines.push("");
+    lines.push("  RECOMMENDATION");
+    lines.push("  " + "-".repeat(70));
+    lines.push(`  ${report.recommendation}`);
+    // Footer
+    lines.push("");
+    lines.push("  " + "=".repeat(70));
+    lines.push("  NeuroVerse Policy Enforcement System");
+    lines.push("  Design rules. Run reality. See what changes.");
+    lines.push("  " + "=".repeat(70));
+    lines.push("");
+    return lines.join("\n");
+}
+/**
+ * Generate guided next steps for the user.
+ *
+ * Design principle: ONE mental model.
+ *   - Write rules in plain English → run enforce → see what changes
+ *   - JSON world files are optional (power user path)
+ *   - Every output ends with an experiment prompt
+ *   - ALL suggestions come from governed AI — with trace
+ */
+async function formatGuidedNextSteps(report, usedCustomInput) {
+    const lines = [];
+    // Experiment prompts — governed AI generates these
+    const { experiments, governance } = await suggestExperiments(report);
+    if (experiments.length > 0) {
+        for (const exp of experiments) {
+            lines.push("");
+            lines.push(`  ${exp.label}`);
+            lines.push("  " + "-".repeat(70));
+            lines.push(`  ${exp.prompt}`);
+            lines.push("");
+            lines.push(`    ${exp.command}`);
+            lines.push("");
+            lines.push(`  ${exp.expectation}`);
+        }
+        // Show governance trace — the AI is governed too
+        lines.push("");
+        lines.push(`  ┌─ Governed AI ────────────────────────────────┐`);
+        lines.push(`  │ Actor: ${governance.actor.padEnd(40)}│`);
+        lines.push(`  │ Action: ${governance.action.padEnd(39)}│`);
+        lines.push(`  │ Constraints: ${String(governance.trace.constraints.length).padEnd(34)}│`);
+        lines.push(`  │ Passed: ${String(governance.trace.passed).padEnd(39)}│`);
+        if (governance.trace.violations.length > 0) {
+            lines.push(`  │ Violations: ${governance.trace.violations.join(", ").slice(0, 35).padEnd(35)}│`);
+        }
+        lines.push(`  └──────────────────────────────────────────────┘`);
+    }
+    lines.push("");
+    lines.push("  WHAT TO DO NEXT");
+    lines.push("  " + "-".repeat(70));
+    if (!usedCustomInput) {
+        // First run — teach them the simplest path
+        lines.push("");
+        lines.push("  Write your own rules. No JSON needed — just plain English.");
+        lines.push("");
+        lines.push("  1. Create a text file (my-rules.txt):");
+        lines.push("");
+        lines.push("       Block panic selling during high volatility");
+        lines.push("       Limit leverage to 5x");
+        lines.push("       Maintain minimum liquidity floor");
+        lines.push("       Slow down algorithmic trading when contagion spreads");
+        lines.push("");
+        lines.push("  2. Run it:");
+        lines.push("");
+        lines.push("       npx nv-sim enforce trading my-rules.txt");
+        lines.push("");
+        lines.push("  3. Change a rule. Run again. See what changes.");
+        lines.push("");
+        lines.push("  That's it. Rules are plain English. No DSL. No config.");
+    }
+    else {
+        // They already used custom input — guide iteration
+        const best = report.runs[report.divergence.bestIteration - 1];
+        lines.push("");
+        lines.push(`  Best result: "${best.worldName}" (iteration ${report.divergence.bestIteration}).`);
+        lines.push("");
+        lines.push("  To iterate: edit your rules file and run again.");
+        lines.push("  To compare two rule sets side by side:");
+        lines.push("");
+        lines.push("    npx nv-sim enforce trading light-rules.txt strict-rules.txt");
+        lines.push("");
+        lines.push("  To try a different scenario:");
+        lines.push("");
+        lines.push("    npx nv-sim enforce strait_of_hormuz my-rules.txt");
+        lines.push("    npx nv-sim enforce ai_regulation_crisis my-rules.txt");
+        lines.push("");
+        lines.push("  To save a report:");
+        lines.push("");
+        lines.push("    npx nv-sim enforce trading my-rules.txt --output=report.json");
+    }
+    // Rule patterns — always show, it's the reference card
+    lines.push("");
+    lines.push("  RULE PATTERNS (what the engine understands)");
+    lines.push("  " + "-".repeat(70));
+    lines.push('    "Block X"      → hard suppression of matching actions');
+    lines.push('    "Limit X"      → caps extreme positions');
+    lines.push('    "Slow X"       → dampens large movements');
+    lines.push('    "Maintain X"   → enforces minimum thresholds');
+    lines.push('    "Rebalance X"  → pulls extremes toward equilibrium');
+    lines.push('    "Require X"    → enforceable structural constraint');
+    lines.push('    "Monitor X"    → generates a gate (circuit breaker)');
+    lines.push("");
+    lines.push("  Examples:  examples/policies/trading-rules.txt");
+    lines.push("             examples/policies/strict-rules.txt");
+    lines.push("");
+    return lines.join("\n");
+}
+/**
+ * Suggest experiments via the governed AI pipeline.
+ *
+ * ALL suggestions flow through evaluateAIAction() — the AI analyst
+ * is subject to the same governance constraints as any other actor.
+ *
+ * Two kinds:
+ *   TRY REMOVING — which rules are load-bearing?
+ *   TRY ADDING   — what new rule could improve this?
+ *
+ * Users aren't just pruning. They're designing.
+ * And the governed AI is their design partner.
+ */
+async function suggestExperiments(report) {
+    const analystRole = aiProvider_1.AI_ROLES.find(r => r.id === "ai_analyst");
+    const governance = await (0, aiProvider_1.evaluateAIAction)(analystRole, "suggest_experiments", async () => generateExperimentsFromTrace(report));
+    return {
+        experiments: governance.result,
+        governance,
+    };
+}
+/**
+ * Governed archetype detection.
+ * The ai_analyst detects system patterns — this goes through governance.
+ */
+async function governedDetectArchetype(report) {
+    const analystRole = aiProvider_1.AI_ROLES.find(r => r.id === "ai_analyst");
+    return (0, aiProvider_1.evaluateAIAction)(analystRole, "detect_archetype", async () => detectSystemArchetype(report));
+}
+/**
+ * Governed strategy synthesis from experiment library.
+ * Recommendations are governed — even when derived from past experiments.
+ */
+async function governedSynthesizeStrategy(archetype, currentMetrics, library) {
+    const analystRole = aiProvider_1.AI_ROLES.find(r => r.id === "ai_analyst");
+    return (0, aiProvider_1.evaluateAIAction)(analystRole, "synthesize_strategy", async () => formatBestKnownStrategy(archetype, currentMetrics, library));
+}
+/**
+ * Governed experiment comparison and similarity search.
+ * Even "find similar" is governed — the analyst is constrained.
+ */
+async function governedFindSimilar(archetype, currentMetrics, library) {
+    const analystRole = aiProvider_1.AI_ROLES.find(r => r.id === "ai_analyst");
+    return (0, aiProvider_1.evaluateAIAction)(analystRole, "compare_experiments", async () => formatSimilarExperiments(archetype, currentMetrics, library));
+}
+/**
+ * Deterministic experiment generation from trace data.
+ * No LLM needed — the governed system analyzes metrics and suggests.
+ *
+ * This is the ai_analyst actor generating suggestions from ground truth.
+ * It must reference trace data (must_reference_trace constraint),
+ * include metrics (must_include_metrics), and make no unverifiable claims.
+ */
+function generateExperimentsFromTrace(report) {
+    if (report.runs.length < 1)
+        return [];
+    const experiments = [];
+    const runs = report.runs;
+    const best = runs[report.divergence.bestIteration - 1];
+    const worst = report.runs.length > 1 ? runs[report.divergence.worstIteration - 1] : null;
+    // ---- SUBTRACTIVE: Try removing a rule ----
+    if (best.ruleChanges && best.ruleChanges.added.length > 0) {
+        const keyRule = best.ruleChanges.added[0];
+        experiments.push({
+            label: "TRY REMOVING",
+            prompt: `Remove this rule and see what happens:`,
+            command: `Remove "${keyRule.description}" from your rules file, then run again.`,
+            expectation: `If stability drops, that rule was load-bearing. If nothing changes, it was noise.`,
+        });
+    }
+    else if (worst && worst.iteration > 1 && worst.ruleChanges && worst.ruleChanges.added.length > 0) {
+        experiments.push({
+            label: "TRY REMOVING",
+            prompt: `Iteration ${worst.iteration} made things worse. Remove the rules that were added:`,
+            command: `Remove: "${worst.ruleChanges.added.map(r => r.description).join('", "')}"`,
+            expectation: `Fewer rules sometimes outperform more. Find out which ones actually matter.`,
+        });
+    }
+    else if (best.ruleCount > 3) {
+        experiments.push({
+            label: "TRY REMOVING",
+            prompt: `Your best run used ${best.ruleCount} rules. Can you do better with fewer?`,
+            command: `Create a file with just 2 rules and run: npx nv-sim enforce trading minimal.txt`,
+            expectation: `Sometimes 2 precise rules beat 8 broad ones.`,
+        });
+    }
+    // ---- GENERATIVE: Try adding a rule ----
+    // AI analyst reads metrics from trace and suggests based on what it sees
+    const bestMetrics = best.metrics;
+    const bestComparison = best.comparison;
+    if (bestMetrics.collapseProbability > 0.1) {
+        experiments.push({
+            label: "TRY ADDING",
+            prompt: `Collapse risk is still ${(bestMetrics.collapseProbability * 100).toFixed(0)}%. Try a circuit breaker:`,
+            command: `Add "Monitor system stress and halt trading during extreme conditions"`,
+            expectation: `If collapse risk drops, this rule is acting as a circuit breaker. If velocity collapses, it may be too restrictive.`,
+        });
+    }
+    else if (bestMetrics.maxVolatility > 0.5) {
+        experiments.push({
+            label: "TRY ADDING",
+            prompt: `Volatility is still high (${(bestMetrics.maxVolatility * 100).toFixed(0)}%). Try dampening:`,
+            command: `Add "Slow down all large position changes during elevated volatility"`,
+            expectation: `If volatility drops without killing effectiveness, this is a precision rule. If both drop, it's too broad.`,
+        });
+    }
+    else if (bestMetrics.polarizationEvents > 0) {
+        experiments.push({
+            label: "TRY ADDING",
+            prompt: `${bestMetrics.polarizationEvents} polarization event(s) detected. Try rebalancing:`,
+            command: `Add "Rebalance correlated positions when concentration exceeds threshold"`,
+            expectation: `If polarization disappears, agents were clustering. If it persists, the cause is structural.`,
+        });
+    }
+    else if (bestComparison.governanceEffectiveness < 0.3) {
+        experiments.push({
+            label: "TRY ADDING",
+            prompt: `Governance effectiveness is only ${(bestComparison.governanceEffectiveness * 100).toFixed(0)}%. Try a structural constraint:`,
+            command: `Add "Gate high-risk trades behind approval"`,
+            expectation: `If effectiveness jumps, your current rules are too soft. If nothing changes, the scenario may need different types of rules.`,
+        });
+    }
+    else if (bestMetrics.coalitionRisks > 0) {
+        experiments.push({
+            label: "TRY ADDING",
+            prompt: `${bestMetrics.coalitionRisks} coalition risk(s) detected. Try transparency:`,
+            command: `Add "Require all large position changes to be reported"`,
+            expectation: `If coalition risks drop, hidden coordination was the problem. Transparency breaks collusion.`,
+        });
+    }
+    else {
+        experiments.push({
+            label: "TRY ADDING",
+            prompt: `System is stable. Now stress-test your rules:`,
+            command: `Add "Allow leverage up to 10x" — then run again.`,
+            expectation: `If stability holds, your rules are robust. If it breaks, you've found the boundary.`,
+        });
+    }
+    return experiments;
+}
+function extractKeyInsight(runs) {
+    if (runs.length < 2)
+        return null;
+    // Check if adding more rules made things worse
+    for (let i = 1; i < runs.length; i++) {
+        const prev = runs[i - 1];
+        const curr = runs[i];
+        const effDelta = curr.comparison.governanceEffectiveness - prev.comparison.governanceEffectiveness;
+        const stabDelta = curr.metrics.stabilityScore - prev.metrics.stabilityScore;
+        const addedRules = (curr.ruleChanges?.added.length ?? 0) + (curr.ruleChanges?.gatesAdded.length ?? 0);
+        if (effDelta < -0.02 && addedRules > 0) {
+            return `Adding ${addedRules} rule(s) in iteration ${curr.iteration} reduced effectiveness. More rules don't always mean better governance — precision matters more than volume.`;
+        }
+        if (stabDelta < -0.05 && addedRules > 0) {
+            return `Iteration ${curr.iteration} degraded stability despite adding rules. The new constraints may conflict or over-restrict agent behavior.`;
+        }
+    }
+    // Check if gates made the big difference
+    const runsWithGates = runs.filter(r => r.gateCount > 0);
+    const runsWithoutGates = runs.filter(r => r.gateCount === 0);
+    if (runsWithGates.length > 0 && runsWithoutGates.length > 0) {
+        const avgWithGates = runsWithGates.reduce((s, r) => s + r.comparison.governanceEffectiveness, 0) / runsWithGates.length;
+        const avgWithout = runsWithoutGates.reduce((s, r) => s + r.comparison.governanceEffectiveness, 0) / runsWithoutGates.length;
+        if (avgWithGates > avgWithout + 0.05) {
+            return `Enforcement gates (circuit breakers) are the key differentiator. Rules alone improved effectiveness ${(avgWithout * 100).toFixed(0)}% → rules + gates achieved ${(avgWithGates * 100).toFixed(0)}%.`;
+        }
+    }
+    // Check stability improvement
+    const first = runs[0];
+    const last = runs[runs.length - 1];
+    const stabImprovement = last.metrics.stabilityScore - first.metrics.stabilityScore;
+    if (stabImprovement > 0.1) {
+        return `Governance improved system stability by ${(stabImprovement * 100).toFixed(0)} percentage points across ${runs.length} iterations. Rule iteration works.`;
+    }
+    return null;
+}
+// ============================================
+// GITHUB-STYLE DIAGNOSTIC DISPLAY
+// ============================================
+/**
+ * Format policy diagnostics like GitHub code review.
+ *
+ * Shows errors, warnings, hints with:
+ *   - Line references back to the original file
+ *   - Suggested fixes with exact replacement text
+ *   - Quick fix commands the user can apply
+ *   - Health score and status badge
+ *
+ * "Even the rules get reviewed."
+ */
+function formatPolicyDiagnostics(health, parsed, fileName) {
+    const lines = [];
+    const diags = health.diagnostics;
+    if (diags.length === 0 && health.status === "healthy") {
+        lines.push("");
+        lines.push(`  ✓ ${fileName} — No issues found (${health.healthScore}/100)`);
+        lines.push(`    All rules are structurally sound. Ready to enforce.`);
+        lines.push("");
+        return lines.join("\n");
+    }
+    // Header with causal status — tie validation to system behavior
+    const statusIcon = health.status === "critical" || health.status === "errors" ? "✗"
+        : health.status === "warnings" ? "!"
+            : "✓";
+    const causalSummary = describeCausalImpact(health, parsed);
+    lines.push("");
+    lines.push(`  ${statusIcon} POLICY REVIEW — ${fileName}`);
+    lines.push("  " + "-".repeat(70));
+    lines.push(`  Health: ${health.healthScore}/100 — ${causalSummary}`);
+    lines.push(`  Rules: ${parsed.summary.total} (${parsed.summary.enforced} enforced, ${parsed.summary.advisory} advisory)`);
+    lines.push("");
+    // Sort: errors first, then warnings, info, hints
+    const severityOrder = { error: 0, warning: 1, info: 2, hint: 3 };
+    const sorted = [...diags].sort((a, b) => (severityOrder[a.severity] ?? 4) - (severityOrder[b.severity] ?? 4));
+    for (const diag of sorted) {
+        const icon = diag.severity === "error" ? "✗"
+            : diag.severity === "warning" ? "!"
+                : diag.severity === "info" ? "i"
+                    : "·";
+        const tag = diag.severity.toUpperCase().padEnd(7);
+        // Diagnostic header
+        lines.push(`  ${icon} ${tag} ${diag.id}: ${diag.message}`);
+        // Source location
+        if (diag.source) {
+            const lineRef = diag.source.startLine === diag.source.endLine
+                ? `line ${diag.source.startLine}`
+                : `lines ${diag.source.startLine}-${diag.source.endLine}`;
+            lines.push(`    ${fileName}:${lineRef}`);
+        }
+        // Detail
+        lines.push(`    ${diag.detail}`);
+        // Related rules
+        if (diag.relatedRules.length > 0 && diag.relatedRules.length <= 5) {
+            for (const ruleId of diag.relatedRules) {
+                const rule = parsed.rules.find(r => r.id === ruleId);
+                if (rule) {
+                    lines.push(`    │ ${ruleId} (line ${rule.sourceLine}): "${rule.originalText}"`);
+                }
+            }
+        }
+        // WHY THIS MATTERS — micro-teaching
+        const why = explainWhyItMatters(diag);
+        if (why) {
+            lines.push("");
+            lines.push(`    WHY THIS MATTERS`);
+            lines.push(`    ${why}`);
+        }
+        // Suggested fix
+        if (diag.fix) {
+            lines.push("");
+            lines.push(`    Suggested fix: ${diag.fix}`);
+        }
+        // Quick fix — show the exact text operation
+        if (diag.quickFix) {
+            const qf = diag.quickFix;
+            lines.push("");
+            lines.push(`    ┌─ Quick Fix: ${qf.label} ─${"─".repeat(Math.max(0, 50 - qf.label.length))}┐`);
+            if (qf.operation === "replace" && qf.targetLines && qf.targetLines.length > 0) {
+                for (const ln of qf.targetLines) {
+                    const rule = parsed.rules.find(r => r.sourceLine === ln);
+                    if (rule) {
+                        lines.push(`    │ - line ${ln}: "${rule.originalText}"`);
+                    }
+                }
+                lines.push(`    │ + "${qf.text}"`);
+            }
+            else if (qf.operation === "insert") {
+                for (const insertLine of qf.text.split("\n")) {
+                    lines.push(`    │ + "${insertLine}"`);
+                }
+            }
+            else if (qf.operation === "remove" && qf.targetLines) {
+                for (const ln of qf.targetLines) {
+                    const rule = parsed.rules.find(r => r.sourceLine === ln);
+                    if (rule) {
+                        lines.push(`    │ - line ${ln}: "${rule.originalText}"`);
+                    }
+                }
+            }
+            lines.push(`    └${"─".repeat(55)}┘`);
+            // EXPECTED IMPACT — predict what fixing this would do
+            const impact = predictFixImpact(diag, health, parsed);
+            if (impact) {
+                lines.push("");
+                lines.push(`    EXPECTED IMPACT`);
+                lines.push(`    Before:            ${impact.before}`);
+                lines.push(`    Estimated (simulated) After:   ${impact.after}`);
+                lines.push(`    ${impact.explanation}`);
+            }
+            // PATTERN INSIGHT — teach rule design thinking
+            const pattern = describePatternInsight(diag);
+            if (pattern) {
+                lines.push("");
+                lines.push(`    PATTERN INSIGHT`);
+                lines.push(`    ${pattern.insight}`);
+                lines.push(`    ${pattern.principle}`);
+            }
+            // TEST THIS FIX — zero friction
+            lines.push("");
+            lines.push(`    TEST THIS FIX`);
+            lines.push(`    Apply this change to ${fileName}, then:`);
+            lines.push(`      npx nv-sim enforce trading ${fileName}`);
+            lines.push(`    Or test the fix without editing:`);
+            lines.push(`      npx nv-sim enforce trading --patch ${diag.id}`);
+            lines.push(`    Compare before vs after side by side:`);
+            lines.push(`      npx nv-sim enforce trading --patch ${diag.id} --compare`);
+        }
+        lines.push("");
+    }
+    // Summary footer
+    const parts = [];
+    if (health.counts.errors > 0)
+        parts.push(`${health.counts.errors} error(s)`);
+    if (health.counts.warnings > 0)
+        parts.push(`${health.counts.warnings} warning(s)`);
+    if (health.counts.info > 0)
+        parts.push(`${health.counts.info} info`);
+    if (health.counts.hints > 0)
+        parts.push(`${health.counts.hints} hint(s)`);
+    lines.push(`  ${parts.join(" · ")}`);
+    if (!health.canSimulate) {
+        lines.push("");
+        lines.push("  ✗ Cannot simulate — fix errors above first.");
+    }
+    else if (health.counts.errors > 0) {
+        lines.push("");
+        lines.push("  ! Simulation will proceed, but errors may reduce policy effectiveness.");
+        lines.push("  Fix the issues above, then run again to see the difference.");
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+// ============================================
+// CAUSAL HEALTH LANGUAGE
+// ============================================
+/**
+ * Convert abstract health status to causal language tied to system behavior.
+ * "72/100" is abstract. "72/100 — Conflicts may reduce effectiveness" is actionable.
+ */
+function describeCausalImpact(health, parsed) {
+    const hasConflicts = health.diagnostics.some(d => d.category === "conflict" && d.severity === "error");
+    const hasOverConstrain = health.diagnostics.some(d => d.category === "constraint");
+    const hasWeakEnforcement = health.diagnostics.some(d => d.category === "strength");
+    const hasCoverageGaps = health.diagnostics.some(d => d.category === "coverage");
+    const noRules = parsed.rules.length === 0;
+    if (noRules)
+        return "No rules detected — system will run ungoverned";
+    if (hasConflicts)
+        return "Conflicting rules will create agent deadlocks, reducing system throughput";
+    if (hasOverConstrain)
+        return "Over-restrictive rules may freeze the system during crises";
+    if (hasWeakEnforcement && parsed.summary.enforced === 0)
+        return "No enforceable rules — policy will have no measurable effect";
+    if (hasWeakEnforcement)
+        return "Weak enforcement may produce minimal governance effect";
+    if (hasCoverageGaps)
+        return "Coverage gaps leave critical variables ungoverned";
+    if (health.counts.warnings > 0)
+        return "Minor issues may reduce governance precision";
+    return "Rules are structurally sound";
+}
+// ============================================
+// WHY THIS MATTERS — MICRO-TEACHING
+// ============================================
+/**
+ * One-line explanation of system-level impact for each diagnostic.
+ * This turns validation into education.
+ */
+function explainWhyItMatters(diag) {
+    // Match on category + severity for targeted explanations
+    if (diag.category === "conflict" && diag.severity === "error") {
+        return "Conflicting rules create deadlocks — agents can't comply with both, so neither rule fires effectively.";
+    }
+    if (diag.category === "conflict" && diag.severity === "warning") {
+        return "Overlapping rules compete for the same actions. The engine picks one, which may not be the one you intended.";
+    }
+    if (diag.category === "strength" && diag.severity === "error") {
+        return "Advisory rules are suggestions, not constraints. Without enforcement, agents ignore them under stress.";
+    }
+    if (diag.category === "strength" && diag.severity === "warning") {
+        return "Weak enforcement means most rules are advisory. Under pressure, agents will bypass suggestions.";
+    }
+    if (diag.category === "constraint") {
+        return "Over-constrained systems freeze — agents can't act, so the system fails to respond to crises at all.";
+    }
+    if (diag.category === "coverage" && diag.message.includes("circuit breaker")) {
+        return "Without a circuit breaker, there's no emergency stop. Cascading failures can propagate unchecked.";
+    }
+    if (diag.category === "coverage") {
+        return "Ungoverned variables are blind spots. Agents exploit ungoverned dimensions to route around constraints.";
+    }
+    if (diag.category === "structure" && diag.severity === "hint") {
+        return "Redundant rules add complexity without adding governance. Simpler rule sets are easier to reason about.";
+    }
+    return null;
+}
+/**
+ * Predict the system-level impact of applying a quick fix.
+ * Uses the diagnostic category and rule structure to estimate.
+ *
+ * This is deterministic prediction from policy structure, not simulation.
+ * The real numbers come when they run it again — but this sets expectations.
+ */
+function predictFixImpact(diag, health, parsed) {
+    const currentScore = health.healthScore;
+    const ruleCount = parsed.rules.length;
+    const enforcedCount = parsed.summary.enforced;
+    if (diag.category === "conflict" && diag.severity === "error") {
+        // Conflicts cost ~25 health points each
+        const fixedScore = Math.min(100, currentScore + 25);
+        const effBefore = Math.max(5, Math.round(enforcedCount / Math.max(ruleCount, 1) * 30));
+        const effAfter = Math.round(effBefore * 1.8);
+        return {
+            before: `Health ${currentScore}/100, Effectiveness ~${effBefore}%`,
+            after: `Health ~${fixedScore}/100, Effectiveness ~${effAfter}%`,
+            explanation: "Resolving the conflict restores agent compliance and unblocks governance execution.",
+        };
+    }
+    if (diag.category === "strength" && (diag.severity === "error" || diag.severity === "warning")) {
+        const fixedScore = Math.min(100, currentScore + (diag.severity === "error" ? 25 : 10));
+        return {
+            before: `Health ${currentScore}/100, ${enforcedCount}/${ruleCount} rules enforced`,
+            after: `Health ~${fixedScore}/100, ${Math.min(ruleCount, enforcedCount + 2)}/${ruleCount} rules enforced`,
+            explanation: "Strengthening enforcement gives the engine actionable constraints instead of suggestions.",
+        };
+    }
+    if (diag.category === "constraint") {
+        const fixedScore = Math.min(100, currentScore + 10);
+        return {
+            before: `Health ${currentScore}/100, system may freeze under stress`,
+            after: `Health ~${fixedScore}/100, agents retain response flexibility`,
+            explanation: "Adding flexibility rules lets agents respond to crises within governance bounds.",
+        };
+    }
+    if (diag.category === "coverage" && diag.message.includes("circuit breaker")) {
+        const fixedScore = Math.min(100, currentScore + 3);
+        return {
+            before: `Health ${currentScore}/100, no emergency stop mechanism`,
+            after: `Health ~${fixedScore}/100, cascade protection active`,
+            explanation: "A circuit breaker is the last line of defense — it catches what individual rules miss.",
+        };
+    }
+    if (diag.category === "coverage") {
+        const fixedScore = Math.min(100, currentScore + 3);
+        return {
+            before: `Health ${currentScore}/100, blind spots in governance`,
+            after: `Health ~${fixedScore}/100, critical variables governed`,
+            explanation: "Covering all critical variables prevents agents from exploiting ungoverned dimensions.",
+        };
+    }
+    return null;
+}
+/**
+ * After showing a quick fix, teach users the underlying rule design pattern.
+ * Not just "what to fix" but "how to think about rules."
+ */
+function describePatternInsight(diag) {
+    if (diag.category === "conflict" && diag.severity === "error") {
+        return {
+            insight: "This change converts a hard conflict into a conditional constraint.",
+            principle: "Hard rules (block/require) often conflict. Conditional rules (limit/gate) preserve flexibility.",
+        };
+    }
+    if (diag.category === "conflict" && diag.severity === "warning") {
+        return {
+            insight: "Overlapping rules are being merged into a single, precise constraint.",
+            principle: "One specific rule outperforms two vague ones. Precision > volume.",
+        };
+    }
+    if (diag.category === "strength" && diag.severity === "error") {
+        return {
+            insight: "This upgrades an advisory rule to an enforceable constraint.",
+            principle: "Advisory rules are suggestions. Under stress, agents ignore suggestions. Enforcement makes it real.",
+        };
+    }
+    if (diag.category === "strength" && diag.severity === "warning") {
+        return {
+            insight: "This rebalances your rule mix toward enforcement.",
+            principle: "The ideal ratio is ~60% enforced, ~40% advisory. Too many suggestions = no governance.",
+        };
+    }
+    if (diag.category === "constraint") {
+        return {
+            insight: "This relaxes over-restrictive rules into bounded flexibility.",
+            principle: "Good governance sets boundaries, not mandates. Agents need room to respond to crises.",
+        };
+    }
+    if (diag.category === "coverage") {
+        return {
+            insight: "This adds governance to an unmonitored system dimension.",
+            principle: "Agents optimize for what's measured. Ungoverned variables become attack surfaces.",
+        };
+    }
+    return null;
+}
+// ============================================
+// RULE IMPACT ATTRIBUTION
+// ============================================
+/**
+ * After a simulation run, attribute stability/effectiveness changes
+ * to individual rules.
+ *
+ * "Which rule actually caused the change?"
+ *
+ * This is the long-term moat: users can see exactly which rules
+ * are load-bearing and which are noise.
+ */
+function formatRuleImpactAttribution(report) {
+    if (report.runs.length < 1)
+        return "";
+    const lines = [];
+    const runs = report.runs;
+    // Build attribution from rule changes across iterations
+    const attributions = [];
+    for (let i = 0; i < runs.length; i++) {
+        const run = runs[i];
+        const prev = i > 0 ? runs[i - 1] : null;
+        if (!run.ruleChanges)
+            continue;
+        const stabDelta = prev
+            ? run.metrics.stabilityScore - prev.metrics.stabilityScore
+            : run.metrics.stabilityScore - 0.5; // baseline is 0.5 without rules
+        const effDelta = prev
+            ? run.comparison.governanceEffectiveness - prev.comparison.governanceEffectiveness
+            : run.comparison.governanceEffectiveness;
+        // Attribute to added rules
+        for (const rule of run.ruleChanges.added) {
+            const perRuleStab = run.ruleChanges.added.length > 0
+                ? stabDelta / run.ruleChanges.added.length
+                : 0;
+            const perRuleEff = run.ruleChanges.added.length > 0
+                ? effDelta / run.ruleChanges.added.length
+                : 0;
+            attributions.push({
+                ruleDescription: rule.description,
+                stabilityDelta: perRuleStab,
+                effectivenessDelta: perRuleEff,
+                iteration: run.iteration,
+                action: "added",
+            });
+        }
+        // Attribute gates
+        for (const gate of run.ruleChanges.gatesAdded) {
+            attributions.push({
+                ruleDescription: `Gate: ${gate.label}: ${gate.condition}`,
+                stabilityDelta: stabDelta * 0.3, // gates typically contribute ~30% of stability gains
+                effectivenessDelta: effDelta * 0.2,
+                iteration: run.iteration,
+                action: "added",
+            });
+        }
+    }
+    if (attributions.length === 0)
+        return "";
+    // Sort by absolute stability impact (most impactful first)
+    attributions.sort((a, b) => Math.abs(b.stabilityDelta) - Math.abs(a.stabilityDelta));
+    lines.push("");
+    lines.push("  RULE IMPACT");
+    lines.push("  " + "-".repeat(70));
+    lines.push("  Which rules shaped the outcome:");
+    lines.push("");
+    for (const attr of attributions.slice(0, 8)) {
+        const stabSign = attr.stabilityDelta >= 0 ? "+" : "";
+        const effSign = attr.effectivenessDelta >= 0 ? "+" : "";
+        const icon = attr.stabilityDelta >= 0 ? "+" : "-";
+        lines.push(`  ${icon} "${attr.ruleDescription}"`);
+        lines.push(`      ${stabSign}${Math.round(attr.stabilityDelta * 100)} stability, ${effSign}${Math.round(attr.effectivenessDelta * 100)} effectiveness`);
+        // Flag problematic rules
+        if (attr.stabilityDelta < -0.05) {
+            lines.push(`      ^ This rule degraded the system. Consider removing or conditioning it.`);
+        }
+        else if (attr.stabilityDelta > 0.15) {
+            lines.push(`      ^ Load-bearing rule. Removing this would significantly degrade stability.`);
+        }
+    }
+    if (attributions.length > 8) {
+        lines.push(`  ... and ${attributions.length - 8} more rules with minor impact`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+/**
+ * Detect the system archetype from simulation metrics.
+ *
+ * After runs, identify the structural pattern the system exhibits.
+ * This evolves the tool from "rule engine" to "system intelligence layer."
+ *
+ * Archetypes are derived from metrics, not guessed:
+ *   - High volatility + feedback = amplification loop
+ *   - Coalition risks + polarization = coordination failure
+ *   - High collapse probability = fragile equilibrium
+ *   - Stable + low effectiveness = governance disconnect
+ */
+function detectSystemArchetype(report) {
+    if (report.runs.length < 1)
+        return "";
+    const best = report.runs[report.divergence.bestIteration - 1];
+    const metrics = best.metrics;
+    const comparison = best.comparison;
+    const archetype = classifyArchetype(metrics, comparison);
+    if (!archetype)
+        return "";
+    const lines = [];
+    lines.push("");
+    lines.push("  SYSTEM PATTERN");
+    lines.push("  " + "-".repeat(70));
+    lines.push(`  This system behaves like: ${archetype.name}`);
+    lines.push(`  ${archetype.description}`);
+    lines.push("");
+    lines.push("  Common successful strategies:");
+    for (const strategy of archetype.successfulStrategies) {
+        lines.push(`    - ${strategy}`);
+    }
+    lines.push("");
+    lines.push(`  Risk pattern: ${archetype.riskPattern}`);
+    lines.push("");
+    return lines.join("\n");
+}
+function classifyArchetype(metrics, comparison) {
+    // High volatility + feedback amplification
+    if (metrics.maxVolatility > 0.5 && metrics.collapseProbability > 0.1) {
+        return {
+            name: "High-volatility system with feedback amplification",
+            description: "Agent actions amplify each other, creating cascading effects that compound rapidly.",
+            successfulStrategies: [
+                "Conditional gating (halt actions above threshold)",
+                "Volatility dampening (slow large movements)",
+                "Circuit breakers (emergency halt mechanisms)",
+            ],
+            riskPattern: "Hard constraints create deadlocks under stress — use conditional rules instead.",
+        };
+    }
+    // Coalition risks + polarization = coordination failure
+    if (metrics.coalitionRisks > 0 && metrics.polarizationEvents > 0) {
+        return {
+            name: "Coordination failure with polarization dynamics",
+            description: "Agents cluster into opposing groups. Hidden coordination and faction behavior dominate.",
+            successfulStrategies: [
+                "Transparency requirements (report large actions)",
+                "Rebalancing rules (pull extremes toward center)",
+                "Position limits (cap concentration)",
+            ],
+            riskPattern: "Surveillance rules without rebalancing increase polarization — combine both.",
+        };
+    }
+    // High collapse probability = fragile equilibrium
+    if (metrics.collapseProbability > 0.15) {
+        return {
+            name: "Fragile equilibrium under stress",
+            description: "The system appears stable but has hidden brittleness. Small shocks can trigger collapse.",
+            successfulStrategies: [
+                "Circuit breakers at multiple thresholds",
+                "Liquidity floors (maintain minimums)",
+                "Graduated response (escalating restrictions)",
+            ],
+            riskPattern: "Single-threshold rules fail — the system needs layered defense.",
+        };
+    }
+    // Stable but governance doesn't matter
+    if (metrics.stabilityScore > 0.8 && comparison.governanceEffectiveness < 0.15) {
+        return {
+            name: "Governance disconnect",
+            description: "The system is stable, but your rules aren't the reason. Governance has minimal measurable effect.",
+            successfulStrategies: [
+                "Stress-test with more extreme scenarios",
+                "Add rules targeting ungoverned variables",
+                "Increase scenario severity to find the rules' breaking point",
+            ],
+            riskPattern: "Rules that never activate provide false confidence — test under stress.",
+        };
+    }
+    // Coalition risks without polarization = hidden coordination
+    if (metrics.coalitionRisks > 0) {
+        return {
+            name: "Hidden coordination risk",
+            description: "Agents are forming coalitions that may circumvent governance. Actions appear independent but correlate.",
+            successfulStrategies: [
+                "Transparency requirements (require reporting)",
+                "Correlation monitoring (detect coordinated movements)",
+                "Position diversity requirements",
+            ],
+            riskPattern: "Punitive rules drive coordination underground — use transparency instead.",
+        };
+    }
+    // Effective governance + good stability = well-governed system
+    if (metrics.stabilityScore > 0.7 && comparison.governanceEffectiveness > 0.3) {
+        return {
+            name: "Well-governed adaptive system",
+            description: "Rules are effective and the system responds well to governance. Strong foundation for iteration.",
+            successfulStrategies: [
+                "Fine-tune existing rules (small parameter changes)",
+                "Add monitoring rules to detect drift",
+                "Stress-test with extreme scenarios to find limits",
+            ],
+            riskPattern: "Over-optimization at current conditions — rules may not generalize to new scenarios.",
+        };
+    }
+    return null;
+}
+/**
+ * Load all saved experiments from the experiments/ directory.
+ */
+function loadExperimentLibrary(experimentsDir = "experiments") {
+    if (!fs.existsSync(experimentsDir))
+        return [];
+    const files = fs.readdirSync(experimentsDir)
+        .filter((f) => f.endsWith(".json"));
+    const experiments = [];
+    for (const file of files) {
+        try {
+            const data = JSON.parse(fs.readFileSync(path.join(experimentsDir, file), "utf-8"));
+            if (data.id && data.metrics && data.report) {
+                experiments.push(data);
+            }
+        }
+        catch {
+            // Skip corrupted files
+        }
+    }
+    return experiments.sort((a, b) => new Date(a.savedAt).getTime() - new Date(b.savedAt).getTime());
+}
+/**
+ * Format a saved experiment for disk storage.
+ *
+ * Now includes lineage: tracks which experiment this was derived from,
+ * what patches were applied, and the improvement delta.
+ *
+ * Users build a decision tree of governance evolution:
+ *   v0 → v1 (+16 stability) → v2 (+4 stability, +12 effectiveness)
+ */
+function createSavedExperiment(report, rulesFile, patchesApplied, parentExperiment) {
+    const best = report.runs[report.divergence.bestIteration - 1];
+    const archetype = classifyArchetype(best.metrics, best.comparison);
+    const lineage = parentExperiment ? {
+        parentId: parentExperiment.id,
+        patchesFromParent: patchesApplied,
+        improvementFromParent: {
+            stability: best.metrics.stabilityScore - parentExperiment.metrics.stability,
+            effectiveness: best.comparison.governanceEffectiveness - parentExperiment.metrics.effectiveness,
+            collapseProbability: best.metrics.collapseProbability - parentExperiment.metrics.collapseProbability,
+        },
+        ancestors: [...parentExperiment.lineage.ancestors, parentExperiment.id],
+        generation: parentExperiment.lineage.generation + 1,
+    } : {
+        parentId: null,
+        patchesFromParent: [],
+        improvementFromParent: null,
+        ancestors: [],
+        generation: 0,
+    };
+    return {
+        id: `exp-${Date.now().toString(36)}`,
+        savedAt: new Date().toISOString(),
+        scenario: report.scenario,
+        rulesFile,
+        patchesApplied,
+        metrics: {
+            stability: best.metrics.stabilityScore,
+            effectiveness: best.comparison.governanceEffectiveness,
+            collapseProbability: best.metrics.collapseProbability,
+        },
+        ruleImpact: [],
+        archetype: archetype?.name ?? null,
+        lineage,
+        report,
+    };
+}
+/**
+ * Format experiment lineage as a visual chain.
+ *
+ * Shows the decision tree:
+ *   v0-baseline → v1-gating (+16 stab) → v2-dampening (+4 stab, +12 eff)
+ */
+function formatExperimentLineage(experiment, library) {
+    const lines = [];
+    if (experiment.lineage.generation === 0 && !experiment.lineage.parentId) {
+        lines.push("");
+        lines.push("  LINEAGE");
+        lines.push("  " + "-".repeat(70));
+        lines.push("  This is a root experiment (generation 0). No parent.");
+        lines.push("  Future experiments derived from this will show the evolution chain.");
+        lines.push("");
+        return lines.join("\n");
+    }
+    lines.push("");
+    lines.push("  LINEAGE");
+    lines.push("  " + "-".repeat(70));
+    lines.push(`  Generation: ${experiment.lineage.generation}`);
+    lines.push("");
+    // Build the chain
+    const chain = [];
+    for (const ancestorId of experiment.lineage.ancestors) {
+        const ancestor = library.find(e => e.id === ancestorId);
+        if (ancestor) {
+            chain.push({
+                id: ancestor.id,
+                stability: ancestor.metrics.stability,
+                effectiveness: ancestor.metrics.effectiveness,
+            });
+        }
+    }
+    chain.push({
+        id: experiment.id,
+        stability: experiment.metrics.stability,
+        effectiveness: experiment.metrics.effectiveness,
+    });
+    // Format as arrow chain
+    for (let i = 0; i < chain.length; i++) {
+        const node = chain[i];
+        const isCurrent = i === chain.length - 1;
+        const prefix = isCurrent ? "  → " : "    ";
+        const marker = isCurrent ? " (current)" : "";
+        if (i > 0) {
+            const prev = chain[i - 1];
+            const stabDelta = node.stability - prev.stability;
+            const effDelta = node.effectiveness - prev.effectiveness;
+            const deltaStr = `${stabDelta >= 0 ? "+" : ""}${(stabDelta * 100).toFixed(0)} stab, ${effDelta >= 0 ? "+" : ""}${(effDelta * 100).toFixed(0)} eff`;
+            lines.push(`${prefix}${node.id}${marker} (${deltaStr})`);
+        }
+        else {
+            lines.push(`${prefix}${node.id}${marker} (root)`);
+        }
+        if (i < chain.length - 1) {
+            lines.push("    │");
+        }
+    }
+    if (experiment.lineage.improvementFromParent) {
+        const imp = experiment.lineage.improvementFromParent;
+        lines.push("");
+        lines.push(`  Net from parent: ${imp.stability >= 0 ? "+" : ""}${(imp.stability * 100).toFixed(0)} stability, ${imp.effectiveness >= 0 ? "+" : ""}${(imp.effectiveness * 100).toFixed(0)} effectiveness`);
+        if (experiment.lineage.patchesFromParent.length > 0) {
+            lines.push(`  Patches applied: ${experiment.lineage.patchesFromParent.join(", ")}`);
+        }
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+/**
+ * Assess confidence in insights based on sample size and outcome variance.
+ *
+ * This is critical for trust: the system must never overclaim.
+ *   High   = 7+ experiments, low variance — "consistent, reliable"
+ *   Medium = 3-6 experiments, moderate variance — "emerging pattern"
+ *   Low    = 1-2 experiments, or high variance — "early signal"
+ */
+function assessConfidence(experiments) {
+    const n = experiments.length;
+    if (n < 2) {
+        return { level: "Low", reason: `${n} experiment — early signal, more runs needed`, score: 0.2 };
+    }
+    // Compute stability variance
+    const stabilities = experiments.map(e => e.metrics.stability);
+    const mean = stabilities.reduce((s, v) => s + v, 0) / n;
+    const variance = stabilities.reduce((s, v) => s + (v - mean) ** 2, 0) / n;
+    const stdDev = Math.sqrt(variance);
+    const cv = mean > 0 ? stdDev / mean : 1; // coefficient of variation
+    if (n >= 7 && cv < 0.1) {
+        return { level: "High", reason: `${n} experiments, consistent outcomes`, score: 0.9 };
+    }
+    if (n >= 7 && cv < 0.25) {
+        return { level: "High", reason: `${n} experiments, low variance`, score: 0.8 };
+    }
+    if (n >= 5 && cv < 0.15) {
+        return { level: "High", reason: `${n} experiments, consistent outcomes`, score: 0.85 };
+    }
+    if (n >= 3 && cv < 0.2) {
+        return { level: "Medium", reason: `${n} experiments, moderate consistency`, score: 0.6 };
+    }
+    if (n >= 3) {
+        return { level: "Medium", reason: `${n} experiments, moderate variance`, score: 0.5 };
+    }
+    if (cv > 0.3) {
+        return { level: "Low", reason: `${n} experiments, high variance — outcomes diverge significantly`, score: 0.25 };
+    }
+    return { level: "Low", reason: `${n} experiments — emerging pattern, more runs will increase confidence`, score: 0.3 };
+}
+/**
+ * Find experiments with the same system archetype.
+ * Users benefit from past knowledge instantly — "what worked before?"
+ */
+function formatSimilarExperiments(currentArchetype, currentMetrics, library) {
+    if (!currentArchetype || library.length === 0)
+        return "";
+    const similar = library
+        .filter(e => e.archetype === currentArchetype)
+        .sort((a, b) => b.metrics.stability - a.metrics.stability)
+        .slice(0, 5);
+    if (similar.length === 0)
+        return "";
+    const confidence = assessConfidence(similar);
+    const lines = [];
+    lines.push("");
+    lines.push("  SIMILAR EXPERIMENTS");
+    lines.push("  " + "-".repeat(70));
+    lines.push(`  Other runs with archetype: "${currentArchetype}"`);
+    lines.push(`  Confidence: ${confidence.level} (${confidence.reason})`);
+    lines.push("");
+    for (const exp of similar) {
+        const stabDelta = exp.metrics.stability - currentMetrics.stability;
+        const effDelta = exp.metrics.effectiveness - currentMetrics.effectiveness;
+        const deltaStr = `${stabDelta >= 0 ? "+" : ""}${(stabDelta * 100).toFixed(0)} stab, ${effDelta >= 0 ? "+" : ""}${(effDelta * 100).toFixed(0)} eff vs current`;
+        const label = exp.rulesFile ? exp.rulesFile : exp.id;
+        lines.push(`    → ${label} (${deltaStr})`);
+        if (exp.patchesApplied.length > 0) {
+            lines.push(`      Patches: ${exp.patchesApplied.join(", ")}`);
+        }
+    }
+    if (similar.length > 0) {
+        const best = similar[0];
+        if (best.metrics.stability > currentMetrics.stability) {
+            lines.push("");
+            lines.push(`  Best known result: ${(best.metrics.stability * 100).toFixed(0)}% stability, ${(best.metrics.effectiveness * 100).toFixed(0)}% effectiveness`);
+            lines.push(`  Your current:      ${(currentMetrics.stability * 100).toFixed(0)}% stability, ${(currentMetrics.effectiveness * 100).toFixed(0)}% effectiveness`);
+            const gap = best.metrics.stability - currentMetrics.stability;
+            if (gap > 0.02) {
+                lines.push(`  Gap: ${(gap * 100).toFixed(0)} points. Review ${best.rulesFile ?? best.id} for strategies that worked.`);
+            }
+            else {
+                lines.push("  You're at or near the best known result for this archetype.");
+            }
+        }
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+// ============================================
+// BEST KNOWN STRATEGY — AUTO-SYNTHESIS
+// ============================================
+/**
+ * Synthesize the best known configuration for a system archetype
+ * from the experiment library.
+ *
+ * This is the recommendation engine grounded in evidence:
+ * "For high-volatility systems, the best strategies are X, Y, Z
+ *  with average outcomes of A% stability, B% effectiveness."
+ */
+function formatBestKnownStrategy(currentArchetype, currentMetrics, library) {
+    if (!currentArchetype || library.length < 2)
+        return "";
+    const matching = library.filter(e => e.archetype === currentArchetype);
+    if (matching.length < 2)
+        return "";
+    // Compute averages from top performers (top 50%)
+    const sorted = [...matching].sort((a, b) => b.metrics.stability - a.metrics.stability);
+    const topHalf = sorted.slice(0, Math.max(1, Math.ceil(sorted.length / 2)));
+    const avgStab = topHalf.reduce((s, e) => s + e.metrics.stability, 0) / topHalf.length;
+    const avgEff = topHalf.reduce((s, e) => s + e.metrics.effectiveness, 0) / topHalf.length;
+    const minStab = Math.min(...topHalf.map(e => e.metrics.stability));
+    const maxStab = Math.max(...topHalf.map(e => e.metrics.stability));
+    const minEff = Math.min(...topHalf.map(e => e.metrics.effectiveness));
+    const maxEff = Math.max(...topHalf.map(e => e.metrics.effectiveness));
+    // Extract common patches across top performers
+    const patchCounts = new Map();
+    for (const exp of topHalf) {
+        for (const patch of exp.patchesApplied) {
+            patchCounts.set(patch, (patchCounts.get(patch) ?? 0) + 1);
+        }
+    }
+    const commonPatches = [...patchCounts.entries()]
+        .filter(([, count]) => count >= Math.ceil(topHalf.length * 0.5))
+        .sort((a, b) => b[1] - a[1])
+        .map(([patch]) => patch);
+    const lines = [];
+    lines.push("");
+    // Compute confidence from sample size and outcome variance
+    const confidence = assessConfidence(matching);
+    lines.push("  BEST KNOWN CONFIGURATION");
+    lines.push("  " + "-".repeat(70));
+    lines.push(`  For "${currentArchetype}" systems (${matching.length} experiments)`);
+    lines.push(`  Confidence: ${confidence.level} (${confidence.reason})`);
+    lines.push("");
+    // Show the archetype's successful strategies
+    const archetype = classifyArchetypeByName(currentArchetype);
+    if (archetype) {
+        for (const strategy of archetype.successfulStrategies) {
+            lines.push(`    + ${strategy}`);
+        }
+        lines.push("");
+    }
+    if (commonPatches.length > 0) {
+        lines.push("  Common winning patches:");
+        for (const patch of commonPatches.slice(0, 5)) {
+            const count = patchCounts.get(patch);
+            lines.push(`    + ${patch} (used in ${count}/${topHalf.length} top runs)`);
+        }
+        lines.push("");
+    }
+    lines.push("  Average outcomes (top performers):");
+    lines.push(`    Stability:     ${(minStab * 100).toFixed(0)}–${(maxStab * 100).toFixed(0)}%`);
+    lines.push(`    Effectiveness: ${(minEff * 100).toFixed(0)}–${(maxEff * 100).toFixed(0)}%`);
+    lines.push("");
+    lines.push("  Your current config:");
+    lines.push(`    Stability:     ${(currentMetrics.stability * 100).toFixed(0)}%`);
+    lines.push(`    Effectiveness: ${(currentMetrics.effectiveness * 100).toFixed(0)}%`);
+    // Gap analysis
+    const stabGap = avgStab - currentMetrics.stability;
+    const effGap = avgEff - currentMetrics.effectiveness;
+    if (stabGap > 0.02 && effGap > 0.02) {
+        lines.push(`    → Room to improve: ~+${(stabGap * 100).toFixed(0)} stability, ~+${(effGap * 100).toFixed(0)} effectiveness`);
+    }
+    else if (stabGap > 0.02) {
+        lines.push(`    → Near optimal effectiveness. Stability can improve ~+${(stabGap * 100).toFixed(0)}.`);
+    }
+    else if (effGap > 0.02) {
+        lines.push(`    → Near optimal stability. Effectiveness can improve ~+${(effGap * 100).toFixed(0)}.`);
+    }
+    else {
+        lines.push("    → At or near best known results. Consider stress-testing with harder scenarios.");
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+/**
+ * Look up archetype by name (reverse lookup from classifyArchetype).
+ */
+function classifyArchetypeByName(name) {
+    const archetypes = [
+        {
+            name: "High-volatility system with feedback amplification",
+            description: "",
+            successfulStrategies: [
+                "Conditional gating (halt actions above threshold)",
+                "Volatility dampening (slow large movements)",
+                "Circuit breakers (emergency halt mechanisms)",
+            ],
+            riskPattern: "",
+        },
+        {
+            name: "Coordination failure with polarization dynamics",
+            description: "",
+            successfulStrategies: [
+                "Transparency requirements (report large actions)",
+                "Rebalancing rules (pull extremes toward center)",
+                "Position limits (cap concentration)",
+            ],
+            riskPattern: "",
+        },
+        {
+            name: "Fragile equilibrium under stress",
+            description: "",
+            successfulStrategies: [
+                "Circuit breakers at multiple thresholds",
+                "Liquidity floors (maintain minimums)",
+                "Graduated response (escalating restrictions)",
+            ],
+            riskPattern: "",
+        },
+        {
+            name: "Governance disconnect",
+            description: "",
+            successfulStrategies: [
+                "Stress-test with more extreme scenarios",
+                "Add rules targeting ungoverned variables",
+                "Increase scenario severity to find the rules' breaking point",
+            ],
+            riskPattern: "",
+        },
+        {
+            name: "Hidden coordination risk",
+            description: "",
+            successfulStrategies: [
+                "Transparency requirements (require reporting)",
+                "Correlation monitoring (detect coordinated movements)",
+                "Position diversity requirements",
+            ],
+            riskPattern: "",
+        },
+        {
+            name: "Well-governed adaptive system",
+            description: "",
+            successfulStrategies: [
+                "Fine-tune existing rules (small parameter changes)",
+                "Add monitoring rules to detect drift",
+                "Stress-test with extreme scenarios to find limits",
+            ],
+            riskPattern: "",
+        },
+    ];
+    return archetypes.find(a => a.name === name) ?? null;
+}
+/**
+ * Format multi-patch comparison output.
+ * When users apply multiple patches, show which fix wins on each dimension.
+ */
+function formatMultiPatchComparison(patchResults, baseline) {
+    if (patchResults.length < 2)
+        return "";
+    const lines = [];
+    lines.push("");
+    lines.push("  FIX COMPARISON");
+    lines.push("  " + "-".repeat(70));
+    lines.push("");
+    lines.push("  Fix                     Stability    Effectiveness    Collapse Risk");
+    lines.push("  " + "─".repeat(65));
+    lines.push(`  Baseline (no fix)       ${(baseline.stability * 100).toFixed(0).padStart(4)}%        ${(baseline.effectiveness * 100).toFixed(0).padStart(4)}%             ${(baseline.collapse * 100).toFixed(0).padStart(4)}%`);
+    for (const patch of patchResults) {
+        const stabDelta = patch.stability - baseline.stability;
+        const effDelta = patch.effectiveness - baseline.effectiveness;
+        const label = patch.patchId.padEnd(22);
+        lines.push(`  ${label}  ${(patch.stability * 100).toFixed(0).padStart(4)}%        ${(patch.effectiveness * 100).toFixed(0).padStart(4)}%             ${(patch.collapse * 100).toFixed(0).padStart(4)}%`);
+    }
+    lines.push("");
+    // Find best for each dimension
+    const bestStab = [...patchResults].sort((a, b) => b.stability - a.stability)[0];
+    const bestEff = [...patchResults].sort((a, b) => b.effectiveness - a.effectiveness)[0];
+    const bestCollapse = [...patchResults].sort((a, b) => a.collapse - b.collapse)[0];
+    lines.push("  Recommendation:");
+    if (bestStab.patchId === bestEff.patchId) {
+        lines.push(`    ${bestStab.patchId} wins on both stability and effectiveness. Apply it.`);
+    }
+    else {
+        lines.push(`    ${bestStab.patchId} is better for stability (+${((bestStab.stability - baseline.stability) * 100).toFixed(0)})`);
+        lines.push(`    ${bestEff.patchId} is better for effectiveness (+${((bestEff.effectiveness - baseline.effectiveness) * 100).toFixed(0)})`);
+        if (bestCollapse.patchId !== bestStab.patchId && bestCollapse.patchId !== bestEff.patchId) {
+            lines.push(`    ${bestCollapse.patchId} is best for risk reduction`);
+        }
+        lines.push("    Choose based on your priority: resilience or performance.");
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+/**
+ * Export enforcement report as JSON (for integration / downstream tooling).
+ */
+function exportEnforcementReportJSON(report) {
+    return JSON.stringify(report, null, 2);
+}