@insiderfinance/totalfinance 0.1.0

package/modules/volatility/dist/vanna-volga.js

@@ -0,0 +1,833 @@
+/**
+ * Vanna–volga smile construction (spec: `docs/specs/vanna-volga.md`). The FX/crypto market standard for
+ * building a full smile from three quotes — ATM vol + the δ-delta risk reversal and butterfly. Prices
+ * any strike as the flat-ATM Black–Scholes value plus the cost of a portfolio of the three market
+ * instruments that hedges the option's vega, vanna, and volga, so the smile **reprices the three market
+ * pillars exactly** and interpolates smoothly. Composes `smileFromQuotes` (pillars) and round-trips
+ * through `riskReversalButterfly` (quotes). Forward (undiscounted) terms throughout — discount-invariant.
+ */
+import { CONVENTIONS_VERSION, ErrorCode, InputError, WarningCode, ensureFinite, ensureFiniteWhenPresent, ensureKnownKeys, ensurePositive, requireArgumentArray, requireArgumentObject, validateClosedRequest, warning, } from '../../core/dist/index.js';
+import { luDecompose, luSolve, makePchipInterpolator, normalPdf } from '../../math/dist/index.js';
+import { blackScholesImpliedVolatility, blackScholesPrice, } from '../../options/dist/black-scholes.js';
+import { riskNeutralDistribution } from './analytics.js';
+import { smileFromQuotes } from './risk-reversal.js';
+import { VALIDATION_SPECS } from './generated/validation-specs.js';
+/**
+ * Generated closed-request specs (spec 3B.1b): allowlists projected from the declarations.
+ * Resolved at module load so a stale key fails at import. `vannaVolgaApproximation` and
+ * `vannaVolgaDensity` carry no generated keys and keep their curated Law 12 allowlists.
+ */
+function vannaVolgaSpecOf(key) {
+    const spec = VALIDATION_SPECS[key];
+    if (spec === undefined) {
+        throw new Error(`vanna-volga: no generated validation spec for '${key}' — run \`pnpm validation:update\``);
+    }
+    return spec;
+}
+/**
+ * Hard cap on the Breeden-Litzenberger density grid (2026-08-23 review, P0): `gridPoints` sizes
+ * the strike/density/cdf arrays and each point costs several smile + Black-Scholes evaluations,
+ * so an "integer" of 1e308 was an absurd allocation. 100,001 (odd, keeping ATM on the centre
+ * node) is 125× the 801-point default and still well under a second of synchronous work.
+ */
+const MAX_DENSITY_GRID_POINTS = 100_001;
+const CALIBRATE_VANNA_VOLGA_SPEC = vannaVolgaSpecOf('calibrateVannaVolga#0');
+const CALIBRATE_VANNA_VOLGA_5_SPEC = vannaVolgaSpecOf('calibrateVannaVolga5#0');
+const VANNA_VOLGA_5_DENSITY_SPEC = vannaVolgaSpecOf('vannaVolga5Density#0');
+const CALIBRATE_VANNA_VOLGA_EXAMPLE = () => 'calibrateVannaVolga({ forward: 100, timeToExpiryYears: 0.25, atmVolatility: 0.2, ' +
+    'riskReversal: -0.02, butterfly: 0.01, strikes: [90, 100, 110] })';
+const CALIBRATE_VANNA_VOLGA_5_EXAMPLE = () => 'calibrateVannaVolga5({ forward: 100, timeToExpiryYears: 0.25, atmVolatility: 0.2, ' +
+    'riskReversal25: -0.02, butterfly25: 0.01, riskReversal10: -0.035, butterfly10: 0.025, ' +
+    'strikes: [80, 100, 120] })';
+const VANNA_VOLGA_5_DENSITY_EXAMPLE = () => 'vannaVolga5Density({ forward: 100, timeToExpiryYears: 0.25, atmVolatility: 0.2, ' +
+    'riskReversal25: -0.02, butterfly25: 0.01, riskReversal10: -0.035, butterfly10: 0.025 })';
+/** Below this vol (0.1%) a VV inversion is treated as a far-extrapolation breakdown, not a real quote. */
+const MIN_VOL = 1e-3;
+/**
+ * Law 12 allowlists for the three entry points that had none. A typo'd knob here is silent and
+ * expensive: `gridPoint: 2001` or `widthSd: 8` left the density on its 801-point / 6-sd DEFAULT grid
+ * and the caller read the truncated moments as if their request had been honoured.
+ */
+const VANNA_VOLGA_APPROXIMATION_KEYS = [
+    'forward',
+    'timeToExpiryYears',
+    'atmVolatility',
+    'riskReversal',
+    'butterfly',
+    'delta',
+    'strikes',
+    'order',
+];
+const VANNA_VOLGA_DENSITY_KEYS = [
+    'forward',
+    'timeToExpiryYears',
+    'atmVolatility',
+    'riskReversal',
+    'butterfly',
+    'delta',
+    'order',
+    'gridPoints',
+    'widthStandardDeviations',
+    'step',
+];
+/** Forward (undiscounted) Black call price. */
+const fwdCall = ({ forward, strike, timeToExpiryYears, volatility }) => blackScholesPrice({
+    type: 'call',
+    spot: forward,
+    strike,
+    timeToExpiryYears,
+    riskFreeRate: 0,
+    dividendYield: 0,
+    volatility,
+});
+/** Raw forward `(vega, vanna, volga)` at strike `K`, vol `σ`. */
+function fwdGreeks(input) {
+    const { forward: F, strike: K, timeToExpiryYears: T, volatility: sigma } = input;
+    const sqrtT = Math.sqrt(T);
+    const vol = sigma * sqrtT;
+    const d1 = (Math.log(F / K) + 0.5 * sigma * sigma * T) / vol;
+    const d2 = d1 - vol;
+    const pdf = normalPdf(d1);
+    const vega = F * pdf * sqrtT;
+    const vanna = (-pdf * d2) / sigma;
+    const volga = (vega * d1 * d2) / sigma;
+    return [vega, vanna, volga];
+}
+/**
+ * Construct a vanna–volga smile from the `(ATM, riskReversal, butterfly)` quotes and evaluate it at the
+ * requested strikes. The three market pillars (from {@link smileFromQuotes}) reprice exactly; strikes so
+ * far out of range that the VV price violates the no-arbitrage bounds cannot be inverted and are reported.
+ * See `docs/specs/vanna-volga.md`.
+ */
+export function calibrateVannaVolga(input) {
+    const functionName = 'calibrateVannaVolga';
+    validateClosedRequest(functionName, input, CALIBRATE_VANNA_VOLGA_SPEC, {
+        exampleCall: CALIBRATE_VANNA_VOLGA_EXAMPLE,
+    });
+    ensurePositive(input.forward, 'forward', functionName);
+    ensurePositive(input.timeToExpiryYears, 'timeToExpiryYears', functionName);
+    ensurePositive(input.atmVolatility, 'atmVolatility', functionName);
+    if (input.strikes.length === 0) {
+        throw new InputError(`${functionName}: strikes must be a non-empty array.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { strikes: 0 },
+        });
+    }
+    input.strikes.forEach((K, i) => ensurePositive(K, `strikes[${i}]`, functionName));
+    const delta = input.delta ?? 0.25;
+    const F = input.forward;
+    const T = input.timeToExpiryYears;
+    const atm = input.atmVolatility;
+    // The three pillars from the quotes (also validates delta ∈ (0, 0.5) and positive wing volatilities).
+    const p = smileFromQuotes({
+        forward: F,
+        timeToExpiryYears: T,
+        atmVolatility: atm,
+        riskReversal: input.riskReversal,
+        butterfly: input.butterfly,
+        delta,
+    });
+    const pillarK = [p.putStrike, p.atmStrike, p.callStrike];
+    const pillarSig = [p.putVolatility, p.atmVolatility, p.callVolatility];
+    // The 3×3 pillar-greeks matrix (columns = each pillar's vega/vanna/volga at the ATM vol) is fixed
+    // across all query strikes, so factor it once. `M[row][col]`.
+    const g0 = fwdGreeks({ forward: F, strike: pillarK[0], timeToExpiryYears: T, volatility: atm });
+    const g1 = fwdGreeks({ forward: F, strike: pillarK[1], timeToExpiryYears: T, volatility: atm });
+    const g2 = fwdGreeks({ forward: F, strike: pillarK[2], timeToExpiryYears: T, volatility: atm });
+    const M = [
+        [g0[0], g1[0], g2[0]],
+        [g0[1], g1[1], g2[1]],
+        [g0[2], g1[2], g2[2]],
+    ];
+    let lu;
+    try {
+        lu = luDecompose(M);
+    }
+    catch {
+        throw new InputError(`${functionName}: the pillar vega/vanna/volga matrix is singular — the three pillars are degenerate (check the delta and quotes).`, { code: ErrorCode.LinalgSingular, context: { pillarStrikes: pillarK } });
+    }
+    // Market cost carried by each pillar (the vol correction the hedge pays for).
+    const pillarCost = [0, 1, 2].map((i) => fwdCall({
+        forward: F,
+        strike: pillarK[i],
+        timeToExpiryYears: T,
+        volatility: pillarSig[i],
+    }) - fwdCall({ forward: F, strike: pillarK[i], timeToExpiryYears: T, volatility: atm }));
+    const volatilities = new Array(input.strikes.length);
+    const unrepresentable = [];
+    input.strikes.forEach((K, idx) => {
+        const w = luSolve(lu, fwdGreeks({ forward: F, strike: K, timeToExpiryYears: T, volatility: atm }));
+        if (!w.every((x) => Number.isFinite(x))) {
+            unrepresentable.push(K);
+            return;
+        }
+        const price = fwdCall({ forward: F, strike: K, timeToExpiryYears: T, volatility: atm }) +
+            w[0] * pillarCost[0] +
+            w[1] * pillarCost[1] +
+            w[2] * pillarCost[2];
+        const impliedVolatility = blackScholesImpliedVolatility({
+            type: 'call',
+            price,
+            spot: F,
+            strike: K,
+            timeToExpiryYears: T,
+            riskFreeRate: 0,
+            dividendYield: 0,
+        });
+        // Un-representable if the price is out of the no-arb bounds (no inversion) OR the VV price has
+        // collapsed to intrinsic, giving a degenerate ≈ 0 vol — a far-extrapolation breakdown, not a real quote.
+        if (!impliedVolatility.converged || !(impliedVolatility.value >= MIN_VOL)) {
+            unrepresentable.push(K);
+            return;
+        }
+        volatilities[idx] = impliedVolatility.value;
+    });
+    if (unrepresentable.length > 0) {
+        throw new InputError(`${functionName}: the vanna–volga price is outside the no-arbitrage bounds at ${unrepresentable.length} strike(s) (${unrepresentable
+            .map((k) => k.toFixed(2))
+            .join(', ')}) — too far from the pillars to represent; query strikes nearer the ATM/wing range.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { strikes: unrepresentable, pillarStrikes: pillarK },
+        });
+    }
+    return {
+        strikes: [...input.strikes],
+        volatilities,
+        pillars: {
+            putStrike: p.putStrike,
+            putVolatility: p.putVolatility,
+            atmStrike: p.atmStrike,
+            atmVolatility: p.atmVolatility,
+            callStrike: p.callStrike,
+            callVolatility: p.callVolatility,
+        },
+        delta,
+        assumptions: {
+            conventionsVersion: CONVENTIONS_VERSION,
+            method: 'vanna-volga',
+            deltaConvention: 'forward',
+            delta,
+        },
+        diagnostics: {
+            engine: 'vanna-volga',
+            method: 'exact vega/vanna/volga replication',
+            converged: true,
+            warnings: [],
+        },
+    };
+}
+function castagnaMercurio(input) {
+    const { order, forward: F, timeToExpiryYears: T, strike: K, putStrike: K1, atmStrike: K2, callStrike: K3, putVolatility: s1, atmVolatility: s2, callVolatility: s3, } = input;
+    const ln = Math.log;
+    const y1 = (ln(K2 / K) * ln(K3 / K)) / (ln(K2 / K1) * ln(K3 / K1));
+    const y2 = (ln(K / K1) * ln(K3 / K)) / (ln(K2 / K1) * ln(K3 / K2));
+    const y3 = (ln(K / K1) * ln(K / K2)) / (ln(K3 / K1) * ln(K3 / K2));
+    const first = y1 * s1 + y2 * s2 + y3 * s3; // log-strike Lagrange interpolation
+    if (order === 1)
+        return first;
+    // Forward Black d₁·d₂ at the ATM vol σ₂.
+    const d1d2 = (k) => {
+        const v = s2 * Math.sqrt(T);
+        const d1 = (ln(F / k) + 0.5 * s2 * s2 * T) / v;
+        return d1 * (d1 - v);
+    };
+    const D1 = y1 * (s1 - s2) + y3 * (s3 - s2); // = first − σ₂
+    const D2 = y1 * d1d2(K1) * (s1 - s2) ** 2 + y3 * d1d2(K3) * (s3 - s2) ** 2;
+    const dd = d1d2(K);
+    // At K = F·e^{±½σ₂²T} the denominator d₁d₂ → 0; the 2nd-order formula has the finite limit
+    // σ₂ + D₁ + D₂/(2σ₂) (a first-order interpolation plus a small curvature correction).
+    if (Math.abs(dd) < 1e-12)
+        return s2 + D1 + D2 / (2 * s2);
+    const arg = s2 * s2 + dd * (2 * s2 * D1 + D2);
+    if (arg < 0)
+        return Number.NaN; // far-extrapolation breakdown
+    return s2 + (-s2 + Math.sqrt(arg)) / dd;
+}
+/**
+ * Vanna-volga implied vol by the Castagna–Mercurio (2007) closed form — the fast, always-defined market
+ * quote, complementing the exact replication in {@link calibrateVannaVolga}. Same three pillars (via
+ * `smileFromQuotes`), which both orders reprice exactly; far-extrapolation breakdowns (a negative curvature
+ * `√`, or a vol collapsed below `MIN_VOL`) are collected and reported rather than returned as garbage. See
+ * `docs/specs/vanna-volga-approx.md`.
+ */
+export function vannaVolgaApproximation(input) {
+    const functionName = 'vannaVolgaApproximation';
+    requireArgumentObject(functionName, 'input', input);
+    ensureKnownKeys(functionName, 'input', input, VANNA_VOLGA_APPROXIMATION_KEYS);
+    ensurePositive(input.forward, 'forward', functionName);
+    ensurePositive(input.timeToExpiryYears, 'timeToExpiryYears', functionName);
+    ensurePositive(input.atmVolatility, 'atmVolatility', functionName);
+    ensureFinite(input.riskReversal, 'riskReversal', functionName);
+    ensureFinite(input.butterfly, 'butterfly', functionName);
+    requireArgumentArray(functionName, 'strikes', input.strikes);
+    if (input.strikes.length === 0) {
+        throw new InputError(`${functionName}: strikes must be a non-empty array.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { strikes: 0 },
+        });
+    }
+    input.strikes.forEach((K, i) => ensurePositive(K, `strikes[${i}]`, functionName));
+    const delta = input.delta ?? 0.25;
+    const order = input.order ?? 2;
+    if (order !== 1 && order !== 2) {
+        throw new InputError(`${functionName}: order must be 1 or 2; got ${String(order)}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { order },
+        });
+    }
+    const F = input.forward;
+    const T = input.timeToExpiryYears;
+    const p = smileFromQuotes({
+        forward: F,
+        timeToExpiryYears: T,
+        atmVolatility: input.atmVolatility,
+        riskReversal: input.riskReversal,
+        butterfly: input.butterfly,
+        delta,
+    });
+    const [K1, K2, K3] = [p.putStrike, p.atmStrike, p.callStrike];
+    const [s1, s2, s3] = [p.putVolatility, p.atmVolatility, p.callVolatility];
+    const volatilities = new Array(input.strikes.length);
+    const unrepresentable = [];
+    input.strikes.forEach((K, idx) => {
+        const v = castagnaMercurio({
+            order,
+            forward: F,
+            timeToExpiryYears: T,
+            strike: K,
+            putStrike: K1,
+            atmStrike: K2,
+            callStrike: K3,
+            putVolatility: s1,
+            atmVolatility: s2,
+            callVolatility: s3,
+        });
+        if (!Number.isFinite(v) || !(v >= MIN_VOL)) {
+            unrepresentable.push(K);
+            return;
+        }
+        volatilities[idx] = v;
+    });
+    if (unrepresentable.length > 0) {
+        throw new InputError(`${functionName}: the Castagna–Mercurio approximation broke down at ${unrepresentable.length} strike(s) (${unrepresentable
+            .map((k) => k.toFixed(2))
+            .join(', ')}) — too far from the pillars to represent; query strikes nearer the ATM/wing range.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { strikes: unrepresentable, pillarStrikes: [K1, K2, K3] },
+        });
+    }
+    return {
+        strikes: [...input.strikes],
+        volatilities,
+        pillars: {
+            putStrike: p.putStrike,
+            putVolatility: p.putVolatility,
+            atmStrike: p.atmStrike,
+            atmVolatility: p.atmVolatility,
+            callStrike: p.callStrike,
+            callVolatility: p.callVolatility,
+        },
+        delta,
+        order,
+        assumptions: {
+            conventionsVersion: CONVENTIONS_VERSION,
+            method: 'castagna-mercurio',
+            deltaConvention: 'forward',
+            delta,
+            order,
+        },
+        diagnostics: {
+            engine: 'vanna-volga',
+            method: `castagna-mercurio order-${order}`,
+            converged: true,
+            warnings: [],
+        },
+    };
+}
+/** Validate the shared density grid controls; returns the resolved `(gridPoints, widthStandardDeviations, step)`. */
+function densityGridControls(input) {
+    const { functionName, forward: F, gridPoints, widthStandardDeviations, step } = input;
+    ensureFiniteWhenPresent(gridPoints, 'gridPoints', functionName);
+    ensureFiniteWhenPresent(widthStandardDeviations, 'widthStandardDeviations', functionName);
+    ensureFiniteWhenPresent(step, 'step', functionName);
+    const gp = gridPoints ?? 801;
+    // Safe integer AND a work cap (2026-08-23 review, P0): gridPoints sizes the strike grid AND
+    // every derived array (density, cdf), and each point costs several smile + Black-Scholes
+    // evaluations for the Breeden-Litzenberger second difference — `Number.isInteger(1e308)` is
+    // `true`, so the old gate licensed an absurd allocation. 100,001 points is 125× the 801-point
+    // default (~a few hundred ms of grid evaluation) — a parametric Castagna-Mercurio density gains
+    // nothing beyond that resolution.
+    if (!Number.isSafeInteger(gp) || gp < 11 || gp > MAX_DENSITY_GRID_POINTS || gp % 2 === 0) {
+        throw new InputError(`${functionName}: gridPoints must be an odd integer in [11, ${MAX_DENSITY_GRID_POINTS.toLocaleString('en-US')}] — each point is several smile/Black-Scholes evaluations materialized into the density and cdf arrays, so the cap keeps the largest grid well under a second (the default is 801); got ${String(gp)}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { gridPoints: gp, max: MAX_DENSITY_GRID_POINTS },
+        });
+    }
+    const w = widthStandardDeviations ?? 6;
+    ensurePositive(w, 'widthStandardDeviations', functionName);
+    if (step !== undefined)
+        ensurePositive(step, 'step', functionName);
+    return { gridPoints: gp, widthStandardDeviations: w, step: step ?? F * 1e-3 };
+}
+/** The log-uniform strike grid `F·e^{±widthStandardDeviations·σ√T}` (an odd count puts the ATM forward on the centre node). */
+function densityGrid(input) {
+    const { forward: F, atmVolatility, timeToExpiryYears: T, gridPoints, widthStandardDeviations, } = input;
+    const halfLog = widthStandardDeviations * atmVolatility * Math.sqrt(T);
+    const lnLo = Math.log(F) - halfLog;
+    const lnHi = Math.log(F) + halfLog;
+    const strikes = new Array(gridPoints);
+    for (let i = 0; i < gridPoints; i++) {
+        strikes[i] = Math.exp(lnLo + ((lnHi - lnLo) * i) / (gridPoints - 1));
+    }
+    return strikes;
+}
+/**
+ * Breeden–Litzenberger risk-neutral density in forward space from a `smile` that is finite and positive
+ * across `strikes ± step`: the undiscounted forward Black call's strike derivatives are the density and CDF.
+ * Samples the grid, integrates the moments (trapezoid), inverts the CDF (bisection), and raises
+ * mass/mean/non-monotone-CDF warnings. Shared by {@link vannaVolgaDensity} and {@link vannaVolga5Density}.
+ */
+function forwardMeasureDensity(input) {
+    const { functionName, smile, forward: F, timeToExpiryYears: T, strikes, step } = input;
+    const gridPoints = strikes.length;
+    // Breeden–Litzenberger in forward space (spot = F, rate = 0, q = 0). Reuses the verified analytics.ts core.
+    const bl = riskNeutralDistribution(smile, {
+        spot: F,
+        timeToExpiryYears: T,
+        riskFreeRate: 0,
+        step,
+    });
+    const densityArr = strikes.map((K) => bl.density(K));
+    const cdfArr = strikes.map((K) => bl.cdf(K));
+    // Non-uniform trapezoidal integration of g(K)·f(K) over the (geometric) grid.
+    const integrate = (g) => {
+        let sum = 0;
+        for (let i = 0; i < gridPoints - 1; i++) {
+            const dK = strikes[i + 1] - strikes[i];
+            sum += (dK * (g(strikes[i]) * densityArr[i] + g(strikes[i + 1]) * densityArr[i + 1])) / 2;
+        }
+        return sum;
+    };
+    const totalMass = integrate(() => 1);
+    const mean = integrate((K) => K) / totalMass;
+    const variance = integrate((K) => (K - mean) ** 2) / totalMass;
+    const stdev = Math.sqrt(Math.max(0, variance));
+    // stdev/variance are strictly positive for any real smile with T > 0, so divide directly.
+    const skewness = integrate((K) => (K - mean) ** 3) / totalMass / stdev ** 3;
+    const excessKurtosis = integrate((K) => (K - mean) ** 4) / totalMass / variance ** 2 - 3;
+    // Inverse CDF by bisection over the grid span (the CDF is monotone for an arbitrage-free smile).
+    const quantile = (pr) => {
+        if (!(pr > 0 && pr < 1)) {
+            throw new InputError(`${functionName}: quantile p must be in (0, 1); got ${String(pr)}.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { p: pr },
+            });
+        }
+        let lo = strikes[0];
+        let hi = strikes[gridPoints - 1];
+        for (let it = 0; it < 80; it++) {
+            const mid = 0.5 * (lo + hi);
+            if (bl.cdf(mid) < pr)
+                lo = mid;
+            else
+                hi = mid;
+        }
+        return 0.5 * (lo + hi);
+    };
+    // Diagnostics: grid-truncation (mass/mean drift) and residual butterfly arbitrage (non-monotone CDF).
+    const warnings = [];
+    if (Math.abs(totalMass - 1) > 1e-2) {
+        warnings.push(warning(WarningCode.ModelLimitation, `risk-neutral mass ∫f dK = ${totalMass.toFixed(4)} deviates from 1 by > 1% — widen the grid (widthStandardDeviations) or the smile is arbitrageable.`, 'warn', { totalMass }));
+    }
+    if (Math.abs(mean - F) / F > 1e-2) {
+        warnings.push(warning(WarningCode.ModelLimitation, `risk-neutral mean ${mean.toFixed(2)} deviates from the forward ${F} (the martingale property) by > 1% — the grid is too coarse/narrow or the smile is arbitrageable.`, 'warn', { mean, forward: F }));
+    }
+    let nonMonotone = false;
+    for (let i = 1; i < gridPoints; i++) {
+        if (cdfArr[i] < cdfArr[i - 1] - 1e-9) {
+            nonMonotone = true;
+            break;
+        }
+    }
+    if (nonMonotone) {
+        warnings.push(warning(WarningCode.ModelLimitation, `the implied CDF is non-monotone — the smile carries a butterfly arbitrage (a negative-density region); probabilities across it are clamped.`, 'warn', {}));
+    }
+    return {
+        density: bl.density,
+        cdf: bl.cdf,
+        probabilityBelow: bl.probabilityBelow,
+        probabilityAbove: bl.probabilityAbove,
+        probabilityBetween: bl.probabilityBetween,
+        quantile,
+        grid: { strikes, density: densityArr, cdf: cdfArr },
+        moments: { totalMass, mean, variance, stdev, skewness, excessKurtosis },
+        warnings,
+    };
+}
+/**
+ * The risk-neutral terminal distribution implied by the three vanna-volga quotes (ATM + δ-delta RR/BF).
+ * Builds the **Castagna–Mercurio** smile (the always-defined closed form — the exact {@link calibrateVannaVolga}
+ * breaks down across the wide strike grid a density needs) and applies **Breeden–Litzenberger** in forward
+ * space: the undiscounted forward Black call's strike derivatives are the risk-neutral density and CDF
+ * directly. Returns density/CDF/probability closures plus a sampled grid, the distribution's moments
+ * (mass ≈ 1, mean ≈ forward, variance, skewness, excess kurtosis), and an inverse CDF. A non-convex
+ * (butterfly ≤ 0) smile — where the CM curvature itself is undefined — is a typed error; a residual
+ * butterfly arbitrage (non-monotone CDF) or a grid-truncation mass/mean drift is a disclosed warning.
+ * See `docs/specs/vanna-volga-density.md`.
+ */
+export function vannaVolgaDensity(input) {
+    const functionName = 'vannaVolgaDensity';
+    requireArgumentObject(functionName, 'input', input);
+    ensureKnownKeys(functionName, 'input', input, VANNA_VOLGA_DENSITY_KEYS);
+    ensurePositive(input.forward, 'forward', functionName);
+    ensurePositive(input.timeToExpiryYears, 'timeToExpiryYears', functionName);
+    ensurePositive(input.atmVolatility, 'atmVolatility', functionName);
+    ensureFinite(input.riskReversal, 'riskReversal', functionName);
+    ensureFinite(input.butterfly, 'butterfly', functionName);
+    ensureFiniteWhenPresent(input.delta, 'delta', functionName);
+    ensureFiniteWhenPresent(input.order, 'order', functionName);
+    const delta = input.delta ?? 0.25;
+    const order = input.order ?? 2;
+    if (order !== 1 && order !== 2) {
+        throw new InputError(`${functionName}: order must be 1 or 2; got ${String(order)}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { order },
+        });
+    }
+    const F = input.forward;
+    const T = input.timeToExpiryYears;
+    const { gridPoints, widthStandardDeviations, step } = densityGridControls({
+        functionName,
+        forward: F,
+        gridPoints: input.gridPoints,
+        widthStandardDeviations: input.widthStandardDeviations,
+        step: input.step,
+    });
+    // Build the three pillars once; the per-strike vol comes from the private CM closed form.
+    const p = smileFromQuotes({
+        forward: F,
+        timeToExpiryYears: T,
+        atmVolatility: input.atmVolatility,
+        riskReversal: input.riskReversal,
+        butterfly: input.butterfly,
+        delta,
+    });
+    const [K1, K2, K3] = [p.putStrike, p.atmStrike, p.callStrike];
+    const [s1, s2, s3] = [p.putVolatility, p.atmVolatility, p.callVolatility];
+    const smile = (K) => castagnaMercurio({
+        order,
+        forward: F,
+        timeToExpiryYears: T,
+        strike: K,
+        putStrike: K1,
+        atmStrike: K2,
+        callStrike: K3,
+        putVolatility: s1,
+        atmVolatility: s2,
+        callVolatility: s3,
+    });
+    const strikes = densityGrid({
+        forward: F,
+        atmVolatility: input.atmVolatility,
+        timeToExpiryYears: T,
+        gridPoints,
+        widthStandardDeviations,
+    });
+    // Pre-scan the grid + the ±step stencil: a non-finite CM vol means the closed form's curvature √ turns
+    // negative there and the smile can't be represented — a clear typed error beats a NaN leaking downstream.
+    // A negative K−step (huge step) yields ln(F/negative) = NaN, so the finite check subsumes a K−step > 0 test.
+    const breakdown = [];
+    for (const K of strikes) {
+        if (![K - step, K, K + step].every((k) => Number.isFinite(smile(k)))) {
+            breakdown.push(K);
+        }
+    }
+    if (breakdown.length > 0) {
+        throw new InputError(`${functionName}: the Castagna–Mercurio smile is undefined at ${breakdown.length} grid strike(s) (e.g. ${breakdown
+            .slice(0, 3)
+            .map((k) => k.toFixed(2))
+            .join(', ')}) — its curvature can't be represented across the ±${widthStandardDeviations}σ grid (the risk reversal is too steep for the butterfly, or the butterfly is ≤ 0). Narrow the grid via widthStandardDeviations, or check the quotes.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { strikes: breakdown, pillarStrikes: [K1, K2, K3] },
+        });
+    }
+    const core = forwardMeasureDensity({
+        functionName,
+        smile,
+        forward: F,
+        timeToExpiryYears: T,
+        strikes,
+        step,
+    });
+    return {
+        density: core.density,
+        cdf: core.cdf,
+        probabilityBelow: core.probabilityBelow,
+        probabilityAbove: core.probabilityAbove,
+        probabilityBetween: core.probabilityBetween,
+        quantile: core.quantile,
+        grid: core.grid,
+        moments: core.moments,
+        pillars: {
+            putStrike: p.putStrike,
+            putVolatility: p.putVolatility,
+            atmStrike: p.atmStrike,
+            atmVolatility: p.atmVolatility,
+            callStrike: p.callStrike,
+            callVolatility: p.callVolatility,
+        },
+        order,
+        assumptions: {
+            conventionsVersion: CONVENTIONS_VERSION,
+            method: 'breeden-litzenberger',
+            smile: 'castagna-mercurio',
+            measure: 'risk-neutral-forward',
+            order,
+        },
+        diagnostics: {
+            engine: 'vanna-volga',
+            method: `breeden-litzenberger on castagna-mercurio order-${order}`,
+            converged: core.warnings.length === 0,
+            warnings: core.warnings,
+        },
+    };
+}
+/**
+ * The 5-pillar anchors + PCHIP-of-total-variance smile from the five-quote set. Validates the shared quote
+ * fields and delta ordering, builds the five `(strike, vol)` pillars via {@link smileFromQuotes} at each
+ * delta, asserts strictly-increasing pillar strikes, and returns the total-variance interpolant. Shared by
+ * {@link calibrateVannaVolga5} (strike evaluation + arbitrage scan) and {@link vannaVolga5Density} (density).
+ */
+function buildVanna5Smile(functionName, input) {
+    // The two public fronts validate their closed requests at the head (spec 3B.1b); what remains
+    // here is the shared DOMAIN residue: positivity, and the wing-delta ordering.
+    ensurePositive(input.forward, 'forward', functionName);
+    ensurePositive(input.timeToExpiryYears, 'timeToExpiryYears', functionName);
+    ensurePositive(input.atmVolatility, 'atmVolatility', functionName);
+    const innerDelta = input.innerDelta ?? 0.25;
+    const outerDelta = input.outerDelta ?? 0.1;
+    // Outer (10Δ) must be a further-OTM wing than inner (25Δ): 0 < outer < inner < 0.5.
+    if (!(outerDelta > 0 && outerDelta < innerDelta && innerDelta < 0.5)) {
+        throw new InputError(`${functionName}: require 0 < outerDelta < innerDelta < 0.5 (got outer ${outerDelta}, inner ${innerDelta}).`, { code: ErrorCode.InputOutOfRange, context: { innerDelta, outerDelta } });
+    }
+    const wingExtrapolation = input.wingExtrapolation ?? 'flat';
+    const F = input.forward;
+    const T = input.timeToExpiryYears;
+    // Five anchors: two `smileFromQuotes` (inner 25Δ, outer 10Δ), sharing the ATM.
+    const inner = smileFromQuotes({
+        forward: F,
+        timeToExpiryYears: T,
+        atmVolatility: input.atmVolatility,
+        riskReversal: input.riskReversal25,
+        butterfly: input.butterfly25,
+        delta: innerDelta,
+    });
+    const outer = smileFromQuotes({
+        forward: F,
+        timeToExpiryYears: T,
+        atmVolatility: input.atmVolatility,
+        riskReversal: input.riskReversal10,
+        butterfly: input.butterfly10,
+        delta: outerDelta,
+    });
+    const pillars = [
+        { strike: outer.putStrike, volatility: outer.putVolatility, delta: outerDelta, kind: 'put' },
+        { strike: inner.putStrike, volatility: inner.putVolatility, delta: innerDelta, kind: 'put' },
+        { strike: F, volatility: input.atmVolatility, delta: 0.5, kind: 'atm' },
+        { strike: inner.callStrike, volatility: inner.callVolatility, delta: innerDelta, kind: 'call' },
+        { strike: outer.callStrike, volatility: outer.callVolatility, delta: outerDelta, kind: 'call' },
+    ];
+    // The anchors must be strictly increasing in strike for the interpolation to be well-posed.
+    for (let i = 1; i < pillars.length; i++) {
+        if (!(pillars[i].strike > pillars[i - 1].strike)) {
+            throw new InputError(`${functionName}: the quotes imply non-monotone pillar strikes (${pillars
+                .map((p) => p.strike.toFixed(2))
+                .join(', ')}) — the 10Δ/25Δ wings cross; check the quotes.`, { code: ErrorCode.InputOutOfRange, context: { strikes: pillars.map((p) => p.strike) } });
+        }
+    }
+    // PCHIP of total variance w(k) = σ²T against log-moneyness k = ln(K/F): exact at the pillars, C¹, no
+    // overshoot. Total-variance space gives the arbitrage-aware linear wing extrapolation.
+    const ks = pillars.map((p) => Math.log(p.strike / F));
+    const ws = pillars.map((p) => p.volatility * p.volatility * T);
+    const wOf = makePchipInterpolator(ks, ws, { extrapolate: wingExtrapolation });
+    const varAt = (K) => wOf(Math.log(K / F));
+    return { pillars, varAt, innerDelta, outerDelta, wingExtrapolation };
+}
+/**
+ * Build the FX/crypto smile from the full five-quote set — ATM + the 25Δ and 10Δ risk reversal / butterfly —
+ * so it **exactly reprices all five market pillars** (10Δ put, 25Δ put, ATM, 25Δ call, 10Δ call) and pins the
+ * wings to real quotes instead of extrapolating them like the 3-pillar {@link calibrateVannaVolga} /
+ * {@link vannaVolgaApproximation}. The anchors come from {@link smileFromQuotes} at each delta; the smile is a
+ * shape-preserving PCHIP interpolation of total variance `σ²T` in log-moneyness (exact at the pillars, C¹
+ * smooth, no overshoot). Exact repricing of arbitrary quotes can't guarantee no arbitrage, so the implied
+ * Breeden–Litzenberger density is checked across the pillar span and a butterfly arbitrage is a disclosed
+ * warning. See `docs/specs/vanna-volga-5.md`.
+ */
+export function calibrateVannaVolga5(input) {
+    const functionName = 'calibrateVannaVolga5';
+    validateClosedRequest(functionName, input, CALIBRATE_VANNA_VOLGA_5_SPEC, {
+        exampleCall: CALIBRATE_VANNA_VOLGA_5_EXAMPLE,
+    });
+    if (input.strikes.length === 0) {
+        throw new InputError(`${functionName}: strikes must be a non-empty array.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { strikes: 0 },
+        });
+    }
+    input.strikes.forEach((K, i) => ensurePositive(K, `strikes[${i}]`, functionName));
+    const { pillars, varAt, innerDelta, outerDelta, wingExtrapolation } = buildVanna5Smile(functionName, input);
+    const F = input.forward;
+    const T = input.timeToExpiryYears;
+    const volatilities = new Array(input.strikes.length);
+    const nonPositiveVar = [];
+    input.strikes.forEach((K, i) => {
+        const w = varAt(K);
+        if (!(w > 0)) {
+            nonPositiveVar.push(K);
+            return;
+        }
+        volatilities[i] = Math.sqrt(w / T);
+    });
+    if (nonPositiveVar.length > 0) {
+        throw new InputError(`${functionName}: the linear wing extrapolation drove total variance ≤ 0 at ${nonPositiveVar.length} strike(s) (${nonPositiveVar
+            .map((k) => k.toFixed(2))
+            .join(', ')}) — query strikes nearer the pillars or use wingExtrapolation: 'flat'.`, { code: ErrorCode.InputOutOfRange, context: { strikes: nonPositiveVar } });
+    }
+    // Butterfly-arbitrage diagnostic: the implied Breeden–Litzenberger density must stay ≥ 0 where the quotes
+    // determine the smile. Exact repricing of arbitrary quotes can't guarantee it — an over-convex butterfly
+    // makes the call-price curve locally concave (negative density). Surface it rather than return a silently-
+    // arbitrageable smile. The scan is the *interior* (loK+2h, hiK-2h): a stencil straddling an outer knot,
+    // where the flat/linear wing extrapolation meets the curve, picks up that slope kink as a spurious density
+    // spike, not a genuine arbitrage — and the constant-vol wings are individually arbitrage-free anyway.
+    const warnings = [];
+    const volatilityOf = (K) => Math.sqrt(Math.max(varAt(K), 1e-12) / T);
+    const h = F * 1e-3;
+    const callAt = (K) => blackScholesPrice({
+        type: 'call',
+        spot: F,
+        strike: K,
+        timeToExpiryYears: T,
+        riskFreeRate: 0,
+        dividendYield: 0,
+        volatility: volatilityOf(K),
+    });
+    const scanLo = pillars[0].strike + 2 * h;
+    const scanHi = pillars[pillars.length - 1].strike - 2 * h;
+    const steps = 200;
+    let minDensity = Infinity;
+    for (let i = 0; i <= steps; i++) {
+        const K = scanLo + ((scanHi - scanLo) * i) / steps;
+        const d = (callAt(K + h) - 2 * callAt(K) + callAt(K - h)) / (h * h);
+        if (d < minDensity)
+            minDensity = d;
+    }
+    if (minDensity < -1e-6) {
+        warnings.push(warning(WarningCode.ModelLimitation, `the quoted pillars imply a butterfly arbitrage — the implied risk-neutral density goes negative (min ${minDensity.toExponential(2)}) between the pillars; the smile reprices the quotes but is not arbitrage-free. Use calibrateSsvi/ESSVI for a guaranteed arb-free surface.`, 'warn', { minDensity }));
+    }
+    return {
+        strikes: [...input.strikes],
+        volatilities,
+        pillars,
+        innerDelta,
+        outerDelta,
+        assumptions: {
+            conventionsVersion: CONVENTIONS_VERSION,
+            method: 'vanna-volga-5',
+            deltaConvention: 'forward',
+            interpolation: 'pchip-total-variance',
+            wingExtrapolation,
+        },
+        diagnostics: {
+            engine: 'vanna-volga',
+            method: 'pchip total-variance through 5 pillars',
+            converged: warnings.length === 0,
+            warnings,
+        },
+    };
+}
+/**
+ * The risk-neutral terminal distribution implied by the **five**-pillar vanna-volga smile (ATM + 25Δ + 10Δ
+ * RR/BF) — the {@link vannaVolgaDensity} read-out (PDF / CDF / quantiles / probability-in-range / moments),
+ * but with the core `[10Δ put, 10Δ call]` range (where most probability mass sits) pinned to real quotes
+ * instead of extrapolated from three. Builds the {@link calibrateVannaVolga5} PCHIP smile and applies
+ * **Breeden–Litzenberger** in forward space via the shared density core. The wing is extrapolated **linearly**
+ * in total variance (C¹ at the 10Δ knots, so the density stays smooth — a `flat` wing would put a spurious
+ * kink-spike in the density at the interior 10Δ knots); a down-sloping wing that drives total variance ≤ 0 on
+ * the grid is a typed error. See `docs/specs/vanna-volga-5-density.md`.
+ */
+export function vannaVolga5Density(input) {
+    const functionName = 'vannaVolga5Density';
+    validateClosedRequest(functionName, input, VANNA_VOLGA_5_DENSITY_SPEC, {
+        exampleCall: VANNA_VOLGA_5_DENSITY_EXAMPLE,
+    });
+    const F = input.forward;
+    ensurePositive(F, 'forward', functionName);
+    const T = input.timeToExpiryYears;
+    const { gridPoints, widthStandardDeviations, step } = densityGridControls({
+        functionName,
+        forward: F,
+        gridPoints: input.gridPoints,
+        widthStandardDeviations: input.widthStandardDeviations,
+        step: input.step,
+    });
+    // Build the 5-pillar smile once, with a linear (C¹) wing so the density stays smooth at the 10Δ knots.
+    const { pillars, varAt, innerDelta, outerDelta } = buildVanna5Smile(functionName, {
+        ...input,
+        wingExtrapolation: 'linear',
+    });
+    const smile = (K) => Math.sqrt(Math.max(varAt(K), 0) / T);
+    const strikes = densityGrid({
+        forward: F,
+        atmVolatility: input.atmVolatility,
+        timeToExpiryYears: T,
+        gridPoints,
+        widthStandardDeviations,
+    });
+    // Pre-scan the grid + stencil: a linear wing on a down-sloping smile can drive total variance ≤ 0 far out.
+    const nonPositiveVar = [];
+    for (const K of strikes) {
+        if (![K - step, K, K + step].every((k) => varAt(k) > 0)) {
+            nonPositiveVar.push(K);
+        }
+    }
+    if (nonPositiveVar.length > 0) {
+        throw new InputError(`${functionName}: the linear wing extrapolation drove total variance ≤ 0 at ${nonPositiveVar.length} grid strike(s) (e.g. ${nonPositiveVar
+            .slice(0, 3)
+            .map((k) => k.toFixed(2))
+            .join(', ')}) — a wing too steep for the ±${widthStandardDeviations}σ grid. Narrow the grid via widthStandardDeviations, or check the quotes.`, { code: ErrorCode.InputOutOfRange, context: { strikes: nonPositiveVar } });
+    }
+    const core = forwardMeasureDensity({
+        functionName,
+        smile,
+        forward: F,
+        timeToExpiryYears: T,
+        strikes,
+        step,
+    });
+    return {
+        density: core.density,
+        cdf: core.cdf,
+        probabilityBelow: core.probabilityBelow,
+        probabilityAbove: core.probabilityAbove,
+        probabilityBetween: core.probabilityBetween,
+        quantile: core.quantile,
+        grid: core.grid,
+        moments: core.moments,
+        pillars,
+        innerDelta,
+        outerDelta,
+        assumptions: {
+            conventionsVersion: CONVENTIONS_VERSION,
+            method: 'breeden-litzenberger',
+            smile: 'vanna-volga-5',
+            measure: 'risk-neutral-forward',
+        },
+        diagnostics: {
+            engine: 'vanna-volga',
+            method: 'breeden-litzenberger on vanna-volga-5',
+            converged: core.warnings.length === 0,
+            warnings: core.warnings,
+        },
+    };
+}
+//# sourceMappingURL=vanna-volga.js.map