@insiderfinance/totalfinance 0.1.0

package/modules/volatility/dist/sabr-delta.js

@@ -0,0 +1,153 @@
+/**
+ * SABR Bartlett (minimum-variance) greeks (roadmap Tier 2 — the `minimumVarianceDelta` SABR follow-up).
+ *
+ * When the smile is a SABR fit, the vol–spot sensitivity is not a free input — the model dictates it,
+ * because the forward `F` and the vol level `α` are correlated (`⟨dW_F, dW_α⟩ = ρ dt`). Bartlett (2006)
+ * derived the resulting minimum-variance hedges: the greeks that account for the vol move that, on average,
+ * accompanies a forward move (and vice-versa).
+ *
+ *   Δ_Bartlett = ∂V/∂F + ∂V/∂α · (ρν / F^β)          V_Bartlett = ∂V/∂α + ∂V/∂F · (ρ F^β / ν)
+ *
+ * plus the second-order companion — the minimum-variance **gamma**, the price convexity `d²V/dF²` along the
+ * correlated hedge path `α(F)` (≈ the naive gamma at the money, materially different in the wings).
+ *
+ * `∂V/∂F` (the total SABR delta), `∂V/∂α` (the SABR vega), and `∂²V/∂F²` (the SABR gamma) are exactly the
+ * finite-difference greeks `sabrPrice(…, { greeks: true })` computes, so this composes that verified engine
+ * and adds the coupling. See `docs/specs/sabr-bartlett-delta.md` and `docs/specs/sabr-bartlett-gamma.md`.
+ * The SABR realization of {@link minimumVarianceDelta}.
+ */
+import { CONVENTIONS_VERSION, ErrorCode, InputError, ensureFinite, ensurePositive, validateClosedRequest, } from '../../core/dist/index.js';
+import {} from '../../options/dist/index.js';
+import { sabrPrice, sabrVolatility } from '../../options/dist/sabr.js';
+import { VALIDATION_SPECS } from './generated/validation-specs.js';
+/**
+ * Generated closed-request spec (spec 3B.1b): the allowlist projected from the declaration.
+ * Resolved at module load so a stale key fails at import.
+ */
+function sabrDeltaSpecOf(key) {
+    const spec = VALIDATION_SPECS[key];
+    if (spec === undefined) {
+        throw new Error(`sabr-delta: no generated validation spec for '${key}' — run \`pnpm validation:update\``);
+    }
+    return spec;
+}
+const SABR_BARTLETT_GREEKS_SPEC = sabrDeltaSpecOf('sabrBartlettGreeks#0');
+const SABR_BARTLETT_GREEKS_EXAMPLE = () => "sabrBartlettGreeks({ type: 'call', input: { forward: 100, strike: 105, " +
+    'timeToExpiryYears: 0.5 }, parameters: { alpha: 0.2, beta: 0.5, rho: -0.3, nu: 0.4 } })';
+const FN = 'sabrBartlettGreeks';
+/** Resolve the SABR forward `F` and discount rate `r` from `input.forward`, or `input.spot` (+ rate, div). */
+function resolveForward(input) {
+    const r = input.riskFreeRate ?? 0;
+    ensureFinite(r, 'riskFreeRate', FN);
+    if (typeof input.forward === 'number') {
+        ensurePositive(input.forward, 'forward', FN);
+        return { F: input.forward, r };
+    }
+    if (typeof input.spot === 'number') {
+        ensurePositive(input.spot, 'spot', FN);
+        const q = input.dividendYield ?? 0;
+        ensureFinite(q, 'dividendYield', FN);
+        return { F: input.spot * Math.exp((r - q) * input.timeToExpiryYears), r };
+    }
+    throw new InputError(`${FN}: provide either input.forward or input.spot.`, {
+        code: ErrorCode.InputMissingField,
+        context: { fields: ['forward', 'spot'] },
+    });
+}
+/**
+ * Bartlett (2006) minimum-variance delta, vega & gamma for a SABR-parametrised option — the model-consistent
+ * hedges that account for the correlated forward/vol dynamics. Composes `sabrPrice` (naive delta/vega/gamma)
+ * with the correlation coupling `ρν/F^β` (delta) and `ρF^β/ν` (vega); the Bartlett gamma is the price
+ * convexity along the correlated hedge path. Greeks are w.r.t. the **forward**, as in `sabrPrice`. Each is
+ * reported alongside its naive counterpart and the adjustment. See `docs/specs/sabr-bartlett-delta.md` and
+ * `docs/specs/sabr-bartlett-gamma.md`.
+ */
+export function sabrBartlettGreeks(request) {
+    validateClosedRequest(FN, request, SABR_BARTLETT_GREEKS_SPEC, {
+        argumentName: 'request',
+        subject: true,
+        exampleCall: SABR_BARTLETT_GREEKS_EXAMPLE,
+    });
+    const { type, input, parameters, options: options = {} } = request;
+    const volatilityType = options.volatilityType ?? 'lognormal';
+    // The Bartlett vega coupling ρF^β/ν requires ν > 0. With no vol-of-vol the forward and vol are
+    // uncorrelated in level moves and the SABR smile is degenerate, so reject ν ≤ 0 up front with a clear
+    // message rather than dividing by zero. (`sabrPrice`/`sabrVolatility` also validate α/β/ρ/strike/t.)
+    if (!(parameters.nu > 0)) {
+        throw new InputError(`${FN}: nu must be > 0 for the Bartlett minimum-variance greeks — with no vol-of-vol the forward and vol level do not co-move; got ${String(parameters.nu)}.`, { code: ErrorCode.InputOutOfRange, context: { nu: parameters.nu } });
+    }
+    const { F, r } = resolveForward(input);
+    const priced = sabrPrice({
+        type,
+        input,
+        parameters,
+        options: { volatilityType, greeks: true },
+    });
+    const greeks = priced.greeks; // greeks: true ⇒ present
+    const sabrDelta = greeks.delta; // ∂V/∂F (raw, per 1.00 forward)
+    const sabrVegaDisplay = greeks.vega; // ∂V/∂α per 1%
+    const sabrVegaRaw = sabrVegaDisplay * 100; // per 1.00 α
+    const sabrGamma = greeks.gamma; // ∂²V/∂F² (raw), parameters fixed
+    const impliedVolatility = sabrVolatility({
+        input: { forward: F, strike: input.strike, timeToExpiryYears: input.timeToExpiryYears },
+        parameters,
+        options: { volatilityType },
+    });
+    const { beta, rho, nu } = parameters;
+    const fBeta = Math.pow(F, beta);
+    const alphaPerForward = (rho * nu) / fBeta; // E[δα | δF] per unit F
+    const forwardPerAlpha = (rho * fBeta) / nu; // E[δF | δα] per unit α
+    const bartlettDelta = sabrDelta + sabrVegaRaw * alphaPerForward;
+    const bartlettVegaRaw = sabrVegaRaw + sabrDelta * forwardPerAlpha;
+    const bartlettVega = bartlettVegaRaw / 100;
+    // Bartlett gamma: the price convexity along the correlated hedge path α(F). Integrating dα/dF = ρν/F^β
+    // gives α(F') = α + ρν·(F'^{1−β} − F^{1−β})/(1−β), with the β = 1 log limit. bartlettGamma is the central
+    // second difference of the SABR price along that exact path — the P&L convexity a Bartlett-hedger sees.
+    const priceAt = (f, a) => sabrPrice({
+        type,
+        input: {
+            forward: f,
+            strike: input.strike,
+            timeToExpiryYears: input.timeToExpiryYears,
+            riskFreeRate: r,
+        },
+        parameters: { ...parameters, alpha: a },
+        options: {
+            volatilityType,
+            greeks: false,
+        },
+    }).value;
+    const alphaOnPath = (fp) => Math.abs(1 - beta) < 1e-12
+        ? parameters.alpha + rho * nu * Math.log(fp / F)
+        : parameters.alpha +
+            (rho * nu * (Math.pow(fp, 1 - beta) - Math.pow(F, 1 - beta))) / (1 - beta);
+    const dF = F * 5e-4;
+    const bartlettGamma = (priceAt(F + dF, alphaOnPath(F + dF)) -
+        2 * priced.value +
+        priceAt(F - dF, alphaOnPath(F - dF))) /
+        (dF * dF);
+    const assumptions = {
+        conventionsVersion: CONVENTIONS_VERSION,
+        timeToExpiryYears: input.timeToExpiryYears,
+        model: 'sabr',
+        measure: 'min-variance-hedge',
+        volatilityType,
+    };
+    return {
+        value: {
+            impliedVolatility,
+            sabrDelta,
+            bartlettDelta,
+            deltaAdjustment: bartlettDelta - sabrDelta,
+            sabrVega: sabrVegaDisplay,
+            bartlettVega,
+            vegaAdjustment: bartlettVega - sabrVegaDisplay,
+            sabrGamma,
+            bartlettGamma,
+            gammaAdjustment: bartlettGamma - sabrGamma,
+        },
+        assumptions,
+        diagnostics: { warnings: [] },
+    };
+}
+//# sourceMappingURL=sabr-delta.js.map

package/modules/volatility/dist/sabr-delta.js.map

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

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

@@ -0,0 +1,62 @@
+/**
+ * SABR smile calibration (spec §10.1).
+ *
+ * Fits the three free SABR parameters `(α, ρ, ν)` — the backbone exponent `β` is fixed by the user
+ * (0.5 for rates, ~1 for equities) since it is statistically hard to separate from `ρ` — to a single
+ * expiry's market smile, using the Hagan implied-vol expansion from `@insiderfinance/totalfinance/options`. The fit is a
+ * Levenberg–Marquardt least-squares over a reparameterization that keeps `α > 0`, `ρ ∈ (−1, 1)`,
+ * `ν > 0` at every step; `α` is seeded from the at-the-money vol.
+ */
+import { type Diagnostics } from '../../core/dist/index.js';
+import { type SabrParameters, type SabrVolatilityType } from '../../options/dist/index.js';
+export interface SABRCalibrationOptions {
+    /** Backbone exponent β ∈ [0, 1] (default 0.5). */
+    beta?: number;
+    /** Hagan expansion to fit against (default `'lognormal'`). */
+    volatilityType?: SabrVolatilityType;
+    /** LM iteration budget (default 200, maximum 10,000). */
+    maximumIterations?: number;
+    /** LM tolerance (default 1e-12). */
+    tolerance?: number;
+    /**
+     * Warm start for the `(α, ρ, ν)` search (Stage 4.5); `β` stays an option and is never fitted.
+     * Replaces the ATM-derived default start.
+     */
+    initialParameters?: {
+        alpha: number;
+        rho: number;
+        nu: number;
+    };
+}
+export interface SABRCalibrationResult {
+    parameters: SabrParameters;
+    /** Root-mean-square implied-volatility error of the fit. */
+    rmse: number;
+    converged: boolean;
+    iterations: number;
+    /** Applied conventions, echoed (Law 2 report grammar). */
+    assumptions: {
+        conventionsVersion: string;
+        beta: number;
+        volatilityType: SabrVolatilityType;
+        /** Whether the search began from a caller-supplied `initialParameters` or the ATM-derived default. */
+        initialParameters: 'supplied' | 'default';
+    };
+    /** Structured warnings; a non-converged fit explains itself here. */
+    diagnostics: Diagnostics;
+}
+/**
+ * Calibrate `(α, ρ, ν)` of a SABR smile to market implied volatilities at a single expiry. Needs at least 3
+ * strikes. Returns the full {@link SabrParameters} (including the fixed `β`), the fit RMSE, and convergence.
+ */
+/** Market smile input for {@link calibrateSabrSmile}: the forward, and aligned strikes/impliedVolatilities at one expiry. */
+export interface SABRSmileInput {
+    forward: number;
+    strikes: number[];
+    /** Implied volatilities aligned to `strikes` (annualized decimals). */
+    impliedVolatilities: number[];
+    /** Time to expiry in years. */
+    timeToExpiryYears: number;
+}
+export declare function calibrateSabrSmile(input: SABRSmileInput, options?: SABRCalibrationOptions): SABRCalibrationResult;
+//# sourceMappingURL=sabr.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sabr.d.ts","sourceRoot":"","sources":["../src/sabr.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAGL,KAAK,WAAW,EAUjB,MAAM,0BAAoB,CAAC;AAE5B,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,kBAAkB,EAAE,MAAM,6BAAuB,CAAC;AAKrF,MAAM,WAAW,sBAAsB;IACrC,kDAAkD;IAClD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,cAAc,CAAC,EAAE,kBAAkB,CAAC;IACpC,yDAAyD;IACzD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,oCAAoC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,iBAAiB,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;CAChE;AAED,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,cAAc,CAAC;IAC3B,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,WAAW,EAAE;QACX,kBAAkB,EAAE,MAAM,CAAC;QAC3B,IAAI,EAAE,MAAM,CAAC;QACb,cAAc,EAAE,kBAAkB,CAAC;QACnC,sGAAsG;QACtG,iBAAiB,EAAE,UAAU,GAAG,SAAS,CAAC;KAC3C,CAAC;IACF,qEAAqE;IACrE,WAAW,EAAE,WAAW,CAAC;CAC1B;AA2DD;;;GAGG;AACH,6HAA6H;AAC7H,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,uEAAuE;IACvE,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,+BAA+B;IAC/B,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,cAAc,EACrB,OAAO,GAAE,sBAA2B,GACnC,qBAAqB,CA4OvB"}

package/modules/volatility/dist/sabr.js

@@ -0,0 +1,262 @@
+/**
+ * SABR smile calibration (spec §10.1).
+ *
+ * Fits the three free SABR parameters `(α, ρ, ν)` — the backbone exponent `β` is fixed by the user
+ * (0.5 for rates, ~1 for equities) since it is statistically hard to separate from `ρ` — to a single
+ * expiry's market smile, using the Hagan implied-vol expansion from `@insiderfinance/totalfinance/options`. The fit is a
+ * Levenberg–Marquardt least-squares over a reparameterization that keeps `α > 0`, `ρ ∈ (−1, 1)`,
+ * `ν > 0` at every step; `α` is seeded from the at-the-money vol.
+ */
+import { CONVENTIONS_VERSION, ErrorCode, InputError, WarningCode, ensurePositive, isQuantError, PostconditionError, validateClosedRequest, warning, } from '../../core/dist/index.js';
+import { levenbergMarquardt } from '../../math/dist/index.js';
+import {} from '../../options/dist/index.js';
+import { sabrVolatility } from '../../options/dist/sabr.js';
+import { requireCalibrationIterationBudget } from './calibration-limits.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 sabrSpecOf(key) {
+    const spec = VALIDATION_SPECS[key];
+    if (spec === undefined) {
+        throw new Error(`sabr: no generated validation spec for '${key}' — run \`pnpm validation:update\``);
+    }
+    return spec;
+}
+const CALIBRATE_SABR_INPUT_SPEC = sabrSpecOf('calibrateSabrSmile#0');
+const CALIBRATE_SABR_OPTIONS_SPEC = sabrSpecOf('calibrateSabrSmile#1');
+const CALIBRATE_SABR_EXAMPLE = () => 'calibrateSabrSmile({ forward: 100, strikes: [90, 100, 110], ' +
+    'impliedVolatilities: [0.22, 0.2, 0.21], timeToExpiryYears: 0.5 }, { beta: 0.5 })';
+/**
+ * Hagan's expansion is a small-time asymptotic: outside its validity region (`ρ² > 2/3` with a large
+ * `ν²·T`, or a huge `α²/(F·K)^{1−β}` on a low shifted forward) its `1 + […]·T` bracket goes negative
+ * and `sabrVolatility` REFUSES the point rather than returning a negative vol. The least-squares
+ * search walks through parameter space, so it WILL probe such points — that must steer the optimizer,
+ * not abort the calibration (and, before the options-side guard existed, must not be fitted against a
+ * negative "volatility" either). Recognized by the guard's own `timeBracket` context.
+ */
+function outOfDomainBracket(error) {
+    // Narrow on BOTH the code and the guard's own `timeBracket` context: a plain out-of-range error
+    // (a bad forward, a non-positive strike) is a real defect and must still surface.
+    if (!isQuantError(error, ErrorCode.InputOutOfRange))
+        return undefined;
+    const bracket = error.context?.['timeBracket'];
+    return typeof bracket === 'number' ? bracket : undefined;
+}
+/** At-the-money implied vol: the market IV at the strike closest to the forward. */
+function atmVolatility(forward, strikes, impliedVolatilities) {
+    let best = 0;
+    let bestDist = Infinity;
+    for (let i = 0; i < strikes.length; i++) {
+        const dist = Math.abs(Math.log(strikes[i] / forward));
+        if (dist < bestDist) {
+            bestDist = dist;
+            best = impliedVolatilities[i];
+        }
+    }
+    return best;
+}
+export function calibrateSabrSmile(input, options = {}) {
+    // A natural wrong key ({ volatilities: … }) must teach the real slot names (did-you-mean
+    // "impliedVolatilities"), not crash on `.length` — the spec rejects unknown keys first, then
+    // enforces presence, types, and finiteness.
+    validateClosedRequest('calibrateSabrSmile', input, CALIBRATE_SABR_INPUT_SPEC, {
+        exampleCall: CALIBRATE_SABR_EXAMPLE,
+    });
+    // `null` slips past the `= {}` default and would die on the first option read — reject it typed.
+    validateClosedRequest('calibrateSabrSmile', options, CALIBRATE_SABR_OPTIONS_SPEC, {
+        argumentName: 'options',
+        exampleCall: CALIBRATE_SABR_EXAMPLE,
+    });
+    requireCalibrationIterationBudget('calibrateSabrSmile', options.maximumIterations);
+    const { forward, strikes, impliedVolatilities, timeToExpiryYears } = input;
+    const functionName = 'calibrateSabrSmile';
+    ensurePositive(forward, 'forward', functionName);
+    ensurePositive(timeToExpiryYears, 'timeToExpiryYears', functionName);
+    const n = strikes.length;
+    if (n !== impliedVolatilities.length) {
+        throw new InputError(`${functionName}: strikes and impliedVolatilities must have the same length (${n} vs ${impliedVolatilities.length}).`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { strikes: n, impliedVolatilities: impliedVolatilities.length },
+        });
+    }
+    if (n < 3) {
+        throw new InputError(`${functionName}: need ≥ 3 strikes to identify (α, ρ, ν), got ${n}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { strikes: n },
+        });
+    }
+    for (let i = 0; i < n; i++) {
+        ensurePositive(strikes[i], `strikes[${i}]`, functionName);
+        ensurePositive(impliedVolatilities[i], `impliedVolatilities[${i}]`, functionName);
+    }
+    const beta = options.beta ?? 0.5;
+    if (beta < 0 || beta > 1) {
+        throw new InputError(`${functionName}: beta must be in [0, 1], got ${beta}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { beta },
+        });
+    }
+    const volatilityType = options.volatilityType ?? 'lognormal';
+    // Seed α from the ATM vol, in the convention being fitted: Hagan's ATM lognormal is σ ≈ α/F^{1−β}
+    // (⇒ α ≈ σ·F^{1−β}), but the ATM NORMAL is σ_N ≈ α·F^β (⇒ α ≈ σ_N/F^β). Using the lognormal
+    // relation for a Bachelier fit is wrong by F^{1−2β} — a factor of 100 on a $100 forward at β=0.5 —
+    // which starts the search deep outside Hagan's validity region.
+    const atm = atmVolatility(forward, strikes, impliedVolatilities);
+    const alpha0 = volatilityType === 'normal'
+        ? Math.max(1e-8, atm / Math.pow(forward, beta))
+        : Math.max(1e-4, atm * Math.pow(forward, 1 - beta));
+    // Reparameterize so constraints hold for free: α=e^{x0}, ρ=tanh(x1), ν=e^{x2} — with the OPEN
+    // interval enforced. `Math.tanh` saturates to exactly ±1 in IEEE-754 for |x| ≳ 19, and SABR requires
+    // ρ ∈ (−1, 1) strictly: an LM step that far out made the pricer reject its own trial point
+    // ("rho must be in (-1, 1), got -1") and killed the whole calibration. Same for α/ν, where
+    // `Math.exp` overflows to Infinity (and underflows to 0) well inside the search's reach.
+    const RHO_LIMIT = 1 - 1e-9;
+    const clampToRange = (v, lo, hi) => Math.min(hi, Math.max(lo, v));
+    const toParams = (x) => ({
+        alpha: clampToRange(Math.exp(x[0]), 1e-12, 1e12),
+        beta,
+        rho: clampToRange(Math.tanh(x[1]), -RHO_LIMIT, RHO_LIMIT),
+        nu: clampToRange(Math.exp(x[2]), 1e-12, 1e12),
+    });
+    // The residual SCALE (market vol units) sets the out-of-domain penalty: it must dwarf any real
+    // residual so the optimizer leaves the region, while staying finite and monotone in how far out of
+    // domain the point is (a flat penalty has no gradient and can strand the search on the boundary).
+    const volatilityScale = Math.max(1e-4, impliedVolatilities.reduce((s, v) => s + v, 0) / n);
+    const penaltyFor = (bracket) => 10 * volatilityScale * (1 + Math.log1p(Math.max(0, 1 - bracket)));
+    /** Model vols at `p`, or `undefined` when any strike is outside Hagan's validity region. */
+    const modelVols = (p) => {
+        const out = new Array(n);
+        for (let i = 0; i < n; i++) {
+            try {
+                out[i] = sabrVolatility({
+                    input: { forward, strike: strikes[i], timeToExpiryYears },
+                    parameters: p,
+                    options: { volatilityType },
+                });
+            }
+            catch (e) {
+                if (outOfDomainBracket(e) !== undefined)
+                    return undefined;
+                throw e;
+            }
+        }
+        return out;
+    };
+    // Best point the search actually EVALUATED inside the domain — the fallback if LM's final iterate
+    // lands outside it, so this function never hands back parameters its own smile cannot evaluate.
+    const bestInDomain = { point: null };
+    let outOfDomainProbes = 0;
+    const residuals = (x) => {
+        const p = toParams(x);
+        let sumSquared = 0;
+        let inDomain = true;
+        const out = strikes.map((K, i) => {
+            let model;
+            try {
+                model = sabrVolatility({
+                    input: { forward, strike: K, timeToExpiryYears },
+                    parameters: p,
+                    options: { volatilityType },
+                });
+            }
+            catch (e) {
+                const bracket = outOfDomainBracket(e);
+                if (bracket === undefined)
+                    throw e;
+                if (inDomain)
+                    outOfDomainProbes++; // count PARAMETER SETS, not strikes
+                inDomain = false;
+                return penaltyFor(bracket);
+            }
+            const r = model - impliedVolatilities[i];
+            sumSquared += r * r;
+            return r;
+        });
+        if (inDomain && (bestInDomain.point === null || sumSquared < bestInDomain.point.sumSquared)) {
+            bestInDomain.point = { x: [...x], sumSquared };
+        }
+        return out;
+    };
+    const start = options.initialParameters;
+    if (start !== undefined) {
+        ensurePositive(start.alpha, 'initialParameters.alpha', functionName);
+        ensurePositive(start.nu, 'initialParameters.nu', functionName);
+        if (!Number.isFinite(start.rho) || !(Math.abs(start.rho) < 1)) {
+            throw new InputError(`${functionName}: initialParameters.rho must be a finite correlation in (−1, 1). Received ${String(start.rho)}.`, { code: ErrorCode.InputOutOfRange, context: { field: 'initialParameters.rho' } });
+        }
+    }
+    const x0 = start !== undefined
+        ? [Math.log(start.alpha), Math.atanh(start.rho), Math.log(start.nu)]
+        : [Math.log(alpha0), Math.atanh(-0.3), Math.log(0.5)];
+    const res = levenbergMarquardt(residuals, x0, {
+        maximumIterations: options.maximumIterations ?? 200,
+        tolerance: options.tolerance ?? 1e-12,
+    });
+    const warnings = [];
+    let parameters = toParams(res.parameters);
+    const lmVols = modelVols(parameters);
+    let vols;
+    let converged = res.converged;
+    if (lmVols !== undefined) {
+        vols = lmVols;
+    }
+    else {
+        // LM finished outside Hagan's domain. Returning those parameters would hand back a smile that
+        // THROWS when evaluated (or, worse, a negative vol on an older options build) — fall back to the
+        // best in-domain point the search saw and say the fit did not converge.
+        const feasible = bestInDomain.point;
+        if (feasible === null) {
+            throw new InputError(`${functionName}: every parameter set the search visited fell outside Hagan's ${volatilityType} expansion domain (its 1 + […]·T bracket goes non-positive), so no SABR smile can be fitted to this quote set. Shorten timeToExpiryYears, lower the quoted vols, or fit with volatilityType: '${volatilityType === 'normal' ? 'lognormal' : 'normal'}'.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { forward, timeToExpiryYears, beta, volatilityType },
+            });
+        }
+        parameters = toParams(feasible.x);
+        const fallbackVols = modelVols(parameters);
+        // `feasible` was recorded BECAUSE every strike evaluated there; a re-evaluation that now fails
+        // would mean the pricer is not a pure function of its inputs.
+        if (fallbackVols === undefined) {
+            throw new PostconditionError(`${functionName}: a parameter set that evaluated inside Hagan's domain during the search no longer does on re-evaluation — this is a TotalFinance defect; please report it with these inputs.`, {
+                code: ErrorCode.PostconditionNonFinite,
+                context: { forward, timeToExpiryYears, beta, volatilityType },
+            });
+        }
+        vols = fallbackVols;
+        converged = false;
+        warnings.push(warning(WarningCode.VolatilityCalibrationNotConverged, `calibrateSabrSmile: the Levenberg–Marquardt search ended outside Hagan's ${volatilityType} expansion domain; the returned parameters are the best point it visited INSIDE the domain. Gate on \`converged\` before trusting them.`, 'warn', { iterations: res.iterations, volatilityType }));
+    }
+    if (!converged && warnings.length === 0) {
+        warnings.push(warning(WarningCode.VolatilityCalibrationNotConverged, `calibrateSabrSmile: the Levenberg–Marquardt fit stopped without converging — parameters are the best point found; gate on \`converged\` before trusting them.`, 'warn', { iterations: res.iterations }));
+    }
+    if (outOfDomainProbes > 0) {
+        // Disclosed, not silent: the search ran near (or through) the edge of Hagan's validity region.
+        // The returned parameters are inside it, but a fit that had to be fenced away from the boundary
+        // is a fit the caller should look at twice.
+        warnings.push(warning(WarningCode.ModelLimitation, `calibrateSabrSmile: ${outOfDomainProbes} trial parameter set(s) fell outside Hagan's ${volatilityType} expansion domain and were penalized rather than fitted; the returned parameters are inside it.`, 'info', { outOfDomainProbes, volatilityType }));
+    }
+    // RMSE from the RETURNED parameters (not the optimizer's last norm): after a domain fall-back those
+    // are different points, and the reported error must describe what the caller actually gets.
+    const rmse = Math.sqrt(vols.reduce((s, v, i) => s + (v - impliedVolatilities[i]) ** 2, 0) / n);
+    return {
+        parameters,
+        rmse,
+        converged,
+        iterations: res.iterations,
+        assumptions: {
+            conventionsVersion: CONVENTIONS_VERSION,
+            beta,
+            volatilityType,
+            initialParameters: start !== undefined ? 'supplied' : 'default',
+        },
+        diagnostics: {
+            engine: 'sabr',
+            method: 'levenberg-marquardt + hagan',
+            converged,
+            iterations: res.iterations,
+            warnings,
+        },
+    };
+}
+//# sourceMappingURL=sabr.js.map

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

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

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

@@ -0,0 +1,63 @@
+/**
+ * Volatility skew / smile metrics for a single expiry (spec §10.2).
+ *
+ * Builds the expiry's smile (via {@link VolatilitySurface}) and reports ATM IV, 10/25-delta put/call IVs,
+ * risk reversals, butterflies, directional skews, and the ATM skew slope/curvature in log-moneyness.
+ * Delta points are located in call-delta space: a 25-delta put is the strike whose call-delta equals
+ * `e^{−qt}−0.25` (its put-delta is −0.25); a 25-delta call is call-delta `0.25`.
+ */
+import { type Computed, type MarketInputs, type OptionQuote, type PriceSource } from '../../core/dist/index.js';
+import { type SurfaceModel } from './surface.js';
+export type RiskReversalConvention = 'callMinusPut' | 'putMinusCall';
+/**
+ * Market snapshot for `skew()` — the workspace-canonical {@link MarketInputs}, except `spot` is
+ * optional (it falls back to each quote's `underlyingPrice` when omitted) (WS3.2).
+ */
+export type SkewMarket = Omit<MarketInputs, 'spot'> & {
+    /** Spot price. Falls back to each quote's `underlyingPrice` when omitted. */
+    spot?: number;
+};
+/** Non-market skew configuration: which expiry, the price source, model, and RR convention (WS3.2). */
+export interface SkewConfig {
+    /** The expiry to analyze (ISO label present in the chain). */
+    expiry: string;
+    priceSource?: PriceSource;
+    model?: SurfaceModel;
+    /** Risk-reversal sign convention (default `callMinusPut`). */
+    riskReversalConvention?: RiskReversalConvention;
+}
+export interface SkewMetrics {
+    expiry: string;
+    timeToExpiryYears: number;
+    forward: number;
+    /** ATM-forward implied vol (the smile evaluated at `K = forward`). */
+    atmImpliedVolatility: number;
+    put10DeltaImpliedVolatility: number;
+    put25DeltaImpliedVolatility: number;
+    call25DeltaImpliedVolatility: number;
+    call10DeltaImpliedVolatility: number;
+    /** 25-/10-delta risk reversals (signed per `riskReversalConvention`). */
+    riskReversal25Delta: number;
+    riskReversal10Delta: number;
+    /** 25-/10-delta butterflies: `(wingCall + wingPut)/2 − atmImpliedVolatility`. */
+    butterfly25Delta: number;
+    butterfly10Delta: number;
+    /** Wing IV minus ATM: `put25DeltaImpliedVolatility − atmImpliedVolatility` and `call25DeltaImpliedVolatility − atmImpliedVolatility`. */
+    putSkew: number;
+    callSkew: number;
+    /** `d(iv)/d(logMoneyness)` at the forward (negative for the usual equity put-skew). */
+    skewSlope: number;
+    /** `d²(iv)/d(logMoneyness)²` at the forward (smile convexity). */
+    smileCurvature: number;
+    /** Wing steepness: extra IV in the 10Δ wings over the 25Δ wings, `(iv10P − iv25P) + (iv10C − iv25C)`. */
+    wingSteepness: number;
+}
+export type SkewResult = Computed<SkewMetrics>;
+export interface SkewInput {
+    quotes: OptionQuote[];
+    market: SkewMarket;
+    config: SkewConfig;
+}
+/** Compute skew/smile metrics for one expiry of an option chain. */
+export declare function skew(input: SkewInput): SkewResult;
+//# sourceMappingURL=skew.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"skew.d.ts","sourceRoot":"","sources":["../src/skew.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAGL,KAAK,QAAQ,EAIb,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,WAAW,EAIjB,MAAM,0BAAoB,CAAC;AAC5B,OAAO,EAAE,KAAK,YAAY,EAAqB,MAAM,cAAc,CAAC;AAsBpE,MAAM,MAAM,sBAAsB,GAAG,cAAc,GAAG,cAAc,CAAC;AAErE;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,GAAG;IACpD,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,uGAAuG;AACvG,MAAM,WAAW,UAAU;IACzB,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,8DAA8D;IAC9D,sBAAsB,CAAC,EAAE,sBAAsB,CAAC;CACjD;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,iBAAiB,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,oBAAoB,EAAE,MAAM,CAAC;IAC7B,2BAA2B,EAAE,MAAM,CAAC;IACpC,2BAA2B,EAAE,MAAM,CAAC;IACpC,4BAA4B,EAAE,MAAM,CAAC;IACrC,4BAA4B,EAAE,MAAM,CAAC;IACrC,yEAAyE;IACzE,mBAAmB,EAAE,MAAM,CAAC;IAC5B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,iFAAiF;IACjF,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,yIAAyI;IACzI,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,uFAAuF;IACvF,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,cAAc,EAAE,MAAM,CAAC;IACvB,yGAAyG;IACzG,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC,WAAW,CAAC,CAAC;AA8B/C,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,EAAE,UAAU,CAAC;CACpB;AAED,oEAAoE;AACpE,wBAAgB,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU,CAiHjD"}