garch 1.2.3 → 2.0.0

package/build/index.mjs

@@ -88,9 +88,16 @@ function nelderMead(fn, x0, options = {}) {
             }
         }
     }
+    // Re-sort before returning: on maxIter exit the last iteration may have
+    // placed a better point at the worst-vertex slot without a sort pass.
+    let bestIdx = 0;
+    for (let i = 1; i <= n; i++) {
+        if (values[i] < values[bestIdx])
+            bestIdx = i;
+    }
     return {
-        x: simplex[0],
-        fx: values[0],
+        x: simplex[bestIdx],
+        fx: values[bestIdx],
         iterations,
         converged,
     };
@@ -110,15 +117,27 @@ function shrink(simplex, values, sigma, fn, n) {
  *
  * Perturbation uses golden-ratio quasi-random sequence for uniform
  * coverage of the search space without clustering.
+ *
+ * The restart budget adapts to the problem: after the scheduled restarts,
+ * exploration continues while restarts keep finding improvements, so easy
+ * unimodal fits stop early and rugged landscapes get extra effort. The
+ * schedule is deterministic — same inputs, same result.
  */
 const PHI = (1 + Math.sqrt(5)) / 2; // golden ratio
 function nelderMeadMultiStart(fn, x0, options = {}) {
-    const { maxIter = 1000, tol = 1e-8, restarts = 3 } = options;
+    const { maxIter = 1000, tol = 1e-8, restarts = 3, extraStarts = [] } = options;
     const n = x0.length;
     // Run from original starting point
     let best = nelderMead(fn, x0, { maxIter, tol });
-    // Run from perturbed starting points
-    for (let k = 1; k <= restarts; k++) {
+    for (const start of extraStarts) {
+        const result = nelderMead(fn, start, { maxIter, tol });
+        if (result.fx < best.fx)
+            best = result;
+    }
+    // Scheduled restarts, then keep going while they pay off.
+    // An explicit restarts=0 opts out of multi-start entirely.
+    const maxRestarts = restarts === 0 ? 0 : restarts * 2 + 4;
+    for (let k = 1; k <= maxRestarts; k++) {
         const perturbed = new Array(n);
         for (let i = 0; i < n; i++) {
             // Quasi-random perturbation: golden-ratio sequence mapped to [-0.5, +0.5]
@@ -129,13 +148,95 @@ function nelderMeadMultiStart(fn, x0, options = {}) {
                 : x0[i] * (1 + scale);
         }
         const result = nelderMead(fn, perturbed, { maxIter, tol });
+        const improved = result.fx < best.fx - tol * Math.max(1, Math.abs(best.fx));
         if (result.fx < best.fx) {
             best = result;
         }
+        // Past the scheduled budget, stop at the first non-improving restart
+        if (k >= restarts && !improved)
+            break;
+    }
+    // Polish: if the winning run hit maxIter, restart from its solution with
+    // a fresh simplex (up to 3 rounds). Starting at the best point, fx can
+    // only improve; the converged flag reflects the final round honestly.
+    for (let p = 0; p < 3 && !best.converged; p++) {
+        const polished = nelderMead(fn, best.x, { maxIter, tol });
+        if (polished.fx <= best.fx) {
+            best = polished;
+        }
+        else {
+            break;
+        }
     }
     return best;
 }
 
+/**
+ * Typed error hierarchy so bot code can branch on error class instead of
+ * parsing message strings.
+ *
+ *   try { predict(candles, '1h') }
+ *   catch (e) {
+ *     if (e instanceof NotEnoughDataError) await fetchMoreCandles();
+ *     else if (e instanceof BadDataError) alertDataPipeline(e.message);
+ *     else throw e;
+ *   }
+ */
+class GarchError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+/** The sample is too short for the requested interval/model. Fetch more candles. */
+class NotEnoughDataError extends GarchError {
+}
+/** The candles themselves are broken: invalid OHLC, unsorted or duplicated timestamps. Fix the data pipeline. */
+class BadDataError extends GarchError {
+}
+/** A call argument is out of range or of the wrong shape (interval, confidence, steps, currentPrice). Fix the call site. */
+class InvalidArgumentError extends GarchError {
+}
+
+/**
+ * Validate OHLC integrity. Garbage candles (NaN, non-positive prices,
+ * high < low) otherwise propagate silently as NaN through every estimator.
+ */
+function validateCandles(candles) {
+    for (let i = 0; i < candles.length; i++) {
+        const c = candles[i];
+        if (!isFinite(c.open) || c.open <= 0 || !isFinite(c.high) || c.high <= 0
+            || !isFinite(c.low) || c.low <= 0 || !isFinite(c.close) || c.close <= 0) {
+            throw new BadDataError(`Invalid OHLC at candle ${i}: open=${c.open} high=${c.high} low=${c.low} close=${c.close}`);
+        }
+        if (c.high < c.low) {
+            throw new BadDataError(`Invalid candle ${i}: high (${c.high}) < low (${c.low})`);
+        }
+        // Open/close must lie inside [low, high] — Parkinson, Garman-Klass and
+        // Yang-Zhang all assume it; violated candles silently distort every
+        // range-based estimator. Tiny relative slack absorbs float rounding.
+        const bodyHigh = Math.max(c.open, c.close);
+        const bodyLow = Math.min(c.open, c.close);
+        if (c.high < bodyHigh * (1 - 1e-9) || c.low > bodyLow * (1 + 1e-9)) {
+            throw new BadDataError(`Invalid candle ${i}: open/close outside [low, high] (open=${c.open} high=${c.high} low=${c.low} close=${c.close})`);
+        }
+    }
+}
+/**
+ * Linear-interpolation quantile of a pre-sorted (ascending) sample.
+ */
+function empiricalQuantile(sortedAsc, p) {
+    const n = sortedAsc.length;
+    if (n === 0)
+        return NaN;
+    if (n === 1)
+        return sortedAsc[0];
+    const pos = Math.min(Math.max(p, 0), 1) * (n - 1);
+    const lo = Math.floor(pos);
+    const hi = Math.min(lo + 1, n - 1);
+    const frac = pos - lo;
+    return sortedAsc[lo] * (1 - frac) + sortedAsc[hi] * frac;
+}
 /**
  * Calculate log returns from candles
  */
@@ -143,7 +244,7 @@ function calculateReturns(candles) {
     const returns = [];
     for (let i = 1; i < candles.length; i++) {
         if (!(candles[i].close > 0) || !(candles[i - 1].close > 0)) {
-            throw new Error(`Invalid close price at index ${i}`);
+            throw new BadDataError(`Invalid close price at index ${i}`);
         }
         returns.push(Math.log(candles[i].close / candles[i - 1].close));
     }
@@ -156,7 +257,7 @@ function calculateReturnsFromPrices(prices) {
     const returns = [];
     for (let i = 1; i < prices.length; i++) {
         if (!(prices[i] > 0 && Number.isFinite(prices[i])) || !(prices[i - 1] > 0 && Number.isFinite(prices[i - 1]))) {
-            throw new Error(`Invalid price at index ${i}`);
+            throw new BadDataError(`Invalid price at index ${i}`);
         }
         returns.push(Math.log(prices[i] / prices[i - 1]));
     }
@@ -373,7 +474,9 @@ function studentTNegLL(returns, varianceSeries, df) {
     let sum = 0;
     for (let i = 0; i < n; i++) {
         const v = varianceSeries[i];
-        if (v <= 1e-12 || !isFinite(v))
+        // Positivity only — an absolute floor (1e-12) makes the likelihood
+        // scale-dependent and breaks df profiling on low-volatility series
+        if (v <= 0 || !isFinite(v))
             return 1e10;
         sum += 0.5 * Math.log(v) + halfDfPlus1 * Math.log(1 + (returns[i] ** 2) / ((df - 2) * v));
     }
@@ -391,6 +494,117 @@ function expectedAbsStudentT(df) {
         return EXPECTED_ABS_NORMAL; // fallback
     return Math.sqrt((df - 2) / Math.PI) * Math.exp(logGamma((df - 1) / 2) - logGamma(df / 2));
 }
+/**
+ * Continued-fraction evaluation for the regularized incomplete beta
+ * function (Lentz's method, Numerical Recipes §6.4).
+ */
+function betaContinuedFraction(a, b, x) {
+    const MAX_ITER = 300;
+    const EPS = 3e-14;
+    const FPMIN = 1e-300;
+    const qab = a + b;
+    const qap = a + 1;
+    const qam = a - 1;
+    let c = 1;
+    let d = 1 - (qab * x) / qap;
+    if (Math.abs(d) < FPMIN)
+        d = FPMIN;
+    d = 1 / d;
+    let h = d;
+    for (let m = 1; m <= MAX_ITER; m++) {
+        const m2 = 2 * m;
+        let aa = (m * (b - m) * x) / ((qam + m2) * (a + m2));
+        d = 1 + aa * d;
+        if (Math.abs(d) < FPMIN)
+            d = FPMIN;
+        c = 1 + aa / c;
+        if (Math.abs(c) < FPMIN)
+            c = FPMIN;
+        d = 1 / d;
+        h *= d * c;
+        aa = (-(a + m) * (qab + m) * x) / ((a + m2) * (qap + m2));
+        d = 1 + aa * d;
+        if (Math.abs(d) < FPMIN)
+            d = FPMIN;
+        c = 1 + aa / c;
+        if (Math.abs(c) < FPMIN)
+            c = FPMIN;
+        d = 1 / d;
+        const del = d * c;
+        h *= del;
+        if (Math.abs(del - 1) < EPS)
+            break;
+    }
+    return h;
+}
+/**
+ * Regularized incomplete beta function I_x(a, b).
+ */
+function incompleteBeta(x, a, b) {
+    if (x <= 0)
+        return 0;
+    if (x >= 1)
+        return 1;
+    const lnFront = logGamma(a + b) - logGamma(a) - logGamma(b)
+        + a * Math.log(x) + b * Math.log(1 - x);
+    const front = Math.exp(lnFront);
+    // Use the continued fraction in its region of fast convergence
+    if (x < (a + 1) / (a + b + 2)) {
+        return (front * betaContinuedFraction(a, b, x)) / a;
+    }
+    return 1 - (front * betaContinuedFraction(b, a, 1 - x)) / b;
+}
+/**
+ * CDF of the (raw, unstandardized) Student-t distribution with df degrees
+ * of freedom: P(T ≤ t).
+ */
+function studentTCdf(t, df) {
+    if (!isFinite(t))
+        return t > 0 ? 1 : 0;
+    const x = df / (df + t * t);
+    const tail = 0.5 * incompleteBeta(x, df / 2, 0.5);
+    return t >= 0 ? 1 - tail : tail;
+}
+/**
+ * Two-sided quantile of the STANDARDIZED Student-t distribution
+ * (unit variance). The t-analog of probit(): returns z such that
+ * P(|Z| ≤ z) = confidence when Z ~ t(df) scaled to variance 1.
+ *
+ * This is what price corridors must use when the model was fitted with
+ * Student-t innovations: with fat tails (small df) the Gaussian probit
+ * makes 68% bands too wide and 99% bands dangerously narrow.
+ *
+ * Falls back to probit() for df > 1000 (where the difference from the
+ * Gaussian quantile is < 0.3% even at 99%) or df ≤ 2 (variance undefined).
+ */
+function studentTProbit(confidence, df) {
+    if (confidence <= 0 || confidence >= 1) {
+        throw new Error(`confidence must be in (0, 1), got ${confidence}`);
+    }
+    if (!isFinite(df) || df > 1000 || df <= 2) {
+        return probit(confidence);
+    }
+    const p = (1 + confidence) / 2;
+    // Bracket the raw t quantile, then bisect on the CDF
+    let lo = 0;
+    let hi = 1;
+    while (studentTCdf(hi, df) < p && hi < 1e8)
+        hi *= 2;
+    for (let i = 0; i < 200; i++) {
+        const mid = 0.5 * (lo + hi);
+        if (studentTCdf(mid, df) < p) {
+            lo = mid;
+        }
+        else {
+            hi = mid;
+        }
+        if (hi - lo < 1e-12 * (1 + hi))
+            break;
+    }
+    const rawQuantile = 0.5 * (lo + hi);
+    // Standardize: t(df) has variance df/(df-2)
+    return rawQuantile * Math.sqrt((df - 2) / df);
+}
 /**
  * 1D grid search for optimal df that minimizes Student-t neg-LL.
  * Used by HAR-RV and NoVaS where df is profiled after main optimization.
@@ -530,15 +744,18 @@ class Garch {
             throw new Error('Need at least 50 data points for GARCH estimation');
         }
         // Determine if input is candles or prices
+        // Variance floor keeps degenerate (constant-price) data from producing
+        // log(0)/division-by-zero downstream instead of a graceful bad fit.
         if (typeof data[0] === 'number') {
             this.returns = calculateReturnsFromPrices(data);
-            this.initialVariance = sampleVariance(this.returns);
+            this.initialVariance = Math.max(sampleVariance(this.returns), 1e-300);
             this.rv = null;
         }
         else {
             const candles = data;
+            validateCandles(candles);
             this.returns = calculateReturns(candles);
-            this.initialVariance = yangZhangVariance(candles);
+            this.initialVariance = Math.max(yangZhangVariance(candles), 1e-300);
             // Parkinson (1980) per-candle RV: ~5× more efficient than r²
             this.rv = perCandleParkinson(candles, this.returns);
         }
@@ -547,16 +764,33 @@ class Garch {
      * Calibrate GARCH(1,1) parameters using Maximum Likelihood Estimation
      */
     fit(options = {}) {
-        const { maxIter = 1000, tol = 1e-8 } = options;
-        const returns = this.returns;
-        const n = returns.length;
-        const initVar = this.initialVariance;
-        const rv = this.rv;
+        const { maxIter = 1000, tol = 1e-8, forgetting = 1 } = options;
+        const n = this.returns.length;
+        // Exponential forgetting: observation t contributes with weight
+        // λ^(n−1−t) (newest = 1), so the fit adapts to regime shifts instead of
+        // weighting a year-old candle like yesterday's. λ = 1 disables.
+        const weights = new Array(n).fill(1);
+        if (forgetting < 1) {
+            for (let t = 0; t < n; t++)
+                weights[t] = Math.pow(forgetting, n - 1 - t);
+        }
+        const wTotal = weights.reduce((a, b) => a + b, 0);
+        // Calibrate in normalized space: returns are scaled to unit initial
+        // variance, so the likelihood floors, penalty constants, and optimizer
+        // tolerances are scale-free — a stablecoin pair and a high-vol altcoin
+        // follow the same optimizer path. Parameters are mapped back to the
+        // data scale after optimization.
+        const s2 = 1 / this.initialVariance;
+        const s = Math.sqrt(s2);
+        const returns = this.returns.map(r => r * s);
+        const rv = this.rv ? this.rv.map(v => v * s2) : null;
+        const initVar = 1;
+        const varFloor = 1e-12;
         // Student-t negative log-likelihood function
         function negLogLikelihood(params) {
             const [omega, alpha, beta, df] = params;
             // Constraints
-            if (omega <= 1e-12)
+            if (omega <= varFloor)
                 return 1e10;
             if (alpha < 0 || beta < 0)
                 return 1e10;
@@ -566,7 +800,7 @@ class Garch {
                 return 1e10;
             const halfDfPlus1 = (df + 1) / 2;
             const dfMinus2 = df - 2;
-            const constant = n * (logGamma(halfDfPlus1) - logGamma(df / 2) - 0.5 * Math.log(Math.PI * dfMinus2));
+            const constant = wTotal * (logGamma(halfDfPlus1) - logGamma(df / 2) - 0.5 * Math.log(Math.PI * dfMinus2));
             let variance = initVar;
             let ll = 0;
             for (let i = 0; i < n; i++) {
@@ -574,24 +808,44 @@ class Garch {
                     const innovation = rv ? rv[i - 1] : returns[i - 1] ** 2;
                     variance = omega + alpha * innovation + beta * variance;
                 }
-                if (variance <= 1e-12)
+                if (variance <= varFloor)
                     return 1e10;
                 // Student-t log-likelihood
-                ll += -0.5 * Math.log(variance) - halfDfPlus1 * Math.log(1 + (returns[i] ** 2) / (dfMinus2 * variance));
+                ll += weights[i] * (-0.5 * Math.log(variance) - halfDfPlus1 * Math.log(1 + (returns[i] ** 2) / (dfMinus2 * variance)));
             }
             return -(ll + constant);
         }
-        // Initial guesses
-        const omega0 = initVar * 0.05;
+        // Initial guesses: variance targeting — ω₀ implied by the sample
+        // variance and the persistence seed, so the optimizer starts at the
+        // observed volatility level for any asset/interval.
         const alpha0 = 0.1;
         const beta0 = 0.85;
+        const omega0 = initVar * (1 - alpha0 - beta0);
         const df0 = 5;
-        const result = nelderMeadMultiStart(negLogLikelihood, [omega0, alpha0, beta0, df0], { maxIter, tol, restarts: 3 });
-        const [omega, alpha, beta, df] = result.x;
+        // Warm start (previous window's optimum) replaces the cold seed: the
+        // multi-start perturbations then explore its neighborhood, and rolling
+        // refits converge in a fraction of the cold multi-start cost. The
+        // constraint set is window-independent, so a previous optimum is
+        // always feasible.
+        const wp = options.warmStart;
+        const warmValid = !!(wp && isFinite(wp.omega) && wp.omega > 0
+            && isFinite(wp.alpha) && isFinite(wp.beta) && isFinite(wp.df));
+        const x0 = warmValid
+            ? [wp.omega * s2, wp.alpha, wp.beta, wp.df]
+            : [omega0, alpha0, beta0, df0];
+        const result = nelderMeadMultiStart(negLogLikelihood, x0, {
+            maxIter,
+            tol,
+            restarts: warmValid ? 1 : 3,
+        });
+        // Map back to the data scale: ω scales with variance, α/β/df are scale-free
+        const [omegaScaled, alpha, beta, df] = result.x;
+        const omega = omegaScaled / s2;
         const persistence = alpha + beta;
         const unconditionalVariance = omega / (1 - persistence);
         const annualizedVol = Math.sqrt(unconditionalVariance * this.periodsPerYear) * 100;
-        const logLikelihood = -result.fx;
+        // Jacobian of the rescaling: LL in data units = LL(scaled) + n·ln s
+        const logLikelihood = -result.fx + n * Math.log(s);
         const numParams = 4;
         return {
             params: {
@@ -700,15 +954,18 @@ class Egarch {
         if (data.length < 50) {
             throw new Error('Need at least 50 data points for EGARCH estimation');
         }
+        // Variance floor keeps degenerate (constant-price) data from producing
+        // ω = ln(0) = -Infinity instead of a graceful bad fit.
         if (typeof data[0] === 'number') {
             this.returns = calculateReturnsFromPrices(data);
-            this.initialVariance = sampleVariance(this.returns);
+            this.initialVariance = Math.max(sampleVariance(this.returns), 1e-300);
             this.rv = null;
         }
         else {
             const candles = data;
+            validateCandles(candles);
             this.returns = calculateReturns(candles);
-            this.initialVariance = yangZhangVariance(candles);
+            this.initialVariance = Math.max(yangZhangVariance(candles), 1e-300);
             // Parkinson (1980) per-candle RV: ~5× more efficient than r²
             this.rv = perCandleParkinson(candles, this.returns);
         }
@@ -717,11 +974,28 @@ class Egarch {
      * Calibrate EGARCH(1,1) parameters using Maximum Likelihood Estimation
      */
     fit(options = {}) {
-        const { maxIter = 1000, tol = 1e-8 } = options;
-        const returns = this.returns;
-        const n = returns.length;
-        const initLogVar = Math.log(this.initialVariance);
-        const rv = this.rv;
+        const { maxIter = 1000, tol = 1e-8, forgetting = 1 } = options;
+        const n = this.returns.length;
+        const initLogVarOrig = Math.log(this.initialVariance);
+        // Exponential forgetting: observation t contributes with weight
+        // λ^(n−1−t) (newest = 1); λ = 1 disables.
+        const weights = new Array(n).fill(1);
+        if (forgetting < 1) {
+            for (let t = 0; t < n; t++)
+                weights[t] = Math.pow(forgetting, n - 1 - t);
+        }
+        const wTotal = weights.reduce((a, b) => a + b, 0);
+        // Calibrate in normalized space: returns are scaled to unit initial
+        // variance, so the likelihood floors, the ±50 log-variance clamp, and
+        // optimizer tolerances are scale-free — a stablecoin pair and a
+        // high-vol altcoin follow the same optimizer path. ω is mapped back
+        // to the data scale after optimization.
+        const s2 = 1 / this.initialVariance;
+        const s = Math.sqrt(s2);
+        const returns = this.returns.map(r => r * s);
+        const rv = this.rv ? this.rv.map(v => v * s2) : null;
+        const initLogVar = 0; // ln of the scaled initial variance
+        const varFloor = 1e-12;
         function negLogLikelihood(params) {
             const [omega, alpha, gamma, beta, df] = params;
             // EGARCH allows negative gamma, but beta should ensure stationarity
@@ -729,10 +1003,22 @@ class Egarch {
                 return 1e10;
             if (df <= 2.01 || df > 100)
                 return 1e10;
+            // ω/(1−β) is the implied unconditional ln(σ²). When β rides toward ±1
+            // on weakly-identified data the likelihood surface is flat along this
+            // ridge and the implied long-run variance drifts orders of magnitude
+            // away from the sample variance measured on the same data. Hard wall
+            // at 4 orders of magnitude, plus a weak Gaussian prior (sd = 1 in
+            // log-variance) that resolves the flat direction toward the sample
+            // level while leaving well-identified fits untouched.
+            const impliedLogVar = omega / (1 - beta);
+            if (!isFinite(impliedLogVar) || Math.abs(impliedLogVar - initLogVar) > Math.log(1e4))
+                return 1e10;
+            const priorDev = impliedLogVar - initLogVar;
+            const prior = 0.5 * priorDev * priorDev;
             const eAbsZ = expectedAbsStudentT(df);
             const halfDfPlus1 = (df + 1) / 2;
             const dfMinus2 = df - 2;
-            const constant = n * (logGamma(halfDfPlus1) - logGamma(df / 2) - 0.5 * Math.log(Math.PI * dfMinus2));
+            const constant = wTotal * (logGamma(halfDfPlus1) - logGamma(df / 2) - 0.5 * Math.log(Math.PI * dfMinus2));
             let logVariance = initLogVar;
             let variance = Math.exp(logVariance);
             let ll = 0;
@@ -752,28 +1038,48 @@ class Egarch {
                     logVariance = Math.max(-50, Math.min(50, logVariance));
                     variance = Math.exp(logVariance);
                 }
-                if (variance <= 1e-12 || !isFinite(variance))
+                if (variance <= varFloor || !isFinite(variance))
                     return 1e10;
                 // Student-t log-likelihood
-                ll += -0.5 * Math.log(variance) - halfDfPlus1 * Math.log(1 + (returns[i] ** 2) / (dfMinus2 * variance));
+                ll += weights[i] * (-0.5 * Math.log(variance) - halfDfPlus1 * Math.log(1 + (returns[i] ** 2) / (dfMinus2 * variance)));
             }
-            return -(ll + constant);
+            return -(ll + constant) + prior;
         }
-        // Initial guesses
-        // omega approximates log of unconditional variance when other params are small
-        const omega0 = initLogVar * 0.1;
+        // Initial guesses: variance targeting in log space —
+        // E[ln σ²] = ω/(1−β), so ω₀ = ln(σ̂²)·(1−β₀) starts the optimizer at
+        // the observed volatility level (ω₀ = 0.1·ln σ̂² implied a level of
+        // 2·ln σ̂² with β₀ = 0.95 — orders of magnitude off).
+        const beta0 = 0.95;
+        const omega0 = initLogVar * (1 - beta0);
         const alpha0 = 0.1;
         const gamma0 = -0.05; // Negative for typical leverage effect
-        const beta0 = 0.95;
         const df0 = 5;
-        const result = nelderMeadMultiStart(negLogLikelihood, [omega0, alpha0, gamma0, beta0, df0], { maxIter, tol, restarts: 4 });
-        const [omega, alpha, gamma, beta, df] = result.x;
+        // Warm start (previous window's optimum) replaces the cold seed with a
+        // reduced restart budget. The hard wall on the implied unconditional
+        // level moves with the sample variance between windows, so an
+        // out-of-wall warm seed falls back to the cold start.
+        const wp = options.warmStart;
+        let warmX0 = null;
+        if (wp && isFinite(wp.omega) && isFinite(wp.beta) && Math.abs(wp.beta) < 1) {
+            const cand = [wp.omega - (1 - wp.beta) * initLogVarOrig, wp.alpha, wp.gamma, wp.beta, wp.df];
+            if (Math.abs(cand[0] / (1 - wp.beta)) <= Math.log(1e4))
+                warmX0 = cand;
+        }
+        const result = nelderMeadMultiStart(negLogLikelihood, warmX0 ?? [omega0, alpha0, gamma0, beta0, df0], { maxIter, tol, restarts: warmX0 ? 1 : 4 });
+        // Map back to the data scale: ln σ²_orig = ln σ²_scaled + ln σ̂²_orig,
+        // so ω_orig = ω_scaled + (1−β)·ln σ̂²_orig; α/γ/β/df are scale-free
+        const [omegaScaled, alpha, gamma, beta, df] = result.x;
+        const omega = omegaScaled + (1 - beta) * initLogVarOrig;
         // For EGARCH, unconditional variance: E[ln(σ²)] = ω/(1-β)
         // So E[σ²] ≈ exp(ω/(1-β)) when α and γ effects average out
         const unconditionalLogVar = omega / (1 - beta);
         const unconditionalVariance = Math.exp(unconditionalLogVar);
         const annualizedVol = Math.sqrt(unconditionalVariance * this.periodsPerYear) * 100;
-        const logLikelihood = -result.fx;
+        // Report the pure likelihood: strip the shrinkage prior evaluated at
+        // the optimum (the prior deviation is scale-invariant), then add the
+        // Jacobian of the rescaling: LL in data units = LL(scaled) + n·ln s
+        const priorAtOptimum = 0.5 * (unconditionalLogVar - initLogVarOrig) ** 2;
+        const logLikelihood = -(result.fx - priorAtOptimum) + n * Math.log(s);
         const numParams = 5;
         return {
             params: {
@@ -824,6 +1130,33 @@ class Egarch {
         }
         return variance;
     }
+    /**
+     * Mean drift of the magnitude term under the fitted dynamics.
+     *
+     * With RV magnitude, E[√(RV/σ²)] ≠ E[|z|]: the in-sample recursion
+     * carries a mean offset α·m̄ per step that ω absorbed during fitting.
+     * A multi-step forecast that drops the α term entirely would therefore
+     * converge to a level systematically below the fitted dynamics.
+     * Returns m̄ = mean(magnitude − E|z|) over the sample (0 for prices-only
+     * input, where magnitude = |z| and the offset is sampling noise).
+     */
+    magnitudeDrift(params) {
+        if (!this.rv)
+            return 0;
+        const { df } = params;
+        const eAbsZ = df > 2 ? expectedAbsStudentT(df) : EXPECTED_ABS_NORMAL;
+        const series = this.getVarianceSeries(params);
+        let sum = 0;
+        let count = 0;
+        for (let i = 1; i < this.returns.length; i++) {
+            const m = Math.sqrt(this.rv[i - 1] / series[i - 1]);
+            if (!isFinite(m))
+                continue;
+            sum += m - eAbsZ;
+            count++;
+        }
+        return count > 0 ? sum / count : 0;
+    }
     /**
      * Forecast variance forward
      *
@@ -848,11 +1181,15 @@ class Egarch {
             + alpha * (magnitude - eAbsZ)
             + gamma * z
             + beta * Math.log(lastVariance);
+        logVariance = Math.max(-50, Math.min(50, logVariance));
         variance.push(Math.exp(logVariance));
-        // Multi-step: assume E[z] = 0, E[|z|] = eAbsZ
-        // So the α and γ terms contribute 0 on average
+        // Multi-step: assume E[z] = 0. With RV magnitude the α term has a
+        // nonzero mean α·m̄ under the fitted dynamics — keep it as drift so
+        // the forecast converges to the same level the fit implies.
+        const drift = alpha * this.magnitudeDrift(params);
         for (let h = 1; h < steps; h++) {
-            logVariance = omega + beta * logVariance;
+            logVariance = omega + drift + beta * logVariance;
+            logVariance = Math.max(-50, Math.min(50, logVariance));
             variance.push(Math.exp(logVariance));
         }
         return {
@@ -995,11 +1332,14 @@ class HarRv {
     shortLag;
     mediumLag;
     longLag;
+    logSpec;
+    lnRv = null;
     constructor(data, options = {}) {
         this.periodsPerYear = options.periodsPerYear ?? 252;
         this.shortLag = options.shortLag ?? DEFAULT_SHORT;
         this.mediumLag = options.mediumLag ?? DEFAULT_MEDIUM;
         this.longLag = options.longLag ?? DEFAULT_LONG;
+        this.logSpec = options.logSpec ?? false;
         const minRequired = this.longLag + 30;
         if (data.length < minRequired) {
             throw new Error(`Need at least ${minRequired} data points for HAR-RV estimation`);
@@ -1011,10 +1351,25 @@ class HarRv {
         }
         else {
             const candles = data;
+            validateCandles(candles);
             this.returns = calculateReturns(candles);
             // Parkinson (1980) per-candle RV: (1/(4·ln2))·(ln(H/L))²
             this.rv = perCandleParkinson(candles, this.returns);
         }
+        if (this.logSpec) {
+            // ln RV with a floor at half the smallest positive observation: the
+            // log regression must not see −Infinity from a flat candle
+            let minPos = Infinity;
+            for (const v of this.rv) {
+                if (v > 0 && v < minPos)
+                    minPos = v;
+            }
+            if (!isFinite(minPos)) {
+                throw new Error('log-HAR needs at least one positive realized-variance observation');
+            }
+            const floor = minPos * 0.5;
+            this.lnRv = this.rv.map(v => Math.log(Math.max(v, floor)));
+        }
     }
     /**
      * Calibrate HAR-RV via OLS.
@@ -1022,6 +1377,13 @@ class HarRv {
     fit() {
         const { rv, shortLag, mediumLag, longLag } = this;
         const n = rv.length;
+        // Level spec: regress in normalized units (RV scaled to unit mean) so
+        // the singular-matrix pivot threshold keeps detecting genuine
+        // collinearity instead of tripping on low-volatility series.
+        // Log spec: ln RV is already O(10) and shift-equivariant — no scaling.
+        const meanRv = rv.reduce((s, v) => s + v, 0) / n;
+        const s2 = meanRv > 0 ? 1 / meanRv : 1;
+        const series = this.logSpec ? this.lnRv : rv.map(v => v * s2);
         // Build regression data
         // Usable range: t = longLag-1 .. n-2 (need longLag history, and rv[t+1] as target)
         const startIdx = longLag - 1;
@@ -1030,21 +1392,31 @@ class HarRv {
         const X = [];
         const y = [];
         for (let t = startIdx; t <= endIdx; t++) {
-            const rvShort = rollingMean(rv, t, shortLag);
-            const rvMedium = rollingMean(rv, t, mediumLag);
-            const rvLong = rollingMean(rv, t, longLag);
+            const rvShort = rollingMean(series, t, shortLag);
+            const rvMedium = rollingMean(series, t, mediumLag);
+            const rvLong = rollingMean(series, t, longLag);
             X.push([1, rvShort, rvMedium, rvLong]);
-            y.push(rv[t + 1]);
+            y.push(series[t + 1]);
         }
         const result = ols(X, y);
-        const [beta0, betaShort, betaMedium, betaLong] = result.beta;
+        const [beta0Raw, betaShort, betaMedium, betaLong] = result.beta;
+        // Level spec: intercept back to the data scale. Log spec: intercept is
+        // already in data units (log scaling is a shift the OLS absorbed).
+        const beta0 = this.logSpec ? beta0Raw : beta0Raw / s2;
+        const residualLogVar = this.logSpec ? result.rss / nObs : undefined;
         const persistence = betaShort + betaMedium + betaLong;
-        const unconditionalVariance = persistence < 1 && persistence > -1
-            ? Math.max(beta0 / (1 - persistence), 1e-20)
-            : sampleVariance(this.returns);
+        let unconditionalVariance;
+        if (persistence < 1 && persistence > -1) {
+            unconditionalVariance = this.logSpec
+                ? Math.exp(Math.max(-720, Math.min(50, beta0 / (1 - persistence) + residualLogVar / 2)))
+                : Math.max(beta0 / (1 - persistence), 1e-20);
+        }
+        else {
+            unconditionalVariance = sampleVariance(this.returns);
+        }
         const annualizedVol = Math.sqrt(Math.abs(unconditionalVariance) * this.periodsPerYear) * 100;
         // Student-t log-likelihood on returns using HAR-RV fitted variances
-        const varianceSeries = this.getVarianceSeriesInternal(result.beta);
+        const varianceSeries = this.getVarianceSeriesInternal([beta0, betaShort, betaMedium, betaLong], residualLogVar ?? 0);
         const df = profileStudentTDf(this.returns, varianceSeries);
         const ll = -studentTNegLL(this.returns, varianceSeries, df);
         const numParams = 5; // beta0, betaShort, betaMedium, betaLong, df
@@ -1059,6 +1431,7 @@ class HarRv {
                 annualizedVol,
                 r2: result.r2,
                 df,
+                ...(this.logSpec ? { logSpec: true, residualLogVar } : {}),
             },
             diagnostics: {
                 logLikelihood: ll,
@@ -1071,10 +1444,12 @@ class HarRv {
     }
     /**
      * Internal: compute variance series from beta vector.
+     * For the log spec the prediction is E[RV] = exp(ŷ + σ²_ε/2).
      */
-    getVarianceSeriesInternal(beta) {
-        const { rv, shortLag, mediumLag, longLag } = this;
-        const n = rv.length;
+    getVarianceSeriesInternal(beta, residualLogVar = 0) {
+        const { shortLag, mediumLag, longLag } = this;
+        const source = this.logSpec ? this.lnRv : this.rv;
+        const n = source.length;
         const fallback = sampleVariance(this.returns);
         const series = [];
         for (let i = 0; i < n; i++) {
@@ -1085,11 +1460,13 @@ class HarRv {
             else {
                 // HAR prediction for rv[i] based on rv[..i-1]
                 const t = i - 1;
-                const rvS = rollingMean(rv, t, shortLag);
-                const rvM = rollingMean(rv, t, mediumLag);
-                const rvL = rollingMean(rv, t, longLag);
+                const rvS = rollingMean(source, t, shortLag);
+                const rvM = rollingMean(source, t, mediumLag);
+                const rvL = rollingMean(source, t, longLag);
                 const predicted = beta[0] + beta[1] * rvS + beta[2] * rvM + beta[3] * rvL;
-                series.push(Math.max(predicted, 1e-20));
+                series.push(this.logSpec
+                    ? Math.exp(Math.max(-720, Math.min(50, predicted + residualLogVar / 2)))
+                    : Math.max(predicted, 1e-20));
             }
         }
         return series;
@@ -1099,19 +1476,21 @@ class HarRv {
      */
     getVarianceSeries(params) {
         const beta = [params.beta0, params.betaShort, params.betaMedium, params.betaLong];
-        return this.getVarianceSeriesInternal(beta);
+        return this.getVarianceSeriesInternal(beta, params.residualLogVar ?? 0);
     }
     /**
      * Forecast variance forward.
      *
      * Uses iterative substitution: each forecast step feeds back
-     * into the rolling RV components for subsequent steps.
+     * into the rolling RV components for subsequent steps (point forecasts
+     * of ln RV for the log spec, bias-corrected on output).
      */
     forecast(params, steps = 1) {
-        const { rv, shortLag, mediumLag, longLag } = this;
+        const { shortLag, mediumLag, longLag } = this;
         const { beta0, betaShort, betaMedium, betaLong } = params;
-        // Working copy of recent rv values + forecasts appended
-        const history = rv.slice();
+        const residualLogVar = params.residualLogVar ?? 0;
+        // Working copy of recent (ln) rv values + forecasts appended
+        const history = this.logSpec ? this.lnRv.slice() : this.rv.slice();
         const variance = [];
         for (let h = 0; h < steps; h++) {
             const t = history.length - 1;
@@ -1119,9 +1498,15 @@ class HarRv {
             const rvM = rollingMean(history, t, mediumLag);
             const rvL = rollingMean(history, t, longLag);
             const predicted = beta0 + betaShort * rvS + betaMedium * rvM + betaLong * rvL;
-            const v = Math.max(predicted, 1e-20);
-            variance.push(v);
-            history.push(v);
+            if (this.logSpec) {
+                variance.push(Math.exp(Math.max(-720, Math.min(50, predicted + residualLogVar / 2))));
+                history.push(predicted); // E[ln RV] feeds the recursion
+            }
+            else {
+                const v = Math.max(predicted, 1e-20);
+                variance.push(v);
+                history.push(v);
+            }
         }
         return {
             variance,
@@ -1158,7 +1543,7 @@ function calibrateHarRv(data, options = {}) {
  * where:
  * - ω (omega) > 0: constant term
  * - α (alpha) ≥ 0: symmetric shock response
- * - γ (gamma) ≥ 0: asymmetric leverage coefficient
+ * - γ (gamma) ≥ −α: asymmetric leverage coefficient (negative = inverted leverage)
  * - β (beta) ≥ 0: persistence
  * - I(r<0) = 1 when return is negative, 0 otherwise
  * - Stationarity: α + γ/2 + β < 1
@@ -1176,15 +1561,18 @@ class GjrGarch {
         if (data.length < 50) {
             throw new Error('Need at least 50 data points for GJR-GARCH estimation');
         }
+        // Variance floor keeps degenerate (constant-price) data from producing
+        // log(0)/division-by-zero downstream instead of a graceful bad fit.
         if (typeof data[0] === 'number') {
             this.returns = calculateReturnsFromPrices(data);
-            this.initialVariance = sampleVariance(this.returns);
+            this.initialVariance = Math.max(sampleVariance(this.returns), 1e-300);
             this.rv = null;
         }
         else {
             const candles = data;
+            validateCandles(candles);
             this.returns = calculateReturns(candles);
-            this.initialVariance = yangZhangVariance(candles);
+            this.initialVariance = Math.max(yangZhangVariance(candles), 1e-300);
             this.rv = perCandleParkinson(candles, this.returns);
         }
     }
@@ -1192,16 +1580,38 @@ class GjrGarch {
      * Calibrate GJR-GARCH(1,1) parameters using Maximum Likelihood Estimation
      */
     fit(options = {}) {
-        const { maxIter = 1000, tol = 1e-8 } = options;
-        const returns = this.returns;
-        const n = returns.length;
-        const initVar = this.initialVariance;
-        const rv = this.rv;
+        const { maxIter = 1000, tol = 1e-8, forgetting = 1 } = options;
+        const n = this.returns.length;
+        // Exponential forgetting: observation t contributes with weight
+        // λ^(n−1−t) (newest = 1); λ = 1 disables.
+        const weights = new Array(n).fill(1);
+        if (forgetting < 1) {
+            for (let t = 0; t < n; t++)
+                weights[t] = Math.pow(forgetting, n - 1 - t);
+        }
+        const wTotal = weights.reduce((a, b) => a + b, 0);
+        // Calibrate in normalized space: returns are scaled to unit initial
+        // variance, so the likelihood floors, penalty constants, and optimizer
+        // tolerances are scale-free — a stablecoin pair and a high-vol altcoin
+        // follow the same optimizer path. Parameters are mapped back to the
+        // data scale after optimization.
+        const s2 = 1 / this.initialVariance;
+        const s = Math.sqrt(s2);
+        const returns = this.returns.map(r => r * s);
+        const rv = this.rv ? this.rv.map(v => v * s2) : null;
+        const initVar = 1;
+        const varFloor = 1e-12;
         function negLogLikelihood(params) {
             const [omega, alpha, gamma, beta, df] = params;
-            if (omega <= 1e-12)
+            if (omega <= varFloor)
+                return 1e10;
+            if (alpha < 0 || beta < 0)
                 return 1e10;
-            if (alpha < 0 || gamma < 0 || beta < 0)
+            // Positivity of σ² only needs the response to negative returns
+            // (α + γ) to stay non-negative — γ itself may be negative (inverted
+            // leverage: pumps driving volatility harder than dumps, common in
+            // crypto), which a γ ≥ 0 constraint would silently censor.
+            if (alpha + gamma < 0)
                 return 1e10;
             if (alpha + gamma / 2 + beta >= 0.9999)
                 return 1e10;
@@ -1209,7 +1619,7 @@ class GjrGarch {
                 return 1e10;
             const halfDfPlus1 = (df + 1) / 2;
             const dfMinus2 = df - 2;
-            const constant = n * (logGamma(halfDfPlus1) - logGamma(df / 2) - 0.5 * Math.log(Math.PI * dfMinus2));
+            const constant = wTotal * (logGamma(halfDfPlus1) - logGamma(df / 2) - 0.5 * Math.log(Math.PI * dfMinus2));
             let variance = initVar;
             let ll = 0;
             for (let i = 0; i < n; i++) {
@@ -1218,24 +1628,40 @@ class GjrGarch {
                     const indicator = returns[i - 1] < 0 ? 1 : 0;
                     variance = omega + alpha * innovation + gamma * innovation * indicator + beta * variance;
                 }
-                if (variance <= 1e-12)
+                if (variance <= varFloor)
                     return 1e10;
                 // Student-t log-likelihood
-                ll += -0.5 * Math.log(variance) - halfDfPlus1 * Math.log(1 + (returns[i] ** 2) / (dfMinus2 * variance));
+                ll += weights[i] * (-0.5 * Math.log(variance) - halfDfPlus1 * Math.log(1 + (returns[i] ** 2) / (dfMinus2 * variance)));
             }
             return -(ll + constant);
         }
-        const omega0 = initVar * 0.05;
+        // Variance targeting: ω₀ implied by sample variance and persistence seed
         const alpha0 = 0.05;
         const gamma0 = 0.1;
         const beta0 = 0.85;
+        const omega0 = initVar * (1 - alpha0 - gamma0 / 2 - beta0);
         const df0 = 5;
-        const result = nelderMeadMultiStart(negLogLikelihood, [omega0, alpha0, gamma0, beta0, df0], { maxIter, tol, restarts: 4 });
-        const [omega, alpha, gamma, beta, df] = result.x;
+        // Warm start (previous window's optimum) replaces the cold seed with a
+        // reduced restart budget; feasibility is window-independent.
+        const wp = options.warmStart;
+        const warmValid = !!(wp && isFinite(wp.omega) && wp.omega > 0
+            && isFinite(wp.alpha) && isFinite(wp.gamma) && isFinite(wp.beta) && isFinite(wp.df));
+        const x0 = warmValid
+            ? [wp.omega * s2, wp.alpha, wp.gamma, wp.beta, wp.df]
+            : [omega0, alpha0, gamma0, beta0, df0];
+        const result = nelderMeadMultiStart(negLogLikelihood, x0, {
+            maxIter,
+            tol,
+            restarts: warmValid ? 1 : 4,
+        });
+        // Map back to the data scale: ω scales with variance, α/γ/β/df are scale-free
+        const [omegaScaled, alpha, gamma, beta, df] = result.x;
+        const omega = omegaScaled / s2;
         const persistence = alpha + gamma / 2 + beta;
         const unconditionalVariance = omega / (1 - persistence);
         const annualizedVol = Math.sqrt(unconditionalVariance * this.periodsPerYear) * 100;
-        const logLikelihood = -result.fx;
+        // Jacobian of the rescaling: LL in data units = LL(scaled) + n·ln s
+        const logLikelihood = -result.fx + n * Math.log(s);
         const numParams = 5;
         return {
             params: {
@@ -1324,6 +1750,251 @@ function calibrateGjrGarch(data, options = {}) {
     return model.fit(options);
 }
 
+/**
+ * Realized GARCH(1,1) (Hansen, Huang & Shek, 2012), log-linear, φ = 1.
+ *
+ *   r_t = σ_t·z_t,                     z_t ~ standardized t(df)
+ *   ln σ²_t = ω + β·ln σ²_{t−1} + γ·ln RV_{t−1}
+ *   ln RV_t = ξ + ln σ²_t + τ₁·z_t + τ₂·(z²_t − 1) + u_t,   u_t ~ N(0, σ²_u)
+ *
+ * Unlike the RV-in-place-of-ε² hybrids, the measurement equation estimates
+ * the bias (ξ) and noise (σ_u) of the realized measure inside the joint
+ * likelihood: RV information is weighted by how trustworthy it actually is,
+ * and leverage enters through τ₁. Stationarity: β + γ < 1 (with φ = 1).
+ */
+class RealizedGarch {
+    returns;
+    lnRv;
+    periodsPerYear;
+    initialVariance;
+    constructor(data, options = {}) {
+        this.periodsPerYear = options.periodsPerYear ?? 252;
+        if (data.length < 50) {
+            throw new Error('Need at least 50 data points for Realized GARCH estimation');
+        }
+        let rv;
+        if (typeof data[0] === 'number') {
+            this.returns = calculateReturnsFromPrices(data);
+            this.initialVariance = Math.max(sampleVariance(this.returns), 1e-300);
+            // Prices only — squared returns as the (noisy) realized measure
+            rv = this.returns.map(r => r * r);
+        }
+        else {
+            const candles = data;
+            validateCandles(candles);
+            this.returns = calculateReturns(candles);
+            this.initialVariance = Math.max(yangZhangVariance(candles), 1e-300);
+            rv = perCandleParkinson(candles, this.returns);
+        }
+        // ln RV with a floor at half the smallest positive observation: the
+        // measurement equation lives in logs and a literal zero (flat candle)
+        // must not inject −Infinity.
+        let minPos = Infinity;
+        for (const v of rv) {
+            if (v > 0 && v < minPos)
+                minPos = v;
+        }
+        if (!isFinite(minPos)) {
+            throw new Error('Realized GARCH needs at least one positive realized-variance observation');
+        }
+        const floor = minPos * 0.5;
+        this.lnRv = rv.map(v => Math.log(Math.max(v, floor)));
+    }
+    /**
+     * Calibrate by joint MLE over returns and the realized measure.
+     */
+    fit(options = {}) {
+        const { maxIter = 1000, tol = 1e-8, forgetting = 1 } = options;
+        const n = this.returns.length;
+        const initLogVarOrig = Math.log(this.initialVariance);
+        // Normalized space: returns to unit initial variance, ln RV shifted
+        // accordingly — ξ, τ, σ_u, df are scale-free; ω is mapped back below.
+        const s2 = 1 / this.initialVariance;
+        const s = Math.sqrt(s2);
+        const returns = this.returns.map(r => r * s);
+        const lnRv = this.lnRv.map(v => v + Math.log(s2));
+        // Exponential forgetting: w_t = λ^(n−1−t), newest observation weight 1
+        const weights = new Array(n).fill(1);
+        if (forgetting < 1) {
+            for (let t = 0; t < n; t++)
+                weights[t] = Math.pow(forgetting, n - 1 - t);
+        }
+        const wTotal = weights.reduce((a, b) => a + b, 0);
+        const LOG_2PI = Math.log(2 * Math.PI);
+        function negLogLikelihood(params) {
+            const [omega, beta, gamma, xi, tau1, tau2, lnSigmaU, df] = params;
+            if (beta < 0 || gamma < 0)
+                return 1e10;
+            if (beta + gamma >= 0.9999)
+                return 1e10;
+            if (df <= 2.01 || df > 100)
+                return 1e10;
+            if (Math.abs(lnSigmaU) > 5)
+                return 1e10;
+            // Same flat-ridge treatment as EGARCH: hard wall on the implied
+            // unconditional level plus a weak Gaussian prior toward the sample
+            // variance (scaled space: ln σ̂² = 0)
+            const impliedLogVar = (omega + gamma * xi) / (1 - beta - gamma);
+            if (!isFinite(impliedLogVar) || Math.abs(impliedLogVar) > Math.log(1e4))
+                return 1e10;
+            const prior = 0.5 * impliedLogVar * impliedLogVar;
+            const sigmaU2 = Math.exp(2 * lnSigmaU);
+            const halfDfPlus1 = (df + 1) / 2;
+            const dfMinus2 = df - 2;
+            const constant = wTotal * (logGamma(halfDfPlus1) - logGamma(df / 2) - 0.5 * Math.log(Math.PI * dfMinus2)
+                - 0.5 * (LOG_2PI + 2 * lnSigmaU));
+            let logVariance = 0; // scaled initial variance = 1
+            let ll = 0;
+            for (let i = 0; i < n; i++) {
+                if (i > 0) {
+                    logVariance = omega + beta * logVariance + gamma * lnRv[i - 1];
+                    logVariance = Math.max(-50, Math.min(50, logVariance));
+                }
+                const variance = Math.exp(logVariance);
+                const z = returns[i] / Math.sqrt(variance);
+                // Return likelihood (Student-t) + measurement likelihood (Gaussian)
+                const u = lnRv[i] - xi - logVariance - tau1 * z - tau2 * (z * z - 1);
+                ll += weights[i] * (-0.5 * logVariance - halfDfPlus1 * Math.log(1 + (z * z) / dfMinus2)
+                    - 0.5 * (u * u) / sigmaU2);
+                if (!isFinite(ll))
+                    return 1e10;
+            }
+            return -(ll + constant) + prior;
+        }
+        // Initial guesses: variance targeting in scaled log space (level 0)
+        const beta0 = 0.55;
+        const gamma0 = 0.4;
+        const xi0 = lnRv.reduce((a, b) => a + b, 0) / n; // E[ln RV] − E[ln σ²] with E[ln σ²]=0
+        const omega0 = -gamma0 * xi0;
+        const x0 = [omega0, beta0, gamma0, xi0, -0.05, 0.1, Math.log(0.5), 5];
+        // Warm start (previous window's optimum) replaces the cold seed with a
+        // reduced restart budget; the level wall moves with the sample, so an
+        // out-of-wall warm seed falls back to the cold start.
+        let warmX0 = null;
+        const wp = options.warmStart;
+        if (wp && isFinite(wp.omega) && isFinite(wp.beta) && isFinite(wp.gamma) && wp.beta + wp.gamma < 1) {
+            const cand = [
+                wp.omega - (1 - wp.beta - wp.gamma) * initLogVarOrig,
+                wp.beta,
+                wp.gamma,
+                wp.xi,
+                wp.tau1,
+                wp.tau2,
+                Math.log(Math.max(wp.sigmaU, 1e-4)),
+                wp.df,
+            ];
+            const implied = (cand[0] + wp.gamma * wp.xi) / (1 - wp.beta - wp.gamma);
+            if (Math.abs(implied) <= Math.log(1e4))
+                warmX0 = cand;
+        }
+        // Cold restarts kept low: the variance-targeted seed plus the level
+        // prior already resolve the ω/β/γ ridge, and the adaptive multi-start
+        // extends the budget on its own when restarts keep improving.
+        const result = nelderMeadMultiStart(negLogLikelihood, warmX0 ?? x0, {
+            maxIter,
+            tol,
+            restarts: warmX0 ? 1 : 2,
+        });
+        // Map back: ln σ²_orig = ln σ²_scaled + ln σ̂²_orig, ξ is invariant, so
+        // ω_orig = ω_scaled + (1 − β − γ)·ln σ̂²_orig
+        const [omegaScaled, beta, gamma, xi, tau1, tau2, lnSigmaU, df] = result.x;
+        const omega = omegaScaled + (1 - beta - gamma) * initLogVarOrig;
+        const sigmaU = Math.exp(lnSigmaU);
+        const persistence = beta + gamma;
+        const unconditionalLogVar = (omega + gamma * xi) / (1 - persistence);
+        const unconditionalVariance = Math.exp(unconditionalLogVar);
+        const annualizedVol = Math.sqrt(unconditionalVariance * this.periodsPerYear) * 100;
+        // Strip the shrinkage prior (deviation is scale-invariant) and add the
+        // returns Jacobian; the ln RV measurement density is shift-invariant.
+        const priorAtOptimum = 0.5 * (unconditionalLogVar - initLogVarOrig) ** 2;
+        const logLikelihood = -(result.fx - priorAtOptimum) + n * Math.log(s);
+        const numParams = 8;
+        return {
+            params: {
+                omega,
+                beta,
+                gamma,
+                xi,
+                tau1,
+                tau2,
+                sigmaU,
+                persistence,
+                unconditionalVariance,
+                annualizedVol,
+                df,
+            },
+            diagnostics: {
+                logLikelihood,
+                aic: calculateAIC(logLikelihood, numParams),
+                bic: calculateBIC(logLikelihood, numParams, n),
+                iterations: result.iterations,
+                converged: result.converged,
+            },
+        };
+    }
+    /**
+     * Conditional variance series (data scale). σ²_t is driven by RV_{t−1}
+     * through the log recursion — no look-ahead.
+     */
+    getVarianceSeries(params) {
+        const { omega, beta, gamma } = params;
+        const variance = [];
+        let logVariance = Math.log(this.initialVariance);
+        for (let i = 0; i < this.returns.length; i++) {
+            if (i > 0) {
+                logVariance = omega + beta * logVariance + gamma * this.lnRv[i - 1];
+                logVariance = Math.max(-720, Math.min(50, logVariance));
+            }
+            variance.push(Math.exp(logVariance));
+        }
+        return variance;
+    }
+    /**
+     * Forecast variance forward. One step uses the actual last RV; further
+     * steps substitute E[ln RV_t] = ξ + ln σ²_t, giving the reduced recursion
+     * ln σ²_{t+h} = (ω + γξ) + (β + γ)·ln σ²_{t+h−1}.
+     */
+    forecast(params, steps = 1) {
+        const { omega, beta, gamma, xi } = params;
+        const series = this.getVarianceSeries(params);
+        const variance = [];
+        let logVariance = omega
+            + beta * Math.log(series[series.length - 1])
+            + gamma * this.lnRv[this.lnRv.length - 1];
+        logVariance = Math.max(-720, Math.min(50, logVariance));
+        variance.push(Math.exp(logVariance));
+        for (let h = 1; h < steps; h++) {
+            logVariance = omega + gamma * xi + (beta + gamma) * logVariance;
+            logVariance = Math.max(-720, Math.min(50, logVariance));
+            variance.push(Math.exp(logVariance));
+        }
+        return {
+            variance,
+            volatility: variance.map(v => Math.sqrt(v)),
+            annualized: variance.map(v => Math.sqrt(v * this.periodsPerYear) * 100),
+        };
+    }
+    /**
+     * Get the return series.
+     */
+    getReturns() {
+        return [...this.returns];
+    }
+    /**
+     * Get initial variance estimate.
+     */
+    getInitialVariance() {
+        return this.initialVariance;
+    }
+}
+/**
+ * Convenience function to calibrate Realized GARCH from candles or prices.
+ */
+function calibrateRealizedGarch(data, options = {}) {
+    const model = new RealizedGarch(data, options);
+    return model.fit(options);
+}
+
 const DEFAULT_LAGS = 10;
 /**
  * NoVaS (Normalizing and Variance-Stabilizing) model (Politis, 2003)
@@ -1362,6 +2033,7 @@ class NoVaS {
         }
         else {
             const candles = data;
+            validateCandles(candles);
             this.returns = calculateReturns(candles);
             // Parkinson (1980) per-candle RV: ~5× more efficient than r²
             this.rv = perCandleParkinson(candles, this.returns);
@@ -1377,17 +2049,28 @@ class NoVaS {
         const returns = this.returns;
         const n = returns.length;
         const p = this.lags;
-        const initVar = sampleVariance(returns);
+        const initVarOrig = sampleVariance(returns);
         // Innovation: Parkinson RV for candles, r² for prices
         const r2 = this.rv ?? returns.map(r => r * r);
+        // Calibrate in normalized space: returns are scaled to unit sample
+        // variance, so D² floors, the screening grid, and the stage-2 OLS
+        // conditioning are scale-free. The intercept weight and β₀ are mapped
+        // back to the data scale below; lag weights are scale-free.
+        const s2 = initVarOrig > 0 ? 1 / initVarOrig : 1;
+        const returnsS = returns.map(r => r * Math.sqrt(s2));
+        const r2S = r2.map(v => v * s2);
+        const initVar = 1;
+        const unscaleWeights = (w) => [w[0] / s2, ...w.slice(1)];
         /**
          * Compute D² for a given weight vector.
          * D² = S² + (K - 3)² where S, K are skewness and kurtosis of W_t.
          */
+        // In normalized space the sample variance is 1, so a fixed epsilon is safe
+        const a0Floor = 1e-12;
         function objectiveD2(rawWeights) {
             // Enforce constraints: a_j >= 0 via abs, a_0 > epsilon
             const weights = rawWeights.map(w => Math.abs(w));
-            if (weights[0] < 1e-15)
+            if (weights[0] < a0Floor)
                 return 1e10;
             // Stationarity: sum(a_1..a_p) < 1
             let lagSum = 0;
@@ -1404,11 +2087,11 @@ class NoVaS {
             for (let t = p; t < n; t++) {
                 let variance = weights[0];
                 for (let j = 1; j <= p; j++) {
-                    variance += weights[j] * r2[t - j];
+                    variance += weights[j] * r2S[t - j];
                 }
-                if (variance <= 1e-15)
+                if (variance <= 0)
                     return 1e10;
-                const w = returns[t] / Math.sqrt(variance);
+                const w = returnsS[t] / Math.sqrt(variance);
                 if (!isFinite(w))
                     return 1e10;
                 sumW += w;
@@ -1438,28 +2121,70 @@ class NoVaS {
         for (let j = 1; j <= p; j++) {
             x0.push(0.9 * (1 - lambda) * Math.pow(lambda, j - 1));
         }
-        const result = nelderMeadMultiStart(objectiveD2, x0, { maxIter, tol, restarts: 6 });
-        // Extract final weights (abs for constraint enforcement)
-        const weights = result.x.map(w => Math.abs(w));
-        let persistence = 0;
-        for (let j = 1; j <= p; j++)
-            persistence += weights[j];
-        const unconditionalVariance = persistence < 1 && persistence > -1
-            ? Math.max(weights[0] / (1 - persistence), 1e-20)
-            : sampleVariance(returns);
-        const annualizedVol = Math.sqrt(unconditionalVariance * this.periodsPerYear) * 100;
-        // ── Stage 2: OLS rescaling of D²-variance ──────────────
-        // RV_{t+1} = β₀ + β₁·σ²_t(D²)
-        // D² weights discover lag structure; OLS rescales for forecast accuracy.
-        // Only 2 parameters → robust on small samples with noisy per-candle RV.
-        const d2Variance = this.getVarianceSeriesInternal(weights);
-        let forecastWeights;
-        let olsR2;
-        try {
+        // Warm start (previous window's data-scale weights): the screening
+        // cloud exists to discover the lag structure, which a warm start
+        // already carries — skip it and run a reduced multi-start instead.
+        const warm = options.warmWeights;
+        const warmScaled = warm && warm.length === p + 1 && warm.every(v => isFinite(v))
+            ? [warm[0] * s2, ...warm.slice(1)]
+            : null;
+        // Screening: the multi-start perturbation scales x0 multiplicatively and
+        // preserves its exponential-decay shape, so far-lag weight structures are
+        // unreachable from x0 alone (measured: 5.6× worse D² on two-spike ARCH
+        // ground truth). D² costs one pass to evaluate, so scan a deterministic
+        // low-discrepancy cloud of sparse weight shapes and hand the best few to
+        // Nelder-Mead as explicit extra starts.
+        const screened = [];
+        if (!warmScaled) {
+            // Kronecker sequence: one irrational stride per dimension
+            const strides = [];
+            for (let i = 0, prime = 2; i <= p + 1; prime++) {
+                let isPrime = true;
+                for (let q = 2; q * q <= prime; q++)
+                    if (prime % q === 0) {
+                        isPrime = false;
+                        break;
+                    }
+                if (!isPrime)
+                    continue;
+                strides.push(Math.sqrt(prime) % 1);
+                i++;
+            }
+            for (let s = 1; s <= 384; s++) {
+                // a0 log-uniform in [0.01, 1]·initVar
+                const a0 = initVar * Math.pow(10, ((s * strides[0]) % 1) * 2 - 2);
+                const raw = [];
+                let rawSum = 0;
+                for (let j = 1; j <= p; j++) {
+                    // ~half the lags exactly zero — spikes and gaps are in the span
+                    const u = (s * strides[j]) % 1;
+                    const v = Math.max(0, u * 2 - 1);
+                    raw.push(v);
+                    rawSum += v;
+                }
+                if (rawSum <= 0)
+                    continue;
+                const target = 0.1 + 0.85 * ((s * strides[p + 1]) % 1);
+                const w = [a0, ...raw.map(v => (v * target) / rawSum)];
+                screened.push({ d2: objectiveD2(w), w });
+            }
+            screened.sort((a, b) => a.d2 - b.d2);
+        }
+        const extraStarts = warmScaled ? [] : screened.slice(0, 3).map(c => c.w);
+        // Stage-2 OLS (RV_t ~ β₀ + β₁·σ²_t) for a given weight vector.
+        // σ²_t is built from r2[t-1..t-p], so it already IS the one-step-ahead
+        // prediction of rv[t] — pairing it with r2[t+1] (as before) calibrated
+        // β one bar off from how getForecastVarianceSeries and forecast use it.
+        // Used both to pick among D² candidates and for the final rescaling.
+        // Takes and returns normalized-space quantities (β₁ is scale-free,
+        // the caller unscales β₀); the degenerate-denominator threshold is
+        // then meaningful at any data scale.
+        const stage2 = (wScaled) => {
+            const dv = this.getVarianceSeriesInternal(unscaleWeights(wScaled));
             let sumX = 0, sumY = 0, sumXX = 0, sumXY = 0, count = 0;
-            for (let t = p; t < n - 1; t++) {
-                const x = d2Variance[t];
-                const y = r2[t + 1];
+            for (let t = p; t < n; t++) {
+                const x = dv[t] * s2;
+                const y = r2S[t];
                 sumX += x;
                 sumY += y;
                 sumXX += x * x;
@@ -1468,25 +2193,62 @@ class NoVaS {
             }
             const denom = count * sumXX - sumX * sumX;
             if (Math.abs(denom) < 1e-30)
-                throw new Error('Degenerate variance series');
+                return null;
             const beta1 = (count * sumXY - sumX * sumY) / denom;
             const beta0 = (sumY - beta1 * sumX) / count;
-            forecastWeights = [beta0, beta1];
-            // R²
             const yMean = sumY / count;
             let rss = 0, tss = 0;
-            for (let t = p; t < n - 1; t++) {
-                const yHat = beta0 + beta1 * d2Variance[t];
-                rss += (r2[t + 1] - yHat) ** 2;
-                tss += (r2[t + 1] - yMean) ** 2;
+            for (let t = p; t < n; t++) {
+                const yHat = beta0 + beta1 * dv[t] * s2;
+                rss += (r2S[t] - yHat) ** 2;
+                tss += (r2S[t] - yMean) ** 2;
+            }
+            return { beta0, beta1, rss, r2: tss > 0 ? 1 - rss / tss : 0 };
+        };
+        // D² is underdetermined: two moment conditions (skewness, kurtosis)
+        // constrain p+1 weights, so its minimum is a manifold and near-zero D²
+        // differences are sampling noise — sd of (K−3)² at n ≈ 500 is ~0.05.
+        // Run NM from the exp-decay seed and from each screened start, then
+        // among candidates within that noise floor of the best D² pick the best
+        // RV forecaster: normality identifies the set, prediction picks the point.
+        const D2_NOISE = 0.05;
+        const candidateRuns = [
+            nelderMeadMultiStart(objectiveD2, warmScaled ?? x0, { maxIter, tol, restarts: warmScaled ? 1 : 6 }),
+            ...extraStarts.map(s => nelderMead(objectiveD2, s, { maxIter, tol })),
+        ];
+        const bestD2 = Math.min(...candidateRuns.map(r => r.fx));
+        let result = candidateRuns[0];
+        let bestRss = Infinity;
+        for (const run of candidateRuns) {
+            if (run.fx > bestD2 + D2_NOISE)
+                continue;
+            const s2 = stage2(run.x.map(Math.abs));
+            const rss = s2 ? s2.rss : Infinity;
+            if (rss < bestRss || (rss === bestRss && run.fx < result.fx)) {
+                bestRss = rss;
+                result = run;
             }
-            olsR2 = tss > 0 ? 1 - rss / tss : 0;
-        }
-        catch {
-            // OLS failed — fall back to identity rescaling [0, 1]
-            forecastWeights = [0, 1];
-            olsR2 = 0;
         }
+        // Extract final weights (abs for constraint enforcement) and map the
+        // intercept back to the data scale
+        const weightsScaled = result.x.map(w => Math.abs(w));
+        const weights = unscaleWeights(weightsScaled);
+        let persistence = 0;
+        for (let j = 1; j <= p; j++)
+            persistence += weights[j];
+        const unconditionalVariance = persistence < 1 && persistence > -1
+            ? Math.max(weights[0] / (1 - persistence), 1e-20)
+            : sampleVariance(returns);
+        const annualizedVol = Math.sqrt(unconditionalVariance * this.periodsPerYear) * 100;
+        // ── Stage 2: OLS rescaling of D²-variance ──────────────
+        // RV_{t+1} = β₀ + β₁·σ²_t(D²)
+        // D² weights discover lag structure; OLS rescales for forecast accuracy.
+        // Only 2 parameters → robust on small samples with noisy per-candle RV.
+        const d2Variance = this.getVarianceSeriesInternal(weights);
+        const s2Final = stage2(weightsScaled);
+        // OLS failed (degenerate variance series) — fall back to identity rescaling
+        const forecastWeights = s2Final ? [s2Final.beta0 / s2, s2Final.beta1] : [0, 1];
+        const olsR2 = s2Final ? s2Final.r2 : 0;
         // Student-t log-likelihood for AIC comparison with GARCH/EGARCH/HAR-RV
         const df = profileStudentTDf(returns, d2Variance);
         const ll = -studentTNegLL(returns, d2Variance, df);
@@ -1635,132 +2397,967 @@ const INTERVALS_PER_YEAR = {
     '6h': 1_460,
     '8h': 1_095,
 };
+function validateInterval(interval) {
+    if (!(interval in INTERVALS_PER_YEAR)) {
+        throw new InvalidArgumentError(`Unknown interval '${interval}' — valid intervals: ${Object.keys(INTERVALS_PER_YEAR).join(', ')}`);
+    }
+}
+function validateConfidence(confidence) {
+    if (!(confidence > 0 && confidence < 1)) {
+        const hint = confidence > 1 && confidence <= 100
+            ? ` (did you pass percent? Use a fraction: ${confidence / 100})`
+            : '';
+        throw new InvalidArgumentError(`confidence must be in (0, 1), got ${confidence}${hint}`);
+    }
+}
+/**
+ * Accept both the positional form (currentPrice, confidence) and an options
+ * object — `predict(candles, '1h', { confidence: 0.9 })` cannot be confused
+ * with a price the way `predict(candles, '1h', 0.9)` can.
+ */
+function resolvePredictArgs(candles, currentPriceOrOptions, confidence) {
+    let price;
+    let conf = confidence;
+    if (currentPriceOrOptions !== null && typeof currentPriceOrOptions === 'object') {
+        price = currentPriceOrOptions.currentPrice;
+        conf = currentPriceOrOptions.confidence ?? confidence;
+    }
+    else {
+        price = currentPriceOrOptions;
+    }
+    validateConfidence(conf);
+    if (price !== null && price !== undefined) {
+        if (!(Number.isFinite(price) && price > 0)) {
+            throw new InvalidArgumentError(`currentPrice must be a positive finite number, got ${price}`);
+        }
+        return { currentPrice: price, confidence: conf };
+    }
+    return { currentPrice: candles[candles.length - 1].close, confidence: conf };
+}
 function assertMinCandles(candles, interval) {
+    validateInterval(interval);
     const min = MIN_CANDLES[interval];
     if (candles.length < min) {
-        throw new Error(`Need at least ${min} candles for ${interval} interval, got ${candles.length}`);
+        throw new NotEnoughDataError(`Need at least ${min} candles for ${interval} interval, got ${candles.length}`);
     }
-    for (let i = 0; i < candles.length; i++) {
-        const c = candles[i];
-        if (!isFinite(c.close) || c.close <= 0) {
-            throw new Error(`Invalid close price at candle ${i}: ${c.close}`);
+    validateCandles(candles);
+}
+// ── Data quality ──────────────────────────────────────────────
+/** Timestamps in ms (seconds are auto-scaled), or null when any candle lacks one. */
+function getTimestampsMs(candles) {
+    if (!candles.every(c => Number.isFinite(c.timestamp)))
+        return null;
+    return candles.map(c => (c.timestamp < 1e12 ? c.timestamp * 1000 : c.timestamp));
+}
+/** Hard failures on broken timestamp ordering — garbage-in guards for predict. */
+function assertTimestampOrder(candles) {
+    const ts = getTimestampsMs(candles);
+    if (!ts)
+        return;
+    for (let i = 1; i < ts.length; i++) {
+        if (ts[i] < ts[i - 1]) {
+            throw new BadDataError(`Candles are not sorted by timestamp (index ${i}) — sort ascending before calling. Check your data feed.`);
+        }
+        if (ts[i] === ts[i - 1]) {
+            throw new BadDataError(`Duplicate candle timestamp at index ${i} — deduplicate your data feed before calling.`);
         }
     }
+}
+function formatSpacing(ms) {
+    if (ms >= 3_600_000)
+        return `${(ms / 3_600_000).toFixed(1)}h`;
+    if (ms >= 60_000)
+        return `${(ms / 60_000).toFixed(1)}m`;
+    return `${(ms / 1000).toFixed(0)}s`;
+}
+/** Non-critical data observations appended to PredictionResult.warnings. */
+function collectDataWarnings(candles, interval, warnings) {
     const recommended = RECOMMENDED_CANDLES[interval];
-    if (candles.length < recommended) ;
-}
-function fitGarchFamily(candles, periodsPerYear, steps) {
-    // Fit all three GARCH-family models and pick the best by AIC
-    // (AIC is fair here — all three optimize the same Student-t LL)
-    const garchModel = new Garch(candles, { periodsPerYear });
-    const garchFit = garchModel.fit();
-    let bestAic = garchFit.diagnostics.aic;
-    let best = {
-        forecast: garchModel.forecast(garchFit.params, steps),
-        modelType: 'garch',
-        converged: garchFit.diagnostics.converged,
-        persistence: garchFit.params.persistence,
-        varianceSeries: garchModel.getVarianceSeries(garchFit.params),
-        returns: garchModel.getReturns(),
+    if (candles.length < recommended) {
+        warnings.push({
+            code: 'LOW_SAMPLE',
+            critical: false,
+            message: `${candles.length} candles provided; ≥${recommended} recommended for ${interval} — estimates are noisier on short samples.`,
+        });
+    }
+    const ts = getTimestampsMs(candles);
+    if (!ts || ts.length < 3)
+        return;
+    const barMs = YEAR_MS / INTERVALS_PER_YEAR[interval];
+    const spacings = [];
+    for (let i = 1; i < ts.length; i++)
+        spacings.push(ts[i] - ts[i - 1]);
+    spacings.sort((a, b) => a - b);
+    const median = spacings[Math.floor(spacings.length / 2)];
+    if (median > 0 && Math.abs(median / barMs - 1) > 0.25) {
+        warnings.push({
+            code: 'INTERVAL_MISMATCH',
+            critical: false,
+            message: `Candle spacing looks like ~${formatSpacing(median)} while interval is '${interval}' — check the interval argument.`,
+        });
+        return; // gap counting is meaningless against the wrong bar size
+    }
+    let gaps = 0;
+    for (const dt of spacings) {
+        if (dt > barMs * 1.5)
+            gaps += Math.round(dt / barMs) - 1;
+    }
+    const gapPct = (gaps / (candles.length + gaps)) * 100;
+    if (gapPct > 1) {
+        warnings.push({
+            code: 'DATA_GAPS',
+            critical: false,
+            message: `~${gaps} missing bars (${gapPct.toFixed(1)}%) detected from timestamps — the seasonal profile and lag structure may be distorted. Check your feed for outages.`,
+        });
+    }
+}
+/**
+ * Pre-flight data check with plain-language, actionable messages: run it on
+ * a new data source before wiring it into predict. Errors are conditions
+ * predict would throw on; warnings degrade quality but do not block.
+ */
+function checkData(candles, interval) {
+    validateInterval(interval);
+    const issues = [];
+    const recommended = RECOMMENDED_CANDLES[interval];
+    if (candles.length < MIN_CANDLES[interval]) {
+        issues.push({
+            code: 'TOO_FEW_CANDLES',
+            severity: 'error',
+            message: `Need at least ${MIN_CANDLES[interval]} candles for ${interval}, got ${candles.length} — fetch more history.`,
+        });
+    }
+    try {
+        validateCandles(candles);
+    }
+    catch (e) {
+        issues.push({
+            code: 'INVALID_OHLC',
+            severity: 'error',
+            message: `${e.message}. Broken OHLC usually means a feed/parsing bug — check the failing candle in your pipeline.`,
+        });
+    }
+    try {
+        assertTimestampOrder(candles);
+    }
+    catch (e) {
+        const msg = e.message;
+        issues.push({
+            code: msg.includes('Duplicate') ? 'DUPLICATE_TIMESTAMPS' : 'UNSORTED',
+            severity: 'error',
+            message: msg,
+        });
+    }
+    const soft = [];
+    collectDataWarnings(candles, interval, soft);
+    for (const w of soft) {
+        issues.push({ code: w.code, severity: 'warning', message: w.message });
+    }
+    let flat = 0;
+    for (const c of candles) {
+        if (c.high === c.low)
+            flat++;
+    }
+    const flatPct = (flat / Math.max(candles.length, 1)) * 100;
+    if (flatPct > 20) {
+        issues.push({
+            code: 'FLAT_CANDLES',
+            severity: 'warning',
+            message: `${flatPct.toFixed(0)}% of candles have high === low — range-based estimators degrade to squared returns. Synthetic or illiquid feed?`,
+        });
+    }
+    return {
+        ok: !issues.some(i => i.severity === 'error'),
+        issues,
+        recommendedCandles: recommended,
     };
-    const egarchModel = new Egarch(candles, { periodsPerYear });
-    const egarchFit = egarchModel.fit();
-    if (egarchFit.diagnostics.aic < bestAic) {
-        bestAic = egarchFit.diagnostics.aic;
-        best = {
-            forecast: egarchModel.forecast(egarchFit.params, steps),
-            modelType: 'egarch',
-            converged: egarchFit.diagnostics.converged,
-            persistence: egarchFit.params.persistence,
-            varianceSeries: egarchModel.getVarianceSeries(egarchFit.params),
-            returns: egarchModel.getReturns(),
-        };
+}
+// ── Intraday seasonality ──────────────────────────────────────
+const DAY_MS = 86_400_000;
+const YEAR_MS = 31_536_000_000;
+/**
+ * Diurnal variance profile from per-candle Parkinson RV.
+ *
+ * Intraday markets have a strong time-of-day volatility pattern (sessions,
+ * funding, weekends). A GARCH-family fit smears it into average persistence,
+ * so corridors are systematically too narrow in active hours and too wide in
+ * quiet ones. Factors are estimated per intraday bucket (≤24 per day, bars
+ * grouped for sub-hour intervals), circularly smoothed, shrunk toward 1 by
+ * bucket support, and gated by a χ² significance test against the RV
+ * sampling noise (inflated for volatility clustering) — pure-GARCH data
+ * without seasonality returns null and the pipeline is unchanged.
+ *
+ * Timestamps (ms or s), when present on every candle, anchor buckets to
+ * real time of day and survive gaps; otherwise buckets are positional and
+ * assume contiguous bars.
+ */
+function computeSeasonality(candles, interval) {
+    const periodsPerYear = INTERVALS_PER_YEAR[interval];
+    const barsPerDay = Math.round(periodsPerYear / 365);
+    if (barsPerDay < 3)
+        return null;
+    const buckets = Math.min(24, barsPerDay);
+    const returns = calculateReturns(candles);
+    const rv = perCandleParkinson(candles, returns);
+    const n = returns.length;
+    const nCandles = candles.length;
+    const hasTs = candles.every(c => Number.isFinite(c.timestamp));
+    const ts = hasTs
+        ? candles.map(c => (c.timestamp < 1e12 ? c.timestamp * 1000 : c.timestamp))
+        : null;
+    const barMs = YEAR_MS / periodsPerYear;
+    const bucketOfReturn = (t) => {
+        const i = t + 1;
+        if (ts) {
+            const time = i < nCandles ? ts[i] : ts[nCandles - 1] + (i - (nCandles - 1)) * barMs;
+            return Math.min(buckets - 1, Math.floor(((time % DAY_MS) / DAY_MS) * buckets));
+        }
+        return Math.min(buckets - 1, Math.floor(((i % barsPerDay) / barsPerDay) * buckets));
+    };
+    // Work in log-RV: per-observation RV is heavy-tailed, so level means are
+    // dominated by single prints while log means have modest, comparable
+    // variance across buckets. Bucket ratios of geometric means equal
+    // variance ratios up to a constant (identical noise shape per bucket),
+    // which the normalization below removes anyway.
+    const logSums = new Array(buckets).fill(0);
+    const counts = new Array(buckets).fill(0);
+    let totalLog = 0;
+    let totalCount = 0;
+    for (let t = 0; t < n; t++) {
+        if (!(rv[t] > 0))
+            continue;
+        const b = bucketOfReturn(t);
+        const lv = Math.log(rv[t]);
+        logSums[b] += lv;
+        counts[b]++;
+        totalLog += lv;
+        totalCount++;
+    }
+    // Every bucket needs support — a sample that does not cover the day
+    // (e.g. 500 one-minute candles) cannot identify a diurnal profile
+    if (totalCount < buckets * 5 || counts.some(c => c < 5))
+        return null;
+    const overallLog = totalLog / totalCount;
+    let varLog = 0;
+    for (let t = 0; t < n; t++) {
+        if (!(rv[t] > 0))
+            continue;
+        varLog += (Math.log(rv[t]) - overallLog) ** 2;
     }
-    const gjrModel = new GjrGarch(candles, { periodsPerYear });
-    const gjrFit = gjrModel.fit();
-    if (gjrFit.diagnostics.aic < bestAic) {
-        best = {
-            forecast: gjrModel.forecast(gjrFit.params, steps),
-            modelType: 'gjr-garch',
-            converged: gjrFit.diagnostics.converged,
-            persistence: gjrFit.params.persistence,
-            varianceSeries: gjrModel.getVarianceSeries(gjrFit.params),
-            returns: gjrModel.getReturns(),
-        };
+    varLog /= totalCount;
+    if (!(varLog > 0))
+        return null;
+    // Significance gate: χ² of bucket log-means against their sampling noise.
+    // The per-observation variance is inflated ×2.25 (≈1.5² for volatility
+    // clustering shrinking the effective sample), so the diurnal profile of
+    // pure noise does not trigger deseasonalization.
+    const rawLog = logSums.map((s, b) => s / counts[b] - overallLog);
+    let chi2 = 0;
+    for (let b = 0; b < buckets; b++) {
+        chi2 += (counts[b] * rawLog[b] * rawLog[b]) / (varLog * 2.25);
+    }
+    const pValue = chi2Survival(chi2, buckets - 1);
+    const smoothedLog = rawLog.map((_, b) => 0.25 * rawLog[(b + buckets - 1) % buckets] + 0.5 * rawLog[b] + 0.25 * rawLog[(b + 1) % buckets]);
+    // Shrink toward 0 by bucket support so thin buckets cannot inject noise.
+    // The prior is light (5 pseudo-obs): the χ² gate is the real protection
+    // against fitting noise, and a heavy prior halves genuine profiles on
+    // realistic windows (~17 obs/bucket), leaving residual seasonality.
+    let factors = smoothedLog.map((v, b) => Math.exp(v * (counts[b] / (counts[b] + 5))));
+    // Sample-weighted normalization keeps the overall variance level unchanged
+    let m = 0;
+    for (let t = 0; t < n; t++)
+        m += factors[bucketOfReturn(t)];
+    m /= n;
+    factors = factors.map(v => v / m);
+    const ratio = Math.max(...factors) / Math.min(...factors);
+    if (ratio < 1.25 || pValue > 0.01)
+        return null;
+    return { factors, bucketOfReturn };
+}
+/**
+ * Rescale each candle's log-moves by 1/√f(bucket) so the deseasonalized
+ * series has a flat diurnal profile. Gaps (open vs prev close) are scaled
+ * with the same factor; OHLC ordering is preserved (monotone log map).
+ */
+function deseasonalizeCandles(candles, season) {
+    const out = [candles[0]];
+    let close = candles[0].close;
+    for (let t = 0; t < candles.length - 1; t++) {
+        const c = candles[t + 1];
+        const prevOriginalClose = candles[t].close;
+        const g = 1 / Math.sqrt(season.factors[season.bucketOfReturn(t)]);
+        const open = close * Math.pow(c.open / prevOriginalClose, g);
+        const newClose = open * Math.pow(c.close / c.open, g);
+        const high = open * Math.pow(c.high / c.open, g);
+        const low = open * Math.pow(c.low / c.open, g);
+        out.push({ ...c, open, high, low, close: newClose });
+        close = newClose;
+    }
+    return out;
+}
+/**
+ * Candidate HAR lag triples for this interval and sample size.
+ *
+ * The textbook (1, 5, 22) encodes *daily equity* horizons (day/week/month
+ * in trading days) and is wrong for intraday 24/7 markets. Candidates are
+ * built from the candle interval itself — one bar / one day / one week in
+ * bars — capped by what the sample can support (long lag ≤ n/5 and enough
+ * rows for the OLS). The final choice among candidates is made by QLIKE
+ * on the out-of-sample region, not by convention.
+ */
+function selectHarLagCandidates(nReturns, periodsPerYear) {
+    const maxLong = Math.floor(Math.min(nReturns / 5, nReturns - 31));
+    const candidates = [];
+    if (maxLong >= 22)
+        candidates.push([1, 5, 22]);
+    const barsPerDay = Math.round(periodsPerYear / 365);
+    if (barsPerDay >= 3) {
+        const barsPerWeek = 7 * barsPerDay;
+        if (barsPerWeek <= maxLong) {
+            candidates.push([1, barsPerDay, barsPerWeek]);
+        }
+        else if (barsPerDay * 2 <= maxLong) {
+            // Week does not fit the sample — use the longest supported horizon
+            candidates.push([1, barsPerDay, maxLong]);
+        }
     }
-    return best;
+    if (candidates.length === 0) {
+        // Tiny sample: geometric spacing within what the data supports
+        const long = Math.max(3, maxLong);
+        candidates.push([1, Math.max(2, Math.round(Math.sqrt(long))), long]);
+    }
+    // Dedupe
+    return candidates.filter((c, i) => candidates.findIndex(d => d[0] === c[0] && d[1] === c[1] && d[2] === c[2]) === i);
+}
+/**
+ * NoVaS lag order grown with the sample (~n^(1/3), the standard
+ * lag-order rate), instead of a fixed p = 10. Anchored to p = 10 at
+ * n ≈ 500 (where a far-lag ARCH(10) ground truth is recovered best);
+ * adapts down for short samples, up for long ones.
+ */
+function adaptiveNovasLags(nReturns) {
+    return Math.min(20, Math.max(5, Math.round(1.26 * Math.cbrt(nReturns))));
 }
-function fitHarRv(candles, periodsPerYear, steps) {
+/**
+ * Empirical variance-scale correction.
+ *
+ * RV-based models (HAR-RV, NoVaS) forecast Parkinson realized variance,
+ * which is NOT the same quantity as the close-to-close return variance the
+ * price corridor needs — range-based RV is systematically smaller whenever
+ * moves happen between closes (gaps, thin wicks). The corridor must satisfy
+ * Var(r_t / σ_t) = 1, so rescale by c = E[r²/σ²] measured on the sample.
+ *
+ * For MLE-calibrated GARCH-family fits c ≈ 1 (the likelihood already
+ * self-calibrates the level), so this is a no-op there.
+ *
+ * z² is capped at 50 to keep a single extreme print from distorting the
+ * scale (bias of the cap is <2% even at df = 5).
+ *
+ * `warmup` is the combination's own structural warm-up (longest lag /
+ * seeding region), not a fixed constant.
+ */
+function varianceScaleCorrection(returns, varianceSeries, warmup) {
+    let sum = 0;
+    let count = 0;
+    for (let i = warmup; i < returns.length; i++) {
+        const v = varianceSeries[i];
+        if (!(v > 0) || !isFinite(v))
+            continue;
+        const z2 = (returns[i] * returns[i]) / v;
+        if (!isFinite(z2))
+            continue;
+        sum += Math.min(z2, 50);
+        count++;
+    }
+    if (count < 30)
+        return 1;
+    const c = sum / count;
+    if (!isFinite(c) || c <= 0)
+        return 1;
+    // Sanity clamp: beyond this the fit is garbage and `reliable` flags it
+    return Math.min(100, Math.max(0.01, c));
+}
+function applyScale(fit, c, periodsPerYear) {
+    if (c === 1)
+        return;
+    fit.varianceSeries = fit.varianceSeries.map(v => v * c);
+    const variance = fit.forecast.variance.map(v => v * c);
+    fit.forecast = {
+        variance,
+        volatility: variance.map(v => Math.sqrt(v)),
+        annualized: variance.map(v => Math.sqrt(v * periodsPerYear) * 100),
+    };
+    // simMembers stay on the model scale on purpose: the simulated corridor
+    // multiplier is a standardized ratio, so a uniform scale c cancels.
+}
+const OOS_TRAIN_RATIO = 0.75;
+/**
+ * Fit all candidate models, score them by out-of-sample QLIKE, and combine.
+ *
+ * Candidates are calibrated on the first 75% of the sample and their
+ * one-step variance forecasts scored by QLIKE on the held-out 25% —
+ * in-sample QLIKE favors the OLS-calibrated models (HAR, NoVaS stage 2)
+ * exactly as much as they overfit. Final parameters are refitted on the
+ * full sample.
+ *
+ * Combination instead of selection: n·QLIKE behaves like a deviance, so
+ * weights w ∝ exp(−0.5·n_eval·ΔQLIKE) collapse to the winner when the gap
+ * is decisive and average when candidates are within noise of each other
+ * (forecast combination robustly beats picking one model on short samples).
+ */
+/** Forgetting factor of the adaptive GARCH candidate (half-life ≈ 69 bars). */
+const FORGET_LAMBDA = 0.99;
+function fitModel(candles, periodsPerYear, steps, warm) {
+    const returns = calculateReturns(candles);
+    const rv = perCandleParkinson(candles, returns);
+    const nReturns = returns.length;
+    const nTrain = Math.floor(candles.length * OOS_TRAIN_RATIO);
+    const trainCandles = candles.slice(0, nTrain);
+    const evalStart = nTrain - 1; // first out-of-sample index in return space
+    const nEval = nReturns - evalStart;
+    const members = [];
+    // ── GARCH (λ = 1) and adaptive GARCH (exponential forgetting) ──
+    // Two candidates from the same recursion: the forgetting variant tracks
+    // regime shifts, the plain one wins on stationary stretches — the OOS
+    // score decides which regime the data is in.
+    for (const forgetting of [1, FORGET_LAMBDA]) {
+        try {
+            const warmStart = forgetting === 1 ? warm?.garch : warm?.garchForget;
+            const trainFit = new Garch(trainCandles, { periodsPerYear }).fit({ forgetting, warmStart });
+            const model = new Garch(candles, { periodsPerYear });
+            const oos = qlike(model.getVarianceSeries(trainFit.params).slice(evalStart), rv.slice(evalStart));
+            const fit = model.fit({ forgetting, warmStart });
+            const fc = model.forecast(fit.params, steps);
+            if (warm) {
+                if (forgetting === 1)
+                    warm.garch = fit.params;
+                else
+                    warm.garchForget = fit.params;
+            }
+            members.push({
+                modelType: 'garch',
+                varianceSeries: model.getVarianceSeries(fit.params),
+                forecast: fc,
+                persistence: fit.params.persistence,
+                converged: fit.diagnostics.converged,
+                warmup: 0,
+                oosQlike: oos,
+                weight: 0,
+                sim: { kind: 'garch', weight: 0, omega: fit.params.omega, alpha: fit.params.alpha, gamma: 0, beta: fit.params.beta, v1: fc.variance[0] },
+            });
+        }
+        catch { /* degenerate data — other members cover */ }
+    }
+    // ── EGARCH ──
     try {
-        const model = new HarRv(candles, { periodsPerYear });
-        const fit = model.fit();
-        // Skip HAR-RV if persistence >= 1 (non-stationary) or R² too low
-        if (fit.params.persistence >= 1 || fit.params.r2 < 0)
-            return null;
-        return {
-            forecast: model.forecast(fit.params, steps),
-            modelType: 'har-rv',
+        const trainFit = new Egarch(trainCandles, { periodsPerYear }).fit({ warmStart: warm?.egarch });
+        const model = new Egarch(candles, { periodsPerYear });
+        const oos = qlike(model.getVarianceSeries(trainFit.params).slice(evalStart), rv.slice(evalStart));
+        const fit = model.fit({ warmStart: warm?.egarch });
+        const fc = model.forecast(fit.params, steps);
+        if (warm)
+            warm.egarch = fit.params;
+        members.push({
+            modelType: 'egarch',
+            varianceSeries: model.getVarianceSeries(fit.params),
+            forecast: fc,
+            persistence: fit.params.persistence,
             converged: fit.diagnostics.converged,
+            warmup: 0,
+            oosQlike: oos,
+            weight: 0,
+            sim: {
+                kind: 'egarch',
+                weight: 0,
+                omega: fit.params.omega,
+                alpha: fit.params.alpha,
+                gamma: fit.params.gamma,
+                beta: fit.params.beta,
+                logv1: Math.log(Math.max(fc.variance[0], 1e-300)),
+                eAbsZ: expectedAbsStudentT(fit.params.df),
+                mbar: model.magnitudeDrift(fit.params),
+            },
+        });
+    }
+    catch { /* degenerate data */ }
+    // ── GJR-GARCH ──
+    try {
+        const trainFit = new GjrGarch(trainCandles, { periodsPerYear }).fit({ warmStart: warm?.gjr });
+        const model = new GjrGarch(candles, { periodsPerYear });
+        const oos = qlike(model.getVarianceSeries(trainFit.params).slice(evalStart), rv.slice(evalStart));
+        const fit = model.fit({ warmStart: warm?.gjr });
+        const fc = model.forecast(fit.params, steps);
+        if (warm)
+            warm.gjr = fit.params;
+        members.push({
+            modelType: 'gjr-garch',
+            varianceSeries: model.getVarianceSeries(fit.params),
+            forecast: fc,
             persistence: fit.params.persistence,
+            converged: fit.diagnostics.converged,
+            warmup: 0,
+            oosQlike: oos,
+            weight: 0,
+            sim: { kind: 'garch', weight: 0, omega: fit.params.omega, alpha: fit.params.alpha, gamma: fit.params.gamma, beta: fit.params.beta, v1: fc.variance[0] },
+        });
+    }
+    catch { /* degenerate data */ }
+    // ── Realized GARCH ──
+    try {
+        const trainFit = new RealizedGarch(trainCandles, { periodsPerYear }).fit({ warmStart: warm?.rgarch });
+        const model = new RealizedGarch(candles, { periodsPerYear });
+        const oos = qlike(model.getVarianceSeries(trainFit.params).slice(evalStart), rv.slice(evalStart));
+        const fit = model.fit({ warmStart: warm?.rgarch });
+        const fc = model.forecast(fit.params, steps);
+        if (warm)
+            warm.rgarch = fit.params;
+        members.push({
+            modelType: 'realized-garch',
             varianceSeries: model.getVarianceSeries(fit.params),
-            returns: model.getReturns(),
-        };
+            forecast: fc,
+            persistence: fit.params.persistence,
+            converged: fit.diagnostics.converged,
+            warmup: 0,
+            oosQlike: oos,
+            weight: 0,
+            sim: {
+                kind: 'rgarch',
+                weight: 0,
+                omega: fit.params.omega,
+                beta: fit.params.beta,
+                gamma: fit.params.gamma,
+                xi: fit.params.xi,
+                tau1: fit.params.tau1,
+                tau2: fit.params.tau2,
+                sigmaU: fit.params.sigmaU,
+                logv1: Math.log(Math.max(fc.variance[0], 1e-300)),
+            },
+        });
     }
-    catch {
-        return null;
+    catch { /* degenerate data */ }
+    // ── HAR-RV (lag triple AND level/log spec chosen by the same OOS score) ──
+    try {
+        let bestLags = null;
+        let bestLog = false;
+        let bestScore = Infinity;
+        // Warm state pins the previously selected configuration — a spec search
+        // per rolling refit would mostly rediscover the same one
+        const lagCandidates = warm?.harLags
+            ? [warm.harLags]
+            : selectHarLagCandidates(nTrain - 1, periodsPerYear);
+        const specCandidates = warm?.harLags ? [warm.harLog ?? false] : [false, true];
+        for (const [shortLag, mediumLag, longLag] of lagCandidates) {
+            for (const logSpec of specCandidates) {
+                try {
+                    const trainFit = new HarRv(trainCandles, { periodsPerYear, shortLag, mediumLag, longLag, logSpec }).fit();
+                    if (trainFit.params.persistence >= 1 || trainFit.params.r2 < 0)
+                        continue;
+                    const full = new HarRv(candles, { periodsPerYear, shortLag, mediumLag, longLag, logSpec });
+                    const score = qlike(full.getVarianceSeries(trainFit.params).slice(evalStart), rv.slice(evalStart));
+                    if (score < bestScore) {
+                        bestScore = score;
+                        bestLags = [shortLag, mediumLag, longLag];
+                        bestLog = logSpec;
+                    }
+                }
+                catch {
+                    continue;
+                }
+            }
+        }
+        if (bestLags) {
+            const [shortLag, mediumLag, longLag] = bestLags;
+            const model = new HarRv(candles, { periodsPerYear, shortLag, mediumLag, longLag, logSpec: bestLog });
+            const fit = model.fit();
+            if (fit.params.persistence < 1 && fit.params.r2 >= 0) {
+                const fc = model.forecast(fit.params, steps);
+                if (warm) {
+                    warm.harLags = bestLags;
+                    warm.harLog = bestLog;
+                }
+                members.push({
+                    modelType: 'har-rv',
+                    varianceSeries: model.getVarianceSeries(fit.params),
+                    forecast: fc,
+                    persistence: fit.params.persistence,
+                    converged: fit.diagnostics.converged,
+                    warmup: longLag,
+                    oosQlike: bestScore,
+                    weight: 0,
+                    sim: { kind: 'flat', weight: 0, path: fc.variance },
+                });
+            }
+        }
     }
-}
-function fitNoVaS(candles, periodsPerYear, steps) {
+    catch { /* degenerate data */ }
+    // ── NoVaS ──
     try {
-        const model = new NoVaS(candles, { periodsPerYear });
-        const fit = model.fit();
-        // Skip if persistence >= 1 (non-stationary)
-        if (fit.params.persistence >= 1)
-            return null;
-        return {
-            forecast: model.forecast(fit.params, steps),
-            modelType: 'novas',
-            converged: fit.diagnostics.converged,
-            persistence: fit.params.persistence,
-            varianceSeries: model.getForecastVarianceSeries(fit.params),
-            returns: model.getReturns(),
-        };
+        const lags = adaptiveNovasLags(nReturns);
+        const warmWeights = warm?.novasWeights && warm.novasWeights.length === lags + 1
+            ? warm.novasWeights
+            : undefined;
+        const trainFit = new NoVaS(trainCandles, { periodsPerYear, lags }).fit({ warmWeights });
+        if (trainFit.params.persistence < 1) {
+            const model = new NoVaS(candles, { periodsPerYear, lags });
+            const oos = qlike(model.getForecastVarianceSeries(trainFit.params).slice(evalStart), rv.slice(evalStart));
+            const fit = model.fit({ warmWeights });
+            if (fit.params.persistence < 1) {
+                const fc = model.forecast(fit.params, steps);
+                if (warm)
+                    warm.novasWeights = fit.params.weights;
+                members.push({
+                    modelType: 'novas',
+                    varianceSeries: model.getForecastVarianceSeries(fit.params),
+                    forecast: fc,
+                    persistence: fit.params.persistence,
+                    converged: fit.diagnostics.converged,
+                    warmup: lags,
+                    oosQlike: oos,
+                    weight: 0,
+                    sim: { kind: 'flat', weight: 0, path: fc.variance },
+                });
+            }
+        }
     }
-    catch {
-        return null;
+    catch { /* degenerate data */ }
+    if (members.length === 0) {
+        throw new Error('All volatility models failed to fit');
+    }
+    // ── Weights from OOS QLIKE ──
+    const finiteScores = members.map(m => m.oosQlike).filter(q => isFinite(q));
+    const qmin = finiteScores.length > 0 ? Math.min(...finiteScores) : NaN;
+    let wsum = 0;
+    for (const m of members) {
+        const d = isFinite(m.oosQlike) && isFinite(qmin) ? m.oosQlike - qmin : isFinite(qmin) ? Infinity : 0;
+        m.weight = Math.exp(-0.5 * nEval * d);
+        wsum += m.weight;
+    }
+    for (const m of members)
+        m.weight /= wsum;
+    const kept = members.filter(m => m.weight >= 0.02);
+    const keptSum = kept.reduce((s, m) => s + m.weight, 0);
+    for (const m of kept)
+        m.weight /= keptSum;
+    const top = kept.reduce((a, b) => (b.weight > a.weight ? b : a));
+    // ── Combine ──
+    const combinedSeries = new Array(nReturns).fill(0);
+    for (const m of kept) {
+        for (let i = 0; i < nReturns; i++)
+            combinedSeries[i] += m.weight * m.varianceSeries[i];
+    }
+    const combinedVariance = new Array(steps).fill(0);
+    for (const m of kept) {
+        for (let h = 0; h < steps; h++)
+            combinedVariance[h] += m.weight * m.forecast.variance[h];
+    }
+    const best = {
+        forecast: {
+            variance: combinedVariance,
+            volatility: combinedVariance.map(v => Math.sqrt(v)),
+            annualized: combinedVariance.map(v => Math.sqrt(v * periodsPerYear) * 100),
+        },
+        modelType: top.modelType,
+        converged: top.converged,
+        persistence: top.persistence,
+        varianceSeries: combinedSeries,
+        returns,
+        df: 5,
+        warmup: Math.max(...kept.map(m => m.warmup)),
+        zSorted: [],
+        simMembers: kept.map(m => ({ ...m.sim, weight: m.weight })),
+        weights: kept.reduce((acc, m) => {
+            acc[m.modelType] = (acc[m.modelType] ?? 0) + m.weight;
+            return acc;
+        }, {}),
+    };
+    // Calibrate the combination to the return scale: QLIKE picks the best RV
+    // forecasters, but the corridor needs the return-variance scale.
+    // Warm-up comes from the combination's own structure (its longest lag /
+    // seeding region), capped so calibration keeps a usable sample.
+    const warmup = Math.min(Math.max(best.warmup, 10), Math.floor(nReturns / 4));
+    best.warmup = warmup;
+    const c = varianceScaleCorrection(best.returns, best.varianceSeries, warmup);
+    applyScale(best, c, periodsPerYear);
+    // Re-profile tail thickness on the corrected residuals — this df drives
+    // the model half of the corridor quantile.
+    best.df = profileStudentTDf(best.returns, best.varianceSeries);
+    // Empirical calibration sample: signed z_t of the corrected residuals —
+    // the two tails are calibrated separately (return distributions are
+    // skewed; folding them into |z| hides that)
+    const zs = [];
+    for (let i = warmup; i < nReturns; i++) {
+        const v = best.varianceSeries[i];
+        if (!(v > 0) || !isFinite(v))
+            continue;
+        const z = best.returns[i] / Math.sqrt(v);
+        if (isFinite(z))
+            zs.push(z);
     }
+    zs.sort((a, b) => a - b);
+    best.zSorted = zs;
+    return best;
 }
-function fitModel(candles, periodsPerYear, steps) {
-    const garchResult = fitGarchFamily(candles, periodsPerYear, steps);
-    const harResult = fitHarRv(candles, periodsPerYear, steps);
-    const novasResult = fitNoVaS(candles, periodsPerYear, steps);
-    // Compute realized variance (Parkinson RV) for QLIKE scoring
-    const returns = calculateReturns(candles);
-    const rv = perCandleParkinson(candles, returns);
-    // Pick model with lowest QLIKE (Patton 2011) — neutral forecast-error metric.
-    // Unlike AIC (which favors MLE-calibrated models), QLIKE judges only
-    // how well the variance series predicts realized variance.
-    let best = garchResult;
-    let bestScore = qlike(garchResult.varianceSeries, rv);
-    if (harResult) {
-        const score = qlike(harResult.varianceSeries, rv);
-        if (score < bestScore) {
-            best = harResult;
-            bestScore = score;
+// ── Model-implied horizon quantile by simulation ──────────────
+function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a |= 0;
+        a = (a + 0x6d2b79f5) | 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+function simRandn(rng) {
+    const u1 = Math.max(rng(), 1e-12);
+    const u2 = rng();
+    return Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
+}
+// Horizon-simulation sizing: two tails × SIM_TAIL_DRAWS target samples,
+// bounded from both sides, with a hard cap on total work (B·steps).
+const SIM_TAIL_DRAWS = 200;
+const SIM_MIN_DRAWS = 500;
+const SIM_MAX_DRAWS = 40_000;
+const SIM_WORK_BUDGET = 20_000_000;
+/**
+ * Marsaglia–Tsang gamma sampler (shape a ≥ 1).
+ *
+ * Rejection sampling accepts >96% of proposals for a ≥ 1, so the caps are
+ * never reached on valid inputs — they are a hard termination guarantee:
+ * a NaN slipping into the parameters would otherwise make every accept
+ * condition false and spin both loops forever.
+ */
+function gammaSample(a, rng) {
+    const d = a - 1 / 3;
+    const c = 1 / Math.sqrt(9 * d);
+    for (let iter = 0; iter < 100; iter++) {
+        let x = simRandn(rng);
+        let v = 1 + c * x;
+        for (let inner = 0; inner < 100 && v <= 0; inner++) {
+            x = simRandn(rng);
+            v = 1 + c * x;
         }
+        if (!(v > 0))
+            break;
+        v = v * v * v;
+        const u = rng();
+        if (u < 1 - 0.0331 * x * x * x * x)
+            return d * v;
+        if (Math.log(u) < 0.5 * x * x + d * (1 - v + Math.log(v)))
+            return d * v;
+    }
+    // Degrades a single draw to the distribution mean — never hangs
+    return a;
+}
+/** Sampler for standardized (unit-variance) Student-t(df); Gaussian for df > 100. */
+function makeTSampler(df, rng) {
+    if (!isFinite(df) || df > 100)
+        return () => simRandn(rng);
+    const scale = Math.sqrt((df - 2) / df);
+    return () => {
+        const chi2 = 2 * gammaSample(df / 2, rng);
+        return (simRandn(rng) / Math.sqrt(chi2 / df)) * scale;
+    };
+}
+/**
+ * Model-implied h-step standardized-sum tail quantiles by simulation
+ * through the fitted recursions (mixture across combination members).
+ *
+ * Replaces the old zGauss + (zT − zGauss)/h interpolation: simulation
+ * captures volatility feedback within the horizon (a shock raises later
+ * σ's), the seasonal σ-path weighting, and the CLT decay of fat tails —
+ * all of which the linear interpolation only approximated. Sums are kept
+ * signed, so leverage (γ in GJR/EGARCH, τ₁ in Realized GARCH) produces
+ * genuinely asymmetric tails. Innovations are standardized t(df) draws
+ * with the profiled df; the seed is fixed so results are deterministic.
+ */
+function simulateHorizonTails(fit, steps, confidence, factorPath) {
+    const members = fit.simMembers;
+    if (!members || members.length === 0)
+        return null;
+    const f = factorPath && factorPath.length >= steps ? factorPath : new Array(steps).fill(1);
+    const rng = mulberry32(0x5eed1e55);
+    const drawZ = makeTSampler(fit.df, rng);
+    // Draw count: enough that each requested tail holds ≥ SIM_TAIL_DRAWS
+    // samples, clamped so B·steps never exceeds SIM_WORK_BUDGET path-steps —
+    // runtime stays bounded no matter what horizon or confidence is asked.
+    const B = Math.max(SIM_MIN_DRAWS, Math.min(SIM_MAX_DRAWS, Math.ceil((2 * SIM_TAIL_DRAWS) / Math.max(1 - confidence, 1e-4)), Math.floor(SIM_WORK_BUDGET / steps)));
+    const cum = [];
+    let acc = 0;
+    for (const m of members) {
+        acc += m.weight;
+        cum.push(acc);
+    }
+    const draws = new Array(B);
+    for (let b = 0; b < B; b++) {
+        const u = rng() * acc;
+        let mi = 0;
+        while (mi < cum.length - 1 && u > cum[mi])
+            mi++;
+        const m = members[mi];
+        let num = 0;
+        let den = 0;
+        if (m.kind === 'flat') {
+            for (let j = 0; j < steps; j++) {
+                const v = m.path[Math.min(j, m.path.length - 1)] * f[j];
+                if (!(v > 0))
+                    continue;
+                num += Math.sqrt(v) * drawZ();
+                den += v;
+            }
+        }
+        else if (m.kind === 'egarch') {
+            let lv = m.logv1;
+            for (let j = 0; j < steps; j++) {
+                const v = Math.exp(lv) * f[j];
+                const z = drawZ();
+                num += Math.sqrt(v) * z;
+                den += v;
+                lv = m.omega + m.alpha * (Math.abs(z) + m.mbar - m.eAbsZ) + m.gamma * z + m.beta * lv;
+                lv = Math.max(-50, Math.min(50, lv));
+            }
+        }
+        else if (m.kind === 'rgarch') {
+            let lv = m.logv1;
+            for (let j = 0; j < steps; j++) {
+                const v = Math.exp(lv) * f[j];
+                const z = drawZ();
+                num += Math.sqrt(v) * z;
+                den += v;
+                const lnRvSim = m.xi + lv + m.tau1 * z + m.tau2 * (z * z - 1) + m.sigmaU * simRandn(rng);
+                lv = m.omega + m.beta * lv + m.gamma * lnRvSim;
+                lv = Math.max(-50, Math.min(50, lv));
+            }
+        }
+        else {
+            let v = m.v1;
+            for (let j = 0; j < steps; j++) {
+                const vf = v * f[j];
+                const z = drawZ();
+                num += Math.sqrt(vf) * z;
+                den += vf;
+                const innov = v * z * z;
+                v = m.omega + m.alpha * innov + (z < 0 ? m.gamma * innov : 0) + m.beta * v;
+                if (!(v > 0) || !isFinite(v))
+                    v = m.v1;
+            }
+        }
+        draws[b] = den > 0 ? num / Math.sqrt(den) : 0;
     }
-    if (novasResult) {
-        const score = qlike(novasResult.varianceSeries, rv);
-        if (score < bestScore) {
-            best = novasResult;
-            bestScore = score;
+    draws.sort((a, b) => a - b);
+    const pTail = (1 - confidence) / 2;
+    const up = empiricalQuantile(draws, 1 - pTail);
+    const down = -empiricalQuantile(draws, pTail);
+    if (!isFinite(up) || !isFinite(down) || up <= 0 || down <= 0)
+        return null;
+    return { up, down };
+}
+/**
+ * Signed h-step standardized-sum sample: Σr / √(Σσ²) over overlapping
+ * windows of the post-warm-up region. This is the h-step analog of
+ * fit.zSorted — it absorbs whatever the single-period model misses about
+ * aggregation (volatility autocorrelation, Jensen bias in EGARCH
+ * multi-step, fat tails washing out by CLT), separately per tail.
+ */
+function horizonZ(fit, steps) {
+    const { returns, varianceSeries, warmup } = fit;
+    const out = [];
+    for (let t = warmup; t + steps <= returns.length; t++) {
+        let sumR = 0;
+        let sumV = 0;
+        let ok = true;
+        for (let j = 0; j < steps; j++) {
+            const v = varianceSeries[t + j];
+            if (!(v > 0) || !isFinite(v)) {
+                ok = false;
+                break;
+            }
+            sumR += returns[t + j];
+            sumV += v;
         }
+        if (!ok)
+            continue;
+        const z = sumR / Math.sqrt(sumV);
+        if (isFinite(z))
+            out.push(z);
     }
-    return best;
+    out.sort((a, b) => a - b);
+    return out;
 }
-function checkReliable(fit) {
-    if (!fit.converged || fit.persistence >= 0.999)
-        return false;
+/**
+ * Corridor multipliers (upper and lower, calibrated separately) for a
+ * two-sided confidence level at horizon `steps`.
+ *
+ * Each tail carries (1−confidence)/2 mass. The empirical quantile of the
+ * signed standardized (h-step) return anchors each tail where the sample
+ * supports it, and the model quantile takes over as that tail runs out of
+ * observations. The blend weight per tail is the expected number of tail
+ * exceedances m = n_eff·(1−confidence)/2 shrunk by a prior of 5 pseudo-
+ * observations; overlapping h-step windows are discounted by 1/steps.
+ *
+ * The model half is the (symmetric) fitted t(df) quantile at one step and
+ * the simulated model-implied tails (simulateHorizonTails — asymmetric
+ * through the fitted leverage terms) at longer horizons.
+ */
+function corridorZBounds(fit, confidence, steps = 1, factorPath) {
+    const zGauss = probit(confidence);
+    const zT = studentTProbit(confidence, fit.df);
+    let modelUp;
+    let modelDown;
+    if (steps === 1) {
+        modelUp = zT;
+        modelDown = zT;
+    }
+    else {
+        const sim = simulateHorizonTails(fit, steps, confidence, factorPath);
+        const fallback = zGauss + (zT - zGauss) / steps;
+        modelUp = sim ? sim.up : fallback;
+        modelDown = sim ? sim.down : fallback;
+    }
+    const zs = steps === 1 ? fit.zSorted : horizonZ(fit, steps);
+    const n = zs.length;
+    if (n < 50)
+        return { up: modelUp, down: modelDown };
+    const pTail = (1 - confidence) / 2;
+    const empUp = empiricalQuantile(zs, 1 - pTail);
+    const empDown = -empiricalQuantile(zs, pTail);
+    const effN = n / steps; // overlap discount
+    const tailCount = effN * pTail;
+    const w = tailCount / (tailCount + 5);
+    const up = isFinite(empUp) && empUp > 0 ? w * empUp + (1 - w) * modelUp : modelUp;
+    const down = isFinite(empDown) && empDown > 0 ? w * empDown + (1 - w) * modelDown : modelDown;
+    return { up, down };
+}
+/** Reliability checks as explainable warnings; `reliable` = none critical fired. */
+function collectFitWarnings(fit, warnings) {
+    if (!fit.converged) {
+        warnings.push({
+            code: 'NOT_CONVERGED',
+            critical: true,
+            message: 'The volatility optimizer did not converge — the corridor cannot be trusted. More candles usually helps.',
+        });
+    }
+    if (fit.persistence >= 0.999) {
+        warnings.push({
+            code: 'HIGH_PERSISTENCE',
+            critical: true,
+            message: 'Volatility persistence hit the stationarity boundary (≥0.999) — long-run variance is unidentified and the corridor is unstable.',
+        });
+    }
+    // Degenerate forecast: variance collapsed to the numerical clamp
+    // (flat market, HAR/NoVaS 1e-20 floor) — a zero-width corridor is never
+    // a reliable market forecast. Floor is relative to the sample variance
+    // so legitimately low-volatility series are not flagged; a zero-variance
+    // (flat) return series is always degenerate.
+    const sv = sampleVariance(fit.returns);
+    if (!(sv > 0) || !(fit.forecast.variance[0] > sv * 1e-8)) {
+        warnings.push({
+            code: 'DEGENERATE_VARIANCE',
+            critical: true,
+            message: 'Forecast variance collapsed to the numerical floor (flat or degenerate market) — a zero-width corridor is not a forecast.',
+        });
+        return; // Ljung-Box on degenerate residuals is meaningless
+    }
     // Ljung-Box on squared standardized residuals
     const { returns, varianceSeries } = fit;
     const squared = returns.map((r, i) => {
@@ -1768,93 +3365,243 @@ function checkReliable(fit) {
         return z * z;
     });
     const lb = ljungBox(squared, 10);
-    return lb.pValue >= 0.05;
+    if (!(lb.pValue >= 0.05)) {
+        warnings.push({
+            code: 'RESIDUAL_AUTOCORRELATION',
+            critical: true,
+            message: `Squared residuals stay autocorrelated (Ljung-Box p=${lb.pValue.toFixed(3)}) — the model did not fully capture volatility clustering; the corridor may understate risk.`,
+        });
+    }
 }
-/**
- * Forecast expected price range for t+1 (next candle).
- *
- * Auto-selects the best volatility model via QLIKE.
- * Uses log-normal price bands: P·exp(±z·σ), where z = probit(confidence).
- * @param confidence — two-sided probability in (0,1). Default ≈0.6827 (±1σ).
- *   Common values: 0.90 → z=1.645, 0.95 → z=1.96, 0.99 → z=2.576.
- */
-function predict(candles, interval, currentPrice, confidence = 0.6827) {
-    assertMinCandles(candles, interval);
-    currentPrice = currentPrice || candles[candles.length - 1].close;
-    const z = probit(confidence);
-    const fit = fitModel(candles, INTERVALS_PER_YEAR[interval], 1);
-    const sigma = fit.forecast.volatility[0];
-    const upperPrice = currentPrice * Math.exp(z * sigma);
-    const lowerPrice = currentPrice * Math.exp(-z * sigma);
+// ── Prediction ────────────────────────────────────────────────
+function runPredict(candles, interval, steps, currentPrice, confidence, warm) {
+    // Hard bound on the horizon: forecasts, seasonal paths, and the horizon
+    // simulation are all O(steps) — an unbounded horizon is unbounded work,
+    // and a corridor further out than the whole sample is meaningless anyway.
+    if (steps > candles.length) {
+        throw new InvalidArgumentError(`steps must not exceed the sample length (${candles.length}), got ${steps}`);
+    }
+    assertTimestampOrder(candles);
+    const warnings = [];
+    collectDataWarnings(candles, interval, warnings);
+    const periodsPerYear = INTERVALS_PER_YEAR[interval];
+    const nReturns = candles.length - 1;
+    // Deseasonalize, fit in flat-profile space, reseasonalize the forecast
+    const season = computeSeasonality(candles, interval);
+    const fitCandles = season ? deseasonalizeCandles(candles, season) : candles;
+    const fit = fitModel(fitCandles, periodsPerYear, steps, warm);
+    const factorPath = new Array(steps).fill(1);
+    if (season) {
+        for (let h = 0; h < steps; h++) {
+            factorPath[h] = season.factors[season.bucketOfReturn(nReturns + h)];
+        }
+        const variance = fit.forecast.variance.map((v, h) => v * factorPath[h]);
+        fit.forecast = {
+            variance,
+            volatility: variance.map(v => Math.sqrt(v)),
+            annualized: variance.map(v => Math.sqrt(v * periodsPerYear) * 100),
+        };
+    }
+    const { up: zUp, down: zDown } = corridorZBounds(fit, confidence, steps, factorPath);
+    const cumulativeVariance = fit.forecast.variance.reduce((sum, v) => sum + v, 0);
+    const sigma = Math.sqrt(cumulativeVariance);
+    const upperPrice = currentPrice * Math.exp(zUp * sigma);
+    const lowerPrice = currentPrice * Math.exp(-zDown * sigma);
+    collectFitWarnings(fit, warnings);
     return {
         modelType: fit.modelType,
         currentPrice,
         sigma,
+        df: fit.df,
+        zScore: (zUp + zDown) / 2,
+        zScoreUp: zUp,
+        zScoreDown: zDown,
         move: upperPrice - currentPrice,
         movePercent: (upperPrice / currentPrice - 1) * 100,
         upperPrice,
         lowerPrice,
-        reliable: checkReliable(fit),
+        reliable: warnings.every(w => !w.critical),
+        warnings,
+        modelWeights: fit.weights,
+        seasonalityDetected: season !== null,
+    };
+}
+/**
+ * Stateful predictor for rolling use (bots, backtests): each subsequent
+ * predict/predictRange warm-starts every optimizer from the previous
+ * window's optimum with a reduced multi-start budget — same math, a
+ * fraction of the cost. State is per-instrument: do not share one
+ * predictor across symbols.
+ */
+function createPredictor(interval) {
+    validateInterval(interval);
+    const warm = {};
+    return {
+        predict(candles, currentPriceOrOptions, confidence = 0.6827) {
+            assertMinCandles(candles, interval);
+            const args = resolvePredictArgs(candles, currentPriceOrOptions, confidence);
+            return runPredict(candles, interval, 1, args.currentPrice, args.confidence, warm);
+        },
+        predictRange(candles, steps, currentPriceOrOptions, confidence = 0.6827) {
+            assertMinCandles(candles, interval);
+            if (!Number.isFinite(steps) || steps < 1) {
+                throw new InvalidArgumentError(`steps must be a number >= 1, got ${steps}`);
+            }
+            const args = resolvePredictArgs(candles, currentPriceOrOptions, confidence);
+            return runPredict(candles, interval, Math.floor(steps), args.currentPrice, args.confidence, warm);
+        },
     };
 }
+/**
+ * Forecast expected price range for t+1 (next candle).
+ *
+ * Combines all volatility models weighted by out-of-sample QLIKE,
+ * deseasonalizes the diurnal variance profile when one is present,
+ * rescales the variance to the return scale (Var(r/σ) = 1), and builds
+ * bands P·exp(±z·σ) where z is calibrated on the data itself: the
+ * empirical |z| quantile of the standardized residuals blended with the
+ * fitted Student-t quantile as the tail runs out of observations (see
+ * corridorZ). Empirical coverage tracks the requested confidence without
+ * assuming a distributional shape.
+ * @param confidence — two-sided probability in (0,1). Default ≈0.6827 (±1σ).
+ *   Common values: 0.90, 0.95, 0.99.
+ */
+function predict(candles, interval, currentPriceOrOptions, confidence = 0.6827) {
+    assertMinCandles(candles, interval);
+    const args = resolvePredictArgs(candles, currentPriceOrOptions, confidence);
+    return runPredict(candles, interval, 1, args.currentPrice, args.confidence);
+}
 /**
  * Forecast expected price range over multiple candles.
  *
- * Cumulative σ = √(σ₁² + σ₂² + ... + σₙ²) — total expected move over N periods.
- * Uses log-normal price bands: P·exp(±z·σ), where z = probit(confidence).
+ * Cumulative σ = √(σ₁² + σ₂² + ... + σₙ²) — total expected move over N
+ * periods, with each step's variance carrying its own seasonal factor.
+ * Uses log-normal price bands P·exp(±z·σ) where z is calibrated at the
+ * requested horizon: the empirical quantile of |h-step standardized sums|
+ * from the sample itself, blended with the model-implied quantile simulated
+ * through the fitted recursions (volatility feedback and fat-tail decay
+ * included).
  * @param confidence — two-sided probability in (0,1). Default ≈0.6827 (±1σ).
+ * @param steps — horizon in candles, 1 ≤ steps ≤ candles.length.
  */
-function predictRange(candles, interval, steps, currentPrice, confidence = 0.6827) {
+function predictRange(candles, interval, steps, currentPriceOrOptions, confidence = 0.6827) {
     assertMinCandles(candles, interval);
-    const z = probit(confidence);
-    const fit = fitModel(candles, INTERVALS_PER_YEAR[interval], steps);
-    currentPrice = currentPrice || candles[candles.length - 1].close;
-    const cumulativeVariance = fit.forecast.variance.reduce((sum, v) => sum + v, 0);
-    const sigma = Math.sqrt(cumulativeVariance);
-    const upperPrice = currentPrice * Math.exp(z * sigma);
-    const lowerPrice = currentPrice * Math.exp(-z * sigma);
-    return {
-        modelType: fit.modelType,
-        currentPrice,
-        sigma,
-        move: upperPrice - currentPrice,
-        movePercent: (upperPrice / currentPrice - 1) * 100,
-        upperPrice,
-        lowerPrice,
-        reliable: checkReliable(fit),
-    };
+    if (!Number.isFinite(steps) || steps < 1) {
+        throw new InvalidArgumentError(`steps must be a number >= 1, got ${steps}`);
+    }
+    steps = Math.floor(steps);
+    const args = resolvePredictArgs(candles, currentPriceOrOptions, confidence);
+    return runPredict(candles, interval, steps, args.currentPrice, args.confidence);
 }
 // ── Backtest ──────────────────────────────────────────────────
 const BACKTEST_WINDOW_RATIO = 0.75;
 /**
- * Walk-forward backtest of predict.
+ * Kupiec (1995) proportion-of-failures test: is the observed hit rate
+ * statistically consistent with the nominal confidence, given how many
+ * walk-forward points there are? A raw hitRate of 63% vs nominal 68% means
+ * nothing without n — this answers "failure or noise" directly.
+ */
+function kupiecTest(hits, total, confidence) {
+    const misses = total - hits;
+    const p = 1 - confidence; // nominal failure probability per observation
+    const pHat = total > 0 ? misses / total : 0;
+    const nominalPct = (confidence * 100).toFixed(1);
+    const coveragePct = total > 0 ? ((hits / total) * 100).toFixed(1) : '0';
+    // Binomial log-likelihood with the 0·ln(0) := 0 convention
+    const ll = (prob) => {
+        let v = 0;
+        if (misses > 0)
+            v += misses * Math.log(prob);
+        if (hits > 0)
+            v += hits * Math.log(1 - prob);
+        return v;
+    };
+    const lr = pHat > 0 && pHat < 1 ? -2 * (ll(p) - ll(pHat)) : -2 * ll(p);
+    const pValue = chi2Survival(Math.max(lr, 0), 1);
+    if (total < 30) {
+        return {
+            verdict: 'inconclusive',
+            pValue,
+            message: `Only ${total} walk-forward points — too few to judge calibration. Aim for ≥30 (more candles or stride: 1).`,
+        };
+    }
+    if (pValue < 0.05) {
+        if (pHat > p) {
+            return {
+                verdict: 'too-narrow',
+                pValue,
+                message: `Coverage ${coveragePct}% is below the nominal ${nominalPct}% (Kupiec p=${pValue.toFixed(4)}) — the corridor is too narrow: real risk exceeds what it shows.`,
+            };
+        }
+        return {
+            verdict: 'too-wide',
+            pValue,
+            message: `Coverage ${coveragePct}% is above the nominal ${nominalPct}% (Kupiec p=${pValue.toFixed(4)}) — the corridor is too wide: decisions based on it are overly conservative.`,
+        };
+    }
+    return {
+        verdict: 'well-calibrated',
+        pValue,
+        message: `Coverage ${coveragePct}% vs nominal ${nominalPct}% over ${total} points is consistent with a calibrated corridor (Kupiec p=${pValue.toFixed(4)}).`,
+    };
+}
+/**
+ * Walk-forward calibration statistics for predict.
  *
- * Window is computed automatically: 75% of candles for fitting, 25% for testing.
+ * Refits the model on a rolling window (75% of candles, min MIN_CANDLES)
+ * and checks whether the next close lands inside the predicted corridor.
+ * A well-calibrated tool has hitRate ≈ confidence·100.
+ *
+ * Every refit costs a full multi-model calibration, so by default the test
+ * points are subsampled to at most ~100 refits (stride grows with the test
+ * span). Pass `stride: 1` to evaluate every candle when runtime is not a
+ * concern, or any positive stride to control the trade-off yourself.
  * Throws if not enough candles for the given interval.
- * Returns true if the model's hit rate meets the required threshold.
  * @param confidence — two-sided probability in (0,1) for the prediction band.
  *   Default ≈0.6827 (±1σ).
- * @param requiredPercent — minimum hit rate (0–100) to pass. Default 68.
  */
-function backtest(candles, interval, confidence = 0.6827, requiredPercent = 68) {
+function backtestStats(candles, interval, confidence = 0.6827, options = {}) {
     assertMinCandles(candles, interval);
-    if (requiredPercent <= 0)
-        return true;
-    if (requiredPercent >= 100)
-        return false;
     const window = Math.max(MIN_CANDLES[interval], Math.floor(candles.length * BACKTEST_WINDOW_RATIO));
+    if (candles.length - 1 <= window) {
+        throw new Error(`Need at least ${window + 2} candles to backtest ${interval} interval, got ${candles.length}`);
+    }
+    const testSpan = candles.length - 1 - window;
+    const stride = Math.max(1, Math.floor(options.stride ?? Math.ceil(testSpan / 100)));
     let hits = 0;
     let total = 0;
-    for (let i = window; i < candles.length - 1; i++) {
+    // Rolling refits share warm-start state — same estimates as cold fits up
+    // to optimizer tolerance, at a fraction of the multi-start cost
+    const warm = {};
+    for (let i = window; i < candles.length - 1; i += stride) {
         const slice = candles.slice(i - window, i + 1);
-        const predicted = predict(slice, interval, slice[slice.length - 1].close, confidence);
+        const price = slice[slice.length - 1].close;
+        const predicted = runPredict(slice, interval, 1, price, confidence, warm);
         const actual = candles[i + 1].close;
         if (actual >= predicted.lowerPrice && actual <= predicted.upperPrice) {
             hits++;
         }
         total++;
     }
-    return (hits / total) * 100 >= requiredPercent;
+    return { hits, total, hitRate: (hits / total) * 100, ...kupiecTest(hits, total, confidence) };
+}
+/**
+ * Walk-forward backtest of predict.
+ *
+ * Window is computed automatically: 75% of candles for fitting, 25% for testing.
+ * Throws if not enough candles for the given interval.
+ * Returns true if the model's hit rate meets the required threshold.
+ * @param confidence — two-sided probability in (0,1) for the prediction band.
+ *   Default ≈0.6827 (±1σ).
+ * @param requiredPercent — minimum hit rate (0–100) to pass. Default 68.
+ */
+function backtest(candles, interval, confidence = 0.6827, requiredPercent = 68) {
+    assertMinCandles(candles, interval);
+    if (requiredPercent <= 0)
+        return true;
+    if (requiredPercent > 100)
+        return false;
+    return backtestStats(candles, interval, confidence).hitRate >= requiredPercent;
 }
 
-export { EXPECTED_ABS_NORMAL, Egarch, Garch, GjrGarch, HarRv, NoVaS, backtest, calculateReturns, calculateReturnsFromPrices, calibrateEgarch, calibrateGarch, calibrateGjrGarch, calibrateHarRv, calibrateNoVaS, checkLeverageEffect, expectedAbsStudentT, garmanKlassVariance, ljungBox, logGamma, nelderMead, nelderMeadMultiStart, perCandleParkinson, predict, predictRange, probit, profileStudentTDf, qlike, sampleVariance, sampleVarianceWithMean, studentTNegLL, yangZhangVariance };
+export { BadDataError, EXPECTED_ABS_NORMAL, Egarch, Garch, GarchError, GjrGarch, HarRv, InvalidArgumentError, NoVaS, NotEnoughDataError, RealizedGarch, backtest, backtestStats, calculateReturns, calculateReturnsFromPrices, calibrateEgarch, calibrateGarch, calibrateGjrGarch, calibrateHarRv, calibrateNoVaS, calibrateRealizedGarch, checkData, checkLeverageEffect, computeSeasonality, createPredictor, deseasonalizeCandles, empiricalQuantile, expectedAbsStudentT, garmanKlassVariance, incompleteBeta, kupiecTest, ljungBox, logGamma, nelderMead, nelderMeadMultiStart, perCandleParkinson, predict, predictRange, probit, profileStudentTDf, qlike, sampleVariance, sampleVarianceWithMean, studentTCdf, studentTNegLL, studentTProbit, validateCandles, yangZhangVariance };