@insiderfinance/totalfinance 0.1.0

package/modules/volatility/dist/otm-strip.js

@@ -0,0 +1,181 @@
+/**
+ * Shared OTM-strip extraction for the model-free chain indices (variance index, tail-risk / SKEW). From
+ * a raw option chain it derives, per expiry, the put–call-parity **forward** and the **OTM strip** (puts
+ * below the forward, calls above, averaged at the money) that both the DDKZ variance replication and the
+ * Bakshi–Kapadia–Madan moment estimators integrate over. An expiry that can't be replicated (< 3 OTM
+ * strikes, no strike carrying both a call and a put, no bracketing forward strike) is dropped with a
+ * disclosed warning — never fabricated. Internal to `@insiderfinance/totalfinance/volatility` (not part of the package surface).
+ */
+import { ErrorCode, InputError, WarningCode, optionExpiryToMs, requireArgumentObject, resolveValuationAsOf, usEquityMarketDayIndex, warning, yearFraction, } from '../../core/dist/index.js';
+const DAY_MS = 86_400_000;
+/**
+ * The US options market's calendar day (America/New_York) as a whole-day index. Expiries resolve to
+ * 16:00 ET, i.e. 20:00/21:00 **UTC**, so flooring both instants to UTC midnight counts the wrong
+ * boundary: an evening-ET snapshot (21:30 ET Thursday = 01:30 UTC Friday) already sits on the next
+ * UTC date, and every `daysToExpiry` on the chain came back one day SHORT — which shifts the
+ * variance-index T₁/T₂ interpolation weights (and can drop the 30-day bracket) at the UTC rollover,
+ * mid-session in Asia. Pure: reads only the timestamp it is given.
+ */
+function marketDayIndex(epochMs) {
+    return usEquityMarketDayIndex(epochMs);
+}
+const DATE_ONLY = /^(\d{4})-(\d{2})-(\d{2})$/;
+/**
+ * The market day of the `asOf` **as the caller expressed it**: a date-only `'YYYY-MM-DD'` names a
+ * trading DATE and is taken literally (core resolves it to UTC midnight = 19:00/20:00 ET the previous
+ * day, which must not be re-zoned into the day before); anything else is an instant, mapped to the ET
+ * date it falls on.
+ */
+function asOfMarketDayIndex(asOf, resolvedMs) {
+    if (typeof asOf === 'string') {
+        const m = DATE_ONLY.exec(asOf);
+        if (m)
+            return Math.round(Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3])) / DAY_MS);
+    }
+    return marketDayIndex(resolvedMs);
+}
+/** Best available mid for a quote: `mid`, else `(bid+ask)/2`, else `mark`, else `last`. */
+export function midOf(q) {
+    if (typeof q.mid === 'number' && Number.isFinite(q.mid))
+        return q.mid;
+    if (typeof q.bid === 'number' &&
+        typeof q.ask === 'number' &&
+        Number.isFinite(q.bid) &&
+        Number.isFinite(q.ask)) {
+        return (q.bid + q.ask) / 2;
+    }
+    if (typeof q.mark === 'number' && Number.isFinite(q.mark))
+        return q.mark;
+    if (typeof q.last === 'number' && Number.isFinite(q.last))
+        return q.last;
+    return undefined;
+}
+/** Group a chain into `expiry → strike → { call, put } mids`, validating each quote's contract. */
+function groupChain(quotes, functionName) {
+    const byExpiry = new Map();
+    for (let i = 0; i < quotes.length; i++) {
+        const q = quotes[i];
+        requireArgumentObject(functionName, `quotes[${i}]`, q);
+        const c = q.contract;
+        requireArgumentObject(functionName, `quotes[${i}].contract`, c);
+        const { type, strike, expiry } = c;
+        if ((type !== 'call' && type !== 'put') ||
+            typeof strike !== 'number' ||
+            typeof expiry !== 'string') {
+            throw new InputError(`${functionName}: quotes[${i}].contract must be { type: 'call'|'put', strike: number, expiry: 'YYYY-MM-DD' }.`, { code: ErrorCode.InputWrongType, context: { index: i } });
+        }
+        const price = midOf(q);
+        if (price === undefined || !(price >= 0))
+            continue; // no usable mid — skip this quote
+        let byStrike = byExpiry.get(expiry);
+        if (byStrike === undefined) {
+            byStrike = new Map();
+            byExpiry.set(expiry, byStrike);
+        }
+        const cp = byStrike.get(strike) ?? {};
+        if (type === 'call')
+            cp.call = price;
+        else
+            cp.put = price;
+        byStrike.set(strike, cp);
+    }
+    return byExpiry;
+}
+/** Extract one expiry's OTM strip (forward + strikes + OTM prices), or a disclosed skip reason. */
+function stripForExpiry(input) {
+    const { expiry, byStrike, asOf: asOfMs, asOfDayIndex, riskFreeRate } = input;
+    const expiryMs = optionExpiryToMs(expiry);
+    const t = yearFraction(asOfMs, expiryMs, 'ACT/365F');
+    if (!(t > 0))
+        return { skip: 'already expired' };
+    // Forward from put–call parity at the strike with the smallest |C − P| (most at-the-money).
+    const paired = [...byStrike.entries()].filter(([, cp]) => cp.call !== undefined && cp.put !== undefined);
+    if (paired.length === 0)
+        return { skip: 'no strike carries both a call and a put to imply the forward' };
+    let kStar = paired[0][0];
+    let bestGap = Infinity;
+    for (const [k, cp] of paired) {
+        const gap = Math.abs(cp.call - cp.put);
+        if (gap < bestGap) {
+            bestGap = gap;
+            kStar = k;
+        }
+    }
+    const disc = Math.exp(riskFreeRate * t);
+    const cpStar = byStrike.get(kStar);
+    const forward = kStar + disc * (cpStar.call - cpStar.put);
+    if (!(forward > 0))
+        return { skip: `non-positive parity forward (${forward})` };
+    // K0 = the highest strike ≤ forward; the OTM strip is puts below, calls above, averaged at K0.
+    const strikesAsc = [...byStrike.keys()].sort((a, b) => a - b);
+    let k0;
+    for (const k of strikesAsc)
+        if (k <= forward)
+            k0 = k;
+    if (k0 === undefined)
+        return { skip: `no strike at or below the forward ${forward}` };
+    const strikes = [];
+    const otmPrices = [];
+    for (const k of strikesAsc) {
+        const cp = byStrike.get(k);
+        let price;
+        if (k < k0)
+            price = cp.put;
+        else if (k > k0)
+            price = cp.call;
+        else
+            price =
+                cp.call !== undefined && cp.put !== undefined
+                    ? (cp.call + cp.put) / 2
+                    : (cp.call ?? cp.put);
+        if (price === undefined || !Number.isFinite(price) || price < 0)
+            continue;
+        strikes.push(k);
+        otmPrices.push(price);
+    }
+    if (strikes.length < 3)
+        return { skip: `only ${strikes.length} usable OTM strikes (need ≥ 3)` };
+    return {
+        expiry,
+        timeToExpiryYears: t,
+        // Whole calendar days between the two MARKET dates (America/New_York). `expiryMs` is the 16:00-ET
+        // expiry instant (≈ 20:00–21:00 UTC), so neither instant may be compared on the UTC clock: the
+        // expiry would round a day up, and an evening-ET `asOf` a day down.
+        daysToExpiry: marketDayIndex(expiryMs) - asOfDayIndex,
+        forward,
+        strikes,
+        otmPrices,
+    };
+}
+/**
+ * Build the per-expiry OTM strips from a chain (ascending by DTE), disclosing every dropped expiry. The
+ * shared front-door for the model-free chain indices; each consumer computes its own moments over the
+ * returned strips.
+ */
+export function extractOtmStrips(quotes, options, functionName) {
+    const asOfMs = resolveValuationAsOf(options.asOf, functionName);
+    const asOfDayIndex = asOfMarketDayIndex(options.asOf, asOfMs);
+    const byExpiry = groupChain(quotes, functionName);
+    const strips = [];
+    const warnings = [];
+    for (const [expiry, byStrike] of byExpiry) {
+        const s = stripForExpiry({
+            expiry,
+            byStrike,
+            asOf: asOfMs,
+            asOfDayIndex,
+            riskFreeRate: options.rate,
+        });
+        if ('skip' in s) {
+            warnings.push(warning(WarningCode.ModelLimitation, `expiry ${expiry} dropped: ${s.skip}.`, 'info', {
+                expiry,
+            }));
+        }
+        else {
+            strips.push(s);
+        }
+    }
+    strips.sort((a, b) => a.daysToExpiry - b.daysToExpiry);
+    return { strips, warnings, asOfMs };
+}
+//# sourceMappingURL=otm-strip.js.map

package/modules/volatility/dist/otm-strip.js.map

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

package/modules/volatility/dist/risk-reversal.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Risk reversal & butterfly (spec: `docs/specs/risk-reversal-butterfly.md`). The standard FX/crypto
+ * smile-quoting decomposition: a smile ⇄ `(ATM, riskReversal, butterfly)`.
+ *
+ *   - `riskReversalButterfly` — from a smile function, find the δ-delta wing strikes and report the ATM
+ *     vol, the risk reversal (`callVolatility − putVolatility`, the skew) and the butterfly (`avg − ATM`, the curvature).
+ *   - `smileFromQuotes` — the exact inverse: from `(ATM, RR, BF)` recover the three `(strike, vol)` anchors.
+ *
+ * Forward delta (`Δ_call = N(d₁)`) throughout — spot/rate-free.
+ */
+import { type Diagnostics } from '../../core/dist/index.js';
+/** Input for {@link riskReversalButterfly}. */
+export interface RiskReversalButterflyInput {
+    /** Forward price of the underlying. */
+    forward: number;
+    /** Time to expiry in years. */
+    timeToExpiryYears: number;
+    /** The smile: strike → implied vol (from any fit — SVI, SSVI, volatilitySurface, …). */
+    smile: (strike: number) => number;
+    /** Delta level for the wings (0.25 = 25-delta). Default 0.25. Must be in `(0, 0.5)`. */
+    delta?: number;
+}
+/** The risk-reversal / butterfly decomposition of a smile. */
+export interface RiskReversalButterfly {
+    /** ATM vol (at `K = forward`). */
+    atmVolatility: number;
+    /** The δ-delta call strike. */
+    callStrike: number;
+    /** The vol at the call strike. */
+    callVolatility: number;
+    /** The δ-delta put strike. */
+    putStrike: number;
+    /** The vol at the put strike. */
+    putVolatility: number;
+    /** `callVolatility − putVolatility` — the skew (< 0 ⇒ puts bid). */
+    riskReversal: number;
+    /** `(callVolatility + putVolatility)/2 − atmVolatility` — the curvature (> 0 ⇒ smile). */
+    butterfly: number;
+    delta: number;
+    assumptions: {
+        conventionsVersion: string;
+        deltaConvention: 'forward';
+        delta: number;
+    };
+    diagnostics: Diagnostics;
+}
+/**
+ * Decompose a smile into the ATM vol, the δ-delta **risk reversal** (`callVolatility − putVolatility`, the skew) and
+ * **butterfly** (`(callVolatility + putVolatility)/2 − ATM`, the curvature) — the standard FX/crypto quoting triple.
+ * Forward delta throughout. See `docs/specs/risk-reversal-butterfly.md`.
+ */
+export declare function riskReversalButterfly(input: RiskReversalButterflyInput): RiskReversalButterfly;
+/** Input for {@link smileFromQuotes}. */
+export interface SmileFromQuotesInput {
+    forward: number;
+    timeToExpiryYears: number;
+    /** ATM vol. */
+    atmVolatility: number;
+    /** Risk reversal (`callVolatility − putVolatility`). */
+    riskReversal: number;
+    /** Butterfly (`(callVolatility + putVolatility)/2 − atmVolatility`). */
+    butterfly: number;
+    /** Delta level. Default 0.25. */
+    delta?: number;
+}
+/** The three `(strike, vol)` smile anchors implied by the quotes. */
+export interface SmileAnchors {
+    putStrike: number;
+    putVolatility: number;
+    atmStrike: number;
+    atmVolatility: number;
+    callStrike: number;
+    callVolatility: number;
+    delta: number;
+    assumptions: {
+        conventionsVersion: string;
+        deltaConvention: 'forward';
+        delta: number;
+    };
+    diagnostics: Diagnostics;
+}
+/**
+ * Recover the three smile anchors — the δ-delta put, the ATM, and the δ-delta call `(strike, vol)` — from
+ * the `(ATM, riskReversal, butterfly)` quotes. Exact inverse of {@link riskReversalButterfly}: the wing
+ * volatilities are `ATM + BF ± RR/2`, and each wing strike is closed form (`K = F·exp(½σ²T − Φ⁻¹(·)σ√T)`) since
+ * the vol is now known. See `docs/specs/risk-reversal-butterfly.md`.
+ */
+export declare function smileFromQuotes(input: SmileFromQuotesInput): SmileAnchors;
+//# sourceMappingURL=risk-reversal.d.ts.map

package/modules/volatility/dist/risk-reversal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"risk-reversal.d.ts","sourceRoot":"","sources":["../src/risk-reversal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAGL,KAAK,WAAW,EAMjB,MAAM,0BAAoB,CAAC;AA8D5B,+CAA+C;AAC/C,MAAM,WAAW,0BAA0B;IACzC,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,wFAAwF;IACxF,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;IAClC,wFAAwF;IACxF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,8DAA8D;AAC9D,MAAM,WAAW,qBAAqB;IACpC,kCAAkC;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,+BAA+B;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,cAAc,EAAE,MAAM,CAAC;IACvB,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,YAAY,EAAE,MAAM,CAAC;IACrB,0FAA0F;IAC1F,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE;QAAE,kBAAkB,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,SAAS,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACvF,WAAW,EAAE,WAAW,CAAC;CAC1B;AA6CD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,0BAA0B,GAAG,qBAAqB,CA6D9F;AAMD,yCAAyC;AACzC,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,wDAAwD;IACxD,YAAY,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qEAAqE;AACrE,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE;QAAE,kBAAkB,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,SAAS,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACvF,WAAW,EAAE,WAAW,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,YAAY,CAoDzE"}

package/modules/volatility/dist/risk-reversal.js

@@ -0,0 +1,176 @@
+/**
+ * Risk reversal & butterfly (spec: `docs/specs/risk-reversal-butterfly.md`). The standard FX/crypto
+ * smile-quoting decomposition: a smile ⇄ `(ATM, riskReversal, butterfly)`.
+ *
+ *   - `riskReversalButterfly` — from a smile function, find the δ-delta wing strikes and report the ATM
+ *     vol, the risk reversal (`callVolatility − putVolatility`, the skew) and the butterfly (`avg − ATM`, the curvature).
+ *   - `smileFromQuotes` — the exact inverse: from `(ATM, RR, BF)` recover the three `(strike, vol)` anchors.
+ *
+ * Forward delta (`Δ_call = N(d₁)`) throughout — spot/rate-free.
+ */
+import { CONVENTIONS_VERSION, ErrorCode, InputError, ensureFinite, ensurePositive, validateClosedRequest, } from '../../core/dist/index.js';
+import { brent, normalCdf, normalInverseCdf } from '../../math/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 riskReversalSpecOf(key) {
+    const spec = VALIDATION_SPECS[key];
+    if (spec === undefined) {
+        throw new Error(`risk-reversal: no generated validation spec for '${key}' — run \`pnpm validation:update\``);
+    }
+    return spec;
+}
+const RISK_REVERSAL_BUTTERFLY_SPEC = riskReversalSpecOf('riskReversalButterfly#0');
+const SMILE_FROM_QUOTES_SPEC = riskReversalSpecOf('smileFromQuotes#0');
+const RISK_REVERSAL_BUTTERFLY_EXAMPLE = () => 'riskReversalButterfly({ forward: 100, timeToExpiryYears: 0.25, smile: (strike) => 0.2, delta: 0.25 })';
+const SMILE_FROM_QUOTES_EXAMPLE = () => 'smileFromQuotes({ forward: 100, timeToExpiryYears: 0.25, atmVolatility: 0.2, ' +
+    'riskReversal: -0.02, butterfly: 0.01 })';
+const assumptionsFor = (delta) => ({
+    conventionsVersion: CONVENTIONS_VERSION,
+    deltaConvention: 'forward',
+    delta,
+});
+/** Forward-delta of a call at strike `K` with vol `σ`: `N(d₁)`. */
+function forwardCallDelta(input) {
+    const { forward: F, strike: K, volatility: sigma, sqrtTime: sqrtT } = input;
+    const d1 = (Math.log(F / K) + 0.5 * sigma * sigma * sqrtT * sqrtT) / (sigma * sqrtT);
+    return normalCdf(d1);
+}
+/** Validate the `delta` level: a finite number in `(0, 0.5)`. */
+function requireDelta(delta, functionName) {
+    ensureFinite(delta, 'delta', functionName);
+    if (!(delta > 0 && delta < 0.5)) {
+        throw new InputError(`${functionName}: delta must be in (0, 0.5); got ${delta}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { delta },
+        });
+    }
+}
+/** Root-find the strike where the forward call-delta equals `target`, on `[lo, hi]`. */
+function solveDeltaStrike(request) {
+    const { input, target, lowerBound: lo, upperBound: hi, sqrtTime: sqrtT, label, functionName, } = request;
+    const F = input.forward;
+    const res = brent((K) => {
+        const sigma = input.smile(K);
+        if (!(sigma > 0) || !Number.isFinite(sigma))
+            return Number.NaN;
+        return (forwardCallDelta({ forward: F, strike: K, volatility: sigma, sqrtTime: sqrtT }) - target);
+    }, lo, hi, { tolerance: 1e-12, maximumIterations: 200 });
+    if (!res.converged || !Number.isFinite(res.value)) {
+        throw new InputError(`${functionName}: could not find a ${label} strike with forward call-delta ${target.toFixed(4)} on the supplied smile — the smile is too extreme for this delta (try a larger delta, or check the smile).`, { code: ErrorCode.SolverNoConvergence, context: { target, bracket: [lo, hi] } });
+    }
+    return res.value;
+}
+/**
+ * Decompose a smile into the ATM vol, the δ-delta **risk reversal** (`callVolatility − putVolatility`, the skew) and
+ * **butterfly** (`(callVolatility + putVolatility)/2 − ATM`, the curvature) — the standard FX/crypto quoting triple.
+ * Forward delta throughout. See `docs/specs/risk-reversal-butterfly.md`.
+ */
+export function riskReversalButterfly(input) {
+    const functionName = 'riskReversalButterfly';
+    validateClosedRequest(functionName, input, RISK_REVERSAL_BUTTERFLY_SPEC, {
+        exampleCall: RISK_REVERSAL_BUTTERFLY_EXAMPLE,
+    });
+    ensurePositive(input.forward, 'forward', functionName);
+    ensurePositive(input.timeToExpiryYears, 'timeToExpiryYears', functionName);
+    const delta = input.delta ?? 0.25;
+    requireDelta(delta, functionName);
+    const F = input.forward;
+    const sqrtT = Math.sqrt(input.timeToExpiryYears);
+    const atmVolatility = input.smile(F);
+    ensurePositive(atmVolatility, 'smile(forward)', functionName);
+    // Bracket the wings ±8 ATM-vol standard deviations from the forward.
+    const span = Math.exp(8 * atmVolatility * sqrtT);
+    const callStrike = solveDeltaStrike({
+        input,
+        target: delta,
+        lowerBound: F,
+        upperBound: F * span,
+        sqrtTime: sqrtT,
+        label: 'call',
+        functionName,
+    });
+    // Put |Δ| = 1 − N(d₁) = δ ⇒ N(d₁) = 1 − δ (an OTM put below F).
+    const putStrike = solveDeltaStrike({
+        input,
+        target: 1 - delta,
+        lowerBound: F / span,
+        upperBound: F,
+        sqrtTime: sqrtT,
+        label: 'put',
+        functionName,
+    });
+    const callVolatility = input.smile(callStrike);
+    const putVolatility = input.smile(putStrike);
+    ensurePositive(callVolatility, 'smile(callStrike)', functionName);
+    ensurePositive(putVolatility, 'smile(putStrike)', functionName);
+    const riskReversal = callVolatility - putVolatility;
+    const butterfly = (callVolatility + putVolatility) / 2 - atmVolatility;
+    return {
+        atmVolatility,
+        callStrike,
+        callVolatility,
+        putStrike,
+        putVolatility,
+        riskReversal,
+        butterfly,
+        delta,
+        assumptions: assumptionsFor(delta),
+        diagnostics: {
+            engine: 'risk-reversal-butterfly',
+            method: 'forward-delta wings',
+            converged: true,
+            warnings: [],
+        },
+    };
+}
+/**
+ * Recover the three smile anchors — the δ-delta put, the ATM, and the δ-delta call `(strike, vol)` — from
+ * the `(ATM, riskReversal, butterfly)` quotes. Exact inverse of {@link riskReversalButterfly}: the wing
+ * volatilities are `ATM + BF ± RR/2`, and each wing strike is closed form (`K = F·exp(½σ²T − Φ⁻¹(·)σ√T)`) since
+ * the vol is now known. See `docs/specs/risk-reversal-butterfly.md`.
+ */
+export function smileFromQuotes(input) {
+    const functionName = 'smileFromQuotes';
+    validateClosedRequest(functionName, input, SMILE_FROM_QUOTES_SPEC, {
+        exampleCall: SMILE_FROM_QUOTES_EXAMPLE,
+    });
+    ensurePositive(input.forward, 'forward', functionName);
+    ensurePositive(input.timeToExpiryYears, 'timeToExpiryYears', functionName);
+    ensurePositive(input.atmVolatility, 'atmVolatility', functionName);
+    const delta = input.delta ?? 0.25;
+    requireDelta(delta, functionName);
+    const F = input.forward;
+    const sqrtT = Math.sqrt(input.timeToExpiryYears);
+    const callVolatility = input.atmVolatility + input.butterfly + input.riskReversal / 2;
+    const putVolatility = input.atmVolatility + input.butterfly - input.riskReversal / 2;
+    if (!(callVolatility > 0) || !(putVolatility > 0)) {
+        throw new InputError(`${functionName}: the quotes imply a non-positive wing vol (call ${callVolatility}, put ${putVolatility}); check ATM/RR/BF.`, { code: ErrorCode.InputOutOfRange, context: { callVolatility, putVolatility } });
+    }
+    // K = F·exp(½σ²T − Φ⁻¹(N(d₁))·σ√T); N(d₁) = δ (call), 1 − δ (put).
+    const callStrike = F *
+        Math.exp(0.5 * callVolatility * callVolatility * sqrtT * sqrtT -
+            normalInverseCdf(delta) * callVolatility * sqrtT);
+    const putStrike = F *
+        Math.exp(0.5 * putVolatility * putVolatility * sqrtT * sqrtT -
+            normalInverseCdf(1 - delta) * putVolatility * sqrtT);
+    return {
+        putStrike,
+        putVolatility,
+        atmStrike: F,
+        atmVolatility: input.atmVolatility,
+        callStrike,
+        callVolatility,
+        delta,
+        assumptions: assumptionsFor(delta),
+        diagnostics: {
+            engine: 'smile-from-quotes',
+            method: 'closed-form anchors',
+            converged: true,
+            warnings: [],
+        },
+    };
+}
+//# sourceMappingURL=risk-reversal.js.map

package/modules/volatility/dist/risk-reversal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"risk-reversal.js","sourceRoot":"","sources":["../src/risk-reversal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAEL,mBAAmB,EAEnB,SAAS,EACT,UAAU,EACV,YAAY,EACZ,cAAc,EACd,qBAAqB,GACtB,MAAM,0BAAoB,CAAC;AAC5B,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,0BAAoB,CAAC;AACxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAEnE;;;GAGG;AACH,SAAS,kBAAkB,CAAC,GAAW;IACrC,MAAM,IAAI,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACnC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CACb,oDAAoD,GAAG,oCAAoC,CAC5F,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,4BAA4B,GAAG,kBAAkB,CAAC,yBAAyB,CAAC,CAAC;AACnF,MAAM,sBAAsB,GAAG,kBAAkB,CAAC,mBAAmB,CAAC,CAAC;AAEvE,MAAM,+BAA+B,GAAG,GAAW,EAAE,CACnD,uGAAuG,CAAC;AAC1G,MAAM,yBAAyB,GAAG,GAAW,EAAE,CAC7C,+EAA+E;IAC/E,yCAAyC,CAAC;AAE5C,MAAM,cAAc,GAAG,CACrB,KAAa,EAC8D,EAAE,CAAC,CAAC;IAC/E,kBAAkB,EAAE,mBAAmB;IACvC,eAAe,EAAE,SAAS;IAC1B,KAAK;CACN,CAAC,CAAC;AAEH,mEAAmE;AACnE,SAAS,gBAAgB,CAAC,KAKzB;IACC,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,UAAU,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC;IAC5E,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC;IACrF,OAAO,SAAS,CAAC,EAAE,CAAC,CAAC;AACvB,CAAC;AAED,iEAAiE;AACjE,SAAS,YAAY,CAAC,KAAa,EAAE,YAAoB;IACvD,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC;IAC3C,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,GAAG,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,UAAU,CAAC,GAAG,YAAY,oCAAoC,KAAK,GAAG,EAAE;YAChF,IAAI,EAAE,SAAS,CAAC,eAAe;YAC/B,OAAO,EAAE,EAAE,KAAK,EAAE;SACnB,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAuCD,wFAAwF;AACxF,SAAS,gBAAgB,CAAC,OAQzB;IACC,MAAM,EACJ,KAAK,EACL,MAAM,EACN,UAAU,EAAE,EAAE,EACd,UAAU,EAAE,EAAE,EACd,QAAQ,EAAE,KAAK,EACf,KAAK,EACL,YAAY,GACb,GAAG,OAAO,CAAC;IACZ,MAAM,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC;IACxB,MAAM,GAAG,GAAG,KAAK,CACf,CAAC,CAAC,EAAE,EAAE;QACJ,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAC7B,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,OAAO,MAAM,CAAC,GAAG,CAAC;QAC/D,OAAO,CACL,gBAAgB,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,UAAU,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM,CACzF,CAAC;IACJ,CAAC,EACD,EAAE,EACF,EAAE,EACF,EAAE,SAAS,EAAE,KAAK,EAAE,iBAAiB,EAAE,GAAG,EAAE,CAC7C,CAAC;IACF,IAAI,CAAC,GAAG,CAAC,SAAS,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,UAAU,CAClB,GAAG,YAAY,sBAAsB,KAAK,mCAAmC,MAAM,CAAC,OAAO,CACzF,CAAC,CACF,4GAA4G,EAC7G,EAAE,IAAI,EAAE,SAAS,CAAC,mBAAmB,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,CAChF,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC,KAAK,CAAC;AACnB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAiC;IACrE,MAAM,YAAY,GAAG,uBAAuB,CAAC;IAC7C,qBAAqB,CAAC,YAAY,EAAE,KAAK,EAAE,4BAA4B,EAAE;QACvE,WAAW,EAAE,+BAA+B;KAC7C,CAAC,CAAC;IACH,cAAc,CAAC,KAAK,CAAC,OAAO,EAAE,SAAS,EAAE,YAAY,CAAC,CAAC;IACvD,cAAc,CAAC,KAAK,CAAC,iBAAiB,EAAE,mBAAmB,EAAE,YAAY,CAAC,CAAC;IAC3E,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,IAAI,CAAC;IAClC,YAAY,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;IAElC,MAAM,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC;IACxB,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;IACjD,MAAM,aAAa,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACrC,cAAc,CAAC,aAAa,EAAE,gBAAgB,EAAE,YAAY,CAAC,CAAC;IAE9D,qEAAqE;IACrE,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,aAAa,GAAG,KAAK,CAAC,CAAC;IACjD,MAAM,UAAU,GAAG,gBAAgB,CAAC;QAClC,KAAK;QACL,MAAM,EAAE,KAAK;QACb,UAAU,EAAE,CAAC;QACb,UAAU,EAAE,CAAC,GAAG,IAAI;QACpB,QAAQ,EAAE,KAAK;QACf,KAAK,EAAE,MAAM;QACb,YAAY;KACb,CAAC,CAAC;IACH,gEAAgE;IAChE,MAAM,SAAS,GAAG,gBAAgB,CAAC;QACjC,KAAK;QACL,MAAM,EAAE,CAAC,GAAG,KAAK;QACjB,UAAU,EAAE,CAAC,GAAG,IAAI;QACpB,UAAU,EAAE,CAAC;QACb,QAAQ,EAAE,KAAK;QACf,KAAK,EAAE,KAAK;QACZ,YAAY;KACb,CAAC,CAAC;IAEH,MAAM,cAAc,GAAG,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAC/C,MAAM,aAAa,GAAG,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAC7C,cAAc,CAAC,cAAc,EAAE,mBAAmB,EAAE,YAAY,CAAC,CAAC;IAClE,cAAc,CAAC,aAAa,EAAE,kBAAkB,EAAE,YAAY,CAAC,CAAC;IAChE,MAAM,YAAY,GAAG,cAAc,GAAG,aAAa,CAAC;IACpD,MAAM,SAAS,GAAG,CAAC,cAAc,GAAG,aAAa,CAAC,GAAG,CAAC,GAAG,aAAa,CAAC;IAEvE,OAAO;QACL,aAAa;QACb,UAAU;QACV,cAAc;QACd,SAAS;QACT,aAAa;QACb,YAAY;QACZ,SAAS;QACT,KAAK;QACL,WAAW,EAAE,cAAc,CAAC,KAAK,CAAC;QAClC,WAAW,EAAE;YACX,MAAM,EAAE,yBAAyB;YACjC,MAAM,EAAE,qBAAqB;YAC7B,SAAS,EAAE,IAAI;YACf,QAAQ,EAAE,EAAE;SACb;KACF,CAAC;AACJ,CAAC;AAiCD;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,KAA2B;IACzD,MAAM,YAAY,GAAG,iBAAiB,CAAC;IACvC,qBAAqB,CAAC,YAAY,EAAE,KAAK,EAAE,sBAAsB,EAAE;QACjE,WAAW,EAAE,yBAAyB;KACvC,CAAC,CAAC;IACH,cAAc,CAAC,KAAK,CAAC,OAAO,EAAE,SAAS,EAAE,YAAY,CAAC,CAAC;IACvD,cAAc,CAAC,KAAK,CAAC,iBAAiB,EAAE,mBAAmB,EAAE,YAAY,CAAC,CAAC;IAC3E,cAAc,CAAC,KAAK,CAAC,aAAa,EAAE,eAAe,EAAE,YAAY,CAAC,CAAC;IACnE,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,IAAI,CAAC;IAClC,YAAY,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;IAElC,MAAM,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC;IACxB,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;IACjD,MAAM,cAAc,GAAG,KAAK,CAAC,aAAa,GAAG,KAAK,CAAC,SAAS,GAAG,KAAK,CAAC,YAAY,GAAG,CAAC,CAAC;IACtF,MAAM,aAAa,GAAG,KAAK,CAAC,aAAa,GAAG,KAAK,CAAC,SAAS,GAAG,KAAK,CAAC,YAAY,GAAG,CAAC,CAAC;IACrF,IAAI,CAAC,CAAC,cAAc,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,aAAa,GAAG,CAAC,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,UAAU,CAClB,GAAG,YAAY,oDAAoD,cAAc,SAAS,aAAa,qBAAqB,EAC5H,EAAE,IAAI,EAAE,SAAS,CAAC,eAAe,EAAE,OAAO,EAAE,EAAE,cAAc,EAAE,aAAa,EAAE,EAAE,CAChF,CAAC;IACJ,CAAC;IAED,mEAAmE;IACnE,MAAM,UAAU,GACd,CAAC;QACD,IAAI,CAAC,GAAG,CACN,GAAG,GAAG,cAAc,GAAG,cAAc,GAAG,KAAK,GAAG,KAAK;YACnD,gBAAgB,CAAC,KAAK,CAAC,GAAG,cAAc,GAAG,KAAK,CACnD,CAAC;IACJ,MAAM,SAAS,GACb,CAAC;QACD,IAAI,CAAC,GAAG,CACN,GAAG,GAAG,aAAa,GAAG,aAAa,GAAG,KAAK,GAAG,KAAK;YACjD,gBAAgB,CAAC,CAAC,GAAG,KAAK,CAAC,GAAG,aAAa,GAAG,KAAK,CACtD,CAAC;IAEJ,OAAO;QACL,SAAS;QACT,aAAa;QACb,SAAS,EAAE,CAAC;QACZ,aAAa,EAAE,KAAK,CAAC,aAAa;QAClC,UAAU;QACV,cAAc;QACd,KAAK;QACL,WAAW,EAAE,cAAc,CAAC,KAAK,CAAC;QAClC,WAAW,EAAE;YACX,MAAM,EAAE,mBAAmB;YAC3B,MAAM,EAAE,qBAAqB;YAC7B,SAAS,EAAE,IAAI;YACf,QAAQ,EAAE,EAAE;SACb;KACF,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,67 @@
+/**
+ * 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 { type Computed, type OptionType } from '../../core/dist/index.js';
+import { type SabrInput, type SabrParameters, type SabrVolatilityType } from '../../options/dist/index.js';
+/** Knobs for {@link sabrBartlettGreeks}. */
+export interface SabrBartlettOptions {
+    /** Hagan expansion: `'lognormal'` (Black, default) or `'normal'` (Bachelier). */
+    volatilityType?: SabrVolatilityType;
+}
+export interface SabrBartlettGreeksInput {
+    type: OptionType;
+    input: SabrInput;
+    parameters: SabrParameters;
+    options?: SabrBartlettOptions;
+}
+/** The Bartlett (minimum-variance) SABR greeks, alongside the naive SABR greeks they adjust. */
+export interface SabrBartlettGreeks {
+    /** Hagan implied vol at `(F, K, t)`. */
+    impliedVolatility: number;
+    /** `∂V/∂F` holding parameters fixed — the naive SABR (model) delta, per 1.00 of forward. */
+    sabrDelta: number;
+    /** The Bartlett minimum-variance delta, per 1.00 of forward. */
+    bartlettDelta: number;
+    /** `bartlettDelta − sabrDelta` — the correlation contribution to the delta. */
+    deltaAdjustment: number;
+    /** `∂V/∂α`, per 1% of `α` — the naive SABR vega. */
+    sabrVega: number;
+    /** The Bartlett minimum-variance vega, per 1% of `α`. */
+    bartlettVega: number;
+    /** `bartlettVega − sabrVega` — the correlation contribution to the vega. */
+    vegaAdjustment: number;
+    /** `∂²V/∂F²` holding parameters fixed — the naive SABR gamma, per 1.00 of forward. */
+    sabrGamma: number;
+    /** The Bartlett minimum-variance gamma — `d²V/dF²` along the correlated hedge path. */
+    bartlettGamma: number;
+    /** `bartlettGamma − sabrGamma` — the correlation contribution to the gamma (≈ 0 at the money). */
+    gammaAdjustment: number;
+}
+/**
+ * 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 declare function sabrBartlettGreeks(request: SabrBartlettGreeksInput): Computed<SabrBartlettGreeks, {
+    measure: 'min-variance-hedge';
+    volatilityType: SabrVolatilityType;
+}>;
+//# sourceMappingURL=sabr-delta.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sabr-delta.d.ts","sourceRoot":"","sources":["../src/sabr-delta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAIL,KAAK,QAAQ,EAGb,KAAK,UAAU,EAIhB,MAAM,0BAAoB,CAAC;AAC5B,OAAO,EACL,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACxB,MAAM,6BAAuB,CAAC;AAwB/B,4CAA4C;AAC5C,MAAM,WAAW,mBAAmB;IAClC,iFAAiF;IACjF,cAAc,CAAC,EAAE,kBAAkB,CAAC;CACrC;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,SAAS,CAAC;IACjB,UAAU,EAAE,cAAc,CAAC;IAC3B,OAAO,CAAC,EAAE,mBAAmB,CAAC;CAC/B;AAED,gGAAgG;AAChG,MAAM,WAAW,kBAAkB;IACjC,wCAAwC;IACxC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,4FAA4F;IAC5F,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,aAAa,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,eAAe,EAAE,MAAM,CAAC;IACxB,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,cAAc,EAAE,MAAM,CAAC;IACvB,sFAAsF;IACtF,SAAS,EAAE,MAAM,CAAC;IAClB,uFAAuF;IACvF,aAAa,EAAE,MAAM,CAAC;IACtB,kGAAkG;IAClG,eAAe,EAAE,MAAM,CAAC;CACzB;AAwBD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,uBAAuB,GAC/B,QAAQ,CACT,kBAAkB,EAClB;IAAE,OAAO,EAAE,oBAAoB,CAAC;IAAC,cAAc,EAAE,kBAAkB,CAAA;CAAE,CACtE,CA0GA"}