garch 1.0.3 → 1.1.0

package/README.md

@@ -3,8 +3,9 @@
 </p>
 
 <p align="center">
-  <strong>Missing GARCH/EGARCH forecast for NodeJS</strong><br>
-  GARCH and EGARCH volatility models for TypeScript. Zero dependencies.
+  <strong>Missing volatility forecast for NodeJS</strong><br>
+  Realized GARCH, Realized EGARCH, Realized GJR-GARCH, HAR-RV and NoVaS<br>
+  models for TypeScript. Zero dependencies.
 </p>
 
 ## Installation
@@ -17,7 +18,7 @@ npm install garch
 
 ### `predict(candles, interval, currentPrice?)`
 
-Forecast expected price range for the next candle (t+1). Auto-selects GARCH or EGARCH based on leverage effect. Returns a +-1 sigma price corridor.
+Forecast expected price range for the next candle (t+1). Auto-selects the best model (GARCH, EGARCH, GJR-GARCH, HAR-RV or NoVaS) by QLIKE forecast-error comparison. Returns a +-1 sigma price corridor.
 
 ```typescript
 import { predict } from 'garch';
@@ -57,7 +58,7 @@ interface PredictionResult {
   move: number;                   // +/- price move = currentPrice * sigma
   upperPrice: number;             // currentPrice + move
   lowerPrice: number;             // currentPrice - move
-  modelType: 'garch' | 'egarch'; // Auto-selected model
+  modelType: 'garch' | 'egarch' | 'gjr-garch' | 'har-rv' | 'novas'; // Auto-selected model
   reliable: boolean;              // Quality flag (convergence + persistence + Ljung-Box)
 }
 ```
@@ -121,18 +122,20 @@ backtest(candles, '4h', 50); // true  -- hit rate >= 50% (custom)
 
 ## Supported Intervals
 
-| Interval | Min Candles | Periods/Year | Coverage |
-|----------|-------------|--------------|----------|
-| `1m` | 500 | 525,600 | ~8-16 hours |
-| `3m` | 500 | 175,200 | ~25 hours |
-| `5m` | 500 | 105,120 | ~1.7 days |
-| `15m` | 300 | 35,040 | ~3 days |
-| `30m` | 200 | 17,520 | ~4 days |
-| `1h` | 200 | 8,760 | ~8 days |
-| `2h` | 200 | 4,380 | ~17 days |
-| `4h` | 200 | 2,190 | ~33 days |
-| `6h` | 150 | 1,460 | ~37 days |
-| `8h` | 150 | 1,095 | ~50 days |
+| Interval | Min Candles | Recommended | Periods/Year | Coverage |
+|----------|-------------|-------------|--------------|----------|
+| `1m` | 500 | 1,500 | 525,600 | ~8-16 hours |
+| `3m` | 500 | 1,500 | 175,200 | ~25 hours |
+| `5m` | 500 | 1,500 | 105,120 | ~1.7 days |
+| `15m` | 300 | 1,000 | 35,040 | ~3 days |
+| `30m` | 200 | 1,000 | 17,520 | ~4 days |
+| `1h` | 200 | 500 | 8,760 | ~8 days |
+| `2h` | 200 | 500 | 4,380 | ~17 days |
+| `4h` | 200 | 500 | 2,190 | ~33 days |
+| `6h` | 150 | 300 | 1,460 | ~37 days |
+| `8h` | 150 | 300 | 1,095 | ~50 days |
+
+For intervals below 1h, per-candle Parkinson RV is noisier — more data helps OLS and QLIKE model selection. A `console.warn` is emitted when candle count is below the recommended value. Always check `reliable: true` in the output.
 
 ## Timeframes
 
@@ -157,7 +160,16 @@ Lower timeframes contain more microstructure noise — use larger datasets to co
 
 ### GARCH(1,1)
 
-Conditional variance model (Bollerslev, 1986):
+Conditional variance model (Bollerslev, 1986). Input type determines the innovation term automatically:
+
+**Candle[] input** — Realized GARCH (Hansen & Huang, 2016). Uses Parkinson (1980) per-candle realized variance proxy (~5× more efficient than squared returns):
+
+```
+sigma_t^2 = omega + alpha * RV_{t-1} + beta * sigma_{t-1}^2
+RV_t = (1 / (4·ln2)) · ln(H/L)^2     (Parkinson estimator)
+```
+
+**number[] input** — Classical GARCH. Uses squared returns:
 
 ```
 sigma_t^2 = omega + alpha * epsilon_{t-1}^2 + beta * sigma_{t-1}^2
@@ -169,13 +181,16 @@ sigma_t^2 = omega + alpha * epsilon_{t-1}^2 + beta * sigma_{t-1}^2
 - Stationarity constraint: **alpha + beta < 1**
 - Unconditional variance: **E[sigma^2] = omega / (1 - alpha - beta)**
 
-Parameter estimation via **Gaussian MLE** (maximum likelihood):
+Parameter estimation via **Student-t MLE** (maximum likelihood) with multi-start Nelder-Mead optimization. The Student-t distribution captures fat tails observed in financial returns:
 
 ```
-LL = -0.5 * sum[ ln(sigma_t^2) + epsilon_t^2 / sigma_t^2 ]
+LL = n·[lnΓ((df+1)/2) - lnΓ(df/2) - 0.5·ln(π·(df-2))]
+     - 0.5 · sum[ ln(sigma_t^2) + (df+1)·ln(1 + r_t^2 / ((df-2)·sigma_t^2)) ]
 ```
 
-Multi-step forecast converges to unconditional variance:
+- **df** > 2 — degrees of freedom (estimated jointly with omega, alpha, beta via multi-start Nelder-Mead)
+
+Multi-step forecast converges to unconditional variance (E[RV] = sigma^2, so recursion is identical):
 
 ```
 sigma_{t+h}^2 = omega + (alpha + beta) * sigma_{t+h-1}^2
@@ -183,26 +198,191 @@ sigma_{t+h}^2 = omega + (alpha + beta) * sigma_{t+h-1}^2
 
 ### EGARCH(1,1)
 
-Exponential GARCH (Nelson, 1991). Models log-variance, capturing asymmetric volatility:
+Exponential GARCH (Nelson, 1991). Models log-variance, capturing asymmetric volatility. Input type determines the magnitude term automatically:
+
+**Candle[] input** — Realized EGARCH. Magnitude uses Parkinson RV, leverage keeps directional return:
 
 ```
-ln(sigma_t^2) = omega + alpha * (|z_{t-1}| - sqrt(2/pi)) + gamma * z_{t-1} + beta * ln(sigma_{t-1}^2)
+ln(sigma_t^2) = omega + alpha * (sqrt(RV_{t-1} / sigma_{t-1}^2) - E[|Z|]) + gamma * z_{t-1} + beta * ln(sigma_{t-1}^2)
 ```
 
-Where **z_t = epsilon_t / sigma_t** is the standardized residual, **sqrt(2/pi) ~ 0.7979**.
+**number[] input** — Classical EGARCH. Magnitude uses |z|:
+
+```
+ln(sigma_t^2) = omega + alpha * (|z_{t-1}| - E[|Z|]) + gamma * z_{t-1} + beta * ln(sigma_{t-1}^2)
+```
+
+Where **z_t = epsilon_t / sigma_t** is the standardized residual and **E[|Z|]** is the expected absolute value of a standardized Student-t(df) variable:
+
+```
+E[|Z|] = sqrt((df-2)/pi) · Γ((df-1)/2) / Γ(df/2)
+```
 
+- **sqrt(RV/sigma^2)** is a more efficient estimate of |z| from OHLC data
 - **gamma** < 0 — leverage effect (negative returns increase vol more than positive)
 - No positivity constraints needed (log-variance is always real)
 - Stationarity: **|beta| < 1**
 - Unconditional variance: **E[sigma^2] ~ exp(omega / (1 - beta))**
+- **df** > 2 — degrees of freedom (estimated jointly via multi-start Nelder-Mead)
+
+### GJR-GARCH(1,1)
+
+Threshold GARCH (Glosten, Jagannathan & Runkle, 1993). Captures leverage effect in variance space (unlike EGARCH which uses log-variance). Input type determines the innovation term automatically:
+
+**Candle[] input** — Realized GJR-GARCH. Uses Parkinson RV as innovation, return sign as leverage indicator:
+
+```
+sigma_t^2 = omega + alpha * RV_{t-1} + gamma * RV_{t-1} * I(r_{t-1}<0) + beta * sigma_{t-1}^2
+```
+
+**number[] input** — Classical GJR-GARCH. Uses squared returns:
+
+```
+sigma_t^2 = omega + alpha * epsilon_{t-1}^2 + gamma * epsilon_{t-1}^2 * I(r_{t-1}<0) + beta * sigma_{t-1}^2
+```
+
+Where **I(r<0) = 1** when return is negative, **0** otherwise.
+
+- **gamma** >= 0 — leverage coefficient (bad news amplifies variance by extra gamma)
+- **omega** > 0, **alpha** >= 0, **beta** >= 0
+- Stationarity: **alpha + gamma/2 + beta < 1** (half of innovations are negative on average)
+- Unconditional variance: **E[sigma^2] = omega / (1 - alpha - gamma/2 - beta)**
+- **df** > 2 — degrees of freedom (estimated jointly via multi-start Nelder-Mead)
+
+Multi-step forecast uses effective persistence = alpha + gamma/2 + beta:
+
+```
+sigma_{t+h}^2 = omega + (alpha + gamma/2 + beta) * sigma_{t+h-1}^2
+```
+
+### HAR-RV
+
+Heterogeneous Autoregressive model of Realized Variance (Corsi, 2009). Captures multi-scale volatility clustering via three overlapping horizons:
+
+```
+RV_{t+1} = beta_0 + beta_1 * RV_short + beta_2 * RV_medium + beta_3 * RV_long + epsilon
+```
+
+Where **RV_t** is the per-candle realized variance proxy:
+
+- **OHLC input** — Parkinson (1980): **RV_t = (1 / (4·ln2)) · ln(H/L)^2** (~5× more efficient than close-to-close)
+- **Prices-only input** — squared return: **RV_t = r_t^2** (fallback when no OHLC available)
+
+Classic HAR-RV uses sum of intraday squared returns, but that requires tick/minute data. Parkinson uses the high-low range of each candle as a variance proxy — no intraday data needed.
+
+- **RV_short** = mean(RV_t) — last 1 period (default)
+- **RV_medium** = mean(RV_{t-4} ... RV_t) — last 5 periods
+- **RV_long** = mean(RV_{t-21} ... RV_t) — last 22 periods
+
+Parameter estimation via **OLS** (closed-form, always converges):
+
+```
+beta = (X'X)^{-1} X'y
+```
+
+After OLS, **df** (degrees of freedom) is profiled via grid search over the Student-t log-likelihood with the OLS-fitted variance series.
+
+- Persistence: **beta_1 + beta_2 + beta_3 < 1** for stationarity
+- Unconditional variance: **E[RV] = beta_0 / (1 - beta_1 - beta_2 - beta_3)**
+- **R^2** measures explained variance in the regression
+
+Multi-step forecast via iterative substitution: each predicted RV feeds back into the rolling components for subsequent steps.
+
+### NoVaS
+
+Normalizing and Variance-Stabilizing transformation (Politis, 2003). Model-free approach using the ARCH frame. Input type determines the innovation term automatically:
+
+**Candle[] input** — Realized NoVaS. Uses Parkinson (1980) per-candle RV as innovation (~5× more efficient than squared returns):
+
+```
+sigma_t^2 = a_0 + a_1 * RV_{t-1} + a_2 * RV_{t-2} + ... + a_p * RV_{t-p}
+RV_t = (1 / (4·ln2)) · ln(H/L)^2     (Parkinson estimator)
+W_t  = X_t / sigma_t
+```
+
+**number[] input** — Classical NoVaS. Uses squared returns:
+
+```
+sigma_t^2 = a_0 + a_1 * X_{t-1}^2 + a_2 * X_{t-2}^2 + ... + a_p * X_{t-p}^2
+W_t       = X_t / sigma_t
+```
+
+Parameters **a_0, ..., a_p** are chosen to minimize the non-normality of the transformed series {W_t}:
+
+```
+D^2 = S^2 + (K - 3)^2
+```
+
+where **S** = skewness and **K** = kurtosis of {W_t}. For perfect normality D^2 = 0.
+
+- **a_0** > 0 — baseline variance
+- **a_j** >= 0 — weight on j-th lagged innovation (RV or squared return)
+- Stationarity: **sum(a_1 ... a_p) < 1**
+- Unconditional variance: **E[sigma^2] = a_0 / (1 - sum(a_1 ... a_p))**
+- Default lags: **p = 10** (configurable)
+- Parkinson RV is less noisy than r², so Candle[] typically achieves lower D^2
+
+Key difference from GARCH: parameters are found via **normality criterion** (D^2 minimization), not MLE. No distributional assumptions on the return series — truly model-free. Uses multi-start Nelder-Mead for optimization (6 restarts to escape local minima in the 11-dimensional D^2 landscape). After fitting, **df** is profiled via grid search over the Student-t log-likelihood (same as HAR-RV).
+
+After D^2 optimization, weights are **rescaled via OLS** on the realized variance series to minimize forecast error. This keeps NoVaS model-free (D^2 selects lag structure) while making it QLIKE-competitive with HAR-RV.
+
+**Two-stage calibration:**
+
+- **Stage 1** — D^2 minimization: discovers lag structure via normality criterion (model-free). Produces `weights` (a_0, ..., a_p).
+- **Stage 2** — OLS rescaling: regresses RV_{t+1} on sigma_t^2(D^2) to produce forecast-optimal weights. Produces `forecastWeights` = [beta_0, beta_1].
+
+```
+forecast_sigma_t^2 = beta_0 + beta_1 * sigma_t^2(D^2)
+```
+
+D^2 acts as a data-driven smoother over RV lags — more flexible than HAR-RV's fixed rolling means (1, 5, 22). OLS rescaling adjusts for bias with only 2 parameters, keeping the model robust on small samples with noisy per-candle RV.
+
+Multi-step forecast: replace future innovations with sigma^2 (since E[RV] = E[X^2] = sigma^2), then rescale:
+
+```
+d2_{t+h} = a_0 + sum_j a_j * E[innovation_{t+h-j}]
+sigma_{t+h}^2 = beta_0 + beta_1 * d2_{t+h}
+```
 
 ### Model Auto-Selection
 
-`predict` and `predictRange` automatically choose between GARCH and EGARCH:
+`predict` and `predictRange` fit all five models and pick the winner by **QLIKE** (Patton, 2011) — a neutral forecast-error metric that judges how well each model's variance series predicts realized variance:
+
+```
+QLIKE = (1/n) · sum[ RV_t / sigma_t^2 - ln(RV_t / sigma_t^2) - 1 ]
+```
+
+Lower QLIKE = better forecast. Unlike AIC (which favors MLE-calibrated models), QLIKE is neutral to calibration method — OLS, D^2-minimization, and MLE all compete on equal footing.
+
+1. **GARCH-family pipeline**: fit GARCH, EGARCH, GJR-GARCH — pick best by AIC (fair since all three optimize Student-t LL)
+2. **HAR-RV pipeline**: fit HAR-RV via OLS. Skip if persistence >= 1 or R^2 < 0
+3. **NoVaS pipeline**: fit NoVaS via D^2 minimization + OLS rescaling. Skip if persistence >= 1
+4. Compute Parkinson RV from candles. Score each pipeline's variance series by QLIKE. Lowest QLIKE wins
+
+```
+fitModel(candles)
+  |-- fitGarchFamily() --> min_AIC(GARCH, EGARCH, GJR-GARCH) --> QLIKE_1
+  |-- fitHarRv()       --> HAR-RV (OLS)                       --> QLIKE_2
+  |-- fitNoVaS()       --> NoVaS (D²)                         --> QLIKE_3
+  |-- rv = perCandleParkinson(candles)
+  \-- return min(QLIKE_1, QLIKE_2, QLIKE_3)
+```
+
+When given `Candle[]`, all five OHLC-aware models (GARCH, EGARCH, GJR-GARCH, HAR-RV, NoVaS) use Parkinson per-candle RV instead of squared returns, extracting ~5× more information from the same data.
+
+### When Each Model Wins
+
+The library fits all five models on every call and picks the best by QLIKE. Each model uses its own calibration method (MLE, OLS, or D^2) but they all compete on the same forecast-error metric. Here's what patterns in data favor each:
+
+- **GARCH** — Volatility spikes after any big move (up or down equally), then gradually fades back to normal. No difference between bullish and bearish shocks. Classic symmetric mean-reverting vol clustering.
+
+- **EGARCH** — Drops hit harder than pumps. A -5% candle causes way more volatility than a +5% candle. Strong "fear > greed" asymmetry. Works through a log-variance model so the asymmetry coefficient `gamma * z` directly amplifies negative shocks. Typical for stocks and BTC during risk-off periods.
+
+- **GJR-GARCH** — Same idea as EGARCH (red candles increase vol more than green ones) but the effect is milder and simpler: when the return is negative, a bonus term `gamma * epsilon^2` is added to variance. When positive — nothing extra. A binary switch rather than a continuous asymmetry. Common in altcoins and less panic-prone markets.
 
-1. Compute volatility of negative returns vs. positive returns
-2. If ratio > 1.2 — use EGARCH (significant leverage effect detected)
-3. Otherwise — use simpler GARCH
+- **HAR-RV** — Volatility has memory at multiple horizons. The model takes a single timeframe of candles and internally builds three scales: last candle's RV (short, lag 1), rolling average over 5 candles (medium), and rolling average over 22 candles (long). These three components are combined via OLS regression. Works well when different types of participants (scalpers, swing traders, institutions) all influence the same market at different speeds. If your asset has visible "rhythm" across day/week/month — HAR-RV will likely beat GARCH family (sideways, daily patterns).
+
+- **NoVaS** — Volatility drifts or cycles without clear shock-and-decay patterns. Slow trend changes, regime shifts, compression/expansion phases, or "breathing" patterns that don't fit any parametric formula. Model-free: finds weights `a_0...a_p` that make the normalized series as close to Gaussian as possible (minimizes D^2 = skewness^2 + (kurtosis - 3)^2). No assumptions about the distribution shape.
 
 ### Variance Estimators
 
@@ -222,6 +402,24 @@ sigma^2_GK = (1/n) * sum[ 0.5 * ln(H/L)^2 - (2*ln2 - 1) * ln(C/O)^2 ]
 
 ~5x more efficient than close-to-close variance.
 
+### Student-t Log-Likelihood
+
+All five models use a **Student-t** distribution for log-likelihood computation. Financial return series exhibit fat tails (excess kurtosis), and the Student-t captures this with an additional **degrees of freedom (df)** parameter:
+
+- **df ~ 3–10**: Heavy tails (common in crypto/equity returns)
+- **df ~ 20–50**: Mild excess kurtosis
+- **df → ∞**: Thin tails
+
+For GARCH, EGARCH, and GJR-GARCH, **df** is optimized jointly with the other parameters via Nelder-Mead. For HAR-RV and NoVaS, **df** is profiled via a two-pass grid search (coarse 2.5–50, then fine ±1 around the best) after the main optimization.
+
+Helper functions exported from the library:
+
+- `logGamma(x)` — Lanczos approximation (g=7, n=9), ~15-digit accuracy
+- `studentTNegLL(returns, varianceSeries, df)` — Full negative log-likelihood
+- `expectedAbsStudentT(df)` — E[|Z|] for standardized t(df), used in EGARCH centering
+- `profileStudentTDf(returns, varianceSeries)` — Grid search for optimal df
+- `qlike(varianceSeries, rv)` — QLIKE loss (Patton, 2011) for volatility forecast evaluation
+
 ### Reliability Check
 
 The `reliable` flag in `PredictionResult` is `true` when all three conditions hold:
@@ -232,25 +430,68 @@ The `reliable` flag in `PredictionResult` is `true` when all three conditions ho
 
 ### Optimization
 
-Parameters are estimated via **Nelder-Mead** simplex method (derivative-free). Default: 1000 iterations, tolerance 1e-8. Model comparison uses **AIC** (2k - 2LL) and **BIC** (k*ln(n) - 2LL).
+GARCH/EGARCH/GJR-GARCH parameters (including df) are estimated via **multi-start Nelder-Mead** simplex method (derivative-free). Each model runs Nelder-Mead from multiple deterministic starting points (golden-ratio quasi-random perturbation) and keeps the best result — this escapes local minima that single-start NM would get stuck in, especially important for higher-dimensional problems like NoVaS (11 parameters).
+
+| Model | Parameters | Restarts | Total NM runs |
+|-------|-----------|----------|---------------|
+| GARCH | 4 (omega, alpha, beta, df) | 3 | 4 |
+| EGARCH | 5 (omega, alpha, gamma, beta, df) | 4 | 5 |
+| GJR-GARCH | 5 (omega, alpha, gamma, beta, df) | 4 | 5 |
+| NoVaS | p+1 (a_0...a_p, default p=10) | 6 | 7 |
+| HAR-RV | 4 (beta_0...beta_3) | — | OLS (closed-form) |
+
+Default per run: 1000 iterations (2000 for NoVaS D^2), tolerance 1e-8. Initial simplex uses 20% perturbation from x0 for broader exploration. HAR-RV uses **OLS** (exact solution in one step) + df profiling.
+
+Within the GARCH family, model comparison uses **AIC** (2k - 2LL) — fair since all three optimize the same Student-t LL objective. Across model families (GARCH vs HAR-RV vs NoVaS), comparison uses **QLIKE** (Patton, 2011):
+
+```
+QLIKE = (1/n) · sum[ RV_t / sigma_t^2 - ln(RV_t / sigma_t^2) - 1 ]
+```
+
+where RV_t is Parkinson per-candle realized variance and sigma_t^2 is the model's fitted conditional variance. QLIKE is the standard loss function for volatility forecast evaluation — it is neutral to calibration method (MLE, OLS, D^2 all compete fairly).
 
 ## Tests
 
-**400 tests** across **17 test files**. All passing.
+**923 tests** across **22 test files**. All passing.
 
 | Category | Files | Tests | What's covered |
 |----------|-------|-------|----------------|
-| Mathematical formulas | `math.test.ts` | 45 | GARCH/EGARCH variance recursion, log-likelihood, forecast formulas, AIC/BIC, Yang-Zhang, Garman-Klass, Ljung-Box, chi-squared |
+| Mathematical formulas | `math.test.ts` | 45 | GARCH/EGARCH variance recursion, log-likelihood, forecast formulas, AIC/BIC, QLIKE, Yang-Zhang, Garman-Klass, Ljung-Box, chi-squared |
+| Math coverage | `math-coverage.test.ts` | 79 | Parkinson formula verification, rv↔returns alignment, H=L fallback, Parkinson-based forecast, candle validation, reliable flag cascade, backtest validity, numerical precision, cross-model consistency, Realized GARCH/EGARCH/GJR-GARCH Candle[] vs number[], perCandleParkinson shared function |
 | Full pipeline coverage | `plan-coverage.test.ts` | 73 | End-to-end: fit, forecast, predict, predictRange, backtest, model selection |
 | GARCH unit | `garch.test.ts` | 10 | Parameter estimation, variance series, forecast convergence, candle vs price input |
-| EGARCH unit | `egarch.test.ts` | 11 | Leverage detection, asymmetric volatility, model comparison via AIC |
-| Optimizer | `optimizer.test.ts`, `optimizer-shrink.test.ts` | 16 | Nelder-Mead on Rosenbrock/quadratic/parabolic, convergence, shrinking |
-| Statistical properties | `properties.test.ts` | 13 | Parameter recovery from synthetic data, local LL maximum, unconditional variance |
-| Regression | `regression.test.ts` | 9 | Parameter recovery, deterministic outputs |
-| Stability | `stability.test.ts` | 10 | Long-term forecast behavior, variance convergence |
+| EGARCH unit | `egarch.test.ts` | 11 | Leverage detection, asymmetric volatility, model comparison |
+| GJR-GARCH unit | `gjr-garch.test.ts` | 86 | Variance recursion (r² and Parkinson), indicator function I(r<0), forecast formula (one-step + multi-step), constraint barriers, computed fields, AIC/BIC numParams=5, estimation properties (perturbation, determinism), numerical stability, degenerate params, Realized path (Candle[] vs number[], flat candles, bad OHLC), options forwarding, immutability, instance isolation, cross-model consistency, scale invariance, property-based fuzz, predict/predictRange/backtest integration |
+| HAR-RV unit | `har.test.ts` | 138 | OLS regression, R^2, Parkinson RV proxy, forecast convergence, multi-step iterative substitution, rolling RV components, edge cases, fuzz, integration with predict, OLS orthogonality, TSS=RSS+ESS, normal equations, regression snapshots, mutation safety |
+| NoVaS unit | `novas.test.ts` | 109 | D^2 minimization, normality improvement, variance series, forecast convergence, edge cases, fuzz, integration with predict, determinism, scale invariance |
+| Optimizer | `optimizer.test.ts`, `optimizer-shrink.test.ts` | 20 | Nelder-Mead on Rosenbrock/quadratic/parabolic, convergence, shrinking, multi-start (Rastrigin escape, high-dimensional, equivalence) |
+| Statistical properties | `properties.test.ts` | 15 | Parameter recovery from synthetic data, local LL maximum, unconditional variance, GJR-GARCH forecast convergence and model selection |
+| Regression | `regression.test.ts` | 11 | Parameter recovery, deterministic outputs, cross-model consistency for GARCH/EGARCH/GJR-GARCH |
+| Stability | `stability.test.ts` | 12 | Long-term forecast behavior, variance convergence, GJR-GARCH near-constant and outlier handling |
 | Robustness | `robustness.test.ts` | 53 | Extreme moves, stress scenarios |
-| Edge cases | `edge-cases.test.ts`, `coverage-gaps*.test.ts` | 148 | Insufficient data, near-unit-root, zero returns, constant prices, negative prices, overflow/underflow, trending data, 10K+ data points |
-| Miscellaneous | `misc.test.ts` | 12 | Integration scenarios, different intervals |
+| Realized models | `realized-garch.test.ts` | 83 | Candle[] vs number[] for GARCH/EGARCH/GJR-GARCH/NoVaS, Parkinson RV edge cases, flat candles, extreme H/L, scale invariance, all-identical OHLC, minimum-length boundary, D² comparison, predict fallback, **ground-truth volatility recovery** (see below) |
+| Edge cases | `edge-cases.test.ts`, `coverage-gaps*.test.ts` | 165 | Insufficient data, near-unit-root, zero returns, constant prices, negative prices, overflow/underflow, trending data, 10K+ data points, GJR-GARCH immutability and instance isolation, EGARCH df≤2 fallback, logGamma/expectedAbsStudentT/qlike edge cases |
+| Miscellaneous | `misc.test.ts` | 13 | Integration scenarios, different intervals, immutability |
+
+### Ground-Truth Volatility Test
+
+The test suite includes an end-to-end integration test that verifies `predict` recovers known volatility from synthetic data. This is the strongest correctness guarantee — it proves the entire pipeline (data generation, model fitting, auto-selection, forecasting) produces numerically accurate results.
+
+**How it works:**
+
+1. Generate 500 OHLC candles with **known constant per-period volatility** sigma_true (returns are iid N(0, sigma_true^2), high/low simulated via Brownian bridge noise)
+2. Run `predict()` on these candles — auto-selects the best model, fits parameters, produces a 1-step forecast
+3. Verify predicted sigma matches sigma_true
+
+**What is verified:**
+
+| Test | Assertion |
+|------|-----------|
+| sigma_true = 0.2%, 1%, 3% | Relative error < 50% for each |
+| Monotonicity | sigma_true_1 < sigma_true_2 < sigma_true_3 implies predicted_1 < predicted_2 < predicted_3 |
+| Median accuracy (20 seeds) | Median relative error < 30% across 20 independent runs (sigma_true = 1%) |
+| +-1 sigma hit rate (Monte Carlo) | Out-of-sample +-1 sigma corridor captures 45–90% of actual next moves across 30 trials (theoretical: 68.27%) |
+| Proportionality | 2x sigma_true produces ~2x predicted sigma (ratio between 1.2x and 3.5x) |
 
 ```bash
 npm test        # run all tests