@insiderfinance/totalfinance 0.1.0

package/modules/options/dist/monte-carlo.js

@@ -0,0 +1,388 @@
+/**
+ * Monte-Carlo / quasi-Monte-Carlo European option pricing on geometric Brownian motion (spec §9.3).
+ *
+ * Built on the seeded MC estimator in `./mc/core`. The terminal underlying is the control variate
+ * (its expectation `S₀·e^{−qT}` is known exactly), and Greeks are computed by common-random-number
+ * finite differences — re-pricing with the *same* seed so the bumps difference cleanly.
+ *
+ * This is the reference path-pricer: against Black–Scholes–Merton it converges to the closed form, so
+ * it both validates the analytic engines and prices payoffs the closed form can't. Stochastic-vol and
+ * exotic pricers reuse the same estimator with their own dynamics and payoffs.
+ *
+ *   import { monteCarloPrice } from '@insiderfinance/totalfinance/options/monte-carlo';
+ *   monteCarloPrice({ contract: option.call({ ..., style: 'european' }), market, options: { paths: 100_000, seed: 7, method: 'sobol' } });
+ */
+import { ensureKnownKeys, requireFiniteFields, ensureFiniteWhenPresent, CONVENTIONS_VERSION, DEFAULT_GREEK_UNITS, ErrorCode, InputError, UnsupportedError, ensureEnum, ensureFinite, ensurePositive, requireArgumentObject, resolveValuationAsOf, WarningCode, } from '../../core/dist/index.js';
+import { expiryConventionOf } from './engine-bsm.js';
+import { escrowedSpot, hasDiscreteDividends } from './dividends.js';
+import { gbmTerminalUnchecked, monteCarloEstimate, } from './mc/core.js';
+import { contractTimeToExpiryYears } from './time.js';
+import { assertNoArbitrageBounds } from './engines/bounds.js';
+import { finiteDifferenceExtendedGreeks, resolveFdSteps } from './engines/fd-greeks.js';
+export { gbm, gbmPath, gbmTerminal } from './mc/core.js';
+/**
+ * Low-level kernel: estimate the discounted European payoff on GBM. Inputs are assumed validated
+ * (S, K, T, σ all > 0). Uses the discounted terminal price as a control variate.
+ *
+ * The raw kernel remains direct and assumption-light, but its financially interchangeable values
+ * are named so a transposed rate, yield, time, or volatility cannot typecheck unnoticed.
+ */
+export function monteCarloEuropean(input) {
+    requireArgumentObject('monteCarloEuropean', 'input', input);
+    ensureKnownKeys('monteCarloEuropean', 'input', input, [
+        'type',
+        'spot',
+        'strike',
+        'timeToExpiryYears',
+        'riskFreeRate',
+        'dividendYield',
+        'volatility',
+        'options',
+    ]);
+    // Every numeric is declared REQUIRED: present / a number / finite each teach their own code —
+    // a null spot used to reach the GBM kernel and estimate NaN with a clean confidence interval.
+    requireFiniteFields('monteCarloEuropean', input, ['spot', 'strike', 'timeToExpiryYears', 'riskFreeRate', 'dividendYield', 'volatility'], {
+        exampleCall: "monteCarloEuropean({ type: 'call', spot: 100, strike: 105, timeToExpiryYears: 0.5, riskFreeRate: 0.045, dividendYield: 0, volatility: 0.2, options: { paths: 100_000, seed: 42 } })",
+    });
+    const { type, spot: S, strike: K, timeToExpiryYears: T, riskFreeRate: r, dividendYield: q, volatility: sigma, options, } = input;
+    // `type` is a meaning-changing string: unvalidated garbage would silently price the other leg.
+    ensureEnum(type, ['call', 'put'], 'type', 'monteCarloEuropean');
+    requireArgumentObject('monteCarloEuropean', 'options', options);
+    for (const numField of ['confidence', 'paths', 'seed']) {
+        const numValue = options[numField];
+        if (numValue !== undefined && (typeof numValue !== 'number' || !Number.isFinite(numValue))) {
+            throw new InputError(`monteCarloEuropean: options.${numField} must be a finite number when provided. Received ${numValue === null ? 'null' : typeof numValue}.`, { code: ErrorCode.InputWrongType, context: { field: numField } });
+        }
+    }
+    for (const flag of ['greeks', 'extendedGreeks', 'antithetic', 'brownianBridge']) {
+        const flagValue = options[flag];
+        if (flagValue !== undefined && typeof flagValue !== 'boolean') {
+            throw new InputError(`monteCarloEuropean: options.${flag} must be a boolean when provided. Received ${flagValue === null ? 'null' : typeof flagValue}.`, { code: ErrorCode.InputWrongType, context: { field: flag } });
+        }
+    }
+    const df = Math.exp(-r * T);
+    const payoff = (z) => {
+        const ST = gbmTerminalUnchecked({
+            spot: S,
+            riskFreeRate: r,
+            dividendYield: q,
+            volatility: sigma,
+            timeToExpiryYears: T,
+            shock: z[0],
+        });
+        return df * (type === 'call' ? Math.max(ST - K, 0) : Math.max(K - ST, 0));
+    };
+    const control = {
+        estimate: (z) => df *
+            gbmTerminalUnchecked({
+                spot: S,
+                riskFreeRate: r,
+                dividendYield: q,
+                volatility: sigma,
+                timeToExpiryYears: T,
+                shock: z[0],
+            }),
+        mean: S * Math.exp(-q * T),
+    };
+    return monteCarloEstimate({
+        dimensions: 1,
+        payoff,
+        options,
+        controlVariate: control,
+        label: 'monteCarloPrice',
+    });
+}
+/** Common-random-number finite-difference Greeks: re-price with the same seed so bumps difference cleanly. */
+function crnGreeks(input) {
+    const { type, spot: S, strike: K, timeToExpiryYears: T, riskFreeRate: r, dividendYield: q, volatility: sigma, options, } = input;
+    const priceAt = ({ spot, volatility, timeToExpiryYears, riskFreeRate, dividendYield, }) => monteCarloEuropean({
+        type,
+        spot,
+        strike: K,
+        timeToExpiryYears,
+        riskFreeRate,
+        dividendYield,
+        volatility,
+        options,
+    }).value;
+    // The full set uses common random numbers throughout (the seed is fixed in `options`), so the
+    // difference stencils are low-variance. `sigma` is the real GBM vol here (no vol-level proxy).
+    if (options.extendedGreeks) {
+        return finiteDifferenceExtendedGreeks({
+            price: priceAt,
+            spotAt: () => S,
+            state: { spot: S, T, r, q, sigma },
+        });
+    }
+    const base = priceAt({
+        spot: S,
+        volatility: sigma,
+        timeToExpiryYears: T,
+        riskFreeRate: r,
+        dividendYield: q,
+    });
+    // Adaptive near the vol/time boundaries (P2.3) — same rule as every other FD path.
+    const { spotStep, volatilityStep, timeStepYears, rateStep } = resolveFdSteps({ spot: S, T, r, q, sigma }, { timeStepYears: Math.min(1e-4, T / 4) });
+    const pSup = priceAt({
+        spot: S + spotStep,
+        volatility: sigma,
+        timeToExpiryYears: T,
+        riskFreeRate: r,
+        dividendYield: q,
+    });
+    const pSdn = priceAt({
+        spot: S - spotStep,
+        volatility: sigma,
+        timeToExpiryYears: T,
+        riskFreeRate: r,
+        dividendYield: q,
+    });
+    const delta = (pSup - pSdn) / (2 * spotStep);
+    const gamma = (pSup - 2 * base + pSdn) / (spotStep * spotStep);
+    const vega = (priceAt({
+        spot: S,
+        volatility: sigma + volatilityStep,
+        timeToExpiryYears: T,
+        riskFreeRate: r,
+        dividendYield: q,
+    }) -
+        priceAt({
+            spot: S,
+            volatility: sigma - volatilityStep,
+            timeToExpiryYears: T,
+            riskFreeRate: r,
+            dividendYield: q,
+        })) /
+        (2 * volatilityStep) /
+        100;
+    const theta = -(priceAt({
+        spot: S,
+        volatility: sigma,
+        timeToExpiryYears: T + timeStepYears,
+        riskFreeRate: r,
+        dividendYield: q,
+    }) -
+        priceAt({
+            spot: S,
+            volatility: sigma,
+            timeToExpiryYears: T - timeStepYears,
+            riskFreeRate: r,
+            dividendYield: q,
+        })) /
+        (2 * timeStepYears) /
+        365;
+    const rho = (priceAt({
+        spot: S,
+        volatility: sigma,
+        timeToExpiryYears: T,
+        riskFreeRate: r + rateStep,
+        dividendYield: q,
+    }) -
+        priceAt({
+            spot: S,
+            volatility: sigma,
+            timeToExpiryYears: T,
+            riskFreeRate: r - rateStep,
+            dividendYield: q,
+        })) /
+        (2 * rateStep) /
+        100;
+    return { delta, gamma, theta, vega, rho };
+}
+function assumptions(input) {
+    const { timeToExpiryYears: t, dividendYield: q, asOf, escrowed, expiry } = 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: 'black-scholes-merton',
+        engine: 'monte-carlo',
+    };
+}
+function methodLabel(method) {
+    return method === 'pseudo' ? 'monte-carlo' : `monte-carlo-${method}`;
+}
+export function monteCarloPrice(input) {
+    requireArgumentObject('monteCarloPrice', 'input', input);
+    // Law 12: a misspelled top-level field (`contarct`) must teach, never price against defaults.
+    ensureKnownKeys('monteCarloPrice', 'input', input, ['contract', 'market', 'options']);
+    const mcOptions = input['options'];
+    if (mcOptions !== undefined && (mcOptions === null || typeof mcOptions !== 'object')) {
+        throw new InputError(`monteCarloPrice: options must be an object when provided. Received ${mcOptions === null ? 'null' : typeof mcOptions}.`, { code: ErrorCode.InputWrongType, context: { field: 'options' } });
+    }
+    if (mcOptions !== undefined) {
+        for (const numField of ['confidence', 'paths', 'seed']) {
+            const numValue = mcOptions[numField];
+            if (numValue !== undefined && (typeof numValue !== 'number' || !Number.isFinite(numValue))) {
+                throw new InputError(`monteCarloPrice: options.${numField} must be a finite number when provided. Received ${numValue === null ? 'null' : typeof numValue}.`, { code: ErrorCode.InputWrongType, context: { field: numField } });
+            }
+        }
+        for (const flag of ['greeks', 'extendedGreeks', 'antithetic', 'brownianBridge']) {
+            const flagValue = mcOptions[flag];
+            if (flagValue !== undefined && typeof flagValue !== 'boolean') {
+                throw new InputError(`monteCarloPrice: options.${flag} must be a boolean when provided. Received ${flagValue === null ? 'null' : typeof flagValue}.`, { code: ErrorCode.InputWrongType, context: { field: flag } });
+            }
+        }
+    }
+    const { contract, market, options } = input;
+    requireArgumentObject('monteCarloPrice', 'contract', contract);
+    requireArgumentObject('monteCarloPrice', 'market', market);
+    const functionName = 'monteCarloPrice';
+    if (contract.style !== 'european') {
+        throw new UnsupportedError(`${functionName}: the GBM Monte-Carlo engine prices European-style options only; received "${contract.style}".`, { code: ErrorCode.EngineUnsupportedContract, context: { style: contract.style } });
+    }
+    if (typeof market.spot !== 'number') {
+        throw new InputError(`${functionName}: market.spot is required.`, {
+            code: ErrorCode.InputMissingField,
+            context: { field: 'spot' },
+        });
+    }
+    if (typeof market.volatility !== 'number') {
+        throw new InputError(`${functionName}: market.volatility (a number) is required.`, {
+            code: ErrorCode.InputMissingField,
+            context: { field: 'volatility' },
+        });
+    }
+    if (typeof market.riskFreeRate !== 'number') {
+        throw new InputError(`${functionName}: market.riskFreeRate (a number) is required.`, {
+            code: ErrorCode.InputMissingField,
+            context: { field: 'riskFreeRate' },
+        });
+    }
+    ensurePositive(market.spot, 'spot', functionName, ErrorCode.InputNegativeSpot);
+    ensurePositive(market.volatility, 'volatility', functionName, ErrorCode.InputNegativeVolatility);
+    ensurePositive(contract.strike, 'strike', functionName, ErrorCode.InputNegativeStrike);
+    ensureFinite(market.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(market.dividendYield, 'dividendYield', functionName);
+    const q = market.dividendYield ?? 0;
+    const asOfMs = resolveValuationAsOf(market.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.`, {
+            code: ErrorCode.InputNegativeTime,
+            context: { asOf: market.asOf, expiry: contract.expiry },
+        });
+    }
+    const escrowed = hasDiscreteDividends(market);
+    const S = escrowed
+        ? escrowedSpot({
+            spot: market.spot,
+            market,
+            asOf: asOfMs,
+            timeToExpiryYears: T,
+            riskFreeRate: market.riskFreeRate,
+            functionName,
+        })
+        : market.spot;
+    const sigma = market.volatility;
+    const r = market.riskFreeRate;
+    const K = contract.strike;
+    const type = contract.type;
+    const est = monteCarloEuropean({
+        type,
+        spot: S,
+        strike: K,
+        timeToExpiryYears: T,
+        riskFreeRate: r,
+        dividendYield: q,
+        volatility: sigma,
+        options,
+    });
+    // Monte-Carlo defaults to NOT computing Greeks (each is ~2 extra path budgets). When not requested
+    // they are ABSENT — never fabricated zeros (design law #4) — with an info diagnostic. Pass
+    // `{ greeks: true }` to compute CRN finite-difference Greeks.
+    const wantGreeks = options.extendedGreeks || (options.greeks ?? false);
+    const greeks = wantGreeks
+        ? crnGreeks({
+            type,
+            spot: S,
+            strike: K,
+            timeToExpiryYears: T,
+            riskFreeRate: r,
+            dividendYield: q,
+            volatility: sigma,
+            options,
+        })
+        : undefined;
+    const fd = wantGreeks
+        ? resolveFdSteps({ spot: S, T, r, q, sigma }, options.extendedGreeks ? {} : { timeStepYears: Math.min(1e-4, T / 4) })
+        : undefined;
+    const diagnostics = {
+        engine: 'monte-carlo',
+        method: methodLabel(est.method),
+        converged: est.converged,
+        iterations: est.paths,
+        // The exact bump sizes differenced for the CRN Greeks (P2.3).
+        ...(fd !== undefined
+            ? {
+                finiteDifferenceBumps: options.extendedGreeks
+                    ? {
+                        spotStep: fd.spotStep,
+                        volatilityStep: fd.volatilityStep,
+                        timeStepYears: fd.timeStepYears,
+                        rateStep: fd.rateStep,
+                        dividendYieldStep: fd.dividendYieldStep,
+                    }
+                    : {
+                        spotStep: fd.spotStep,
+                        volatilityStep: fd.volatilityStep,
+                        timeStepYears: fd.timeStepYears,
+                        rateStep: fd.rateStep,
+                    },
+            }
+            : {}),
+        warnings: wantGreeks
+            ? est.warnings
+            : [
+                ...est.warnings,
+                {
+                    code: WarningCode.GreeksNotComputed,
+                    message: 'Greeks were not computed for this Monte-Carlo price; pass { greeks: true }.',
+                    severity: 'info',
+                },
+            ],
+    };
+    // Structural postcondition (defect-fix wave, finding 5), with the estimator's own sampling error
+    // as slack so a legitimate draw near the bound is never mistaken for a defect.
+    assertNoArbitrageBounds({
+        engine: 'monte-carlo',
+        type,
+        style: 'european',
+        value: est.value,
+        underlyingPresentValue: S * Math.exp(-q * T),
+        strikePresentValue: K * Math.exp(-r * T),
+        spot: S,
+        strike: K,
+        tolerance: 5 *
+            (est.standardError !== null && Number.isFinite(est.standardError) ? est.standardError : 0),
+    });
+    return {
+        value: est.value,
+        ...(greeks ? { greeks } : {}),
+        assumptions: assumptions({
+            timeToExpiryYears: T,
+            dividendYield: q,
+            asOf: asOfMs,
+            escrowed,
+            expiry: contract.expiry,
+        }),
+        diagnostics,
+        monteCarlo: {
+            standardError: est.standardError,
+            confidenceInterval: est.confidenceInterval,
+            paths: est.paths,
+            seed: est.seed,
+            method: est.method,
+            varianceReduction: est.varianceReduction,
+        },
+    };
+}
+//# sourceMappingURL=monte-carlo.js.map

package/modules/options/dist/monte-carlo.js.map

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

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

@@ -0,0 +1,191 @@
+/**
+ * `@insiderfinance/totalfinance/options/parity` — put-call parity, implied carry, and box-spread financing from a
+ * snapshot option chain (spec §WS9.4).
+ *
+ * Put-call parity says the call/put mid at each strike sits on a straight line in the strike `K`:
+ *
+ *     C(K) − P(K) = e^(−rT)·(F − K) = S·e^(−qT) − K·e^(−rT)
+ *
+ * so a regression of the parity spread `y_K = C(K) − P(K)` on `K` recovers the forward and the
+ * discount factor from one expiry's chain, with no volatility model:
+ *
+ *   - slope     = −e^(−rT)                     ⇒ implied discount factor  DF = −slope = e^(−rT)
+ *   - intercept =  e^(−rT)·F = S·e^(−qT)       ⇒ implied forward          F  = −intercept / slope
+ *   - implied financing rate                   ⇒ r* = −ln(DF) / T
+ *   - implied dividend yield (given S)         ⇒ q  = r − ln(F/S) / T
+ *
+ * Every function returns the pro-API envelope `{ value, assumptions, diagnostics }` (spec §5.2):
+ * `assumptions` echoes the applied conventions (day-count, `asOf`, time-to-expiry, price source,
+ * outlier threshold), and `diagnostics` carries the per-strike parity residuals plus the MAD-based
+ * outlier trim (count + strikes) so nothing is hidden. Quantitative degeneracy is reported via
+ * `diagnostics.converged` and `diagnostics.warnings`, never a fabricated value (design law #4).
+ * Malformed arguments (missing `rows`/`options`, bad numbers) throw an {@link InputError} with a stable
+ * `input.*` code; chain-level gaps (a missing leg, too few usable strikes) throw a stable `parity.*`
+ * code — see {@link ParityCode}.
+ */
+import type { Assumptions, Diagnostics, EpochMs, OptionQuote, PriceSource } from '../../core/dist/index.js';
+/** Default MAD multiplier `k`: a strike whose parity residual exceeds `k·MAD` is trimmed. */
+export declare const DEFAULT_OUTLIER_THRESHOLD = 3.5;
+/** Stable `parity.*` error/warning codes (public API; the set is open). */
+export declare const ParityCode: {
+    /** A specifically requested strike/leg quote is missing (box spread). */
+    readonly StrikeUnavailable: "parity.strike_unavailable";
+    /** Fewer than two usable strikes with both a call and a put — a line cannot be fit. */
+    readonly InsufficientStrikes: "parity.insufficient_strikes";
+    /** The regression slope is non-negative, so no positive discount factor exists. */
+    readonly NonPositiveDiscount: "parity.nonpositive_discount";
+    /** The implied forward came out non-positive / non-finite. */
+    readonly NonPositiveForward: "parity.nonpositive_forward";
+    /** The box debit is non-positive, so no real financing rate exists. */
+    readonly DegenerateBox: "parity.degenerate_box";
+    /** The regression-implied rate disagrees materially with the supplied rate. */
+    readonly RateMismatch: "parity.rate_mismatch";
+};
+/** Per-strike parity diagnostic echoed for every usable strike (design law: nothing hidden). */
+export interface ParityStrikeResidual {
+    strike: number;
+    /** Call price at this strike (from the chosen `source`). */
+    call: number;
+    /** Put price at this strike. */
+    put: number;
+    /** Observed parity spread `C − P`. */
+    spread: number;
+    /** Fitted spread `intercept + slope·K` from the final (post-trim) regression. */
+    fitted: number;
+    /** `spread − fitted`. */
+    residual: number;
+    /** Whether this strike was dropped as a MAD outlier before the final fit. */
+    trimmed: boolean;
+}
+/** Assumptions echoed by the regression-based parity functions. */
+export type ParityAssumptions = Assumptions<{
+    riskFreeRate: number;
+    priceSource: PriceSource;
+    outlierThreshold: number;
+    spot?: number;
+}>;
+/** Diagnostics for the regression-based parity functions. Extends the shared {@link Diagnostics}. */
+export interface ParityDiagnostics extends Diagnostics {
+    /** Number of strikes used in the final fit (after trimming). */
+    strikesUsed: number;
+    /** Number of strikes trimmed as MAD outliers. */
+    trimmedCount: number;
+    /** The strikes that were trimmed, ascending. */
+    trimmedStrikes: number[];
+    /** Per-strike parity residuals for every usable strike (trimmed ones flagged). */
+    perStrike: ParityStrikeResidual[];
+    /** Median absolute deviation of the initial-fit residuals used for trimming. */
+    medianAbsoluteDeviationResidual: number;
+    /** Coefficient of determination of the final regression. */
+    rSquared: number;
+    /** Implied discount factor `DF = −slope = e^(−rT)`. */
+    impliedDiscountFactor: number;
+    /** Implied continuously-compounded financing rate `r* = −ln(DF)/T`. */
+    impliedRate: number;
+}
+/** The rich envelope returned by {@link impliedForward}/{@link impliedDividendYield}/{@link impliedBorrow}. */
+export interface ParityResult {
+    value: number;
+    assumptions: ParityAssumptions;
+    diagnostics: ParityDiagnostics;
+}
+/** Assumptions echoed by {@link boxSpreadRate}. */
+export type BoxSpreadAssumptions = Assumptions<{
+    priceSource: PriceSource;
+    lowerStrike: number;
+    upperStrike: number;
+}>;
+/** Diagnostics for {@link boxSpreadRate}. */
+export interface BoxSpreadDiagnostics extends Diagnostics {
+    /** Net debit of the box `(C(k1) − C(k2)) + (P(k2) − P(k1))`. */
+    debit: number;
+    /** Strike width `k2 − k1`, the guaranteed expiry payoff. */
+    width: number;
+    /** `debit / width = e^(−rT)`, the implied discount factor. */
+    discountFactor: number;
+}
+/** The rich envelope returned by {@link boxSpreadRate}. */
+export interface BoxSpreadResult {
+    value: number;
+    assumptions: BoxSpreadAssumptions;
+    diagnostics: BoxSpreadDiagnostics;
+}
+/** Options shared by the regression-based parity functions. */
+export interface ImpliedForwardOptions {
+    /** Continuously-compounded risk-free rate. */
+    riskFreeRate: number;
+    /** Snapshot time (epoch ms, 'YYYY-MM-DD', or zoned ISO datetime); time-to-expiry is measured from here under ACT/365F. */
+    asOf: EpochMs | string;
+    /** Quote price source per leg (default `mid`). */
+    source?: PriceSource;
+    /** MAD multiplier for outlier trimming (default {@link DEFAULT_OUTLIER_THRESHOLD}). */
+    outlierThreshold?: number;
+}
+/** Options for {@link impliedDividendYield} — adds the spot needed to back out `q`. */
+export interface ImpliedDividendYieldOptions extends ImpliedForwardOptions {
+    spot: number;
+}
+/** Options for {@link impliedBorrow} — adds the spot used in diagnostics. */
+export interface ImpliedBorrowOptions extends ImpliedForwardOptions {
+    spot: number;
+}
+/** Options for {@link boxSpreadRate}. */
+export interface BoxSpreadOptions {
+    /** Snapshot time (epoch ms, 'YYYY-MM-DD', or zoned ISO datetime). */
+    asOf: EpochMs | string;
+    /** Quote price source per leg (default `mid`). */
+    source?: PriceSource;
+}
+/** One cohesive request for put-call-parity forward inference. */
+export interface ImpliedForwardInput {
+    quotes: readonly OptionQuote[];
+    expiry: string;
+    options: ImpliedForwardOptions;
+}
+/** One cohesive request for dividend-yield inference from put-call parity. */
+export interface ImpliedDividendYieldInput {
+    quotes: readonly OptionQuote[];
+    expiry: string;
+    options: ImpliedDividendYieldOptions;
+}
+/** One cohesive request for borrow-spread inference from put-call parity. */
+export interface ImpliedBorrowInput {
+    quotes: readonly OptionQuote[];
+    expiry: string;
+    options: ImpliedBorrowOptions;
+}
+/** One cohesive request for a box-spread-implied financing rate. */
+export interface BoxSpreadRateInput {
+    quotes: readonly OptionQuote[];
+    expiry: string;
+    lowerStrike: number;
+    upperStrike: number;
+    options: BoxSpreadOptions;
+}
+/**
+ * Implied forward `F` from put-call parity across one expiry's chain.
+ *
+ * Regresses `C(K) − P(K)` on `K`; from `slope = −e^(−rT)` and `intercept = e^(−rT)·F`,
+ * `F = −intercept / slope`. The supplied `rate` is echoed and compared against the
+ * regression-implied financing rate (reported in `diagnostics.impliedRate`); it does not bias `F`.
+ */
+export declare function impliedForward(input: ImpliedForwardInput): ParityResult;
+/**
+ * Implied continuous dividend yield `q` from `F = S·e^((r−q)T)` ⇒ `q = r − ln(F/S)/T`, using the
+ * regression forward and the supplied `spot`/`rate`.
+ */
+export declare function impliedDividendYield(input: ImpliedDividendYieldInput): ParityResult;
+/**
+ * Implied borrow / financing spread: the regression-implied financing rate `r*` (from the parity
+ * slope) minus the supplied `rate`. Zero when the chain was priced at exactly `rate`.
+ */
+export declare function impliedBorrow(input: ImpliedBorrowInput): ParityResult;
+/**
+ * Implied financing rate from the box spread between strikes `k1 < k2`.
+ *
+ * A box (bull call spread `+` bear put spread) locks in `(k2 − k1)` at expiry for a net debit
+ * `box = (C(k1) − C(k2)) + (P(k2) − P(k1))`, so `box = (k2 − k1)·e^(−rT)` and
+ * `rate = −ln(box / (k2 − k1)) / T`. Throws `parity.strike_unavailable` when a needed leg is missing.
+ */
+export declare function boxSpreadRate(input: BoxSpreadRateInput): BoxSpreadResult;
+//# sourceMappingURL=parity.d.ts.map

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

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