@samsmith2121/synthetic-leverage-engine 0.1.0

package/dist/src/analysis.js

@@ -0,0 +1,843 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runStrategyComparison = runStrategyComparison;
+exports.runParameterSweep = runParameterSweep;
+exports.runScenarioAnalysis = runScenarioAnalysis;
+exports.buildRollingWindowScenarios = buildRollingWindowScenarios;
+exports.runOneWaySensitivity = runOneWaySensitivity;
+exports.runTwoWaySensitivity = runTwoWaySensitivity;
+exports.buildResearchSummaries = buildResearchSummaries;
+exports.rankStrategyRuns = rankStrategyRuns;
+exports.buildStrategyDiagnostics = buildStrategyDiagnostics;
+const backtest_1 = require("./backtest");
+const metrics_1 = require("./metrics");
+const EPSILON = 1e-12;
+function runStrategyComparison(days, baseConfig, variants, rankBy = 'twrCagr') {
+    const runs = variants.map((variant) => runSingleStrategy(days, baseConfig, variant));
+    return {
+        runs,
+        ranking: rankStrategyRuns(runs, rankBy),
+    };
+}
+function runParameterSweep(days, baseConfig, grid, config = {}) {
+    const monteCarloBlockLengths = grid.monteCarloBlockLengths && grid.monteCarloBlockLengths.length > 0
+        ? grid.monteCarloBlockLengths
+        : [undefined];
+    const rows = [];
+    for (const vixThreshold of grid.vixThresholds) {
+        for (const leverageMultiple of grid.leverageMultiples) {
+            for (const tradeSpread of grid.tradeSpreads) {
+                for (const expenseRatioAnnual of grid.expenseRatiosAnnual) {
+                    for (const cashMode of grid.cashModes) {
+                        for (const cashYieldDaily of grid.cashYieldDailyValues) {
+                            for (const monteCarloBlockLength of monteCarloBlockLengths) {
+                                const strategyName = [
+                                    config.baseVariantName ?? 'sweep',
+                                    `vix${vixThreshold}`,
+                                    `lev${leverageMultiple}`,
+                                    `spr${tradeSpread}`,
+                                    `er${expenseRatioAnnual}`,
+                                    `cash${cashMode}`,
+                                    `yld${cashYieldDaily}`,
+                                    `blk${monteCarloBlockLength ?? 'na'}`,
+                                ].join('__');
+                                const variant = {
+                                    name: strategyName,
+                                    signal: {
+                                        vixThreshold,
+                                        leverageMultiple,
+                                    },
+                                    tradeSpread,
+                                    expenseRatioAnnual,
+                                    cashMode,
+                                    cashYieldDaily,
+                                    monteCarloBlockLength,
+                                };
+                                const run = runSingleStrategy(days, baseConfig, variant);
+                                if (config.monteCarloConfig && monteCarloBlockLength !== undefined && run.ok) {
+                                    try {
+                                        (0, backtest_1.runMonteCarloBacktest)(days, mergeEngineConfig(baseConfig, variant), {
+                                            ...config.monteCarloConfig,
+                                            blockLength: monteCarloBlockLength,
+                                        });
+                                    }
+                                    catch (error) {
+                                        run.warnings.push({
+                                            code: 'MONTE_CARLO_BLOCK_TOO_LONG',
+                                            message: error instanceof Error ? error.message : 'monte carlo validation failed',
+                                            context: {
+                                                blockLength: monteCarloBlockLength,
+                                                sourceLength: days.length,
+                                            },
+                                        });
+                                    }
+                                }
+                                rows.push({
+                                    strategyName,
+                                    vixThreshold,
+                                    leverageMultiple,
+                                    tradeSpread,
+                                    expenseRatioAnnual,
+                                    cashMode,
+                                    cashYieldDaily,
+                                    monteCarloBlockLength,
+                                    run,
+                                });
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return {
+        rows,
+        ranking: rankStrategyRuns(rows.map((r) => r.run), config.rankBy ?? 'twrCagr'),
+    };
+}
+function runScenarioAnalysis(days, baseConfig, variant, scenarios, includeFullPeriod = true) {
+    const rows = [];
+    if (includeFullPeriod) {
+        const fullRun = runSingleStrategy(days, baseConfig, { ...variant, name: `${variant.name}__full_period` });
+        rows.push({
+            scenarioName: 'full_period',
+            startDate: days[0]?.date ?? '',
+            endDate: days[days.length - 1]?.date ?? '',
+            run: fullRun,
+            warnings: [...fullRun.warnings, ...buildScenarioWarnings(days)],
+        });
+    }
+    for (const scenario of scenarios) {
+        const sliced = sliceDaysByDate(days, scenario.startDate, scenario.endDate);
+        if (!sliced.ok) {
+            const warning = {
+                code: 'SWEEP_VALIDATION_FAILED',
+                message: sliced.error,
+                context: { scenarioName: scenario.name },
+            };
+            rows.push({
+                scenarioName: scenario.name,
+                startDate: scenario.startDate,
+                endDate: scenario.endDate,
+                run: {
+                    ok: false,
+                    strategy: variant,
+                    error: sliced.error,
+                    warnings: [warning],
+                },
+                warnings: [warning],
+            });
+            continue;
+        }
+        const run = runSingleStrategy(sliced.days, baseConfig, { ...variant, name: `${variant.name}__${scenario.name}` });
+        rows.push({
+            scenarioName: scenario.name,
+            startDate: scenario.startDate,
+            endDate: scenario.endDate,
+            run,
+            warnings: [...run.warnings, ...buildScenarioWarnings(sliced.days)],
+        });
+    }
+    return { rows };
+}
+function buildRollingWindowScenarios(days, windowLengthDays, stepDays) {
+    if (!Number.isInteger(windowLengthDays) || windowLengthDays <= 0) {
+        throw new Error('windowLengthDays must be a positive integer');
+    }
+    if (!Number.isInteger(stepDays) || stepDays <= 0) {
+        throw new Error('stepDays must be a positive integer');
+    }
+    const scenarios = [];
+    for (let i = 0; i + windowLengthDays - 1 < days.length; i += stepDays) {
+        const startDate = days[i].date;
+        const endDate = days[i + windowLengthDays - 1].date;
+        scenarios.push({
+            name: `rolling_${startDate}_${endDate}`,
+            startDate,
+            endDate,
+        });
+    }
+    return scenarios;
+}
+function runOneWaySensitivity(days, baseConfig, baseVariant, parameter, values, rankBy = 'twrCagr') {
+    const rows = values.map((value) => {
+        const variant = applySensitivityValue(baseVariant, parameter, value);
+        return {
+            parameter,
+            parameterValue: value,
+            run: runSingleStrategy(days, baseConfig, variant),
+        };
+    });
+    return {
+        parameter,
+        rows,
+        ranking: rankStrategyRuns(rows.map((row) => row.run), rankBy),
+    };
+}
+function runTwoWaySensitivity(days, baseConfig, baseVariant, xParameter, xValues, yParameter, yValues, rankBy = 'twrCagr') {
+    if (xParameter === yParameter) {
+        throw new Error('xParameter and yParameter must differ');
+    }
+    const cells = [];
+    for (const xValue of xValues) {
+        for (const yValue of yValues) {
+            const xVariant = applySensitivityValue(baseVariant, xParameter, xValue);
+            const variant = applySensitivityValue(xVariant, yParameter, yValue);
+            cells.push({
+                xParameter,
+                xValue,
+                yParameter,
+                yValue,
+                run: runSingleStrategy(days, baseConfig, variant),
+            });
+        }
+    }
+    return {
+        xParameter,
+        yParameter,
+        xValues,
+        yValues,
+        cells,
+        ranking: rankStrategyRuns(cells.map((cell) => cell.run), rankBy),
+    };
+}
+function buildResearchSummaries(comparison, scenarioResult, options = {}) {
+    const summaries = [];
+    const successfulRuns = comparison.runs.filter((run) => run.ok);
+    const byTradeoff = [...successfulRuns]
+        .filter((run) => run.summary.maxDrawdown > 0 && run.summary.twrCagr !== null)
+        .sort((a, b) => compareByMetric(a.summary, b.summary, 'returnToDrawdown'))[0];
+    if (byTradeoff) {
+        summaries.push({
+            kind: 'best_growth_drawdown_tradeoff',
+            strategyName: byTradeoff.strategy.name,
+            rationale: 'Highest TWR CAGR to max drawdown ratio among successful runs.',
+            metrics: {
+                twrCagr: byTradeoff.summary.twrCagr,
+                maxDrawdown: byTradeoff.summary.maxDrawdown,
+                returnToDrawdown: safeReturnToDrawdown(byTradeoff.summary),
+            },
+        });
+    }
+    const drawdownLimit = options.maxDrawdownConstraint;
+    if (drawdownLimit !== undefined) {
+        const constrained = [...successfulRuns]
+            .filter((run) => run.summary.twrCagr !== null && run.summary.maxDrawdown <= drawdownLimit)
+            .sort((a, b) => compareByMetric(a.summary, b.summary, 'twrCagr'))[0];
+        if (constrained) {
+            summaries.push({
+                kind: 'highest_twr_under_drawdown_constraint',
+                strategyName: constrained.strategy.name,
+                rationale: 'Highest TWR CAGR among variants meeting configured max drawdown constraint.',
+                metrics: {
+                    twrCagr: constrained.summary.twrCagr,
+                    maxDrawdown: constrained.summary.maxDrawdown,
+                    constraint: drawdownLimit,
+                },
+            });
+        }
+    }
+    const lowestCost = [...successfulRuns].sort((a, b) => {
+        const aCost = a.summary.totalTradeCost + a.summary.totalBorrowCost + a.summary.totalErCost;
+        const bCost = b.summary.totalTradeCost + b.summary.totalBorrowCost + b.summary.totalErCost;
+        if (Math.abs(aCost - bCost) <= EPSILON) {
+            return a.strategy.name.localeCompare(b.strategy.name);
+        }
+        return aCost - bCost;
+    })[0];
+    if (lowestCost) {
+        const totalCost = lowestCost.summary.totalTradeCost + lowestCost.summary.totalBorrowCost + lowestCost.summary.totalErCost;
+        summaries.push({
+            kind: 'lowest_cost',
+            strategyName: lowestCost.strategy.name,
+            rationale: 'Lowest total explicit implementation cost among successful runs.',
+            metrics: {
+                totalCost,
+                tradeCost: lowestCost.summary.totalTradeCost,
+                borrowCost: lowestCost.summary.totalBorrowCost,
+                erCost: lowestCost.summary.totalErCost,
+            },
+        });
+    }
+    const bestBenchmark = [...successfulRuns]
+        .filter((run) => run.summary.benchmark?.excessTwrCagr !== null && run.summary.benchmark?.excessTwrCagr !== undefined)
+        .sort((a, b) => compareByMetric(a.summary, b.summary, 'excessTwrCagr'))[0];
+    if (bestBenchmark) {
+        summaries.push({
+            kind: 'most_benchmark_outperforming',
+            strategyName: bestBenchmark.strategy.name,
+            rationale: 'Highest excess TWR CAGR over benchmark on matched dates.',
+            metrics: {
+                excessTwrCagr: bestBenchmark.summary.benchmark?.excessTwrCagr ?? null,
+                benchmarkTwrCagr: bestBenchmark.summary.benchmark?.benchmarkTwrCagr ?? null,
+            },
+        });
+    }
+    if (scenarioResult) {
+        const robust = pickMostRobustScenarioVariant(scenarioResult);
+        if (robust) {
+            summaries.push(robust);
+        }
+    }
+    return summaries;
+}
+function rankStrategyRuns(runs, metric) {
+    const successes = runs.filter((r) => r.ok);
+    const sorted = [...successes].sort((a, b) => compareByMetric(a.summary, b.summary, metric));
+    return sorted.map((run, index) => ({
+        strategyName: run.strategy.name,
+        metric,
+        rank: index + 1,
+        value: getMetricValue(run.summary, metric),
+    }));
+}
+function runSingleStrategy(days, baseConfig, variant) {
+    try {
+        validateVariant(variant, baseConfig);
+        const adjustedDays = applyVariantToDays(days, variant);
+        const config = mergeEngineConfig(baseConfig, variant);
+        const backtest = (0, backtest_1.runFixedBacktest)(adjustedDays, config);
+        const summary = summarizeAnalysisRun(variant.name, config.initialEquity, backtest);
+        return {
+            ok: true,
+            strategy: variant,
+            summary,
+            warnings: collectRunWarnings(adjustedDays, variant, summary),
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'unknown error';
+        return {
+            ok: false,
+            strategy: variant,
+            error: message,
+            warnings: [
+                {
+                    code: 'SWEEP_VALIDATION_FAILED',
+                    message,
+                    context: { strategyName: variant.name },
+                },
+            ],
+        };
+    }
+}
+function summarizeAnalysisRun(strategyName, initialEquity, backtest) {
+    const dailyReturns = backtest.daily.map((d) => d.capitalBaseBeforeReturn === 0 ? 0 : d.equityEnd / d.capitalBaseBeforeReturn - 1);
+    const totalInvested = initialEquity + backtest.daily.reduce((acc, day) => acc + day.contribution, 0);
+    const cashFlows = buildCashFlows(backtest.daily, initialEquity);
+    const benchmark = summarizeBenchmark(backtest.benchmark, backtest.maxDrawdown);
+    return {
+        strategyName,
+        finalEquity: backtest.finalEquity,
+        totalInvested,
+        twrCagr: backtest.twrCagr,
+        xirr: (0, metrics_1.computeXirr)(cashFlows),
+        maxDrawdown: backtest.maxDrawdown,
+        volatility: (0, metrics_1.computeVolatilityFromReturns)(dailyReturns),
+        totalTradeCost: backtest.daily.reduce((acc, d) => acc + d.tradeCost, 0),
+        totalBorrowCost: backtest.daily.reduce((acc, d) => acc + d.borrowDrag, 0),
+        totalErCost: backtest.daily.reduce((acc, d) => acc + d.expenseDrag, 0),
+        totalSwitches: countSwitches(backtest),
+        diagnostics: buildStrategyDiagnostics(backtest, totalInvested),
+        ...(benchmark ? { benchmark } : {}),
+    };
+}
+function buildStrategyDiagnostics(backtest, totalInvested) {
+    const daily = backtest.daily;
+    const exposure = buildExposureDiagnostics(daily);
+    const transitions = buildTransitionDiagnostics(daily);
+    const costs = buildCostDiagnostics(daily, backtest.finalEquity, totalInvested);
+    const drawdown = buildDrawdownDiagnostics(daily);
+    const benchmarkRelative = buildBenchmarkRelativeDiagnostics(backtest.benchmark);
+    return {
+        exposure,
+        transitions,
+        costs,
+        drawdown,
+        ...(benchmarkRelative ? { benchmarkRelative } : {}),
+    };
+}
+function summarizeBenchmark(benchmark, strategyMaxDrawdown) {
+    if (!benchmark) {
+        return undefined;
+    }
+    return {
+        benchmarkTotalReturn: benchmark.benchmarkTotalReturn,
+        benchmarkTwrCagr: benchmark.benchmarkTwrCagr,
+        benchmarkVolatility: benchmark.benchmarkVolatility,
+        benchmarkMaxDrawdown: benchmark.benchmarkMaxDrawdown,
+        excessTotalReturn: benchmark.excessTotalReturn,
+        excessTwrCagr: benchmark.excessTwrCagr,
+        trackingError: benchmark.trackingError,
+        relativeMaxDrawdown: strategyMaxDrawdown - benchmark.benchmarkMaxDrawdown,
+    };
+}
+function countSwitches(backtest) {
+    return backtest.daily.reduce((count, day) => count + (Math.abs(day.appliedPosition - day.priorAppliedPosition) > EPSILON ? 1 : 0), 0);
+}
+function buildCashFlows(daily, initialEquity) {
+    if (daily.length === 0) {
+        return [];
+    }
+    const flows = [{ date: daily[0].date, amount: -initialEquity }];
+    for (const day of daily) {
+        if (day.contribution !== 0) {
+            flows.push({ date: day.date, amount: -day.contribution });
+        }
+    }
+    flows.push({ date: daily[daily.length - 1].date, amount: daily[daily.length - 1].equityEnd });
+    return flows;
+}
+function compareByMetric(a, b, metric) {
+    const aValue = getMetricValue(a, metric);
+    const bValue = getMetricValue(b, metric);
+    if (aValue === null && bValue === null) {
+        return a.strategyName.localeCompare(b.strategyName);
+    }
+    if (aValue === null) {
+        return 1;
+    }
+    if (bValue === null) {
+        return -1;
+    }
+    if (metric === 'maxDrawdown' || metric === 'volatility') {
+        if (Math.abs(aValue - bValue) <= EPSILON) {
+            return a.strategyName.localeCompare(b.strategyName);
+        }
+        return aValue - bValue;
+    }
+    if (Math.abs(aValue - bValue) <= EPSILON) {
+        return a.strategyName.localeCompare(b.strategyName);
+    }
+    return bValue - aValue;
+}
+function getMetricValue(summary, metric) {
+    switch (metric) {
+        case 'twrCagr':
+            return summary.twrCagr;
+        case 'xirr':
+            return summary.xirr;
+        case 'maxDrawdown':
+            return summary.maxDrawdown;
+        case 'volatility':
+            return summary.volatility;
+        case 'excessTwrCagr':
+            return summary.benchmark?.excessTwrCagr ?? null;
+        case 'returnToDrawdown':
+            return safeReturnToDrawdown(summary);
+        default:
+            return null;
+    }
+}
+function safeReturnToDrawdown(summary) {
+    if (summary.twrCagr === null || summary.maxDrawdown <= 0) {
+        return null;
+    }
+    return summary.twrCagr / summary.maxDrawdown;
+}
+function validateVariant(variant, baseConfig) {
+    if (variant.signal && Math.abs(variant.signal.leverageMultiple) > baseConfig.maxLeverage) {
+        throw new Error('signal leverageMultiple exceeds maxLeverage');
+    }
+    if (variant.cashMode === 'configured_yield' && variant.cashYieldDaily === undefined) {
+        throw new Error('configured_yield requires cashYieldDaily');
+    }
+}
+function mergeEngineConfig(baseConfig, variant) {
+    return {
+        ...baseConfig,
+        ...variant.engineConfigOverrides,
+        cashYieldDaily: variant.cashMode === 'zero_yield' ? 0 : variant.cashYieldDaily ?? baseConfig.cashYieldDaily,
+    };
+}
+function applyVariantToDays(days, variant) {
+    return days.map((day) => {
+        let transformedSignal;
+        if (!variant.signal) {
+            transformedSignal = day.signalInput;
+        }
+        else if (variant.signal.smaMode) {
+            // SMA mode: signalInput is 1 (price above SMA) or 0 (price below SMA).
+            // Leveraged when signalInput > vixThreshold; set vixThreshold: 0 for standard use.
+            // Using > (not <=) because the SMA signal convention is opposite to VIX: a high
+            // value (1 = above SMA = uptrend) should trigger leverage, not cash.
+            transformedSignal = day.signalInput > variant.signal.vixThreshold
+                ? variant.signal.leverageMultiple
+                : variant.signal.cashExposure ?? 0;
+        }
+        else {
+            // VIX mode (default): lower signalInput = lower volatility = leveraged.
+            transformedSignal = day.signalInput <= variant.signal.vixThreshold
+                ? variant.signal.leverageMultiple
+                : variant.signal.cashExposure ?? 0;
+        }
+        return {
+            ...day,
+            signalInput: transformedSignal,
+            tradeSpread: variant.tradeSpread ?? day.tradeSpread,
+            expenseRatioAnnual: variant.expenseRatioAnnual ?? day.expenseRatioAnnual,
+        };
+    });
+}
+function sliceDaysByDate(days, startDate, endDate) {
+    if (startDate > endDate) {
+        return { ok: false, error: `invalid scenario range: ${startDate} is after ${endDate}` };
+    }
+    const sliced = days.filter((day) => day.date >= startDate && day.date <= endDate);
+    if (sliced.length === 0) {
+        return { ok: false, error: `scenario range ${startDate}..${endDate} has no data` };
+    }
+    return { ok: true, days: sliced };
+}
+function buildExposureDiagnostics(daily) {
+    const dayCount = daily.length;
+    if (dayCount === 0) {
+        return {
+            pctDaysCash: 0,
+            pctDaysOneX: 0,
+            pctDaysLeveraged: 0,
+            averageAppliedLeverage: 0,
+            leverageDistribution: {},
+        };
+    }
+    let cashDays = 0;
+    let oneXDays = 0;
+    let leveragedDays = 0;
+    const distribution = new Map();
+    for (const day of daily) {
+        const absLev = Math.abs(day.appliedPosition);
+        const bucket = day.appliedPosition.toFixed(4);
+        distribution.set(bucket, (distribution.get(bucket) ?? 0) + 1);
+        if (absLev <= EPSILON) {
+            cashDays += 1;
+        }
+        else if (absLev <= 1 + EPSILON) {
+            oneXDays += 1;
+        }
+        else {
+            leveragedDays += 1;
+        }
+    }
+    const leverageDistribution = {};
+    for (const [level, count] of [...distribution.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+        leverageDistribution[level] = count / dayCount;
+    }
+    return {
+        pctDaysCash: cashDays / dayCount,
+        pctDaysOneX: oneXDays / dayCount,
+        pctDaysLeveraged: leveragedDays / dayCount,
+        averageAppliedLeverage: daily.reduce((acc, day) => acc + Math.abs(day.appliedPosition), 0) / dayCount,
+        leverageDistribution,
+    };
+}
+function regimeForPosition(position) {
+    const absLev = Math.abs(position);
+    if (absLev <= EPSILON) {
+        return 'cash';
+    }
+    if (absLev <= 1 + EPSILON) {
+        return 'one_x';
+    }
+    return 'leveraged';
+}
+function buildTransitionDiagnostics(daily) {
+    const transitionCounts = new Map();
+    const holdDurations = {
+        cash: [],
+        one_x: [],
+        leveraged: [],
+    };
+    let totalSwitches = 0;
+    let lastRegime = null;
+    let currentRunLength = 0;
+    for (const day of daily) {
+        const priorRegime = regimeForPosition(day.priorAppliedPosition);
+        const currentRegime = regimeForPosition(day.appliedPosition);
+        if (priorRegime !== currentRegime) {
+            totalSwitches += 1;
+            const key = `${priorRegime}->${currentRegime}`;
+            transitionCounts.set(key, (transitionCounts.get(key) ?? 0) + 1);
+        }
+        if (lastRegime === null || currentRegime !== lastRegime) {
+            if (lastRegime !== null && currentRunLength > 0) {
+                holdDurations[lastRegime].push(currentRunLength);
+            }
+            lastRegime = currentRegime;
+            currentRunLength = 1;
+        }
+        else {
+            currentRunLength += 1;
+        }
+    }
+    if (lastRegime !== null && currentRunLength > 0) {
+        holdDurations[lastRegime].push(currentRunLength);
+    }
+    const transitionCountsObj = {};
+    for (const [key, count] of [...transitionCounts.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+        transitionCountsObj[key] = count;
+    }
+    return {
+        totalSwitches,
+        transitionCounts: transitionCountsObj,
+        averageHoldingDurationByRegime: {
+            cash: average(holdDurations.cash),
+            one_x: average(holdDurations.one_x),
+            leveraged: average(holdDurations.leveraged),
+        },
+    };
+}
+function buildCostDiagnostics(daily, finalEquity, totalInvested) {
+    const totalTradeCost = daily.reduce((acc, day) => acc + day.tradeCost, 0);
+    const totalBorrowCost = daily.reduce((acc, day) => acc + day.borrowDrag, 0);
+    const totalErCost = daily.reduce((acc, day) => acc + day.expenseDrag, 0);
+    const totalCost = totalTradeCost + totalBorrowCost + totalErCost;
+    return {
+        totalTradeCost,
+        totalBorrowCost,
+        totalErCost,
+        totalCost,
+        tradeCostShare: totalCost > 0 ? totalTradeCost / totalCost : 0,
+        borrowCostShare: totalCost > 0 ? totalBorrowCost / totalCost : 0,
+        erCostShare: totalCost > 0 ? totalErCost / totalCost : 0,
+        totalCostPctFinalEquity: finalEquity > 0 ? totalCost / finalEquity : null,
+        totalCostPctInvestedCapital: totalInvested !== undefined && totalInvested > 0 ? totalCost / totalInvested : null,
+    };
+}
+function buildDrawdownDiagnostics(daily) {
+    if (daily.length === 0) {
+        return {
+            maxDrawdown: 0,
+            maxDrawdownDurationDays: 0,
+            episodesAbove10Pct: 0,
+            episodesAbove20Pct: 0,
+            episodesAbove30Pct: 0,
+        };
+    }
+    const equity = daily.map((day) => day.equityEnd);
+    let peak = equity[0];
+    let currentPeakIndex = 0;
+    let maxDrawdown = 0;
+    let maxDrawdownPeakIndex = 0;
+    let maxDrawdownTroughIndex = 0;
+    for (let i = 0; i < equity.length; i += 1) {
+        const level = equity[i];
+        if (level > peak) {
+            peak = level;
+            currentPeakIndex = i;
+        }
+        if (peak > 0) {
+            const drawdown = (peak - level) / peak;
+            if (drawdown > maxDrawdown) {
+                maxDrawdown = drawdown;
+                maxDrawdownPeakIndex = currentPeakIndex;
+                maxDrawdownTroughIndex = i;
+            }
+        }
+    }
+    let recoveryIndex = maxDrawdownTroughIndex;
+    const maxPeakLevel = equity[maxDrawdownPeakIndex];
+    while (recoveryIndex < equity.length && equity[recoveryIndex] < maxPeakLevel) {
+        recoveryIndex += 1;
+    }
+    const maxDrawdownDurationDays = recoveryIndex >= equity.length
+        ? equity.length - 1 - maxDrawdownPeakIndex
+        : recoveryIndex - maxDrawdownPeakIndex;
+    const drawdowns = buildDrawdownSeries(equity);
+    return {
+        maxDrawdown,
+        maxDrawdownDurationDays,
+        episodesAbove10Pct: countEpisodesAboveThreshold(drawdowns, 0.10),
+        episodesAbove20Pct: countEpisodesAboveThreshold(drawdowns, 0.20),
+        episodesAbove30Pct: countEpisodesAboveThreshold(drawdowns, 0.30),
+    };
+}
+function buildBenchmarkRelativeDiagnostics(benchmark) {
+    if (!benchmark) {
+        return undefined;
+    }
+    const excess = benchmark.strategyReturns.map((value, idx) => value - benchmark.benchmarkReturns[idx]);
+    const outperformPeriods = excess.filter((value) => value > EPSILON).length;
+    return {
+        matchedPeriods: excess.length,
+        outperformPeriods,
+        outperformPct: excess.length > 0 ? outperformPeriods / excess.length : null,
+        averageExcessReturn: excess.length > 0 ? average(excess) : null,
+        medianExcessReturn: excess.length > 0 ? median(excess) : null,
+        excessTwrCagr: benchmark.excessTwrCagr,
+    };
+}
+function buildDrawdownSeries(equity) {
+    const drawdowns = [];
+    let peak = equity[0] ?? 0;
+    for (const level of equity) {
+        if (level > peak) {
+            peak = level;
+        }
+        drawdowns.push(peak > 0 ? (peak - level) / peak : 0);
+    }
+    return drawdowns;
+}
+function countEpisodesAboveThreshold(drawdowns, threshold) {
+    let episodes = 0;
+    let inEpisode = false;
+    for (const value of drawdowns) {
+        if (value >= threshold) {
+            if (!inEpisode) {
+                episodes += 1;
+                inEpisode = true;
+            }
+        }
+        else {
+            inEpisode = false;
+        }
+    }
+    return episodes;
+}
+function average(values) {
+    if (values.length === 0) {
+        return 0;
+    }
+    return values.reduce((acc, value) => acc + value, 0) / values.length;
+}
+function median(values) {
+    if (values.length === 0) {
+        return 0;
+    }
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    if (sorted.length % 2 === 0) {
+        return (sorted[mid - 1] + sorted[mid]) / 2;
+    }
+    return sorted[mid];
+}
+function applySensitivityValue(variant, parameter, value) {
+    const next = { ...variant };
+    switch (parameter) {
+        case 'vixThreshold':
+            next.signal = { ...(next.signal ?? { vixThreshold: 0, leverageMultiple: 1 }), vixThreshold: Number(value) };
+            break;
+        case 'leverageMultiple':
+            next.signal = {
+                ...(next.signal ?? { vixThreshold: 0, leverageMultiple: 1 }),
+                leverageMultiple: Number(value),
+            };
+            break;
+        case 'tradeSpread':
+            next.tradeSpread = Number(value);
+            break;
+        case 'expenseRatioAnnual':
+            next.expenseRatioAnnual = Number(value);
+            break;
+        case 'cashYieldDaily':
+            next.cashYieldDaily = Number(value);
+            next.cashMode = 'configured_yield';
+            break;
+        case 'cashMode':
+            if (value !== 'zero_yield' && value !== 'configured_yield') {
+                throw new Error('cashMode sensitivity value must be zero_yield or configured_yield');
+            }
+            next.cashMode = value;
+            break;
+        default:
+            throw new Error(`unsupported sensitivity parameter: ${String(parameter)}`);
+    }
+    next.name = `${variant.name}__${parameter}_${String(value)}`;
+    return next;
+}
+function collectRunWarnings(days, variant, summary) {
+    const warnings = [];
+    const benchmarkCount = days.filter((day) => day.benchmarkReturn !== undefined).length;
+    if (benchmarkCount === 0) {
+        warnings.push({
+            code: 'BENCHMARK_UNAVAILABLE',
+            message: 'No benchmark returns were available for matched-date analytics.',
+        });
+    }
+    else if (benchmarkCount < days.length) {
+        warnings.push({
+            code: 'BENCHMARK_PARTIAL_COVERAGE',
+            message: 'Benchmark returns were only partially available; matched-date analytics used overlap only.',
+            context: {
+                benchmarkDays: benchmarkCount,
+                totalDays: days.length,
+                coveragePct: benchmarkCount / days.length,
+            },
+        });
+    }
+    if (summary.xirr === null) {
+        warnings.push({
+            code: 'XIRR_UNAVAILABLE',
+            message: 'XIRR could not be computed from available cash flows.',
+        });
+    }
+    if ((variant.tradeSpread ?? 0) < 0 || (variant.expenseRatioAnnual ?? 0) < 0 || (variant.cashYieldDaily ?? 0) < 0) {
+        warnings.push({
+            code: 'UNUSUAL_ASSUMPTION',
+            message: 'Strategy includes negative spread/expense/yield assumptions; interpret cautiously.',
+            context: {
+                tradeSpread: variant.tradeSpread ?? null,
+                expenseRatioAnnual: variant.expenseRatioAnnual ?? null,
+                cashYieldDaily: variant.cashYieldDaily ?? null,
+            },
+        });
+    }
+    return warnings;
+}
+function buildScenarioWarnings(days) {
+    if (days.length >= 2) {
+        return [];
+    }
+    return [
+        {
+            code: 'SCENARIO_TOO_FEW_OBSERVATIONS',
+            message: 'Scenario has fewer than 2 observations; annualized metrics may be unavailable.',
+            context: {
+                observations: days.length,
+            },
+        },
+    ];
+}
+function pickMostRobustScenarioVariant(scenarioResult) {
+    const candidates = [];
+    const grouped = new Map();
+    for (const row of scenarioResult.rows) {
+        if (!row.run.ok || row.scenarioName === 'full_period') {
+            continue;
+        }
+        if (row.run.summary.twrCagr === null) {
+            continue;
+        }
+        const existing = grouped.get(row.run.strategy.name) ?? [];
+        existing.push(row.run.summary.twrCagr);
+        grouped.set(row.run.strategy.name, existing);
+    }
+    for (const [strategyName, series] of grouped.entries()) {
+        if (series.length < 2) {
+            continue;
+        }
+        candidates.push({
+            strategyName,
+            minScenarioTwr: Math.min(...series),
+            scenarioCount: series.length,
+        });
+    }
+    if (candidates.length === 0) {
+        return null;
+    }
+    candidates.sort((a, b) => {
+        if (Math.abs(a.minScenarioTwr - b.minScenarioTwr) <= EPSILON) {
+            return a.strategyName.localeCompare(b.strategyName);
+        }
+        return b.minScenarioTwr - a.minScenarioTwr;
+    });
+    const winner = candidates[0];
+    return {
+        kind: 'most_robust_across_scenarios',
+        strategyName: winner.strategyName,
+        rationale: 'Highest worst-scenario TWR CAGR among variants with at least two scenario runs.',
+        metrics: {
+            minScenarioTwrCagr: winner.minScenarioTwr,
+            scenarioCount: winner.scenarioCount,
+        },
+    };
+}