@insiderfinance/totalfinance 0.1.0

package/modules/options/dist/chain-greeks.js

@@ -0,0 +1,154 @@
+/**
+ * `chainGreeks` (pre-publish interface repairs, B7): the Greeks call that exists.
+ *
+ * A chain row is `OptionQuote`. Its optional `greeks` are what a vendor supplied or what this call
+ * stamped: per row it selects the observed price, solves the implied volatility with the same
+ * style routing as `option.impliedVolatility` (closed-form Black–Scholes–Merton for a European
+ * contract, the Bjerksund–Stensland 2002 engine for an American one), prices the contract at that
+ * volatility, and stamps `impliedVolatility` and the display-unit `greeks` with their provenance.
+ *
+ * It never throws per row: a row without a usable price, a price with no volatility, or a
+ * malformed row is reported in `diagnostics.rows` and returned unchanged. The arguments themselves
+ * are validated like every other door — a malformed request is a typed error.
+ */
+import { CONVENTIONS_VERSION, DEFAULT_GREEK_UNITS, ErrorCode, InputError, WarningCode, ensureEnum, ensureFiniteWhenPresent, ensureKnownKeys, isQuantError, requireArgumentArray, requireArgumentObject, requireFiniteFields, resolveValuationAsOf, selectQuotePrice, } from '../../core/dist/index.js';
+import { engines } from './engines.js';
+import { impliedVolatilityOption, priceOption } from './pro.js';
+const NAME = 'chainGreeks';
+const INPUT_KEYS = ['quotes', 'market', 'priceSource'];
+const PRICE_SOURCES = ['bid', 'ask', 'mid', 'last', 'mark'];
+const EXAMPLE_CALL = "chainGreeks({ quotes, market: { spot: 100, riskFreeRate: 0.04, asOf: '2026-06-01T15:30:00-04:00' } })";
+function skipped(index, reason, message) {
+    return { index, status: 'skipped', engine: null, reason, message };
+}
+/**
+ * Solve every chain row's implied volatility and Greeks from its observed price. See the module
+ * note: non-throwing per row, style-routed, display units, provenance stamped.
+ */
+export function chainGreeks(input) {
+    requireArgumentObject(NAME, 'input', input);
+    ensureKnownKeys(NAME, 'input', input, INPUT_KEYS);
+    requireArgumentArray(NAME, 'input.quotes', input.quotes);
+    requireArgumentObject(NAME, 'input.market', input.market);
+    // Optional enum: present-or-absent, never coalesced (a `null` must teach, not run at 'mid').
+    const priceSource = input.priceSource === undefined ? 'mid' : input.priceSource;
+    ensureEnum(priceSource, PRICE_SOURCES, 'priceSource', NAME);
+    requireFiniteFields(NAME, input.market, ['spot', 'riskFreeRate'], {
+        path: 'input.market',
+        exampleCall: EXAMPLE_CALL,
+    });
+    if (!(input.market.spot > 0)) {
+        throw new InputError(`${NAME}: input.market.spot must be positive.`, {
+            code: ErrorCode.InputNegativeSpot,
+            context: { function: NAME, field: 'input.market.spot' },
+        });
+    }
+    ensureFiniteWhenPresent(input.market.dividendYield, 'input.market.dividendYield', NAME);
+    const dividendYield = input.market.dividendYield ?? 0;
+    const asOf = resolveValuationAsOf(input.market.asOf, NAME);
+    const market = {
+        spot: input.market.spot,
+        riskFreeRate: input.market.riskFreeRate,
+        dividendYield,
+        asOf,
+    };
+    const rows = [];
+    const rowDiagnostics = [];
+    input.quotes.forEach((quote, index) => {
+        // A row that is not a quote is a programming error, not a data condition: it throws.
+        requireArgumentObject(NAME, `input.quotes[${index}]`, quote);
+        requireArgumentObject(NAME, `input.quotes[${index}].contract`, quote.contract);
+        try {
+            const price = selectQuotePrice(quote, priceSource);
+            if (price === undefined) {
+                rows.push(quote);
+                rowDiagnostics.push(skipped(index, 'chain_greeks.no_price', `no ${priceSource} price on the row`));
+                return;
+            }
+            // Style routing, and ONE engine per row: the Greeks are taken from the engine that solved
+            // the volatility, never from a different model at that volatility.
+            const engine = quote.contract.style === 'american' ? { engine: engines.bjerksundStensland2002() } : {};
+            const solved = impliedVolatilityOption({
+                contract: quote.contract,
+                market: { ...market, price },
+                ...engine,
+            });
+            if (solved.value === null) {
+                const cause = solved.diagnostics.warnings[0];
+                rows.push(quote);
+                rowDiagnostics.push(skipped(index, cause?.code ?? 'chain_greeks.no_implied_volatility', cause?.message ?? 'no volatility reproduces the observed price'));
+                return;
+            }
+            const priced = priceOption({
+                contract: quote.contract,
+                market: { ...market, volatility: solved.value },
+                greeks: true,
+                ...engine,
+            });
+            const g = priced.greeks;
+            const greeks = {
+                delta: g.delta,
+                gamma: g.gamma,
+                theta: g.theta,
+                vega: g.vega,
+                rho: g.rho,
+                provenance: {
+                    source: 'chainGreeks',
+                    model: solved.diagnostics.engine,
+                    timestampMs: asOf,
+                },
+            };
+            rows.push({ ...quote, impliedVolatility: solved.value, greeks });
+            rowDiagnostics.push({
+                index,
+                status: 'solved',
+                engine: solved.diagnostics.engine,
+                reason: null,
+                message: null,
+            });
+        }
+        catch (error) {
+            // A row the pricers refuse (expired against `asOf`, a strike the contract law rejects, a
+            // price below intrinsic) is a data condition: reported, not thrown — the caller asked for
+            // the chain. Anything that is not a typed TotalFinance error is a bug and propagates.
+            if (!isQuantError(error))
+                throw error;
+            rows.push(quote);
+            rowDiagnostics.push(skipped(index, error.code, error.message));
+        }
+    });
+    const skippedCount = rowDiagnostics.filter((row) => row.status === 'skipped').length;
+    const warnings = [];
+    if (skippedCount > 0) {
+        warnings.push({
+            code: WarningCode.OptionsChainGreeksRowsSkipped,
+            message: `${skippedCount} of ${input.quotes.length} row(s) were not solved; see diagnostics.rows for each reason. Skipped rows are returned unchanged.`,
+            severity: 'warn',
+            context: { skippedCount, rowCount: input.quotes.length },
+        });
+    }
+    return {
+        value: rows,
+        assumptions: {
+            conventionsVersion: CONVENTIONS_VERSION,
+            dayCount: 'ACT/365F',
+            compounding: 'continuous',
+            asOf,
+            priceSource,
+            engines: { european: 'black-scholes-merton', american: 'bjerksund-stensland-2002' },
+            provenanceSource: 'chainGreeks',
+            spot: market.spot,
+            riskFreeRate: market.riskFreeRate,
+            dividendYield,
+            units: DEFAULT_GREEK_UNITS,
+        },
+        diagnostics: {
+            engine: 'chain-greeks',
+            warnings,
+            rows: rowDiagnostics,
+            solvedCount: input.quotes.length - skippedCount,
+            skippedCount,
+        },
+    };
+}
+//# sourceMappingURL=chain-greeks.js.map

package/modules/options/dist/chain-greeks.js.map

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

package/modules/options/dist/chain-health.d.ts

@@ -0,0 +1,254 @@
+/** Pure, bounded quote-quality and model-compatibility reporting for a single underlying. */
+import { type Assumptions, type MarketInputs, type OptionContract, type OptionQuote, type PriceSource, type QuantWarning } from '../../core/dist/index.js';
+import type { DiscreteDividend } from './index.js';
+/** Canonical quote fields; only timestamp absence is relaxed so it can be reported honestly. */
+export interface OptionChainHealthQuote extends Omit<OptionQuote, 'timestampMs'> {
+    /** Epoch milliseconds when known. Missing is reported, never replaced by market.asOf. */
+    timestampMs?: number;
+}
+export interface OptionChainHealthMarket extends Pick<MarketInputs, 'asOf'> {
+    /** All quote and expected-contract underlyings must match exactly. */
+    underlying: string;
+    /** Required only when BSM assessment is requested. */
+    spot?: number;
+    /** Annual continuous risk-free rate, decimal; required only for BSM assessment. */
+    riskFreeRate?: number;
+    /**
+     * Annual continuous yield, decimal. The package dividend rule applies: omitted means 0 (no
+     * continuous yield), echoed in `assumptions.dividendYield` and disclosed by a warning when the
+     * model assessment defaulted it.
+     */
+    dividendYield?: number;
+    /** Nonempty cash schedules are validated but explicitly unsupported by this BSM report. */
+    dividends?: readonly DiscreteDividend[];
+}
+/** The model path requires real caller-supplied economics; the quote-only path does not. */
+export type OptionChainHealthModelMarket = OptionChainHealthMarket & Required<Pick<MarketInputs, 'spot' | 'riskFreeRate'>>;
+export interface OptionChainHealthConfig {
+    /**
+     * Omit for quote-only health. `'black-scholes-merton'` names the dynamics: European rows invert
+     * closed-form Black–Scholes–Merton and American rows invert the Bjerksund–Stensland 2002 engine
+     * under the same dynamics, each inside its own style's no-arbitrage band. No row is ever priced
+     * as the other exercise style.
+     */
+    model?: 'black-scholes-merton';
+    /** No fallback to last/mark. mid uses explicit mid, otherwise the bid/ask midpoint. */
+    priceSource: PriceSource;
+    /** Non-negative elapsed milliseconds; stale iff age strictly exceeds this threshold. */
+    maximumQuoteAgeMs: number;
+    /** Non-negative spread / bid-ask midpoint ratio; wide iff strictly greater. */
+    maximumRelativeSpread: number;
+    /** Default 1; positive safe integer ≤10,000. Distinct expiration instants, including expired ones. */
+    minimumExpiries?: number;
+    /** Default 1; positive safe integer ≤10,000; per expiration instant AND exercise style. */
+    minimumStrikesPerExpiry?: number;
+    /** Optional smaller row budget; default and hard ceiling 10,000. No silent truncation. */
+    maximumQuotes?: number;
+    /** Model rows only. Closed optional σ bracket; defaults 1e-7 and 5, hard bounds, never expanded. */
+    solver?: {
+        lowerVolatilityBound?: number;
+        upperVolatilityBound?: number;
+    };
+}
+export type OptionChainHealthInput = {
+    /** Dense, open observation records. Unconsumed provider metadata is neither traversed nor copied. */
+    quotes: readonly OptionChainHealthQuote[];
+    /** Optional dense explicit universe (≤10,000). No exchange listing universe is inferred. */
+    expectedContracts?: readonly OptionContract[];
+} & ({
+    market: OptionChainHealthModelMarket;
+    config: OptionChainHealthConfig & {
+        model: 'black-scholes-merton';
+    };
+} | {
+    market: OptionChainHealthMarket;
+    config: OptionChainHealthConfig & {
+        model?: never;
+        solver?: never;
+    };
+});
+export type OptionChainHealthIssue = 'stale' | 'future' | 'missing_timestamp' | 'missing_bid' | 'missing_ask' | 'missing_price' | 'crossed' | 'wide' | 'expired';
+export type OptionChainHealthModelStatus = 'not-requested' | 'compatible' | 'model-incompatible' | 'unsupported' | 'not-evaluated' | 'unavailable';
+export interface OptionChainHealthModelResult {
+    /** Compatibility with the specified model, NOT a verdict that a market observation is bad. */
+    status: OptionChainHealthModelStatus;
+    /**
+     * The engine this row's bounds and inverse come from under the requested dynamics — closed-form
+     * BSM for a European contract, Bjerksund–Stensland 2002 for an American one. Null when no model
+     * assessment was requested.
+     */
+    engine: 'black-scholes-merton' | 'bjerksund-stensland-2002' | null;
+    /**
+     * The style's no-arbitrage price band per underlying share, or null when not evaluable: the
+     * discounted band for a European row, the undiscounted intrinsic-to-spot/strike band for an
+     * American row.
+     */
+    bounds: {
+        lower: number;
+        upper: number;
+    } | null;
+    /** Every applicable unsupported assumption, not just the first one encountered. */
+    unsupportedReasons: ('discrete_dividends' | 'adjusted_deliverable')[];
+    impliedVolatility: number | null;
+    solver: {
+        status: 'converged' | 'not-run' | 'unavailable' | 'failed';
+        /** null when no model assessment was requested. */
+        method: 'brent' | null;
+        converged: boolean;
+        iterations: number;
+        /** Null only on success. Failed inverses never receive a guessed or supplied IV. */
+        reason: string | null;
+        /** Absolute repricing residual per share; null if no finite solve was accepted. */
+        priceResidual: number | null;
+    };
+}
+/** Pricing identity only: accounting/venue metadata is not used to scale or interpret premiums. */
+export type OptionChainHealthContract = Pick<OptionContract, 'underlying' | 'type' | 'style' | 'strike' | 'expiry' | 'expiresAt' | 'expiryConvention'>;
+export interface OptionChainHealthRow {
+    /** Input order is preserved, including duplicate observations. */
+    quoteIndex: number;
+    contract: OptionChainHealthContract;
+    timestampMs: number | null;
+    ageMs: number | null;
+    selectedPrice: number | null;
+    bid: number | null;
+    ask: number | null;
+    spread: number | null;
+    /** null for absent/crossed sides or two zero sides; the reason is in diagnostics.warnings. */
+    relativeSpread: number | null;
+    timeToExpiryYears: number;
+    issues: OptionChainHealthIssue[];
+    model: OptionChainHealthModelResult;
+    diagnostics: {
+        warnings: QuantWarning[];
+    };
+}
+export interface OptionChainHealthExpiryCoverage {
+    expiresAt: number;
+    style: OptionContract['style'];
+    expired: boolean;
+    quoteCount: number;
+    selectedPriceCount: number;
+    solvedCount: number;
+    strikes: number[];
+    callStrikes: number[];
+    putStrikes: number[];
+    /** Missing side at an observed strike, NOT proof that the exchange lists that side. */
+    missingCallStrikes: number[];
+    missingPutStrikes: number[];
+    belowMinimumStrikes: boolean;
+}
+/** Concrete report shape, directly assignable to createAnalysisArtifact's result without a cast. */
+export type OptionChainHealthReport = {
+    rows: OptionChainHealthRow[];
+    summary: {
+        quoteCount: number;
+        quotesWithIssues: number;
+        issueCounts: Record<OptionChainHealthIssue, number>;
+        modelStatusCounts: Record<OptionChainHealthModelStatus, number>;
+        solvedCount: number;
+    };
+    coverage: {
+        /** Sorted by expiration instant, then style (code-unit order); no locale or clock dependency. */
+        expiries: OptionChainHealthExpiryCoverage[];
+        expiryCount: number;
+        belowMinimumExpiries: boolean;
+        duplicateQuoteCount: number;
+        /** null means no expected universe supplied; [] means the supplied universe is covered. */
+        missingContracts: OptionChainHealthContract[] | null;
+        expectedContractCount: number | null;
+    };
+    assumptions: Assumptions<{
+        underlying: string;
+        spot?: number;
+        riskFreeRate?: number;
+        dividendYield?: number;
+        dividends: DiscreteDividend[];
+        modelAssessment: 'not-requested' | 'black-scholes-merton';
+        priceSource: PriceSource;
+        priceUnit: 'per-underlying-share';
+        impliedVolatilityUnit: 'annualized-decimal';
+        /** Each row is bounded and inverted under its own contract's exercise style. */
+        exercisePolicy: 'by-contract-style' | 'not-assessed';
+        /** Present when a model was requested: the engine each exercise style is assessed with. */
+        exerciseEngines?: {
+            european: 'black-scholes-merton';
+            american: 'bjerksund-stensland-2002';
+        };
+        quotePolicy: 'report-only';
+        coverageIdentity: 'underlying-expiresAt-style-type-strike';
+        maximumQuoteAgeMs: number;
+        maximumRelativeSpread: number;
+        minimumExpiries: number;
+        minimumStrikesPerExpiry: number;
+        maximumQuotes: number;
+        lowerVolatilityBound: number | null;
+        upperVolatilityBound: number | null;
+        maximumSolverIterations: number;
+    }>;
+    diagnostics: {
+        warnings: QuantWarning[];
+    };
+};
+/**
+ * Consolidated chain-health report. Structural malformations throw indexed InputError; absent
+ * prices/timestamps, empty chains and unavailable inverses are valid reports, never fake IVs.
+ *
+ * Omit config.model for quote health and coverage only: market needs just underlying and asOf,
+ * with no invented spot/rate/yield. Each model.status is 'not-requested', bounds/IV are null and
+ * the solver is not run. Select config.model: 'black-scholes-merton' to additionally assess
+ * compatibility under BSM dynamics, supplying market.spot and riskFreeRate (dividendYield follows
+ * the package rule: omitted is 0, echoed and disclosed). Each row is assessed under its OWN
+ * exercise style — a European row against the discounted closed-form band and inverse, an American
+ * row against the undiscounted intrinsic band and the Bjerksund–Stensland 2002 engine — never as
+ * the other style. This is quote health plus SELECTED model compatibility, NOT certification of all
+ * option pricing. Nonempty canonical DiscreteDividend schedules and adjusted deliverables report
+ * unsupported; no escrowed-dividend approximation is performed here.
+ *
+ * No clock, rate, exercise, or quote-source inference. Prices are per underlying share;
+ * multiplier and unconsumed provider fields are ignored. Stale/future/wide quotes are retained and
+ * may be inverted with their warnings attached; crossed markets are not inverted. BSM compatibility
+ * is NOT proof of quote validity, nor is incompatibility proof of a bad market observation. This
+ * report checks individual model bounds, not cross-strike/calendar static arbitrage.
+ *
+ * Controls are closed. Quote/contract/dividend observations are open and never mutated. Coverage
+ * counts all observations (including expired/unavailable), not an automatically filtered universe.
+ * Expected contracts use pricing identity; different venue/multiplier metadata does not create a
+ * second slot. A missing call/put side is only an observed-grid gap unless explicitly expected.
+ *
+ * Work: ≤10,000 quotes, ≤10,000 expected contracts, ≤1,000 dividends, bounded strings and at most
+ * 100 Brent iterations per quote. All lengths are checked before row traversal or result allocation.
+ * Rows preserve input order; coverage and missing-contract identities are sorted deterministically.
+ *
+ * @example
+ * ```ts
+ * import { option, optionChainHealth } from '@insiderfinance/totalfinance/options';
+ *
+ * const contract = option.call({
+ *   underlying: 'X', style: 'european', strike: 100,
+ *   expiry: '2027-01-01T00:00:00Z',
+ * });
+ * const report = optionChainHealth({
+ *   quotes: [{ contract, timestampMs: 1767225600000, bid: 7.9, ask: 8.1 }],
+ *   market: { underlying: 'X', spot: 100, asOf: '2026-01-01T00:00:00Z', riskFreeRate: 0, dividendYield: 0 },
+ *   config: {
+ *     model: 'black-scholes-merton', priceSource: 'mid', maximumQuoteAgeMs: 60_000,
+ *     maximumRelativeSpread: 0.1,
+ *   },
+ * });
+ * if (!report.rows[0]?.model.solver.converged) throw new Error('IV unavailable');
+ * // One-year ATM price 8 => annualized IV about 0.20086744, NOT an assumed 20%.
+ * if (Math.abs(report.rows[0].model.impliedVolatility! - 0.20086744) > 1e-7) throw new Error('Unexpected IV');
+ * if (report.coverage.expiries[0]?.missingPutStrikes[0] !== 100) throw new Error('Expected unobserved put side');
+ *
+ * const quotesOnly = optionChainHealth({
+ *   quotes: [{ contract, timestampMs: 1767225600000, bid: 9, ask: 7 }],
+ *   market: { underlying: 'X', asOf: '2026-01-01T00:00:00Z' },
+ *   config: { priceSource: 'mid', maximumQuoteAgeMs: 60_000, maximumRelativeSpread: 0.1 },
+ * });
+ * if (quotesOnly.summary.issueCounts.crossed !== 1) throw new Error('Expected crossed quote');
+ * if (quotesOnly.rows[0]?.model.status !== 'not-requested') throw new Error('No model requested');
+ * ```
+ */
+export declare function optionChainHealth(input: OptionChainHealthInput): OptionChainHealthReport;
+//# sourceMappingURL=chain-health.d.ts.map

package/modules/options/dist/chain-health.d.ts.map

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