@insiderfinance/totalfinance 0.1.0

package/modules/volatility/dist/ssvi.js

@@ -0,0 +1,490 @@
+/**
+ * SSVI — the Gatheral–Jacquier surface SVI (spec: `docs/specs/ssvi-surface.md`, roadmap Tier 2). Where
+ * `calibrateSvi` fits one smile at a time (and independent slices can cross in maturity, an arbitrage the
+ * per-slice fit can't see), SSVI parametrizes the WHOLE surface with the ATM total-variance term
+ * structure `θ(t)`, a global skew `ρ`, and a curvature function `φ(θ)` — and is free of calendar
+ * arbitrage by construction whenever `θ(t)` is non-decreasing.
+ *
+ *   w(k, θ) = (θ/2)·[ 1 + ρ·φ(θ)·k + √((φ(θ)·k + ρ)² + (1 − ρ²)) ],   θ = σ_ATM(t)²·t
+ *
+ * SSVI at a fixed θ IS a raw-SVI slice, so evaluation and the Gatheral-`g` butterfly density test reuse
+ * `./svi.ts` rather than re-deriving them.
+ */
+import { CONVENTIONS_VERSION, ErrorCode, InputError, ensureFinite, ensureKnownKeys, requireArgumentArray, requireArgumentObject, validateClosedRequest, warning, WarningCode, } from '../../core/dist/index.js';
+import { nelderMead, normalPdf } from '../../math/dist/index.js';
+import { sviMinG } from './svi.js';
+import { requireCalibrationIterationBudget } from './calibration-limits.js';
+import { requireSsviStart } from './calibration-start.js';
+import { phiValueUnchecked, requirePhi, ssviSliceWUnchecked, ssviToSviUnchecked, } from './ssvi-kernel.js';
+import { VALIDATION_SPECS } from './generated/validation-specs.js';
+/**
+ * Per-point least-squares weights for a set of prepared slices: `1` (uniform) or the Black vega
+ * `φ(d₁)·√t` at the market vol `σ = √(w/t)` (vega). The weights depend only on the market data, so they are
+ * computed once and held fixed across the calibration search. A degenerate point (`w ≤ 0`) gets weight 0.
+ */
+export function calibrationWeights(slices, weight) {
+    requireArgumentArray('calibrationWeights', 'slices', slices);
+    return slices.map((sl, i) => {
+        requireArgumentObject('calibrationWeights', `slices[${i}]`, sl);
+        requireArgumentArray('calibrationWeights', `slices[${i}].k`, sl.k);
+        requireArgumentArray('calibrationWeights', `slices[${i}].w`, sl.w);
+        return sl.k.map((k, j) => {
+            if (weight === 'uniform')
+                return 1;
+            const wj = sl.w[j];
+            if (!(wj > 0))
+                return 0;
+            const sqrtT = Math.sqrt(sl.timeToExpiryYears);
+            const sigma = Math.sqrt(wj / sl.timeToExpiryYears);
+            const d1 = -k / (sigma * sqrtT) + 0.5 * sigma * sqrtT;
+            return normalPdf(d1) * sqrtT;
+        });
+    });
+}
+// ─────────────────────────────── core ───────────────────────────────
+/**
+ * Generated closed-request specs (spec 3B.1b): allowlists projected from the declarations.
+ * Resolved at module load so a stale key fails at import.
+ */
+function ssviSpecOf(key) {
+    const spec = VALIDATION_SPECS[key];
+    if (spec === undefined) {
+        throw new Error(`ssvi: no generated validation spec for '${key}' — run \`pnpm validation:update\``);
+    }
+    return spec;
+}
+const CALIBRATE_SSVI_SURFACE_SPEC = ssviSpecOf('calibrateSsvi#0');
+const CALIBRATE_SSVI_OPTIONS_SPEC = ssviSpecOf('calibrateSsvi#1');
+const PREPARE_SLICES_SPEC = ssviSpecOf('prepareSlices#0');
+const SSVI_ARBITRAGE_PARAMETERS_SPEC = ssviSpecOf('ssviArbitrageFree#0');
+const SSVI_ARBITRAGE_OPTIONS_SPEC = ssviSpecOf('ssviArbitrageFree#1');
+const PHI_VALUE_SPEC = ssviSpecOf('phiValue#0');
+const SSVI_SLICE_SPEC = ssviSpecOf('ssviSliceW#0');
+const SSVI_TO_SVI_SPEC = ssviSpecOf('ssviToSVI#0');
+const SSVI_TOTAL_VARIANCE_SPEC = ssviSpecOf('ssviTotalVariance#0');
+const SSVI_VOLATILITY_SPEC = ssviSpecOf('ssviVolatility#0');
+/** A runnable diagnosis call — `ssviArbitrageFree` takes (parameters, options?), not (…, k, t). */
+const SSVI_ARBITRAGE_EXAMPLE = () => "ssviArbitrageFree({ rho: -0.3, phi: { kind: 'power-law', eta: 1.0, gamma: 0.5 }, " +
+    'thetaTerm: [{ timeToExpiryYears: 1, theta: 0.04 }] })';
+/** A runnable surface-calibration call, complete enough to satisfy every fitting precondition. */
+function calibrationExampleCall(functionName) {
+    return (`${functionName}({ slices: [` +
+        '{ timeToExpiryYears: 0.25, k: [-0.1, 0, 0.1], impliedVolatility: [0.22, 0.2, 0.21] }, ' +
+        '{ timeToExpiryYears: 0.5, k: [-0.1, 0, 0.1], impliedVolatility: [0.23, 0.21, 0.22] }] })');
+}
+/**
+ * Evaluate the curvature `φ(θ)`. Shared with `./essvi.ts` (the eSSVI extension) so the two use one
+ * definition. The unguarded arithmetic lives in `./ssvi-kernel.ts`, which the grid sweeps call.
+ *
+ * 3B.1b STOP: `phiValue#0`'s generated spec collapses the `SSVIPhi` union to its shared `kind`
+ * field (a top-level spec carries no branches), so enforcing it would reject the union's own
+ * `eta`/`gamma`/`lambda` as unknown fields. `requirePhi` remains the validation head here.
+ */
+export function phiValue(phi, theta) {
+    // The generated union spec closes each phi branch's key set (the unknown-key conviction);
+    // requirePhi keeps its curated discriminant-first teaching beneath it.
+    validateClosedRequest('phiValue', phi, PHI_VALUE_SPEC, {
+        argumentName: 'phi',
+        exampleCall: "phiValue({ kind: 'power-law', eta: 1, gamma: 0.5 }, 0.04)",
+    });
+    requirePhi(phi, 'phiValue');
+    ensureFinite(theta, 'theta', 'phiValue');
+    return phiValueUnchecked(phi, theta);
+}
+const SSVI_SLICE_EXAMPLE_CALL = 'ssviSliceW({ k: 0, theta: 0.04, rho: -0.3, psi: 1 })';
+const SSVI_SLICE_HINTS = {
+    k: 'log-moneyness ln(K/F)',
+    theta: 'ATM total variance at this maturity',
+    rho: 'global skew, in (-1, 1)',
+    psi: 'curvature phi(theta)',
+};
+/** SSVI total variance at a fixed θ (the raw SSVI slice function). Shared with `./essvi.ts`. */
+export function ssviSliceW(input) {
+    validateClosedRequest('ssviSliceW', input, SSVI_SLICE_SPEC, {
+        exampleCall: SSVI_SLICE_EXAMPLE_CALL,
+        hints: SSVI_SLICE_HINTS,
+    });
+    const { k, theta, rho, psi } = input;
+    return ssviSliceWUnchecked({ k, theta, rho, psi });
+}
+export function ssviToSVI(input) {
+    validateClosedRequest('ssviToSVI', input, SSVI_TO_SVI_SPEC, {
+        exampleCall: 'ssviToSVI({ theta: 0.04, rho: -0.3, psi: 1 })',
+    });
+    return ssviToSviUnchecked(input);
+}
+/**
+ * Interpolate `θ(t)` linearly in `t` from the knots; `θ(0)=0`, flat beyond the last knot (constant total
+ * variance — a decreasing vol). Monotone knots ⇒ monotone `θ(t)` ⇒ the time interpolation stays
+ * calendar-arbitrage-free. Shared with `./essvi.ts` (its richer `{t,theta,rho}` knots are assignable).
+ */
+export function thetaAt(thetaTerm, timeToExpiryYears) {
+    requireArgumentArray('thetaAt', 'thetaTerm', thetaTerm);
+    const n = thetaTerm.length;
+    if (n === 0) {
+        throw new InputError('thetaAt: thetaTerm must have at least one knot.', {
+            code: ErrorCode.InputOutOfRange,
+            context: { knots: 0 },
+        });
+    }
+    const first = thetaTerm[0];
+    if (timeToExpiryYears <= first.timeToExpiryYears)
+        return (first.theta * timeToExpiryYears) / first.timeToExpiryYears;
+    const last = thetaTerm[n - 1];
+    if (timeToExpiryYears >= last.timeToExpiryYears)
+        return last.theta;
+    for (let i = 1; i < n; i++) {
+        const hi = thetaTerm[i];
+        if (timeToExpiryYears <= hi.timeToExpiryYears) {
+            const lo = thetaTerm[i - 1];
+            const frac = (timeToExpiryYears - lo.timeToExpiryYears) / (hi.timeToExpiryYears - lo.timeToExpiryYears);
+            return lo.theta + frac * (hi.theta - lo.theta);
+        }
+    }
+    return last.theta;
+}
+/** A runnable call to the FAILING evaluator, with a complete SSVI parameter object. */
+function surfaceExampleCall(functionName) {
+    return (`${functionName}({ rho: -0.3, phi: { kind: 'power-law', eta: 1.0, gamma: 0.5 }, ` +
+        'thetaTerm: [{ timeToExpiryYears: 1, theta: 0.04 }] }, 0, 1)');
+}
+/**
+ * The domain residue the generated spec cannot express: at least one θ-knot. Shape, presence,
+ * field types, finiteness, the φ union's branches, and closedness are the spec head's job.
+ */
+function requireThetaKnots(parameters, functionName) {
+    if (parameters.thetaTerm.length === 0) {
+        throw new InputError(`${functionName}: parameters.thetaTerm must have at least one knot.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { knots: 0 },
+        });
+    }
+}
+/** Total implied variance `w(k, t)` on a calibrated SSVI surface. */
+export function ssviTotalVariance(parameters, k, timeToExpiryYears) {
+    const functionName = 'ssviTotalVariance';
+    validateClosedRequest(functionName, parameters, SSVI_TOTAL_VARIANCE_SPEC, {
+        argumentName: 'parameters',
+        exampleCall: () => surfaceExampleCall(functionName),
+    });
+    requireThetaKnots(parameters, functionName);
+    ensureFinite(k, 'k', functionName);
+    if (!(timeToExpiryYears > 0)) {
+        throw new InputError(`${functionName}: timeToExpiryYears must be positive; got ${timeToExpiryYears}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { timeToExpiryYears },
+        });
+    }
+    const theta = thetaAt(parameters.thetaTerm, timeToExpiryYears);
+    return ssviSliceWUnchecked({
+        k,
+        theta,
+        rho: parameters.rho,
+        psi: phiValueUnchecked(parameters.phi, theta),
+    });
+}
+/** Implied volatility `√(w/t)` on a calibrated SSVI surface. */
+export function ssviVolatility(parameters, k, timeToExpiryYears) {
+    validateClosedRequest('ssviVolatility', parameters, SSVI_VOLATILITY_SPEC, {
+        argumentName: 'parameters',
+        exampleCall: () => surfaceExampleCall('ssviVolatility'),
+    });
+    return Math.sqrt(ssviTotalVariance(parameters, k, timeToExpiryYears) / timeToExpiryYears);
+}
+const DEFAULT_G_GRID = Array.from({ length: 81 }, (_, i) => -1 + (2 * i) / 80);
+/**
+ * Diagnose the no-arbitrage status of an SSVI surface: calendar (θ non-decreasing + the ∂_θ(θφ) bound)
+ * and butterfly (the exact Gatheral `g ≥ 0` density test at every θ-knot, plus the Gatheral–Jacquier
+ * sufficient conditions). See the spec.
+ */
+export function ssviArbitrageFree(parameters, options = {}) {
+    const functionName = 'ssviArbitrageFree';
+    validateClosedRequest(functionName, parameters, SSVI_ARBITRAGE_PARAMETERS_SPEC, {
+        argumentName: 'parameters',
+        exampleCall: SSVI_ARBITRAGE_EXAMPLE,
+    });
+    validateClosedRequest(functionName, options, SSVI_ARBITRAGE_OPTIONS_SPEC, {
+        argumentName: 'options',
+        exampleCall: SSVI_ARBITRAGE_EXAMPLE,
+    });
+    requireThetaKnots(parameters, functionName);
+    const grid = options.grid ?? DEFAULT_G_GRID;
+    const { rho, phi, thetaTerm } = parameters;
+    // Calendar: θ strictly increasing across the knots.
+    let calendar = true;
+    for (let i = 1; i < thetaTerm.length; i++) {
+        if (!(thetaTerm[i].theta >= thetaTerm[i - 1].theta))
+            calendar = false;
+    }
+    // Calendar (φ side): 0 ≤ ∂_θ(θφ) ≤ (1/ρ²)(1+√(1−ρ²))·φ(θ) at each knot (auto-pass for ρ=0).
+    const bound = rho === 0 ? Infinity : (1 / (rho * rho)) * (1 + Math.sqrt(1 - rho * rho));
+    for (const knot of thetaTerm) {
+        const th = knot.theta;
+        const h = Math.max(1e-7, 1e-5 * th);
+        const dThetaPhi = ((th + h) * phiValueUnchecked(phi, th + h) - (th - h) * phiValueUnchecked(phi, th - h)) /
+            (2 * h);
+        const phiTh = phiValueUnchecked(phi, th);
+        if (!(dThetaPhi >= -1e-9 && dThetaPhi <= bound * phiTh + 1e-9))
+            calendar = false;
+    }
+    // Butterfly: exact g ≥ 0 on the reduced SVI slice at each knot + GJ sufficient conditions.
+    let minG = Infinity;
+    let butterfly = true;
+    let sufficient = true;
+    for (const knot of thetaTerm) {
+        const psi = phiValueUnchecked(phi, knot.theta);
+        // Unchecked kernel: the surface was validated at this head; re-validating per knot is 3B.1b-1.
+        const svi = ssviToSviUnchecked({ theta: knot.theta, rho, psi });
+        // ONE sweep. `sviButterflyFree` is `sviMinG(...) >= -1e-8`, so calling both walked the same grid
+        // twice per knot to compute a boolean already implied by the number.
+        const knotMinG = sviMinG(svi, grid);
+        if (!(knotMinG >= -1e-8))
+            butterfly = false;
+        minG = Math.min(minG, knotMinG);
+        const c1 = knot.theta * psi * (1 + Math.abs(rho));
+        const c2 = knot.theta * psi * psi * (1 + Math.abs(rho));
+        if (!(c1 < 4 && c2 <= 4))
+            sufficient = false;
+    }
+    return {
+        calendarArbitrageFree: calendar,
+        butterflyArbitrageFree: butterfly,
+        minButterflyG: minG,
+        sufficientConditionsHold: sufficient,
+    };
+}
+// ─────────────────────────────── calibration ───────────────────────────────
+/** Linear interpolation of the (k, w) points evaluated at k = 0 (the ATM total variance). Shared with `./essvi.ts`. */
+export function atmTotalVariance(k, w) {
+    requireArgumentArray('atmTotalVariance', 'k', k);
+    requireArgumentArray('atmTotalVariance', 'w', w);
+    // Sort by k, then linear-interpolate at 0 (flat-extrapolate outside the range).
+    const idx = k.map((_, i) => i).sort((a, b) => k[a] - k[b]);
+    const ks = idx.map((i) => k[i]);
+    const ws = idx.map((i) => w[i]);
+    if (0 <= ks[0])
+        return ws[0];
+    const n = ks.length;
+    if (0 >= ks[n - 1])
+        return ws[n - 1];
+    for (let i = 1; i < n; i++) {
+        if (0 <= ks[i]) {
+            const frac = (0 - ks[i - 1]) / (ks[i] - ks[i - 1]);
+            return ws[i - 1] + frac * (ws[i] - ws[i - 1]);
+        }
+    }
+    return ws[n - 1];
+}
+/**
+ * Validate + resolve each slice's total variances (`w` or `iv²·t`), compute its ATM θ, and sort by
+ * maturity. Shared with `./essvi.ts`, whose calibration input is the same `{ slices }` shape.
+ */
+export function prepareSlices(input, functionName) {
+    if (typeof functionName !== 'string' || functionName.length === 0) {
+        throw new InputError(`prepareSlices: functionName must be a non-empty string naming the calling boundary. Received ${functionName === null ? 'null' : functionName === undefined ? 'undefined' : typeof functionName}.`, { code: ErrorCode.InputWrongType, context: { field: 'functionName' } });
+    }
+    // The spec enforces `slices`' presence (its omit-required conviction was genuine) and the closed
+    // key set; everything per-slice below stays curated teaching the spec cannot express.
+    validateClosedRequest(functionName, input, PREPARE_SLICES_SPEC, {
+        argumentName: 'surface',
+        subject: true,
+        exampleCall: () => calibrationExampleCall(functionName),
+    });
+    const slices = input.slices;
+    if (slices.length < 2) {
+        throw new InputError(`${functionName}: need ≥ 2 maturity slices to fit a surface; got ${slices.length}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { slices: slices.length },
+        });
+    }
+    const prepared = [];
+    for (let s = 0; s < slices.length; s++) {
+        const slice = slices[s];
+        requireArgumentObject(functionName, `slices[${s}]`, slice);
+        ensureKnownKeys(functionName, `slices[${s}]`, slice, [
+            'timeToExpiryYears',
+            'k',
+            'w',
+            'impliedVolatility',
+        ]);
+        if (!(slice.timeToExpiryYears > 0)) {
+            throw new InputError(`${functionName}: slices[${s}].t must be positive; got ${slice.timeToExpiryYears}.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { index: s, timeToExpiryYears: slice.timeToExpiryYears },
+            });
+        }
+        requireArgumentArray(functionName, `slices[${s}].k`, slice.k);
+        const k = slice.k;
+        let w;
+        if (slice.w !== undefined) {
+            requireArgumentArray(functionName, `slices[${s}].w`, slice.w);
+            w = slice.w;
+        }
+        else if (slice.impliedVolatility !== undefined) {
+            requireArgumentArray(functionName, `slices[${s}].impliedVolatility`, slice.impliedVolatility);
+            w = slice.impliedVolatility.map((v) => v * v * slice.timeToExpiryYears);
+        }
+        else {
+            throw new InputError(`${functionName}: slices[${s}] must provide w or impliedVolatility.`, {
+                code: ErrorCode.InputMissingField,
+                context: { index: s },
+            });
+        }
+        if (k.length !== w.length) {
+            throw new InputError(`${functionName}: slices[${s}] k and w/impliedVolatility must have the same length (${k.length} vs ${w.length}).`, { code: ErrorCode.InputOutOfRange, context: { index: s, k: k.length, w: w.length } });
+        }
+        if (k.length < 3) {
+            throw new InputError(`${functionName}: slices[${s}] needs ≥ 3 points; got ${k.length}.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { index: s, points: k.length },
+            });
+        }
+        for (let j = 0; j < k.length; j++) {
+            ensureFinite(k[j], `slices[${s}].k[${j}]`, functionName);
+            ensureFinite(w[j], `slices[${s}].w[${j}]`, functionName);
+            if (!(w[j] > 0)) {
+                throw new InputError(`${functionName}: total variance must be positive; slices[${s}].w[${j}] = ${w[j]}.`, {
+                    code: ErrorCode.InputOutOfRange,
+                    context: { index: s, j, w: w[j] },
+                });
+            }
+        }
+        prepared.push({
+            timeToExpiryYears: slice.timeToExpiryYears,
+            k,
+            w,
+            theta: atmTotalVariance(k, w),
+        });
+    }
+    prepared.sort((a, b) => a.timeToExpiryYears - b.timeToExpiryYears);
+    return prepared;
+}
+/**
+ * Fit a calendar-arbitrage-free SSVI surface to a market total-variance surface: θ knots from each
+ * slice's ATM variance (made monotone), then a global `ρ` and `φ`-parameters by least squares. See the
+ * spec.
+ */
+export function calibrateSsvi(surface, options = {}) {
+    const functionName = 'calibrateSsvi';
+    validateClosedRequest(functionName, surface, CALIBRATE_SSVI_SURFACE_SPEC, {
+        argumentName: 'surface',
+        subject: true,
+        exampleCall: () => calibrationExampleCall(functionName),
+    });
+    validateClosedRequest(functionName, options, CALIBRATE_SSVI_OPTIONS_SPEC, {
+        argumentName: 'options',
+        exampleCall: () => calibrationExampleCall(functionName),
+    });
+    requireCalibrationIterationBudget(functionName, options.maximumIterations);
+    const phiKind = options.phi ?? 'power-law';
+    const weightMode = options.weight ?? 'uniform';
+    const start = options.initialParameters;
+    if (start !== undefined)
+        requireSsviStart(functionName, start, phiKind);
+    const prepared = prepareSlices(surface, functionName);
+    const warnings = [];
+    // Enforce a non-decreasing θ term structure (calendar-arb-free by construction). A non-monotone raw
+    // ATM structure is a data arbitrage — clamp to the running max and disclose.
+    let clamped = false;
+    let runningMax = 0;
+    const thetaTerm = prepared.map((p) => {
+        let theta = p.theta;
+        if (theta < runningMax) {
+            theta = runningMax;
+            clamped = true;
+        }
+        runningMax = theta;
+        return { timeToExpiryYears: p.timeToExpiryYears, theta };
+    });
+    if (clamped) {
+        warnings.push(warning(WarningCode.VolatilitySsviCalendarData, `${functionName}: the raw ATM total-variance term structure was not non-decreasing (a calendar arbitrage in the data) — it was clamped to its increasing hull to keep the surface arbitrage-free.`, 'warn'));
+    }
+    // Objective: (optionally vega-)weighted SSE of SSVI vs market total variance, with the θ knots fixed.
+    // The weights use the market data only, so they are fixed across the search.
+    const weights = calibrationWeights(prepared, weightMode);
+    const thetas = thetaTerm.map((t) => t.theta);
+    const buildPhi = (x) => phiKind === 'power-law'
+        ? { kind: 'power-law', eta: x[1], gamma: x[2] }
+        : { kind: 'heston', lambda: x[1] };
+    const feasible = (x) => {
+        if (!(Math.abs(x[0]) < 0.999))
+            return false;
+        if (phiKind === 'power-law')
+            return x[1] > 1e-6 && x[2] > 1e-4 && x[2] < 0.9999;
+        return x[1] > 1e-6;
+    };
+    const sse = (x) => {
+        if (!feasible(x))
+            return 1e12;
+        const rho = x[0];
+        const phi = buildPhi(x);
+        let s = 0;
+        for (let i = 0; i < prepared.length; i++) {
+            const psi = phiValueUnchecked(phi, thetas[i]);
+            const sl = prepared[i];
+            const wt = weights[i];
+            for (let j = 0; j < sl.k.length; j++) {
+                const difference = ssviSliceWUnchecked({ k: sl.k[j], theta: thetas[i], rho, psi }) - sl.w[j];
+                s += wt[j] * difference * difference;
+            }
+        }
+        return s;
+    };
+    const x0 = start !== undefined
+        ? start.phi.kind === 'power-law'
+            ? [start.rho, start.phi.eta, start.phi.gamma]
+            : [start.rho, start.phi.lambda]
+        : phiKind === 'power-law'
+            ? [-0.2, 1.0, 0.5]
+            : [-0.2, 1.0];
+    const res = nelderMead(sse, x0, {
+        maximumIterations: options.maximumIterations ?? 1000,
+        tolerance: options.tolerance ?? 1e-12,
+    });
+    const rho = res.argMin[0];
+    const phi = buildPhi(res.argMin);
+    const parameters = { rho, phi, thetaTerm };
+    // RMSE overall + per slice.
+    let totalSq = 0;
+    let totalN = 0;
+    const perSliceRmse = prepared.map((sl, i) => {
+        const psi = phiValueUnchecked(phi, thetas[i]);
+        let sq = 0;
+        for (let j = 0; j < sl.k.length; j++) {
+            const difference = ssviSliceWUnchecked({ k: sl.k[j], theta: thetas[i], rho, psi }) - sl.w[j];
+            sq += difference * difference;
+        }
+        totalSq += sq;
+        totalN += sl.k.length;
+        return { timeToExpiryYears: sl.timeToExpiryYears, rmse: Math.sqrt(sq / sl.k.length) };
+    });
+    const rmse = Math.sqrt(totalSq / totalN);
+    const arbitrage = ssviArbitrageFree(parameters);
+    if (!arbitrage.butterflyArbitrageFree) {
+        warnings.push(warning(WarningCode.VolatilitySsviButterfly, `${functionName}: the calibrated surface has butterfly arbitrage at one or more maturities (min Gatheral g = ${arbitrage.minButterflyG.toFixed(4)} < 0) — the market data likely embeds it; treat the wings with caution.`, 'warn'));
+    }
+    if (!res.converged) {
+        warnings.push(warning(WarningCode.VolatilitySsviNotConverged, `${functionName}: the calibration search stopped without converging; treat the fit as approximate.`, 'warn'));
+    }
+    return {
+        parameters,
+        rmse,
+        perSliceRmse,
+        arbitrage,
+        converged: res.converged,
+        assumptions: {
+            conventionsVersion: CONVENTIONS_VERSION,
+            phi: phiKind,
+            weight: weightMode,
+            initialParameters: start !== undefined ? 'supplied' : 'default',
+        },
+        diagnostics: {
+            engine: 'ssvi',
+            method: `nelder-mead + ${phiKind}`,
+            converged: res.converged,
+            iterations: res.iterations,
+            warnings,
+        },
+    };
+}
+//# sourceMappingURL=ssvi.js.map

package/modules/volatility/dist/ssvi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssvi.js","sourceRoot":"","sources":["../src/ssvi.ts"],"names":[],"mappings":"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"}

package/modules/volatility/dist/sticky-regime.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Sticky-strike vs sticky-delta regime measurement (spec: `docs/specs/sticky-regime.md`, roadmap Tier 2).
+ * When spot moves, does the smile stay put on strikes or slide with the spot? `minimumVarianceDelta`
+ * *assumes* that regime; `stickyRegime` *measures* it — regressing a fixed reference strike's implied-vol
+ * changes on spot log-returns to get the vol-spot beta `β = ∂σ_K/∂lnS`, then placing the market on the
+ * sticky-strike (`β=0`) ↔ sticky-moneyness (`β=−skewSlope`) axis.
+ */
+import { type Diagnostics } from '../../core/dist/index.js';
+/** Inputs for {@link stickyRegime}. */
+export interface StickyRegimeInput {
+    /** Per-observation underlying spot, aligned to `fixedStrikeVolatility`. */
+    spot: ArrayLike<number>;
+    /** Per-observation implied vol of a FIXED reference strike (same K across the series). */
+    fixedStrikeVolatility: ArrayLike<number>;
+    /** The smile slope `∂σ/∂ln(K)` — the sticky-moneyness reference. Omit ⇒ only `β`/R² (indeterminate). */
+    skewSlope?: number;
+}
+/** The measured regime. */
+export interface StickyRegime {
+    /**
+     * `∂σ_K/∂lnS` — the empirical vol-spot beta from the regression, **per LOG spot** (vol points per
+     * 100% spot move). NOT the same quantity as `VolatilitySpotBeta.volatilitySpotBeta` /
+     * `minimumVarianceDelta({ volatilitySpotBeta })`, which are `∂σ/∂S` — per DOLLAR. The two differ by
+     * a factor of `S`: feeding this straight into the hedge would scale the smile adjustment by the
+     * spot price. Divide by the reference spot first (`estimateVolatilitySpotBeta` does exactly that
+     * when its `basis` is `'log'`).
+     */
+    volatilitySpotBetaPerLogSpot: number;
+    tStatistic: number;
+    /** How much of the fixed-strike vol's change spot returns explain. */
+    rSquared: number;
+    /** Position on the axis: 0 = sticky-strike, 1 = sticky-moneyness (`= −β/skewSlope`); `null` if no reference. */
+    stickiness: number | null;
+    regime: 'sticky-strike' | 'sticky-moneyness' | 'intermediate' | 'indeterminate';
+    observations: number;
+    assumptions: {
+        conventionsVersion: string;
+        skewSlope: number | null;
+    };
+    diagnostics: Diagnostics;
+}
+/**
+ * Measure whether the market's smile is sticky-strike or sticky-moneyness (sticky-delta) from a history
+ * of spot and a fixed reference strike's implied vol. See `docs/specs/sticky-regime.md`.
+ */
+export declare function stickyRegime(input: StickyRegimeInput): StickyRegime;
+//# sourceMappingURL=sticky-regime.d.ts.map

package/modules/volatility/dist/sticky-regime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sticky-regime.d.ts","sourceRoot":"","sources":["../src/sticky-regime.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAEL,KAAK,WAAW,EAWjB,MAAM,0BAAoB,CAAC;AAG5B,uCAAuC;AACvC,MAAM,WAAW,iBAAiB;IAChC,2EAA2E;IAC3E,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;IACxB,0FAA0F;IAC1F,qBAAqB,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;IACzC,wGAAwG;IACxG,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,2BAA2B;AAC3B,MAAM,WAAW,YAAY;IAC3B;;;;;;;OAOG;IACH,4BAA4B,EAAE,MAAM,CAAC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;IACjB,gHAAgH;IAChH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,eAAe,GAAG,kBAAkB,GAAG,cAAc,GAAG,eAAe,CAAC;IAChF,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE;QAAE,kBAAkB,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IACtE,WAAW,EAAE,WAAW,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,YAAY,CAyFnE"}

package/modules/volatility/dist/sticky-regime.js

@@ -0,0 +1,81 @@
+/**
+ * Sticky-strike vs sticky-delta regime measurement (spec: `docs/specs/sticky-regime.md`, roadmap Tier 2).
+ * When spot moves, does the smile stay put on strikes or slide with the spot? `minimumVarianceDelta`
+ * *assumes* that regime; `stickyRegime` *measures* it — regressing a fixed reference strike's implied-vol
+ * changes on spot log-returns to get the vol-spot beta `β = ∂σ_K/∂lnS`, then placing the market on the
+ * sticky-strike (`β=0`) ↔ sticky-moneyness (`β=−skewSlope`) axis.
+ */
+import { CONVENTIONS_VERSION, ErrorCode, InputError, ensureFinite, ensureKnownKeys, ensurePositive, requireArgumentArray, requireArgumentObject, warning, WarningCode, } from '../../core/dist/index.js';
+import { ols } from '../../math/dist/index.js';
+/**
+ * Measure whether the market's smile is sticky-strike or sticky-moneyness (sticky-delta) from a history
+ * of spot and a fixed reference strike's implied vol. See `docs/specs/sticky-regime.md`.
+ */
+export function stickyRegime(input) {
+    const functionName = 'stickyRegime';
+    requireArgumentObject(functionName, 'input', input);
+    ensureKnownKeys(functionName, 'input', input, ['spot', 'fixedStrikeVolatility', 'skewSlope']);
+    requireArgumentArray(functionName, 'spot', input.spot);
+    requireArgumentArray(functionName, 'fixedStrikeVolatility', input.fixedStrikeVolatility);
+    const n = input.spot.length;
+    if (input.fixedStrikeVolatility.length !== n) {
+        throw new InputError(`${functionName}: spot (${n}) and fixedStrikeVolatility (${input.fixedStrikeVolatility.length}) must have the same length.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { spotLength: n, fixedStrikeVolatilityLength: input.fixedStrikeVolatility.length },
+        });
+    }
+    if (n < 4) {
+        throw new InputError(`${functionName}: need ≥ 4 observations for a stable regression; got ${n}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { observations: n },
+        });
+    }
+    const skewSlope = input.skewSlope;
+    if (skewSlope !== undefined)
+        ensureFinite(skewSlope, 'skewSlope', functionName);
+    // Δσ_K vs ΔlnS over the series.
+    const dLnS = [];
+    const dSig = [];
+    for (let t = 0; t < n; t++) {
+        ensurePositive(input.spot[t], `spot[${t}]`, functionName);
+        ensurePositive(input.fixedStrikeVolatility[t], `fixedStrikeVolatility[${t}]`, functionName);
+        if (t > 0) {
+            dLnS.push(Math.log(input.spot[t] / input.spot[t - 1]));
+            dSig.push(input.fixedStrikeVolatility[t] - input.fixedStrikeVolatility[t - 1]);
+        }
+    }
+    const reg = ols(dSig, dLnS.map((x) => [x])); // coefficients: [intercept, β]
+    const volatilitySpotBetaPerLogSpot = reg.coefficients[1];
+    const tStatistic = reg.tStatistics[1];
+    const rSquared = reg.rSquared;
+    const warnings = [];
+    let stickiness = null;
+    let regime;
+    // A flat smile (or no reference) leaves the sticky axis undefined — don't divide by ~0.
+    if (skewSlope === undefined || Math.abs(skewSlope) < 1e-6) {
+        regime = 'indeterminate';
+        warnings.push(warning(WarningCode.VolatilityStickyIndeterminate, `${functionName}: ${skewSlope === undefined ? 'no skewSlope was supplied' : `the smile is ~flat (skewSlope ${skewSlope})`}, so the sticky-strike ↔ sticky-moneyness axis is undefined. Reporting the raw vol-spot beta (${volatilitySpotBetaPerLogSpot.toFixed(4)}) and R² only.`, 'info'));
+    }
+    else {
+        stickiness = -volatilitySpotBetaPerLogSpot / skewSlope;
+        regime =
+            stickiness < 0.25 ? 'sticky-strike' : stickiness > 0.75 ? 'sticky-moneyness' : 'intermediate';
+    }
+    // A low R² is the EXPECTED signature of sticky-strike (the vol doesn't respond to spot), so it isn't a
+    // reliability concern there. Warn only when a non-trivial (intermediate / sticky-moneyness) placement
+    // rests on a weak regression — that's the case worth flagging.
+    if (rSquared < 0.1 && regime !== 'sticky-strike' && regime !== 'indeterminate') {
+        warnings.push(warning(WarningCode.VolatilityStickyWeakFit, `${functionName}: spot returns explain little of the fixed-strike vol changes (R² ${rSquared.toFixed(3)}) — the placement (${regime}) rests on a weak vol-spot regression; treat it with caution.`, 'info'));
+    }
+    return {
+        volatilitySpotBetaPerLogSpot,
+        tStatistic,
+        rSquared,
+        stickiness,
+        regime,
+        observations: n,
+        assumptions: { conventionsVersion: CONVENTIONS_VERSION, skewSlope: skewSlope ?? null },
+        diagnostics: { engine: 'sticky-regime', method: 'ols', converged: true, warnings },
+    };
+}
+//# sourceMappingURL=sticky-regime.js.map