@samsmith2121/synthetic-leverage-engine 0.1.0

package/dist/src/validation-cases.js

@@ -0,0 +1,930 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runModelValidationCases = runModelValidationCases;
+const public_api_1 = require("./public-api");
+const EPSILON = 1e-9;
+function runModelValidationCases() {
+    const results = [];
+    const baselineDataset = buildSyntheticDataset('2007-01-01', '2023-12-29', {
+        monthlyContribution: 0,
+        smaLength: null,
+        includeBenchmark: true,
+        stressWindows: true,
+    });
+    const baselineConfig = buildEngineConfig();
+    const baselineVariant = {
+        name: 'baseline_1x_no_filters',
+    };
+    const baselineRun = (0, public_api_1.runComparison)({
+        days: baselineDataset.days,
+        config: baselineConfig,
+        strategies: [baselineVariant],
+    }).comparison.runs[0];
+    if (!baselineRun.ok) {
+        results.push({
+            id: 'A',
+            name: 'Baseline equivalence run succeeds',
+            status: 'FAIL',
+            actual: baselineRun.error,
+            expected: 'Baseline run should execute successfully.',
+            core: true,
+        });
+        return summarizeResults(results);
+    }
+    const baselineSummary = baselineRun.summary;
+    const benchmark = baselineSummary.benchmark;
+    const baselineReturnGap = benchmark ? Math.abs(totalReturn(baselineSummary.finalEquity, baselineSummary.totalInvested) - benchmark.benchmarkTotalReturn) : Number.POSITIVE_INFINITY;
+    const baselineCagrGap = benchmark ? Math.abs((baselineSummary.twrCagr ?? 0) - (benchmark.benchmarkTwrCagr ?? 0)) : Number.POSITIVE_INFINITY;
+    const baselineBorrow = baselineSummary.totalBorrowCost;
+    const baselineTrade = baselineSummary.totalTradeCost;
+    results.push(makeResult('A1', 'Baseline: strategy total return ~ benchmark', baselineReturnGap <= 1e-6, `return gap=${formatPct(baselineReturnGap)}`, 'Gap <= 0.0001%.', true));
+    results.push(makeResult('A2', 'Baseline: strategy CAGR ~ benchmark CAGR', baselineCagrGap <= 1e-6, `cagr gap=${formatPct(baselineCagrGap)}`, 'Gap <= 0.0001%.', true));
+    results.push(makeResult('A3', 'Baseline: financing drag is zero', nearlyEqual(baselineBorrow, 0), `borrow drag=${baselineBorrow.toFixed(8)}`, 'Borrow drag == 0 at 1x.', true));
+    results.push(makeResult('A4', 'Baseline: trade drag is zero', nearlyEqual(baselineTrade, 0), `trade drag=${baselineTrade.toFixed(8)}`, 'Trade drag == 0 with no turnover + zero spread.', true));
+    const regimeNoopVariant = {
+        name: 'regime_noop_1x',
+        signal: {
+            vixThreshold: 20,
+            leverageMultiple: 1,
+            cashExposure: 1,
+        },
+    };
+    const regimeNoopRun = (0, public_api_1.runComparison)({
+        days: baselineDataset.days.map((day) => ({ ...day, signalInput: 35 })),
+        config: baselineConfig,
+        strategies: [regimeNoopVariant],
+    }).comparison.runs[0];
+    if (!regimeNoopRun.ok) {
+        results.push(makeResult('B', 'Regime no-op run succeeds', false, regimeNoopRun.error, 'Run should execute successfully.', true));
+    }
+    else {
+        const finalGap = Math.abs(regimeNoopRun.summary.finalEquity - baselineSummary.finalEquity);
+        const cagrGap = Math.abs((regimeNoopRun.summary.twrCagr ?? 0) - (baselineSummary.twrCagr ?? 0));
+        results.push(makeResult('B1', 'Regime no-op: final equity near baseline', finalGap <= 1e-6, `final equity gap=${finalGap.toFixed(8)}`, 'Gap <= 1e-6.', true));
+        results.push(makeResult('B2', 'Regime no-op: CAGR near baseline', cagrGap <= 1e-6, `cagr gap=${formatPct(cagrGap)}`, 'Gap <= 0.0001%.', true));
+    }
+    runCostMonotonicityChecks(results, baselineDataset.days, baselineConfig);
+    runContributionAccountingCheck(results);
+    runLeverageSmokeChecks(results);
+    runSmaSensitivityChecks(results);
+    runStressWindowChecks(results, baselineDataset.days, baselineConfig);
+    runLookAheadChecks(results);
+    runExactPathParityChecks(results);
+    runMixedRegimeNoOpChecks(results, baselineDataset.days, baselineConfig);
+    runRealisticCostChecks(results, baselineDataset.days, baselineConfig);
+    runMonteCarloValidationChecks(results, baselineDataset.days, baselineConfig);
+    runGoldenBaselineChecks(results);
+    runTimingChecks(results);
+    runLookAheadContaminationCheck(results);
+    return summarizeResults(results);
+}
+function runCostMonotonicityChecks(results, days, config) {
+    const base = (0, public_api_1.runComparison)({ days, config, strategies: [{ name: 'cost_base', signal: { vixThreshold: 999, leverageMultiple: 1, cashExposure: 1 } }] }).comparison.runs[0];
+    if (!base.ok) {
+        results.push(makeResult('C', 'Cost monotonicity baseline run', false, base.error, 'Baseline cost run should succeed.', true));
+        return;
+    }
+    const cases = [
+        { id: 'C1', name: 'Expense ratio monotonicity', variant: { name: 'high_er', expenseRatioAnnual: 0.01, signal: { vixThreshold: 999, leverageMultiple: 1, cashExposure: 1 } } },
+        { id: 'C2', name: 'Bank spread monotonicity', variant: { name: 'higher_bank_spread', signal: { vixThreshold: 999, leverageMultiple: 2, cashExposure: 2 }, engineConfigOverrides: { initialBorrowRateDaily: 0.0004 } } },
+        { id: 'C3', name: 'Trade spread monotonicity', variant: { name: 'high_trade_spread', tradeSpread: 0.002, signal: { vixThreshold: 999, leverageMultiple: 1, cashExposure: 1 } } },
+    ];
+    for (const costCase of cases) {
+        const run = (0, public_api_1.runComparison)({ days, config, strategies: [costCase.variant] }).comparison.runs[0];
+        if (!run.ok) {
+            results.push(makeResult(costCase.id, costCase.name, false, run.error, 'Run should succeed.', true));
+            continue;
+        }
+        const comparableBase = costCase.id === 'C2'
+            ? (0, public_api_1.runComparison)({
+                days,
+                config,
+                strategies: [{ name: 'bank_base', signal: { vixThreshold: 999, leverageMultiple: 2, cashExposure: 2 }, engineConfigOverrides: { initialBorrowRateDaily: 0.0001 } }],
+            }).comparison.runs[0]
+            : base;
+        if (!comparableBase.ok) {
+            results.push(makeResult(costCase.id, costCase.name, false, comparableBase.error, 'Comparable base run should succeed.', true));
+            continue;
+        }
+        const improvedFinal = run.summary.finalEquity > comparableBase.summary.finalEquity + EPSILON;
+        const improvedCagr = (run.summary.twrCagr ?? -Infinity) > (comparableBase.summary.twrCagr ?? -Infinity) + EPSILON;
+        results.push(makeResult(costCase.id, costCase.name, !(improvedFinal || improvedCagr), `base(final=${comparableBase.summary.finalEquity.toFixed(4)}, cagr=${formatPct(comparableBase.summary.twrCagr ?? 0)}), test(final=${run.summary.finalEquity.toFixed(4)}, cagr=${formatPct(run.summary.twrCagr ?? 0)})`, 'Increasing cost should not improve ending value or CAGR.', true));
+    }
+}
+function runContributionAccountingCheck(results) {
+    const contributionAmount = 250;
+    const dataset = buildSyntheticDataset('2018-01-01', '2020-12-31', {
+        monthlyContribution: contributionAmount,
+        smaLength: null,
+        includeBenchmark: false,
+        stressWindows: false,
+    });
+    const run = (0, public_api_1.runComparison)({ days: dataset.days, config: buildEngineConfig(), strategies: [{ name: 'contrib_check' }] }).comparison.runs[0];
+    if (!run.ok) {
+        results.push(makeResult('D', 'Contribution accounting run succeeds', false, run.error, 'Run should succeed.', true));
+        return;
+    }
+    const expectedInvested = 10000 + contributionAmount * dataset.contributionMonths;
+    const diff = run.summary.totalInvested - expectedInvested;
+    results.push(makeResult('D1', 'Contribution accounting exactness', nearlyEqual(diff, 0), `reported=${run.summary.totalInvested.toFixed(2)}, expected=${expectedInvested.toFixed(2)}, diff=${diff.toFixed(6)}`, 'Invested = initial + monthly contribution × contribution months.', true));
+}
+function runLeverageSmokeChecks(results) {
+    const dataset = buildSyntheticDataset('2016-01-01', '2019-12-31', {
+        monthlyContribution: 0,
+        smaLength: null,
+        includeBenchmark: false,
+        stressWindows: false,
+        bullishBias: true,
+    });
+    const comparison = (0, public_api_1.runComparison)({
+        days: dataset.days,
+        config: buildEngineConfig(),
+        strategies: [
+            { name: 'lev_1x', signal: { vixThreshold: 999, leverageMultiple: 1, cashExposure: 1 } },
+            { name: 'lev_2x', signal: { vixThreshold: 999, leverageMultiple: 2, cashExposure: 2 } },
+            { name: 'lev_3x', signal: { vixThreshold: 999, leverageMultiple: 3, cashExposure: 3 } },
+        ],
+    }).comparison.runs;
+    const runs = comparison.filter((run) => run.ok);
+    if (runs.length !== 3) {
+        results.push(makeResult('E', 'Leverage smoke test run completeness', false, `successful runs=${runs.length}/3`, 'All leverage runs should succeed.', true));
+        return;
+    }
+    const [oneX, twoX, threeX] = runs;
+    const volatilityMonotone = (twoX.summary.volatility ?? 0) >= (oneX.summary.volatility ?? 0) - EPSILON && (threeX.summary.volatility ?? 0) >= (twoX.summary.volatility ?? 0) - EPSILON;
+    const drawdownMonotone = twoX.summary.maxDrawdown >= oneX.summary.maxDrawdown - EPSILON && threeX.summary.maxDrawdown >= twoX.summary.maxDrawdown - EPSILON;
+    const stats = `1x(vol=${formatPct(oneX.summary.volatility ?? 0)}, dd=${formatPct(oneX.summary.maxDrawdown)}), 2x(vol=${formatPct(twoX.summary.volatility ?? 0)}, dd=${formatPct(twoX.summary.maxDrawdown)}), 3x(vol=${formatPct(threeX.summary.volatility ?? 0)}, dd=${formatPct(threeX.summary.maxDrawdown)})`;
+    results.push(makeResult('E1', 'Leverage smoke: volatility non-decreasing with leverage', volatilityMonotone, stats, 'In bullish path, higher leverage should not reduce volatility.', true));
+    results.push(makeResult('E2', 'Leverage smoke: drawdown non-decreasing with leverage', drawdownMonotone, stats, 'In bullish path, higher leverage should not reduce drawdown without strong reason.', true));
+}
+function runSmaSensitivityChecks(results) {
+    // F0: Bug reproduction — VIX-scale threshold silently suppresses all SMA regime switches.
+    // buildSmaSignalInputs now emits 1/0 (price above/below SMA). Without smaMode the default
+    // comparison is signalInput <= vixThreshold. With threshold=20: both 0<=20 and 1<=20 are
+    // always TRUE, so the engine never switches to cash. totalSwitches must be 0.
+    const bugReproDataset = buildSyntheticDataset('2010-01-01', '2023-12-29', {
+        monthlyContribution: 0,
+        smaLength: 100,
+        includeBenchmark: false,
+        stressWindows: true,
+    });
+    const bugReproRun = (0, public_api_1.runComparison)({
+        days: bugReproDataset.days,
+        config: buildEngineConfig(),
+        strategies: [{ name: 'f0_vix_threshold_20_no_smaMode', signal: { vixThreshold: 20, leverageMultiple: 1, cashExposure: 0 } }],
+    }).comparison.runs[0];
+    if (!bugReproRun.ok) {
+        results.push(makeResult('F0', 'SMA bug repro run succeeds', false, bugReproRun.error, 'Run must succeed.', true));
+    }
+    else {
+        const zeroSwitches = bugReproRun.summary.totalSwitches === 0;
+        results.push(makeResult('F0', 'SMA bug repro: VIX-scale threshold (20) with 1/0 SMA signal suppresses all regime switching', zeroSwitches, `totalSwitches=${bugReproRun.summary.totalSwitches} (expected 0 — vixThreshold=20 always ≥ signalInput∈{0,1})`, 'Without smaMode the VIX-scale comparison traps both 0 and 1 on the same side; zero switches confirms the bug.', true));
+    }
+    // F1: Corrected SMA switching — smaMode: true flips the comparison to signalInput > vixThreshold.
+    // With threshold=0: signalInput=1 > 0 = leveraged (price above SMA), signalInput=0 not > 0 = cash.
+    // Each SMA length must produce actual regime switching and lengths must yield distinct outcomes.
+    const lengths = [50, 100, 200];
+    const outcomes = [];
+    for (const length of lengths) {
+        const dataset = buildSyntheticDataset('2010-01-01', '2023-12-29', {
+            monthlyContribution: 0,
+            smaLength: length,
+            includeBenchmark: false,
+            stressWindows: true,
+        });
+        const run = (0, public_api_1.runComparison)({
+            days: dataset.days,
+            config: buildEngineConfig(),
+            strategies: [{ name: `sma_${length}`, signal: { vixThreshold: 0, leverageMultiple: 1, cashExposure: 0, smaMode: true } }],
+        }).comparison.runs[0];
+        if (!run.ok) {
+            results.push(makeResult('F1', `SMA ${length} run succeeds`, false, run.error, 'Run should succeed.', true));
+            return;
+        }
+        outcomes.push({ length, finalEquity: run.summary.finalEquity, twrCagr: run.summary.twrCagr, totalSwitches: run.summary.totalSwitches });
+    }
+    // Every SMA length must produce at least one regime switch (cash ↔ leveraged).
+    const allSwitch = outcomes.every((o) => o.totalSwitches > 0);
+    const distinctFinals = new Set(outcomes.map((o) => o.finalEquity.toFixed(6))).size;
+    const distinctCagrs = new Set(outcomes.map((o) => (o.twrCagr ?? 0).toFixed(8))).size;
+    results.push(makeResult('F1', 'SMA smaMode: each length produces regime switching and distinct outcomes across 50/100/200', allSwitch && (distinctFinals > 1 || distinctCagrs > 1), outcomes.map((o) => `SMA${o.length}: switches=${o.totalSwitches}, final=${o.finalEquity.toFixed(2)}, cagr=${formatPct(o.twrCagr ?? 0)}`).join(' | '), 'smaMode: true must produce totalSwitches > 0 for each length; outcomes must differ across lengths.', true));
+}
+function runStressWindowChecks(results, days, config) {
+    const strategy = {
+        name: 'stress_window_strategy',
+        signal: { vixThreshold: 0, leverageMultiple: 2, cashExposure: 0 },
+        tradeSpread: 0.0003,
+        expenseRatioAnnual: 0.003,
+    };
+    const scenarioRows = (0, public_api_1.runScenarios)({
+        days,
+        config,
+        strategy,
+        includeFullPeriod: false,
+        scenarios: [
+            { name: '2008_crisis', startDate: '2008-01-01', endDate: '2008-12-31' },
+            { name: '2020_covid', startDate: '2020-01-01', endDate: '2020-12-31' },
+            { name: '2022_bear', startDate: '2022-01-01', endDate: '2022-12-31' },
+        ],
+    }).scenarios.rows;
+    for (const row of scenarioRows) {
+        if (!row.run.ok) {
+            results.push(makeResult(`G-${row.scenarioName}`, `Stress window ${row.scenarioName} executes`, false, row.run.error, 'Scenario run should complete successfully.', true));
+            continue;
+        }
+        const summary = row.run.summary;
+        results.push(makeResult(`G-${row.scenarioName}`, `Stress window ${row.scenarioName} metrics reported`, true, `return=${formatPct(totalReturn(summary.finalEquity, summary.totalInvested))}, drawdown=${formatPct(summary.maxDrawdown)}, borrow_drag=${summary.totalBorrowCost.toFixed(4)}, trade_drag=${summary.totalTradeCost.toFixed(4)}, er_drag=${summary.totalErCost.toFixed(4)}`, 'Run should complete and report return/drawdown/drag metrics.', true));
+    }
+}
+function runLookAheadChecks(results) {
+    const full = buildSyntheticDataset('2015-01-01', '2023-12-29', {
+        monthlyContribution: 0,
+        smaLength: 100,
+        includeBenchmark: false,
+        stressWindows: true,
+    });
+    const withShock = buildSyntheticDataset('2015-01-01', '2023-12-29', {
+        monthlyContribution: 0,
+        smaLength: 100,
+        includeBenchmark: false,
+        stressWindows: true,
+        postCutoffShock: { date: '2021-01-04', returnShift: 0.05 },
+    });
+    const cutoff = '2021-01-04';
+    const unaffected = full.days
+        .filter((d) => d.date < cutoff)
+        .every((day, idx) => nearlyEqual(day.signalInput, withShock.days[idx].signalInput));
+    const timingRun = (0, public_api_1.runComparison)({
+        days: full.days,
+        config: buildEngineConfig(),
+        strategies: [{ name: 'timing_guard', signal: { vixThreshold: 0, leverageMultiple: 1, cashExposure: 0, smaMode: true } }],
+    }).comparison.runs[0];
+    if (!timingRun.ok) {
+        results.push(makeResult('H1', 'Look-ahead timing run succeeds', false, timingRun.error, 'Timing validation run should succeed.', true));
+        return;
+    }
+    results.push(makeResult('H1', 'Look-ahead guard: pre-cutoff signals unaffected by future-return perturbation', unaffected, `cutoff=${cutoff}, pre-cutoff signal equality=${unaffected}`, 'Changing future returns should not alter earlier signals.', true));
+    const noLeak = timingRun.summary.diagnostics.transitions.totalSwitches >= 0;
+    const assumptionText = 'Engine timing assumption: signal(t) computed from day t input and applied at t+1 via appliedPosition(t)=targetPosition(t-1).';
+    results.push({
+        id: 'H2',
+        name: 'Look-ahead timing assumption inspection (manual audit aid)',
+        status: noLeak ? 'WARN' : 'FAIL',
+        actual: assumptionText,
+        expected: 'Confirm signal uses only available data and exposure switching is T+1.',
+        core: false,
+    });
+}
+function runExactPathParityChecks(results) {
+    // Hand-crafted 5-day path with explicitly known daily returns.
+    // Expected final equity is computed independently as a product of (1+r) factors —
+    // no engine logic required to derive the expected value.
+    const knownReturns = [0.01, -0.005, 0.02, -0.015, 0.0075];
+    const days = ['2020-01-02', '2020-01-03', '2020-01-06', '2020-01-07', '2020-01-08'].map((date, i) => ({
+        date,
+        assetReturn: knownReturns[i],
+        benchmarkReturn: knownReturns[i],
+        signalInput: 1,
+        borrowRateDaily: 0,
+        expenseRatioAnnual: 0,
+        tradeSpread: 0,
+    }));
+    const config = {
+        initialEquity: 10000,
+        tradeCostRate: 0,
+        maxLeverage: 3,
+        initialTargetPosition: 1,
+        initialAppliedPosition: 1,
+        initialBorrowRateDaily: 0,
+        cashYieldDaily: 0,
+    };
+    // Independently computed: $10,000 × Π(1 + rᵢ). No engine code involved.
+    const expectedFinal = knownReturns.reduce((equity, r) => equity + equity * r, 10000);
+    const run = (0, public_api_1.runComparison)({
+        days,
+        config,
+        strategies: [{ name: 'exact_path_1x_zero_cost' }],
+    }).comparison.runs[0];
+    if (!run.ok) {
+        results.push(makeResult('I', 'Exact path parity run succeeds', false, run.error, 'Run should succeed.', true));
+        return;
+    }
+    const finalGap = Math.abs(run.summary.finalEquity - expectedFinal);
+    results.push(makeResult('I1', 'Exact known path: 1x zero-cost final equity matches independently computed product', finalGap < 1e-8, `engine=${run.summary.finalEquity.toFixed(10)}, computed=${expectedFinal.toFixed(10)}, gap=${finalGap.toExponential(3)}`, 'Final equity must equal $10,000 compounded daily at each known return to within 1e-8 — no costs, no contributions.', true));
+    const bm = run.summary.benchmark;
+    const stratReturn = totalReturn(run.summary.finalEquity, run.summary.totalInvested);
+    const bmReturn = bm ? bm.benchmarkTotalReturn : null;
+    const returnGap = bmReturn !== null ? Math.abs(stratReturn - bmReturn) : Number.POSITIVE_INFINITY;
+    results.push(makeResult('I2', 'Exact known path: 1x zero-cost strategy return equals benchmark return to machine epsilon', returnGap < 1e-8, `strategy=${formatPct(stratReturn)}, benchmark=${bmReturn !== null ? formatPct(bmReturn) : 'N/A'}, gap=${returnGap.toExponential(3)}`, 'With identical asset and benchmark returns at 1x zero cost, total returns must match exactly.', true));
+}
+function runMixedRegimeNoOpChecks(results, baseDays, config) {
+    // Alternate signalInput between 10 (below threshold) and 40 (above threshold).
+    // When leverageMultiple == cashExposure == 1, every day resolves to targetPosition=1
+    // regardless of which regime fires — so mixed signals must not alter the equity path.
+    const mixedDays = baseDays.map((day, i) => ({
+        ...day,
+        signalInput: i % 2 === 0 ? 10 : 40,
+    }));
+    // Baseline: threshold=999 means every day is in leverage mode → leverageMultiple=1 always.
+    const alwaysLevRun = (0, public_api_1.runComparison)({
+        days: mixedDays,
+        config,
+        strategies: [{ name: 'j_always_lev_1x', signal: { vixThreshold: 999, leverageMultiple: 1, cashExposure: 1 } }],
+    }).comparison.runs[0];
+    // Test: threshold=25, even days (signalInput=10) hit leverage=1, odd days (signalInput=40) hit cash=1.
+    const mixedRun = (0, public_api_1.runComparison)({
+        days: mixedDays,
+        config,
+        strategies: [{ name: 'j_mixed_1x_1x', signal: { vixThreshold: 25, leverageMultiple: 1, cashExposure: 1 } }],
+    }).comparison.runs[0];
+    if (!alwaysLevRun.ok) {
+        results.push(makeResult('J1', 'Mixed regime no-op runs succeed', false, alwaysLevRun.error, 'Both runs should succeed.', true));
+        return;
+    }
+    if (!mixedRun.ok) {
+        results.push(makeResult('J1', 'Mixed regime no-op runs succeed', false, mixedRun.error, 'Both runs should succeed.', true));
+        return;
+    }
+    const finalGap = Math.abs(mixedRun.summary.finalEquity - alwaysLevRun.summary.finalEquity);
+    results.push(makeResult('J1', 'No-op regime: VIX 1x/1x filter with mixed signals produces identical equity to always-1x', finalGap < EPSILON, `always_1x=${alwaysLevRun.summary.finalEquity.toFixed(8)}, mixed_1x_1x=${mixedRun.summary.finalEquity.toFixed(8)}, gap=${finalGap.toExponential(3)}`, 'With leverageMultiple=1 and cashExposure=1, VIX regime switching must not alter the equity path.', true));
+}
+function runRealisticCostChecks(results, baseDays, config) {
+    // K1: 0.5% annual expense ratio at sustained 1x must reduce equity vs zero ER.
+    const erBaseRun = (0, public_api_1.runComparison)({
+        days: baseDays,
+        config,
+        strategies: [{ name: 'k_er_zero', signal: { vixThreshold: 999, leverageMultiple: 1, cashExposure: 1 } }],
+    }).comparison.runs[0];
+    const erCostRun = (0, public_api_1.runComparison)({
+        days: baseDays,
+        config,
+        strategies: [{ name: 'k_er_half_pct', expenseRatioAnnual: 0.005, signal: { vixThreshold: 999, leverageMultiple: 1, cashExposure: 1 } }],
+    }).comparison.runs[0];
+    if (!erBaseRun.ok) {
+        results.push(makeResult('K1', 'Realistic ER monotonicity runs succeed', false, erBaseRun.error, 'Both ER runs should succeed.', true));
+    }
+    else if (!erCostRun.ok) {
+        results.push(makeResult('K1', 'Realistic ER monotonicity runs succeed', false, erCostRun.error, 'Both ER runs should succeed.', true));
+    }
+    else {
+        const erWorse = erCostRun.summary.finalEquity < erBaseRun.summary.finalEquity - EPSILON
+            && (erCostRun.summary.twrCagr ?? 0) < (erBaseRun.summary.twrCagr ?? 0) - EPSILON;
+        results.push(makeResult('K1', 'Realistic cost: 0.5% annual ER strictly reduces final equity and CAGR over 16-year horizon', erWorse, `zero_er(final=${erBaseRun.summary.finalEquity.toFixed(4)}, cagr=${formatPct(erBaseRun.summary.twrCagr ?? 0)}), er_0.5pct(final=${erCostRun.summary.finalEquity.toFixed(4)}, cagr=${formatPct(erCostRun.summary.twrCagr ?? 0)})`, '0.5% annual expense ratio must strictly reduce both final equity and CAGR vs zero ER.', true));
+    }
+    // K2: 0.1% daily borrow rate at sustained 2x must reduce equity vs 0.01% daily.
+    // borrowRateDaily is per-day in DayInput; override directly since variants only control initialBorrowRateDaily.
+    const lowBorrowDays = baseDays.map((day) => ({ ...day, borrowRateDaily: 0.0001 }));
+    const highBorrowDays = baseDays.map((day) => ({ ...day, borrowRateDaily: 0.001 }));
+    const borrowBaseRun = (0, public_api_1.runComparison)({
+        days: lowBorrowDays,
+        config,
+        strategies: [{ name: 'k_borrow_low_2x', signal: { vixThreshold: 999, leverageMultiple: 2, cashExposure: 2 } }],
+    }).comparison.runs[0];
+    const borrowHighRun = (0, public_api_1.runComparison)({
+        days: highBorrowDays,
+        config,
+        strategies: [{ name: 'k_borrow_high_2x', signal: { vixThreshold: 999, leverageMultiple: 2, cashExposure: 2 } }],
+    }).comparison.runs[0];
+    if (!borrowBaseRun.ok) {
+        results.push(makeResult('K2', 'Realistic borrow monotonicity runs succeed', false, borrowBaseRun.error, 'Both borrow runs should succeed.', true));
+    }
+    else if (!borrowHighRun.ok) {
+        results.push(makeResult('K2', 'Realistic borrow monotonicity runs succeed', false, borrowHighRun.error, 'Both borrow runs should succeed.', true));
+    }
+    else {
+        const borrowWorse = borrowHighRun.summary.finalEquity < borrowBaseRun.summary.finalEquity - EPSILON;
+        results.push(makeResult('K2', 'Realistic cost: 0.1% daily borrow rate at 2x strictly reduces equity vs 0.01% daily', borrowWorse, `low_borrow_0.01pct(final=${borrowBaseRun.summary.finalEquity.toFixed(4)}), high_borrow_0.1pct(final=${borrowHighRun.summary.finalEquity.toFixed(4)})`, '10x higher daily borrow rate at sustained 2x must strictly reduce final equity over multi-year horizon.', true));
+    }
+    // K3: 0.05% trade spread under active regime switching must reduce equity vs zero spread.
+    // Use days where signalInput alternates every 10 bars so position switches 1x↔0x ~420 times.
+    const switchingDays = baseDays.map((day, i) => ({
+        ...day,
+        signalInput: i % 10 === 0 ? 10 : 40,
+    }));
+    const spreadZeroRun = (0, public_api_1.runComparison)({
+        days: switchingDays,
+        config,
+        strategies: [{
+                name: 'k_spread_zero',
+                tradeSpread: 0,
+                signal: { vixThreshold: 25, leverageMultiple: 1, cashExposure: 0 },
+            }],
+    }).comparison.runs[0];
+    const spreadCostRun = (0, public_api_1.runComparison)({
+        days: switchingDays,
+        config,
+        strategies: [{
+                name: 'k_spread_realistic',
+                tradeSpread: 0.0005,
+                signal: { vixThreshold: 25, leverageMultiple: 1, cashExposure: 0 },
+            }],
+    }).comparison.runs[0];
+    if (!spreadZeroRun.ok) {
+        results.push(makeResult('K3', 'Realistic trade spread monotonicity runs succeed', false, spreadZeroRun.error, 'Both spread runs should succeed.', true));
+    }
+    else if (!spreadCostRun.ok) {
+        results.push(makeResult('K3', 'Realistic trade spread monotonicity runs succeed', false, spreadCostRun.error, 'Both spread runs should succeed.', true));
+    }
+    else {
+        const spreadWorse = spreadCostRun.summary.finalEquity < spreadZeroRun.summary.finalEquity - EPSILON;
+        results.push(makeResult('K3', 'Realistic cost: 0.05% trade spread reduces equity vs zero spread under ~420 regime switches', spreadWorse, `zero_spread(final=${spreadZeroRun.summary.finalEquity.toFixed(4)}), spread_0.05pct(final=${spreadCostRun.summary.finalEquity.toFixed(4)})`, '0.05% trade spread must strictly reduce final equity when regime switching generates turnover.', true));
+    }
+}
+function runMonteCarloValidationChecks(results, baseDays, config) {
+    // Use a 5-year tail of the baseline dataset as the MC source (last 1260 trading days).
+    // This keeps MC runs fast while using realistic positive-drift data with a stress year (2022).
+    const mcDays1260 = baseDays.slice(-1260);
+    // Use a 1-year tail for tests where only distributional shape matters (not horizon length).
+    const mcDays252 = baseDays.slice(-252);
+    runMC1MedianCalibration(results, mcDays1260, config);
+    runMC2PercentileOrder(results, mcDays252, config);
+    // MC-3 uses the 1260-day source so the distribution is wide enough for
+    // seed-to-seed p50 variation to be clearly detectable at different path counts.
+    runMC3PathCountStability(results, mcDays1260, config);
+    runMC4BlockLengthSensitivity(results, mcDays252, config);
+    runMC5VarianceDrag(results);
+}
+// MC-1: 200-path MC median ending equity within 50%–200% of fixed backtest — calibration check.
+function runMC1MedianCalibration(results, sourceDays, config) {
+    const fixedRun = (0, public_api_1.runComparison)({
+        days: sourceDays,
+        config,
+        strategies: [{ name: 'mc1_fixed_baseline' }],
+    }).comparison.runs[0];
+    if (!fixedRun.ok) {
+        results.push(makeResult('MC-1', 'MC-1 fixed baseline run succeeds', false, fixedRun.error, 'Fixed run must succeed.', true));
+        return;
+    }
+    const mc = (0, public_api_1.runMonteCarlo)({
+        days: sourceDays,
+        config,
+        monteCarlo: { paths: 200, horizonDays: sourceDays.length, seed: 42, blockLength: 5 },
+    });
+    const fixedFinal = fixedRun.summary.finalEquity;
+    const mcMedian = mc.summary.medianEndingEquity;
+    const ratio = mcMedian / fixedFinal;
+    const inRange = ratio >= 0.5 && ratio <= 2.0;
+    results.push(makeResult('MC-1', 'MC-1: 200-path median ending equity is within 50%–200% of fixed backtest — MC calibrated to source data', inRange, `fixed=${fixedFinal.toFixed(2)}, mc_median=${mcMedian.toFixed(2)}, ratio=${ratio.toFixed(3)}`, 'MC median ending equity must be within 0.5×–2× of fixed backtest equity on same source data.', true));
+}
+// MC-2: P5 < P50 < P95 must hold strictly for ending equity, TWR CAGR, and max drawdown.
+function runMC2PercentileOrder(results, sourceDays, config) {
+    const mc = (0, public_api_1.runMonteCarlo)({
+        days: sourceDays,
+        config,
+        monteCarlo: { paths: 100, horizonDays: sourceDays.length, seed: 42, blockLength: 5 },
+    });
+    const eq = mc.summary.endingEquity;
+    const twr = mc.summary.twrCagr;
+    const dd = mc.summary.maxDrawdown;
+    const equityOrdered = eq.p5 < eq.p50 && eq.p50 < eq.p95;
+    const twrOrdered = twr.p5 < twr.p50 && twr.p50 < twr.p95;
+    const ddOrdered = dd.p5 < dd.p50 && dd.p50 < dd.p95;
+    results.push(makeResult('MC-2', 'MC-2: P5 < P50 < P95 holds strictly for ending equity, TWR CAGR, and max drawdown', equityOrdered && twrOrdered && ddOrdered, `equity(p5=${eq.p5.toFixed(2)}, p50=${eq.p50.toFixed(2)}, p95=${eq.p95.toFixed(2)}) ` +
+        `twr(p5=${formatPct(twr.p5)}, p50=${formatPct(twr.p50)}, p95=${formatPct(twr.p95)}) ` +
+        `dd(p5=${formatPct(dd.p5)}, p50=${formatPct(dd.p50)}, p95=${formatPct(dd.p95)})`, 'All three MC summary metrics must satisfy strict percentile ordering across all paths.', true));
+}
+// MC-3: 300-path p50 is closer across seeds than 50-path p50 — convergence with path count.
+// Uses 1260-day source so the equity distribution is wide enough that seed-to-seed
+// variation at 50 paths is clearly larger than at 300 paths (sqrt(300/50) ≈ 2.45× improvement).
+function runMC3PathCountStability(results, sourceDays, config) {
+    const mcBase = { horizonDays: sourceDays.length, blockLength: 5 };
+    // Seeds far apart to maximise independent sampling between the two paired runs.
+    const seedA = 7;
+    const seedB = 77777;
+    const low50a = (0, public_api_1.runMonteCarlo)({ days: sourceDays, config, monteCarlo: { paths: 50, seed: seedA, ...mcBase } });
+    const low50b = (0, public_api_1.runMonteCarlo)({ days: sourceDays, config, monteCarlo: { paths: 50, seed: seedB, ...mcBase } });
+    const high300a = (0, public_api_1.runMonteCarlo)({ days: sourceDays, config, monteCarlo: { paths: 300, seed: seedA, ...mcBase } });
+    const high300b = (0, public_api_1.runMonteCarlo)({ days: sourceDays, config, monteCarlo: { paths: 300, seed: seedB, ...mcBase } });
+    const diff50 = Math.abs(low50a.summary.medianEndingEquity - low50b.summary.medianEndingEquity);
+    const diff300 = Math.abs(high300a.summary.medianEndingEquity - high300b.summary.medianEndingEquity);
+    results.push(makeResult('MC-3', 'MC-3: 300-path median ending equity is more stable across seeds than 50-path median', diff300 < diff50, `50-path seed spread=${diff50.toFixed(4)}, 300-path seed spread=${diff300.toFixed(4)}`, '300 paths must produce lower seed-to-seed p50 variation than 50 paths (convergence by LLN, sqrt(300/50)≈2.45× improvement).', true));
+}
+// MC-4: blockLength=3 vs blockLength=21 produce meaningfully different P5-P95 equity spread.
+function runMC4BlockLengthSensitivity(results, sourceDays, config) {
+    const mcBase = { paths: 200, horizonDays: sourceDays.length, seed: 42 };
+    const shortBlock = (0, public_api_1.runMonteCarlo)({ days: sourceDays, config, monteCarlo: { ...mcBase, blockLength: 3 } });
+    const longBlock = (0, public_api_1.runMonteCarlo)({ days: sourceDays, config, monteCarlo: { ...mcBase, blockLength: 21 } });
+    const spread3 = shortBlock.summary.endingEquity.p95 - shortBlock.summary.endingEquity.p5;
+    const spread21 = longBlock.summary.endingEquity.p95 - longBlock.summary.endingEquity.p5;
+    const spreadDiff = Math.abs(spread3 - spread21);
+    // Require at least $50 difference in the P5–P95 band — a detectable sensitivity.
+    const meaningfullyDifferent = spreadDiff > 50;
+    results.push(makeResult('MC-4', 'MC-4: blockLength=3 and blockLength=21 produce meaningfully different P5–P95 equity spread (Δ > $50)', meaningfullyDifferent, `block3 spread=${spread3.toFixed(2)}, block21 spread=${spread21.toFixed(2)}, diff=${spreadDiff.toFixed(2)}`, 'Changing block length from 3 to 21 must produce a detectable difference in the P5–P95 equity range.', true));
+}
+// MC-5: Variance drag — on a zero-drift ±3%/day dataset, MC median CAGR must be negative.
+// Arithmetic mean return = 0, but geometric mean = (1.03×0.97)^(N/2) - 1 < 0.
+// Confirms MC correctly propagates variance drag (σ²/2 per day) through compounding.
+function runMC5VarianceDrag(results) {
+    // Build a 1-year zero-drift alternating dataset (±3% daily, ~252 trading days).
+    const dates = businessDays('2021-01-01', '2021-12-31');
+    const volatileDays = dates.map((date, i) => ({
+        date,
+        assetReturn: i % 2 === 0 ? 0.03 : -0.03,
+        signalInput: 1,
+        borrowRateDaily: 0,
+        expenseRatioAnnual: 0,
+        tradeSpread: 0,
+    }));
+    const zeroConfig = {
+        initialEquity: 10000,
+        tradeCostRate: 0,
+        maxLeverage: 3,
+        initialTargetPosition: 1,
+        initialAppliedPosition: 1,
+        initialBorrowRateDaily: 0,
+        cashYieldDaily: 0,
+    };
+    const mc = (0, public_api_1.runMonteCarlo)({
+        days: volatileDays,
+        config: zeroConfig,
+        monteCarlo: { paths: 200, horizonDays: volatileDays.length, seed: 42, blockLength: 5 },
+    });
+    const medianCagr = mc.summary.medianTwrCagr;
+    results.push(makeResult('MC-5', 'MC-5: Zero-drift ±3%/day dataset yields negative MC median CAGR — variance drag confirmed', medianCagr < 0, `mc_median_cagr=${formatPct(medianCagr)}, arithmetic_mean_daily_return=0.0000%`, 'With zero arithmetic mean return and ±3% daily volatility, MC median CAGR must be negative (variance drag ≈ σ²/2 per day ≈ −10% annual).', true));
+}
+function runGoldenBaselineChecks(results) {
+    const returns = [0.01, -0.02, 0.015, 0.005, -0.01];
+    const dates = ['2020-01-02', '2020-01-03', '2020-01-06', '2020-01-07', '2020-01-08'];
+    const zeroConfig = {
+        initialEquity: 10000,
+        tradeCostRate: 0,
+        maxLeverage: 3,
+        initialTargetPosition: 1,
+        initialAppliedPosition: 1,
+        initialBorrowRateDaily: 0,
+        cashYieldDaily: 0,
+    };
+    // GOLD-1: 1x leverage, zero costs, no contributions.
+    // Expected final equity: 10000 compounded by each daily return at 1x.
+    const gold1Days = dates.map((date, i) => ({
+        date,
+        assetReturn: returns[i],
+        signalInput: 1,
+        borrowRateDaily: 0,
+        expenseRatioAnnual: 0,
+        tradeSpread: 0,
+    }));
+    const gold1Expected = returns.reduce((equity, r) => equity + equity * r, 10000);
+    const gold1Run = (0, public_api_1.runComparison)({
+        days: gold1Days,
+        config: zeroConfig,
+        strategies: [{ name: 'gold1_1x_zero_cost' }],
+    }).comparison.runs[0];
+    if (!gold1Run.ok) {
+        results.push(makeResult('GOLD-1', 'Golden baseline: 1x zero-cost path runs', false, gold1Run.error, 'Run must succeed.', true));
+    }
+    else {
+        const gap = Math.abs(gold1Run.summary.finalEquity - gold1Expected);
+        results.push(makeResult('GOLD-1', 'Golden baseline: 1x zero-cost 5-day path matches hand-computed expected equity', gap < 1e-6, `actual=${gold1Run.summary.finalEquity.toFixed(10)}, expected=${gold1Expected.toFixed(10)}, gap=${gap.toExponential(3)}`, `Final equity must equal $${gold1Expected.toFixed(10)} to within 1e-6.`, true));
+    }
+    // GOLD-2: 2x leverage, zero costs (borrowRateDaily=0 → borrow drag is zero at 2x), no contributions.
+    // Expected: each day's pnl = equity * 2 * dailyReturn.
+    const gold2Config = {
+        ...zeroConfig,
+        initialTargetPosition: 2,
+        initialAppliedPosition: 2,
+    };
+    const gold2Days = dates.map((date, i) => ({
+        date,
+        assetReturn: returns[i],
+        signalInput: 2,
+        borrowRateDaily: 0,
+        expenseRatioAnnual: 0,
+        tradeSpread: 0,
+    }));
+    const gold2Expected = returns.reduce((equity, r) => equity + equity * 2 * r, 10000);
+    const gold2Run = (0, public_api_1.runComparison)({
+        days: gold2Days,
+        config: gold2Config,
+        strategies: [{ name: 'gold2_2x_zero_cost' }],
+    }).comparison.runs[0];
+    if (!gold2Run.ok) {
+        results.push(makeResult('GOLD-2', 'Golden baseline: 2x zero-cost path runs', false, gold2Run.error, 'Run must succeed.', true));
+    }
+    else {
+        const gap = Math.abs(gold2Run.summary.finalEquity - gold2Expected);
+        results.push(makeResult('GOLD-2', 'Golden baseline: 2x zero-cost 5-day path matches hand-computed expected equity (borrow drag zero at borrowRate=0)', gap < 1e-6, `actual=${gold2Run.summary.finalEquity.toFixed(10)}, expected=${gold2Expected.toFixed(10)}, gap=${gap.toExponential(3)}`, `Final equity must equal $${gold2Expected.toFixed(10)} to within 1e-6.`, true));
+    }
+    // GOLD-3: 1x, $500 contribution on day index 2, contribution applied before return.
+    const gold3Days = dates.map((date, i) => ({
+        date,
+        assetReturn: returns[i],
+        signalInput: 1,
+        contribution: i === 2 ? 500 : 0,
+        borrowRateDaily: 0,
+        expenseRatioAnnual: 0,
+        tradeSpread: 0,
+    }));
+    // Hand-compute: (equity + contribution) * (1 + return) each step.
+    let gold3Expected = 10000;
+    for (let i = 0; i < returns.length; i++) {
+        gold3Expected = (gold3Expected + (i === 2 ? 500 : 0)) * (1 + returns[i]);
+    }
+    const gold3Run = (0, public_api_1.runComparison)({
+        days: gold3Days,
+        config: zeroConfig,
+        strategies: [{ name: 'gold3_contrib_day3' }],
+    }).comparison.runs[0];
+    if (!gold3Run.ok) {
+        results.push(makeResult('GOLD-3', 'Golden baseline: contribution path runs', false, gold3Run.error, 'Run must succeed.', true));
+    }
+    else {
+        const gap = Math.abs(gold3Run.summary.finalEquity - gold3Expected);
+        results.push(makeResult('GOLD-3', 'Golden baseline: 1x path with $500 contribution on day 3 matches contribution-before-return expected equity', gap < 1e-6, `actual=${gold3Run.summary.finalEquity.toFixed(10)}, expected=${gold3Expected.toFixed(10)}, gap=${gap.toExponential(3)}`, `Final equity must equal $${gold3Expected.toFixed(10)} to within 1e-6.`, true));
+    }
+}
+function runTimingChecks(results) {
+    // TIMING-1: signal flips from 0 to 1 at day index 2.
+    // T+1: appliedPosition(t) = targetPosition(t-1), so day-2 return is missed at the flip.
+    // Same-day (buggy): would capture day-2 return immediately.
+    const timing1Returns = [0.01, 0.02, 0.01, 0.01, 0.01];
+    const timing1Dates = ['2020-01-02', '2020-01-03', '2020-01-06', '2020-01-07', '2020-01-08'];
+    const timing1Signals = [0, 0, 1, 1, 1];
+    const timing1Days = timing1Dates.map((date, i) => ({
+        date,
+        assetReturn: timing1Returns[i],
+        signalInput: timing1Signals[i],
+        borrowRateDaily: 0,
+        expenseRatioAnnual: 0,
+        tradeSpread: 0,
+    }));
+    const timing1Config = {
+        initialEquity: 10000,
+        tradeCostRate: 0,
+        maxLeverage: 3,
+        initialTargetPosition: 0,
+        initialAppliedPosition: 0,
+        initialBorrowRateDaily: 0,
+        cashYieldDaily: 0,
+    };
+    // T+1 expected: applied = prevTarget (starts at initialTargetPosition=0).
+    let t1Expected = 10000;
+    let prevTarget = 0;
+    for (let i = 0; i < timing1Returns.length; i++) {
+        t1Expected = t1Expected + t1Expected * prevTarget * timing1Returns[i];
+        prevTarget = timing1Signals[i];
+    }
+    // Same-day (hypothetical buggy) expected: applied = today's signal.
+    let sameDayExpected = 10000;
+    for (let i = 0; i < timing1Returns.length; i++) {
+        sameDayExpected = sameDayExpected + sameDayExpected * timing1Signals[i] * timing1Returns[i];
+    }
+    const timing1Run = (0, public_api_1.runComparison)({
+        days: timing1Days,
+        config: timing1Config,
+        strategies: [{ name: 'timing1_t1_check' }],
+    }).comparison.runs[0];
+    if (!timing1Run.ok) {
+        results.push(makeResult('TIMING-1', 'TIMING-1: T+1 timing check run succeeds', false, timing1Run.error, 'Run must succeed.', true));
+    }
+    else {
+        const gapVsT1 = Math.abs(timing1Run.summary.finalEquity - t1Expected);
+        const diffVsSameDay = Math.abs(timing1Run.summary.finalEquity - sameDayExpected);
+        results.push(makeResult('TIMING-1', 'T+1 timing: engine output matches T+1 expected to machine epsilon and differs detectably from same-day expected', gapVsT1 < 1e-6 && diffVsSameDay > 100, `actual=${timing1Run.summary.finalEquity.toFixed(6)}, t1_expected=${t1Expected.toFixed(6)}, same_day_expected=${sameDayExpected.toFixed(6)}, gap_vs_t1=${gapVsT1.toExponential(3)}, diff_vs_same_day=${diffVsSameDay.toFixed(4)}`, 'Engine must match T+1 expected to within 1e-6 and differ from same-day expected by > $100.', true));
+    }
+    // TIMING-2: contribution-before-return vs contribution-after-return.
+    // Uses same returns as GOLD-1/3 with $500 contribution on day index 2.
+    const timing2Returns = [0.01, -0.02, 0.015, 0.005, -0.01];
+    const timing2Dates = ['2020-01-02', '2020-01-03', '2020-01-06', '2020-01-07', '2020-01-08'];
+    const timing2Days = timing2Dates.map((date, i) => ({
+        date,
+        assetReturn: timing2Returns[i],
+        signalInput: 1,
+        contribution: i === 2 ? 500 : 0,
+        borrowRateDaily: 0,
+        expenseRatioAnnual: 0,
+        tradeSpread: 0,
+    }));
+    const timing2Config = {
+        initialEquity: 10000,
+        tradeCostRate: 0,
+        maxLeverage: 3,
+        initialTargetPosition: 1,
+        initialAppliedPosition: 1,
+        initialBorrowRateDaily: 0,
+        cashYieldDaily: 0,
+    };
+    // Before-return (correct): (equity + contribution) * (1 + return).
+    let beforeReturnExpected = 10000;
+    for (let i = 0; i < timing2Returns.length; i++) {
+        beforeReturnExpected = (beforeReturnExpected + (i === 2 ? 500 : 0)) * (1 + timing2Returns[i]);
+    }
+    // After-return (hypothetical buggy): equity * (1 + return) + contribution.
+    let afterReturnExpected = 10000;
+    for (let i = 0; i < timing2Returns.length; i++) {
+        afterReturnExpected = afterReturnExpected * (1 + timing2Returns[i]) + (i === 2 ? 500 : 0);
+    }
+    const timing2Run = (0, public_api_1.runComparison)({
+        days: timing2Days,
+        config: timing2Config,
+        strategies: [{ name: 'timing2_contrib_order' }],
+    }).comparison.runs[0];
+    if (!timing2Run.ok) {
+        results.push(makeResult('TIMING-2', 'TIMING-2: Contribution ordering check run succeeds', false, timing2Run.error, 'Run must succeed.', true));
+    }
+    else {
+        const gapVsBefore = Math.abs(timing2Run.summary.finalEquity - beforeReturnExpected);
+        const diffVsAfter = Math.abs(timing2Run.summary.finalEquity - afterReturnExpected);
+        results.push(makeResult('TIMING-2', 'Contribution ordering: engine applies contribution before return, not after', gapVsBefore < 1e-6 && diffVsAfter > 5, `actual=${timing2Run.summary.finalEquity.toFixed(6)}, before_return_expected=${beforeReturnExpected.toFixed(6)}, after_return_expected=${afterReturnExpected.toFixed(6)}, gap_vs_before=${gapVsBefore.toExponential(3)}, diff_vs_after=${diffVsAfter.toFixed(4)}`, 'Engine must match contribution-before-return expected to within 1e-6 and differ from contribution-after-return by > $5.', true));
+    }
+}
+function runLookAheadContaminationCheck(results) {
+    // 100-day path with a large return shock injected at day index 50.
+    // Pre-cutoff run (days 0-48) must be identical between clean and shocked datasets —
+    // the shock cannot contaminate earlier equity because it has not happened yet.
+    // Full run must differ substantially, confirming the shock propagates correctly post-cutoff.
+    const N = 100;
+    const shockIndex = 50;
+    const normalReturn = 0.001;
+    const shockReturn = 0.50;
+    const allDates = businessDays('2020-01-02', '2020-12-31').slice(0, N);
+    const cleanDays = allDates.map((date) => ({
+        date,
+        assetReturn: normalReturn,
+        signalInput: 1,
+        borrowRateDaily: 0,
+        expenseRatioAnnual: 0,
+        tradeSpread: 0,
+    }));
+    const shockedDays = allDates.map((date, i) => ({
+        date,
+        assetReturn: i === shockIndex ? shockReturn : normalReturn,
+        signalInput: 1,
+        borrowRateDaily: 0,
+        expenseRatioAnnual: 0,
+        tradeSpread: 0,
+    }));
+    const lookaheadConfig = {
+        initialEquity: 10000,
+        tradeCostRate: 0,
+        maxLeverage: 3,
+        initialTargetPosition: 1,
+        initialAppliedPosition: 1,
+        initialBorrowRateDaily: 0,
+        cashYieldDaily: 0,
+    };
+    // Pre-cutoff: slice to indices 0..(shockIndex-2) — all days before the shock.
+    const preCutoffClean = (0, public_api_1.runComparison)({
+        days: cleanDays.slice(0, shockIndex - 1),
+        config: lookaheadConfig,
+        strategies: [{ name: 'lookahead_pre_clean' }],
+    }).comparison.runs[0];
+    if (!preCutoffClean.ok) {
+        results.push(makeResult('LOOKAHEAD-1', 'LOOKAHEAD-1: Look-ahead contamination runs succeed', false, preCutoffClean.error, 'All runs must succeed.', true));
+        return;
+    }
+    const preCutoffShocked = (0, public_api_1.runComparison)({
+        days: shockedDays.slice(0, shockIndex - 1),
+        config: lookaheadConfig,
+        strategies: [{ name: 'lookahead_pre_shocked' }],
+    }).comparison.runs[0];
+    if (!preCutoffShocked.ok) {
+        results.push(makeResult('LOOKAHEAD-1', 'LOOKAHEAD-1: Look-ahead contamination runs succeed', false, preCutoffShocked.error, 'All runs must succeed.', true));
+        return;
+    }
+    const fullClean = (0, public_api_1.runComparison)({
+        days: cleanDays,
+        config: lookaheadConfig,
+        strategies: [{ name: 'lookahead_full_clean' }],
+    }).comparison.runs[0];
+    if (!fullClean.ok) {
+        results.push(makeResult('LOOKAHEAD-1', 'LOOKAHEAD-1: Look-ahead contamination runs succeed', false, fullClean.error, 'All runs must succeed.', true));
+        return;
+    }
+    const fullShocked = (0, public_api_1.runComparison)({
+        days: shockedDays,
+        config: lookaheadConfig,
+        strategies: [{ name: 'lookahead_full_shocked' }],
+    }).comparison.runs[0];
+    if (!fullShocked.ok) {
+        results.push(makeResult('LOOKAHEAD-1', 'LOOKAHEAD-1: Look-ahead contamination runs succeed', false, fullShocked.error, 'All runs must succeed.', true));
+        return;
+    }
+    const preCutoffGap = Math.abs(preCutoffClean.summary.finalEquity - preCutoffShocked.summary.finalEquity);
+    const fullDiff = Math.abs(fullClean.summary.finalEquity - fullShocked.summary.finalEquity);
+    results.push(makeResult('LOOKAHEAD-1', 'Look-ahead contamination: pre-cutoff equity identical between clean/shocked; full-run equity differs substantially after shock', preCutoffGap < EPSILON && fullDiff > 1000, `pre_cutoff_gap=${preCutoffGap.toExponential(3)}, full_run_diff=${fullDiff.toFixed(2)} (shock at day ${shockIndex}: +${(shockReturn * 100).toFixed(0)}% return)`, 'Pre-cutoff gap must be < 1e-9. Full-run diff must be > $1000.', true));
+}
+function summarizeResults(results) {
+    const summary = {
+        total: results.length,
+        passed: results.filter((r) => r.status === 'PASS').length,
+        failed: results.filter((r) => r.status === 'FAIL').length,
+        warnings: results.filter((r) => r.status === 'WARN').length,
+        failedCore: results.filter((r) => r.status === 'FAIL' && r.core).length,
+    };
+    return { results, summary };
+}
+function buildEngineConfig() {
+    return {
+        initialEquity: 10000,
+        tradeCostRate: 0,
+        maxLeverage: 3,
+        initialTargetPosition: 1,
+        initialAppliedPosition: 1,
+        initialBorrowRateDaily: 0.0001,
+        cashYieldDaily: 0,
+    };
+}
+function makeResult(id, name, pass, actual, expected, core) {
+    return {
+        id,
+        name,
+        status: pass ? 'PASS' : 'FAIL',
+        actual,
+        expected,
+        core,
+    };
+}
+function buildSyntheticDataset(startDate, endDate, options) {
+    const dates = businessDays(startDate, endDate);
+    const returns = dates.map((date, index) => {
+        const year = Number(date.slice(0, 4));
+        let base = 0.00035 + ((index % 9) - 4) * 0.00018;
+        if (options.bullishBias) {
+            base = 0.0005 + ((index % 11) - 5) * 0.00022;
+        }
+        if (options.stressWindows) {
+            if (year === 2008) {
+                base -= 0.0012;
+            }
+            if (year === 2020) {
+                base -= date < '2020-04-15' ? 0.0015 : -0.0008;
+            }
+            if (year === 2022) {
+                base -= 0.0008;
+            }
+        }
+        if (options.postCutoffShock && date >= options.postCutoffShock.date) {
+            base += options.postCutoffShock.returnShift;
+        }
+        return base;
+    });
+    const signalInputs = options.smaLength ? buildSmaSignalInputs(returns, options.smaLength) : dates.map(() => 1);
+    let contributionMonths = 0;
+    let currentMonth = '';
+    const days = dates.map((date, index) => {
+        const monthKey = date.slice(0, 7);
+        let contribution = 0;
+        if (options.monthlyContribution > 0 && monthKey !== currentMonth) {
+            currentMonth = monthKey;
+            contribution = options.monthlyContribution;
+            contributionMonths += 1;
+        }
+        return {
+            date,
+            assetReturn: returns[index],
+            benchmarkReturn: options.includeBenchmark ? returns[index] : undefined,
+            signalInput: signalInputs[index],
+            contribution,
+            borrowRateDaily: 0.0001,
+            expenseRatioAnnual: 0,
+            tradeSpread: 0,
+        };
+    });
+    return { days, contributionMonths };
+}
+function buildSmaSignalInputs(returns, length) {
+    // Returns a clean boolean-style signal: 1 when price is at or above the SMA
+    // (invest / leveraged regime), 0 when price is below the SMA (cash regime).
+    //
+    // Previous encoding was sma/price - 1 (a small normalized distance value).
+    // That encoding was incompatible with VIX-scale thresholds: any threshold > ~0.1
+    // (such as the typical VIX level 20) would always satisfy signalInput <= threshold,
+    // keeping the strategy permanently leveraged with zero regime switches.
+    // Using 1/0 avoids scale confusion and pairs cleanly with smaMode in applyVariantToDays.
+    const closes = [];
+    let price = 100;
+    return returns.map((ret, index) => {
+        price *= 1 + ret;
+        closes.push(price);
+        const from = Math.max(0, index - length + 1);
+        const window = closes.slice(from, index + 1);
+        const sma = window.reduce((acc, value) => acc + value, 0) / window.length;
+        return price >= sma ? 1 : 0;
+    });
+}
+function businessDays(startDate, endDate) {
+    const out = [];
+    const d = new Date(`${startDate}T00:00:00Z`);
+    const end = new Date(`${endDate}T00:00:00Z`);
+    while (d <= end) {
+        const day = d.getUTCDay();
+        if (day !== 0 && day !== 6) {
+            out.push(d.toISOString().slice(0, 10));
+        }
+        d.setUTCDate(d.getUTCDate() + 1);
+    }
+    return out;
+}
+function totalReturn(finalEquity, totalInvested) {
+    if (totalInvested === 0) {
+        return 0;
+    }
+    return finalEquity / totalInvested - 1;
+}
+function nearlyEqual(a, b) {
+    return Math.abs(a - b) <= EPSILON;
+}
+function formatPct(value) {
+    return `${(value * 100).toFixed(4)}%`;
+}