@insiderfinance/totalfinance 0.1.0

package/modules/options/dist/dividend-term-structure.js

@@ -0,0 +1,180 @@
+/**
+ * Dividend term structures (spec: `docs/specs/dividend-term-structure.md`, roadmap Tier 2). Unifies the
+ * two ways a desk carries dividends — a **discrete cash schedule** (real ex-dates and amounts) and a
+ * **continuous yield** `q` (the one number a Black–Scholes engine wants) — into a single per-maturity
+ * term structure of the dividend-adjusted forward `F(T)`, the PV of the dividends accruing before `T`,
+ * and the **continuous-equivalent yield** `q_eff(T)` that reproduces that forward exactly.
+ *
+ * EX-DATE CONVENTION: a date-only `exDate` resolves to the US equity market OPEN (09:30
+ * America/New_York), while a date-only MATURITY resolves to the 16:00 ET option close — two different
+ * events, two different instants (see {@link parseExDateToEpoch}). A zoned datetime is taken as-is.
+ *
+ * Same escrowed-dividend model as {@link escrowedSpot} (the `0 < τᵢ < T` rule), so `q_eff(T)` is a
+ * *lossless* collapse of the schedule at each expiry: pricing with `(S, r, q_eff(T), σ)` returns exactly
+ * the escrowed-spot price, because BSM depends on `(S,r,q)` only through the forward. This is the forward
+ * direction of the relationship `parity.impliedDividendYield` inverts (recovering `q_eff` from prices).
+ */
+import { ensureFiniteWhenPresent, CONVENTIONS_VERSION, ErrorCode, InputError, ensureFinite, ensurePositive, requireArgumentObject, ensureKnownKeys, resolveValuationAsOf, warning, WarningCode, } from '../../core/dist/index.js';
+import { timeToExDateYears, timeToExpiryYears } from './time.js';
+const pct = (x) => `${(x * 100).toFixed(2)}%`;
+const money = (x) => x.toFixed(2);
+/**
+ * Build the dividend term structure — per-expiry forward, dividend PV, and continuous-equivalent yield —
+ * from a discrete cash schedule and/or a continuous yield. See `docs/specs/dividend-term-structure.md`.
+ */
+export function dividendTermStructure(input) {
+    const functionName = 'dividendTermStructure';
+    requireArgumentObject(functionName, 'input', input);
+    // Law 12 (2026-08-23, fourth review): the input is CLOSED — an unknown key is a typo teaching,
+    // never silently ignored.
+    ensureKnownKeys(functionName, 'input', input, [
+        'spot',
+        'riskFreeRate',
+        'dividendYield',
+        'dividends',
+        'asOf',
+        'maturities',
+    ]);
+    ensurePositive(input.spot, 'spot', functionName, ErrorCode.InputNegativeSpot);
+    const S = input.spot;
+    if (typeof input.riskFreeRate !== 'number') {
+        throw new InputError(`${functionName}: rate (a number) is required.`, {
+            code: ErrorCode.InputMissingField,
+            context: { field: 'riskFreeRate' },
+        });
+    }
+    ensureFinite(input.riskFreeRate, 'riskFreeRate', functionName);
+    const r = input.riskFreeRate;
+    // 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.
+    // `?? []` would treat an explicit `dividends: null` as an omission — null is a stated value,
+    // and a caller who wrote it is told so (2026-08-23 fourth-review enforcement).
+    for (const field of ['dividendYield', 'dividends']) {
+        if (input[field] === null) {
+            throw new InputError(`${functionName}: ${field} must not be null — omit the field to take its default.`, { code: ErrorCode.InputWrongType, context: { field } });
+        }
+    }
+    ensureFiniteWhenPresent(input.dividendYield, 'dividendYield', functionName);
+    const q = input.dividendYield ?? 0;
+    const asOfMs = resolveValuationAsOf(input.asOf, functionName);
+    ensureFinite(asOfMs, 'asOf', functionName);
+    if (!Array.isArray(input.maturities) || input.maturities.length === 0) {
+        throw new InputError(`${functionName}: at least one maturity (ISO date) is required.`, {
+            code: ErrorCode.InputMissingField,
+            context: { field: 'maturities' },
+        });
+    }
+    // Resolve the discrete schedule: validate amounts (matching escrowedSpot), split future from past.
+    const future = [];
+    let pastCount = 0;
+    const rawDividends = input.dividends ?? [];
+    if (!Array.isArray(rawDividends)) {
+        throw new InputError(`${functionName}: dividends must be an array of { exDate, amount }.`, {
+            code: ErrorCode.InputWrongType,
+            context: { field: 'dividends' },
+        });
+    }
+    for (const div of rawDividends) {
+        requireArgumentObject(functionName, 'dividend', div);
+        if (!Number.isFinite(div.amount) || div.amount < 0) {
+            throw new InputError(`${functionName}: dividend amount must be a finite, non-negative number, got ${div.amount}.`, { code: ErrorCode.InputOutOfRange, context: { exDate: div.exDate, amount: div.amount } });
+        }
+        // Ex-dates use the MARKET-OPEN convention (09:30 ET for a date-only label), identical to
+        // `escrowedSpot` — the two must agree or `q_eff(T)` would stop reproducing the escrowed price.
+        const tau = timeToExDateYears(asOfMs, div.exDate, functionName);
+        if (tau > 0)
+            future.push({ tau, amount: div.amount, pv: div.amount * Math.exp(-r * tau) });
+        else
+            pastCount++;
+    }
+    const totalDividendPresentValue = future.reduce((s, d) => s + d.pv, 0);
+    // Per-maturity term-structure rows.
+    const points = [];
+    for (const maturity of input.maturities) {
+        const T = timeToExpiryYears(asOfMs, maturity, functionName);
+        if (!(T > 0)) {
+            throw new InputError(`${functionName}: maturity ${maturity} is not after asOf (year fraction ${T}).`, {
+                code: ErrorCode.InputNegativeTime,
+                context: { asOf: input.asOf, maturity, T },
+            });
+        }
+        let dividendPresentValue = 0;
+        let discreteCount = 0;
+        for (const d of future) {
+            if (d.tau < T) {
+                dividendPresentValue += d.pv;
+                discreteCount++;
+            }
+        }
+        // Escrowed spot must stay positive — same contract as escrowedSpot (never emit a NaN forward/yield).
+        if (!(dividendPresentValue < S)) {
+            throw new InputError(`${functionName}: present value of dividends before ${maturity} (${dividendPresentValue}) is not less than the spot (${S}); the escrowed spot would be non-positive.`, { code: ErrorCode.InputOutOfRange, context: { maturity, dividendPresentValue, spot: S } });
+        }
+        const forward = (S - dividendPresentValue) * Math.exp((r - q) * T);
+        const discreteEquivalentYield = -Math.log(1 - dividendPresentValue / S) / T;
+        const impliedContinuousYield = q + discreteEquivalentYield;
+        const carry = r - impliedContinuousYield;
+        points.push({
+            maturity,
+            yearsToExpiry: T,
+            dividendPresentValue,
+            discreteCount,
+            forward,
+            discreteEquivalentYield,
+            impliedContinuousYield,
+            carry,
+        });
+    }
+    points.sort((a, b) => a.yearsToExpiry - b.yearsToExpiry);
+    const warnings = [];
+    if (pastCount > 0) {
+        warnings.push(warning(WarningCode.OptionsDividendsPast, `${functionName}: ${pastCount} dividend${pastCount === 1 ? '' : 's'} with an ex-date on or before asOf ${pastCount === 1 ? 'was' : 'were'} dropped (already paid, so not in any forward).`, 'info', { pastCount }));
+    }
+    if (future.length === 0) {
+        warnings.push(warning(WarningCode.OptionsDividendsNone, q === 0
+            ? `${functionName}: no dividends supplied — the forwards are the pure cost-of-carry S·e^{rT} (implied yield 0).`
+            : `${functionName}: no discrete dividends supplied — the forwards reflect the continuous yield ${pct(q)} only.`, 'info'));
+    }
+    const dividendModel = future.length > 0 ? 'discreteSchedule' : q === 0 ? 'none' : 'continuousYield';
+    return {
+        points,
+        totalDividendPresentValue,
+        continuousYield: q,
+        summary: composeSummary({
+            points,
+            S,
+            totalDividendPresentValue,
+            futureCount: future.length,
+            q,
+        }),
+        assumptions: {
+            conventionsVersion: CONVENTIONS_VERSION,
+            spot: S,
+            riskFreeRate: r,
+            continuousYield: q,
+            dividendModel,
+        },
+        diagnostics: {
+            engine: 'dividend-term-structure',
+            method: 'escrowed-dividend forward + continuous-equivalent yield',
+            converged: true,
+            warnings,
+        },
+    };
+}
+/** Compose the one-line term-structure summary. */
+function composeSummary(p) {
+    const first = p.points[0];
+    const last = p.points[p.points.length - 1];
+    const n = p.points.length;
+    const expiries = `${n} expir${n === 1 ? 'y' : 'ies'}`;
+    if (p.futureCount === 0) {
+        const carry = p.q === 0 ? 'pure cost-of-carry' : `continuous yield ${pct(p.q)}`;
+        return `No discrete dividends — ${expiries} priced off ${carry}; the implied dividend yield is a flat ${pct(p.q)}.`;
+    }
+    const yieldSpan = n === 1
+        ? `an implied dividend yield of ${pct(first.impliedContinuousYield)}`
+        : `an implied dividend yield of ${pct(first.impliedContinuousYield)} at ${first.yearsToExpiry.toFixed(2)}y and ${pct(last.impliedContinuousYield)} at ${last.yearsToExpiry.toFixed(2)}y`;
+    return `${p.futureCount} upcoming dividend${p.futureCount === 1 ? '' : 's'} worth ${money(p.totalDividendPresentValue)} PV on a ${money(p.S)} spot — across ${expiries}, ${yieldSpan}.`;
+}
+//# sourceMappingURL=dividend-term-structure.js.map

package/modules/options/dist/dividend-term-structure.js.map

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

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

@@ -0,0 +1,34 @@
+/**
+ * Discrete-dividend handling shared by every engine (BSM/pro and the American engines), so the
+ * `market.dividends` field is never silently ignored on one path while honored on another.
+ *
+ * EX-DATE CONVENTION: a date-only `exDate` resolves to the US equity market OPEN (09:30
+ * America/New_York) — the instant the share stops carrying the dividend — NOT the 16:00 ET
+ * option-expiry convention. See {@link parseExDateToEpoch}. A zoned datetime `exDate` is the
+ * caller's explicit instant.
+ */
+import { type EpochMs } from '../../core/dist/index.js';
+import type { OptionMarket } from './types.js';
+/** Named state needed to apply the escrowed-dividend approximation. */
+export interface EscrowedSpotInput {
+    spot: number;
+    market: OptionMarket;
+    asOf: EpochMs;
+    timeToExpiryYears: number;
+    riskFreeRate: number;
+    functionName: string;
+}
+/** Whether the market carries a discrete cash-dividend schedule. */
+export declare function hasDiscreteDividends(market: OptionMarket): boolean;
+/**
+ * Escrowed-dividend spot: the spot reduced by the present value of cash dividends with an ex-date
+ * strictly before expiry. This is the documented approximation used uniformly across engines for
+ * discrete dividends; continuous `dividendYield` is applied separately by each model.
+ *
+ * Each dividend amount must be finite and non-negative, and the resulting escrowed spot must stay
+ * positive — otherwise this throws a typed {@link InputError}. A pricer must never return a `NaN`
+ * value with `converged: true` (design law #4), so a malformed or spot-exceeding dividend schedule
+ * is rejected here rather than silently producing `NaN` downstream.
+ */
+export declare function escrowedSpot(input: EscrowedSpotInput): number;
+//# sourceMappingURL=dividends.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dividends.d.ts","sourceRoot":"","sources":["../src/dividends.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,KAAK,OAAO,EAAyB,MAAM,0BAAoB,CAAC;AAEzE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,uEAAuE;AACvE,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,YAAY,CAAC;IACrB,IAAI,EAAE,OAAO,CAAC;IACd,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,oEAAoE;AACpE,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAElE;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAmC7D"}

package/modules/options/dist/dividends.js

@@ -0,0 +1,51 @@
+/**
+ * Discrete-dividend handling shared by every engine (BSM/pro and the American engines), so the
+ * `market.dividends` field is never silently ignored on one path while honored on another.
+ *
+ * EX-DATE CONVENTION: a date-only `exDate` resolves to the US equity market OPEN (09:30
+ * America/New_York) — the instant the share stops carrying the dividend — NOT the 16:00 ET
+ * option-expiry convention. See {@link parseExDateToEpoch}. A zoned datetime `exDate` is the
+ * caller's explicit instant.
+ */
+import { ErrorCode, InputError } from '../../core/dist/index.js';
+import { timeToExDateYears } from './time.js';
+/** Whether the market carries a discrete cash-dividend schedule. */
+export function hasDiscreteDividends(market) {
+    return !!(market.dividends && market.dividends.length > 0);
+}
+/**
+ * Escrowed-dividend spot: the spot reduced by the present value of cash dividends with an ex-date
+ * strictly before expiry. This is the documented approximation used uniformly across engines for
+ * discrete dividends; continuous `dividendYield` is applied separately by each model.
+ *
+ * Each dividend amount must be finite and non-negative, and the resulting escrowed spot must stay
+ * positive — otherwise this throws a typed {@link InputError}. A pricer must never return a `NaN`
+ * value with `converged: true` (design law #4), so a malformed or spot-exceeding dividend schedule
+ * is rejected here rather than silently producing `NaN` downstream.
+ */
+export function escrowedSpot(input) {
+    const { spot, market, asOf, timeToExpiryYears: horizonYears, riskFreeRate, functionName: fn, } = input;
+    if (!hasDiscreteDividends(market))
+        return spot;
+    let pv = 0;
+    for (const div of market.dividends) {
+        if (!Number.isFinite(div.amount) || div.amount < 0) {
+            throw new InputError(`${fn}: dividend amount must be a finite, non-negative number, got ${div.amount}.`, { code: ErrorCode.InputOutOfRange, context: { exDate: div.exDate, amount: div.amount } });
+        }
+        // Ex-dates resolve at the market OPEN (09:30 ET): once the ex-date session has started the
+        // dividend is already out of the spot, so `t <= 0` correctly drops it instead of escrowing it
+        // a second time out of an intraday spot.
+        const t = timeToExDateYears(asOf, div.exDate, fn);
+        if (t > 0 && t < horizonYears)
+            pv += div.amount * Math.exp(-riskFreeRate * t);
+    }
+    const escrowed = spot - pv;
+    if (!(escrowed > 0)) {
+        throw new InputError(`${fn}: present value of discrete dividends (${pv}) is not less than the spot (${spot}); the escrowed spot would be non-positive.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { spot, dividendPresentValue: pv, escrowedSpot: escrowed },
+        });
+    }
+    return escrowed;
+}
+//# sourceMappingURL=dividends.js.map

package/modules/options/dist/dividends.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dividends.js","sourceRoot":"","sources":["../src/dividends.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAgB,SAAS,EAAE,UAAU,EAAE,MAAM,0BAAoB,CAAC;AACzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAa9C,oEAAoE;AACpE,MAAM,UAAU,oBAAoB,CAAC,MAAoB;IACvD,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAAC,KAAwB;IACnD,MAAM,EACJ,IAAI,EACJ,MAAM,EACN,IAAI,EACJ,iBAAiB,EAAE,YAAY,EAC/B,YAAY,EACZ,YAAY,EAAE,EAAE,GACjB,GAAG,KAAK,CAAC;IACV,IAAI,CAAC,oBAAoB,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IAC/C,IAAI,EAAE,GAAG,CAAC,CAAC;IACX,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,SAAU,EAAE,CAAC;QACpC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACnD,MAAM,IAAI,UAAU,CAClB,GAAG,EAAE,gEAAgE,GAAG,CAAC,MAAM,GAAG,EAClF,EAAE,IAAI,EAAE,SAAS,CAAC,eAAe,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,EAAE,CACzF,CAAC;QACJ,CAAC;QACD,2FAA2F;QAC3F,8FAA8F;QAC9F,yCAAyC;QACzC,MAAM,CAAC,GAAG,iBAAiB,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAClD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,YAAY;YAAE,EAAE,IAAI,GAAG,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC;IAChF,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAE,CAAC;IAC3B,IAAI,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,EAAE,CAAC;QACpB,MAAM,IAAI,UAAU,CAClB,GAAG,EAAE,0CAA0C,EAAE,gCAAgC,IAAI,6CAA6C,EAClI;YACE,IAAI,EAAE,SAAS,CAAC,eAAe;YAC/B,OAAO,EAAE,EAAE,IAAI,EAAE,oBAAoB,EAAE,EAAE,EAAE,YAAY,EAAE,QAAQ,EAAE;SACpE,CACF,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/modules/options/dist/engine-bsm.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared BSM contract-pricing used by both the engine objects (`engines.*`) and the pro API
+ * (`option.price` / `option.impliedVolatility`). Single source of truth — routes to the `bsm` kernel.
+ */
+import { type OptionContract } from '../../core/dist/index.js';
+import { type ImpliedVolatilityOptions, type ImpliedVolatilitySolveResult } from './iv.js';
+import type { OptionMarket, PriceResult } from './types.js';
+export interface BlackScholesEngineConfig {
+    name: string;
+    /** Whether `market.dividendYield` is applied (BSM) or ignored (textbook Black–Scholes). */
+    useDividends: boolean;
+}
+/** The applied expiry-resolution convention, echoed in assumptions so it is never silent. */
+export declare function expiryConventionOf(expiry: string): 'us-equity-close' | 'explicit-instant';
+/** Price a European contract under BSM, returning value + Greeks + assumptions + diagnostics. */
+export declare function priceContract(config: BlackScholesEngineConfig, contract: OptionContract, market: OptionMarket, options?: {
+    greeks?: boolean;
+    extendedGreeks?: boolean;
+}): PriceResult;
+/** Solve implied volatility for a contract from `market.price`, returning a rich envelope. */
+export declare function impliedVolatilityContract(config: BlackScholesEngineConfig, contract: OptionContract, market: OptionMarket, options?: ImpliedVolatilityOptions): ImpliedVolatilitySolveResult;
+//# sourceMappingURL=engine-bsm.d.ts.map

package/modules/options/dist/engine-bsm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-bsm.d.ts","sourceRoot":"","sources":["../src/engine-bsm.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAQL,KAAK,cAAc,EAMpB,MAAM,0BAAoB,CAAC;AAI5B,OAAO,EACL,KAAK,wBAAwB,EAC7B,KAAK,4BAA4B,EAElC,MAAM,SAAS,CAAC;AAEjB,OAAO,KAAK,EAAkB,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAI5E,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,2FAA2F;IAC3F,YAAY,EAAE,OAAO,CAAC;CACvB;AAqCD,6FAA6F;AAC7F,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,GAAG,kBAAkB,CAEzF;AA+DD,iGAAiG;AACjG,wBAAgB,aAAa,CAC3B,MAAM,EAAE,wBAAwB,EAChC,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,YAAY,EACpB,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,cAAc,CAAC,EAAE,OAAO,CAAA;CAAE,GACvD,WAAW,CA6Fb;AAED,8FAA8F;AAC9F,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,wBAAwB,EAChC,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE,wBAA6B,GACrC,4BAA4B,CA0D9B"}

package/modules/options/dist/engine-bsm.js

@@ -0,0 +1,236 @@
+/**
+ * Shared BSM contract-pricing used by both the engine objects (`engines.*`) and the pro API
+ * (`option.price` / `option.impliedVolatility`). Single source of truth — routes to the `bsm` kernel.
+ */
+import { CONVENTIONS_VERSION, DEFAULT_GREEK_UNITS, ErrorCode, InputError, UnsupportedError, ensureFinite, ensurePositive, resolveValuationAsOf, WarningCode, } from '../../core/dist/index.js';
+import { blackScholesExtendedGreeks, blackScholesGreeks, blackScholesPrice } from './bsm.js';
+import { escrowedSpot, hasDiscreteDividends } from './dividends.js';
+import { withLambdaDisclosure, withUnderflowDisclosure } from './facade-util.js';
+import { impliedVolatility, } from './iv.js';
+import { contractTimeToExpiryYears } from './time.js';
+const MODEL = 'black-scholes-merton';
+function requireSpot(market, 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);
+    return market.spot;
+}
+function requireScalarVolatility(market, functionName) {
+    if (typeof market.volatility !== 'number') {
+        throw new InputError(`${functionName}: market.volatility (a number) is required.`, {
+            code: ErrorCode.InputMissingField,
+            context: { field: 'volatility', function: functionName },
+        });
+    }
+    ensurePositive(market.volatility, 'volatility', functionName, ErrorCode.InputNegativeVolatility);
+    return market.volatility;
+}
+function requireRate(market, functionName) {
+    if (typeof market.riskFreeRate !== 'number') {
+        throw new InputError(`${functionName}: market.riskFreeRate (a number) is required in 0.0.1.`, {
+            code: ErrorCode.InputMissingField,
+            context: { field: 'riskFreeRate', function: functionName },
+        });
+    }
+    ensureFinite(market.riskFreeRate, 'riskFreeRate', functionName);
+    return market.riskFreeRate;
+}
+const DATE_ONLY_EXPIRY = /^\d{4}-\d{2}-\d{2}$/;
+/** The applied expiry-resolution convention, echoed in assumptions so it is never silent. */
+export function expiryConventionOf(expiry) {
+    return DATE_ONLY_EXPIRY.test(expiry) ? 'us-equity-close' : 'explicit-instant';
+}
+function resolveTimeToExpiry(asOf, contract, functionName) {
+    const asOfMs = resolveValuationAsOf(asOf, functionName);
+    ensureFinite(asOfMs, 'asOf', functionName);
+    const t = contractTimeToExpiryYears(asOfMs, contract, functionName);
+    if (t <= 0) {
+        throw new UnsupportedError(`${functionName}: contract expiry ${contract.expiry} is not after asOf; BSM requires t > 0.`, {
+            code: ErrorCode.InputNegativeTime,
+            context: { asOf, expiry: contract.expiry, timeToExpiryYears: t },
+        });
+    }
+    return { t, asOfMs };
+}
+function assertEuropean(config, contract) {
+    if (contract.style !== 'european') {
+        throw new UnsupportedError(`${config.name} prices European-style options only; received style "${contract.style}". ` +
+            `For American/Bermudan pricing use the engines.* factories ` +
+            `(e.g. engines.binomial(), engines.bjerksundStensland2002()).`, {
+            code: ErrorCode.EngineUnsupportedContract,
+            context: { engine: config.name, style: contract.style },
+        });
+    }
+}
+function proAssumptions(input) {
+    const { engine, timeToExpiryYears: t, dividendYield: q, asOf, expiry, escrowed = false } = input;
+    return {
+        conventionsVersion: CONVENTIONS_VERSION,
+        dayCount: 'ACT/365F',
+        compounding: 'continuous',
+        asOf,
+        timeToExpiryYears: t,
+        expiryConvention: expiryConventionOf(expiry),
+        dividendModel: escrowed ? 'discreteSchedule' : q === 0 ? 'none' : 'continuousYield',
+        units: DEFAULT_GREEK_UNITS,
+        model: MODEL,
+        engine,
+    };
+}
+function closedForm(engine) {
+    return { engine, method: 'closed-form', converged: true, warnings: [] };
+}
+/** Price a European contract under BSM, returning value + Greeks + assumptions + diagnostics. */
+export function priceContract(config, contract, market, options) {
+    const functionName = `option.price(${config.name})`;
+    assertEuropean(config, contract);
+    const spot = requireSpot(market, functionName);
+    const vol = requireScalarVolatility(market, functionName);
+    const rate = requireRate(market, functionName);
+    ensurePositive(contract.strike, 'strike', functionName, ErrorCode.InputNegativeStrike);
+    const q = config.useDividends ? (market.dividendYield ?? 0) : 0;
+    ensureFinite(q, 'dividendYield', functionName);
+    const { t, asOfMs } = resolveTimeToExpiry(market.asOf, contract, functionName);
+    // Discrete cash dividends are applied via the escrowed-spot model — the same handling the American
+    // engines use — so `market.dividends` is never silently ignored on the dividend-aware BSM path.
+    // The textbook `blackScholes` engine (`useDividends: false`) is the no-dividend model and ignores
+    // both continuous and discrete dividends by design.
+    const escrowed = config.useDividends && hasDiscreteDividends(market);
+    const S = escrowed
+        ? escrowedSpot({
+            spot,
+            market,
+            asOf: asOfMs,
+            timeToExpiryYears: t,
+            riskFreeRate: rate,
+            functionName,
+        })
+        : spot;
+    const value = blackScholesPrice({
+        type: contract.type,
+        spot: S,
+        strike: contract.strike,
+        timeToExpiryYears: t,
+        riskFreeRate: rate,
+        dividendYield: q,
+        volatility: vol,
+    });
+    // Honor `greeks: false` (engine-substitutability law, spec P2.4): absent Greeks mean "not
+    // requested", flagged not-computed — matching the American/FD engines' contract exactly.
+    // `extendedGreeks` implies `greeks` (the shared PriceOptions semantics).
+    const wantExtended = options?.extendedGreeks ?? false;
+    const wantGreeks = wantExtended || (options?.greeks ?? true);
+    const greeks = !wantGreeks
+        ? undefined
+        : wantExtended
+            ? blackScholesExtendedGreeks({
+                type: contract.type,
+                spot: S,
+                strike: contract.strike,
+                timeToExpiryYears: t,
+                riskFreeRate: rate,
+                dividendYield: q,
+                volatility: vol,
+            })
+            : blackScholesGreeks({
+                type: contract.type,
+                spot: S,
+                strike: contract.strike,
+                timeToExpiryYears: t,
+                riskFreeRate: rate,
+                dividendYield: q,
+                volatility: vol,
+            });
+    // The facade discloses an underflowed price; the PRO path must say the same thing, or the same
+    // calculation is honest through one door and silent through the other.
+    let diagnostics = withUnderflowDisclosure(closedForm(config.name), value);
+    if (!wantGreeks) {
+        diagnostics = {
+            ...diagnostics,
+            warnings: [
+                ...diagnostics.warnings,
+                {
+                    code: WarningCode.GreeksNotComputed,
+                    message: 'Greeks were not computed (greeks: false).',
+                    severity: 'info',
+                },
+            ],
+        };
+    }
+    else if (wantExtended && greeks.lambda === null) {
+        diagnostics = withLambdaDisclosure(diagnostics, { lambda: null });
+    }
+    const base = {
+        value,
+        assumptions: proAssumptions({
+            engine: config.name,
+            timeToExpiryYears: t,
+            dividendYield: q,
+            asOf: asOfMs,
+            expiry: contract.expiry,
+            escrowed,
+        }),
+        diagnostics,
+    };
+    return greeks ? { ...base, greeks } : base;
+}
+/** Solve implied volatility for a contract from `market.price`, returning a rich envelope. */
+export function impliedVolatilityContract(config, contract, market, options = {}) {
+    const functionName = 'option.impliedVolatility';
+    assertEuropean(config, contract);
+    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 },
+        });
+    }
+    ensurePositive(market.price, 'price', functionName);
+    const spot = requireSpot(market, functionName);
+    const rate = requireRate(market, functionName);
+    ensurePositive(contract.strike, 'strike', functionName, ErrorCode.InputNegativeStrike);
+    const q = config.useDividends ? (market.dividendYield ?? 0) : 0;
+    ensureFinite(q, 'dividendYield', functionName);
+    const { t, asOfMs } = resolveTimeToExpiry(market.asOf, contract, functionName);
+    // Discrete dividends are escrowed off the spot, consistent with pricing (above) and the American
+    // engines, so the inverted vol is solved against the same effective spot.
+    const escrowed = config.useDividends && hasDiscreteDividends(market);
+    const S = escrowed
+        ? escrowedSpot({
+            spot,
+            market,
+            asOf: asOfMs,
+            timeToExpiryYears: t,
+            riskFreeRate: rate,
+            functionName,
+        })
+        : spot;
+    // Route through the full IV method suite (auto/brent/newton/halley/householder + fallback),
+    // re-stamping the pro assumptions envelope (which carries asOf). Non-convergence and no-arbitrage
+    // failures arrive as `diagnostics.converged: false`, never a fabricated value.
+    const res = impliedVolatility({
+        price: market.price,
+        spot: S,
+        strike: contract.strike,
+        timeToExpiryYears: t,
+        riskFreeRate: rate,
+        type: contract.type,
+        dividendYield: q,
+    }, options);
+    return {
+        value: res.value,
+        assumptions: proAssumptions({
+            engine: config.name,
+            timeToExpiryYears: t,
+            dividendYield: q,
+            asOf: asOfMs,
+            expiry: contract.expiry,
+            escrowed,
+        }),
+        diagnostics: res.diagnostics,
+    };
+}
+//# sourceMappingURL=engine-bsm.js.map

package/modules/options/dist/engine-bsm.js.map

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

package/modules/options/dist/engines/american-approx.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Closed-form American approximations (spec §9.3):
+ *   - Barone–Adesi–Whaley (1987) quadratic approximation;
+ *   - Bjerksund–Stensland (1993) single-boundary approximation;
+ *   - Bjerksund–Stensland (2002) two-boundary refinement — splits time to expiry at
+ *     `t₁ = ½(√5 − 1)T` and uses two flat exercise boundaries, evaluated with the cumulative
+ *     bivariate normal. This is the more accurate, more widely-used form (the default alias).
+ *
+ * All use the carry rate `b = r − q` and reuse the BSM European price. They are validated against
+ * the lattice engines (the convergence reference) and an external benchmark in tests.
+ */
+import type { AmericanApproximationInput } from './scalar-pricing.js';
+/** A BAW price with the critical-price iteration's own convergence verdict (never assumed). */
+export interface BawSolution {
+    value: number;
+    /** `false` when the critical-price Newton loop hit its budget without meeting tolerance. */
+    converged: boolean;
+    /** Newton steps taken (0 when the closed European branch answered without iterating). */
+    iterations: number;
+}
+/** Barone–Adesi–Whaley American price with diagnostics (the form the engine adapter uses). */
+export declare function bawSolve(input: AmericanApproximationInput): BawSolution;
+/** Barone–Adesi–Whaley American option price. */
+export declare function bawPrice(input: AmericanApproximationInput): number;
+/** Bjerksund–Stensland (1993) American option price. */
+export declare function bjerksundStenslandPrice(input: AmericanApproximationInput): number;
+/** Bjerksund–Stensland (2002) American option price — the two-boundary refinement of the 1993 form. */
+export declare function bjerksundStensland2002Price(input: AmericanApproximationInput): number;
+//# sourceMappingURL=american-approx.d.ts.map

package/modules/options/dist/engines/american-approx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"american-approx.d.ts","sourceRoot":"","sources":["../../src/engines/american-approx.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAqNtE,+FAA+F;AAC/F,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,4FAA4F;IAC5F,SAAS,EAAE,OAAO,CAAC;IACnB,yFAAyF;IACzF,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,8FAA8F;AAC9F,wBAAgB,QAAQ,CAAC,KAAK,EAAE,0BAA0B,GAAG,WAAW,CAkHvE;AAED,iDAAiD;AACjD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,0BAA0B,GAAG,MAAM,CAElE;AA0ID,wDAAwD;AACxD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,0BAA0B,GAAG,MAAM,CA+BjF;AA4GD,uGAAuG;AACvG,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,0BAA0B,GAAG,MAAM,CA+BrF"}