@retiregolden/engine 0.1.0

package/dist/montecarlo/marketModels.d.ts

@@ -0,0 +1,248 @@
+/**
+ * Pluggable stochastic market models (roadmap V4, feature catalog §11).
+ *
+ * Each model turns an injected RNG into one path of per-year market
+ * conditions for the deterministic ledger: an additive return shock (single
+ * market factor applied to non-cash investable accounts), a realized
+ * inflation rate, and — for plans with allocated accounts — per-class
+ * correlated shocks sharing the same allocation schema as the deterministic
+ * ledger. Shocks are centered so the expected return stays the plan's own
+ * assumption; the models supply dispersion, skew, and the return/inflation
+ * co-movement.
+ *
+ * Configs are plain JSON so they can cross the Web Worker boundary.
+ *
+ * Extended in the stochastic-market-model-library plan (Track 2) to 15+
+ * models. All new models are mean-preserving by default (path avg shock ~0),
+ * respect RNG draw ordering (new draws after core for classShocks parity),
+ * and default lognormal/historical paths are byte-identical.
+ */
+import { type AssetClassId, type Plan } from '../model/plan.js';
+import type { MarketSeries } from '../projection/types.js';
+import type { Rng } from './rng.js';
+export interface MarketModel {
+    /** One simulation path of per-year market conditions. */
+    generatePath(rng: Rng, yearCount: number): MarketSeries;
+}
+/**
+ * Per-class shock generation for plans with allocated accounts
+ * (asset-allocation-and-return-model-v2, step 6). Volatilities come from the
+ * resolved Assumptions-level class parameters; the correlation matrix defaults
+ * to the documented long-horizon historical one. Enabling this consumes extra
+ * RNG draws per year, so it is only switched on when the plan actually has an
+ * allocated account — single-return plans keep their exact current paths.
+ */
+export interface ClassShockConfig {
+    /** Annual volatility per class, percentage points, ASSET_CLASS_IDS keys. */
+    volatilityPctByClass: Record<AssetClassId, number>;
+    /** Correlation matrix over ASSET_CLASS_IDS order; default: the documented long-horizon matrix. */
+    correlations?: number[][];
+}
+export interface LognormalModelConfig {
+    type: 'lognormal';
+    /** Annual volatility of the portfolio return, percentage points (default 12). */
+    returnVolPct?: number;
+    /** Mean inflation, percent (default: the plan's assumption — pass it explicitly). */
+    inflationMeanPct: number;
+    /** Annual volatility of inflation, percentage points (default 1.5). */
+    inflationVolPct?: number;
+    /** Correlation between the return shock and inflation (default −0.2). */
+    correlation?: number;
+    /** Emit per-class correlated shocks for allocated accounts; omit for single-factor only. */
+    classShocks?: ClassShockConfig;
+}
+export interface HistoricalModelConfig {
+    type: 'historical';
+    /**
+     * iid: each year sampled independently; block: contiguous blocks keep
+     * multi-year momentum/mean-reversion; sequence: full historical replay
+     * from a random start. Blocks and sequences wrap around.
+     */
+    mode: 'iid' | 'block' | 'sequence';
+    /** Stocks share of the sampled portfolio (default 60 ⇒ 60/40). */
+    equityWeightPct?: number;
+    /** Block length in years for mode 'block' (default 5). */
+    blockLengthYears?: number;
+    /**
+     * Emit per-class shocks keyed off the same sampled historical years: stock
+     * classes replay the S&P series, bonds the Treasury series (each centered on
+     * its own mean), cash stays unshocked. No extra RNG draws, so the sampled
+     * year sequence — and every unallocated account — is unchanged.
+     */
+    classShocks?: boolean;
+}
+export interface StudentTModelConfig {
+    type: 'student-t';
+    /** Degrees of freedom for t (lower = fatter tails; default 5). */
+    df?: number;
+    /** Annual volatility of the portfolio return, percentage points (default 12). */
+    returnVolPct?: number;
+    inflationMeanPct: number;
+    inflationVolPct?: number;
+    correlation?: number;
+    classShocks?: ClassShockConfig;
+}
+export interface RegimeSwitchModelConfig {
+    type: 'regime-switch';
+    /** Bull regime mean *deviation* (real, %; default +4 so symmetric with bear). */
+    bullMeanPct?: number;
+    /** Bear regime mean *deviation* (real, %; default -4). */
+    bearMeanPct?: number;
+    /** Bull vol (default 10). */
+    bullVolPct?: number;
+    /** Bear vol (default 20). */
+    bearVolPct?: number;
+    /** Probability of switching regime each year (default 0.05). */
+    switchProb?: number;
+    inflationMeanPct: number;
+    inflationVolPct?: number;
+    classShocks?: ClassShockConfig;
+}
+export interface CapeConditionedModelConfig {
+    type: 'cape-conditioned';
+    /** Starting (or current) CAPE; high values reduce forward mean (default 25). */
+    startingCape?: number;
+    /** Sensitivity: %pt reduction in mean per CAPE point above 20 (default 0.15). */
+    capeSensitivity?: number;
+    returnVolPct?: number;
+    inflationMeanPct: number;
+    inflationVolPct?: number;
+    correlation?: number;
+    classShocks?: ClassShockConfig;
+}
+export interface StationaryBootstrapModelConfig {
+    type: 'stationary';
+    equityWeightPct?: number;
+    /** Expected block length (geometric; default 5). */
+    meanBlockLength?: number;
+    classShocks?: boolean;
+}
+export interface EmpiricalModelConfig {
+    type: 'empirical';
+    /** Raw historical (no mean centering) vs centered. Non-centered is "honest" historical mean from data. */
+    centered?: boolean;
+    equityWeightPct?: number;
+    classShocks?: boolean;
+}
+export interface GarchModelConfig {
+    type: 'garch';
+    /** GARCH(1,1) omega (base var, scaled). Default tuned for ~12% ann vol. */
+    omega?: number;
+    alpha?: number;
+    beta?: number;
+    returnVolScalePct?: number;
+    inflationMeanPct: number;
+    inflationVolPct?: number;
+    correlation?: number;
+    classShocks?: ClassShockConfig;
+}
+export interface InflationRegimeModelConfig {
+    type: 'inflation-regime';
+    /** Normal vs high-inflation regime. */
+    highInflationMean?: number;
+    highInflationProb?: number;
+    returnVolPct?: number;
+    baseInflationMeanPct: number;
+    correlation?: number;
+    classShocks?: ClassShockConfig;
+}
+export interface ReversedHistoryModelConfig {
+    type: 'reversed-history';
+    /** Window length for reversed replay blocks. */
+    windowLengthYears?: number;
+    equityWeightPct?: number;
+    classShocks?: boolean;
+}
+export interface UserShockModelConfig {
+    type: 'user-shock';
+    /** 1-based year index in the path to apply the shock. */
+    shockYear?: number;
+    /** Additive shock in that year, percent (e.g. -20 for crash year). */
+    shockPct?: number;
+    /** Base model after the shock year (lognormal params). */
+    baseReturnVolPct?: number;
+    inflationMeanPct: number;
+    classShocks?: ClassShockConfig;
+}
+export interface GaussianModelConfig {
+    type: 'gaussian';
+    /** Annual volatility of the portfolio return shock, percentage points (default 12). */
+    returnVolPct?: number;
+    inflationMeanPct: number;
+    inflationVolPct?: number;
+    correlation?: number;
+    classShocks?: ClassShockConfig;
+}
+export interface AR1ModelConfig {
+    type: 'ar1';
+    /** Autoregression coefficient phi (0 < phi < 1 for mean reversion; default 0.2). */
+    phi?: number;
+    returnVolPct?: number;
+    inflationMeanPct: number;
+    inflationVolPct?: number;
+    correlation?: number;
+    classShocks?: ClassShockConfig;
+}
+export type MarketModelConfig = LognormalModelConfig | HistoricalModelConfig | StudentTModelConfig | RegimeSwitchModelConfig | CapeConditionedModelConfig | StationaryBootstrapModelConfig | EmpiricalModelConfig | GarchModelConfig | InflationRegimeModelConfig | ReversedHistoryModelConfig | UserShockModelConfig | GaussianModelConfig | AR1ModelConfig;
+export declare function buildLognormalModelConfigForPlan(plan: Plan, returnVolPct?: number): LognormalModelConfig;
+export declare function createMarketModel(config: MarketModelConfig): MarketModel;
+/**
+ * Lognormal-correlated model: the yearly gross return multiplier is
+ * lognormal with mean 1 (so the shock is mean-preserving around each
+ * account's expected return); inflation is normal and correlated with the
+ * return shock via a Gaussian copula.
+ */
+export declare function createLognormalModel(config: LognormalModelConfig): MarketModel;
+/**
+ * Historical bootstrap over the embedded Shiller/Damodaran annual series.
+ * The sampled blended-portfolio return is centered on its historical mean,
+ * preserving the plan's expected return while replaying historical
+ * dispersion and the realized co-movement of returns and inflation.
+ */
+export declare function createHistoricalModel(config: HistoricalModelConfig): MarketModel;
+/**
+ * Student-t fat-tailed returns (mean-preserving). Uses t-distributed shocks
+ * scaled to target volatility; lower df => fatter tails than Gaussian.
+ * Draws: z_t for return, then inflation copula, then class after.
+ */
+export declare function createStudentTModel(config: StudentTModelConfig): MarketModel;
+/**
+ * Simple two-regime Markov switching (bull/bear) on mean and vol.
+ * State persists with 1-p switch. Regime means (bullMeanPct / bearMeanPct) are *deviations*
+ * from zero so the unconditional expected shock is near zero when bull/bear are symmetric.
+ * Inflation is always centered on the provided mean (no regime bias).
+ */
+export declare function createRegimeSwitchModel(config: RegimeSwitchModelConfig): MarketModel;
+/**
+ * CAPE-conditioned: starting high CAPE lowers the mean return (linear taper).
+ * Uses lognormal base but shifts mu down.
+ */
+export declare function createCapeConditionedModel(config: CapeConditionedModelConfig): MarketModel;
+/** Stationary (Politis-Romano) bootstrap: geometric block lengths. */
+export declare function createStationaryBootstrapModel(config: StationaryBootstrapModelConfig): MarketModel;
+/** Empirical historical: optionally non-centered (raw history mean).
+ * Note: non-centered mode outputs raw historical portfolio returns as the "shock".
+ * Because the projection always does expected + shock, non-centered will add the
+ * historical mean on top of the plan's assumption (potential double-count).
+ * UI defaults to centered for correctness; non-centered kept for advanced use.
+ */
+export declare function createEmpiricalModel(config: EmpiricalModelConfig): MarketModel;
+/** GARCH(1,1) approx for vol clustering. Simple recursion on sigma_t. */
+export declare function createGarchModel(config: GarchModelConfig): MarketModel;
+/** Fat-tailed / regime inflation correlated to returns. */
+export declare function createInflationRegimeModel(config: InflationRegimeModelConfig): MarketModel;
+/** Reversed history blocks chosen stochastically (formalized from suites). */
+export declare function createReversedHistoryModel(config: ReversedHistoryModelConfig): MarketModel;
+/** User-specified deterministic shock in one year, then lognormal-ish. */
+export declare function createUserShockModel(config: UserShockModelConfig): MarketModel;
+/**
+ * Additive multivariate Gaussian (normal) shocks. Distinct from lognormal:
+ * returns can be <-100% in theory (rare), symmetric, no built-in compounding skew.
+ * Mean-preserving (shocks centered at 0).
+ */
+export declare function createGaussianModel(config: GaussianModelConfig): MarketModel;
+/**
+ * AR(1) mean-reverting shocks. Introduces serial correlation (momentum or reversion)
+ * controlled by phi. Distinct dynamics from iid models. Shocks remain mean-zero.
+ */
+export declare function createAR1Model(config: AR1ModelConfig): MarketModel;