@calculator53295/backtest-engine 0.1.0

package/dist/canonical/returns.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Canonical monthly real-return series + adapters into it.
+ *
+ * The canonical series is the Monte Carlo `RealReturnSeries` (monthly, real,
+ * fractional) — it is what `runHistoricalSequence`/`runBootstrap` consume. The
+ * two upstream shapes are:
+ *  - Fathom `TickerSeries`: daily nominal price records (handled elsewhere by
+ *    the engine's alignment layer, not here).
+ *  - retirement-sim `HistoricalRow`: monthly nominal returns per asset class
+ *    plus a CPI level.
+ *
+ * `historicalRowsToRealReturns` converts the monthly rows using the same
+ * real-return math as `montecarlo/data.ts`: blend the nominal per-asset returns
+ * by allocation, then deflate by month-over-month CPI growth. The bond/cash
+ * composition is unambiguous here (each row carries a separate bond and cash
+ * return), so the default blend is the allocation-weighted average — but the
+ * blend is exposed as an explicit parameter for callers whose asset set or
+ * weighting differs.
+ */
+import type { RealReturnSeries } from '../montecarlo/simulate.js';
+import type { Buckets } from './allocation.js';
+/**
+ * retirement-sim's monthly historical row (mirrored structurally; staging is
+ * read-only). Returns are NOMINAL monthly fractions; `cpi` is an index level.
+ */
+export interface HistoricalRow {
+    /** 'YYYY-MM' (or 'YYYY-MM-DD', normalized to month on output). */
+    date: string;
+    /** Nominal monthly stock (S&P) return. */
+    spReturn: number;
+    /** Nominal monthly bond return. */
+    bondReturn: number;
+    /** Nominal monthly cash return. */
+    cashReturn: number;
+    /** CPI index level for the month. */
+    cpi: number;
+    /** Optional Shiller CAPE for the month. */
+    cape?: number;
+}
+/** Blends a row's per-asset nominal returns into one portfolio nominal return. */
+export type ReturnBlend = (row: HistoricalRow, allocation: Buckets) => number;
+/**
+ * Default blend: allocation-weighted average of the three bucket returns,
+ * normalized by the total weight so unnormalized buckets still behave. This
+ * matches `buildRealReturns`'s weighting convention.
+ */
+export declare const weightedBucketBlend: ReturnBlend;
+export interface HistoricalRowsOptions {
+    /** Override the per-row nominal blend (default: `weightedBucketBlend`). */
+    blend?: ReturnBlend;
+}
+/**
+ * Convert monthly `HistoricalRow`s into a canonical `RealReturnSeries`.
+ *
+ * For each month i ≥ 1: inflation = cpi[i] / cpi[i-1]; nominal = blend(row[i]);
+ * real = (1 + nominal) / inflation − 1. The label emitted is month i (the
+ * month the return occurs in), matching `buildRealReturns`. The first row seeds
+ * the CPI base and produces no return, so a series of N rows yields N−1 points.
+ */
+export declare function historicalRowsToRealReturns(rows: HistoricalRow[], allocation: Buckets, options?: HistoricalRowsOptions): RealReturnSeries;
+//# sourceMappingURL=returns.d.ts.map

package/dist/canonical/returns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"returns.d.ts","sourceRoot":"","sources":["../../src/canonical/returns.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAA;AACjE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAG9C;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAA;IACZ,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAA;IAChB,mCAAmC;IACnC,UAAU,EAAE,MAAM,CAAA;IAClB,mCAAmC;IACnC,UAAU,EAAE,MAAM,CAAA;IAClB,qCAAqC;IACrC,GAAG,EAAE,MAAM,CAAA;IACX,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,kFAAkF;AAClF,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,aAAa,EAAE,UAAU,EAAE,OAAO,KAAK,MAAM,CAAA;AAE7E;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,WAQjC,CAAA;AAED,MAAM,WAAW,qBAAqB;IACpC,2EAA2E;IAC3E,KAAK,CAAC,EAAE,WAAW,CAAA;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,aAAa,EAAE,EACrB,UAAU,EAAE,OAAO,EACnB,OAAO,GAAE,qBAA0B,GAClC,gBAAgB,CAoBlB"}

package/dist/canonical/returns.js

@@ -0,0 +1,65 @@
+/**
+ * Canonical monthly real-return series + adapters into it.
+ *
+ * The canonical series is the Monte Carlo `RealReturnSeries` (monthly, real,
+ * fractional) — it is what `runHistoricalSequence`/`runBootstrap` consume. The
+ * two upstream shapes are:
+ *  - Fathom `TickerSeries`: daily nominal price records (handled elsewhere by
+ *    the engine's alignment layer, not here).
+ *  - retirement-sim `HistoricalRow`: monthly nominal returns per asset class
+ *    plus a CPI level.
+ *
+ * `historicalRowsToRealReturns` converts the monthly rows using the same
+ * real-return math as `montecarlo/data.ts`: blend the nominal per-asset returns
+ * by allocation, then deflate by month-over-month CPI growth. The bond/cash
+ * composition is unambiguous here (each row carries a separate bond and cash
+ * return), so the default blend is the allocation-weighted average — but the
+ * blend is exposed as an explicit parameter for callers whose asset set or
+ * weighting differs.
+ */
+import { toMonthKey } from './dates.js';
+/**
+ * Default blend: allocation-weighted average of the three bucket returns,
+ * normalized by the total weight so unnormalized buckets still behave. This
+ * matches `buildRealReturns`'s weighting convention.
+ */
+export const weightedBucketBlend = (row, allocation) => {
+    const total = allocation.stocks + allocation.bonds + allocation.cash;
+    if (total <= 0)
+        return 0;
+    const weighted = allocation.stocks * row.spReturn +
+        allocation.bonds * row.bondReturn +
+        allocation.cash * row.cashReturn;
+    return weighted / total;
+};
+/**
+ * Convert monthly `HistoricalRow`s into a canonical `RealReturnSeries`.
+ *
+ * For each month i ≥ 1: inflation = cpi[i] / cpi[i-1]; nominal = blend(row[i]);
+ * real = (1 + nominal) / inflation − 1. The label emitted is month i (the
+ * month the return occurs in), matching `buildRealReturns`. The first row seeds
+ * the CPI base and produces no return, so a series of N rows yields N−1 points.
+ */
+export function historicalRowsToRealReturns(rows, allocation, options = {}) {
+    const blend = options.blend ?? weightedBucketBlend;
+    const dates = [];
+    const returns = [];
+    for (let i = 1; i < rows.length; i++) {
+        const prev = rows[i - 1];
+        const cur = rows[i];
+        if (!prev || !cur)
+            continue;
+        if (!Number.isFinite(prev.cpi) || prev.cpi <= 0) {
+            throw new Error(`Invalid CPI at '${prev.date}': expected a positive finite value`);
+        }
+        if (!Number.isFinite(cur.cpi) || cur.cpi <= 0) {
+            throw new Error(`Invalid CPI at '${cur.date}': expected a positive finite value`);
+        }
+        const inflation = cur.cpi / prev.cpi;
+        const nominal = blend(cur, allocation);
+        dates.push(toMonthKey(cur.date));
+        returns.push((1 + nominal) / inflation - 1);
+    }
+    return { dates, returns };
+}
+//# sourceMappingURL=returns.js.map

package/dist/canonical/returns.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"returns.js","sourceRoot":"","sources":["../../src/canonical/returns.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAwBvC;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAgB,CAAC,GAAG,EAAE,UAAU,EAAE,EAAE;IAClE,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,GAAG,UAAU,CAAC,KAAK,GAAG,UAAU,CAAC,IAAI,CAAA;IACpE,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,CAAC,CAAA;IACxB,MAAM,QAAQ,GACZ,UAAU,CAAC,MAAM,GAAG,GAAG,CAAC,QAAQ;QAChC,UAAU,CAAC,KAAK,GAAG,GAAG,CAAC,UAAU;QACjC,UAAU,CAAC,IAAI,GAAG,GAAG,CAAC,UAAU,CAAA;IAClC,OAAO,QAAQ,GAAG,KAAK,CAAA;AACzB,CAAC,CAAA;AAOD;;;;;;;GAOG;AACH,MAAM,UAAU,2BAA2B,CACzC,IAAqB,EACrB,UAAmB,EACnB,UAAiC,EAAE;IAEnC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,mBAAmB,CAAA;IAClD,MAAM,KAAK,GAAa,EAAE,CAAA;IAC1B,MAAM,OAAO,GAAa,EAAE,CAAA;IAC5B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;QACxB,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAA;QACnB,IAAI,CAAC,IAAI,IAAI,CAAC,GAAG;YAAE,SAAQ;QAC3B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC;YAChD,MAAM,IAAI,KAAK,CAAC,mBAAmB,IAAI,CAAC,IAAI,qCAAqC,CAAC,CAAA;QACpF,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC;YAC9C,MAAM,IAAI,KAAK,CAAC,mBAAmB,GAAG,CAAC,IAAI,qCAAqC,CAAC,CAAA;QACnF,CAAC;QACD,MAAM,SAAS,GAAG,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAA;QACpC,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,EAAE,UAAU,CAAC,CAAA;QACtC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAA;QAChC,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"}

package/dist/canonical/strategy.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Canonical withdrawal-strategy ids.
+ *
+ * Three vocabularies name the same family of rules differently:
+ *  - Monte Carlo (`src/montecarlo/simulate.ts`): 'fixedReal' | 'fixedPercent' |
+ *    'vpw' | 'guardrails' — a camelCase four.
+ *  - retirement-sim registry (`staging/retirement-sim/strategies/index.ts`):
+ *    a kebab-case superset ('constant-dollar', 'percent-of-portfolio',
+ *    'one-over-n', 'vpw', 'guyton-klinger', 'cape-based', '95-percent',
+ *    'endowment', 'vanguard-dynamic', plus legacy aliases).
+ *
+ * Canonical ids are the kebab-case superset (they already read as the shared
+ * vocabulary). Mappings carry an `approximate` flag and a `note` whenever two
+ * ids name rules that are close but NOT identical — so the difference is
+ * documented at the boundary instead of being silently equated. The Monte
+ * Carlo 'guardrails' rule is a simplified 20%/10% band; it is mapped to
+ * 'guyton-klinger' as an APPROXIMATION, never as an equality.
+ */
+import type { WithdrawalStrategy as MontecarloStrategy } from '../montecarlo/simulate.js';
+/** Monte Carlo strategy id (re-export of the camelCase union). */
+export type MontecarloStrategyId = MontecarloStrategy;
+/** Canonical, kebab-case strategy ids (the retirement-sim "new kinds" superset). */
+export type CanonicalStrategyId = 'constant-dollar' | 'percent-of-portfolio' | 'one-over-n' | 'vpw' | 'guyton-klinger' | 'cape-based' | '95-percent' | 'endowment' | 'vanguard-dynamic';
+export declare const CANONICAL_STRATEGY_IDS: readonly CanonicalStrategyId[];
+/**
+ * retirement-sim `StrategyKind`: the canonical superset plus legacy aliases
+ * and the non-rule 'interactive' mode (mirrored structurally; staging is
+ * read-only).
+ */
+export type RetirementStrategyKind = CanonicalStrategyId | 'fixed-real' | 'fixed-pct' | 'guardrails' | 'interactive';
+/** Result of a strategy-id mapping: the canonical id + whether it's exact. */
+export interface StrategyMapping<Id extends string = CanonicalStrategyId> {
+    id: Id;
+    /** True when the source rule is only approximately the mapped rule. */
+    approximate: boolean;
+    /** Present only for approximate mappings: what the approximation glosses over. */
+    note?: string;
+}
+/** Monte Carlo id → canonical id. Exact except 'guardrails' (≈ Guyton-Klinger). */
+export declare const MONTECARLO_TO_CANONICAL: Record<MontecarloStrategyId, StrategyMapping>;
+/** Map a Monte Carlo strategy id to its canonical id. */
+export declare function montecarloToCanonicalStrategy(id: MontecarloStrategyId): StrategyMapping;
+/**
+ * Map a canonical id back to a Monte Carlo id. The Monte Carlo engine only
+ * implements four rules, so canonical ids outside that set (one-over-n,
+ * cape-based, 95-percent, endowment, vanguard-dynamic) have no equivalent and
+ * throw rather than being coerced to a nearest neighbour.
+ */
+export declare function canonicalToMontecarloStrategy(id: CanonicalStrategyId): StrategyMapping<MontecarloStrategyId>;
+/**
+ * Map a retirement-sim `StrategyKind` to its canonical id. The "new kinds" are
+ * already canonical (identity); legacy aliases fold onto their modern id, and
+ * the non-rule 'interactive' mode throws (it has no withdrawal-rule id).
+ */
+export declare function retirementToCanonicalStrategy(kind: RetirementStrategyKind): StrategyMapping;
+/**
+ * Map a canonical id to retirement-sim's modern strategy id. Canonical ids
+ * were deliberately chosen from the modern retirement-sim vocabulary, so
+ * this direction is exact and total.
+ */
+export declare function canonicalToRetirementStrategy(id: CanonicalStrategyId): StrategyMapping<CanonicalStrategyId>;
+//# sourceMappingURL=strategy.d.ts.map

package/dist/canonical/strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy.d.ts","sourceRoot":"","sources":["../../src/canonical/strategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,IAAI,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAEzF,kEAAkE;AAClE,MAAM,MAAM,oBAAoB,GAAG,kBAAkB,CAAA;AAErD,oFAAoF;AACpF,MAAM,MAAM,mBAAmB,GAC3B,iBAAiB,GACjB,sBAAsB,GACtB,YAAY,GACZ,KAAK,GACL,gBAAgB,GAChB,YAAY,GACZ,YAAY,GACZ,WAAW,GACX,kBAAkB,CAAA;AAEtB,eAAO,MAAM,sBAAsB,EAAE,SAAS,mBAAmB,EAUhE,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAC9B,mBAAmB,GACnB,YAAY,GACZ,WAAW,GACX,YAAY,GACZ,aAAa,CAAA;AAEjB,8EAA8E;AAC9E,MAAM,WAAW,eAAe,CAAC,EAAE,SAAS,MAAM,GAAG,mBAAmB;IACtE,EAAE,EAAE,EAAE,CAAA;IACN,uEAAuE;IACvE,WAAW,EAAE,OAAO,CAAA;IACpB,kFAAkF;IAClF,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AASD,mFAAmF;AACnF,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAAC,oBAAoB,EAAE,eAAe,CAKjF,CAAA;AAED,yDAAyD;AACzD,wBAAgB,6BAA6B,CAAC,EAAE,EAAE,oBAAoB,GAAG,eAAe,CAIvF;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,EAAE,EAAE,mBAAmB,GACtB,eAAe,CAAC,oBAAoB,CAAC,CAavC;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,sBAAsB,GAAG,eAAe,CAoB3F;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC3C,EAAE,EAAE,mBAAmB,GACtB,eAAe,CAAC,mBAAmB,CAAC,CAEtC"}

package/dist/canonical/strategy.js

@@ -0,0 +1,103 @@
+/**
+ * Canonical withdrawal-strategy ids.
+ *
+ * Three vocabularies name the same family of rules differently:
+ *  - Monte Carlo (`src/montecarlo/simulate.ts`): 'fixedReal' | 'fixedPercent' |
+ *    'vpw' | 'guardrails' — a camelCase four.
+ *  - retirement-sim registry (`staging/retirement-sim/strategies/index.ts`):
+ *    a kebab-case superset ('constant-dollar', 'percent-of-portfolio',
+ *    'one-over-n', 'vpw', 'guyton-klinger', 'cape-based', '95-percent',
+ *    'endowment', 'vanguard-dynamic', plus legacy aliases).
+ *
+ * Canonical ids are the kebab-case superset (they already read as the shared
+ * vocabulary). Mappings carry an `approximate` flag and a `note` whenever two
+ * ids name rules that are close but NOT identical — so the difference is
+ * documented at the boundary instead of being silently equated. The Monte
+ * Carlo 'guardrails' rule is a simplified 20%/10% band; it is mapped to
+ * 'guyton-klinger' as an APPROXIMATION, never as an equality.
+ */
+export const CANONICAL_STRATEGY_IDS = [
+    'constant-dollar',
+    'percent-of-portfolio',
+    'one-over-n',
+    'vpw',
+    'guyton-klinger',
+    'cape-based',
+    '95-percent',
+    'endowment',
+    'vanguard-dynamic',
+];
+const GUARDRAILS_NOTE = "Monte Carlo 'guardrails' is a simplified Guyton-Klinger: it cuts the real " +
+    'withdrawal 10% when the current rate drifts 20% above the initial rate and ' +
+    'raises it 10% when 20% below. Full Guyton-Klinger additionally applies an ' +
+    'inflation cap, a post-loss inflation skip, and a preservation/prosperity ' +
+    'timing window. Treat as an approximation, not an equivalence.';
+/** Monte Carlo id → canonical id. Exact except 'guardrails' (≈ Guyton-Klinger). */
+export const MONTECARLO_TO_CANONICAL = {
+    fixedReal: { id: 'constant-dollar', approximate: false },
+    fixedPercent: { id: 'percent-of-portfolio', approximate: false },
+    vpw: { id: 'vpw', approximate: false },
+    guardrails: { id: 'guyton-klinger', approximate: true, note: GUARDRAILS_NOTE },
+};
+/** Map a Monte Carlo strategy id to its canonical id. */
+export function montecarloToCanonicalStrategy(id) {
+    const mapping = MONTECARLO_TO_CANONICAL[id];
+    if (!mapping)
+        throw new Error(`Unknown Monte Carlo strategy '${id}'`);
+    return mapping;
+}
+/**
+ * Map a canonical id back to a Monte Carlo id. The Monte Carlo engine only
+ * implements four rules, so canonical ids outside that set (one-over-n,
+ * cape-based, 95-percent, endowment, vanguard-dynamic) have no equivalent and
+ * throw rather than being coerced to a nearest neighbour.
+ */
+export function canonicalToMontecarloStrategy(id) {
+    switch (id) {
+        case 'constant-dollar':
+            return { id: 'fixedReal', approximate: false };
+        case 'percent-of-portfolio':
+            return { id: 'fixedPercent', approximate: false };
+        case 'vpw':
+            return { id: 'vpw', approximate: false };
+        case 'guyton-klinger':
+            return { id: 'guardrails', approximate: true, note: GUARDRAILS_NOTE };
+        default:
+            throw new Error(`Canonical strategy '${id}' has no Monte Carlo equivalent`);
+    }
+}
+/**
+ * Map a retirement-sim `StrategyKind` to its canonical id. The "new kinds" are
+ * already canonical (identity); legacy aliases fold onto their modern id, and
+ * the non-rule 'interactive' mode throws (it has no withdrawal-rule id).
+ */
+export function retirementToCanonicalStrategy(kind) {
+    if (CANONICAL_STRATEGY_IDS.includes(kind)) {
+        return { id: kind, approximate: false };
+    }
+    switch (kind) {
+        case 'fixed-real':
+            return { id: 'constant-dollar', approximate: false };
+        case 'fixed-pct':
+            return { id: 'percent-of-portfolio', approximate: false };
+        case 'guardrails':
+            return {
+                id: 'guyton-klinger',
+                approximate: true,
+                note: "Legacy 'guardrails' is a simplified guardrail rule; Guyton-Klinger is the full ruleset.",
+            };
+        case 'interactive':
+            throw new Error("retirement-sim 'interactive' has no canonical withdrawal-rule id");
+        default:
+            throw new Error(`Unknown retirement-sim strategy kind '${kind}'`);
+    }
+}
+/**
+ * Map a canonical id to retirement-sim's modern strategy id. Canonical ids
+ * were deliberately chosen from the modern retirement-sim vocabulary, so
+ * this direction is exact and total.
+ */
+export function canonicalToRetirementStrategy(id) {
+    return { id, approximate: false };
+}
+//# sourceMappingURL=strategy.js.map

package/dist/canonical/strategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy.js","sourceRoot":"","sources":["../../src/canonical/strategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAmBH,MAAM,CAAC,MAAM,sBAAsB,GAAmC;IACpE,iBAAiB;IACjB,sBAAsB;IACtB,YAAY;IACZ,KAAK;IACL,gBAAgB;IAChB,YAAY;IACZ,YAAY;IACZ,WAAW;IACX,kBAAkB;CACnB,CAAA;AAuBD,MAAM,eAAe,GACnB,4EAA4E;IAC5E,6EAA6E;IAC7E,4EAA4E;IAC5E,2EAA2E;IAC3E,+DAA+D,CAAA;AAEjE,mFAAmF;AACnF,MAAM,CAAC,MAAM,uBAAuB,GAAkD;IACpF,SAAS,EAAE,EAAE,EAAE,EAAE,iBAAiB,EAAE,WAAW,EAAE,KAAK,EAAE;IACxD,YAAY,EAAE,EAAE,EAAE,EAAE,sBAAsB,EAAE,WAAW,EAAE,KAAK,EAAE;IAChE,GAAG,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE;IACtC,UAAU,EAAE,EAAE,EAAE,EAAE,gBAAgB,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,eAAe,EAAE;CAC/E,CAAA;AAED,yDAAyD;AACzD,MAAM,UAAU,6BAA6B,CAAC,EAAwB;IACpE,MAAM,OAAO,GAAG,uBAAuB,CAAC,EAAE,CAAC,CAAA;IAC3C,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,EAAE,GAAG,CAAC,CAAA;IACrE,OAAO,OAAO,CAAA;AAChB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,6BAA6B,CAC3C,EAAuB;IAEvB,QAAQ,EAAE,EAAE,CAAC;QACX,KAAK,iBAAiB;YACpB,OAAO,EAAE,EAAE,EAAE,WAAW,EAAE,WAAW,EAAE,KAAK,EAAE,CAAA;QAChD,KAAK,sBAAsB;YACzB,OAAO,EAAE,EAAE,EAAE,cAAc,EAAE,WAAW,EAAE,KAAK,EAAE,CAAA;QACnD,KAAK,KAAK;YACR,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,CAAA;QAC1C,KAAK,gBAAgB;YACnB,OAAO,EAAE,EAAE,EAAE,YAAY,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,eAAe,EAAE,CAAA;QACvE;YACE,MAAM,IAAI,KAAK,CAAC,uBAAuB,EAAE,iCAAiC,CAAC,CAAA;IAC/E,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,6BAA6B,CAAC,IAA4B;IACxE,IAAK,sBAA4C,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACjE,OAAO,EAAE,EAAE,EAAE,IAA2B,EAAE,WAAW,EAAE,KAAK,EAAE,CAAA;IAChE,CAAC;IACD,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,YAAY;YACf,OAAO,EAAE,EAAE,EAAE,iBAAiB,EAAE,WAAW,EAAE,KAAK,EAAE,CAAA;QACtD,KAAK,WAAW;YACd,OAAO,EAAE,EAAE,EAAE,sBAAsB,EAAE,WAAW,EAAE,KAAK,EAAE,CAAA;QAC3D,KAAK,YAAY;YACf,OAAO;gBACL,EAAE,EAAE,gBAAgB;gBACpB,WAAW,EAAE,IAAI;gBACjB,IAAI,EAAE,yFAAyF;aAChG,CAAA;QACH,KAAK,aAAa;YAChB,MAAM,IAAI,KAAK,CAAC,kEAAkE,CAAC,CAAA;QACrF;YACE,MAAM,IAAI,KAAK,CAAC,yCAAyC,IAAI,GAAG,CAAC,CAAA;IACrE,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,6BAA6B,CAC3C,EAAuB;IAEvB,OAAO,EAAE,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,CAAA;AACnC,CAAC"}

package/dist/engine/align.d.ts

@@ -0,0 +1,34 @@
+import type { DailyRecord, TickerSeries } from './types.js';
+/**
+ * Per-ticker daily return components on a shared calendar.
+ * All arrays have length = dates.length; index 0 is the buy-in day
+ * (returns there are identity: 1, 1, 0).
+ */
+export interface PreparedAsset {
+    ticker: string;
+    /** totalReturn[t] = adjClose[t] / adjClose[t-1] — dividends reinvested. */
+    totalReturn: number[];
+    /** priceReturn[t] = close[t] * splitFactor[t] / close[t-1] — splits neutralized, dividends dropped. */
+    priceReturn: number[];
+    /** divYield[t] = divCash[t] * (shares growth to t-1) / close[t-1] — cash dividend as fraction of prior value. */
+    divYield: number[];
+}
+export interface AlignedData {
+    dates: string[];
+    assets: Map<string, PreparedAsset>;
+}
+/**
+ * Build the shared calendar (intersection of trading days across all series,
+ * clamped to [start, end]) and per-ticker return components on it.
+ *
+ * Intersection can skip days a ticker traded (e.g. one fund had a holiday).
+ * Returns are computed from each ticker's own consecutive records BETWEEN
+ * calendar days, so a skipped day's move is never lost — it compounds into
+ * the next shared day.
+ */
+export declare function alignSeries(seriesList: TickerSeries[], start?: string, end?: string): AlignedData;
+/** True when `date` starts a new period vs `prevDate` for the given frequency. */
+export declare function isPeriodStart(prevDate: string, date: string, freq: 'annual' | 'quarterly' | 'monthly'): boolean;
+export declare function isNewMonth(prevDate: string, date: string): boolean;
+export type { DailyRecord };
+//# sourceMappingURL=align.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"align.d.ts","sourceRoot":"","sources":["../../src/engine/align.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE3D;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAA;IACd,2EAA2E;IAC3E,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,uGAAuG;IACvG,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,iHAAiH;IACjH,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;CACnC;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,YAAY,EAAE,EAC1B,KAAK,CAAC,EAAE,MAAM,EACd,GAAG,CAAC,EAAE,MAAM,GACX,WAAW,CAmCb;AAuCD,kFAAkF;AAClF,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,QAAQ,GAAG,WAAW,GAAG,SAAS,GACvC,OAAO,CAQT;AAED,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAElE;AAED,YAAY,EAAE,WAAW,EAAE,CAAA"}

package/dist/engine/align.js

@@ -0,0 +1,97 @@
+/**
+ * Build the shared calendar (intersection of trading days across all series,
+ * clamped to [start, end]) and per-ticker return components on it.
+ *
+ * Intersection can skip days a ticker traded (e.g. one fund had a holiday).
+ * Returns are computed from each ticker's own consecutive records BETWEEN
+ * calendar days, so a skipped day's move is never lost — it compounds into
+ * the next shared day.
+ */
+export function alignSeries(seriesList, start, end) {
+    if (seriesList.length === 0)
+        throw new Error('No ticker series provided');
+    // Effective range: caller's range clamped to common history.
+    let lo = start ?? '0000-00-00';
+    let hi = end ?? '9999-99-99';
+    for (const s of seriesList) {
+        if (s.records.length === 0)
+            throw new Error(`Empty series for ${s.ticker}`);
+        const first = s.records[0].date;
+        const last = s.records[s.records.length - 1].date;
+        if (first > lo)
+            lo = first;
+        if (last < hi)
+            hi = last;
+    }
+    if (lo > hi)
+        throw new Error(`No overlapping history in range ${lo}..${hi}`);
+    // Intersection of trading days within [lo, hi].
+    const counts = new Map();
+    for (const s of seriesList) {
+        for (const r of s.records) {
+            if (r.date >= lo && r.date <= hi) {
+                counts.set(r.date, (counts.get(r.date) ?? 0) + 1);
+            }
+        }
+    }
+    const dates = [...counts.entries()]
+        .filter(([, n]) => n === seriesList.length)
+        .map(([d]) => d)
+        .sort();
+    if (dates.length < 2)
+        throw new Error(`Fewer than 2 shared trading days in ${lo}..${hi}`);
+    const assets = new Map();
+    for (const s of seriesList) {
+        assets.set(s.ticker, prepareAsset(s, dates));
+    }
+    return { dates, assets };
+}
+function prepareAsset(series, dates) {
+    const byDate = new Map();
+    series.records.forEach((r, i) => byDate.set(r.date, i));
+    const totalReturn = [1];
+    const priceReturn = [1];
+    const divYield = [0];
+    for (let t = 1; t < dates.length; t++) {
+        const from = byDate.get(dates[t - 1]);
+        const to = byDate.get(dates[t]);
+        if (from === undefined || to === undefined) {
+            throw new Error(`${series.ticker} missing shared date ${dates[t - 1]} or ${dates[t]}`);
+        }
+        // Compound this ticker's own daily records across (from, to].
+        let tr = 1;
+        let pr = 1;
+        let dy = 0;
+        for (let i = from + 1; i <= to; i++) {
+            const prev = series.records[i - 1];
+            const cur = series.records[i];
+            tr *= cur.adjClose / prev.adjClose;
+            // A splitFactor of k means 1 share became k shares; neutralize the price drop.
+            const dayPr = (cur.close * cur.splitFactor) / prev.close;
+            // Dividend cash per unit of value held at `prev` close. Scale by shares
+            // accumulated through intermediate splits within this window (pr so far).
+            dy += (pr * (cur.divCash * cur.splitFactor)) / prev.close;
+            pr *= dayPr;
+        }
+        totalReturn.push(tr);
+        priceReturn.push(pr);
+        divYield.push(dy);
+    }
+    return { ticker: series.ticker, totalReturn, priceReturn, divYield };
+}
+/** True when `date` starts a new period vs `prevDate` for the given frequency. */
+export function isPeriodStart(prevDate, date, freq) {
+    const py = Number(prevDate.slice(0, 4));
+    const pm = Number(prevDate.slice(5, 7));
+    const cy = Number(date.slice(0, 4));
+    const cm = Number(date.slice(5, 7));
+    if (freq === 'annual')
+        return cy !== py;
+    if (freq === 'monthly')
+        return cy !== py || cm !== pm;
+    return cy !== py || Math.floor((cm - 1) / 3) !== Math.floor((pm - 1) / 3);
+}
+export function isNewMonth(prevDate, date) {
+    return prevDate.slice(0, 7) !== date.slice(0, 7);
+}
+//# sourceMappingURL=align.js.map

package/dist/engine/align.js.map

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

package/dist/engine/backtest.d.ts

@@ -0,0 +1,7 @@
+import type { BacktestConfig, BacktestResult, PortfolioSpec, TickerSeries } from './types.js';
+/**
+ * Run a portfolio backtest. See BacktestResult in types.ts for the exact
+ * simulation semantics (flow timing, rebalancing, dividend handling).
+ */
+export declare function runBacktest(seriesList: TickerSeries[], portfolio: PortfolioSpec, config: BacktestConfig): BacktestResult;
+//# sourceMappingURL=backtest.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"backtest.d.ts","sourceRoot":"","sources":["../../src/engine/backtest.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EACd,aAAa,EACb,YAAY,EACb,MAAM,YAAY,CAAA;AAEnB;;;GAGG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,YAAY,EAAE,EAC1B,SAAS,EAAE,aAAa,EACxB,MAAM,EAAE,cAAc,GACrB,cAAc,CAuGhB"}

package/dist/engine/backtest.js

@@ -0,0 +1,95 @@
+import { alignSeries, isNewMonth, isPeriodStart } from './align.js';
+import { computeMetrics } from './metrics.js';
+/**
+ * Run a portfolio backtest. See BacktestResult in types.ts for the exact
+ * simulation semantics (flow timing, rebalancing, dividend handling).
+ */
+export function runBacktest(seriesList, portfolio, config) {
+    const weightSum = portfolio.allocations.reduce((s, a) => s + a.weight, 0);
+    if (Math.abs(weightSum - 100) > 1e-6) {
+        throw new Error(`Weights must sum to 100, got ${weightSum}`);
+    }
+    const bySymbol = new Map(seriesList.map((s) => [s.ticker, s]));
+    const used = portfolio.allocations.map((a) => {
+        const s = bySymbol.get(a.ticker);
+        if (!s)
+            throw new Error(`Missing series for ${a.ticker}`);
+        return s;
+    });
+    const { dates, assets } = alignSeries(used, config.start, config.end);
+    const n = dates.length;
+    const weights = portfolio.allocations.map((a) => a.weight / 100);
+    const prepared = portfolio.allocations.map((a) => assets.get(a.ticker));
+    // State: market value per holding, plus uninvested dividend cash.
+    const holdings = weights.map((w) => config.initialAmount * w);
+    let cash = 0;
+    const values = new Array(n);
+    const twrIndex = new Array(n);
+    const flows = new Array(n).fill(0);
+    const dividendIncome = new Array(n).fill(0);
+    const incomeByHolding = new Array(holdings.length).fill(0);
+    values[0] = config.initialAmount;
+    twrIndex[0] = 1;
+    let totalContributions = 0;
+    for (let t = 1; t < n; t++) {
+        const prevValue = holdings.reduce((s, h) => s + h, cash);
+        // 1. Start-of-day external flow (contribution/withdrawal at prior close values).
+        let flow = 0;
+        if (config.monthlyContribution !== 0 && isNewMonth(dates[t - 1], dates[t])) {
+            flow = config.monthlyContribution;
+            for (let i = 0; i < holdings.length; i++)
+                holdings[i] += flow * weights[i];
+            totalContributions += flow;
+            flows[t] = flow;
+        }
+        // 2. Start-of-day rebalance to target weights (holdings only; dividend cash stays cash).
+        if (config.rebalance !== 'none' &&
+            isPeriodStart(dates[t - 1], dates[t], config.rebalance)) {
+            const invested = holdings.reduce((s, h) => s + h, 0);
+            for (let i = 0; i < holdings.length; i++)
+                holdings[i] = invested * weights[i];
+        }
+        // 3. Apply the day's returns.
+        for (let i = 0; i < holdings.length; i++) {
+            const asset = prepared[i];
+            const income = holdings[i] * asset.divYield[t];
+            dividendIncome[t] += income;
+            incomeByHolding[i] += income;
+            if (config.reinvestDividends) {
+                holdings[i] *= asset.totalReturn[t];
+            }
+            else {
+                cash += income;
+                holdings[i] *= asset.priceReturn[t];
+            }
+        }
+        const value = holdings.reduce((s, h) => s + h, cash);
+        values[t] = value;
+        // Time-weighted return: the flow entered at prior-close values, so the
+        // day's growth acted on (prevValue + flow) — divide it out.
+        twrIndex[t] = twrIndex[t - 1] * (value / (prevValue + flow));
+    }
+    const metrics = computeMetrics(dates, twrIndex, values, flows, config.riskFreeRate ?? 0, config.rfByMonth);
+    const finalValue = values[n - 1];
+    const holdingBreakdowns = portfolio.allocations.map((a, i) => ({
+        ticker: a.ticker,
+        targetWeight: a.weight,
+        endValue: holdings[i],
+        endWeight: finalValue > 0 ? (holdings[i] / finalValue) * 100 : 0,
+        assetTotalReturn: prepared[i].totalReturn.reduce((p, r) => p * r, 1) - 1,
+        income: incomeByHolding[i],
+    }));
+    return {
+        portfolio,
+        dates,
+        values,
+        twrIndex,
+        flows,
+        dividendIncome,
+        endingCash: cash,
+        totalContributions,
+        holdings: holdingBreakdowns,
+        metrics,
+    };
+}
+//# sourceMappingURL=backtest.js.map

package/dist/engine/backtest.js.map

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

package/dist/engine/frontier.d.ts

@@ -0,0 +1,25 @@
+import type { BacktestConfig, TickerSeries } from './types.js';
+/**
+ * A point on the two-asset efficient frontier: the risk (annualized
+ * volatility) and reward (CAGR) of a specific A/B weight mix, plus its
+ * Sharpe ratio, all computed by the real backtest engine over the shared
+ * window — no mean/covariance shortcuts, so it matches every other number
+ * the tool reports.
+ */
+export interface FrontierPoint {
+    weightA: number;
+    volatility: number;
+    cagr: number;
+    sharpe: number;
+}
+/**
+ * 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 declare function twoAssetFrontier(a: TickerSeries, b: TickerSeries, config: BacktestConfig, steps?: number): FrontierPoint[];
+/** Index of the minimum-variance point. */
+export declare function minVarianceIndex(points: FrontierPoint[]): number;
+/** Index of the maximum-Sharpe (tangency) point. */
+export declare function maxSharpeIndex(points: FrontierPoint[]): number;
+//# sourceMappingURL=frontier.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"frontier.d.ts","sourceRoot":"","sources":["../../src/engine/frontier.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAG9D;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,CAAC,EAAE,YAAY,EACf,CAAC,EAAE,YAAY,EACf,MAAM,EAAE,cAAc,EACtB,KAAK,SAAK,GACT,aAAa,EAAE,CAgBjB;AAED,2CAA2C;AAC3C,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,CAIhE;AAED,oDAAoD;AACpD,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,CAI9D"}