@insiderfinance/totalfinance 0.1.0

package/modules/risk/dist/evt.js

@@ -0,0 +1,625 @@
+import { ensureEnumWhenPresent, ensureFiniteWhenPresent } from './options-internal.js';
+/**
+ * EVT tail-risk pack (spec: `docs/specs/evt-tail-risk.md`, roadmap Tier 2 → Tail machinery). The
+ * honest fat-tail toolkit: normal and historical VaR under-state the left tail exactly where the risk
+ * lives, so this fits the *shape of the tail itself* with a Generalized Pareto Distribution
+ * (peaks-over-threshold, justified by the Pickands–Balkema–de Haan theorem) and reads extreme VaR / ES
+ * off it — always shown beside the empirical and normal numbers so the fat-tail gap is explicit.
+ *
+ * - `fitGeneralizedParetoTail` — GPD fit of the loss tail (robust PWM by default, MLE optional with PWM fallback).
+ * - `extremeValueTailRisk`  — EVT VaR + Expected Shortfall (MonteCarloNeil–Frey POT), vs empirical vs normal.
+ * - `drawdownAtRisk` — Drawdown-at-Risk + Conditional Drawdown-at-Risk (Chekhlov–Uryasev).
+ * - `spectralRisk` — a coherent spectral risk measure (Acerbi); ES is the flat-tail special case.
+ *
+ * Pure functions of a return series; nothing fetches data.
+ */
+import { CONVENTIONS_VERSION, ErrorCode, InputError, ensureKnownKeys, requireArgumentArray, requireArgumentObject, warning, WarningCode, } from '../../core/dist/index.js';
+import { mean, nelderMead, normalInverseCdf, quantile, variance } from '../../math/dist/index.js';
+import { maxDrawdownFromReturns, underwater } from '../../performance/dist/index.js';
+const SQRT_2PI = Math.sqrt(2 * Math.PI);
+const normalPdf = (z) => Math.exp(-0.5 * z * z) / SQRT_2PI;
+/**
+ * Hard cap on the mean-excess grid (2026-08-23 review, P0): `gridSize` sizes the threshold array
+ * and each threshold rescans the entire loss sample, so an "integer" of 1e308 was an absurd
+ * allocation and O(gridSize × n) of unbounded synchronous work. See the guard in meanExcessPlot.
+ */
+const MAX_MEAN_EXCESS_GRID_SIZE = 10_000;
+// ─────────────────────────────── shared input handling ───────────────────────────────
+/** Validate a return series and convert to losses `x = −r` (the left tail we care about). */
+function toLosses(returns, functionName) {
+    requireArgumentArray(functionName, 'returns', returns);
+    const n = returns.length;
+    if (n < 2) {
+        throw new InputError(`${functionName}: need ≥ 2 returns; got ${n}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { observations: n },
+        });
+    }
+    const losses = new Array(n);
+    for (let i = 0; i < n; i++) {
+        const r = returns[i];
+        if (!Number.isFinite(r)) {
+            throw new InputError(`${functionName}: returns must be finite; returns[${i}] = ${r}.`, {
+                code: ErrorCode.InputNotFinite,
+                context: { index: i, value: r },
+            });
+        }
+        losses[i] = -r;
+    }
+    return losses;
+}
+function requireConfidence(c, functionName) {
+    if (!(c > 0 && c < 1)) {
+        throw new InputError(`${functionName}: confidence must be in (0, 1); got ${c}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { confidence: c },
+        });
+    }
+}
+// ─────────────────────────────── GPD core ───────────────────────────────
+/**
+ * Probability-weighted-moment (Hosking & Wallis 1987) GPD estimator on the excesses `y > 0`:
+ * `ξ = 2 − a₀/(a₀ − 2a₁)`, `β = 2·a₀·a₁/(a₀ − 2a₁)`, with `a₀ = mean(y)` and
+ * `a₁ = (1/N)·Σ (1 − (i−0.35)/N)·y₍ᵢ₎` over ascending order statistics. Closed form, no convergence risk.
+ */
+function pwmFit(excesses) {
+    const nu = excesses.length;
+    const sorted = [...excesses].sort((a, b) => a - b);
+    let a0 = 0;
+    let a1 = 0;
+    for (let i = 0; i < nu; i++) {
+        a0 += sorted[i];
+        a1 += (1 - (i + 1 - 0.35) / nu) * sorted[i];
+    }
+    a0 /= nu;
+    a1 /= nu;
+    const denom = a0 - 2 * a1;
+    if (!Number.isFinite(denom) || Math.abs(denom) < 1e-15)
+        return null; // degenerate — guarded
+    const shape = 2 - a0 / denom;
+    const scale = (2 * a0 * a1) / denom;
+    if (!(scale > 0) || !Number.isFinite(shape))
+        return null;
+    return { shape, scale };
+}
+/** GPD negative log-likelihood of the excesses at `(ξ, β)`; a large finite penalty on infeasible points. */
+function gpdNegLogLik(excesses, shape, scale) {
+    if (!(scale > 0))
+        return 1e300;
+    const nu = excesses.length;
+    let sumLog = 0;
+    for (let i = 0; i < nu; i++) {
+        const z = 1 + (shape * excesses[i]) / scale;
+        if (z <= 0)
+            return 1e300; // outside the support — infeasible
+        sumLog += Math.log(z);
+    }
+    if (Math.abs(shape) < 1e-8) {
+        // Exponential limit: (1+1/ξ)·Σln(1+ξy/β) → Σ y/β.
+        let sumY = 0;
+        for (let i = 0; i < nu; i++)
+            sumY += excesses[i];
+        return nu * Math.log(scale) + sumY / scale;
+    }
+    return nu * Math.log(scale) + (1 + 1 / shape) * sumLog;
+}
+/**
+ * Maximum-likelihood GPD fit via Nelder–Mead started at the PWM estimate. Returns `null` on
+ * non-convergence or an infeasible optimum so the caller can fall back to PWM (never a silent bad fit).
+ */
+function mleFit(excesses, start) {
+    const res = nelderMead(([xi, beta]) => gpdNegLogLik(excesses, xi, beta), [start.shape, start.scale], {
+        tolerance: 1e-10,
+        maximumIterations: 800,
+    });
+    if (!res.converged)
+        return null;
+    const [shape, scale] = res.argMin;
+    if (!(scale > 0) || !Number.isFinite(shape) || res.minimum >= 1e299)
+        return null;
+    return { shape, scale };
+}
+/** The documented {@link GeneralizedParetoFitOptions} keys — Law 12: an unknown option must throw, never no-op. */
+const GPD_FIT_OPTIONS_KEYS = ['tailFraction', 'threshold', 'method', 'minExceedances'];
+/** {@link extremeValueTailRisk} adds `confidence` to the GPD-fit knobs. */
+const EVT_TAIL_RISK_OPTIONS_KEYS = ['confidence', ...GPD_FIT_OPTIONS_KEYS];
+/** Shared: extract exceedances, fit the GPD, assemble the `GeneralizedParetoFit` with warnings. */
+function fitTail(returns, options, functionName) {
+    requireArgumentObject(functionName, 'options', options);
+    ensureEnumWhenPresent(options.method, 'evt', 'method', ['pwm', 'mle']);
+    const method = options.method ?? 'pwm';
+    if (method !== 'pwm' && method !== 'mle') {
+        throw new InputError(`${functionName}: method must be 'pwm' or 'mle'; got ${String(method)}.`, {
+            code: ErrorCode.InputInvalidEnum,
+            context: { method },
+        });
+    }
+    ensureFiniteWhenPresent(options.minExceedances, 'minExceedances', 'evt');
+    const minExceedances = options.minExceedances ?? 10;
+    const losses = toLosses(returns, functionName);
+    const n = losses.length;
+    let threshold;
+    if (options.threshold !== undefined) {
+        if (!Number.isFinite(options.threshold)) {
+            throw new InputError(`${functionName}: threshold must be finite; got ${options.threshold}.`, {
+                code: ErrorCode.InputNotFinite,
+                context: { threshold: options.threshold },
+            });
+        }
+        threshold = options.threshold;
+    }
+    else {
+        ensureFiniteWhenPresent(options.tailFraction, 'tailFraction', 'evt');
+        const tailFraction = options.tailFraction ?? 0.1;
+        if (!(tailFraction > 0 && tailFraction < 1)) {
+            throw new InputError(`${functionName}: tailFraction must be in (0, 1); got ${tailFraction}.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { tailFraction },
+            });
+        }
+        threshold = quantile(losses, 1 - tailFraction);
+    }
+    const excesses = [];
+    for (let i = 0; i < n; i++)
+        if (losses[i] > threshold)
+            excesses.push(losses[i] - threshold);
+    const nu = excesses.length;
+    if (nu < 2) {
+        throw new InputError(`${functionName}: only ${nu} loss(es) exceed the threshold — need ≥ 2 to fit a GPD. Raise tailFraction or provide more data.`, { code: ErrorCode.InputOutOfRange, context: { exceedances: nu, threshold } });
+    }
+    const warnings = [];
+    const pwm = pwmFit(excesses);
+    let fitted = pwm;
+    let usedMethod = 'pwm';
+    if (method === 'mle') {
+        const mle = pwm !== null ? mleFit(excesses, pwm) : null;
+        if (mle !== null) {
+            fitted = mle;
+            usedMethod = 'mle';
+        }
+        else {
+            warnings.push(warning(WarningCode.RiskExtremeValueMleFallback, `${functionName}: the MLE did not converge to a feasible GPD; falling back to the PWM estimate.`, 'warn'));
+        }
+    }
+    if (fitted === null) {
+        throw new InputError(`${functionName}: the exceedances are degenerate (near-constant); the GPD is not identifiable.`, { code: ErrorCode.InputOutOfRange, context: { exceedances: nu } });
+    }
+    if (nu < minExceedances) {
+        warnings.push(warning(WarningCode.RiskExtremeValueFewExceedances, `${functionName}: only ${nu} exceedances (< ${minExceedances}); the tail fit is unreliable — use a larger sample or tailFraction.`, 'warn'));
+    }
+    if (Math.abs(fitted.shape) > 10) {
+        // No real financial tail has |ξ| this large; near-constant exceedances drive the estimator to an
+        // absurd shape. Disclose rather than return it as a real tail (design law #4: no silent degradation).
+        warnings.push(warning(WarningCode.RiskExtremeValueDegenerateFit, `${functionName}: |ξ| = ${Math.abs(fitted.shape).toFixed(1)} is implausibly large — the exceedances are near-degenerate (nearly constant), so the tail fit is meaningless. Treat the result as unusable.`, 'warn'));
+    }
+    if (fitted.shape >= 1) {
+        warnings.push(warning(WarningCode.RiskExtremeValueInfiniteMean, `${functionName}: fitted tail index ξ = ${fitted.shape.toFixed(3)} ≥ 1 — the tail mean diverges, so Expected Shortfall is infinite.`, 'warn'));
+    }
+    else if (fitted.shape >= 0.5) {
+        warnings.push(warning(WarningCode.RiskExtremeValueInfiniteVariance, `${functionName}: fitted tail index ξ = ${fitted.shape.toFixed(3)} ≥ 0.5 — the tail variance is infinite (extremely heavy tail).`, 'info'));
+    }
+    const fit = {
+        shape: fitted.shape,
+        scale: fitted.scale,
+        threshold,
+        exceedances: nu,
+        observationCount: n,
+        tailFraction: nu / n,
+        method: usedMethod,
+        assumptions: { conventionsVersion: CONVENTIONS_VERSION, estimator: usedMethod },
+        diagnostics: { engine: 'evt-gpd', method: usedMethod, converged: true, warnings },
+    };
+    return { fit, losses, excesses };
+}
+/**
+ * Fit a Generalized Pareto Distribution to the **loss** tail (peaks-over-threshold). Returns the tail
+ * index `ξ`, scale `β`, threshold, and exceedance count, with warnings for a thin sample or
+ * infinite-moment tails. See `docs/specs/evt-tail-risk.md`.
+ */
+export function fitGeneralizedParetoTail(returns, options = {}) {
+    // Law 12: a misspelled knob (`tailfraction` running at the 10% default) must throw, never no-op.
+    requireArgumentObject('fitGeneralizedParetoTail', 'options', options);
+    ensureKnownKeys('fitGeneralizedParetoTail', 'options', options, GPD_FIT_OPTIONS_KEYS);
+    return fitTail(returns, options, 'fitGeneralizedParetoTail').fit;
+}
+/** Empirical (historical) VaR and ES of the loss series at confidence `p`. */
+function empiricalTail(losses, p) {
+    const v = quantile(losses, p);
+    let sum = 0;
+    let count = 0;
+    for (let i = 0; i < losses.length; i++) {
+        if (losses[i] >= v) {
+            sum += losses[i];
+            count++;
+        }
+    }
+    return { valueAtRisk: v, conditionalValueAtRisk: count > 0 ? sum / count : v };
+}
+/** Gaussian VaR and ES of the loss series at confidence `p`. */
+function normalTail(losses, p) {
+    const mu = mean(losses); // mean LOSS (= −mean return)
+    const sd = Math.sqrt(variance(losses, { population: false }));
+    const z = normalInverseCdf(p);
+    return { valueAtRisk: mu + sd * z, conditionalValueAtRisk: mu + (sd * normalPdf(z)) / (1 - p) };
+}
+/**
+ * Extreme-tail VaR and Expected Shortfall via the MonteCarloNeil–Frey peaks-over-threshold method, shown beside
+ * the empirical and normal numbers with a fat-tail ratio. When the confidence sits outside the fitted
+ * tail (`1 − p ≥ Nu/n`) EVT cannot extrapolate, so the empirical quantile is reported with a warning
+ * instead of a fabricated EVT number. See `docs/specs/evt-tail-risk.md`.
+ */
+export function extremeValueTailRisk(returns, options = {}) {
+    const functionName = 'extremeValueTailRisk';
+    requireArgumentObject(functionName, 'options', options);
+    // Law 12: a misspelled knob (`confdence` running at the 0.99 default) must throw, never no-op.
+    ensureKnownKeys(functionName, 'options', options, EVT_TAIL_RISK_OPTIONS_KEYS);
+    ensureFiniteWhenPresent(options.confidence, 'confidence', 'extremeValueTailRisk');
+    const confidence = options.confidence ?? 0.99;
+    requireConfidence(confidence, functionName);
+    const { fit, losses } = fitTail(returns, options, functionName);
+    const { shape: xi, scale: beta, threshold: u, exceedances: nu, observationCount } = fit;
+    const warnings = [...fit.diagnostics.warnings];
+    const empirical = empiricalTail(losses, confidence);
+    const normal = normalTail(losses, confidence);
+    let extremeValueVar;
+    let extremeValueCvar;
+    const tailProb = 1 - confidence;
+    if (tailProb >= nu / observationCount) {
+        // Not deep enough to be in the fitted tail — do not extrapolate; report the empirical quantile.
+        warnings.push(warning(WarningCode.RiskExtremeValueConfidenceOutsideTail, `${functionName}: confidence ${confidence} implies a tail probability ${tailProb.toFixed(4)} ≥ the fitted tail fraction ${(nu / observationCount).toFixed(4)}; EVT cannot extrapolate there, so the empirical VaR/ES is reported.`, 'warn'));
+        extremeValueVar = empirical.valueAtRisk;
+        extremeValueCvar = empirical.conditionalValueAtRisk;
+    }
+    else {
+        // MonteCarloNeil–Frey POT quantile + ES.
+        extremeValueVar =
+            xi === 0
+                ? u + beta * Math.log(nu / (observationCount * tailProb))
+                : u + (beta / xi) * (Math.pow((observationCount / nu) * tailProb, -xi) - 1);
+        if (xi >= 1) {
+            extremeValueCvar = Infinity; // tail mean diverges (already warned in the fit)
+        }
+        else {
+            extremeValueCvar = extremeValueVar / (1 - xi) + (beta - xi * u) / (1 - xi);
+        }
+    }
+    const tailFatnessRatio = normal.valueAtRisk !== 0 ? extremeValueVar / normal.valueAtRisk : Number.NaN;
+    return {
+        confidence,
+        valueAtRisk: extremeValueVar,
+        conditionalValueAtRisk: extremeValueCvar,
+        empirical,
+        normal,
+        tailFatnessRatio,
+        fit,
+        assumptions: { conventionsVersion: CONVENTIONS_VERSION, confidence },
+        diagnostics: { engine: 'evt-tail-risk', method: fit.method, converged: true, warnings },
+    };
+}
+/**
+ * Drawdown-at-Risk and Conditional Drawdown-at-Risk (Chekhlov–Uryasev) from a return series: the
+ * `α`-quantile of the path's underwater (fractional-drawdown) curve, and the mean drawdown beyond it.
+ * Deterministic; no simulation. See `docs/specs/evt-tail-risk.md`.
+ */
+export function drawdownAtRisk(returns, options = {}) {
+    const functionName = 'drawdownAtRisk';
+    requireArgumentObject(functionName, 'options', options);
+    // Law 12: a misspelled knob (`confdence` running at the 0.95 default) must throw, never no-op.
+    ensureKnownKeys(functionName, 'options', options, ['confidence']);
+    ensureFiniteWhenPresent(options.confidence, 'confidence', 'drawdownAtRisk');
+    const confidence = options.confidence ?? 0.95;
+    requireConfidence(confidence, functionName);
+    requireArgumentArray(functionName, 'returns', returns);
+    const n = returns.length;
+    if (n < 1) {
+        throw new InputError(`${functionName}: need ≥ 1 return; got ${n}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { observations: n },
+        });
+    }
+    for (let i = 0; i < n; i++) {
+        if (!Number.isFinite(returns[i])) {
+            throw new InputError(`${functionName}: returns must be finite; returns[${i}] = ${returns[i]}.`, {
+                code: ErrorCode.InputNotFinite,
+                context: { index: i, value: returns[i] },
+            });
+        }
+    }
+    // Growth-of-1 equity, then the underwater (fractional drawdown) series.
+    const equity = new Array(n + 1);
+    equity[0] = 1;
+    for (let i = 0; i < n; i++)
+        equity[i + 1] = equity[i] * (1 + returns[i]);
+    const dd = underwater(equity); // dₜ = 1 − equityₜ/peakₜ ≥ 0
+    const dar = quantile(dd, confidence);
+    let sum = 0;
+    let count = 0;
+    for (let i = 0; i < dd.length; i++) {
+        if (dd[i] >= dar) {
+            sum += dd[i];
+            count++;
+        }
+    }
+    const cdar = count > 0 ? sum / count : dar;
+    const maxDd = maxDrawdownFromReturns(returns).maxDrawdown;
+    return {
+        confidence,
+        drawdownAtRisk: dar,
+        conditionalDrawdownAtRisk: cdar,
+        maxDrawdown: maxDd,
+        observations: n,
+        assumptions: { conventionsVersion: CONVENTIONS_VERSION, confidence },
+        diagnostics: {
+            engine: 'drawdown-at-risk',
+            method: 'chekhlov-uryasev',
+            converged: true,
+            warnings: [],
+        },
+    };
+}
+/**
+ * A coherent spectral risk measure (Acerbi): a weighted average of the loss quantiles with a
+ * non-decreasing weight on worse outcomes. Pass `{ riskAversion }` for the exponential spectrum
+ * `φ(p) = k·e^(−k(1−p))/(1−e^(−k))` (default `k = 10`), or `{ alpha }` for the Expected-Shortfall
+ * spectrum `φ(p) = 𝟙[p ≥ α]/(1−α)` — ES being the flat-tail special case. See the spec.
+ */
+export function spectralRisk(returns, options = {}) {
+    const functionName = 'spectralRisk';
+    requireArgumentObject(functionName, 'options', options);
+    // Law 12: a misspelled knob (`riskAverson` silently running the k=10 default) must throw.
+    ensureKnownKeys(functionName, 'options', options, ['riskAversion', 'alpha']);
+    const losses = toLosses(returns, functionName);
+    const n = losses.length;
+    const sorted = [...losses].sort((a, b) => a - b); // ascending: worst losses last
+    const isES = 'alpha' in options && options.alpha !== undefined;
+    let phi;
+    let spectrum;
+    let riskAversion;
+    let alpha;
+    if (isES) {
+        alpha = options.alpha;
+        if (!(alpha > 0 && alpha < 1)) {
+            throw new InputError(`${functionName}: alpha must be in (0, 1); got ${alpha}.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { alpha },
+            });
+        }
+        const a = alpha;
+        phi = (p) => (p >= a ? 1 / (1 - a) : 0);
+        spectrum = 'expected-shortfall';
+    }
+    else {
+        ensureFiniteWhenPresent(options.riskAversion, 'riskAversion', 'spectralRisk');
+        riskAversion = options.riskAversion ?? 10;
+        if (!(riskAversion > 0) || !Number.isFinite(riskAversion)) {
+            throw new InputError(`${functionName}: riskAversion must be a positive finite number; got ${riskAversion}.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { riskAversion },
+            });
+        }
+        const k = riskAversion;
+        const denom = 1 - Math.exp(-k);
+        phi = (p) => (k * Math.exp(-k * (1 - p))) / denom;
+        spectrum = 'exponential';
+    }
+    // M_φ = Σ φ(pᵢ)·loss₍ᵢ₎·Δp with pᵢ the midpoint plotting position (i−0.5)/n and Δp = 1/n.
+    let value = 0;
+    for (let i = 0; i < n; i++) {
+        const p = (i + 0.5) / n;
+        value += phi(p) * sorted[i];
+    }
+    value /= n;
+    return {
+        value,
+        spectrum,
+        ...(riskAversion !== undefined ? { riskAversion } : {}),
+        ...(alpha !== undefined ? { alpha } : {}),
+        assumptions: { conventionsVersion: CONVENTIONS_VERSION },
+        diagnostics: { engine: 'spectral-risk', method: spectrum, converged: true, warnings: [] },
+    };
+}
+/**
+ * Exceedance-**weighted** least-squares line `y = slope·x + intercept` (x = threshold, y = mean-excess).
+ * Weighting by the exceedance count lets the clean, data-rich low-threshold points drive the fit and keeps
+ * the noisy high-threshold tail (few exceedances) from dominating — the standard way to read the plot.
+ */
+function meanExcessLineFit(points) {
+    let sw = 0;
+    let swx = 0;
+    let swy = 0;
+    let swxx = 0;
+    let swxy = 0;
+    for (const p of points) {
+        const w = p.exceedances;
+        sw += w;
+        swx += w * p.threshold;
+        swy += w * p.meanExcess;
+        swxx += w * p.threshold * p.threshold;
+        swxy += w * p.threshold * p.meanExcess;
+    }
+    const denom = sw * swxx - swx * swx;
+    const slope = denom !== 0 ? (sw * swxy - swx * swy) / denom : 0;
+    return { slope, intercept: (swy - slope * swx) / sw };
+}
+/**
+ * The **mean-excess plot** — the standard tool for choosing the EVT peaks-over-threshold cutoff the rest of
+ * the pack takes as an input. The mean-excess `e(u) = E[X − u | X > u]` is linear in `u` (slope `ξ/(1−ξ)`)
+ * above the true tail threshold and non-linear below it, so the threshold is read off as where the curve
+ * straightens. Returns the curve, a heuristic `suggestedThreshold`, the `tailIndexEstimate` from that
+ * region's slope, and the `suggestedTailFraction` to hand to {@link fitGeneralizedParetoTail}. See
+ * `docs/specs/mean-excess-plot.md`.
+ */
+export function meanExcessPlot(returns, options = {}) {
+    const functionName = 'meanExcessPlot';
+    requireArgumentObject(functionName, 'options', options);
+    // Law 12: a misspelled knob (`gridsize` running at the 25-point default) must throw, never no-op.
+    ensureKnownKeys(functionName, 'options', options, [
+        'thresholds',
+        'gridSize',
+        'startQuantile',
+        'minExceedances',
+        'linearTolerance',
+    ]);
+    const losses = toLosses(returns, functionName);
+    const n = losses.length;
+    ensureFiniteWhenPresent(options.minExceedances, 'minExceedances', 'meanExcessPlot');
+    const minExceedances = options.minExceedances ?? 10;
+    // Safe integer (2026-08-23 review, P0): it only positions the grid's top threshold via
+    // `n − minExceedances − 1` (no loop of its own), but an inexact count silently misplaces it.
+    if (!Number.isSafeInteger(minExceedances) || minExceedances < 1) {
+        throw new InputError(`${functionName}: minExceedances must be a positive integer; got ${minExceedances}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { minExceedances },
+        });
+    }
+    ensureFiniteWhenPresent(options.linearTolerance, 'linearTolerance', 'meanExcessPlot');
+    const linearTolerance = options.linearTolerance ?? 0.1;
+    if (!(linearTolerance > 0)) {
+        throw new InputError(`${functionName}: linearTolerance must be > 0; got ${linearTolerance}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { linearTolerance },
+        });
+    }
+    // Candidate thresholds: explicit, or an even grid from the startQuantile loss to the loss leaving
+    // ~minExceedances above.
+    let thresholds;
+    if (options.thresholds !== undefined) {
+        requireArgumentArray(functionName, 'thresholds', options.thresholds);
+        thresholds = [...options.thresholds].sort((a, b) => a - b);
+        thresholds.forEach((u, i) => {
+            if (!Number.isFinite(u)) {
+                throw new InputError(`${functionName}: thresholds[${i}] must be finite; got ${u}.`, {
+                    code: ErrorCode.InputNotFinite,
+                    context: { index: i, value: u },
+                });
+            }
+        });
+    }
+    else {
+        ensureFiniteWhenPresent(options.gridSize, 'gridSize', 'meanExcessPlot');
+        const gridSize = options.gridSize ?? 25;
+        // Safe integer AND a work cap (2026-08-23 review, P0): gridSize sizes the threshold array and
+        // each threshold costs TWO full passes over the losses (mean excess, then its standard error),
+        // so `Number.isInteger(1e308)` being `true` made the old gate an absurd-allocation license.
+        // 10,000 thresholds × a 10^5-loss sample is ~4·10^9 cheap comparisons — single-digit seconds on
+        // a laptop and 400× the 25-point default; a mean-excess PLOT gains nothing beyond that.
+        if (!Number.isSafeInteger(gridSize) || gridSize < 2 || gridSize > MAX_MEAN_EXCESS_GRID_SIZE) {
+            throw new InputError(`${functionName}: gridSize must be an integer in [2, ${MAX_MEAN_EXCESS_GRID_SIZE.toLocaleString('en-US')}] — each grid point scans the full loss sample twice, so the cap keeps the largest request single-digit seconds of synchronous work (the default is 25); got ${gridSize}.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { gridSize, max: MAX_MEAN_EXCESS_GRID_SIZE },
+            });
+        }
+        ensureFiniteWhenPresent(options.startQuantile, 'startQuantile', 'meanExcessPlot');
+        const startQuantile = options.startQuantile ?? 0.5;
+        if (!(startQuantile > 0 && startQuantile < 1)) {
+            throw new InputError(`${functionName}: startQuantile must be in (0, 1); got ${startQuantile}.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { startQuantile },
+            });
+        }
+        const sorted = [...losses].sort((a, b) => a - b);
+        const loIdx = Math.floor(startQuantile * (n - 1));
+        const hiIdx = n - minExceedances - 1; // ~minExceedances losses lie strictly above sorted[hiIdx]
+        if (hiIdx <= loIdx || !(sorted[hiIdx] > sorted[loIdx])) {
+            throw new InputError(`${functionName}: not enough loss data for a mean-excess grid (n = ${n}, startQuantile = ${startQuantile}, minExceedances = ${minExceedances}) — add observations or lower startQuantile/minExceedances.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { observations: n, startQuantile, minExceedances },
+            });
+        }
+        const uMin = sorted[loIdx];
+        const uMax = sorted[hiIdx];
+        thresholds = Array.from({ length: gridSize }, (_, i) => uMin + ((uMax - uMin) * i) / (gridSize - 1));
+    }
+    // The curve: e(u), Nu, standard error per threshold (skip thresholds with no exceedances).
+    const points = [];
+    for (const u of thresholds) {
+        let sum = 0;
+        let cnt = 0;
+        for (const x of losses) {
+            if (x > u) {
+                sum += x - u;
+                cnt++;
+            }
+        }
+        if (cnt === 0)
+            continue;
+        const me = sum / cnt;
+        let se = 0;
+        if (cnt >= 2) {
+            let ss = 0;
+            for (const x of losses)
+                if (x > u)
+                    ss += (x - u - me) * (x - u - me);
+            se = Math.sqrt(ss / (cnt - 1)) / Math.sqrt(cnt);
+        }
+        points.push({ threshold: u, meanExcess: me, exceedances: cnt, standardError: se });
+    }
+    if (points.length === 0) {
+        throw new InputError(`${functionName}: no threshold has any exceedances — every candidate exceeds all losses.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { thresholds: thresholds.length },
+        });
+    }
+    // Suggested threshold: the lowest u (with ≥ minExceedances above and ≥ 3 candidates above) whose
+    // mean-excess over [u, uₘₐₓ] is linear within the tolerance.
+    const normalizedDeviation = (startIdx) => {
+        const slice = points.slice(startIdx);
+        const { slope, intercept } = meanExcessLineFit(slice);
+        const es = slice.map((p) => p.meanExcess);
+        const range = Math.max(...es) - Math.min(...es);
+        if (!(range > 0))
+            return 0;
+        // Exceedance-weighted RMS deviation from the fitted line — a single noisy high-threshold point (few
+        // exceedances) can't fail the linearity test on its own; the data-rich region governs it.
+        let sw = 0;
+        let ss = 0;
+        for (const p of slice) {
+            const d = p.meanExcess - (intercept + slope * p.threshold);
+            sw += p.exceedances;
+            ss += p.exceedances * d * d;
+        }
+        return Math.sqrt(ss / sw) / range;
+    };
+    const warnings = [];
+    let suggestedIdx = -1;
+    for (let i = 0; i < points.length; i++) {
+        if (points[i].exceedances < minExceedances)
+            continue;
+        if (points.length - i < 3)
+            break; // too few points above to judge linearity
+        if (normalizedDeviation(i) <= linearTolerance) {
+            suggestedIdx = i;
+            break;
+        }
+    }
+    if (suggestedIdx === -1) {
+        for (let i = points.length - 1; i >= 0; i--) {
+            if (points[i].exceedances >= minExceedances) {
+                suggestedIdx = i;
+                break;
+            }
+        }
+        if (suggestedIdx === -1)
+            suggestedIdx = 0;
+        warnings.push(warning(WarningCode.RiskMeanExcessNoLinearRegion, `${functionName}: no threshold produced a clearly-linear mean-excess region within the tolerance (${linearTolerance}) — the suggested threshold is the highest with ≥ ${minExceedances} exceedances; inspect the plot.`, 'warn', { linearTolerance, minExceedances }));
+    }
+    const suggestedThreshold = points[suggestedIdx].threshold;
+    const tailSlice = points.slice(suggestedIdx);
+    const { slope } = tailSlice.length >= 2 ? meanExcessLineFit(tailSlice) : { slope: 0 };
+    const tailIndexEstimate = slope / (1 + slope);
+    const suggestedTailFraction = points[suggestedIdx].exceedances / n;
+    return {
+        points,
+        suggestedThreshold,
+        tailIndexEstimate,
+        suggestedTailFraction,
+        assumptions: { conventionsVersion: CONVENTIONS_VERSION, observations: n, losses: n },
+        diagnostics: {
+            engine: 'mean-excess-plot',
+            method: 'peaks-over-threshold',
+            converged: Number.isFinite(tailIndexEstimate),
+            warnings,
+        },
+    };
+}
+//# sourceMappingURL=evt.js.map