@insiderfinance/totalfinance 0.1.0

package/modules/volatility/dist/essvi.js

@@ -0,0 +1,362 @@
+/**
+ * eSSVI — the extended SSVI surface (spec: `docs/specs/essvi-surface.md`, roadmap Tier 2). Where `ssvi.ts`
+ * ties the WHOLE surface to one global skew `ρ`, eSSVI lets `ρ` vary with maturity, `ρ(θ)`, so a steep
+ * short-dated skew and a mild long-dated one can be fit at once — while the curvature `φ(θ)` stays a global
+ * function. At a fixed θ an eSSVI slice IS an SSVI slice (hence a raw-SVI slice), so evaluation and the
+ * Gatheral-`g` butterfly test reuse `./ssvi.ts`/`./svi.ts`.
+ *
+ *   w(k, θ) = (θ/2)·[ 1 + ρ(θ)·ψ·k + √((ψ·k + ρ(θ))² + (1 − ρ(θ)²)) ],   ψ = φ(θ)
+ *
+ * When `ρ(θ)` is constant, eSSVI reduces exactly to SSVI. Because `ρ` now varies, a non-decreasing `θ(t)`
+ * is NO LONGER sufficient for calendar-arbitrage-freedom (a steep short slice can push its deep-wing total
+ * variance above a longer slice), so the calendar check scans the `(k, t)` grid directly — the definition:
+ * `w(k, t)` non-decreasing in `t` at every `k`.
+ */
+import { CONVENTIONS_VERSION, ErrorCode, InputError, ensureFinite, requireArgumentObject, validateClosedRequest, warning, WarningCode, } from '../../core/dist/index.js';
+import { nelderMead } from '../../math/dist/index.js';
+import { sviMinG } from './svi.js';
+import { calibrateSsvi, calibrationWeights, prepareSlices, thetaAt, } from './ssvi.js';
+import { phiValueUnchecked, ssviSliceWUnchecked, ssviToSviUnchecked } from './ssvi-kernel.js';
+import { VALIDATION_SPECS } from './generated/validation-specs.js';
+import { requireCalibrationIterationBudget } from './calibration-limits.js';
+import { requireSsviStart } from './calibration-start.js';
+const DEFAULT_G_GRID = Array.from({ length: 81 }, (_, i) => -1 + (2 * i) / 80);
+// ─────────────────────────────── 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 essviSpecOf(key) {
+    const spec = VALIDATION_SPECS[key];
+    if (spec === undefined) {
+        throw new Error(`essvi: no generated validation spec for '${key}' — run \`pnpm validation:update\``);
+    }
+    return spec;
+}
+const CALIBRATE_ESSVI_SURFACE_SPEC = essviSpecOf('calibrateEssvi#0');
+const CALIBRATE_ESSVI_OPTIONS_SPEC = essviSpecOf('calibrateEssvi#1');
+const ESSVI_ARBITRAGE_PARAMETERS_SPEC = essviSpecOf('essviArbitrageFree#0');
+const ESSVI_ARBITRAGE_OPTIONS_SPEC = essviSpecOf('essviArbitrageFree#1');
+const ESSVI_TOTAL_VARIANCE_SPEC = essviSpecOf('essviTotalVariance#0');
+const ESSVI_VOLATILITY_SPEC = essviSpecOf('essviVolatility#0');
+/** A runnable diagnosis call — `essviArbitrageFree` takes (parameters, options?), not (…, k, t). */
+const ESSVI_ARBITRAGE_EXAMPLE = () => "essviArbitrageFree({ phi: { kind: 'power-law', eta: 1.0, gamma: 0.5 }, " +
+    'thetaTerm: [{ timeToExpiryYears: 1, theta: 0.04, rho: -0.3 }] })';
+/** A runnable surface-calibration call, complete enough to satisfy every fitting precondition. */
+function essviCalibrationExampleCall(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] }] })');
+}
+/**
+ * Interpolate `ρ(t)` linearly in `t` between knots; flat below the first and above the last (`ρ` can't be
+ * extrapolated to `t = 0`). Mirrors `thetaAt` from `./ssvi.ts` for the skew.
+ */
+function rhoAt(thetaTerm, timeToExpiryYears) {
+    const n = thetaTerm.length;
+    if (timeToExpiryYears <= thetaTerm[0].timeToExpiryYears)
+        return thetaTerm[0].rho;
+    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.rho + frac * (hi.rho - lo.rho);
+        }
+    }
+    return thetaTerm[n - 1].rho; // t beyond the last knot — flat.
+}
+/** A runnable call to the FAILING evaluator — eSSVI knots carry their own `rho`. */
+function essviExampleCall(functionName) {
+    return (`${functionName}({ phi: { kind: 'power-law', eta: 1.0, gamma: 0.5 }, ` +
+        'thetaTerm: [{ timeToExpiryYears: 1, theta: 0.04, rho: -0.3 }] }, 0, 1)');
+}
+/**
+ * The domain residue the generated spec cannot express: at least one knot, and each knot's own
+ * shape and skew — the spec closes the CONTAINER; array elements stay curated teaching. Shape,
+ * presence, finiteness, and the φ union's branches are the spec head's job now.
+ */
+function requireESSVIParams(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 },
+        });
+    }
+    for (let i = 0; i < parameters.thetaTerm.length; i++) {
+        const knot = parameters.thetaTerm[i];
+        requireArgumentObject(functionName, `parameters.thetaTerm[${i}]`, knot);
+        ensureFinite(knot.rho, `parameters.thetaTerm[${i}].rho`, functionName);
+    }
+}
+/** Total implied variance `w(k, t)` on a calibrated eSSVI surface. */
+export function essviTotalVariance(parameters, k, timeToExpiryYears) {
+    const functionName = 'essviTotalVariance';
+    validateClosedRequest(functionName, parameters, ESSVI_TOTAL_VARIANCE_SPEC, {
+        argumentName: 'parameters',
+        exampleCall: () => essviExampleCall(functionName),
+    });
+    requireESSVIParams(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);
+    const rho = rhoAt(parameters.thetaTerm, timeToExpiryYears);
+    return ssviSliceWUnchecked({ k, theta, rho, psi: phiValueUnchecked(parameters.phi, theta) });
+}
+/** Implied volatility `√(w/t)` on a calibrated eSSVI surface. */
+export function essviVolatility(parameters, k, timeToExpiryYears) {
+    validateClosedRequest('essviVolatility', parameters, ESSVI_VOLATILITY_SPEC, {
+        argumentName: 'parameters',
+        exampleCall: () => essviExampleCall('essviVolatility'),
+    });
+    return Math.sqrt(essviTotalVariance(parameters, k, timeToExpiryYears) / timeToExpiryYears);
+}
+/** A `t`-grid spanning the knots, subdivided so intermediate-maturity crossings are caught. */
+function defaultTGrid(thetaTerm) {
+    const ts = thetaTerm.map((kn) => kn.timeToExpiryYears);
+    const SUB = 6;
+    const out = [];
+    for (let i = 1; i < ts.length; i++) {
+        const lo = ts[i - 1];
+        const hi = ts[i];
+        for (let s = 0; s < SUB; s++)
+            out.push(lo + ((hi - lo) * s) / SUB);
+    }
+    out.push(ts[ts.length - 1]); // the last knot (and the sole point for a 1-knot surface).
+    return out;
+}
+/**
+ * Diagnose the no-arbitrage status of an eSSVI surface: butterfly (exact Gatheral `g ≥ 0` at each grid
+ * maturity, reducing the slice to raw SVI) and calendar (`w(k, t)` non-decreasing in `t` at every grid `k`,
+ * scanned directly because θ-monotonicity is not sufficient once `ρ` varies). See the spec.
+ */
+export function essviArbitrageFree(parameters, options = {}) {
+    const functionName = 'essviArbitrageFree';
+    validateClosedRequest(functionName, parameters, ESSVI_ARBITRAGE_PARAMETERS_SPEC, {
+        argumentName: 'parameters',
+        exampleCall: ESSVI_ARBITRAGE_EXAMPLE,
+    });
+    validateClosedRequest(functionName, options, ESSVI_ARBITRAGE_OPTIONS_SPEC, {
+        argumentName: 'options',
+        exampleCall: ESSVI_ARBITRAGE_EXAMPLE,
+    });
+    requireESSVIParams(parameters, functionName);
+    const grid = options.grid ?? DEFAULT_G_GRID;
+    const maturityGrid = options.maturityGrid ?? defaultTGrid(parameters.thetaTerm);
+    // The maturity terms depend on t ALONE. Interpolating them once here — rather than inside the
+    // crossed (k, t) loop below — is not a micro-optimization: the calendar scan visits every maturity
+    // once per grid point, so re-deriving θ(t), ρ(t) and φ(θ) down there repeated the same
+    // interpolation `grid.length` times to produce identical numbers.
+    const terms = maturityGrid.map((t) => {
+        const theta = thetaAt(parameters.thetaTerm, t);
+        const rho = rhoAt(parameters.thetaTerm, t);
+        return { theta, rho, psi: phiValueUnchecked(parameters.phi, theta) };
+    });
+    // Butterfly: each grid maturity is an SSVI slice → reduce to SVI, test Gatheral g ≥ 0.
+    let minG = Infinity;
+    let butterfly = true;
+    for (const term of terms) {
+        // Unchecked kernel: the surface was validated at this head; re-validating per maturity is 3B.1b-1.
+        const svi = ssviToSviUnchecked(term);
+        // ONE sweep — `sviButterflyFree` IS `sviMinG(...) >= -1e-8`, so asking both walked the grid twice
+        // per maturity to recover a boolean the number already carries.
+        const knotMinG = sviMinG(svi, grid);
+        if (!(knotMinG >= -1e-8))
+            butterfly = false;
+        minG = Math.min(minG, knotMinG);
+    }
+    // Calendar: w(k, t) non-decreasing in t at every k on the grid (the definition of no calendar arb).
+    let minSlope = Infinity;
+    for (const k of grid) {
+        let prevW = Number.NEGATIVE_INFINITY;
+        for (const { theta, rho, psi } of terms) {
+            const w = ssviSliceWUnchecked({ k, theta, rho, psi });
+            if (prevW > Number.NEGATIVE_INFINITY)
+                minSlope = Math.min(minSlope, w - prevW);
+            prevW = w;
+        }
+    }
+    return {
+        calendarArbitrageFree: minSlope >= -1e-12,
+        butterflyArbitrageFree: butterfly,
+        minButterflyG: minG,
+        minCalendarSlope: minSlope,
+    };
+}
+// ─────────────────────────────── calibration ───────────────────────────────
+/**
+ * Fit a calendar-arbitrage-free eSSVI surface: θ knots from each slice's ATM variance (made monotone),
+ * then per-maturity `ρᵢ` and a global `φ` by least squares — warm-started from a global SSVI fit, so eSSVI
+ * begins at the best single-`ρ` surface and can only improve, with a calendar-crossing penalty keeping the
+ * fit arbitrage-free between maturities. See the spec.
+ */
+export function calibrateEssvi(surface, options = {}) {
+    const functionName = 'calibrateEssvi';
+    validateClosedRequest(functionName, surface, CALIBRATE_ESSVI_SURFACE_SPEC, {
+        argumentName: 'surface',
+        subject: true,
+        exampleCall: () => essviCalibrationExampleCall(functionName),
+    });
+    validateClosedRequest(functionName, options, CALIBRATE_ESSVI_OPTIONS_SPEC, {
+        argumentName: 'options',
+        exampleCall: () => essviCalibrationExampleCall(functionName),
+    });
+    requireCalibrationIterationBudget(functionName, options.maximumIterations);
+    const phiKind = options.phi ?? 'power-law';
+    const weightMode = options.weight ?? 'uniform';
+    const prepared = prepareSlices(surface, functionName);
+    const warnings = [];
+    // Non-decreasing θ backbone (clamp a data calendar arbitrage to the increasing hull + disclose).
+    let clamped = false;
+    let runningMax = 0;
+    const thetas = prepared.map((p) => {
+        let theta = p.theta;
+        if (theta < runningMax) {
+            theta = runningMax;
+            clamped = true;
+        }
+        runningMax = theta;
+        return theta;
+    });
+    if (clamped) {
+        warnings.push(warning(WarningCode.VolatilityEssviCalendarData, `${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'));
+    }
+    const m = prepared.length;
+    const weights = calibrationWeights(prepared, weightMode);
+    // The start: a caller-supplied `(ρ per knot, φ)` when given (Stage 4.5), else a global SSVI fit
+    // with the same weighting — its ρ seeds every knot, its φ the curvature.
+    const start = options.initialParameters;
+    let x0;
+    if (start !== undefined) {
+        requireSsviStart(functionName, start, phiKind, m);
+        const rhos = Array.isArray(start.rho)
+            ? [...start.rho]
+            : prepared.map(() => start.rho);
+        const phiParams0 = start.phi.kind === 'power-law' ? [start.phi.eta, start.phi.gamma] : [start.phi.lambda];
+        x0 = [...rhos, ...phiParams0];
+    }
+    else {
+        const ssvi = calibrateSsvi(surface, {
+            phi: phiKind,
+            weight: weightMode,
+            ...(options.maximumIterations !== undefined
+                ? { maximumIterations: options.maximumIterations }
+                : {}),
+            ...(options.tolerance !== undefined ? { tolerance: options.tolerance } : {}),
+        });
+        const phi0 = ssvi.parameters.phi;
+        const phiParams0 = phi0.kind === 'power-law' ? [phi0.eta, phi0.gamma] : [phi0.lambda];
+        x0 = [...prepared.map(() => ssvi.parameters.rho), ...phiParams0];
+    }
+    const buildPhi = (x) => phiKind === 'power-law'
+        ? { kind: 'power-law', eta: x[m], gamma: x[m + 1] }
+        : { kind: 'heston', lambda: x[m] };
+    const feasible = (x) => {
+        for (let i = 0; i < m; i++)
+            if (!(Math.abs(x[i]) < 0.999))
+                return false;
+        if (phiKind === 'power-law')
+            return x[m] > 1e-6 && x[m + 1] > 1e-4 && x[m + 1] < 0.9999;
+        return x[m] > 1e-6;
+    };
+    const PENALTY_W = 1e6; // total-variance SSE is ~1e-4; a crossing must dominate.
+    const sse = (x) => {
+        if (!feasible(x))
+            return 1e12;
+        const phi = buildPhi(x);
+        const rhos = x.slice(0, m);
+        let s = 0;
+        for (let i = 0; i < m; 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 d = ssviSliceWUnchecked({ k: sl.k[j], theta: thetas[i], rho: rhos[i], psi }) - sl.w[j];
+                s += wt[j] * d * d;
+            }
+        }
+        // Calendar penalty: discourage w(k, θᵢ) > w(k, θᵢ₊₁) between adjacent knots on the density grid.
+        for (let i = 1; i < m; i++) {
+            const psiLo = phiValueUnchecked(phi, thetas[i - 1]);
+            const psiHi = phiValueUnchecked(phi, thetas[i]);
+            for (const k of DEFAULT_G_GRID) {
+                const wLo = ssviSliceWUnchecked({
+                    k,
+                    theta: thetas[i - 1],
+                    rho: rhos[i - 1],
+                    psi: psiLo,
+                });
+                const wHi = ssviSliceWUnchecked({ k, theta: thetas[i], rho: rhos[i], psi: psiHi });
+                if (wHi < wLo)
+                    s += PENALTY_W * (wLo - wHi) * (wLo - wHi);
+            }
+        }
+        return s;
+    };
+    const res = nelderMead(sse, x0, {
+        maximumIterations: options.maximumIterations ?? 2000,
+        tolerance: options.tolerance ?? 1e-12,
+    });
+    const rhosFit = res.argMin.slice(0, m);
+    const phi = buildPhi(res.argMin);
+    const thetaTerm = prepared.map((p, i) => ({
+        timeToExpiryYears: p.timeToExpiryYears,
+        theta: thetas[i],
+        rho: rhosFit[i],
+    }));
+    const parameters = { 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: rhosFit[i], 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 rhoTerm = thetaTerm.map((kn) => ({ timeToExpiryYears: kn.timeToExpiryYears, rho: kn.rho }));
+    const arbitrage = essviArbitrageFree(parameters);
+    if (!arbitrage.butterflyArbitrageFree) {
+        warnings.push(warning(WarningCode.VolatilityEssviButterfly, `${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 (!arbitrage.calendarArbitrageFree) {
+        warnings.push(warning(WarningCode.VolatilityEssviCalendar, `${functionName}: the calibrated surface still crosses in maturity (min Δw = ${arbitrage.minCalendarSlope.toExponential(2)} < 0) — the per-maturity skews imply a residual calendar arbitrage the penalty could not fully remove.`, 'warn'));
+    }
+    if (!res.converged) {
+        warnings.push(warning(WarningCode.VolatilityEssviNotConverged, `${functionName}: the calibration search stopped without converging; treat the fit as approximate.`, 'warn'));
+    }
+    return {
+        parameters,
+        rmse,
+        perSliceRmse,
+        rhoTerm,
+        arbitrage,
+        converged: res.converged,
+        assumptions: {
+            conventionsVersion: CONVENTIONS_VERSION,
+            phi: phiKind,
+            skew: 'per-maturity',
+            weight: weightMode,
+            initialParameters: start !== undefined ? 'supplied' : 'ssvi-warm-start',
+        },
+        diagnostics: {
+            engine: 'essvi',
+            method: `${start !== undefined ? 'supplied-start' : 'ssvi-warm-start'} + nelder-mead + ${phiKind}`,
+            converged: res.converged,
+            iterations: res.iterations,
+            warnings,
+        },
+    };
+}
+//# sourceMappingURL=essvi.js.map

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

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

package/modules/volatility/dist/estimate.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The scalar-tier estimate envelope (spec §7.4 / WS2.3 / DX1).
+ *
+ * Event-vol probabilities, expected moves, IV rank/percentile, and the variance-swap fair vol used to
+ * return bare scalars or plain objects — so a serialized `probabilityInTheMoney` payload carried no hint that
+ * it is a RISK-NEUTRAL model probability, not a real-world forecast. That caveat lived only in a doc
+ * comment. Each such analytic now returns the standard `Computed<T, Extra>` envelope: the value it
+ * always returned, plus the conventions/model it assumed (`assumptions`) and any estimate-quality
+ * caveat (`diagnostics.warnings`) — uniform with every other rich result in the library.
+ */
+import type { QuantWarning } from '../../core/dist/index.js';
+/** The standard "this is a risk-neutral model estimate, not a real-world forecast" caveat. */
+export declare const RISK_NEUTRAL_ESTIMATE: QuantWarning;
+//# sourceMappingURL=estimate.d.ts.map

package/modules/volatility/dist/estimate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"estimate.d.ts","sourceRoot":"","sources":["../src/estimate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAAoB,CAAC;AAGvD,8FAA8F;AAC9F,eAAO,MAAM,qBAAqB,EAAE,YAKnC,CAAC"}

package/modules/volatility/dist/estimate.js

@@ -0,0 +1,18 @@
+/**
+ * The scalar-tier estimate envelope (spec §7.4 / WS2.3 / DX1).
+ *
+ * Event-vol probabilities, expected moves, IV rank/percentile, and the variance-swap fair vol used to
+ * return bare scalars or plain objects — so a serialized `probabilityInTheMoney` payload carried no hint that
+ * it is a RISK-NEUTRAL model probability, not a real-world forecast. That caveat lived only in a doc
+ * comment. Each such analytic now returns the standard `Computed<T, Extra>` envelope: the value it
+ * always returned, plus the conventions/model it assumed (`assumptions`) and any estimate-quality
+ * caveat (`diagnostics.warnings`) — uniform with every other rich result in the library.
+ */
+import { WarningCode } from '../../core/dist/index.js';
+/** The standard "this is a risk-neutral model estimate, not a real-world forecast" caveat. */
+export const RISK_NEUTRAL_ESTIMATE = {
+    code: WarningCode.EstimateRiskNeutral,
+    message: 'Risk-neutral model estimate — a model-implied level/probability, not a real-world forecast.',
+    severity: 'info',
+};
+//# sourceMappingURL=estimate.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"estimate.js","sourceRoot":"","sources":["../src/estimate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,0BAAoB,CAAC;AAEjD,8FAA8F;AAC9F,MAAM,CAAC,MAAM,qBAAqB,GAAiB;IACjD,IAAI,EAAE,WAAW,CAAC,mBAAmB;IACrC,OAAO,EACL,6FAA6F;IAC/F,QAAQ,EAAE,MAAM;CACjB,CAAC"}

package/modules/volatility/dist/event.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Event-volatility analytics (spec §10.3): expected move (from IV and from the ATM straddle),
+ * risk-neutral probability ITM, and probability of touch (first-passage to a barrier).
+ *
+ * All probabilities are RISK-NEUTRAL model probabilities (they use the risk-neutral drift `r − q`),
+ * not real-world forecasts — this is stated in each function's contract.
+ */
+import { type OptionType, type QuantWarning } from '../../core/dist/index.js';
+export interface ExpectedMove {
+    /** One standard-deviation move in price units: `spot · σ · √t`. */
+    oneSigma: number;
+    /** One-σ move as a fraction of spot: `σ · √t`. */
+    oneSigmaFraction: number;
+    /** Expected absolute move `E|S_t − S_0| = oneSigma · √(2/π)` (≈ the ATM straddle price). */
+    expectedAbsolute: number;
+    /** Spot − oneSigma. */
+    lower: number;
+    /** Spot + oneSigma. */
+    upper: number;
+}
+/** The conventions echoed by an expected-move estimate (a lognormal 1-σ band). */
+type ExpectedMoveExtra = {
+    measure: 'risk-neutral';
+    basis: 'lognormal-1sigma';
+    volatilitySource: string;
+};
+/** Input for {@link expectedMoveFromImpliedVolatility}. */
+export interface ExpectedMoveImpliedVolatilityInput {
+    spot: number;
+    /** Implied volatility (annualized decimal) — the one volatility vocabulary across the library. */
+    impliedVolatility: number;
+    /** Time to expiry in years. */
+    timeToExpiryYears: number;
+}
+/**
+ * FACADE (P3.2, one gesture): the plain call returns the {@link ExpectedMove} numbers; the same
+ * call's `.explain()` returns the full envelope with the risk-neutral caveat — exactly the
+ * `blackScholes.call` / `blackScholes.call.explain` grammar, one import away.
+ */
+export declare const expectedMoveFromImpliedVolatility: import("../../core/dist/index.js").Facade<ExpectedMoveImpliedVolatilityInput, ExpectedMove, ExpectedMoveExtra, ExpectedMove>;
+/**
+ * Expected move implied by the ATM straddle price. The ATM-forward straddle ≈ `E|move|`
+ * (= `oneSigma · √(2/π)`), so `oneSigma = straddlePrice / √(2/π) ≈ 1.2533 · straddlePrice`.
+ */
+/** Input for {@link expectedMoveFromStraddle}. */
+export interface ExpectedMoveStraddleInput {
+    spot: number;
+    /** The ATM straddle mid-price (call + put at the spot strike). */
+    straddlePrice: number;
+}
+/** FACADE: plain {@link ExpectedMove}; `.explain()` for the envelope. */
+export declare const expectedMoveFromStraddle: import("../../core/dist/index.js").Facade<ExpectedMoveStraddleInput, ExpectedMove, ExpectedMoveExtra, ExpectedMove>;
+/**
+ * Risk-neutral probability the option finishes in the money: `N(d2)` for a call, `N(−d2)` for a put,
+ * where `d2 = (ln(S/K) + (r − q − σ²/2)t) / (σ√t)`. This is the model probability `P(S_t ⋛ K)` under
+ * the risk-neutral measure — NOT a real-world forecast.
+ */
+/** The conventions echoed by a risk-neutral probability estimate. */
+type RiskNeutralExtra = {
+    measure: 'risk-neutral';
+    drift: string;
+};
+/** Input for {@link probabilityInTheMoney}. */
+export interface ProbabilityInTheMoneyInput {
+    type: OptionType;
+    spot: number;
+    strike: number;
+    /** Time to expiry in years. */
+    timeToExpiryYears: number;
+    riskFreeRate: number;
+    /** Implied volatility (annualized decimal). */
+    volatility: number;
+    /** Continuous dividend yield (decimal, default 0). */
+    dividendYield?: number;
+}
+/** FACADE: plain probability; `.explain()` carries the risk-neutral disclosure. */
+export declare const probabilityInTheMoney: import("../../core/dist/index.js").Facade<ProbabilityInTheMoneyInput, number, RiskNeutralExtra, number>;
+/**
+ * Risk-neutral probability the underlying TOUCHES `barrier` at any time before `t` (first-passage
+ * probability for geometric Brownian motion with drift `ν = r − q − σ²/2`). Uses the reflection
+ * principle; for a driftless process it reduces to `2·P(S_t beyond barrier)`.
+ */
+/** Input for {@link probabilityOfTouch}. */
+export interface ProbabilityOfTouchInput {
+    spot: number;
+    barrier: number;
+    /** Time to expiry in years. */
+    timeToExpiryYears: number;
+    riskFreeRate: number;
+    /** Implied volatility (annualized decimal). */
+    volatility: number;
+    /** Continuous dividend yield (decimal, default 0). */
+    dividendYield?: number;
+}
+/** FACADE: plain first-passage probability; `.explain()` for the envelope. */
+export declare const probabilityOfTouch: import("../../core/dist/index.js").Facade<ProbabilityOfTouchInput, number, RiskNeutralExtra, number>;
+/**
+ * Realized-vs-implied spread: `impliedVolatility − realizedVolatility` in volatility points (positive ⇒
+ * vol premium). BOTH inputs are ANNUALIZED decimals (0.20 = 20%): a technical-analysis estimator
+ * supplies that with `annualization: 252` on daily bars — a per-bar σ here is wrong by √252.
+ */
+export interface RealizedImpliedInput {
+    /** Annualized implied volatility (decimal). */
+    impliedVolatility: number;
+    /** Annualized realized volatility (decimal) — e.g. `historicalVolatility(closes, { period, annualization: 252 })`. */
+    realizedVolatility: number;
+}
+export declare function realizedImpliedSpread(input: RealizedImpliedInput): number;
+/**
+ * Variance risk premium: `impliedVolatility² − realizedVolatility²`, the premium of option-implied
+ * ANNUALIZED variance over subsequently-realized annualized variance (the compensation for bearing
+ * variance risk; both inputs are annualized volatilities, so the result is in annualized-variance
+ * units). Positive on average.
+ */
+export declare function varianceRiskPremium(input: RealizedImpliedInput): number;
+export interface EventVolatilityDecomposition {
+    /** Total variance over the tenor `σ_atm²·t`. */
+    totalVariance: number;
+    /** Continuous (non-event) variance over the tenor `σ_base²·t`. */
+    baseVariance: number;
+    /** Variance attributed to the discrete event `σ_atm²·t − σ_base²·t` (clamped ≥ 0). */
+    eventVariance: number;
+    /** Implied one-event move as a fraction of spot, `√(eventVariance)` — the earnings/event jump size. */
+    eventMove: number;
+    /** Applied conventions, echoed (Law 2 report grammar). */
+    assumptions: {
+        conventionsVersion: string;
+        timeToExpiryYears: number;
+        method: 'additive-event-variance';
+    };
+    /** Structured warnings; a clamped (base > total) decomposition explains itself here. */
+    diagnostics: {
+        warnings: QuantWarning[];
+    };
+}
+/**
+ * Decompose an event-spanning ATM vol into a continuous (diffusive) part and a discrete event jump
+ * (spec §10.3). With a base (non-event) vol `σ_base` for the same tenor, the event contributes
+ * `σ_atm²·t − σ_base²·t` of variance, i.e. an implied move of `√(that)` on the event day.
+ */
+export declare function eventVolatilityDecomposition(options: {
+    atmVolatility: number;
+    timeToExpiryYears: number;
+    baseVolatility: number;
+}): EventVolatilityDecomposition;
+/** Plain de-earned volatility; use `.explain()` for assumptions and clamp diagnostics. */
+export declare const eventStrippedVolatility: import("../../core/dist/index.js").Facade<{
+    atmVolatility: number;
+    timeToExpiryYears: number;
+    eventMove: number;
+}, number, {
+    method: "additive-event-variance";
+}, number>;
+export {};
+//# sourceMappingURL=event.d.ts.map

package/modules/volatility/dist/event.d.ts.map

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