@samsmith2121/synthetic-leverage-engine 0.1.0

package/dist/src/public-api.d.ts

@@ -0,0 +1,89 @@
+import { ParameterSweepConfig, ParameterSweepGrid, ParameterSweepResult, ScenarioAnalysisResult, ScenarioDefinition, StrategyConfigComparison, StrategyRunResult, StrategyVariant, SweepRankMetric } from './analysis';
+import { toBacktestSummaryExportRows, toDiagnosticsExportRows, toParameterSweepExportRows, toScenarioExportRows, toStrategyComparisonRows } from './reporting';
+import { DayInput, EngineConfig, MonteCarloConfig, MonteCarloSummary } from './types';
+export interface SingleBacktestRequest {
+    days: DayInput[];
+    config: EngineConfig;
+    strategy: StrategyVariant;
+}
+export interface SingleBacktestResponse {
+    run: StrategyRunResult;
+}
+export interface StrategyComparisonRequest {
+    days: DayInput[];
+    config: EngineConfig;
+    strategies: StrategyVariant[];
+    rankBy?: SweepRankMetric;
+}
+export interface StrategyComparisonResponse {
+    comparison: StrategyConfigComparison;
+}
+export interface ParameterSweepRequest {
+    days: DayInput[];
+    config: EngineConfig;
+    grid: ParameterSweepGrid;
+    options?: ParameterSweepConfig;
+}
+export interface ParameterSweepResponse {
+    sweep: ParameterSweepResult;
+}
+export interface ScenarioAnalysisRequest {
+    days: DayInput[];
+    config: EngineConfig;
+    strategy: StrategyVariant;
+    scenarios: ScenarioDefinition[];
+    includeFullPeriod?: boolean;
+}
+export interface ScenarioAnalysisResponse {
+    scenarios: ScenarioAnalysisResult;
+}
+export interface DiagnosticsRequest {
+    days: DayInput[];
+    config: EngineConfig;
+    strategies: StrategyVariant[];
+    rankBy?: SweepRankMetric;
+}
+export interface DiagnosticsResponse {
+    comparison: StrategyConfigComparison;
+    diagnosticsRows: ReturnType<typeof toDiagnosticsExportRows>;
+}
+export interface MonteCarloRequest {
+    days: DayInput[];
+    config: EngineConfig;
+    monteCarlo: MonteCarloConfig;
+}
+export type MonteCarloWarningCode = 'MC_HAS_NON_FINITE_VALUES' | 'MC_SEED_NOT_REPRODUCIBLE' | 'MC_DIFFERENT_SEEDS_IDENTICAL' | 'MC_PATH_DATES_NOT_STRICTLY_INCREASING' | 'MC_PERCENTILES_NOT_ORDERED';
+export interface MonteCarloWarning {
+    code: MonteCarloWarningCode;
+    message: string;
+    context?: Record<string, string | number | boolean | null>;
+}
+export interface MonteCarloResponse {
+    config: MonteCarloConfig;
+    summary: MonteCarloSummary;
+    pathCount: number;
+    warnings: MonteCarloWarning[];
+}
+export interface ExportRowsRequest {
+    comparison?: StrategyConfigComparison;
+    sweep?: ParameterSweepResult;
+    scenarios?: ScenarioAnalysisResult;
+}
+export interface ExportRowsResponse {
+    comparisonRows?: ReturnType<typeof toStrategyComparisonRows>;
+    backtestSummaryRows?: ReturnType<typeof toBacktestSummaryExportRows>;
+    sweepRows?: ReturnType<typeof toParameterSweepExportRows>;
+    scenarioRows?: ReturnType<typeof toScenarioExportRows>;
+    diagnosticsRows?: ReturnType<typeof toDiagnosticsExportRows>;
+}
+/**
+ * UI-focused facade for engine integration.
+ * Financial logic remains inside analysis/backtest modules.
+ */
+export declare function runSingleBacktest(request: SingleBacktestRequest): SingleBacktestResponse;
+export declare function runComparison(request: StrategyComparisonRequest): StrategyComparisonResponse;
+export declare function runSweep(request: ParameterSweepRequest): ParameterSweepResponse;
+export declare function runScenarios(request: ScenarioAnalysisRequest): ScenarioAnalysisResponse;
+export declare function runDiagnostics(request: DiagnosticsRequest): DiagnosticsResponse;
+export declare function runMonteCarlo(request: MonteCarloRequest): MonteCarloResponse;
+export declare function buildExportRows(request: ExportRowsRequest): ExportRowsResponse;

package/dist/src/public-api.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSingleBacktest = runSingleBacktest;
+exports.runComparison = runComparison;
+exports.runSweep = runSweep;
+exports.runScenarios = runScenarios;
+exports.runDiagnostics = runDiagnostics;
+exports.runMonteCarlo = runMonteCarlo;
+exports.buildExportRows = buildExportRows;
+const analysis_1 = require("./analysis");
+const backtest_1 = require("./backtest");
+const reporting_1 = require("./reporting");
+/**
+ * UI-focused facade for engine integration.
+ * Financial logic remains inside analysis/backtest modules.
+ */
+function runSingleBacktest(request) {
+    const comparison = (0, analysis_1.runStrategyComparison)(request.days, request.config, [request.strategy]);
+    return {
+        run: comparison.runs[0],
+    };
+}
+function runComparison(request) {
+    return {
+        comparison: (0, analysis_1.runStrategyComparison)(request.days, request.config, request.strategies, request.rankBy),
+    };
+}
+function runSweep(request) {
+    return {
+        sweep: (0, analysis_1.runParameterSweep)(request.days, request.config, request.grid, request.options),
+    };
+}
+function runScenarios(request) {
+    return {
+        scenarios: (0, analysis_1.runScenarioAnalysis)(request.days, request.config, request.strategy, request.scenarios, request.includeFullPeriod),
+    };
+}
+function runDiagnostics(request) {
+    const comparison = (0, analysis_1.runStrategyComparison)(request.days, request.config, request.strategies, request.rankBy);
+    return {
+        comparison,
+        diagnosticsRows: (0, reporting_1.toDiagnosticsExportRows)(comparison),
+    };
+}
+function runMonteCarlo(request) {
+    const result = (0, backtest_1.runMonteCarloBacktest)(request.days, request.config, request.monteCarlo);
+    return {
+        config: result.config,
+        summary: result.summary,
+        pathCount: result.paths.length,
+        warnings: mapMonteCarloWarnings(result.invariants),
+    };
+}
+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;
+}
+function buildExportRows(request) {
+    return {
+        ...(request.comparison
+            ? {
+                comparisonRows: (0, reporting_1.toStrategyComparisonRows)(request.comparison),
+                backtestSummaryRows: (0, reporting_1.toBacktestSummaryExportRows)(request.comparison),
+                diagnosticsRows: (0, reporting_1.toDiagnosticsExportRows)(request.comparison),
+            }
+            : {}),
+        ...(request.sweep ? { sweepRows: (0, reporting_1.toParameterSweepExportRows)(request.sweep) } : {}),
+        ...(request.scenarios ? { scenarioRows: (0, reporting_1.toScenarioExportRows)(request.scenarios) } : {}),
+    };
+}

package/dist/src/reporting.d.ts

@@ -0,0 +1,112 @@
+import { AnalysisRunSummary, OneWaySensitivityResult, ParameterSweepResult, ScenarioAnalysisResult, StrategyConfigComparison, SweepResultRow, TwoWaySensitivityResult } from './analysis';
+export interface StrategyComparisonRow {
+    strategyName: string;
+    finalEquity: number;
+    totalInvested: number;
+    twrCagr: number | null;
+    xirr: number | null;
+    maxDrawdown: number;
+    volatility: number | null;
+    totalTradeCost: number;
+    totalBorrowCost: number;
+    totalErCost: number;
+    totalSwitches: number;
+    excessTotalReturn?: number | null;
+    excessTwrCagr?: number | null;
+    trackingError?: number | null;
+}
+export interface AnalysisReport {
+    generatedAt: string;
+    comparisonRows: StrategyComparisonRow[];
+    sweepRows: SweepResultRow[];
+    scenarioRows: Array<{
+        scenarioName: string;
+        startDate: string;
+        endDate: string;
+        summary?: AnalysisRunSummary;
+        error?: string;
+        warningCodes: string[];
+    }>;
+}
+export interface BacktestSummaryExportRow {
+    strategy_name: string;
+    final_equity: number;
+    total_invested: number;
+    twr_cagr: number | null;
+    xirr: number | null;
+    max_drawdown: number;
+    volatility: number | null;
+    total_trade_cost: number;
+    total_borrow_cost: number;
+    total_er_cost: number;
+    total_switches: number;
+    excess_twr_cagr: number | null;
+}
+export interface ParameterSweepExportRow {
+    strategy_name: string;
+    vix_threshold: number;
+    leverage_multiple: number;
+    trade_spread: number;
+    expense_ratio_annual: number;
+    cash_mode: string;
+    cash_yield_daily: number;
+    monte_carlo_block_length: number | null;
+    run_ok: boolean;
+    twr_cagr: number | null;
+    xirr: number | null;
+    max_drawdown: number | null;
+    excess_twr_cagr: number | null;
+    warning_codes: string;
+    error: string | null;
+}
+export interface ScenarioExportRow {
+    scenario_name: string;
+    start_date: string;
+    end_date: string;
+    strategy_name: string;
+    run_ok: boolean;
+    twr_cagr: number | null;
+    xirr: number | null;
+    max_drawdown: number | null;
+    warning_codes: string;
+    error: string | null;
+}
+export interface SensitivityExportRow {
+    analysis_type: 'one_way' | 'two_way';
+    parameter_x: string;
+    value_x: number | string;
+    parameter_y: string | null;
+    value_y: number | string | null;
+    strategy_name: string;
+    run_ok: boolean;
+    twr_cagr: number | null;
+    xirr: number | null;
+    max_drawdown: number | null;
+    excess_twr_cagr: number | null;
+    warning_codes: string;
+    error: string | null;
+}
+export interface DiagnosticsExportRow {
+    strategy_name: string;
+    pct_days_cash: number;
+    pct_days_one_x: number;
+    pct_days_leveraged: number;
+    average_applied_leverage: number;
+    total_switches: number;
+    total_cost: number;
+    trade_cost_share: number;
+    borrow_cost_share: number;
+    er_cost_share: number;
+    max_drawdown: number;
+    max_drawdown_duration_days: number;
+    outperform_pct: number | null;
+    excess_twr_cagr: number | null;
+}
+export declare function toStrategyComparisonRows(comparison: StrategyConfigComparison): StrategyComparisonRow[];
+export declare function toBacktestSummaryExportRows(comparison: StrategyConfigComparison): BacktestSummaryExportRow[];
+export declare function toParameterSweepExportRows(sweep: ParameterSweepResult): ParameterSweepExportRow[];
+export declare function toScenarioExportRows(result: ScenarioAnalysisResult): ScenarioExportRow[];
+export declare function toOneWaySensitivityExportRows(result: OneWaySensitivityResult): SensitivityExportRow[];
+export declare function toTwoWaySensitivityExportRows(result: TwoWaySensitivityResult): SensitivityExportRow[];
+export declare function toDiagnosticsExportRows(comparison: StrategyConfigComparison): DiagnosticsExportRow[];
+export declare function buildAnalysisReport(comparison: StrategyConfigComparison, sweep: ParameterSweepResult, scenarios: ScenarioAnalysisResult): AnalysisReport;

package/dist/src/reporting.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toStrategyComparisonRows = toStrategyComparisonRows;
+exports.toBacktestSummaryExportRows = toBacktestSummaryExportRows;
+exports.toParameterSweepExportRows = toParameterSweepExportRows;
+exports.toScenarioExportRows = toScenarioExportRows;
+exports.toOneWaySensitivityExportRows = toOneWaySensitivityExportRows;
+exports.toTwoWaySensitivityExportRows = toTwoWaySensitivityExportRows;
+exports.toDiagnosticsExportRows = toDiagnosticsExportRows;
+exports.buildAnalysisReport = buildAnalysisReport;
+function toStrategyComparisonRows(comparison) {
+    return comparison.runs
+        .filter((run) => run.ok)
+        .map((run) => ({
+        strategyName: run.strategy.name,
+        finalEquity: run.summary.finalEquity,
+        totalInvested: run.summary.totalInvested,
+        twrCagr: run.summary.twrCagr,
+        xirr: run.summary.xirr,
+        maxDrawdown: run.summary.maxDrawdown,
+        volatility: run.summary.volatility,
+        totalTradeCost: run.summary.totalTradeCost,
+        totalBorrowCost: run.summary.totalBorrowCost,
+        totalErCost: run.summary.totalErCost,
+        totalSwitches: run.summary.totalSwitches,
+        ...(run.summary.benchmark
+            ? {
+                excessTotalReturn: run.summary.benchmark.excessTotalReturn,
+                excessTwrCagr: run.summary.benchmark.excessTwrCagr,
+                trackingError: run.summary.benchmark.trackingError,
+            }
+            : {}),
+    }));
+}
+function toBacktestSummaryExportRows(comparison) {
+    return comparison.runs
+        .filter((run) => run.ok)
+        .map((run) => ({
+        strategy_name: run.strategy.name,
+        final_equity: run.summary.finalEquity,
+        total_invested: run.summary.totalInvested,
+        twr_cagr: run.summary.twrCagr,
+        xirr: run.summary.xirr,
+        max_drawdown: run.summary.maxDrawdown,
+        volatility: run.summary.volatility,
+        total_trade_cost: run.summary.totalTradeCost,
+        total_borrow_cost: run.summary.totalBorrowCost,
+        total_er_cost: run.summary.totalErCost,
+        total_switches: run.summary.totalSwitches,
+        excess_twr_cagr: run.summary.benchmark?.excessTwrCagr ?? null,
+    }));
+}
+function toParameterSweepExportRows(sweep) {
+    return sweep.rows.map((row) => ({
+        strategy_name: row.strategyName,
+        vix_threshold: row.vixThreshold,
+        leverage_multiple: row.leverageMultiple,
+        trade_spread: row.tradeSpread,
+        expense_ratio_annual: row.expenseRatioAnnual,
+        cash_mode: row.cashMode,
+        cash_yield_daily: row.cashYieldDaily,
+        monte_carlo_block_length: row.monteCarloBlockLength ?? null,
+        run_ok: row.run.ok,
+        twr_cagr: row.run.ok ? row.run.summary.twrCagr : null,
+        xirr: row.run.ok ? row.run.summary.xirr : null,
+        max_drawdown: row.run.ok ? row.run.summary.maxDrawdown : null,
+        excess_twr_cagr: row.run.ok ? row.run.summary.benchmark?.excessTwrCagr ?? null : null,
+        warning_codes: row.run.warnings.map((warning) => warning.code).join('|'),
+        error: row.run.ok ? null : row.run.error,
+    }));
+}
+function toScenarioExportRows(result) {
+    return result.rows.map((row) => ({
+        scenario_name: row.scenarioName,
+        start_date: row.startDate,
+        end_date: row.endDate,
+        strategy_name: row.run.strategy.name,
+        run_ok: row.run.ok,
+        twr_cagr: row.run.ok ? row.run.summary.twrCagr : null,
+        xirr: row.run.ok ? row.run.summary.xirr : null,
+        max_drawdown: row.run.ok ? row.run.summary.maxDrawdown : null,
+        warning_codes: row.warnings.map((warning) => warning.code).join('|'),
+        error: row.run.ok ? null : row.run.error,
+    }));
+}
+function toOneWaySensitivityExportRows(result) {
+    return result.rows.map((row) => ({
+        analysis_type: 'one_way',
+        parameter_x: row.parameter,
+        value_x: row.parameterValue,
+        parameter_y: null,
+        value_y: null,
+        strategy_name: row.run.strategy.name,
+        run_ok: row.run.ok,
+        twr_cagr: row.run.ok ? row.run.summary.twrCagr : null,
+        xirr: row.run.ok ? row.run.summary.xirr : null,
+        max_drawdown: row.run.ok ? row.run.summary.maxDrawdown : null,
+        excess_twr_cagr: row.run.ok ? row.run.summary.benchmark?.excessTwrCagr ?? null : null,
+        warning_codes: row.run.warnings.map((warning) => warning.code).join('|'),
+        error: row.run.ok ? null : row.run.error,
+    }));
+}
+function toTwoWaySensitivityExportRows(result) {
+    return result.cells.map((cell) => ({
+        analysis_type: 'two_way',
+        parameter_x: cell.xParameter,
+        value_x: cell.xValue,
+        parameter_y: cell.yParameter,
+        value_y: cell.yValue,
+        strategy_name: cell.run.strategy.name,
+        run_ok: cell.run.ok,
+        twr_cagr: cell.run.ok ? cell.run.summary.twrCagr : null,
+        xirr: cell.run.ok ? cell.run.summary.xirr : null,
+        max_drawdown: cell.run.ok ? cell.run.summary.maxDrawdown : null,
+        excess_twr_cagr: cell.run.ok ? cell.run.summary.benchmark?.excessTwrCagr ?? null : null,
+        warning_codes: cell.run.warnings.map((warning) => warning.code).join('|'),
+        error: cell.run.ok ? null : cell.run.error,
+    }));
+}
+function toDiagnosticsExportRows(comparison) {
+    return comparison.runs
+        .filter((run) => run.ok)
+        .map((run) => mapDiagnostics(run.strategy.name, run.summary.diagnostics));
+}
+function buildAnalysisReport(comparison, sweep, scenarios) {
+    return {
+        generatedAt: new Date().toISOString(),
+        comparisonRows: toStrategyComparisonRows(comparison),
+        sweepRows: sweep.rows,
+        scenarioRows: scenarios.rows.map((row) => ({
+            scenarioName: row.scenarioName,
+            startDate: row.startDate,
+            endDate: row.endDate,
+            ...(row.run.ok ? { summary: row.run.summary } : { error: row.run.error }),
+            warningCodes: row.warnings.map((warning) => warning.code),
+        })),
+    };
+}
+function mapDiagnostics(strategyName, diagnostics) {
+    return {
+        strategy_name: strategyName,
+        pct_days_cash: diagnostics.exposure.pctDaysCash,
+        pct_days_one_x: diagnostics.exposure.pctDaysOneX,
+        pct_days_leveraged: diagnostics.exposure.pctDaysLeveraged,
+        average_applied_leverage: diagnostics.exposure.averageAppliedLeverage,
+        total_switches: diagnostics.transitions.totalSwitches,
+        total_cost: diagnostics.costs.totalCost,
+        trade_cost_share: diagnostics.costs.tradeCostShare,
+        borrow_cost_share: diagnostics.costs.borrowCostShare,
+        er_cost_share: diagnostics.costs.erCostShare,
+        max_drawdown: diagnostics.drawdown.maxDrawdown,
+        max_drawdown_duration_days: diagnostics.drawdown.maxDrawdownDurationDays,
+        outperform_pct: diagnostics.benchmarkRelative?.outperformPct ?? null,
+        excess_twr_cagr: diagnostics.benchmarkRelative?.excessTwrCagr ?? null,
+    };
+}

package/dist/src/signal.d.ts

@@ -0,0 +1,34 @@
+import { DayInput, EngineConfig, SignalContext } from './types';
+export interface ThresholdSignalDay {
+    assetClose: number;
+    indicatorClose?: number;
+}
+export interface ThresholdSignalStrategy {
+    leverageMultiple: number;
+    vixDefensiveExposure: number;
+    signal: {
+        useSma: boolean;
+        smaLength: number;
+        exposureAboveSignal?: number;
+        exposureBelowSignal?: number;
+        useVixThreshold: boolean;
+        vixThreshold: number;
+    };
+}
+/**
+ * Pure signal function for day t inputs.
+ * The value returned here is not applied to day t return in fixed path.
+ */
+export declare function computeSignal(context: SignalContext): number;
+/**
+ * Maps signal value to bounded target position.
+ * Keeps leverage logic explicit and auditable.
+ */
+export declare function deriveTargetPosition(signal: number, config: EngineConfig): number;
+export declare function buildSignalContext(day: DayInput, previousDay?: DayInput): SignalContext;
+export declare function computeSmaSeries(values: number[], length: number): Array<number | undefined>;
+/**
+ * Shared threshold/switching helper for consumers that provide close-based inputs
+ * but still need engine-owned target exposure generation before the fixed path.
+ */
+export declare function buildThresholdSignalTargets(days: ThresholdSignalDay[], strategy: ThresholdSignalStrategy): number[];

package/dist/src/signal.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeSignal = computeSignal;
+exports.deriveTargetPosition = deriveTargetPosition;
+exports.buildSignalContext = buildSignalContext;
+exports.computeSmaSeries = computeSmaSeries;
+exports.buildThresholdSignalTargets = buildThresholdSignalTargets;
+/**
+ * Pure signal function for day t inputs.
+ * The value returned here is not applied to day t return in fixed path.
+ */
+function computeSignal(context) {
+    return context.day.signalInput;
+}
+/**
+ * Maps signal value to bounded target position.
+ * Keeps leverage logic explicit and auditable.
+ */
+function deriveTargetPosition(signal, config) {
+    const capped = Math.max(-config.maxLeverage, Math.min(config.maxLeverage, signal));
+    if (Object.is(capped, -0)) {
+        return 0;
+    }
+    return capped;
+}
+function buildSignalContext(day, previousDay) {
+    return { day, previousDay };
+}
+function computeSmaSeries(values, length) {
+    const out = new Array(values.length).fill(undefined);
+    if (length <= 0) {
+        return out;
+    }
+    let sum = 0;
+    for (let i = 0; i < values.length; i += 1) {
+        sum += values[i];
+        if (i >= length) {
+            sum -= values[i - length];
+        }
+        if (i >= length - 1) {
+            out[i] = sum / length;
+        }
+    }
+    return out;
+}
+/**
+ * Shared threshold/switching helper for consumers that provide close-based inputs
+ * but still need engine-owned target exposure generation before the fixed path.
+ */
+function buildThresholdSignalTargets(days, strategy) {
+    const smaSeries = computeSmaSeries(days.map((day) => day.assetClose), strategy.signal.smaLength);
+    const targets = [];
+    let vixDefensive = false;
+    for (let i = 0; i < days.length; i += 1) {
+        const day = days[i];
+        let target = strategy.leverageMultiple;
+        if (strategy.signal.useSma) {
+            const sma = smaSeries[i];
+            if (typeof sma === 'number') {
+                const above = strategy.signal.exposureAboveSignal ?? strategy.leverageMultiple;
+                const below = strategy.signal.exposureBelowSignal ?? strategy.leverageMultiple;
+                target = day.assetClose >= sma ? above : below;
+            }
+        }
+        if (strategy.signal.useVixThreshold && typeof day.indicatorClose === 'number') {
+            const threshold = strategy.signal.vixThreshold;
+            if (day.indicatorClose > threshold + 2) {
+                vixDefensive = true;
+            }
+            if (day.indicatorClose < threshold - 2) {
+                vixDefensive = false;
+            }
+        }
+        if (vixDefensive) {
+            target = strategy.vixDefensiveExposure;
+        }
+        targets.push(Math.max(0, target));
+    }
+    return targets;
+}

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

@@ -0,0 +1,9 @@
+import { DayInput, EngineConfig } from '../types';
+import { SimulatorBacktestRequest, SimulatorDay, SimulatorMonteCarloRequest } from './types';
+export interface PreparedSimulatorRun {
+    sourceDays: SimulatorDay[];
+    engineDays: DayInput[];
+    engineConfig: EngineConfig;
+}
+export declare function prepareSimulatorBacktest(request: SimulatorBacktestRequest): PreparedSimulatorRun;
+export declare function prepareSimulatorMonteCarlo(request: SimulatorMonteCarloRequest): PreparedSimulatorRun;

package/dist/src/simulator/adapters.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareSimulatorBacktest = prepareSimulatorBacktest;
+exports.prepareSimulatorMonteCarlo = prepareSimulatorMonteCarlo;
+const costs_1 = require("../costs");
+const signal_1 = require("../signal");
+const DEFAULT_BUILTIN_RATE_ANNUAL = 0.04;
+function prepareSimulatorBacktest(request) {
+    return prepareSimulatorRun(request.days, request.config, request.strategy);
+}
+function prepareSimulatorMonteCarlo(request) {
+    return prepareSimulatorRun(request.days, request.config, request.strategy);
+}
+function prepareSimulatorRun(sourceDays, simulatorConfig, simulatorStrategy) {
+    const targetSignals = (0, signal_1.buildThresholdSignalTargets)(sourceDays, simulatorStrategy);
+    const engineDays = sourceDays.map((day, index) => buildEngineDay({
+        day,
+        index,
+        targetSignal: targetSignals[index],
+        previousDay: index > 0 ? sourceDays[index - 1] : undefined,
+        previousMonth: index > 0 ? monthOf(sourceDays[index - 1].date) : undefined,
+        simulatorConfig,
+        simulatorStrategy,
+    }));
+    return {
+        sourceDays,
+        engineDays,
+        engineConfig: {
+            initialEquity: simulatorConfig.initialEquity,
+            initialTargetPosition: 0,
+            initialAppliedPosition: 0,
+            tradeCostRate: 0,
+            maxLeverage: Math.max(1, ...targetSignals.map((signal) => Math.abs(signal))),
+            initialBorrowRateDaily: engineDays[0]?.borrowRateDaily,
+            cashYieldDaily: 0,
+            enableInvariantChecks: true,
+        },
+    };
+}
+function buildEngineDay(params) {
+    const { day, index, targetSignal, previousDay, previousMonth, simulatorConfig, simulatorStrategy, } = params;
+    return {
+        date: day.date,
+        assetReturn: computeAssetReturn(day.assetClose, previousDay?.assetClose),
+        benchmarkReturn: computeBenchmarkReturn(day.benchmarkClose, previousDay?.benchmarkClose),
+        signalInput: targetSignal,
+        contribution: contributionForDay(index, monthOf(day.date), previousMonth, simulatorConfig.monthlyContribution),
+        borrowRateDaily: resolveBorrowRateDaily(day, simulatorConfig, simulatorStrategy),
+        expenseRatioAnnual: simulatorConfig.expenseRatioPct / 100,
+        tradeSpread: simulatorConfig.tradeSpreadPct / 100,
+    };
+}
+function resolveBorrowRateDaily(day, simulatorConfig, simulatorStrategy) {
+    const annualFinancingRate = resolveAnnualFinancingRate(day, simulatorStrategy);
+    const annualBorrowRate = annualFinancingRate + simulatorConfig.borrowSpreadPct / 100;
+    return (0, costs_1.annualToDailyRate)(annualBorrowRate);
+}
+function resolveAnnualFinancingRate(day, strategy) {
+    if (strategy.rateSource.mode === 'fixed') {
+        return (strategy.rateSource.fixedRatePct ?? 0) / 100;
+    }
+    if (strategy.rateSource.mode === 'series') {
+        return day.financingRateAnnual ?? 0;
+    }
+    if (day.financingRateAnnual !== undefined) {
+        return day.financingRateAnnual;
+    }
+    return DEFAULT_BUILTIN_RATE_ANNUAL;
+}
+function contributionForDay(index, month, previousMonth, monthlyContribution) {
+    if (monthlyContribution <= 0) {
+        return 0;
+    }
+    if (index === 0) {
+        return 0;
+    }
+    return previousMonth !== month ? monthlyContribution : 0;
+}
+function computeCloseReturn(current, previous) {
+    if (previous === undefined) {
+        return undefined;
+    }
+    if (!Number.isFinite(previous) || previous === 0) {
+        return 0;
+    }
+    return (current - previous) / previous;
+}
+function computeAssetReturn(current, previous) {
+    return computeCloseReturn(current, previous) ?? 0;
+}
+function computeBenchmarkReturn(currentBenchmarkClose, previousBenchmarkClose) {
+    if (currentBenchmarkClose === undefined || previousBenchmarkClose === undefined) {
+        return undefined;
+    }
+    return computeCloseReturn(currentBenchmarkClose, previousBenchmarkClose);
+}
+function monthOf(date) {
+    return new Date(`${date}T00:00:00Z`).getUTCMonth();
+}