@calculator53295/backtest-engine 0.1.0

package/dist/engine/frontier.js

@@ -0,0 +1,40 @@
+import { runBacktest } from './backtest.js';
+/**
+ * Sweep the A/B mix from 0→100% A in `steps` increments. Two assets is the
+ * classic, honest frontier: the whole curve is enumerable, so there's no
+ * optimizer to trust — every point is a portfolio you could actually hold.
+ */
+export function twoAssetFrontier(a, b, config, steps = 21) {
+    const series = [a, b];
+    const points = [];
+    for (let i = 0; i < steps; i++) {
+        const weightA = Math.round((i / (steps - 1)) * 10000) / 100;
+        const weightB = Math.round((100 - weightA) * 100) / 100;
+        const allocations = [
+            { ticker: a.ticker, weight: weightA },
+            { ticker: b.ticker, weight: weightB },
+        ].filter((x) => x.weight > 0);
+        // Single-asset endpoints: one allocation at 100%.
+        const spec = { name: `mix-${i}`, allocations: allocations.length ? allocations : [{ ticker: a.ticker, weight: 100 }] };
+        const m = runBacktest(series, spec, config).metrics;
+        points.push({ weightA, volatility: m.volatility, cagr: m.cagr, sharpe: m.sharpe });
+    }
+    return points;
+}
+/** Index of the minimum-variance point. */
+export function minVarianceIndex(points) {
+    let idx = 0;
+    for (let i = 1; i < points.length; i++)
+        if (points[i].volatility < points[idx].volatility)
+            idx = i;
+    return idx;
+}
+/** Index of the maximum-Sharpe (tangency) point. */
+export function maxSharpeIndex(points) {
+    let idx = 0;
+    for (let i = 1; i < points.length; i++)
+        if (points[i].sharpe > points[idx].sharpe)
+            idx = i;
+    return idx;
+}
+//# sourceMappingURL=frontier.js.map

package/dist/engine/frontier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontier.js","sourceRoot":"","sources":["../../src/engine/frontier.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAgB3C;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAC9B,CAAe,EACf,CAAe,EACf,MAAsB,EACtB,KAAK,GAAG,EAAE;IAEV,MAAM,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IACrB,MAAM,MAAM,GAAoB,EAAE,CAAA;IAClC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/B,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,GAAG,GAAG,CAAA;QAC3D,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAA;QACvD,MAAM,WAAW,GAAG;YAClB,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE;YACrC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE;SACtC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;QAC7B,kDAAkD;QAClD,MAAM,IAAI,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,EAAE,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,EAAE,CAAA;QACtH,MAAM,CAAC,GAAG,WAAW,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,OAAO,CAAA;QACnD,MAAM,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAA;IACpF,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC;AAED,2CAA2C;AAC3C,MAAM,UAAU,gBAAgB,CAAC,MAAuB;IACtD,IAAI,GAAG,GAAG,CAAC,CAAA;IACX,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,UAAU;YAAE,GAAG,GAAG,CAAC,CAAA;IAClG,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,oDAAoD;AACpD,MAAM,UAAU,cAAc,CAAC,MAAuB;IACpD,IAAI,GAAG,GAAG,CAAC,CAAA;IACX,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM;YAAE,GAAG,GAAG,CAAC,CAAA;IAC1F,OAAO,GAAG,CAAA;AACZ,CAAC"}

package/dist/engine/index.d.ts

@@ -0,0 +1,6 @@
+export { runBacktest } from './backtest.js';
+export { twoAssetFrontier, minVarianceIndex, maxSharpeIndex, type FrontierPoint, } from './frontier.js';
+export { alignSeries, isNewMonth, isPeriodStart } from './align.js';
+export { annualIncome, annualReturns, computeMetrics, irr, maxDrawdown, monthlyReturns, monthlyReturnsLabeled, rollingReturns, } from './metrics.js';
+export type * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/engine/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,KAAK,aAAa,GACnB,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AACnE,OAAO,EACL,YAAY,EACZ,aAAa,EACb,cAAc,EACd,GAAG,EACH,WAAW,EACX,cAAc,EACd,qBAAqB,EACrB,cAAc,GACf,MAAM,cAAc,CAAA;AACrB,mBAAmB,YAAY,CAAA"}

package/dist/engine/index.js

@@ -0,0 +1,5 @@
+export { runBacktest } from './backtest.js';
+export { twoAssetFrontier, minVarianceIndex, maxSharpeIndex, } from './frontier.js';
+export { alignSeries, isNewMonth, isPeriodStart } from './align.js';
+export { annualIncome, annualReturns, computeMetrics, irr, maxDrawdown, monthlyReturns, monthlyReturnsLabeled, rollingReturns, } from './metrics.js';
+//# sourceMappingURL=index.js.map

package/dist/engine/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,GAEf,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AACnE,OAAO,EACL,YAAY,EACZ,aAAa,EACb,cAAc,EACd,GAAG,EACH,WAAW,EACX,cAAc,EACd,qBAAqB,EACrB,cAAc,GACf,MAAM,cAAc,CAAA"}

package/dist/engine/metrics.d.ts

@@ -0,0 +1,27 @@
+import type { DrawdownInfo, MetricSet, RollingPoint, YearReturn } from './types.js';
+/** Compound the TWR index into calendar-month returns. */
+export declare function monthlyReturns(dates: string[], twrIndex: number[]): number[];
+/** Calendar-month returns with their 'yyyy-mm' labels (for rf matching, regression). */
+export declare function monthlyReturnsLabeled(dates: string[], twrIndex: number[]): Array<{
+    month: string;
+    ret: number;
+}>;
+export declare function annualReturns(dates: string[], twrIndex: number[]): YearReturn[];
+/**
+ * Trailing-window annualized returns, one observation per month-end.
+ * Empty when the history is shorter than the window.
+ */
+export declare function rollingReturns(dates: string[], twrIndex: number[], windowYears: number): RollingPoint[];
+/** Cash dividend income summed per calendar year. */
+export declare function annualIncome(dates: string[], dividendIncome: number[]): Array<{
+    year: number;
+    income: number;
+}>;
+export declare function maxDrawdown(dates: string[], twrIndex: number[]): DrawdownInfo;
+/**
+ * Money-weighted annual return via bisection on the rate that zeroes the
+ * NPV of {initial investment, flows, final value}.
+ */
+export declare function irr(dates: string[], flows: number[], initialAmount: number, finalValue: number): number;
+export declare function computeMetrics(dates: string[], twrIndex: number[], values: number[], flows: number[], riskFreeRate: number, rfByMonth?: Record<string, number>): MetricSet;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/engine/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/engine/metrics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAmBnF,0DAA0D;AAC1D,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAE5E;AAED,wFAAwF;AACxF,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,EAAE,EACf,QAAQ,EAAE,MAAM,EAAE,GACjB,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAcvC;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,UAAU,EAAE,CAiB/E;AAYD;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EAAE,EACf,QAAQ,EAAE,MAAM,EAAE,EAClB,WAAW,EAAE,MAAM,GAClB,YAAY,EAAE,CAehB;AAED,qDAAqD;AACrD,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EAAE,EACf,cAAc,EAAE,MAAM,EAAE,GACvB,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAUzC;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,YAAY,CAmC7E;AAED;;;GAGG;AACH,wBAAgB,GAAG,CACjB,KAAK,EAAE,MAAM,EAAE,EACf,KAAK,EAAE,MAAM,EAAE,EACf,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,GACjB,MAAM,CA4BR;AAED,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EAAE,EACf,QAAQ,EAAE,MAAM,EAAE,EAClB,MAAM,EAAE,MAAM,EAAE,EAChB,KAAK,EAAE,MAAM,EAAE,EACf,YAAY,EAAE,MAAM,EACpB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACjC,SAAS,CAsCX"}

package/dist/engine/metrics.js

@@ -0,0 +1,202 @@
+const DAY_MS = 86_400_000;
+function yearsBetween(start, end) {
+    return (Date.parse(end) - Date.parse(start)) / DAY_MS / 365.25;
+}
+function mean(xs) {
+    return xs.reduce((s, x) => s + x, 0) / xs.length;
+}
+/** Sample standard deviation. */
+function stdev(xs) {
+    if (xs.length < 2)
+        return 0;
+    const m = mean(xs);
+    return Math.sqrt(xs.reduce((s, x) => s + (x - m) ** 2, 0) / (xs.length - 1));
+}
+/** Compound the TWR index into calendar-month returns. */
+export function monthlyReturns(dates, twrIndex) {
+    return monthlyReturnsLabeled(dates, twrIndex).map((m) => m.ret);
+}
+/** Calendar-month returns with their 'yyyy-mm' labels (for rf matching, regression). */
+export function monthlyReturnsLabeled(dates, twrIndex) {
+    const out = [];
+    let monthStartIdx = 0;
+    for (let t = 1; t < dates.length; t++) {
+        if (dates[t].slice(0, 7) !== dates[t - 1].slice(0, 7)) {
+            out.push({ month: dates[t - 1].slice(0, 7), ret: twrIndex[t - 1] / twrIndex[monthStartIdx] - 1 });
+            monthStartIdx = t - 1;
+        }
+    }
+    out.push({
+        month: dates[dates.length - 1].slice(0, 7),
+        ret: twrIndex[dates.length - 1] / twrIndex[monthStartIdx] - 1,
+    });
+    return out;
+}
+export function annualReturns(dates, twrIndex) {
+    const out = [];
+    let yearStartIdx = 0;
+    for (let t = 1; t < dates.length; t++) {
+        if (dates[t].slice(0, 4) !== dates[t - 1].slice(0, 4)) {
+            out.push({
+                year: Number(dates[t - 1].slice(0, 4)),
+                return: twrIndex[t - 1] / twrIndex[yearStartIdx] - 1,
+            });
+            yearStartIdx = t - 1;
+        }
+    }
+    out.push({
+        year: Number(dates[dates.length - 1].slice(0, 4)),
+        return: twrIndex[dates.length - 1] / twrIndex[yearStartIdx] - 1,
+    });
+    return out;
+}
+/** Indices of the last trading day of each calendar month (incl. the final day). */
+function monthEndIndices(dates) {
+    const out = [];
+    for (let t = 1; t < dates.length; t++) {
+        if (dates[t].slice(0, 7) !== dates[t - 1].slice(0, 7))
+            out.push(t - 1);
+    }
+    out.push(dates.length - 1);
+    return out;
+}
+/**
+ * Trailing-window annualized returns, one observation per month-end.
+ * Empty when the history is shorter than the window.
+ */
+export function rollingReturns(dates, twrIndex, windowYears) {
+    const ends = monthEndIndices(dates);
+    const w = windowYears * 12;
+    const out = [];
+    for (let k = w; k < ends.length; k++) {
+        const start = ends[k - w];
+        const end = ends[k];
+        const years = yearsBetween(dates[start], dates[end]);
+        if (years <= 0)
+            continue;
+        out.push({
+            date: dates[end],
+            value: (twrIndex[end] / twrIndex[start]) ** (1 / years) - 1,
+        });
+    }
+    return out;
+}
+/** Cash dividend income summed per calendar year. */
+export function annualIncome(dates, dividendIncome) {
+    const byYear = new Map();
+    for (let t = 0; t < dates.length; t++) {
+        if (dividendIncome[t] === 0)
+            continue;
+        const year = Number(dates[t].slice(0, 4));
+        byYear.set(year, (byYear.get(year) ?? 0) + dividendIncome[t]);
+    }
+    return [...byYear.entries()]
+        .map(([year, income]) => ({ year, income }))
+        .sort((a, b) => a.year - b.year);
+}
+export function maxDrawdown(dates, twrIndex) {
+    let peak = twrIndex[0];
+    let peakDate = dates[0];
+    let maxDd = 0;
+    let ddPeakDate = dates[0];
+    let troughDate = dates[0];
+    let troughIdx = 0;
+    for (let t = 1; t < twrIndex.length; t++) {
+        if (twrIndex[t] > peak) {
+            peak = twrIndex[t];
+            peakDate = dates[t];
+        }
+        const dd = twrIndex[t] / peak - 1;
+        if (dd < maxDd) {
+            maxDd = dd;
+            ddPeakDate = peakDate;
+            troughDate = dates[t];
+            troughIdx = t;
+        }
+    }
+    // Recovery: first date after the trough where the index regains its peak.
+    let recoveryDate = null;
+    if (maxDd < 0) {
+        const peakLevel = twrIndex[dates.indexOf(ddPeakDate)];
+        for (let t = troughIdx + 1; t < twrIndex.length; t++) {
+            if (twrIndex[t] >= peakLevel) {
+                recoveryDate = dates[t];
+                break;
+            }
+        }
+    }
+    return { maxDrawdown: maxDd, peakDate: ddPeakDate, troughDate, recoveryDate };
+}
+/**
+ * Money-weighted annual return via bisection on the rate that zeroes the
+ * NPV of {initial investment, flows, final value}.
+ */
+export function irr(dates, flows, initialAmount, finalValue) {
+    const t0 = Date.parse(dates[0]);
+    const horizon = yearsBetween(dates[0], dates[dates.length - 1]);
+    if (horizon <= 0)
+        return 0;
+    const npv = (rate) => {
+        let v = -initialAmount;
+        for (let t = 1; t < dates.length; t++) {
+            if (flows[t] !== 0) {
+                const yrs = (Date.parse(dates[t]) - t0) / DAY_MS / 365.25;
+                v -= flows[t] / (1 + rate) ** yrs;
+            }
+        }
+        v += finalValue / (1 + rate) ** horizon;
+        return v;
+    };
+    let lo = -0.9999;
+    let hi = 10;
+    // Short horizons annualize to enormous rates — expand the bracket as needed.
+    while (npv(hi) > 0 && hi < 1e12)
+        hi *= 10;
+    if (npv(lo) * npv(hi) > 0)
+        return NaN; // no sign change — IRR undefined
+    for (let i = 0; i < 200; i++) {
+        const mid = (lo + hi) / 2;
+        if (npv(lo) * npv(mid) <= 0)
+            hi = mid;
+        else
+            lo = mid;
+    }
+    return (lo + hi) / 2;
+}
+export function computeMetrics(dates, twrIndex, values, flows, riskFreeRate, rfByMonth) {
+    const totalReturn = twrIndex[twrIndex.length - 1] / twrIndex[0] - 1;
+    const horizon = yearsBetween(dates[0], dates[dates.length - 1]);
+    const cagr = horizon > 0 ? (1 + totalReturn) ** (1 / horizon) - 1 : 0;
+    const labeled = monthlyReturnsLabeled(dates, twrIndex);
+    const monthly = labeled.map((m) => m.ret);
+    const rfConst = (1 + riskFreeRate) ** (1 / 12) - 1;
+    // Prefer the contemporaneous monthly T-bill return when supplied.
+    const excess = labeled.map((m) => m.ret - (rfByMonth?.[m.month] ?? rfConst));
+    const monthlyStdev = stdev(monthly);
+    const volatility = monthlyStdev * Math.sqrt(12);
+    const sharpe = monthlyStdev > 0 ? (mean(excess) / monthlyStdev) * Math.sqrt(12) : 0;
+    // Downside deviation over ALL months (Portfolio Visualizer convention).
+    const downside = Math.sqrt(mean(excess.map((e) => Math.min(0, e) ** 2)));
+    const sortino = downside > 0 ? (mean(excess) / downside) * Math.sqrt(12) : 0;
+    const annual = annualReturns(dates, twrIndex);
+    // Partial first/last years still count for best/worst, matching PV.
+    const best = annual.length
+        ? annual.reduce((a, b) => (b.return > a.return ? b : a))
+        : null;
+    const worst = annual.length
+        ? annual.reduce((a, b) => (b.return < a.return ? b : a))
+        : null;
+    return {
+        totalReturn,
+        cagr,
+        volatility,
+        sharpe,
+        sortino,
+        drawdown: maxDrawdown(dates, twrIndex),
+        annualReturns: annual,
+        bestYear: best,
+        worstYear: worst,
+        irr: irr(dates, flows, values[0], values[values.length - 1]),
+    };
+}
+//# sourceMappingURL=metrics.js.map

package/dist/engine/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../src/engine/metrics.ts"],"names":[],"mappings":"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"}

package/dist/engine/types.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Canonical daily record, matching data/tickers/<TICKER>.json from the
+ * Tiingo fetch layer. `close` is unadjusted; `adjClose` is split- and
+ * dividend-adjusted as of fetch time.
+ */
+export interface DailyRecord {
+    date: string;
+    close: number;
+    adjClose: number;
+    divCash: number;
+    splitFactor: number;
+}
+export interface TickerSeries {
+    ticker: string;
+    name?: string;
+    records: DailyRecord[];
+}
+export type RebalanceFrequency = 'none' | 'annual' | 'quarterly' | 'monthly';
+export interface Allocation {
+    ticker: string;
+    /** Target weight in percent, e.g. 60 for 60%. Must sum to 100 across the portfolio. */
+    weight: number;
+}
+export interface PortfolioSpec {
+    name: string;
+    allocations: Allocation[];
+}
+export interface BacktestConfig {
+    /** yyyy-mm-dd inclusive bounds. Clamped to the common history of all tickers. */
+    start?: string;
+    end?: string;
+    initialAmount: number;
+    /** Cash added (+) or withdrawn (−) at the start of each calendar month, invested at target weights. */
+    monthlyContribution: number;
+    rebalance: RebalanceFrequency;
+    /** true = dividends reinvested same day (total return). false = dividends accrue as uninvested cash. */
+    reinvestDividends: boolean;
+    /** Constant annual risk-free rate for Sharpe/Sortino, e.g. 0.03. Defaults to 0. */
+    riskFreeRate?: number;
+    /**
+     * Historical MONTHLY risk-free returns keyed by 'yyyy-mm' (e.g. from the
+     * Fama-French RF series). When provided, Sharpe/Sortino use the actual
+     * contemporaneous T-bill return each month instead of the constant.
+     */
+    rfByMonth?: Record<string, number>;
+}
+/** Semantics of the simulation, documented once:
+ * - Calendar = intersection of all tickers' trading days within [start, end].
+ * - Day 0: initial amount buys in at the close. Returns accrue from day 1.
+ * - Monthly cashflows and rebalancing execute at the START of the first
+ *   trading day of the period, at the prior day's closing values.
+ * - Reinvested dividends compound via adjClose ratios (reinvest at close on
+ *   ex-date). Non-reinvested dividends accrue to a cash bucket earning 0%.
+ */
+export interface BacktestResult {
+    portfolio: PortfolioSpec;
+    dates: string[];
+    /** Total portfolio market value per day (holdings + dividend cash), after flows. */
+    values: number[];
+    /** Time-weighted return index, 1.0 at day 0. Flows are excluded — use for all metrics. */
+    twrIndex: number[];
+    /** External flow applied at the start of each day (contributions/withdrawals). */
+    flows: number[];
+    /**
+     * Cash dividends received each day (before any reinvestment). When
+     * reinvesting, this money bought shares the same day — it is still income.
+     */
+    dividendIncome: number[];
+    endingCash: number;
+    totalContributions: number;
+    /** Per-ticker breakdown at the end of the period. */
+    holdings: HoldingBreakdown[];
+    metrics: MetricSet;
+}
+export interface HoldingBreakdown {
+    ticker: string;
+    /** Target weight in percent, from the portfolio spec. */
+    targetWeight: number;
+    endValue: number;
+    /** Share of final portfolio value (incl. dividend cash), percent. */
+    endWeight: number;
+    /** The asset's own cumulative total return over the period (standalone). */
+    assetTotalReturn: number;
+    /** Dividends this holding paid into the portfolio over the period. */
+    income: number;
+}
+export interface DrawdownInfo {
+    maxDrawdown: number;
+    peakDate: string;
+    troughDate: string;
+    /** Date the previous peak was regained, or null if not yet recovered. */
+    recoveryDate: string | null;
+}
+export interface YearReturn {
+    year: number;
+    return: number;
+}
+/** One rolling-window observation, keyed by the window's end date. */
+export interface RollingPoint {
+    date: string;
+    /** Annualized return over the trailing window. */
+    value: number;
+}
+export interface MetricSet {
+    totalReturn: number;
+    cagr: number;
+    /** Annualized from monthly return stdev (×√12), Portfolio Visualizer convention. */
+    volatility: number;
+    sharpe: number;
+    sortino: number;
+    drawdown: DrawdownInfo;
+    annualReturns: YearReturn[];
+    bestYear: YearReturn | null;
+    worstYear: YearReturn | null;
+    /** Money-weighted annual return (IRR). Equals CAGR when there are no flows. */
+    irr: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/engine/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/engine/types.ts"],"names":[],"mappings":"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"}

package/dist/engine/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/engine/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/engine/types.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @calculator53295/backtest-engine
+ *
+ * Pure TypeScript backtest and retirement-simulation engine.
+ * Zero runtime dependencies — this is a hard constraint of the engine.
+ *
+ * Lifted verbatim from Fathom's fixture-guarded engine (app/src/engine +
+ * app/src/montecarlo). One engine, three consumers: retirement-sim, Fathom,
+ * finance-master. This repo must never contain personal financial data —
+ * synthetic or public-market fixtures only.
+ */
+/** Package version. Kept in sync with package.json at release time. */
+export declare const VERSION = "0.1.0";
+export * from './engine/index.js';
+export { mulberry32, trialMonths, runHistoricalSequence, runBootstrap, maxSafeWithdrawal, type WithdrawalStrategy, type SimParams, type RealReturnSeries, type SimResult, } from './montecarlo/simulate.js';
+export { buildRealReturns, type AllocationWeight, type AssetData, } from './montecarlo/data.js';
+/**
+ * Canonical type vocabulary + adapters reconciling the Fathom and
+ * retirement-sim dialects. Namespaced to avoid colliding with the engines'
+ * flat exports (both define an `Allocation`, a `WithdrawalStrategy`, etc.).
+ */
+export * as canonical from './canonical/index.js';
+/** Historical retirement simulation engine and withdrawal strategy registry. */
+export * as retirement from './retirement/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,uEAAuE;AACvE,eAAO,MAAM,OAAO,UAAU,CAAC;AAE/B,cAAc,mBAAmB,CAAA;AACjC,OAAO,EACL,UAAU,EACV,WAAW,EACX,qBAAqB,EACrB,YAAY,EACZ,iBAAiB,EACjB,KAAK,kBAAkB,EACvB,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,SAAS,GACf,MAAM,0BAA0B,CAAA;AACjC,OAAO,EACL,gBAAgB,EAChB,KAAK,gBAAgB,EACrB,KAAK,SAAS,GACf,MAAM,sBAAsB,CAAA;AAE7B;;;;GAIG;AACH,OAAO,KAAK,SAAS,MAAM,sBAAsB,CAAA;AAEjD,gFAAgF;AAChF,OAAO,KAAK,UAAU,MAAM,uBAAuB,CAAA"}

package/dist/index.js

@@ -0,0 +1,25 @@
+/**
+ * @calculator53295/backtest-engine
+ *
+ * Pure TypeScript backtest and retirement-simulation engine.
+ * Zero runtime dependencies — this is a hard constraint of the engine.
+ *
+ * Lifted verbatim from Fathom's fixture-guarded engine (app/src/engine +
+ * app/src/montecarlo). One engine, three consumers: retirement-sim, Fathom,
+ * finance-master. This repo must never contain personal financial data —
+ * synthetic or public-market fixtures only.
+ */
+/** Package version. Kept in sync with package.json at release time. */
+export const VERSION = "0.1.0";
+export * from './engine/index.js';
+export { mulberry32, trialMonths, runHistoricalSequence, runBootstrap, maxSafeWithdrawal, } from './montecarlo/simulate.js';
+export { buildRealReturns, } from './montecarlo/data.js';
+/**
+ * Canonical type vocabulary + adapters reconciling the Fathom and
+ * retirement-sim dialects. Namespaced to avoid colliding with the engines'
+ * flat exports (both define an `Allocation`, a `WithdrawalStrategy`, etc.).
+ */
+export * as canonical from './canonical/index.js';
+/** Historical retirement simulation engine and withdrawal strategy registry. */
+export * as retirement from './retirement/index.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,uEAAuE;AACvE,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAE/B,cAAc,mBAAmB,CAAA;AACjC,OAAO,EACL,UAAU,EACV,WAAW,EACX,qBAAqB,EACrB,YAAY,EACZ,iBAAiB,GAKlB,MAAM,0BAA0B,CAAA;AACjC,OAAO,EACL,gBAAgB,GAGjB,MAAM,sBAAsB,CAAA;AAE7B;;;;GAIG;AACH,OAAO,KAAK,SAAS,MAAM,sBAAsB,CAAA;AAEjD,gFAAgF;AAChF,OAAO,KAAK,UAAU,MAAM,uBAAuB,CAAA"}

package/dist/montecarlo/data.d.ts

@@ -0,0 +1,17 @@
+import type { RealReturnSeries } from './simulate.js';
+export interface AllocationWeight {
+    assetId: string;
+    weight: number;
+}
+/** The asset-class data shape returned by loadAssetClassData(). */
+export interface AssetData {
+    returns: Map<string, Map<string, number>>;
+    cpi: Map<string, number>;
+}
+/**
+ * Build a blended REAL monthly return series for an allocation, over the range
+ * all its assets (and CPI) share. Monthly rebalancing (a weighted average of
+ * each asset's monthly return); nominal is deflated to real via CPI.
+ */
+export declare function buildRealReturns(allocation: AllocationWeight[], data: AssetData): RealReturnSeries;
+//# sourceMappingURL=data.d.ts.map

package/dist/montecarlo/data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data.d.ts","sourceRoot":"","sources":["../../src/montecarlo/data.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAErD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;CACf;AAED,mEAAmE;AACnE,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACzC,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACzB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,gBAAgB,EAAE,EAC9B,IAAI,EAAE,SAAS,GACd,gBAAgB,CA8BlB"}

package/dist/montecarlo/data.js

@@ -0,0 +1,38 @@
+/**
+ * Build a blended REAL monthly return series for an allocation, over the range
+ * all its assets (and CPI) share. Monthly rebalancing (a weighted average of
+ * each asset's monthly return); nominal is deflated to real via CPI.
+ */
+export function buildRealReturns(allocation, data) {
+    const active = allocation.filter((a) => a.weight > 0);
+    if (active.length === 0)
+        return { dates: [], returns: [] };
+    const totalWeight = active.reduce((s, a) => s + a.weight, 0);
+    // Common months present in every asset AND cpi.
+    const maps = active.map((a) => data.returns.get(a.assetId));
+    if (maps.some((m) => !m))
+        return { dates: [], returns: [] };
+    const first = maps[0];
+    const common = [];
+    for (const ym of first.keys()) {
+        if (data.cpi.has(ym) && maps.every((m) => m.has(ym)))
+            common.push(ym);
+    }
+    common.sort();
+    const dates = [];
+    const returns = [];
+    for (let i = 1; i < common.length; i++) {
+        const ym = common[i];
+        const prevCpi = data.cpi.get(common[i - 1]);
+        const curCpi = data.cpi.get(ym);
+        let nominal = 0;
+        for (let a = 0; a < active.length; a++) {
+            nominal += (active[a].weight / totalWeight) * maps[a].get(ym);
+        }
+        const inflation = curCpi / prevCpi;
+        dates.push(ym);
+        returns.push((1 + nominal) / inflation - 1);
+    }
+    return { dates, returns };
+}
+//# sourceMappingURL=data.js.map

package/dist/montecarlo/data.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data.js","sourceRoot":"","sources":["../../src/montecarlo/data.ts"],"names":[],"mappings":"AAaA;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAC9B,UAA8B,EAC9B,IAAe;IAEf,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IACrD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,CAAA;IAC1D,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA;IAE5D,gDAAgD;IAChD,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAA;IAC3D,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,CAAA;IAC3D,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAE,CAAA;IACtB,MAAM,MAAM,GAAa,EAAE,CAAA;IAC3B,KAAK,MAAM,EAAE,IAAI,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QAC9B,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAAE,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IACxE,CAAC;IACD,MAAM,CAAC,IAAI,EAAE,CAAA;IAEb,MAAM,KAAK,GAAa,EAAE,CAAA;IAC1B,MAAM,OAAO,GAAa,EAAE,CAAA;IAC5B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,CAAA;QACpB,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAE,CAAA;QAC5C,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAE,CAAA;QAChC,IAAI,OAAO,GAAG,CAAC,CAAA;QACf,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACvC,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,WAAW,CAAC,GAAG,IAAI,CAAC,CAAC,CAAE,CAAC,GAAG,CAAC,EAAE,CAAE,CAAA;QACjE,CAAC;QACD,MAAM,SAAS,GAAG,MAAM,GAAG,OAAO,CAAA;QAClC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;QACd,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,GAAG,SAAS,GAAG,CAAC,CAAC,CAAA;IAC7C,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAA;AAC3B,CAAC"}