playlist-data-engine 1.1.0

package/dist/core/combat/AI/CombatAI.d.ts

@@ -0,0 +1,179 @@
+/**
+ * CombatAI — Decision engine for AI-controlled combatants
+ *
+ * Produces an `AIDecision` for each combatant's turn based on:
+ * 1. Threat assessment (current battlefield state)
+ * 2. Play style (normal vs aggressive)
+ * 3. Available actions (weapons, spells, items, legendary actions)
+ *
+ * The AI is designed to be **deterministic given the same combat state** —
+ * it uses no randomness internally. All randomness comes from the dice roller
+ * when the AICombatRunner executes the decision.
+ */
+import type { Combatant, CombatInstance } from '../../types/Combat';
+import type { AIConfig, AIPlayStyle, AIDecision, AIThreatAssessment } from '../../types/CombatAI';
+import type { Spell } from '../../types/Character';
+/**
+ * Weapon evaluation — internal representation used to compare weapons.
+ */
+interface WeaponEvaluation {
+    name: string;
+    expectedDamage: number;
+    attackBonus: number;
+    type: 'melee' | 'ranged';
+    properties: string[];
+}
+export declare class CombatAI {
+    private config;
+    constructor(config: AIConfig);
+    /**
+     * Get the effective play style for a combatant.
+     * Per-combatant overrides take priority over side defaults.
+     */
+    getStyleForCombatant(combatant: Combatant): AIPlayStyle;
+    /**
+     * Determine which side a combatant belongs to.
+     */
+    getSide(combatant: Combatant): 'player' | 'enemy';
+    /**
+     * Get all living enemies of a given combatant.
+     */
+    getEnemies(combatant: Combatant, combat: CombatInstance): Combatant[];
+    /**
+     * Get all living allies of a given combatant (including self).
+     */
+    getAllies(combatant: Combatant, combat: CombatInstance): Combatant[];
+    /**
+     * Assess the current battlefield state from a combatant's perspective.
+     *
+     * Provides a snapshot of tactical conditions that drive style-dependent
+     * decision-making. Called at the start of each turn.
+     */
+    assessThreat(combatant: Combatant, combat: CombatInstance): AIThreatAssessment;
+    /**
+     * Main decision entry point.
+     *
+     * Evaluates the battlefield, selects the best action based on play style,
+     * and returns an `AIDecision` for the AICombatRunner to execute.
+     */
+    decide(combatant: Combatant, combat: CombatInstance): AIDecision;
+    /**
+     * Decide whether to cast a spell and which one.
+     * Returns null if no spell is worth casting.
+     */
+    private selectSpellAction;
+    /**
+     * Get all spells available to a combatant (cantrips + slotted spells).
+     */
+    getAvailableSpells(combatant: Combatant): Spell[];
+    /**
+     * Check if spell slots are available for a given spell level.
+     */
+    private hasSlotForLevel;
+    /**
+     * Evaluate a spell for decision-making.
+     */
+    private evaluateSpell;
+    /**
+     * Get the best available spell slot level for a spell.
+     */
+    private getBestAvailableSlot;
+    /**
+     * Decide whether the AI should heal this turn.
+     */
+    private shouldHeal;
+    /**
+     * Pick the best healing spell from available options.
+     */
+    private pickHealingSpell;
+    /**
+     * Pick the best target for a healing spell.
+     */
+    private pickHealingTarget;
+    /**
+     * Get all allies that would benefit from a healing spell.
+     */
+    private getHealingTargets;
+    /**
+     * Decide whether to cast a damage spell instead of attacking.
+     */
+    private shouldCastDamageSpell;
+    /**
+     * Pick the best damage spell.
+     */
+    private pickDamageSpell;
+    /**
+     * Calculate total remaining spell slots across all levels.
+     */
+    private totalSlotsRemaining;
+    /**
+     * Pick targets for a spell.
+     */
+    private pickSpellTargets;
+    /**
+     * Decide whether to cast a control spell.
+     */
+    private shouldCastControlSpell;
+    /**
+     * Pick the best target for a buff spell.
+     */
+    private pickBuffTarget;
+    /**
+     * Decide whether to use an item this turn.
+     * Returns null if no item usage is warranted.
+     */
+    private selectItemAction;
+    /**
+     * Decide whether to take a defensive action (dodge/flee).
+     * Returns null if an offensive action is better.
+     */
+    private selectDefensiveAction;
+    /**
+     * Select a weapon attack action.
+     */
+    private selectAttackAction;
+    /**
+     * Select the best target from available enemies.
+     *
+     * **Normal**: target the enemy with the lowest AC (balanced — easiest to hit).
+     * **Aggressive**: target the enemy with the lowest HP (finish them off for action economy).
+     */
+    selectTarget(enemies: Combatant[], style: AIPlayStyle): Combatant;
+    /**
+     * Select the best weapon to attack with.
+     *
+     * Evaluates all equipped weapons + unarmed strike.
+     * **Normal**: balanced (highest expected damage with reasonable hit chance).
+     * **Aggressive**: highest expected damage regardless of hit chance.
+     */
+    selectWeapon(combatant: Combatant, style: AIPlayStyle): WeaponEvaluation;
+    /**
+     * Evaluate all available weapons for a combatant.
+     */
+    private evaluateWeapons;
+    /**
+     * Select a legendary action for a boss combatant.
+     *
+     * Called by AICombatRunner between other combatants' turns.
+     * **Normal**: spread actions across the round, prefer damage actions.
+     * **Aggressive**: use highest-cost damage actions immediately.
+     *
+     * @param boss - The boss combatant with legendary actions
+     * @param combat - The combat instance
+     * @returns An AIDecision with action='legendaryAction', or null if no action should be taken
+     */
+    selectLegendaryAction(boss: Combatant, combat: CombatInstance): AIDecision | null;
+    /**
+     * Calculate the average (expected) damage from a dice formula string.
+     *
+     * Handles simple formulas like "2d6", "2d6+5", "1d8+3", "3d10".
+     * Returns the mathematical expectation.
+     */
+    averageDamageFromFormula(formula: string): number;
+    /**
+     * Check if a combatant is a support archetype (healer/buffer).
+     */
+    isSupportArchetype(combatant: Combatant): boolean;
+}
+export {};
+//# sourceMappingURL=CombatAI.d.ts.map

package/dist/core/combat/AI/CombatAI.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CombatAI.d.ts","sourceRoot":"","sources":["../../../../src/core/combat/AI/CombatAI.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,SAAS,EACT,cAAc,EACf,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EACV,QAAQ,EACR,WAAW,EACX,UAAU,EACV,kBAAkB,EACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAKnD;;GAEG;AACH,UAAU,gBAAgB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,OAAO,GAAG,QAAQ,CAAC;IACzB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAqBD,qBAAa,QAAQ;IACnB,OAAO,CAAC,MAAM,CAAW;gBAEb,MAAM,EAAE,QAAQ;IAI5B;;;OAGG;IACH,oBAAoB,CAAC,SAAS,EAAE,SAAS,GAAG,WAAW;IASvD;;OAEG;IACH,OAAO,CAAC,SAAS,EAAE,SAAS,GAAG,QAAQ,GAAG,OAAO;IAIjD;;OAEG;IACH,UAAU,CAAC,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,GAAG,SAAS,EAAE;IAQrE;;OAEG;IACH,SAAS,CAAC,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,GAAG,SAAS,EAAE;IAQpE;;;;;OAKG;IACH,YAAY,CAAC,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,GAAG,kBAAkB;IAwE9E;;;;;OAKG;IACH,MAAM,CAAC,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,GAAG,UAAU;IA4BhE;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IA6EzB;;OAEG;IACH,kBAAkB,CAAC,SAAS,EAAE,SAAS,GAAG,KAAK,EAAE;IAiBjD;;OAEG;IACH,OAAO,CAAC,eAAe;IAevB;;OAEG;IACH,OAAO,CAAC,aAAa;IAmDrB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAmB5B;;OAEG;IACH,OAAO,CAAC,UAAU;IAUlB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAwBxB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAyBzB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAYzB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IA8B7B;;OAEG;IACH,OAAO,CAAC,eAAe;IAkCvB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAM3B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IA8BxB;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAO9B;;OAEG;IACH,OAAO,CAAC,cAAc;IAYtB;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAuCxB;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAsB7B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAoB1B;;;;;OAKG;IACH,YAAY,CAAC,OAAO,EAAE,SAAS,EAAE,EAAE,KAAK,EAAE,WAAW,GAAG,SAAS;IAsBjE;;;;;;OAMG;IACH,YAAY,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,GAAG,gBAAgB;IA0BxE;;OAEG;IACH,OAAO,CAAC,eAAe;IA6CvB;;;;;;;;;;OAUG;IACH,qBAAqB,CACnB,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,cAAc,GACrB,UAAU,GAAG,IAAI;IAmFpB;;;;;OAKG;IACH,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAmBjD;;OAEG;IACH,kBAAkB,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO;CAWlD"}

package/dist/core/combat/AI/CombatMetricsTracker.d.ts

@@ -0,0 +1,30 @@
+/**
+ * CombatMetricsTracker — Computes per-combatant statistics from combat history
+ *
+ * Analyzes the action log of a completed CombatInstance to produce
+ * CombatantMetrics for every combatant. This is a post-hoc analysis
+ * — it reads the existing history without modifying the engine.
+ *
+ * Used by AICombatRunner after combat completes, and by the Monte Carlo
+ * simulator to aggregate per-combatant performance across many runs.
+ */
+import type { CombatInstance } from '../../types/Combat.js';
+import type { CombatantMetrics } from '../../types/CombatAI.js';
+export declare class CombatMetricsTracker {
+    /**
+     * Compute per-combatant metrics from a completed combat instance.
+     *
+     * Iterates the full action history and tallies damage dealt/taken,
+     * healing, spells, items, criticals, and action counts per combatant.
+     *
+     * @param combat - A completed CombatInstance (isActive should be false)
+     * @returns Map of combatant ID → CombatantMetrics
+     */
+    computeMetrics(combat: CombatInstance): Map<string, CombatantMetrics>;
+    /**
+     * Check if a spell action is a healing spell.
+     * Healing spells target allies and have the 'healing' tag.
+     */
+    private isHealingSpell;
+}
+//# sourceMappingURL=CombatMetricsTracker.d.ts.map

package/dist/core/combat/AI/CombatMetricsTracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CombatMetricsTracker.d.ts","sourceRoot":"","sources":["../../../../src/core/combat/AI/CombatMetricsTracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAgB,MAAM,uBAAuB,CAAC;AAC1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,qBAAa,oBAAoB;IAC/B;;;;;;;;OAQG;IACH,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAwNrE;;;OAGG;IACH,OAAO,CAAC,cAAc;CAKvB"}

package/dist/core/combat/Analysis/BalanceValidator.d.ts

@@ -0,0 +1,170 @@
+/**
+ * BalanceValidator — Validates encounter balance using Monte Carlo simulation results
+ *
+ * Takes simulation results and an intended difficulty, then compares actual player
+ * win rate against expected win rates per difficulty tier. Produces a BalanceReport
+ * with a balance score, variance classification, and actionable recommendations.
+ *
+ * Expected win rates (D&D 5e-inspired):
+ * - Easy: ~90%+ player win rate
+ * - Medium: ~70-80% player win rate
+ * - Hard: ~50-60% player win rate
+ * - Deadly: ~30-40% player win rate
+ *
+ * Usage:
+ * ```ts
+ * const simulator = new CombatSimulator();
+ * const results = simulator.run(party, enemies, config);
+ * const validator = new BalanceValidator();
+ * const report = validator.validate(results, 'medium');
+ * console.log(report.balanceScore);       // 0-100
+ * console.log(report.difficultyVariance);  // 'balanced' | 'underpowered' | 'overpowered'
+ * ```
+ */
+import type { CharacterSheet } from '../../types/Character.js';
+import type { EncounterDifficulty } from '../../types/Enemy.js';
+import type { SimulationConfig, SimulationResults } from '../Simulation/CombatSimulator.js';
+/**
+ * Variance classification — how the actual difficulty compares to intended.
+ */
+export type DifficultyVariance = 'underpowered' | 'balanced' | 'overpowered';
+/**
+ * A single actionable recommendation for adjusting encounter balance.
+ */
+export interface BalanceRecommendation {
+    /** Human-readable description of the suggested change */
+    description: string;
+    /** Expected impact on win rate (e.g., '+5-10% player win rate') */
+    expectedImpact: string;
+    /** Confidence level for this recommendation (0-1, based on run count) */
+    confidence: number;
+}
+/**
+ * Complete balance analysis report from validating an encounter.
+ */
+export interface BalanceReport {
+    /** The difficulty the encounter was designed for */
+    intendedDifficulty: EncounterDifficulty;
+    /** The difficulty the simulation data actually reflects */
+    actualDifficulty: EncounterDifficulty;
+    /** How well actual matches intended (0-100, 100 = perfect) */
+    balanceScore: number;
+    /** Actual player win rate from simulation */
+    playerWinRate: number;
+    /** Expected win rate range for the intended difficulty */
+    expectedWinRate: {
+        min: number;
+        max: number;
+    };
+    /** Whether encounter is underpowered, balanced, or overpowered */
+    difficultyVariance: DifficultyVariance;
+    /** Statistical confidence based on run count (0-1) */
+    confidence: number;
+    /** Actionable suggestions for improving balance */
+    recommendations: BalanceRecommendation[];
+    /** Average HP remaining for players on winning runs (0-100) */
+    averagePlayerHPPercentRemaining: number;
+    /** Total simulation runs used for this analysis */
+    totalRuns: number;
+}
+/**
+ * Expected player win rate ranges per encounter difficulty tier.
+ *
+ * These are D&D 5e-inspired targets:
+ * - Easy: party should almost always win (~90%+)
+ * - Medium: comfortable but not trivial (~70-80%)
+ * - Hard: challenging, real risk of death (~50-60%)
+ * - Deadly: likely TPK, major achievement to win (~30-40%)
+ *
+ * Tunable — adjust these values to change what "balanced" means for your game.
+ */
+export declare const EXPECTED_WIN_RATES: Record<EncounterDifficulty, {
+    min: number;
+    max: number;
+}>;
+/**
+ * BalanceValidator — Analyzes simulation results to assess encounter balance.
+ *
+ * Stateless between calls. Each `validate()` or `validateFromSimulation()`
+ * call produces an independent BalanceReport.
+ */
+export declare class BalanceValidator {
+    /**
+     * Validate an encounter by running simulations and analyzing results.
+     *
+     * Convenience method that combines CombatSimulator.run() + validate().
+     * Use this when you don't already have simulation results.
+     *
+     * @param players - Player character sheets
+     * @param enemies - Enemy character sheets
+     * @param intendedDifficulty - The difficulty the encounter is designed for
+     * @param config - Simulation configuration (run count, seed, AI styles)
+     * @returns Complete balance analysis report
+     */
+    validate(players: CharacterSheet[], enemies: CharacterSheet[], intendedDifficulty: EncounterDifficulty, config: SimulationConfig): BalanceReport;
+    /**
+     * Analyze existing simulation results to produce a balance report.
+     *
+     * Use this when you already have simulation results and want to evaluate
+     * them against a target difficulty.
+     *
+     * @param results - Simulation results from CombatSimulator.run()
+     * @param intendedDifficulty - The difficulty the encounter was designed for
+     * @returns Complete balance analysis report
+     */
+    analyze(results: SimulationResults, intendedDifficulty: EncounterDifficulty): BalanceReport;
+    /**
+     * Classify what difficulty tier a given win rate falls into.
+     *
+     * Maps win rate to the closest matching difficulty tier:
+     * - >= 90% → easy
+     * - >= 70% → medium
+     * - >= 50% → hard
+     * - < 50% → deadly
+     */
+    private classifyDifficulty;
+    /**
+     * Calculate a balance score (0-100) comparing actual win rate to expected range.
+     *
+     * Score calculation:
+     * - If win rate is within the expected range: 100 - distance from midpoint
+     * - If win rate is outside the expected range: penalty proportional to distance
+     *
+     * A perfect score of 100 means the win rate exactly hits the midpoint of the
+     * expected range. Scores decrease as the actual win rate deviates.
+     *
+     * The score also factors in HP remaining — a 100% win rate with 1 HP left
+     * is different from 100% with full HP. This adjusts the score by up to 10 points.
+     */
+    private calculateBalanceScore;
+    /**
+     * Classify the difficulty variance based on win rate vs expected range.
+     *
+     * - Win rate within expected range → balanced
+     * - Win rate above expected range → underpowered (encounter too easy)
+     * - Win rate below expected range → overpowered (encounter too hard)
+     */
+    private classifyVariance;
+    /**
+     * Calculate statistical confidence based on run count.
+     *
+     * More runs = higher confidence in the results.
+     * Uses a power curve: 1 - 1 / sqrt(n)
+     * - 100 runs → ~0.90 confidence
+     * - 500 runs → ~0.96 confidence
+     * - 1000 runs → ~0.97 confidence
+     * - 2000 runs → ~0.98 confidence
+     * - 5000 runs → ~0.99 confidence
+     */
+    private calculateConfidence;
+    /**
+     * Generate actionable recommendations for improving encounter balance.
+     *
+     * Recommendations are context-aware:
+     * - If overpowered (too hard): suggest reducing enemy strength
+     * - If underpowered (too easy): suggest increasing enemy strength
+     * - If balanced: suggest tuning for HP remaining
+     */
+    private generateRecommendations;
+}
+//# sourceMappingURL=BalanceValidator.d.ts.map

package/dist/core/combat/Analysis/BalanceValidator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BalanceValidator.d.ts","sourceRoot":"","sources":["../../../../src/core/combat/Analysis/BalanceValidator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAG/D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAK5F;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,cAAc,GAAG,UAAU,GAAG,aAAa,CAAC;AAE7E;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,cAAc,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,oDAAoD;IACpD,kBAAkB,EAAE,mBAAmB,CAAC;IACxC,2DAA2D;IAC3D,gBAAgB,EAAE,mBAAmB,CAAC;IACtC,8DAA8D;IAC9D,YAAY,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,aAAa,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,eAAe,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,kEAAkE;IAClE,kBAAkB,EAAE,kBAAkB,CAAC;IACvC,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,eAAe,EAAE,qBAAqB,EAAE,CAAC;IACzC,+DAA+D;IAC/D,+BAA+B,EAAE,MAAM,CAAC;IACxC,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;CACnB;AAID;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,mBAAmB,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAKxF,CAAC;AAIF;;;;;GAKG;AACH,qBAAa,gBAAgB;IAC3B;;;;;;;;;;;OAWG;IACH,QAAQ,CACN,OAAO,EAAE,cAAc,EAAE,EACzB,OAAO,EAAE,cAAc,EAAE,EACzB,kBAAkB,EAAE,mBAAmB,EACvC,MAAM,EAAE,gBAAgB,GACvB,aAAa;IAMhB;;;;;;;;;OASG;IACH,OAAO,CACL,OAAO,EAAE,iBAAiB,EAC1B,kBAAkB,EAAE,mBAAmB,GACtC,aAAa;IAyChB;;;;;;;;OAQG;IACH,OAAO,CAAC,kBAAkB;IAO1B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,qBAAqB;IA2B7B;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;IASxB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,mBAAmB;IAM3B;;;;;;;OAOG;IACH,OAAO,CAAC,uBAAuB;CA0GhC"}

package/dist/core/combat/Analysis/ComparativeAnalyzer.d.ts

@@ -0,0 +1,231 @@
+/**
+ * ComparativeAnalyzer — Compare two encounter configurations using
+ * identical-seed simulation to isolate the effect of a single variable.
+ *
+ * Answers questions like: "How much does +2 AC improve win rate?" or
+ * "Is adding a 5th party member statistically significant?"
+ *
+ * Both configurations are simulated with the same sequence of seeds,
+ * enabling pair-wise comparison where each seed-pair isolates the
+ * variable being tested (dice rolls are identical, only the config differs).
+ *
+ * Usage:
+ * ```ts
+ * const analyzer = new ComparativeAnalyzer();
+ * const comparison = analyzer.compare(
+ *   { players, enemies: enemiesA, ... },
+ *   { players, enemies: enemiesB, ... },
+ *   { runCount: 500, baseSeed: 'ac-comparison', aiConfig: { playerStyle: 'normal', enemyStyle: 'aggressive' } }
+ * );
+ * console.log(comparison.winRateDelta);       // e.g., +0.15
+ * console.log(comparison.isStatisticallySignificant); // true
+ * ```
+ */
+import type { CharacterSheet } from '../../types/Character.js';
+import type { AIConfig } from '../../types/CombatAI.js';
+import type { SimulationResults, SimulationSummary } from '../Simulation/CombatSimulator.js';
+/**
+ * Configuration for one side of a comparative analysis.
+ *
+ * Defines the party, enemies, and any simulation overrides for one
+ * of the two configurations being compared.
+ */
+export interface ComparisonConfig {
+    /** Player character sheets */
+    players: CharacterSheet[];
+    /** Enemy character sheets */
+    enemies: CharacterSheet[];
+    /** Optional label for this configuration (e.g., "Base", "+2 AC") */
+    label?: string;
+    /** Optional combat config override (max turns, flee, etc.) */
+    combatConfig?: import('../../types/Combat.js').CombatConfig;
+}
+/**
+ * Options for the comparative analysis.
+ */
+export interface ComparisonOptions {
+    /** Number of simulations per configuration */
+    runCount: number;
+    /** Base seed — both configs use the same seed sequence for fair comparison */
+    baseSeed: string;
+    /** AI configuration for all simulations */
+    aiConfig: AIConfig;
+    /** Optional combat engine configuration */
+    combatConfig?: import('../../types/Combat.js').CombatConfig;
+    /**
+     * Significance threshold (alpha) for statistical tests.
+     * Default: 0.05 (95% confidence).
+     */
+    significanceThreshold?: number;
+    /** AbortSignal for cancellation */
+    abortSignal?: AbortSignal;
+    /** Progress callback: (completedPerSide, totalPerSide, sideLabel) */
+    onProgress?: (completed: number, total: number, side: string) => void;
+}
+/**
+ * Delta metrics between two configurations.
+ *
+ * Positive values favor config A (A is better for players).
+ * Negative values favor config B (B is better for players).
+ */
+export interface DeltaMetrics {
+    /** Win rate difference: A.winRate - B.winRate (e.g., +0.15 means A wins 15% more) */
+    winRateDelta: number;
+    /** Average rounds difference: A.avgRounds - B.avgRounds */
+    averageRoundsDelta: number;
+    /** Average player HP remaining difference: A.hpRemaining - B.hpRemaining */
+    averageHPRemainingDelta: number;
+    /** Total player deaths difference: A.deaths - B.deaths (negative = fewer deaths in A) */
+    totalPlayerDeathsDelta: number;
+    /** Total enemy deaths difference: A.enemyDeaths - B.enemyDeaths */
+    totalEnemyDeathsDelta: number;
+    /** Median rounds difference */
+    medianRoundsDelta: number;
+}
+/**
+ * Per-combatant delta between two configurations.
+ */
+export interface CombatantDelta {
+    /** Combatant name (from config A) */
+    name: string;
+    /** Which side this combatant is on */
+    side: 'player' | 'enemy';
+    /** DPR difference: A.DPR - B.DPR */
+    dprDelta: number;
+    /** Average total damage dealt difference */
+    damageDealtDelta: number;
+    /** Average total damage taken difference */
+    damageTakenDelta: number;
+    /** Survival rate difference */
+    survivalRateDelta: number;
+    /** Kill rate difference */
+    killRateDelta: number;
+    /** Critical hit rate difference */
+    criticalHitRateDelta: number;
+    /** Average healing done difference */
+    healingDoneDelta: number;
+}
+/**
+ * Result of a statistical significance test.
+ */
+export interface SignificanceResult {
+    /** Whether the difference is statistically significant at the given threshold */
+    isSignificant: boolean;
+    /** The p-value from the test (approximation) */
+    pValue: number;
+    /** The significance threshold used (alpha) */
+    threshold: number;
+    /** Human-readable interpretation */
+    interpretation: string;
+}
+/**
+ * Complete comparison result between two encounter configurations.
+ */
+export interface ComparisonResult {
+    /** Label for configuration A (or "Config A" if not provided) */
+    labelA: string;
+    /** Label for configuration B (or "Config B" if not provided) */
+    labelB: string;
+    /** Full simulation results for configuration A */
+    resultsA: SimulationResults;
+    /** Full simulation results for configuration B */
+    resultsB: SimulationResults;
+    /** Summary for configuration A */
+    summaryA: SimulationSummary;
+    /** Summary for configuration B */
+    summaryB: SimulationSummary;
+    /** Delta metrics (positive = A is better for players) */
+    deltas: DeltaMetrics;
+    /** Per-combatant deltas (matched by combatant index, not ID) */
+    combatantDeltas: CombatantDelta[];
+    /** Statistical significance of the win rate difference */
+    winRateSignificance: SignificanceResult;
+    /** Was the comparison cancelled before completion? */
+    wasCancelled: boolean;
+}
+/**
+ * ComparativeAnalyzer — Compares two encounter configurations using
+ * identical-seed simulation.
+ *
+ * Both configurations are simulated with the same sequence of seeds,
+ * ensuring that dice roll variance is eliminated. The only difference
+ * in outcomes comes from the configuration change itself.
+ *
+ * This enables pair-wise comparison: for each seed, config A and config B
+ * experience the exact same dice rolls, so any outcome difference is
+ * attributable to the config change.
+ *
+ * Stateless between `compare()` calls.
+ */
+export declare class ComparativeAnalyzer {
+    /**
+     * Compare two encounter configurations using identical-seed simulation.
+     *
+     * @param configA - First configuration (baseline)
+     * @param configB - Second configuration (modified)
+     * @param options - Simulation and comparison options
+     * @returns Full comparison result with deltas and significance
+     */
+    compare(configA: ComparisonConfig, configB: ComparisonConfig, options: ComparisonOptions): ComparisonResult;
+    /**
+     * Run simulations for a single configuration.
+     */
+    private runSimulations;
+    /**
+     * Calculate delta metrics between two simulation summaries.
+     *
+     * Positive delta = config A is better for players (higher win rate,
+     * fewer deaths, more HP remaining).
+     */
+    private calculateDeltas;
+    /**
+     * Calculate per-combatant deltas between two simulation results.
+     *
+     * Matches combatants by side and index position (not ID), since
+     * the two configs may have different combatant IDs.
+     */
+    private calculateCombatantDeltas;
+    /**
+     * Get metrics sorted by side, preserving insertion order.
+     */
+    private getMetricsBySide;
+    /**
+     * Create a CombatantDelta from two metrics entries (either may be null).
+     */
+    private makeCombatantDelta;
+    /**
+     * Test whether the win rate difference between two configurations is
+     * statistically significant.
+     *
+     * Uses a normal approximation for the difference of two proportions:
+     * - pA = win rate of config A (proportion of wins)
+     * - pB = win rate of config B
+     * - n = number of runs per config (assumed equal)
+     *
+     * Standard error of the difference: SE = sqrt(pA*(1-pA)/n + pB*(1-pB)/n)
+     * Z-score: Z = (pA - pB) / SE
+     * P-value: 2 * (1 - Φ(|Z|)) for two-tailed test
+     *
+     * For small samples (n < 30), falls back to a conservative check:
+     * the difference must exceed a minimum detectable effect threshold.
+     */
+    private testSignificance;
+    /**
+     * Calculate two-tailed p-value from a Z-score using an approximation
+     * of the standard normal cumulative distribution.
+     *
+     * Uses the Abramowitz and Stegun approximation (maximum error: 7.5e-8).
+     */
+    private twoTailedPValue;
+    /**
+     * Standard normal CDF using the Abramowitz and Stegun approximation.
+     *
+     * Maximum error: 7.5e-8. Valid for z >= 0.
+     */
+    private normalCDF;
+    /**
+     * Round to 4 decimal places for clean output.
+     */
+    private round;
+}
+//# sourceMappingURL=ComparativeAnalyzer.d.ts.map

package/dist/core/combat/Analysis/ComparativeAnalyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ComparativeAnalyzer.d.ts","sourceRoot":"","sources":["../../../../src/core/combat/Analysis/ComparativeAnalyzer.ts"],"names":[],"mappings":"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"}