@insiderfinance/totalfinance 0.1.0

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

@@ -0,0 +1,152 @@
+/**
+ * Earnings / event-vol modeling (spec §10.3, roadmap Tier 2). The term-structure layer over the
+ * single-tenor event-vol kernels (`eventVolatilityDecomposition`, `eventStrippedVolatility`): `calibrateEventVolatility` **extracts**
+ * the continuous vol `σ_base` and the discrete event jump `J` (the implied earnings move) from a whole
+ * ATM-vol term structure by regression — no hand-supplied base vol — and `calibrateEventMove` compares
+ * straddle-**implied** moves to subsequently-**realized** moves across past events (is the earnings
+ * straddle historically over- or under-priced?).
+ *
+ * Model: an event at time τ adds a fixed variance `J²` to any expiry on/after it, the rest accruing
+ * continuously at `σ_base` — so total variance `Vᵢ = σ_base²·Tᵢ + J²·[Tᵢ spans the event]` is linear in
+ * `(σ_base², J²)` and recovered by a least-squares fit. See `docs/specs/earnings-event-vol.md`.
+ */
+import { type Diagnostics, type EpochMs } from '../../core/dist/index.js';
+/** One point on the ATM-vol term structure. */
+export interface AtmVolatilityPoint {
+    /** ISO expiry date → `t` computed from `asOf` (ACT/365F). */
+    expiry: string;
+    /** Annualized ATM implied vol (decimal). */
+    atmVolatility: number;
+}
+/** Inputs for {@link calibrateEventVolatility}. */
+export interface FitEventVolatilityOptions {
+    /** The ATM-vol term structure (≥ 1 expiry; ≥ 2 to fit both `σ_base` and `J`, unless `baseVolatility` given). */
+    termStructure: readonly AtmVolatilityPoint[];
+    /** ISO date of the earnings/event. */
+    eventDate: string;
+    asOf: EpochMs | string;
+    /** Pin the continuous vol when the term structure can't identify it (single expiry / no maturity spread). */
+    baseVolatility?: number;
+}
+/** One expiry's fitted vs actual ATM vol. */
+export interface FittedExpiry {
+    expiry: string;
+    daysToExpiry: number;
+    timeToExpiryYears: number;
+    atmVolatility: number;
+    spansEvent: boolean;
+    /** The model's ATM vol at this expiry. */
+    fittedVolatility: number;
+    /** `atmVolatility − fittedVolatility`. */
+    residual: number;
+}
+/** The event-vol fit. */
+export interface EventVolatilityCalibration {
+    /** Annualized continuous (non-event) vol `√σ_base²`. */
+    baseVolatility: number;
+    /** `σ_base²` — the fitted continuous variance itself (exact; `baseVolatility` is its root). */
+    baseVariance: number;
+    /** Implied event move as a fraction of spot (`J`) — the "earnings move" (`spot·J` in price units). */
+    eventMove: number;
+    /** `J²` — the discrete event variance. */
+    eventVariance: number;
+    daysToEvent: number;
+    perExpiry: FittedExpiry[];
+    /** Fit quality on total variance (1 = perfect). */
+    rSquared: number;
+    assumptions: {
+        conventionsVersion: string;
+        method: string;
+        eventDate: string;
+        /** The valuation instant the maturities were measured from (epoch ms) — what {@link eventVolatilityAtExpiry} evaluates against. */
+        asOf: EpochMs;
+    };
+    diagnostics: Diagnostics;
+}
+/**
+ * Extract the continuous vol and the discrete event jump from an ATM-vol term structure by fitting
+ * `Vᵢ = σ_base²·Tᵢ + J²·[spans]` (a 2-coefficient least-squares regression). See the spec.
+ */
+export declare function calibrateEventVolatility(options: FitEventVolatilityOptions): EventVolatilityCalibration;
+/** One evaluated expiry of {@link eventVolatilityAtExpiry}. */
+export interface EventVolatilityAtExpiryRow {
+    expiry: string;
+    daysToExpiry: number;
+    timeToExpiryYears: number;
+    spansEvent: boolean;
+    /** The model's annualized ATM volatility at this expiry. */
+    value: number;
+}
+export interface EventVolatilityAtExpiryResult {
+    /** The model ATM volatilities, aligned to `input.expiries`. */
+    values: number[];
+    rows: EventVolatilityAtExpiryRow[];
+    assumptions: {
+        conventionsVersion: string;
+        method: 'additive-event-variance';
+        eventDate: string;
+        asOf: EpochMs;
+        baseVolatility: number;
+        eventMove: number;
+    };
+    diagnostics: Diagnostics;
+}
+/**
+ * Evaluate a fitted event-volatility model at any expiries — the forward door of
+ * {@link calibrateEventVolatility}: the ATM volatility the model implies at an expiry, whether or
+ * not that expiry was in the calibration (an expiry after the event carries the jump; one before
+ * it does not). Maturities are measured from the fit's own `assumptions.asOf`.
+ *
+ * @example
+ * ```ts
+ * const fit = calibrateEventVolatility({ termStructure, eventDate: '2026-05-11', asOf: '2026-05-01T10:00:00-04:00' });
+ * eventVolatilityAtExpiry({ fit, expiries: ['2026-05-08', '2026-06-19'] }).values; // [σ_base, √(σ_base² + J²/t)]
+ * ```
+ */
+export declare function eventVolatilityAtExpiry(input: {
+    fit: EventVolatilityCalibration;
+    expiries: readonly string[];
+}): EventVolatilityAtExpiryResult;
+/** One past event: the straddle-implied move before it and the realized move after. */
+export interface EventMoveObservation {
+    /** Straddle-implied move BEFORE the event (fraction of spot), > 0. */
+    impliedMove: number;
+    /** Realized |move| AFTER the event (fraction of spot), ≥ 0. */
+    realizedMove: number;
+    /** Optional label (e.g. the event date). */
+    date?: string;
+}
+/** One calibrated past event. */
+export interface CalibratedEvent extends EventMoveObservation {
+    /** `realizedMove − impliedMove`. */
+    error: number;
+    /** `impliedMove > realizedMove` — the straddle seller won. */
+    overpriced: boolean;
+}
+/** The straddle-implied vs realized-move calibration. */
+export interface EventMoveCalibration {
+    count: number;
+    averageImplied: number;
+    averageRealized: number;
+    /** `averageRealized / averageImplied` — > 1 ⇒ the stock moves MORE than the straddle prices. */
+    ratio: number;
+    /** Fraction of events where implied > realized (how often selling the straddle won). */
+    overpricedFraction: number;
+    /** Mean `realized − implied` — positive ⇒ straddles underpriced on average. */
+    bias: number;
+    /** Mean `|realized − implied|`. */
+    meanAbsoluteError: number;
+    perEvent: CalibratedEvent[];
+    assumptions: {
+        conventionsVersion: string;
+        method: string;
+    };
+    diagnostics: Diagnostics;
+}
+/**
+ * Calibrate the earnings straddle: compare each past event's implied move (before) to its realized move
+ * (after), and aggregate — the ratio, how often selling the straddle won, and the average bias. A
+ * historical statistic (not a forecast). See the spec.
+ */
+export declare function calibrateEventMove(observations: readonly EventMoveObservation[]): EventMoveCalibration;
+//# sourceMappingURL=earnings.d.ts.map

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

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

package/modules/volatility/dist/earnings.js

@@ -0,0 +1,340 @@
+/**
+ * Earnings / event-vol modeling (spec §10.3, roadmap Tier 2). The term-structure layer over the
+ * single-tenor event-vol kernels (`eventVolatilityDecomposition`, `eventStrippedVolatility`): `calibrateEventVolatility` **extracts**
+ * the continuous vol `σ_base` and the discrete event jump `J` (the implied earnings move) from a whole
+ * ATM-vol term structure by regression — no hand-supplied base vol — and `calibrateEventMove` compares
+ * straddle-**implied** moves to subsequently-**realized** moves across past events (is the earnings
+ * straddle historically over- or under-priced?).
+ *
+ * Model: an event at time τ adds a fixed variance `J²` to any expiry on/after it, the rest accruing
+ * continuously at `σ_base` — so total variance `Vᵢ = σ_base²·Tᵢ + J²·[Tᵢ spans the event]` is linear in
+ * `(σ_base², J²)` and recovered by a least-squares fit. See `docs/specs/earnings-event-vol.md`.
+ */
+import { CONVENTIONS_VERSION, ErrorCode, InputError, WarningCode, ensureKnownKeys, ensureNonNegative, ensurePositive, isoDateToEpochMs, optionExpiryToMs, requireArgumentArray, requireArgumentObject, resolveValuationAsOf, usEquityMarketDateUtcMs, warning, yearFraction, validateClosedRequest, } from '../../core/dist/index.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.
+ */
+function earningsSpecOf(key) {
+    const spec = VALIDATION_SPECS[key];
+    if (spec === undefined) {
+        throw new Error(`earnings: no generated validation spec for '${key}' — run \`pnpm validation:update\``);
+    }
+    return spec;
+}
+const EVENT_VOLATILITY_AT_EXPIRY_SPEC = earningsSpecOf('eventVolatilityAtExpiry#0');
+const EVENT_VOLATILITY_AT_EXPIRY_EXAMPLE = "eventVolatilityAtExpiry({ fit: calibrateEventVolatility({ termStructure, eventDate: '2026-05-11', asOf: '2026-05-01T10:00:00-04:00' }), expiries: ['2026-06-19'] })";
+const DAY_MS = 86_400_000;
+/** Whole calendar days from `asOf`'s date to an ISO date (both at midnight — no 16:00-ET inflation). */
+function calendarDays(isoDate, asOfDayMs) {
+    return Math.round((isoDateToEpochMs(isoDate) - asOfDayMs) / DAY_MS);
+}
+/**
+ * Extract the continuous vol and the discrete event jump from an ATM-vol term structure by fitting
+ * `Vᵢ = σ_base²·Tᵢ + J²·[spans]` (a 2-coefficient least-squares regression). See the spec.
+ */
+export function calibrateEventVolatility(options) {
+    const functionName = 'calibrateEventVolatility';
+    requireArgumentObject(functionName, 'options', options);
+    ensureKnownKeys(functionName, 'options', options, [
+        'termStructure',
+        'eventDate',
+        'asOf',
+        'baseVolatility',
+    ]);
+    requireArgumentArray(functionName, 'options.termStructure', options.termStructure);
+    if (typeof options.eventDate !== 'string') {
+        throw new InputError(`${functionName}: eventDate must be an ISO date string.`, {
+            code: ErrorCode.InputWrongType,
+            context: { eventDate: typeof options.eventDate },
+        });
+    }
+    if (options.termStructure.length === 0) {
+        throw new InputError(`${functionName}: termStructure must have at least one expiry.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { points: 0 },
+        });
+    }
+    const asOfMs = resolveValuationAsOf(options.asOf, functionName);
+    // Whole-day counts run between America/New_York calendar dates, not UTC dates: a 21:00 ET
+    // snapshot is already tomorrow in UTC and would report one day fewer than the trader's calendar.
+    const asOfDayMs = usEquityMarketDateUtcMs(asOfMs);
+    const eventMs = optionExpiryToMs(options.eventDate);
+    // Per-expiry (t, spans, total variance V = σ²·t).
+    const rows = options.termStructure.map((p, i) => {
+        requireArgumentObject(functionName, `termStructure[${i}]`, p);
+        ensureKnownKeys(functionName, `termStructure[${i}]`, p, ['expiry', 'atmVolatility']);
+        if (typeof p.expiry !== 'string') {
+            throw new InputError(`${functionName}: termStructure[${i}].expiry must be an ISO date string.`, {
+                code: ErrorCode.InputWrongType,
+                context: { index: i },
+            });
+        }
+        ensurePositive(p.atmVolatility, `termStructure[${i}].atmVolatility`, functionName);
+        const expiryMs = optionExpiryToMs(p.expiry);
+        const t = yearFraction(asOfMs, expiryMs, 'ACT/365F');
+        if (!(t > 0)) {
+            throw new InputError(`${functionName}: termStructure[${i}] (${p.expiry}) is not after asOf.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { index: i, expiry: p.expiry },
+            });
+        }
+        return {
+            expiry: p.expiry,
+            atmVolatility: p.atmVolatility,
+            t,
+            spans: expiryMs >= eventMs,
+            v: p.atmVolatility * p.atmVolatility * t,
+        };
+    });
+    const warnings = [];
+    const spanningCount = rows.filter((r) => r.spans).length;
+    let baseVar; // σ_base²
+    let eventVar; // J²
+    if (options.baseVolatility !== undefined) {
+        // Caller pins the continuous vol — solve the jump from the spanning expiries' excess variance.
+        ensureNonNegative(options.baseVolatility, 'baseVolatility', functionName);
+        baseVar = options.baseVolatility * options.baseVolatility;
+        const excesses = rows.filter((r) => r.spans).map((r) => r.v - baseVar * r.t);
+        eventVar = excesses.length > 0 ? excesses.reduce((a, b) => a + b, 0) / excesses.length : 0;
+    }
+    else if (spanningCount === 0) {
+        // No option captures the event → J is unidentifiable; report the continuous vol only.
+        const st2 = rows.reduce((a, r) => a + r.t * r.t, 0);
+        const stv = rows.reduce((a, r) => a + r.t * r.v, 0);
+        baseVar = st2 > 0 ? stv / st2 : 0;
+        eventVar = 0;
+        warnings.push(warning(WarningCode.ModelLimitation, `no expiry spans the event date ${options.eventDate}; the event move cannot be extracted (eventMove = 0). Include an expiry on/after the event.`, 'warn', { eventDate: options.eventDate }));
+    }
+    else {
+        // Least-squares fit of V on [t, spans]: XᵀX = [[Σt², Σt·s],[Σt·s, Σs]] (s ∈ {0,1} ⇒ s² = s).
+        const st2 = rows.reduce((a, r) => a + r.t * r.t, 0);
+        const sts = rows.reduce((a, r) => a + (r.spans ? r.t : 0), 0);
+        const ss = spanningCount;
+        const stv = rows.reduce((a, r) => a + r.t * r.v, 0);
+        const ssv = rows.reduce((a, r) => a + (r.spans ? r.v : 0), 0);
+        const det = st2 * ss - sts * sts;
+        if (!(Math.abs(det) > 1e-12 * (st2 * ss + 1))) {
+            throw new InputError(`${functionName}: the term structure can't separate the continuous vol from the event jump (need ≥ 2 expiries with different maturities, at least one spanning the event, or pass baseVolatility).`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { spanningExpiries: ss, expiries: rows.length },
+            });
+        }
+        baseVar = (ss * stv - sts * ssv) / det;
+        eventVar = (st2 * ssv - sts * stv) / det;
+    }
+    // Clamp a physically-impossible fit and disclose it (no fabricated positive move).
+    if (baseVar < 0) {
+        warnings.push(warning(WarningCode.ModelLimitation, `fitted continuous variance was negative (${baseVar}); clamped to 0.`, 'warn', {
+            baseVar,
+        }));
+        baseVar = 0;
+    }
+    if (eventVar < 0) {
+        warnings.push(warning(WarningCode.ModelLimitation, `no positive event premium — implied vol falls through the event (fitted event variance ${eventVar}); eventMove clamped to 0.`, 'warn', { eventVar }));
+        eventVar = 0;
+    }
+    const perExpiry = rows.map((r) => {
+        const fittedVolatility = modelAtmVolatility({
+            baseVariance: baseVar,
+            eventVariance: eventVar,
+            timeToExpiryYears: r.t,
+            spansEvent: r.spans,
+        });
+        return {
+            expiry: r.expiry,
+            daysToExpiry: calendarDays(r.expiry, asOfDayMs),
+            timeToExpiryYears: r.t,
+            atmVolatility: r.atmVolatility,
+            spansEvent: r.spans,
+            fittedVolatility,
+            residual: r.atmVolatility - fittedVolatility,
+        };
+    });
+    // R² on total variance, against the reported (clamped) model.
+    const vBar = rows.reduce((a, r) => a + r.v, 0) / rows.length;
+    let ssRes = 0;
+    let ssTot = 0;
+    for (const r of rows) {
+        const fittedVar = baseVar * r.t + (r.spans ? eventVar : 0);
+        ssRes += (r.v - fittedVar) * (r.v - fittedVar);
+        ssTot += (r.v - vBar) * (r.v - vBar);
+    }
+    const rSquared = ssTot > 0 ? 1 - ssRes / ssTot : 1;
+    return {
+        baseVolatility: Math.sqrt(baseVar),
+        baseVariance: baseVar,
+        eventMove: Math.sqrt(eventVar),
+        eventVariance: eventVar,
+        daysToEvent: calendarDays(options.eventDate, asOfDayMs),
+        perExpiry,
+        rSquared,
+        assumptions: {
+            conventionsVersion: CONVENTIONS_VERSION,
+            method: options.baseVolatility !== undefined
+                ? 'pinned-base + excess-variance'
+                : 'ols variance ~ [t, spans]',
+            eventDate: options.eventDate,
+            asOf: asOfMs,
+        },
+        diagnostics: {
+            engine: 'event-vol-fit',
+            method: 'additive-event-variance',
+            converged: true,
+            warnings,
+        },
+    };
+}
+/**
+ * The additive-event-variance model's ATM volatility at maturity `t`: `√(σ_base²·t + J²·[spans]) / √t`.
+ * The ONE formula behind the calibrator's `perExpiry.fittedVolatility` and the direct evaluator
+ * {@link eventVolatilityAtExpiry} (Stage 4.5 — one engine, two doors).
+ */
+function modelAtmVolatility(input) {
+    const fittedVariance = input.baseVariance * input.timeToExpiryYears + (input.spansEvent ? input.eventVariance : 0);
+    return Math.sqrt(Math.max(0, fittedVariance) / input.timeToExpiryYears);
+}
+/**
+ * Evaluate a fitted event-volatility model at any expiries — the forward door of
+ * {@link calibrateEventVolatility}: the ATM volatility the model implies at an expiry, whether or
+ * not that expiry was in the calibration (an expiry after the event carries the jump; one before
+ * it does not). Maturities are measured from the fit's own `assumptions.asOf`.
+ *
+ * @example
+ * ```ts
+ * const fit = calibrateEventVolatility({ termStructure, eventDate: '2026-05-11', asOf: '2026-05-01T10:00:00-04:00' });
+ * eventVolatilityAtExpiry({ fit, expiries: ['2026-05-08', '2026-06-19'] }).values; // [σ_base, √(σ_base² + J²/t)]
+ * ```
+ */
+export function eventVolatilityAtExpiry(input) {
+    const functionName = 'eventVolatilityAtExpiry';
+    // The generated spec proves the WHOLE declared shape — `fit` is the complete calibrateEventVolatility
+    // result (every field, nested assumptions/diagnostics) — so a hand-built partial "fit" teaches
+    // rather than misprices; the semantic laws below are the ones a shape check cannot state.
+    validateClosedRequest(functionName, input, EVENT_VOLATILITY_AT_EXPIRY_SPEC, {
+        exampleCall: EVENT_VOLATILITY_AT_EXPIRY_EXAMPLE,
+    });
+    const record = input.fit;
+    const teaching = ' — pass the result of calibrateEventVolatility() as input.fit.';
+    for (const field of ['baseVolatility', 'baseVariance', 'eventVariance']) {
+        const value = record[field];
+        if (!(value >= 0)) {
+            throw new InputError(`${functionName}: input.fit.${field} must be a non-negative number${teaching}`, { code: ErrorCode.InputOutOfRange, context: { field: `input.fit.${field}` } });
+        }
+    }
+    if (input.expiries.length === 0) {
+        throw new InputError(`${functionName}: input.expiries must name at least one expiry.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { field: 'input.expiries', count: 0 },
+        });
+    }
+    const baseVolatility = record['baseVolatility'];
+    const eventVar = record['eventVariance'];
+    // The EXACT fitted variance, not the root re-squared — so the evaluator reproduces the
+    // calibrator's own perExpiry.fittedVolatility bit for bit (one engine, two doors).
+    const baseVar = record['baseVariance'];
+    const eventDate = input.fit.assumptions.eventDate;
+    const asOfMs = input.fit.assumptions.asOf;
+    // Whole-day counts run between America/New_York calendar dates, not UTC dates: a 21:00 ET
+    // snapshot is already tomorrow in UTC and would report one day fewer than the trader's calendar.
+    const asOfDayMs = usEquityMarketDateUtcMs(asOfMs);
+    const eventMs = optionExpiryToMs(eventDate);
+    const rows = input.expiries.map((expiry, index) => {
+        if (typeof expiry !== 'string') {
+            throw new InputError(`${functionName}: input.expiries[${index}] must be an ISO date string.`, {
+                code: ErrorCode.InputWrongType,
+                context: { field: `input.expiries[${index}]` },
+            });
+        }
+        const expiryMs = optionExpiryToMs(expiry);
+        const t = yearFraction(asOfMs, expiryMs, 'ACT/365F');
+        if (!(t > 0)) {
+            throw new InputError(`${functionName}: input.expiries[${index}] (${expiry}) is not after the fit's asOf — the model has no maturity to evaluate there.`, { code: ErrorCode.InputOutOfRange, context: { field: `input.expiries[${index}]`, expiry } });
+        }
+        const spansEvent = expiryMs >= eventMs;
+        return {
+            expiry,
+            daysToExpiry: calendarDays(expiry, asOfDayMs),
+            timeToExpiryYears: t,
+            spansEvent,
+            value: modelAtmVolatility({
+                baseVariance: baseVar,
+                eventVariance: eventVar,
+                timeToExpiryYears: t,
+                spansEvent,
+            }),
+        };
+    });
+    return {
+        values: rows.map((row) => row.value),
+        rows,
+        assumptions: {
+            conventionsVersion: CONVENTIONS_VERSION,
+            method: 'additive-event-variance',
+            eventDate,
+            asOf: asOfMs,
+            baseVolatility,
+            eventMove: Math.sqrt(eventVar),
+        },
+        diagnostics: {
+            engine: 'event-vol-fit',
+            method: 'additive-event-variance',
+            converged: true,
+            warnings: [],
+        },
+    };
+}
+/**
+ * Calibrate the earnings straddle: compare each past event's implied move (before) to its realized move
+ * (after), and aggregate — the ratio, how often selling the straddle won, and the average bias. A
+ * historical statistic (not a forecast). See the spec.
+ */
+export function calibrateEventMove(observations) {
+    const functionName = 'calibrateEventMove';
+    requireArgumentArray(functionName, 'observations', observations);
+    if (observations.length === 0) {
+        throw new InputError(`${functionName}: observations must have at least one event.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { count: 0 },
+        });
+    }
+    const perEvent = observations.map((o, i) => {
+        requireArgumentObject(functionName, `observations[${i}]`, o);
+        ensureKnownKeys(functionName, `observations[${i}]`, o, ['impliedMove', 'realizedMove', 'date']);
+        ensurePositive(o.impliedMove, `observations[${i}].impliedMove`, functionName);
+        ensureNonNegative(o.realizedMove, `observations[${i}].realizedMove`, functionName);
+        return {
+            ...o,
+            error: o.realizedMove - o.impliedMove,
+            overpriced: o.impliedMove > o.realizedMove,
+        };
+    });
+    const n = perEvent.length;
+    const averageImplied = perEvent.reduce((a, p) => a + p.impliedMove, 0) / n;
+    const averageRealized = perEvent.reduce((a, p) => a + p.realizedMove, 0) / n;
+    const bias = perEvent.reduce((a, p) => a + p.error, 0) / n;
+    const meanAbsoluteError = perEvent.reduce((a, p) => a + Math.abs(p.error), 0) / n;
+    const overpricedFraction = perEvent.filter((p) => p.overpriced).length / n;
+    return {
+        count: n,
+        averageImplied,
+        averageRealized,
+        ratio: averageRealized / averageImplied, // averageImplied > 0 (each impliedMove > 0)
+        overpricedFraction,
+        bias,
+        meanAbsoluteError,
+        perEvent,
+        assumptions: {
+            conventionsVersion: CONVENTIONS_VERSION,
+            method: 'implied-vs-realized calibration',
+        },
+        diagnostics: {
+            engine: 'event-move-calibration',
+            method: 'historical',
+            converged: true,
+            warnings: [],
+        },
+    };
+}
+//# sourceMappingURL=earnings.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"earnings.js","sourceRoot":"","sources":["../src/earnings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,mBAAmB,EAGnB,SAAS,EACT,UAAU,EAEV,WAAW,EACX,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,uBAAuB,EACvB,OAAO,EACP,YAAY,EACZ,qBAAqB,GAEtB,MAAM,0BAAoB,CAAC;AAE5B,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAEnE;;;GAGG;AACH,SAAS,cAAc,CAAC,GAAW;IACjC,MAAM,IAAI,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACnC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CACb,+CAA+C,GAAG,oCAAoC,CACvF,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,+BAA+B,GAAG,cAAc,CAAC,2BAA2B,CAAC,CAAC;AACpF,MAAM,kCAAkC,GACtC,qKAAqK,CAAC;AAExK,MAAM,MAAM,GAAG,UAAU,CAAC;AAE1B,wGAAwG;AACxG,SAAS,YAAY,CAAC,OAAe,EAAE,SAAkB;IACvD,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,gBAAgB,CAAC,OAAO,CAAC,GAAG,SAAS,CAAC,GAAG,MAAM,CAAC,CAAC;AACtE,CAAC;AA0DD;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CACtC,OAAkC;IAElC,MAAM,YAAY,GAAG,0BAA0B,CAAC;IAChD,qBAAqB,CAAC,YAAY,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;IACxD,eAAe,CAAC,YAAY,EAAE,SAAS,EAAE,OAAO,EAAE;QAChD,eAAe;QACf,WAAW;QACX,MAAM;QACN,gBAAgB;KACjB,CAAC,CAAC;IACH,oBAAoB,CAAC,YAAY,EAAE,uBAAuB,EAAE,OAAO,CAAC,aAAsB,CAAC,CAAC;IAC5F,IAAI,OAAO,OAAO,CAAC,SAAS,KAAK,QAAQ,EAAE,CAAC;QAC1C,MAAM,IAAI,UAAU,CAAC,GAAG,YAAY,yCAAyC,EAAE;YAC7E,IAAI,EAAE,SAAS,CAAC,cAAc;YAC9B,OAAO,EAAE,EAAE,SAAS,EAAE,OAAO,OAAO,CAAC,SAAS,EAAE;SACjD,CAAC,CAAC;IACL,CAAC;IACD,IAAI,OAAO,CAAC,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,UAAU,CAAC,GAAG,YAAY,gDAAgD,EAAE;YACpF,IAAI,EAAE,SAAS,CAAC,eAAe;YAC/B,OAAO,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE;SACvB,CAAC,CAAC;IACL,CAAC;IACD,MAAM,MAAM,GAAG,oBAAoB,CAAC,OAAO,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IAChE,0FAA0F;IAC1F,iGAAiG;IACjG,MAAM,SAAS,GAAG,uBAAuB,CAAC,MAAM,CAAC,CAAC;IAClD,MAAM,OAAO,GAAG,gBAAgB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEpD,kDAAkD;IAClD,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QAC9C,qBAAqB,CAAC,YAAY,EAAE,iBAAiB,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QAC9D,eAAe,CAAC,YAAY,EAAE,iBAAiB,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC;QACrF,IAAI,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;YACjC,MAAM,IAAI,UAAU,CAClB,GAAG,YAAY,mBAAmB,CAAC,sCAAsC,EACzE;gBACE,IAAI,EAAE,SAAS,CAAC,cAAc;gBAC9B,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE;aACtB,CACF,CAAC;QACJ,CAAC;QACD,cAAc,CAAC,CAAC,CAAC,aAAa,EAAE,iBAAiB,CAAC,iBAAiB,EAAE,YAAY,CAAC,CAAC;QACnF,MAAM,QAAQ,GAAG,gBAAgB,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QAC5C,MAAM,CAAC,GAAG,YAAY,CAAC,MAAM,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;QACrD,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YACb,MAAM,IAAI,UAAU,CAClB,GAAG,YAAY,mBAAmB,CAAC,MAAM,CAAC,CAAC,MAAM,sBAAsB,EACvE;gBACE,IAAI,EAAE,SAAS,CAAC,eAAe;gBAC/B,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;aACxC,CACF,CAAC;QACJ,CAAC;QACD,OAAO;YACL,MAAM,EAAE,CAAC,CAAC,MAAM;YAChB,aAAa,EAAE,CAAC,CAAC,aAAa;YAC9B,CAAC;YACD,KAAK,EAAE,QAAQ,IAAI,OAAO;YAC1B,CAAC,EAAE,CAAC,CAAC,aAAa,GAAG,CAAC,CAAC,aAAa,GAAG,CAAC;SACzC,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,MAAM,QAAQ,GAAmB,EAAE,CAAC;IACpC,MAAM,aAAa,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC;IAEzD,IAAI,OAAe,CAAC,CAAC,UAAU;IAC/B,IAAI,QAAgB,CAAC,CAAC,KAAK;IAC3B,IAAI,OAAO,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;QACzC,+FAA+F;QAC/F,iBAAiB,CAAC,OAAO,CAAC,cAAc,EAAE,gBAAgB,EAAE,YAAY,CAAC,CAAC;QAC1E,OAAO,GAAG,OAAO,CAAC,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;QAC1D,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7E,QAAQ,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7F,CAAC;SAAM,IAAI,aAAa,KAAK,CAAC,EAAE,CAAC;QAC/B,sFAAsF;QACtF,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACpD,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACpD,OAAO,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAClC,QAAQ,GAAG,CAAC,CAAC;QACb,QAAQ,CAAC,IAAI,CACX,OAAO,CACL,WAAW,CAAC,eAAe,EAC3B,kCAAkC,OAAO,CAAC,SAAS,6FAA6F,EAChJ,MAAM,EACN,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CACjC,CACF,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,6FAA6F;QAC7F,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACpD,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC9D,MAAM,EAAE,GAAG,aAAa,CAAC;QACzB,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACpD,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC9D,MAAM,GAAG,GAAG,GAAG,GAAG,EAAE,GAAG,GAAG,GAAG,GAAG,CAAC;QACjC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,GAAG,CAAC,GAAG,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9C,MAAM,IAAI,UAAU,CAClB,GAAG,YAAY,oLAAoL,EACnM;gBACE,IAAI,EAAE,SAAS,CAAC,eAAe;gBAC/B,OAAO,EAAE,EAAE,gBAAgB,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,MAAM,EAAE;aACzD,CACF,CAAC;QACJ,CAAC;QACD,OAAO,GAAG,CAAC,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;QACvC,QAAQ,GAAG,CAAC,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;IAC3C,CAAC;IAED,mFAAmF;IACnF,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QAChB,QAAQ,CAAC,IAAI,CACX,OAAO,CACL,WAAW,CAAC,eAAe,EAC3B,4CAA4C,OAAO,kBAAkB,EACrE,MAAM,EACN;YACE,OAAO;SACR,CACF,CACF,CAAC;QACF,OAAO,GAAG,CAAC,CAAC;IACd,CAAC;IACD,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;QACjB,QAAQ,CAAC,IAAI,CACX,OAAO,CACL,WAAW,CAAC,eAAe,EAC3B,0FAA0F,QAAQ,4BAA4B,EAC9H,MAAM,EACN,EAAE,QAAQ,EAAE,CACb,CACF,CAAC;QACF,QAAQ,GAAG,CAAC,CAAC;IACf,CAAC;IAED,MAAM,SAAS,GAAmB,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QAC/C,MAAM,gBAAgB,GAAG,kBAAkB,CAAC;YAC1C,YAAY,EAAE,OAAO;YACrB,aAAa,EAAE,QAAQ;YACvB,iBAAiB,EAAE,CAAC,CAAC,CAAC;YACtB,UAAU,EAAE,CAAC,CAAC,KAAK;SACpB,CAAC,CAAC;QACH,OAAO;YACL,MAAM,EAAE,CAAC,CAAC,MAAM;YAChB,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC,MAAM,EAAE,SAAS,CAAC;YAC/C,iBAAiB,EAAE,CAAC,CAAC,CAAC;YACtB,aAAa,EAAE,CAAC,CAAC,aAAa;YAC9B,UAAU,EAAE,CAAC,CAAC,KAAK;YACnB,gBAAgB;YAChB,QAAQ,EAAE,CAAC,CAAC,aAAa,GAAG,gBAAgB;SAC7C,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,8DAA8D;IAC9D,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;IAC7D,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,MAAM,SAAS,GAAG,OAAO,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3D,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;QAC/C,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACvC,CAAC;IACD,MAAM,QAAQ,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAEnD,OAAO;QACL,cAAc,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC;QAClC,YAAY,EAAE,OAAO;QACrB,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC;QAC9B,aAAa,EAAE,QAAQ;QACvB,WAAW,EAAE,YAAY,CAAC,OAAO,CAAC,SAAS,EAAE,SAAS,CAAC;QACvD,SAAS;QACT,QAAQ;QACR,WAAW,EAAE;YACX,kBAAkB,EAAE,mBAAmB;YACvC,MAAM,EACJ,OAAO,CAAC,cAAc,KAAK,SAAS;gBAClC,CAAC,CAAC,+BAA+B;gBACjC,CAAC,CAAC,2BAA2B;YACjC,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,IAAI,EAAE,MAAM;SACb;QACD,WAAW,EAAE;YACX,MAAM,EAAE,eAAe;YACvB,MAAM,EAAE,yBAAyB;YACjC,SAAS,EAAE,IAAI;YACf,QAAQ;SACT;KACF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,kBAAkB,CAAC,KAK3B;IACC,MAAM,cAAc,GAClB,KAAK,CAAC,YAAY,GAAG,KAAK,CAAC,iBAAiB,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9F,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,cAAc,CAAC,GAAG,KAAK,CAAC,iBAAiB,CAAC,CAAC;AAC1E,CAAC;AA2BD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAGvC;IACC,MAAM,YAAY,GAAG,yBAAyB,CAAC;IAC/C,sGAAsG;IACtG,+FAA+F;IAC/F,0FAA0F;IAC1F,qBAAqB,CAAC,YAAY,EAAE,KAAK,EAAE,+BAA+B,EAAE;QAC1E,WAAW,EAAE,kCAAkC;KAChD,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,KAAK,CAAC,GAAyC,CAAC;IAC/D,MAAM,QAAQ,GAAG,gEAAgE,CAAC;IAClF,KAAK,MAAM,KAAK,IAAI,CAAC,gBAAgB,EAAE,cAAc,EAAE,eAAe,CAAU,EAAE,CAAC;QACjF,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAW,CAAC;QACtC,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,EAAE,CAAC;YAClB,MAAM,IAAI,UAAU,CAClB,GAAG,YAAY,eAAe,KAAK,iCAAiC,QAAQ,EAAE,EAC9E,EAAE,IAAI,EAAE,SAAS,CAAC,eAAe,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,aAAa,KAAK,EAAE,EAAE,EAAE,CAC9E,CAAC;QACJ,CAAC;IACH,CAAC;IACD,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,UAAU,CAAC,GAAG,YAAY,iDAAiD,EAAE;YACrF,IAAI,EAAE,SAAS,CAAC,eAAe;YAC/B,OAAO,EAAE,EAAE,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE,CAAC,EAAE;SAC/C,CAAC,CAAC;IACL,CAAC;IACD,MAAM,cAAc,GAAG,MAAM,CAAC,gBAAgB,CAAW,CAAC;IAC1D,MAAM,QAAQ,GAAG,MAAM,CAAC,eAAe,CAAW,CAAC;IACnD,uFAAuF;IACvF,mFAAmF;IACnF,MAAM,OAAO,GAAG,MAAM,CAAC,cAAc,CAAW,CAAC;IACjD,MAAM,SAAS,GAAG,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,SAAS,CAAC;IAClD,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC;IAC1C,0FAA0F;IAC1F,iGAAiG;IACjG,MAAM,SAAS,GAAG,uBAAuB,CAAC,MAAM,CAAC,CAAC;IAClD,MAAM,OAAO,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;IAC5C,MAAM,IAAI,GAAiC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE;QAC9E,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC/B,MAAM,IAAI,UAAU,CAClB,GAAG,YAAY,oBAAoB,KAAK,+BAA+B,EACvE;gBACE,IAAI,EAAE,SAAS,CAAC,cAAc;gBAC9B,OAAO,EAAE,EAAE,KAAK,EAAE,kBAAkB,KAAK,GAAG,EAAE;aAC/C,CACF,CAAC;QACJ,CAAC;QACD,MAAM,QAAQ,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAC1C,MAAM,CAAC,GAAG,YAAY,CAAC,MAAM,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;QACrD,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YACb,MAAM,IAAI,UAAU,CAClB,GAAG,YAAY,oBAAoB,KAAK,MAAM,MAAM,8EAA8E,EAClI,EAAE,IAAI,EAAE,SAAS,CAAC,eAAe,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,kBAAkB,KAAK,GAAG,EAAE,MAAM,EAAE,EAAE,CAC5F,CAAC;QACJ,CAAC;QACD,MAAM,UAAU,GAAG,QAAQ,IAAI,OAAO,CAAC;QACvC,OAAO;YACL,MAAM;YACN,YAAY,EAAE,YAAY,CAAC,MAAM,EAAE,SAAS,CAAC;YAC7C,iBAAiB,EAAE,CAAC;YACpB,UAAU;YACV,KAAK,EAAE,kBAAkB,CAAC;gBACxB,YAAY,EAAE,OAAO;gBACrB,aAAa,EAAE,QAAQ;gBACvB,iBAAiB,EAAE,CAAC;gBACpB,UAAU;aACX,CAAC;SACH,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,OAAO;QACL,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC;QACpC,IAAI;QACJ,WAAW,EAAE;YACX,kBAAkB,EAAE,mBAAmB;YACvC,MAAM,EAAE,yBAAyB;YACjC,SAAS;YACT,IAAI,EAAE,MAAM;YACZ,cAAc;YACd,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC;SAC/B;QACD,WAAW,EAAE;YACX,MAAM,EAAE,eAAe;YACvB,MAAM,EAAE,yBAAyB;YACjC,SAAS,EAAE,IAAI;YACf,QAAQ,EAAE,EAAE;SACb;KACF,CAAC;AACJ,CAAC;AAsCD;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAChC,YAA6C;IAE7C,MAAM,YAAY,GAAG,oBAAoB,CAAC;IAC1C,oBAAoB,CAAC,YAAY,EAAE,cAAc,EAAE,YAAqB,CAAC,CAAC;IAC1E,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,UAAU,CAAC,GAAG,YAAY,8CAA8C,EAAE;YAClF,IAAI,EAAE,SAAS,CAAC,eAAe;YAC/B,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE;SACtB,CAAC,CAAC;IACL,CAAC;IACD,MAAM,QAAQ,GAAsB,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QAC5D,qBAAqB,CAAC,YAAY,EAAE,gBAAgB,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QAC7D,eAAe,CAAC,YAAY,EAAE,gBAAgB,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,aAAa,EAAE,cAAc,EAAE,MAAM,CAAC,CAAC,CAAC;QAChG,cAAc,CAAC,CAAC,CAAC,WAAW,EAAE,gBAAgB,CAAC,eAAe,EAAE,YAAY,CAAC,CAAC;QAC9E,iBAAiB,CAAC,CAAC,CAAC,YAAY,EAAE,gBAAgB,CAAC,gBAAgB,EAAE,YAAY,CAAC,CAAC;QACnF,OAAO;YACL,GAAG,CAAC;YACJ,KAAK,EAAE,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,WAAW;YACrC,UAAU,EAAE,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,YAAY;SAC3C,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,MAAM,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC;IAC1B,MAAM,cAAc,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;IAC3E,MAAM,eAAe,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;IAC7E,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;IAC3D,MAAM,iBAAiB,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;IAClF,MAAM,kBAAkB,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;IAC3E,OAAO;QACL,KAAK,EAAE,CAAC;QACR,cAAc;QACd,eAAe;QACf,KAAK,EAAE,eAAe,GAAG,cAAc,EAAE,4CAA4C;QACrF,kBAAkB;QAClB,IAAI;QACJ,iBAAiB;QACjB,QAAQ;QACR,WAAW,EAAE;YACX,kBAAkB,EAAE,mBAAmB;YACvC,MAAM,EAAE,iCAAiC;SAC1C;QACD,WAAW,EAAE;YACX,MAAM,EAAE,wBAAwB;YAChC,MAAM,EAAE,YAAY;YACpB,SAAS,EAAE,IAAI;YACf,QAAQ,EAAE,EAAE;SACb;KACF,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,115 @@
+/**
+ * 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 { type Diagnostics } from '../../core/dist/index.js';
+import { type SSVIPhi, type SSVISliceInput } from './ssvi.js';
+/** Calibrated eSSVI surface parameters — SSVI with a per-maturity skew. */
+export interface ESSVIParameters {
+    /** Curvature function (global), same family as SSVI. */
+    phi: SSVIPhi;
+    /** Per-knot `(t, θ, ρ)`: θ strictly increasing (calendar backbone), ρ ∈ (−1, 1) per maturity. */
+    thetaTerm: Array<{
+        timeToExpiryYears: number;
+        theta: number;
+        rho: number;
+    }>;
+}
+/** No-arbitrage diagnosis of an eSSVI surface. */
+export interface ESSVIArbitrage {
+    /** No calendar-spread arbitrage — `w(k, t)` non-decreasing in `t` at every grid `k` (the definition). */
+    calendarArbitrageFree: boolean;
+    /** No butterfly arbitrage — the exact Gatheral `g ≥ 0` density test at every grid maturity. */
+    butterflyArbitrageFree: boolean;
+    /** The minimum Gatheral `g(k)` over the grid and maturities (`≥ 0` ⇔ butterfly-free). */
+    minButterflyG: number;
+    /** Minimum `Δw` between adjacent maturities over the grid (`≥ 0` ⇔ calendar-free). */
+    minCalendarSlope: number;
+}
+/** One maturity slice of the market surface (same shape as SSVI's). */
+export type ESSVISliceInput = SSVISliceInput;
+/** Input for {@link calibrateEssvi}. */
+export interface ESSVICalibrationInput {
+    slices: ESSVISliceInput[];
+}
+/** Options for {@link calibrateEssvi}. */
+export interface ESSVICalibrationOptions {
+    /** Curvature family; default `'power-law'`. */
+    phi?: 'power-law' | 'heston';
+    /**
+     * Least-squares weighting of the total-variance residuals: `'uniform'` (default) or `'vega'` — weight each
+     * point by its Black vega `∝ φ(d₁)·√t`, so liquid ATM/near-the-money strikes dominate the fit. Threaded
+     * through the SSVI warm-start too.
+     */
+    weight?: 'uniform' | 'vega';
+    /** Outer-search iteration budget (default 2,000, maximum 10,000). */
+    maximumIterations?: number;
+    /** Outer-search tolerance (default 1e-12). */
+    tolerance?: number;
+    /**
+     * Warm start (Stage 4.5): a scalar `rho` broadcasts to every maturity knot, an array must match
+     * the slice count; `phi.kind` must equal the calibration's `phi` family. A supplied start REPLACES
+     * the internal SSVI warm start (echoed in `assumptions.initialParameters`).
+     */
+    initialParameters?: {
+        rho: number | number[];
+        phi: SSVIPhi;
+    };
+}
+/** Result of {@link calibrateEssvi}. */
+export interface ESSVICalibration {
+    parameters: ESSVIParameters;
+    /** Root-mean-square total-variance error across all points. */
+    rmse: number;
+    perSliceRmse: Array<{
+        timeToExpiryYears: number;
+        rmse: number;
+    }>;
+    /** The fitted skew term structure — the payoff of eSSVI over global-ρ SSVI. */
+    rhoTerm: Array<{
+        timeToExpiryYears: number;
+        rho: number;
+    }>;
+    arbitrage: ESSVIArbitrage;
+    converged: boolean;
+    assumptions: {
+        conventionsVersion: string;
+        phi: 'power-law' | 'heston';
+        skew: 'per-maturity';
+        weight: 'uniform' | 'vega';
+        /** Whether the search began from a caller-supplied start or the internal global-SSVI warm start. */
+        initialParameters: 'supplied' | 'ssvi-warm-start';
+    };
+    diagnostics: Diagnostics;
+}
+/** Total implied variance `w(k, t)` on a calibrated eSSVI surface. */
+export declare function essviTotalVariance(parameters: ESSVIParameters, k: number, timeToExpiryYears: number): number;
+/** Implied volatility `√(w/t)` on a calibrated eSSVI surface. */
+export declare function essviVolatility(parameters: ESSVIParameters, k: number, timeToExpiryYears: number): number;
+/**
+ * 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 declare function essviArbitrageFree(parameters: ESSVIParameters, options?: {
+    grid?: number[];
+    maturityGrid?: number[];
+}): ESSVIArbitrage;
+/**
+ * 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 declare function calibrateEssvi(surface: ESSVICalibrationInput, options?: ESSVICalibrationOptions): ESSVICalibration;
+//# sourceMappingURL=essvi.d.ts.map

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

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