@samsmith2121/synthetic-leverage-engine 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# synthetic-leverage-engine
+Engine and tests for a synthetic leverage simulator
+
+## Handoff note for UI builders
+- The engine is the single source of truth for financial logic.
+- UI integrations should import from `src/public-api.ts` (or package root exports that re-export it) and call engine functions only.
+- UI integrations should avoid importing low-level internal engine files directly unless the public engine surface is intentionally extended first.
+- Do not duplicate backtest, Monte Carlo, benchmark, validation, metrics, diagnostics, or cost logic in UI code.
+- Cash yield behavior is explicit and configurable (`cashYieldDaily`); zero-yield is a supported/default mode, not the only mode.
+- If UI needs new output shapes, extend the engine first and keep locked accounting order unchanged.
+
+The repository now includes a deterministic research workflow on top of the trusted fixed-path engine:
+
+- Strategy diagnostics explaining exposure, transitions, cost mix, drawdown profile, and benchmark-relative behavior (`buildStrategyDiagnostics` via run summaries)
+- Sensitivity analysis utilities:
+  - one-way sensitivity (`runOneWaySensitivity`)
+  - two-way sensitivity with grid-friendly cells (`runTwoWaySensitivity`)
+  - deterministic ranking helper (`rankStrategyRuns`)
+- Structured analysis warnings (`AnalysisWarning`) surfaced directly in strategy/sweep/scenario outputs
+- Rule-based research summary builders (`buildResearchSummaries`) for decision-ready but descriptive recommendations
+- Export-ready flat rows for downstream CSV pipelines:
+  - backtest summary rows
+  - strategy comparison rows
+  - parameter sweep rows
+  - scenario rows
+  - one-way/two-way sensitivity rows
+  - diagnostics rows
+
+Core files:
+- `src/analysis.ts`
+- `src/reporting.ts`
+- `src/analysis-cli.ts` (minimal script entry point)
+
+### Minimal CLI usage
+
+Build first:
+
+```bash
+npm run build
+```
+
+Run modes:
+
+```bash
+node dist/src/analysis-cli.js comparison <days.json> <config.json> <payload.json>
+node dist/src/analysis-cli.js sweep <days.json> <config.json> <payload.json>
+node dist/src/analysis-cli.js scenario <days.json> <config.json> <payload.json>
+node dist/src/analysis-cli.js backtest <days.json> <config.json> [payload.json]
+```
+
+Payload JSON provides typed strategy variants, sweep grids, or scenario definitions.
+
+## Model validation harness
+
+Run the automated model validation suite:
+
+```bash
+npm run validate:model
+```
+
+The harness prints a human-readable PASS/FAIL/WARN report for each validation case, including actual values and expected conditions. It also prints a summary with total passed, total failed, and warnings. The command exits non-zero when any core validation fails.

package/dist/src/analysis-cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/analysis-cli.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/* eslint-disable no-console */
+const node_fs_1 = require("node:fs");
+const analysis_1 = require("./analysis");
+const reporting_1 = require("./reporting");
+function loadJson(path) {
+    return JSON.parse((0, node_fs_1.readFileSync)(path, 'utf8'));
+}
+function main() {
+    const [, , mode, daysPath, configPath, payloadPath] = process.argv;
+    if (!mode || !daysPath || !configPath) {
+        console.error('Usage: node dist/src/analysis-cli.js <backtest|comparison|sweep|scenario> <days.json> <config.json> [payload.json]');
+        process.exit(1);
+    }
+    const days = loadJson(daysPath);
+    const config = loadJson(configPath);
+    if (mode === 'backtest') {
+        const payload = payloadPath ? loadJson(payloadPath) : { variants: [] };
+        const comparison = (0, analysis_1.runStrategyComparison)(days, config, payload.variants ?? []);
+        console.log(JSON.stringify((0, reporting_1.toStrategyComparisonRows)(comparison), null, 2));
+        return;
+    }
+    if (!payloadPath) {
+        console.error(`Mode ${mode} requires payload.json`);
+        process.exit(1);
+    }
+    if (mode === 'comparison') {
+        const payload = loadJson(payloadPath);
+        console.log(JSON.stringify((0, analysis_1.runStrategyComparison)(days, config, payload.variants), null, 2));
+        return;
+    }
+    if (mode === 'sweep') {
+        const payload = loadJson(payloadPath);
+        console.log(JSON.stringify((0, analysis_1.runParameterSweep)(days, config, payload.grid, payload.options), null, 2));
+        return;
+    }
+    if (mode === 'scenario') {
+        const payload = loadJson(payloadPath);
+        const scenarios = payload.rolling
+            ? (0, analysis_1.buildRollingWindowScenarios)(days, payload.rolling.windowLengthDays, payload.rolling.stepDays)
+            : payload.scenarios ?? [];
+        const scenarioResult = (0, analysis_1.runScenarioAnalysis)(days, config, payload.variant, scenarios);
+        const comparison = (0, analysis_1.runStrategyComparison)(days, config, [payload.variant]);
+        const sweep = (0, analysis_1.runParameterSweep)(days, config, {
+            vixThresholds: [payload.variant.signal?.vixThreshold ?? 20],
+            leverageMultiples: [payload.variant.signal?.leverageMultiple ?? 1],
+            tradeSpreads: [payload.variant.tradeSpread ?? 0],
+            expenseRatiosAnnual: [payload.variant.expenseRatioAnnual ?? 0],
+            cashModes: [payload.variant.cashMode ?? 'zero_yield'],
+            cashYieldDailyValues: [payload.variant.cashYieldDaily ?? 0],
+        });
+        console.log(JSON.stringify((0, reporting_1.buildAnalysisReport)(comparison, sweep, scenarioResult), null, 2));
+        return;
+    }
+    console.error(`Unknown mode: ${mode}`);
+    process.exit(1);
+}
+main();

package/dist/src/analysis.d.ts

@@ -0,0 +1,214 @@
+import { BacktestResult, DayInput, EngineConfig, MonteCarloConfig } from './types';
+export type CashModeOption = 'zero_yield' | 'configured_yield';
+export type SweepRankMetric = 'twrCagr' | 'xirr' | 'maxDrawdown' | 'volatility' | 'excessTwrCagr' | 'returnToDrawdown';
+export type AnalysisWarningCode = 'BENCHMARK_UNAVAILABLE' | 'BENCHMARK_PARTIAL_COVERAGE' | 'SCENARIO_TOO_FEW_OBSERVATIONS' | 'MONTE_CARLO_BLOCK_TOO_LONG' | 'UNUSUAL_ASSUMPTION' | 'XIRR_UNAVAILABLE' | 'SWEEP_VALIDATION_FAILED';
+export interface AnalysisWarning {
+    code: AnalysisWarningCode;
+    message: string;
+    context?: Record<string, string | number | boolean | null>;
+}
+export interface SignalThresholdConfig {
+    vixThreshold: number;
+    leverageMultiple: number;
+    cashExposure?: number;
+    /**
+     * When true, treats signalInput as a boolean-style indicator where 1 means
+     * "price above SMA" and 0 means "price below SMA".
+     * Comparison becomes signalInput > vixThreshold (set vixThreshold: 0).
+     * Without this flag the default VIX-scale comparison is signalInput <= vixThreshold,
+     * which silently suppresses all SMA-based switching because SMA distance values
+     * (~0.05 magnitude) are always below any VIX-scale threshold like 20.
+     */
+    smaMode?: boolean;
+}
+export interface StrategyVariant {
+    name: string;
+    signal?: SignalThresholdConfig;
+    tradeSpread?: number;
+    expenseRatioAnnual?: number;
+    cashMode?: CashModeOption;
+    cashYieldDaily?: number;
+    monteCarloBlockLength?: number;
+    engineConfigOverrides?: Partial<EngineConfig>;
+}
+export interface ExposureDiagnostics {
+    pctDaysCash: number;
+    pctDaysOneX: number;
+    pctDaysLeveraged: number;
+    averageAppliedLeverage: number;
+    leverageDistribution: Record<string, number>;
+}
+export interface TransitionDiagnostics {
+    totalSwitches: number;
+    transitionCounts: Record<string, number>;
+    averageHoldingDurationByRegime: Record<string, number>;
+}
+export interface CostDiagnostics {
+    totalTradeCost: number;
+    totalBorrowCost: number;
+    totalErCost: number;
+    totalCost: number;
+    tradeCostShare: number;
+    borrowCostShare: number;
+    erCostShare: number;
+    totalCostPctFinalEquity: number | null;
+    totalCostPctInvestedCapital: number | null;
+}
+export interface DrawdownDiagnostics {
+    maxDrawdown: number;
+    maxDrawdownDurationDays: number;
+    episodesAbove10Pct: number;
+    episodesAbove20Pct: number;
+    episodesAbove30Pct: number;
+}
+export interface BenchmarkRelativeDiagnostics {
+    matchedPeriods: number;
+    outperformPeriods: number;
+    outperformPct: number | null;
+    averageExcessReturn: number | null;
+    medianExcessReturn: number | null;
+    excessTwrCagr: number | null;
+}
+export interface StrategyDiagnostics {
+    exposure: ExposureDiagnostics;
+    transitions: TransitionDiagnostics;
+    costs: CostDiagnostics;
+    drawdown: DrawdownDiagnostics;
+    benchmarkRelative?: BenchmarkRelativeDiagnostics;
+}
+export interface AnalysisRunSummary {
+    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;
+    diagnostics: StrategyDiagnostics;
+    benchmark?: AnalysisBenchmarkSummary;
+}
+export interface AnalysisBenchmarkSummary {
+    benchmarkTotalReturn: number;
+    benchmarkTwrCagr: number | null;
+    benchmarkVolatility: number | null;
+    benchmarkMaxDrawdown: number;
+    excessTotalReturn: number | null;
+    excessTwrCagr: number | null;
+    trackingError: number | null;
+    relativeMaxDrawdown: number;
+}
+export interface StrategyRunSuccess {
+    ok: true;
+    strategy: StrategyVariant;
+    summary: AnalysisRunSummary;
+    warnings: AnalysisWarning[];
+}
+export interface StrategyRunFailure {
+    ok: false;
+    strategy: StrategyVariant;
+    error: string;
+    warnings: AnalysisWarning[];
+}
+export type StrategyRunResult = StrategyRunSuccess | StrategyRunFailure;
+export interface StrategyConfigComparison {
+    runs: StrategyRunResult[];
+    ranking: StrategyRankingEntry[];
+}
+export interface StrategyRankingEntry {
+    strategyName: string;
+    metric: SweepRankMetric;
+    rank: number;
+    value: number | null;
+}
+export interface ParameterSweepGrid {
+    vixThresholds: number[];
+    leverageMultiples: number[];
+    tradeSpreads: number[];
+    expenseRatiosAnnual: number[];
+    cashModes: CashModeOption[];
+    cashYieldDailyValues: number[];
+    monteCarloBlockLengths?: number[];
+}
+export interface ParameterSweepConfig {
+    baseVariantName?: string;
+    rankBy?: SweepRankMetric;
+    monteCarloConfig?: Pick<MonteCarloConfig, 'horizonDays' | 'paths' | 'seed'>;
+}
+export interface SweepResultRow {
+    strategyName: string;
+    vixThreshold: number;
+    leverageMultiple: number;
+    tradeSpread: number;
+    expenseRatioAnnual: number;
+    cashMode: CashModeOption;
+    cashYieldDaily: number;
+    monteCarloBlockLength?: number;
+    run: StrategyRunResult;
+}
+export interface ParameterSweepResult {
+    rows: SweepResultRow[];
+    ranking: StrategyRankingEntry[];
+}
+export interface ScenarioDefinition {
+    name: string;
+    startDate: string;
+    endDate: string;
+}
+export interface ScenarioResultRow {
+    scenarioName: string;
+    startDate: string;
+    endDate: string;
+    run: StrategyRunResult;
+    warnings: AnalysisWarning[];
+}
+export interface ScenarioAnalysisResult {
+    rows: ScenarioResultRow[];
+}
+export type SensitivityParameter = 'vixThreshold' | 'leverageMultiple' | 'tradeSpread' | 'expenseRatioAnnual' | 'cashYieldDaily' | 'cashMode';
+export interface OneWaySensitivityRow {
+    parameter: SensitivityParameter;
+    parameterValue: number | string;
+    run: StrategyRunResult;
+}
+export interface OneWaySensitivityResult {
+    parameter: SensitivityParameter;
+    rows: OneWaySensitivityRow[];
+    ranking: StrategyRankingEntry[];
+}
+export interface TwoWaySensitivityCell {
+    xParameter: SensitivityParameter;
+    xValue: number | string;
+    yParameter: SensitivityParameter;
+    yValue: number | string;
+    run: StrategyRunResult;
+}
+export interface TwoWaySensitivityResult {
+    xParameter: SensitivityParameter;
+    yParameter: SensitivityParameter;
+    xValues: Array<number | string>;
+    yValues: Array<number | string>;
+    cells: TwoWaySensitivityCell[];
+    ranking: StrategyRankingEntry[];
+}
+export type ResearchSummaryKind = 'best_growth_drawdown_tradeoff' | 'highest_twr_under_drawdown_constraint' | 'lowest_cost' | 'most_benchmark_outperforming' | 'most_robust_across_scenarios';
+export interface ResearchSummaryRecommendation {
+    kind: ResearchSummaryKind;
+    strategyName: string;
+    rationale: string;
+    metrics: Record<string, number | string | null>;
+}
+export declare function runStrategyComparison(days: DayInput[], baseConfig: EngineConfig, variants: StrategyVariant[], rankBy?: SweepRankMetric): StrategyConfigComparison;
+export declare function runParameterSweep(days: DayInput[], baseConfig: EngineConfig, grid: ParameterSweepGrid, config?: ParameterSweepConfig): ParameterSweepResult;
+export declare function runScenarioAnalysis(days: DayInput[], baseConfig: EngineConfig, variant: StrategyVariant, scenarios: ScenarioDefinition[], includeFullPeriod?: boolean): ScenarioAnalysisResult;
+export declare function buildRollingWindowScenarios(days: DayInput[], windowLengthDays: number, stepDays: number): ScenarioDefinition[];
+export declare function runOneWaySensitivity(days: DayInput[], baseConfig: EngineConfig, baseVariant: StrategyVariant, parameter: SensitivityParameter, values: Array<number | string>, rankBy?: SweepRankMetric): OneWaySensitivityResult;
+export declare function runTwoWaySensitivity(days: DayInput[], baseConfig: EngineConfig, baseVariant: StrategyVariant, xParameter: SensitivityParameter, xValues: Array<number | string>, yParameter: SensitivityParameter, yValues: Array<number | string>, rankBy?: SweepRankMetric): TwoWaySensitivityResult;
+export declare function buildResearchSummaries(comparison: StrategyConfigComparison, scenarioResult?: ScenarioAnalysisResult, options?: {
+    maxDrawdownConstraint?: number;
+}): ResearchSummaryRecommendation[];
+export declare function rankStrategyRuns(runs: StrategyRunResult[], metric: SweepRankMetric): StrategyRankingEntry[];
+export declare function buildStrategyDiagnostics(backtest: BacktestResult, totalInvested?: number): StrategyDiagnostics;