@insiderfinance/totalfinance 0.1.0

package/modules/options/dist/american-iv.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Engine-inverted implied volatility (spec §9.5, WS4.2).
+ *
+ * Closed-form Black–Scholes–Merton inverts only a European contract. Everything else — an American
+ * contract, or a European contract the caller wants solved under a specific engine (a lattice with
+ * discrete dividends, a custom model) — inverts the ENGINE's price over volatility with a
+ * safeguarded Brent bracket. One kernel does that inversion ({@link invertEngine}); two doors dress
+ * it: {@link americanImpliedVolatility} (the American door, default engine Bjerksund–Stensland
+ * 2002) and `option.impliedVolatility({ contract, market, engine })` (any style with a supplied
+ * engine). The kernel never fabricates a vol: a price outside the style's no-arbitrage band, at the
+ * band's floor (no time value), or unreachable within the bracket fails honestly (design law #4).
+ *
+ * The bounds are model-free, by exercise style: an American call sits in `[max(S−K,0), S]` and an
+ * American put in `[max(K−S,0), K]` (no discounting — exercise is available now); a European
+ * contract sits in the discounted band `blackScholesPriceBounds` states, on the escrowed spot when
+ * the market carries discrete dividends.
+ */
+import { type EpochMs, type OptionContract } from '../../core/dist/index.js';
+import { type OptionPricingEngine } from './engines.js';
+import type { ImpliedVolatilitySolveResult } from './iv.js';
+import type { OptionMarket } from './types.js';
+/** A σ bracket the inversion solves on exactly, with no widening. */
+export interface EngineInversionBracket {
+    lowerVolatilityBound: number;
+    upperVolatilityBound: number;
+}
+/** A request to {@link invertEngine}; the caller has validated the market, contract and engine. */
+export interface EngineInversionRequest {
+    functionName: string;
+    contract: OptionContract;
+    market: OptionMarket;
+    engine: OptionPricingEngine;
+    /**
+     * Explicit Brent bracket in σ. When absent, the safeguarded default `[1e-4, 5]`, widened once to
+     * `[1e-6, 10]` when the root is not inside it.
+     */
+    bracket?: EngineInversionBracket;
+}
+export type EngineInversionStatus = 'solved' | 'below-lower-bound' | 'above-upper-bound' | 'no-time-value' | 'no-convergence';
+/** The raw outcome of one engine inversion — what the two doors and the chain-health report dress. */
+export interface EngineInversion {
+    status: EngineInversionStatus;
+    /** The target price the inversion was asked to reproduce (per share). */
+    price: number;
+    /** The accepted σ, or null for every other status (never a NaN "value"). */
+    value: number | null;
+    /** Absolute repricing residual per share of an accepted solve; null otherwise. */
+    residual: number | null;
+    /** The model-free no-arbitrage band for this style; a price outside it has no volatility. */
+    bounds: {
+        lower: number;
+        upper: number;
+    };
+    iterations: number;
+    /** The σ interval actually searched last. */
+    bracket: [number, number];
+    /** True when the default bracket had to be widened (never for an explicit bracket). */
+    expanded: boolean;
+    /**
+     * On `no-convergence`: the engine's price at the bracket floor and ceiling, and on which side
+     * the target fell outside them — the usual cause is a target under the σ→0 floor, not a fussy
+     * solver.
+     */
+    floor: number | null;
+    belowFloor: boolean;
+    ceiling: number | null;
+    aboveCeiling: boolean;
+    timeToExpiryYears: number;
+    dividendYield: number;
+    escrowed: boolean;
+    asOf: EpochMs;
+}
+/**
+ * Invert `engine.price` over σ for `market.price`. This is the one inversion kernel: it decides the
+ * style's bounds, refuses prices with no volatility, and searches the bracket; the doors turn the
+ * outcome into their own result grammar. The engine must already support the contract.
+ */
+export declare function invertEngine(request: EngineInversionRequest): EngineInversion;
+/** Input for {@link engineImpliedVolatility}: a validated-shape request from a routing door. */
+export interface EngineImpliedVolatilityInput {
+    functionName: string;
+    contract: OptionContract;
+    market: OptionMarket;
+    engine: OptionPricingEngine;
+}
+/**
+ * Invert a supplied engine for any exercise style and answer in the shared implied-volatility
+ * grammar. Internal to the package: `option.impliedVolatility` routes here when the caller names
+ * an engine, and {@link americanImpliedVolatility} is the public American door.
+ */
+export declare function engineImpliedVolatility(input: EngineImpliedVolatilityInput): ImpliedVolatilitySolveResult;
+/** Options for {@link americanImpliedVolatility}. Mirrors the subset of `ImpliedVolatilityOptions` it honours. */
+export interface AmericanImpliedVolatilityOptions {
+    /**
+     * Engine to invert. Default `engines.bjerksundStensland2002()`. Pass e.g. a binomial engine to
+     * handle discrete dividends — the inversion is generic and the reported engine follows the override.
+     */
+    engine?: OptionPricingEngine;
+}
+/** One cohesive request for American implied-volatility inversion. */
+export interface AmericanImpliedVolatilityInput {
+    contract: OptionContract;
+    market: OptionMarket;
+    options?: AmericanImpliedVolatilityOptions;
+}
+/**
+ * Solve the implied volatility of an American contract from `market.price` by inverting an American
+ * pricing engine over σ with a safeguarded Brent bracket (`[1e-4, 5]`, expanded once to `[1e-6, 10]`).
+ * No-arbitrage bounds use the American intrinsic (`max(S−K,0)` calls, `max(K−S,0)` puts, no
+ * discounting): a price below intrinsic, above the upper bound, or at intrinsic (no time value to
+ * imply a vol) fails honestly instead of returning a fabricated number. A European contract is
+ * refused — its door is `option.impliedVolatility`, closed-form by default or engine-inverted when
+ * an engine is named.
+ */
+export declare function americanImpliedVolatility(input: AmericanImpliedVolatilityInput): ImpliedVolatilitySolveResult;
+//# sourceMappingURL=american-iv.d.ts.map

package/modules/options/dist/american-iv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"american-iv.d.ts","sourceRoot":"","sources":["../src/american-iv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAML,KAAK,OAAO,EAGZ,KAAK,cAAc,EASpB,MAAM,0BAAoB,CAAC;AAI5B,OAAO,EAA0B,KAAK,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAEhF,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,SAAS,CAAC;AAG5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAwH/C,qEAAqE;AACrE,MAAM,WAAW,sBAAsB;IACrC,oBAAoB,EAAE,MAAM,CAAC;IAC7B,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED,mGAAmG;AACnG,MAAM,WAAW,sBAAsB;IACrC,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,cAAc,CAAC;IACzB,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,mBAAmB,CAAC;IAC5B;;;OAGG;IACH,OAAO,CAAC,EAAE,sBAAsB,CAAC;CAClC;AAED,MAAM,MAAM,qBAAqB,GAC7B,QAAQ,GACR,mBAAmB,GACnB,mBAAmB,GACnB,eAAe,GACf,gBAAgB,CAAC;AAErB,sGAAsG;AACtG,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,qBAAqB,CAAC;IAC9B,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,kFAAkF;IAClF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,6FAA6F;IAC7F,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1B,uFAAuF;IACvF,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,YAAY,EAAE,OAAO,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,OAAO,CAAC;IAClB,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,sBAAsB,GAAG,eAAe,CAiI7E;AAuFD,gGAAgG;AAChG,MAAM,WAAW,4BAA4B;IAC3C,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,cAAc,CAAC;IACzB,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,mBAAmB,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,4BAA4B,GAClC,4BAA4B,CAqB9B;AAED,kHAAkH;AAClH,MAAM,WAAW,gCAAgC;IAC/C;;;OAGG;IACH,MAAM,CAAC,EAAE,mBAAmB,CAAC;CAC9B;AAED,sEAAsE;AACtE,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,EAAE,cAAc,CAAC;IACzB,MAAM,EAAE,YAAY,CAAC;IACrB,OAAO,CAAC,EAAE,gCAAgC,CAAC;CAC5C;AAMD;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,8BAA8B,GACpC,4BAA4B,CAkC9B"}

package/modules/options/dist/american-iv.js

@@ -0,0 +1,385 @@
+/**
+ * Engine-inverted implied volatility (spec §9.5, WS4.2).
+ *
+ * Closed-form Black–Scholes–Merton inverts only a European contract. Everything else — an American
+ * contract, or a European contract the caller wants solved under a specific engine (a lattice with
+ * discrete dividends, a custom model) — inverts the ENGINE's price over volatility with a
+ * safeguarded Brent bracket. One kernel does that inversion ({@link invertEngine}); two doors dress
+ * it: {@link americanImpliedVolatility} (the American door, default engine Bjerksund–Stensland
+ * 2002) and `option.impliedVolatility({ contract, market, engine })` (any style with a supplied
+ * engine). The kernel never fabricates a vol: a price outside the style's no-arbitrage band, at the
+ * band's floor (no time value), or unreachable within the bracket fails honestly (design law #4).
+ *
+ * The bounds are model-free, by exercise style: an American call sits in `[max(S−K,0), S]` and an
+ * American put in `[max(K−S,0), K]` (no discounting — exercise is available now); a European
+ * contract sits in the discounted band `blackScholesPriceBounds` states, on the escrowed spot when
+ * the market carries discrete dividends.
+ */
+import { ensureFiniteWhenPresent, CONVENTIONS_VERSION, DEFAULT_GREEK_UNITS, ErrorCode, InputError, UnsupportedError, ensureFinite, ensureKnownKeys, ensurePositive, requireArgumentObject, resolveValuationAsOf, WarningCode, } from '../../core/dist/index.js';
+import { brent } from '../../math/dist/index.js';
+import { blackScholesPriceBounds } from './bsm.js';
+import { escrowedSpot, hasDiscreteDividends } from './dividends.js';
+import { engines, requireEngine } from './engines.js';
+import { requireOptionalArgObject } from './facade-util.js';
+import { vanillaIntrinsicUnchecked } from './payoff-kernel.js';
+import { contractTimeToExpiryYears } from './time.js';
+function inversionAssumptions(input) {
+    const { engine, timeToExpiryYears: t, dividendYield: q, asOf, escrowed } = input;
+    const dividendModel = escrowed
+        ? 'discreteSchedule'
+        : q === 0
+            ? 'none'
+            : 'continuousYield';
+    return {
+        conventionsVersion: CONVENTIONS_VERSION,
+        dayCount: 'ACT/365F',
+        compounding: 'continuous',
+        asOf,
+        timeToExpiryYears: t,
+        dividendModel,
+        units: DEFAULT_GREEK_UNITS,
+        model: engine,
+        engine,
+    };
+}
+function fail(input) {
+    const { engine, code, message } = input;
+    return {
+        value: null,
+        assumptions: inversionAssumptions(input),
+        diagnostics: {
+            engine,
+            method: 'none',
+            converged: false,
+            iterations: 0,
+            fallback: false,
+            warnings: [{ code, message, severity: 'error' }],
+        },
+    };
+}
+/**
+ * Validate the market and contract an inversion needs (price, spot, rate, strike, yield, asOf,
+ * a positive time to expiry) with the same messages on every door.
+ */
+function requireInversionInputs(functionName, contract, market) {
+    if (typeof market.price !== 'number') {
+        throw new InputError(`${functionName}: market.price is required to solve implied volatility.`, {
+            code: ErrorCode.InputMissingField,
+            context: { field: 'price', function: functionName },
+        });
+    }
+    // A zero premium is a legitimate observation for the kernel to classify (it sits at or below the
+    // style's floor); the doors refuse it before calling, so a caller asking for a vol at 0 is taught.
+    ensureFinite(market.price, 'price', functionName);
+    if (market.price < 0)
+        ensurePositive(market.price, 'price', functionName);
+    if (typeof market.spot !== 'number') {
+        throw new InputError(`${functionName}: market.spot is required.`, {
+            code: ErrorCode.InputMissingField,
+            context: { field: 'spot', function: functionName },
+        });
+    }
+    ensurePositive(market.spot, 'spot', functionName, ErrorCode.InputNegativeSpot);
+    if (typeof market.riskFreeRate !== 'number') {
+        throw new InputError(`${functionName}: market.riskFreeRate (a number) is required.`, {
+            code: ErrorCode.InputMissingField,
+            context: { field: 'riskFreeRate', function: functionName },
+        });
+    }
+    ensureFinite(market.riskFreeRate, 'riskFreeRate', functionName);
+    ensurePositive(contract.strike, 'strike', functionName, ErrorCode.InputNegativeStrike);
+    // Null is a wrong-typed value, not omission (the 350c2796 ruling): it used to coalesce
+    // to 0 BEFORE the finite check and silently price a dividend-free underlying.
+    ensureFiniteWhenPresent(market.dividendYield, 'dividendYield', functionName);
+    const dividendYield = market.dividendYield ?? 0;
+    const asOf = resolveValuationAsOf(market.asOf, functionName);
+    ensureFinite(asOf, 'asOf', functionName);
+    const timeToExpiryYears = contractTimeToExpiryYears(asOf, contract, functionName);
+    if (timeToExpiryYears <= 0) {
+        throw new UnsupportedError(`${functionName}: contract expiry ${contract.expiry} is not after asOf.`, {
+            code: ErrorCode.InputNegativeTime,
+            context: { asOf: market.asOf, expiry: contract.expiry, timeToExpiryYears },
+        });
+    }
+    return {
+        price: market.price,
+        spot: market.spot,
+        riskFreeRate: market.riskFreeRate,
+        dividendYield,
+        asOf,
+        timeToExpiryYears,
+        escrowed: hasDiscreteDividends(market),
+    };
+}
+/**
+ * Invert `engine.price` over σ for `market.price`. This is the one inversion kernel: it decides the
+ * style's bounds, refuses prices with no volatility, and searches the bracket; the doors turn the
+ * outcome into their own result grammar. The engine must already support the contract.
+ */
+export function invertEngine(request) {
+    const { functionName, contract, market, engine, bracket } = request;
+    const inputs = requireInversionInputs(functionName, contract, market);
+    const { price, spot: S, riskFreeRate, dividendYield: q, asOf, timeToExpiryYears: t } = inputs;
+    const K = contract.strike;
+    const bounds = contract.style === 'american'
+        ? // American intrinsic (no discounting) and the no-arbitrage upper bound: an American call
+            // ≤ spot, an American put ≤ strike — exercise is available now, so nothing is discounted.
+            {
+                lower: vanillaIntrinsicUnchecked({ type: contract.type, underlyingPrice: S, strike: K }),
+                upper: contract.type === 'call' ? S : K,
+            }
+        : // The discounted European band, on the escrowed spot when cash dividends are scheduled —
+            // the same effective spot every engine prices the contract off.
+            blackScholesPriceBounds({
+                type: contract.type,
+                spot: escrowedSpot({
+                    spot: S,
+                    market,
+                    asOf,
+                    timeToExpiryYears: t,
+                    riskFreeRate,
+                    functionName,
+                }),
+                strike: K,
+                timeToExpiryYears: t,
+                riskFreeRate,
+                dividendYield: q,
+            });
+    const tolerance = 1e-8 * Math.max(1, S);
+    const base = {
+        price,
+        value: null,
+        residual: null,
+        bounds,
+        iterations: 0,
+        bracket: [bracket?.lowerVolatilityBound ?? 1e-4, bracket?.upperVolatilityBound ?? 5],
+        expanded: false,
+        floor: null,
+        belowFloor: false,
+        ceiling: null,
+        aboveCeiling: false,
+        timeToExpiryYears: t,
+        dividendYield: q,
+        escrowed: inputs.escrowed,
+        asOf,
+    };
+    if (price < bounds.lower - tolerance)
+        return { ...base, status: 'below-lower-bound' };
+    if (price > bounds.upper + tolerance)
+        return { ...base, status: 'above-upper-bound' };
+    // At (or numerically at) the floor the option carries no time value, so the vol is indeterminate.
+    // Reject rather than let Brent lock onto a bracket endpoint and report a fabricated σ.
+    if (price <= bounds.lower + tolerance)
+        return { ...base, status: 'no-time-value' };
+    const priceAt = (sigma) => engine.price({ contract, market: { ...market, volatility: sigma } }).value;
+    const residual = (sigma) => priceAt(sigma) - price;
+    const tolOpts = {
+        stepTolerance: 1e-8,
+        residualTolerance: 1e-10 * Math.max(1, price),
+        maximumIterations: 100,
+    };
+    // Solve on a bracket, first sanitizing any non-finite endpoint: some engines (e.g. a Leisen–Reimer
+    // lattice) return NaN at extreme σ, which would poison Brent's endpoint check even when a valid root
+    // sits inside the bracket. Walk a non-finite low endpoint up / high endpoint down until both are
+    // finite. The closed-form default (Bjerksund–Stensland) is finite at 1e-4, so its bracket is
+    // unchanged.
+    const solveBracket = (lo, hi) => {
+        let a = lo;
+        for (let i = 0; i < 30 && a < hi && !Number.isFinite(residual(a)); i++)
+            a *= 2;
+        let b = hi;
+        for (let i = 0; i < 30 && b > a && !Number.isFinite(residual(b)); i++)
+            b *= 0.8;
+        if (!(a < b) || !Number.isFinite(residual(a)) || !Number.isFinite(residual(b))) {
+            return { value: NaN, converged: false, iterations: 0, method: 'brent' };
+        }
+        return brent(residual, a, b, tolOpts);
+    };
+    let searched = base.bracket;
+    let res = solveBracket(searched[0], searched[1]);
+    let iterations = res.iterations;
+    let expanded = false;
+    if (!res.converged && bracket === undefined) {
+        // Widen the default bracket once: deep-OTM (tiny σ) and extreme-priced (huge σ) contracts live
+        // outside the default window. An explicit bracket is the caller's resolvability window and is
+        // never widened.
+        searched = [1e-6, 10];
+        const wide = solveBracket(searched[0], searched[1]);
+        iterations += wide.iterations;
+        res = wide;
+        expanded = true;
+    }
+    const accepted = res.converged &&
+        Number.isFinite(res.value) &&
+        res.value > 0 &&
+        Math.abs(priceAt(res.value) - price) <= 1e-6 * Math.max(1, price);
+    if (accepted) {
+        return {
+            ...base,
+            status: 'solved',
+            value: res.value,
+            residual: Math.abs(priceAt(res.value) - price),
+            iterations,
+            bracket: searched,
+            expanded,
+        };
+    }
+    // WHY it failed matters: the usual cause is not a fussy solver but a target price BELOW the
+    // engine's σ→0 floor (an American call on a non-dividend payer is worth at least S − K·e^{−rT},
+    // so a quote under that has no volatility at all). That is not "below the bound" — the American
+    // intrinsic is S − K and the price cleared it — so the floor and ceiling ride the outcome where a
+    // caller can see the gap instead of guessing at the bracket.
+    const floor = priceAt(searched[0]);
+    const ceiling = priceAt(searched[1]);
+    return {
+        ...base,
+        status: 'no-convergence',
+        iterations,
+        bracket: searched,
+        expanded,
+        floor: Number.isFinite(floor) ? floor : null,
+        belowFloor: Number.isFinite(floor) && price < floor,
+        ceiling: Number.isFinite(ceiling) ? ceiling : null,
+        aboveCeiling: Number.isFinite(ceiling) && price > ceiling,
+    };
+}
+/** Turn a raw inversion into the shared implied-volatility result grammar. */
+function dressInversion(inversion, contract, engineName) {
+    const style = contract.style === 'american' ? 'American' : 'European';
+    const band = contract.style === 'american'
+        ? { floor: 'the American intrinsic value', ceiling: 'the American no-arbitrage upper bound' }
+        : {
+            floor: 'the European no-arbitrage lower bound (the discounted intrinsic)',
+            ceiling: 'the European no-arbitrage upper bound',
+        };
+    const assumptions = {
+        engine: engineName,
+        timeToExpiryYears: inversion.timeToExpiryYears,
+        dividendYield: inversion.dividendYield,
+        asOf: inversion.asOf,
+        escrowed: inversion.escrowed,
+    };
+    switch (inversion.status) {
+        case 'below-lower-bound':
+            return fail({
+                ...assumptions,
+                code: ErrorCode.ImpliedVolatilityBelowIntrinsic,
+                message: `price is below ${band.floor}`,
+            });
+        case 'above-upper-bound':
+            return fail({
+                ...assumptions,
+                code: ErrorCode.ImpliedVolatilityAboveMax,
+                message: `price exceeds ${band.ceiling}`,
+            });
+        case 'no-time-value':
+            return fail({
+                ...assumptions,
+                code: ErrorCode.ImpliedVolatilityBelowIntrinsic,
+                message: `price is at ${band.floor} (no time value); implied volatility is indeterminate`,
+            });
+        case 'solved':
+        case 'no-convergence': {
+            const warnings = [];
+            const converged = inversion.status === 'solved';
+            if (inversion.expanded && converged) {
+                warnings.push({
+                    code: WarningCode.ImpliedVolatilityBracketExpanded,
+                    message: 'the [1e-4, 5] bracket did not contain the root; solved on the expanded [1e-6, 10] bracket',
+                    severity: 'info',
+                });
+            }
+            if (!converged) {
+                const { price, floor, belowFloor, ceiling, aboveCeiling, bracket } = inversion;
+                const message = belowFloor && floor !== null
+                    ? `price ${price} is below this engine's σ→0 price floor ${floor}; no volatility reproduces it`
+                    : aboveCeiling && ceiling !== null
+                        ? `price ${price} is above this engine's price ceiling ${ceiling} at σ = ${bracket[1]}; no volatility in the bracket reproduces it`
+                        : `Brent did not converge on an ${style} implied volatility within the safeguarded bracket`;
+                warnings.push({
+                    code: ErrorCode.ImpliedVolatilityNoConvergence,
+                    message,
+                    severity: 'error',
+                    context: { price, floor, belowFloor, ceiling, aboveCeiling, bracket },
+                });
+            }
+            return {
+                // Law 7 / E3: a failed solve is `null` (the reason rides diagnostics), never a NaN "value" —
+                // the declared type and the doc have always promised null.
+                value: converged ? inversion.value : null,
+                assumptions: inversionAssumptions(assumptions),
+                diagnostics: {
+                    engine: engineName,
+                    method: 'brent',
+                    converged,
+                    iterations: inversion.iterations,
+                    fallback: inversion.expanded,
+                    warnings,
+                },
+            };
+        }
+    }
+}
+/**
+ * Invert a supplied engine for any exercise style and answer in the shared implied-volatility
+ * grammar. Internal to the package: `option.impliedVolatility` routes here when the caller names
+ * an engine, and {@link americanImpliedVolatility} is the public American door.
+ */
+export function engineImpliedVolatility(input) {
+    const { functionName, contract, market, engine } = input;
+    requireEngine(functionName, engine);
+    if (typeof market.price === 'number')
+        ensurePositive(market.price, 'price', functionName);
+    // The framework enforces `supports()` on every inversion exactly as `option.price` does, so a
+    // European-only engine handed an American contract fails the same way in both directions.
+    if (!engine.supports(contract)) {
+        throw new UnsupportedError(`engineImpliedVolatility: Engine "${engine.name}" does not support this contract ` +
+            `(style "${contract.style}", type "${contract.type}").`, {
+            code: ErrorCode.EngineUnsupportedContract,
+            context: { engine: engine.name, style: contract.style, type: contract.type },
+        });
+    }
+    return dressInversion(invertEngine({ functionName, contract, market, engine }), contract, engine.name);
+}
+/** Law 12 allowlist for {@link AmericanImpliedVolatilityOptions}. */
+const AMERICAN_IV_KEYS = ['engine'];
+const AMERICAN_IV_REQUEST_KEYS = ['contract', 'market', 'options'];
+/**
+ * Solve the implied volatility of an American contract from `market.price` by inverting an American
+ * pricing engine over σ with a safeguarded Brent bracket (`[1e-4, 5]`, expanded once to `[1e-6, 10]`).
+ * No-arbitrage bounds use the American intrinsic (`max(S−K,0)` calls, `max(K−S,0)` puts, no
+ * discounting): a price below intrinsic, above the upper bound, or at intrinsic (no time value to
+ * imply a vol) fails honestly instead of returning a fabricated number. A European contract is
+ * refused — its door is `option.impliedVolatility`, closed-form by default or engine-inverted when
+ * an engine is named.
+ */
+export function americanImpliedVolatility(input) {
+    requireArgumentObject('americanImpliedVolatility', 'input', input);
+    ensureKnownKeys('americanImpliedVolatility', 'input', input, AMERICAN_IV_REQUEST_KEYS);
+    const { contract, market, options: options = {} } = input;
+    requireArgumentObject('americanImpliedVolatility', 'contract', contract);
+    requireArgumentObject('americanImpliedVolatility', 'market', market);
+    const functionName = 'option.impliedVolatility';
+    // `null` (or a primitive) slips past `options = {}` — teach, never TypeError on `options.engine`.
+    requireOptionalArgObject(functionName, 'options', options);
+    if (options['engine'] === null) {
+        throw new InputError(`americanImpliedVolatility: engine must not be null — omit the field to use the default engine. Received null.`, { code: ErrorCode.InputWrongType, context: { field: 'engine' } });
+    }
+    // Contract/market artifacts may carry provenance metadata; the closed options object remains strict.
+    ensureKnownKeys(functionName, 'options', options, AMERICAN_IV_KEYS);
+    if (contract.style !== 'american') {
+        throw new UnsupportedError(`americanImpliedVolatility: inverts American exercise only; this contract is "${contract.style}". ` +
+            'Use option.impliedVolatility({ contract, market }) for the closed-form European inverse, or ' +
+            'option.impliedVolatility({ contract, market, engine }) to invert a specific engine.', {
+            code: ErrorCode.EngineUnsupportedContract,
+            context: { function: 'americanImpliedVolatility', style: contract.style },
+        });
+    }
+    return engineImpliedVolatility({
+        functionName,
+        contract,
+        market,
+        engine: options.engine ?? engines.bjerksundStensland2002(),
+    });
+}
+//# sourceMappingURL=american-iv.js.map

package/modules/options/dist/american-iv.js.map

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

package/modules/options/dist/arbitrage.d.ts

@@ -0,0 +1,42 @@
+/** No-arbitrage bound checks for option prices (spec §9.5/§9.6). */
+import { type Assumptions, type OptionType, type QuantWarning } from '../../core/dist/index.js';
+/** Input for {@link checkBlackScholesNoArbitrage} — the observed price plus the BSM inputs it's bounded against. */
+export interface BlackScholesNoArbitrageInput {
+    type: OptionType;
+    /** The observed option price to test. */
+    price: number;
+    spot: number;
+    strike: number;
+    /** Time to expiry in years. */
+    timeToExpiryYears: number;
+    riskFreeRate: number;
+    /** Continuous dividend yield (decimal, default 0). */
+    dividendYield?: number;
+}
+/**
+ * The no-arbitrage verdict (Law 2 report grammar): the admissibility flag plus the exact band the
+ * price was tested against, with the applied conventions on `assumptions` and any violations as
+ * structured warnings on `diagnostics.warnings` (empty when the price is admissible).
+ */
+export interface BlackScholesNoArbitrageReport {
+    /** True when the observed price sits inside the BSM no-arbitrage band (within tolerance). */
+    admissible: boolean;
+    /** The no-arbitrage lower bound (discounted intrinsic). */
+    lower: number;
+    /** The no-arbitrage upper bound (call: discounted spot; put: discounted strike). */
+    upper: number;
+    /** Applied conventions, echoed (Law 2 report grammar). */
+    assumptions: Assumptions;
+    /** The violations as structured warnings (empty when admissible). */
+    diagnostics: {
+        warnings: QuantWarning[];
+    };
+}
+/**
+ * Check an observed price against BSM no-arbitrage bounds. Returns a report: `admissible` plus the
+ * `[lower, upper]` band, with each violation as a structured `severity: 'error'` warning on
+ * `diagnostics.warnings` (empty when the price is admissible). Callers decide whether to treat a
+ * violation as fatal.
+ */
+export declare function checkBlackScholesNoArbitrage(input: BlackScholesNoArbitrageInput): BlackScholesNoArbitrageReport;
+//# sourceMappingURL=arbitrage.d.ts.map

package/modules/options/dist/arbitrage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arbitrage.d.ts","sourceRoot":"","sources":["../src/arbitrage.ts"],"names":[],"mappings":"AAAA,oEAAoE;AAEpE,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,YAAY,EAOlB,MAAM,0BAAoB,CAAC;AAM5B,oHAAoH;AACpH,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,UAAU,CAAC;IACjB,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAaD;;;;GAIG;AACH,MAAM,WAAW,6BAA6B;IAC5C,6FAA6F;IAC7F,UAAU,EAAE,OAAO,CAAC;IACpB,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAC;IACd,oFAAoF;IACpF,KAAK,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,WAAW,EAAE,WAAW,CAAC;IACzB,qEAAqE;IACrE,WAAW,EAAE;QAAE,QAAQ,EAAE,YAAY,EAAE,CAAA;KAAE,CAAC;CAC3C;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,4BAA4B,GAClC,6BAA6B,CA8D/B"}

package/modules/options/dist/arbitrage.js

@@ -0,0 +1,79 @@
+/** No-arbitrage bound checks for option prices (spec §9.5/§9.6). */
+import { ensureFiniteWhenPresent, ErrorCode, ensureEnum, ensureFinite, ensureKnownKeys, ensureNonNegative, ensurePositive, requireArgumentObject, } from '../../core/dist/index.js';
+import { analyticAssumptions } from './facade-util.js';
+import { blackScholesPriceBounds } from './bsm.js';
+const TOL = 1e-9;
+/** {@link BlackScholesNoArbitrageInput} keys (Law 12 — mirrors the interface above; keep in sync). */
+const BSM_NO_ARBITRAGE_KEYS = [
+    'type',
+    'price',
+    'spot',
+    'strike',
+    'timeToExpiryYears',
+    'riskFreeRate',
+    'dividendYield',
+];
+/**
+ * Check an observed price against BSM no-arbitrage bounds. Returns a report: `admissible` plus the
+ * `[lower, upper]` band, with each violation as a structured `severity: 'error'` warning on
+ * `diagnostics.warnings` (empty when the price is admissible). Callers decide whether to treat a
+ * violation as fatal.
+ */
+export function checkBlackScholesNoArbitrage(input) {
+    const functionName = 'checkBlackScholesNoArbitrage';
+    requireArgumentObject(functionName, 'input', input);
+    // Law 12: a misspelled field (`divYield`) must teach, never silently loosen the tested band.
+    ensureKnownKeys(functionName, 'input', input, BSM_NO_ARBITRAGE_KEYS);
+    // `type` is meaning-changing: garbage would silently test the other leg's band (design law #4).
+    ensureEnum(input.type, ['call', 'put'], 'type', functionName);
+    // A NaN price makes every band comparison false — it would read as "admissible". Reject it, but
+    // allow an exact 0 (a worthless quote is a legitimate price to test against the band).
+    ensureFinite(input.price, 'price', functionName);
+    ensureNonNegative(input.price, 'price', functionName);
+    ensurePositive(input.spot, 'spot', functionName, ErrorCode.InputNegativeSpot);
+    ensurePositive(input.strike, 'strike', functionName, ErrorCode.InputNegativeStrike);
+    ensurePositive(input.timeToExpiryYears, 'timeToExpiryYears', functionName, ErrorCode.InputNegativeTime);
+    ensureFinite(input.riskFreeRate, 'riskFreeRate', functionName);
+    // Null is a wrong-typed value, not omission (the 350c2796 ruling): it used to coalesce
+    // to 0 BEFORE the finite check and silently price a dividend-free underlying.
+    ensureFiniteWhenPresent(input.dividendYield, 'dividendYield', functionName);
+    const q = input.dividendYield ?? 0;
+    const { type, price, spot, strike, timeToExpiryYears, riskFreeRate } = input;
+    const { lower, upper } = blackScholesPriceBounds({
+        type,
+        spot,
+        strike,
+        timeToExpiryYears,
+        riskFreeRate,
+        dividendYield: q,
+    });
+    const warnings = [];
+    if (price < lower - TOL) {
+        warnings.push({
+            code: ErrorCode.ImpliedVolatilityBelowIntrinsic,
+            message: `price ${price} is below the no-arbitrage lower bound ${lower}`,
+            severity: 'error',
+            context: { price, lower },
+        });
+    }
+    if (price > upper + TOL) {
+        warnings.push({
+            code: ErrorCode.ImpliedVolatilityAboveMax,
+            message: `price ${price} is above the no-arbitrage upper bound ${upper}`,
+            severity: 'error',
+            context: { price, upper },
+        });
+    }
+    return {
+        admissible: warnings.length === 0,
+        lower,
+        upper,
+        assumptions: analyticAssumptions({
+            model: 'black-scholes-merton',
+            timeToExpiryYears,
+            dividendModel: q === 0 ? 'none' : 'continuousYield',
+        }),
+        diagnostics: { warnings },
+    };
+}
+//# sourceMappingURL=arbitrage.js.map