@samsmith2121/synthetic-leverage-engine 0.1.0

package/dist/src/simulator/index.d.ts

@@ -0,0 +1,4 @@
+import type { SimulatorBacktestRequest, SimulatorBacktestResponse, SimulatorMonteCarloRequest, SimulatorMonteCarloResponse } from './types';
+export type { SimulatorAnnualReturnPoint, SimulatorBacktestRequest, SimulatorBacktestResponse, SimulatorBacktestSeries, SimulatorBacktestSummary, SimulatorConfig, SimulatorDay, SimulatorMonteCarloPoint, SimulatorMonteCarloRequest, SimulatorMonteCarloResponse, SimulatorStrategy, SimulatorWarning, } from './types';
+export declare function runSingleBacktest(request: SimulatorBacktestRequest): SimulatorBacktestResponse;
+export declare function runMonteCarlo(request: SimulatorMonteCarloRequest): SimulatorMonteCarloResponse;

package/dist/src/simulator/index.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSingleBacktest = runSingleBacktest;
+exports.runMonteCarlo = runMonteCarlo;
+const backtest_1 = require("../backtest");
+const adapters_1 = require("./adapters");
+const monte_carlo_1 = require("./monte-carlo");
+const series_1 = require("./series");
+const TRADING_DAYS_PER_YEAR = 252;
+function runSingleBacktest(request) {
+    const prepared = (0, adapters_1.prepareSimulatorBacktest)(request);
+    const result = (0, backtest_1.runFixedBacktest)(prepared.engineDays, prepared.engineConfig);
+    return (0, series_1.buildSimulatorBacktestResponse)({
+        result,
+        initialEquity: request.config.initialEquity,
+    });
+}
+function runMonteCarlo(request) {
+    const prepared = (0, adapters_1.prepareSimulatorMonteCarlo)(request);
+    const result = (0, backtest_1.runMonteCarloBacktest)(prepared.engineDays, prepared.engineConfig, {
+        paths: request.simulations,
+        horizonDays: Math.max(1, request.years * TRADING_DAYS_PER_YEAR),
+        seed: request.randomSeed,
+    });
+    return (0, monte_carlo_1.buildSimulatorMonteCarloResponse)({
+        result,
+        years: request.years,
+        startDate: prepared.sourceDays[0]?.date ?? request.config.startDate ?? '1970-01-01',
+        initialEquity: request.config.initialEquity,
+    });
+}

package/dist/src/simulator/monte-carlo.d.ts

@@ -0,0 +1,8 @@
+import { MonteCarloResult } from '../types';
+import { SimulatorMonteCarloResponse } from './types';
+export declare function buildSimulatorMonteCarloResponse(params: {
+    result: MonteCarloResult;
+    years: number;
+    startDate: string;
+    initialEquity: number;
+}): SimulatorMonteCarloResponse;

package/dist/src/simulator/monte-carlo.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSimulatorMonteCarloResponse = buildSimulatorMonteCarloResponse;
+const metrics_1 = require("../metrics");
+const TRADING_DAYS_PER_YEAR = 252;
+function buildSimulatorMonteCarloResponse(params) {
+    const { result, years, startDate, initialEquity } = params;
+    const points = [];
+    const startYear = new Date(`${startDate}T00:00:00Z`).getUTCFullYear();
+    for (let step = 0; step <= years; step += 1) {
+        const equityValues = result.paths.map((path) => checkpointEquity(path.result, step, initialEquity));
+        const benchmarkValues = result.paths
+            .map((path) => checkpointBenchmarkEquity(path.result, step, initialEquity))
+            .filter((value) => value !== undefined);
+        points.push({
+            step,
+            label: String(startYear + step),
+            p10: (0, metrics_1.percentile)(equityValues, 0.1),
+            p25: (0, metrics_1.percentile)(equityValues, 0.25),
+            p50: (0, metrics_1.percentile)(equityValues, 0.5),
+            p75: (0, metrics_1.percentile)(equityValues, 0.75),
+            p90: (0, metrics_1.percentile)(equityValues, 0.9),
+            ...(benchmarkValues.length > 0 ? { benchmarkP50: (0, metrics_1.percentile)(benchmarkValues, 0.5) } : {}),
+        });
+    }
+    return {
+        monteCarlo: {
+            points,
+            warnings: mapMonteCarloWarnings(result.invariants),
+        },
+    };
+}
+function checkpointEquity(result, step, initialEquity) {
+    if (step === 0) {
+        return initialEquity;
+    }
+    const idx = Math.min(step * TRADING_DAYS_PER_YEAR - 1, result.daily.length - 1);
+    return result.daily[idx]?.equityEnd ?? result.finalEquity;
+}
+function checkpointBenchmarkEquity(result, step, initialEquity) {
+    if (step === 0) {
+        return initialEquity;
+    }
+    const benchmark = result.benchmark;
+    if (!benchmark) {
+        return undefined;
+    }
+    const targetDate = result.daily[Math.min(step * TRADING_DAYS_PER_YEAR - 1, result.daily.length - 1)]?.date;
+    if (!targetDate) {
+        return undefined;
+    }
+    const benchmarkIndex = benchmark.dates.findIndex((date) => date === targetDate);
+    if (benchmarkIndex === -1) {
+        return undefined;
+    }
+    return benchmark.benchmarkEquity[benchmarkIndex];
+}
+function mapMonteCarloWarnings(invariants) {
+    if (!invariants) {
+        return [];
+    }
+    const warnings = [];
+    if (!invariants.hasFiniteValues) {
+        warnings.push({
+            code: 'MC_HAS_NON_FINITE_VALUES',
+            message: 'Monte Carlo invariants found non-finite values in path outputs.',
+        });
+    }
+    if (!invariants.sameSeedReproducible) {
+        warnings.push({
+            code: 'MC_SEED_NOT_REPRODUCIBLE',
+            message: 'Monte Carlo same-seed reproducibility invariant failed.',
+        });
+    }
+    if (!invariants.differentSeedsCanDiffer) {
+        warnings.push({
+            code: 'MC_DIFFERENT_SEEDS_IDENTICAL',
+            message: 'Monte Carlo different-seed divergence invariant failed.',
+        });
+    }
+    if (!invariants.pathDatesStrictlyIncreasing) {
+        warnings.push({
+            code: 'MC_PATH_DATES_NOT_STRICTLY_INCREASING',
+            message: 'Monte Carlo path date ordering invariant failed.',
+        });
+    }
+    if (!invariants.percentileSummariesOrdered) {
+        warnings.push({
+            code: 'MC_PERCENTILES_NOT_ORDERED',
+            message: 'Monte Carlo percentile ordering invariant failed.',
+        });
+    }
+    return warnings;
+}

package/dist/src/simulator/series.d.ts

@@ -0,0 +1,6 @@
+import { BacktestResult } from '../types';
+import { SimulatorBacktestResponse } from './types';
+export declare function buildSimulatorBacktestResponse(params: {
+    result: BacktestResult;
+    initialEquity: number;
+}): SimulatorBacktestResponse;

package/dist/src/simulator/series.js

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSimulatorBacktestResponse = buildSimulatorBacktestResponse;
+const metrics_1 = require("../metrics");
+function buildSimulatorBacktestResponse(params) {
+    const { result, initialEquity } = params;
+    const xirr = computeBacktestXirr(result.daily, initialEquity);
+    const volatility = computeBacktestVolatility(result.daily);
+    const summary = buildSummary(result, initialEquity, xirr, volatility);
+    return {
+        run: {
+            ok: true,
+            summary,
+            series: buildSeries(result, initialEquity),
+            warnings: collectWarnings(result, xirr, volatility),
+        },
+    };
+}
+function buildSummary(result, initialEquity, xirr, volatility) {
+    const totalInvested = initialEquity + result.daily.reduce((sum, day) => sum + day.contribution, 0);
+    return {
+        finalEquity: result.finalEquity,
+        totalInvested,
+        twrCagr: result.twrCagr,
+        xirr,
+        maxDrawdown: result.maxDrawdown,
+        volatility,
+        totalTradeCost: result.daily.reduce((sum, day) => sum + day.tradeCost, 0),
+        totalBorrowCost: result.daily.reduce((sum, day) => sum + day.borrowDrag, 0),
+        totalErCost: result.daily.reduce((sum, day) => sum + day.expenseDrag, 0),
+        totalSwitches: countSwitches(result.daily),
+        benchmarkTotalReturn: result.benchmark?.benchmarkTotalReturn ?? null,
+        benchmarkTwrCagr: result.benchmark?.benchmarkTwrCagr ?? null,
+        benchmarkVolatility: result.benchmark?.benchmarkVolatility ?? null,
+        benchmarkMaxDrawdown: result.benchmark?.benchmarkMaxDrawdown ?? null,
+        excessTotalReturn: result.benchmark?.excessTotalReturn ?? null,
+        excessTwrCagr: result.benchmark?.excessTwrCagr ?? null,
+        trackingError: result.benchmark?.trackingError ?? null,
+    };
+}
+function buildSeries(result, initialEquity) {
+    return {
+        equityCurve: result.daily.map((state) => point(state.date, state.equityEnd)),
+        benchmarkCurve: result.benchmark
+            ? result.benchmark.dates.map((date, index) => point(date, result.benchmark?.benchmarkEquity[index] ?? 0))
+            : undefined,
+        drawdownCurve: buildDrawdownCurve(result.daily, initialEquity),
+        leverageCurve: result.daily.map((state) => point(state.date, state.appliedPosition)),
+        returnSeries: result.daily.map((state) => point(state.date, state.capitalBaseBeforeReturn === 0 ? 0 : state.equityEnd / state.capitalBaseBeforeReturn - 1)),
+        annualReturns: buildAnnualReturns(result.daily, initialEquity),
+    };
+}
+function buildDrawdownCurve(daily, initialEquity) {
+    const out = [];
+    let peak = initialEquity;
+    for (const state of daily) {
+        peak = Math.max(peak, state.equityEnd);
+        const drawdown = peak > 0 ? (state.equityEnd - peak) / peak : 0;
+        out.push(point(state.date, drawdown));
+    }
+    return out;
+}
+function buildAnnualReturns(daily, initialEquity) {
+    const buckets = new Map();
+    let priorYearEnd = initialEquity;
+    for (const state of daily) {
+        const year = new Date(`${state.date}T00:00:00Z`).getUTCFullYear();
+        const existing = buckets.get(year);
+        if (!existing) {
+            buckets.set(year, { start: priorYearEnd, end: state.equityEnd });
+        }
+        else {
+            existing.end = state.equityEnd;
+        }
+        priorYearEnd = state.equityEnd;
+    }
+    return [...buckets.entries()].map(([year, values]) => ({
+        year,
+        value: values.start === 0 ? 0 : values.end / values.start - 1,
+    }));
+}
+function computeBacktestXirr(daily, initialEquity) {
+    return (0, metrics_1.computeXirr)(buildCashFlows(daily, initialEquity));
+}
+function computeBacktestVolatility(daily) {
+    return (0, metrics_1.computeVolatilityFromReturns)(daily.map((state) => state.capitalBaseBeforeReturn === 0 ? 0 : state.equityEnd / state.capitalBaseBeforeReturn - 1));
+}
+function buildCashFlows(daily, initialEquity) {
+    if (daily.length === 0) {
+        return [];
+    }
+    const flows = [{ date: daily[0].date, amount: -initialEquity }];
+    for (const state of daily) {
+        if (state.contribution !== 0) {
+            flows.push({ date: state.date, amount: -state.contribution });
+        }
+    }
+    flows.push({ date: daily[daily.length - 1].date, amount: daily[daily.length - 1].equityEnd });
+    return flows;
+}
+function countSwitches(daily) {
+    let switches = 0;
+    for (const state of daily) {
+        if (Math.abs(state.appliedPosition - state.priorAppliedPosition) > 1e-12) {
+            switches += 1;
+        }
+    }
+    return switches;
+}
+function collectWarnings(result, xirr, volatility) {
+    const warnings = [];
+    const benchmarkDates = result.benchmark?.dates.length ?? 0;
+    if (benchmarkDates === 0) {
+        warnings.push({
+            code: 'BENCHMARK_UNAVAILABLE',
+            message: 'No benchmark overlap was available for matched-date benchmark analytics.',
+        });
+    }
+    else if (benchmarkDates < result.daily.length) {
+        warnings.push({
+            code: 'BENCHMARK_PARTIAL_COVERAGE',
+            message: 'Benchmark analytics use matched dates only because benchmark coverage is partial.',
+            context: {
+                benchmarkDays: benchmarkDates,
+                totalDays: result.daily.length,
+                coveragePct: benchmarkDates / result.daily.length,
+            },
+        });
+    }
+    if (result.twrCagr === null) {
+        warnings.push({
+            code: 'TWR_CAGR_UNAVAILABLE',
+            message: 'TWR CAGR is unavailable for the provided backtest window.',
+        });
+    }
+    if (xirr === null) {
+        warnings.push({
+            code: 'XIRR_UNAVAILABLE',
+            message: 'XIRR is unavailable for the provided cash-flow schedule.',
+        });
+    }
+    if (volatility === null) {
+        warnings.push({
+            code: 'VOLATILITY_UNAVAILABLE',
+            message: 'Volatility is unavailable for the provided backtest window.',
+        });
+    }
+    return warnings;
+}
+function point(date, value) {
+    return { date, value };
+}

package/dist/src/simulator/types.d.ts

@@ -0,0 +1,111 @@
+export interface SimulatorDay {
+    date: string;
+    assetClose: number;
+    benchmarkClose?: number;
+    indicatorClose?: number;
+    financingRateAnnual?: number;
+}
+export interface SimulatorConfig {
+    initialEquity: number;
+    monthlyContribution: number;
+    tradeSpreadPct: number;
+    borrowSpreadPct: number;
+    expenseRatioPct: number;
+    startDate?: string;
+    endDate?: string;
+}
+export interface SimulatorStrategy {
+    name: string;
+    leverageMultiple: number;
+    vixDefensiveExposure: number;
+    signal: {
+        useSma: boolean;
+        smaLength: number;
+        exposureAboveSignal?: number;
+        exposureBelowSignal?: number;
+        useVixThreshold: boolean;
+        vixThreshold: number;
+    };
+    rateSource: {
+        mode: 'builtin' | 'fixed' | 'series';
+        fixedRatePct?: number;
+        seriesId?: string;
+    };
+}
+export interface SimulatorBacktestRequest {
+    days: SimulatorDay[];
+    config: SimulatorConfig;
+    strategy: SimulatorStrategy;
+}
+export interface SimulatorWarning {
+    code: string;
+    message: string;
+    context?: Record<string, string | number | boolean | null>;
+}
+export interface SimulatorSeriesPoint {
+    date: string;
+    value: number;
+}
+export interface SimulatorAnnualReturnPoint {
+    year: number;
+    value: number;
+}
+export interface SimulatorBacktestSummary {
+    finalEquity: number;
+    totalInvested: number;
+    twrCagr: number | null;
+    xirr: number | null;
+    maxDrawdown: number;
+    volatility: number | null;
+    totalTradeCost: number;
+    totalBorrowCost: number;
+    totalErCost: number;
+    totalSwitches: number;
+    benchmarkTotalReturn?: number | null;
+    benchmarkTwrCagr?: number | null;
+    benchmarkVolatility?: number | null;
+    benchmarkMaxDrawdown?: number | null;
+    excessTotalReturn?: number | null;
+    excessTwrCagr?: number | null;
+    trackingError?: number | null;
+}
+export interface SimulatorBacktestSeries {
+    equityCurve: SimulatorSeriesPoint[];
+    benchmarkCurve?: SimulatorSeriesPoint[];
+    drawdownCurve: SimulatorSeriesPoint[];
+    leverageCurve: SimulatorSeriesPoint[];
+    returnSeries: SimulatorSeriesPoint[];
+    annualReturns: SimulatorAnnualReturnPoint[];
+}
+export interface SimulatorBacktestResponse {
+    run: {
+        ok: boolean;
+        summary: SimulatorBacktestSummary;
+        series: SimulatorBacktestSeries;
+        warnings: SimulatorWarning[];
+    };
+}
+export interface SimulatorMonteCarloRequest {
+    days: SimulatorDay[];
+    config: SimulatorConfig;
+    strategy: SimulatorStrategy;
+    years: number;
+    simulations: number;
+    randomSeed?: number;
+}
+export interface SimulatorMonteCarloPoint {
+    step: number;
+    label: string;
+    p10: number;
+    p25: number;
+    p50: number;
+    p75: number;
+    p90: number;
+    benchmarkP50?: number;
+}
+export interface SimulatorMonteCarloResponse {
+    monteCarlo: {
+        points: SimulatorMonteCarloPoint[];
+        warnings: SimulatorWarning[];
+    };
+}

package/dist/src/simulator/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/step.d.ts

@@ -0,0 +1,24 @@
+import { BacktestResult, DailyState, DayInput, EngineConfig } from './types';
+export interface StepInput {
+    day: DayInput;
+    previousDay?: DayInput;
+    previousState?: DailyState;
+    previousTargetPosition: number;
+    previousAppliedPosition: number;
+    previousBorrowRateDaily: number;
+    config: EngineConfig;
+}
+/**
+ * Canonical daily engine step using locked order:
+ * 1) read day t inputs
+ * 2) compute signal(t)
+ * 3) derive targetPosition(t)
+ * 4) appliedPosition(t)=targetPosition(t-1)
+ * 5) contribution before return
+ * 6) trade cost at start of day on turnover
+ * 7) apply return
+ * 8) apply borrow + ER drag
+ * 9) save end-of-day state
+ */
+export declare function runDayStep(input: StepInput): DailyState;
+export declare function summarizeResult(daily: DailyState[]): BacktestResult;

package/dist/src/step.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDayStep = runDayStep;
+exports.summarizeResult = summarizeResult;
+const metrics_1 = require("./metrics");
+const costs_1 = require("./costs");
+const contributions_1 = require("./contributions");
+const signal_1 = require("./signal");
+/**
+ * Canonical daily engine step using locked order:
+ * 1) read day t inputs
+ * 2) compute signal(t)
+ * 3) derive targetPosition(t)
+ * 4) appliedPosition(t)=targetPosition(t-1)
+ * 5) contribution before return
+ * 6) trade cost at start of day on turnover
+ * 7) apply return
+ * 8) apply borrow + ER drag
+ * 9) save end-of-day state
+ */
+function runDayStep(input) {
+    const { day, previousDay, previousState, previousTargetPosition, previousAppliedPosition, config } = input;
+    const equityStart = previousState?.equityEnd ?? config.initialEquity;
+    const signalContext = (0, signal_1.buildSignalContext)(day, previousDay);
+    const signal = (0, signal_1.computeSignal)(signalContext);
+    const targetPosition = (0, signal_1.deriveTargetPosition)(signal, config);
+    // T+1 fixed-path behavior: today's applied position is yesterday's target position.
+    const appliedPosition = previousTargetPosition;
+    const contribution = (0, contributions_1.getContributionForDay)(day);
+    const capitalBaseBeforeReturn = (0, contributions_1.applyContribution)(equityStart, contribution);
+    const turnoverNotional = (0, costs_1.calculateTurnoverNotional)(appliedPosition, previousAppliedPosition, capitalBaseBeforeReturn);
+    const tradeCost = (0, costs_1.calculateTradeCost)(turnoverNotional, config.tradeCostRate, day.tradeSpread ?? 0);
+    const equityAfterTradeCost = capitalBaseBeforeReturn - tradeCost;
+    const grossAssetPnl = equityAfterTradeCost * appliedPosition * day.assetReturn;
+    const cashYieldDaily = config.cashYieldDaily ?? 0;
+    const cashWeight = Math.max(0, 1 - Math.abs(appliedPosition));
+    const cashPnl = equityAfterTradeCost * cashWeight * cashYieldDaily;
+    const grossPnl = grossAssetPnl + cashPnl;
+    const equityAfterReturn = equityAfterTradeCost + grossPnl;
+    const borrowRateDaily = day.borrowRateDaily ?? input.previousBorrowRateDaily;
+    const expenseRatioDaily = (0, costs_1.annualToDailyRate)(day.expenseRatioAnnual ?? 0);
+    const borrowDrag = (0, costs_1.calculateBorrowDrag)(appliedPosition, equityAfterTradeCost, borrowRateDaily);
+    const expenseDrag = (0, costs_1.calculateExpenseDrag)(equityAfterTradeCost, expenseRatioDaily);
+    const equityEnd = equityAfterReturn - borrowDrag - expenseDrag;
+    const netPnl = equityEnd - equityStart - contribution;
+    return {
+        date: day.date,
+        equityStart,
+        contribution,
+        capitalBaseBeforeReturn,
+        equityAfterTradeCost,
+        equityEnd,
+        signal,
+        targetPosition,
+        appliedPosition,
+        priorAppliedPosition: previousAppliedPosition,
+        turnoverNotional,
+        tradeCost,
+        grossPnl,
+        borrowDrag,
+        expenseDrag,
+        netPnl,
+        borrowRateDaily,
+        expenseRatioDaily,
+    };
+}
+function summarizeResult(daily) {
+    const equityCurve = daily.map((state) => state.equityEnd);
+    return {
+        daily,
+        finalEquity: daily.length > 0 ? daily[daily.length - 1].equityEnd : 0,
+        twrCagr: (0, metrics_1.computeTwrCagr)(daily),
+        maxDrawdown: (0, metrics_1.computeMaxDrawdownFromEquity)(equityCurve),
+    };
+}

package/dist/src/types.d.ts

@@ -0,0 +1,145 @@
+export interface DayInput {
+    date: string;
+    assetReturn: number;
+    /** Optional benchmark return used in aligned benchmark comparison. */
+    benchmarkReturn?: number;
+    /** Signal source for day t. Signal is computed on day t and applied on day t+1. */
+    signalInput: number;
+    /** Optional scheduled contribution for day t (applied before return). */
+    contribution?: number;
+    /** Daily borrow rate override; missing values carry forward prior known rate. */
+    borrowRateDaily?: number;
+    /** Optional annualized expense ratio. Converted to daily inside the engine. */
+    expenseRatioAnnual?: number;
+    /** Optional day-level trading spread surcharge applied to turnover notional. */
+    tradeSpread?: number;
+}
+export interface EngineConfig {
+    initialEquity: number;
+    /** Target position used prior to first bar. */
+    initialTargetPosition?: number;
+    /** Applied position on the day before the first bar. */
+    initialAppliedPosition?: number;
+    /** Trade-cost rate charged on turnover notional at start of day. */
+    tradeCostRate: number;
+    /** Maximum absolute leverage allowed for target positions. */
+    maxLeverage: number;
+    /**
+     * Explicit initial borrow rate requirement.
+     * If day 1 has no borrowRateDaily, this field must be provided.
+     */
+    initialBorrowRateDaily?: number;
+    /**
+     * Cash mode assumption for this milestone: zero yield unless explicitly configured.
+     * Kept as configurable for future milestones.
+     */
+    cashYieldDaily?: number;
+    /** When true, invariant checks run after each backtest. */
+    enableInvariantChecks?: boolean;
+}
+export interface SignalContext {
+    day: DayInput;
+    previousDay?: DayInput;
+}
+export interface DailyState {
+    date: string;
+    equityStart: number;
+    contribution: number;
+    /** External-flow-adjusted capital base before internal performance effects. */
+    capitalBaseBeforeReturn: number;
+    equityAfterTradeCost: number;
+    equityEnd: number;
+    signal: number;
+    targetPosition: number;
+    appliedPosition: number;
+    priorAppliedPosition: number;
+    turnoverNotional: number;
+    tradeCost: number;
+    grossPnl: number;
+    borrowDrag: number;
+    expenseDrag: number;
+    netPnl: number;
+    borrowRateDaily: number;
+    expenseRatioDaily: number;
+}
+export interface BacktestResult {
+    daily: DailyState[];
+    finalEquity: number;
+    twrCagr: number | null;
+    maxDrawdown: number;
+    benchmark?: BenchmarkComparison | null;
+    invariants?: BacktestInvariantReport;
+}
+export interface BenchmarkComparison {
+    dates: string[];
+    strategyReturns: number[];
+    benchmarkReturns: number[];
+    strategyEquity: number[];
+    benchmarkEquity: number[];
+    benchmarkTotalReturn: number;
+    benchmarkTwrCagr: number | null;
+    benchmarkVolatility: number | null;
+    benchmarkMaxDrawdown: number;
+    excessTotalReturn: number | null;
+    excessTwrCagr: number | null;
+    trackingError: number | null;
+}
+export interface EquityPoint {
+    date: string;
+    equity: number;
+}
+export interface ReturnPoint {
+    date: string;
+    value: number;
+}
+export interface CashFlowPoint {
+    date: string;
+    amount: number;
+}
+export interface MonteCarloConfig {
+    paths: number;
+    horizonDays: number;
+    seed?: number;
+    blockLength?: number;
+}
+export interface MonteCarloPathResult {
+    index: number;
+    seed: number;
+    result: BacktestResult;
+}
+export interface MonteCarloResult {
+    config: MonteCarloConfig;
+    paths: MonteCarloPathResult[];
+    summary: MonteCarloSummary;
+    invariants?: MonteCarloInvariantReport;
+}
+export interface PercentileSummary {
+    p5: number;
+    p50: number;
+    p95: number;
+}
+export interface MonteCarloSummary {
+    endingEquity: PercentileSummary;
+    twrCagr: PercentileSummary;
+    maxDrawdown: PercentileSummary;
+    medianEndingEquity: number;
+    medianTwrCagr: number;
+    medianMaxDrawdown: number;
+}
+export interface BacktestInvariantReport {
+    hasFiniteValues: boolean;
+    noSameDaySignalLeakage: boolean;
+    contributionBeforeReturnOrdering: boolean;
+    tradeCostZeroWithoutPositionChange: boolean;
+    borrowCostZeroAtOrBelowOneX: boolean;
+    borrowCostZeroInCashMode: boolean;
+    benchmarkMatchedDatesOnly: boolean;
+    isDailyDateSequenceStrictlyIncreasing: boolean;
+}
+export interface MonteCarloInvariantReport {
+    hasFiniteValues: boolean;
+    sameSeedReproducible: boolean;
+    differentSeedsCanDiffer: boolean;
+    pathDatesStrictlyIncreasing: boolean;
+    percentileSummariesOrdered: boolean;
+}

package/dist/src/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/validation-cases.d.ts

@@ -0,0 +1,21 @@
+export type ValidationStatus = 'PASS' | 'FAIL' | 'WARN';
+export interface ValidationResult {
+    id: string;
+    name: string;
+    status: ValidationStatus;
+    actual: string;
+    expected: string;
+    core: boolean;
+}
+export interface ValidationSummary {
+    total: number;
+    passed: number;
+    failed: number;
+    warnings: number;
+    failedCore: number;
+}
+export interface ValidationRun {
+    results: ValidationResult[];
+    summary: ValidationSummary;
+}
+export declare function runModelValidationCases(): ValidationRun;