@samsmith2121/synthetic-leverage-engine 0.1.0

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

@@ -0,0 +1 @@
+export declare function runModelValidationHarness(): number;

package/dist/src/validation-harness.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runModelValidationHarness = runModelValidationHarness;
+const validation_cases_1 = require("./validation-cases");
+function runModelValidationHarness() {
+    const run = (0, validation_cases_1.runModelValidationCases)();
+    for (const result of run.results) {
+        console.log(`[${result.status}] ${result.id} ${result.name}`);
+        console.log(`  actual: ${result.actual}`);
+        console.log(`  expected: ${result.expected}`);
+    }
+    console.log('');
+    console.log('Validation summary');
+    console.log(`  total passed: ${run.summary.passed}`);
+    console.log(`  total failed: ${run.summary.failed}`);
+    console.log(`  warnings: ${run.summary.warnings}`);
+    if (run.summary.failedCore > 0) {
+        console.error(`Core validation failures: ${run.summary.failedCore}`);
+        return 1;
+    }
+    return 0;
+}
+if (require.main === module) {
+    const exitCode = runModelValidationHarness();
+    process.exit(exitCode);
+}

package/dist/src/validation.d.ts

@@ -0,0 +1,8 @@
+import { BacktestInvariantReport, BenchmarkComparison, DailyState, DayInput, EngineConfig, MonteCarloConfig, MonteCarloInvariantReport, MonteCarloResult } from './types';
+export declare function validateConfig(config: EngineConfig): void;
+export declare function validateDayInputs(days: DayInput[], config: EngineConfig): void;
+export declare function validateMonteCarloConfig(config: MonteCarloConfig): void;
+export declare function assertBacktestInvariants(daily: DailyState[]): void;
+export declare function evaluateBacktestInvariants(daily: DailyState[], benchmark: BenchmarkComparison | null): BacktestInvariantReport;
+export declare function evaluateBenchmarkAlignmentInvariant(benchmark: BenchmarkComparison | null): boolean;
+export declare function evaluateMonteCarloInvariants(first: MonteCarloResult, secondSameSeed: MonteCarloResult, thirdDifferentSeed: MonteCarloResult): MonteCarloInvariantReport;

package/dist/src/validation.js

@@ -0,0 +1,244 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateConfig = validateConfig;
+exports.validateDayInputs = validateDayInputs;
+exports.validateMonteCarloConfig = validateMonteCarloConfig;
+exports.assertBacktestInvariants = assertBacktestInvariants;
+exports.evaluateBacktestInvariants = evaluateBacktestInvariants;
+exports.evaluateBenchmarkAlignmentInvariant = evaluateBenchmarkAlignmentInvariant;
+exports.evaluateMonteCarloInvariants = evaluateMonteCarloInvariants;
+function isValidIsoDate(date) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) {
+        return false;
+    }
+    const d = new Date(`${date}T00:00:00Z`);
+    return !Number.isNaN(d.getTime()) && d.toISOString().startsWith(date);
+}
+function assertFinite(value, label) {
+    if (!Number.isFinite(value)) {
+        throw new Error(`${label} must be finite`);
+    }
+}
+function validateConfig(config) {
+    assertFinite(config.initialEquity, 'initialEquity');
+    if (config.initialEquity <= 0) {
+        throw new Error('initialEquity must be positive');
+    }
+    assertFinite(config.tradeCostRate, 'tradeCostRate');
+    if (config.tradeCostRate < 0) {
+        throw new Error('tradeCostRate must be non-negative');
+    }
+    if (config.tradeCostRate > 0.1) {
+        throw new Error('tradeCostRate appears unrealistic (>10%)');
+    }
+    assertFinite(config.maxLeverage, 'maxLeverage');
+    if (config.maxLeverage <= 0) {
+        throw new Error('maxLeverage must be positive');
+    }
+    if (config.initialTargetPosition !== undefined) {
+        assertFinite(config.initialTargetPosition, 'initialTargetPosition');
+        if (Math.abs(config.initialTargetPosition) > config.maxLeverage) {
+            throw new Error('initialTargetPosition exceeds maxLeverage bounds');
+        }
+    }
+    if (config.initialAppliedPosition !== undefined) {
+        assertFinite(config.initialAppliedPosition, 'initialAppliedPosition');
+        if (Math.abs(config.initialAppliedPosition) > config.maxLeverage) {
+            throw new Error('initialAppliedPosition exceeds maxLeverage bounds');
+        }
+    }
+    if (config.initialBorrowRateDaily !== undefined) {
+        assertFinite(config.initialBorrowRateDaily, 'initialBorrowRateDaily');
+        if (config.initialBorrowRateDaily <= -1) {
+            throw new Error('initialBorrowRateDaily must be greater than -1');
+        }
+    }
+    if (config.cashYieldDaily !== undefined) {
+        assertFinite(config.cashYieldDaily, 'cashYieldDaily');
+        if (config.cashYieldDaily <= -1) {
+            throw new Error('cashYieldDaily must be greater than -1');
+        }
+    }
+}
+function validateDayInputs(days, config) {
+    if (days.length === 0) {
+        throw new Error('days must not be empty');
+    }
+    let hasKnownBorrowRate = config.initialBorrowRateDaily !== undefined;
+    for (let i = 0; i < days.length; i += 1) {
+        const current = days[i];
+        if (!isValidIsoDate(current.date)) {
+            throw new Error(`invalid date format for ${current.date}; expected YYYY-MM-DD`);
+        }
+        assertFinite(current.assetReturn, `assetReturn for date ${current.date}`);
+        assertFinite(current.signalInput, `signalInput for date ${current.date}`);
+        if (current.contribution !== undefined) {
+            assertFinite(current.contribution, `contribution for date ${current.date}`);
+            if (current.contribution < 0) {
+                throw new Error(`negative contribution is not allowed for date ${current.date}`);
+            }
+        }
+        if (current.borrowRateDaily !== undefined) {
+            assertFinite(current.borrowRateDaily, `borrowRateDaily for date ${current.date}`);
+            if (current.borrowRateDaily <= -1) {
+                throw new Error(`borrowRateDaily must be greater than -1 for date ${current.date}`);
+            }
+            hasKnownBorrowRate = true;
+        }
+        if (current.expenseRatioAnnual !== undefined) {
+            assertFinite(current.expenseRatioAnnual, `expenseRatioAnnual for date ${current.date}`);
+            if (current.expenseRatioAnnual <= -1) {
+                throw new Error(`expenseRatioAnnual must be greater than -1 for date ${current.date}`);
+            }
+        }
+        if (current.tradeSpread !== undefined) {
+            assertFinite(current.tradeSpread, `tradeSpread for date ${current.date}`);
+            if (current.tradeSpread < 0) {
+                throw new Error(`tradeSpread must be non-negative for date ${current.date}`);
+            }
+            if (current.tradeSpread > 0.1) {
+                throw new Error(`tradeSpread appears unrealistic (>10%) for date ${current.date}`);
+            }
+        }
+        if (current.benchmarkReturn !== undefined) {
+            assertFinite(current.benchmarkReturn, `benchmarkReturn for date ${current.date}`);
+        }
+        if (i > 0) {
+            const prev = days[i - 1];
+            if (prev.date >= current.date) {
+                throw new Error('dates must be strictly increasing (ISO YYYY-MM-DD)');
+            }
+        }
+        if (i === 0 && !hasKnownBorrowRate) {
+            throw new Error('first borrow rate must be explicit: provide day[0].borrowRateDaily or config.initialBorrowRateDaily');
+        }
+    }
+}
+function validateMonteCarloConfig(config) {
+    assertFinite(config.paths, 'paths');
+    assertFinite(config.horizonDays, 'horizonDays');
+    if (!Number.isInteger(config.paths) || config.paths <= 0) {
+        throw new Error('paths must be a positive integer');
+    }
+    if (!Number.isInteger(config.horizonDays) || config.horizonDays <= 0) {
+        throw new Error('horizonDays must be a positive integer');
+    }
+    if (config.seed !== undefined) {
+        assertFinite(config.seed, 'seed');
+        if (!Number.isInteger(config.seed) || config.seed < 0) {
+            throw new Error('seed must be a non-negative integer');
+        }
+    }
+    if (config.blockLength !== undefined) {
+        assertFinite(config.blockLength, 'blockLength');
+        if (!Number.isInteger(config.blockLength) || config.blockLength <= 0) {
+            throw new Error('blockLength must be a positive integer');
+        }
+        if (config.blockLength > config.horizonDays) {
+            throw new Error('blockLength must not exceed horizonDays');
+        }
+    }
+}
+function assertBacktestInvariants(daily) {
+    const report = evaluateBacktestInvariants(daily, null);
+    const failed = Object.entries(report).find(([, value]) => !value);
+    if (failed) {
+        throw new Error(`backtest invariant failed: ${failed[0]}`);
+    }
+}
+function evaluateBacktestInvariants(daily, benchmark) {
+    let hasFiniteValues = true;
+    let noSameDaySignalLeakage = true;
+    let contributionBeforeReturnOrdering = true;
+    let tradeCostZeroWithoutPositionChange = true;
+    let borrowCostZeroAtOrBelowOneX = true;
+    let borrowCostZeroInCashMode = true;
+    let isDailyDateSequenceStrictlyIncreasing = true;
+    for (let i = 0; i < daily.length; i += 1) {
+        const current = daily[i];
+        const numericValues = [
+            current.equityStart,
+            current.contribution,
+            current.capitalBaseBeforeReturn,
+            current.equityAfterTradeCost,
+            current.equityEnd,
+            current.signal,
+            current.targetPosition,
+            current.appliedPosition,
+            current.priorAppliedPosition,
+            current.turnoverNotional,
+            current.tradeCost,
+            current.grossPnl,
+            current.borrowDrag,
+            current.expenseDrag,
+            current.netPnl,
+            current.borrowRateDaily,
+            current.expenseRatioDaily,
+        ];
+        if (numericValues.some((value) => !Number.isFinite(value))) {
+            hasFiniteValues = false;
+        }
+        if (current.capitalBaseBeforeReturn !== current.equityStart + current.contribution) {
+            contributionBeforeReturnOrdering = false;
+        }
+        if (current.appliedPosition === current.priorAppliedPosition && current.tradeCost !== 0) {
+            tradeCostZeroWithoutPositionChange = false;
+        }
+        if (Math.abs(current.appliedPosition) <= 1 && current.borrowDrag !== 0) {
+            borrowCostZeroAtOrBelowOneX = false;
+        }
+        if (current.appliedPosition === 0 && current.borrowDrag !== 0) {
+            borrowCostZeroInCashMode = false;
+        }
+        if (i > 0) {
+            const previous = daily[i - 1];
+            if (current.appliedPosition !== previous.targetPosition) {
+                noSameDaySignalLeakage = false;
+            }
+            if (previous.date >= current.date) {
+                isDailyDateSequenceStrictlyIncreasing = false;
+            }
+        }
+    }
+    return {
+        hasFiniteValues,
+        noSameDaySignalLeakage,
+        contributionBeforeReturnOrdering,
+        tradeCostZeroWithoutPositionChange,
+        borrowCostZeroAtOrBelowOneX,
+        borrowCostZeroInCashMode,
+        benchmarkMatchedDatesOnly: evaluateBenchmarkAlignmentInvariant(benchmark),
+        isDailyDateSequenceStrictlyIncreasing,
+    };
+}
+function evaluateBenchmarkAlignmentInvariant(benchmark) {
+    if (!benchmark) {
+        return true;
+    }
+    const expectedLength = benchmark.dates.length;
+    return (benchmark.strategyEquity.length === expectedLength &&
+        benchmark.benchmarkEquity.length === expectedLength &&
+        benchmark.strategyReturns.length === expectedLength &&
+        benchmark.benchmarkReturns.length === expectedLength &&
+        benchmark.dates.every((date, idx) => idx === 0 || benchmark.dates[idx - 1] < date));
+}
+function evaluateMonteCarloInvariants(first, secondSameSeed, thirdDifferentSeed) {
+    const firstSerialized = JSON.stringify(first);
+    const secondSerialized = JSON.stringify(secondSameSeed);
+    const thirdSerialized = JSON.stringify(thirdDifferentSeed);
+    const pathDatesStrictlyIncreasing = first.paths.every((path) => path.result.daily.every((day, index) => index === 0 || path.result.daily[index - 1].date < day.date));
+    const hasFiniteValues = first.paths.every((path) => path.result.daily.every((day) => Object.values(day).every((value) => typeof value !== 'number' || Number.isFinite(value))));
+    const percentileSummariesOrdered = isOrderedPercentiles(first.summary.endingEquity)
+        && isOrderedPercentiles(first.summary.twrCagr)
+        && isOrderedPercentiles(first.summary.maxDrawdown);
+    return {
+        hasFiniteValues,
+        sameSeedReproducible: firstSerialized === secondSerialized,
+        differentSeedsCanDiffer: firstSerialized !== thirdSerialized,
+        pathDatesStrictlyIncreasing,
+        percentileSummariesOrdered,
+    };
+}
+function isOrderedPercentiles(summary) {
+    return summary.p5 <= summary.p50 && summary.p50 <= summary.p95;
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@samsmith2121/synthetic-leverage-engine",
+  "version": "0.1.0",
+  "type": "commonjs",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "files": [
+    "dist/src/**/*",
+    "package.json",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "require": "./dist/src/index.js",
+      "default": "./dist/src/index.js"
+    },
+    "./simulator": {
+      "types": "./dist/src/simulator/index.d.ts",
+      "require": "./dist/src/simulator/index.js",
+      "default": "./dist/src/simulator/index.js"
+    }
+  },
+  "scripts": {
+    "clean": "node -e \"const fs=require('fs'); fs.rmSync('dist',{ recursive:true, force:true });\"",
+    "build": "npm run clean && tsc --project tsconfig.json",
+    "typecheck": "tsc --noEmit --project tsconfig.json",
+    "test": "npm run build && node --test dist/tests/*.test.js",
+    "validate:model": "npm run build && node dist/src/validation-harness.js",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.14.1",
+    "typescript": "^5.8.3"
+  }
+}