@insiderfinance/totalfinance 0.1.0

package/modules/options/dist/payoff-kernel.js

@@ -0,0 +1,27 @@
+/**
+ * The vanilla-intrinsic kernel — the ONE source of truth for `max(S − K, 0)` / `max(K − S, 0)`
+ * (platform roadmap, "One small primitive gap is worth closing").
+ *
+ * The same tiny formula used to be written inline in the option engines, the exercise analytics, and
+ * the American IV boundary. Each copy was correct, and each copy was a place the next edit could make
+ * them disagree. They now all route here.
+ */
+/**
+ * The unchecked kernel: pure arithmetic, no validation.
+ *
+ * It exists so validation can live at the boundary WITHOUT being paid per node: the lattice engines
+ * evaluate this at every terminal (and, for American exercise, interior) node, and the FDM engine at
+ * every grid point — loops whose inputs were validated once at their own boundary. It also preserves
+ * those interior sites' exact semantics: a non-finite node value (an overflowed `u^n`) propagates as
+ * arithmetic, never as a thrown validation error the site did not have before.
+ *
+ * @internal PACKAGE-private, mirroring `blackScholesPriceUnchecked`: this module is deliberately not
+ * a package subpath and the index does not re-export it, so it never reaches the public surface or
+ * the API report. Every caller must have validated (or arithmetically produced) its inputs already.
+ */
+export function vanillaIntrinsicUnchecked(input) {
+    return input.type === 'call'
+        ? Math.max(input.underlyingPrice - input.strike, 0)
+        : Math.max(input.strike - input.underlyingPrice, 0);
+}
+//# sourceMappingURL=payoff-kernel.js.map

package/modules/options/dist/payoff-kernel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payoff-kernel.js","sourceRoot":"","sources":["../src/payoff-kernel.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAcH;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,yBAAyB,CAAC,KAA4B;IACpE,OAAO,KAAK,CAAC,IAAI,KAAK,MAAM;QAC1B,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,eAAe,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;QACnD,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC;AACxD,CAAC"}

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

@@ -0,0 +1,34 @@
+/**
+ * `@insiderfinance/totalfinance/options/payoff` — expiration payoff primitives.
+ *
+ * One deliberately small module (platform roadmap, "One small primitive gap is worth closing"): the
+ * standalone vanilla intrinsic value. Its semantics are closed and not overloaded —
+ *
+ * - it returns the **gross intrinsic value per unit**, not P&L;
+ * - it accepts no premium, quantity, multiplier, probability, volatility, or time — an unknown key
+ *   teaches (Law 12) instead of being silently ignored;
+ * - single-contract and multi-leg P&L stay where they live today: `Position.pnlAtExpiry` and
+ *   `Position.payoff` in `@insiderfinance/totalfinance/strategy`.
+ */
+import { type VanillaIntrinsicInput } from './payoff-kernel.js';
+/**
+ * Gross vanilla intrinsic value per unit: `max(underlyingPrice − strike, 0)` for a call,
+ * `max(strike − underlyingPrice, 0)` for a put.
+ *
+ * A plain number out, and nothing else in: no premium (this is not P&L), no quantity or multiplier
+ * (per unit), no volatility or time (intrinsic is model-free). `underlyingPrice` and `strike` must be
+ * finite and `>= 0` — zero is legal on either leg (a worthless underlying or a zero strike still has
+ * a well-defined intrinsic value).
+ *
+ * @example
+ * ```ts
+ * import { vanillaIntrinsic } from '@insiderfinance/totalfinance/options/payoff';
+ *
+ * vanillaIntrinsic({ type: 'call', underlyingPrice: 112, strike: 100 }); // 12
+ * vanillaIntrinsic({ type: 'put', underlyingPrice: 88, strike: 100 }); // 12
+ * vanillaIntrinsic({ type: 'put', underlyingPrice: 112, strike: 100 }); // 0
+ * ```
+ */
+export declare function vanillaIntrinsic(input: VanillaIntrinsicInput): number;
+export type { VanillaIntrinsicInput } from './payoff-kernel.js';
+//# sourceMappingURL=payoff.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"payoff.d.ts","sourceRoot":"","sources":["../src/payoff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAUH,OAAO,EAA6B,KAAK,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAiB3F;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,MAAM,CAsBrE;AAED,YAAY,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC"}

package/modules/options/dist/payoff.js

@@ -0,0 +1,60 @@
+/**
+ * `@insiderfinance/totalfinance/options/payoff` — expiration payoff primitives.
+ *
+ * One deliberately small module (platform roadmap, "One small primitive gap is worth closing"): the
+ * standalone vanilla intrinsic value. Its semantics are closed and not overloaded —
+ *
+ * - it returns the **gross intrinsic value per unit**, not P&L;
+ * - it accepts no premium, quantity, multiplier, probability, volatility, or time — an unknown key
+ *   teaches (Law 12) instead of being silently ignored;
+ * - single-contract and multi-leg P&L stay where they live today: `Position.pnlAtExpiry` and
+ *   `Position.payoff` in `@insiderfinance/totalfinance/strategy`.
+ */
+import { ErrorCode, ensureEnum, ensureKnownKeys, ensureNonNegative, requireArgumentObject, requireFiniteFields, } from '../../core/dist/index.js';
+import { vanillaIntrinsicUnchecked } from './payoff-kernel.js';
+const OPTION_TYPES = ['call', 'put'];
+const VANILLA_INTRINSIC_FIELDS = ['underlyingPrice', 'strike'];
+/** Law 12 allowlist: the two price legs plus the `type` discriminant — the field set is CLOSED. */
+const VANILLA_INTRINSIC_KEYS = ['type', ...VANILLA_INTRINSIC_FIELDS];
+const VANILLA_INTRINSIC_EXAMPLE_CALL = "vanillaIntrinsic({ type: 'call', underlyingPrice: 112, strike: 100 })";
+const VANILLA_INTRINSIC_HINTS = {
+    underlyingPrice: 'the underlying price per unit, in the same currency unit as strike',
+    strike: 'the strike price per unit, in the same currency unit as underlyingPrice',
+};
+/**
+ * Gross vanilla intrinsic value per unit: `max(underlyingPrice − strike, 0)` for a call,
+ * `max(strike − underlyingPrice, 0)` for a put.
+ *
+ * A plain number out, and nothing else in: no premium (this is not P&L), no quantity or multiplier
+ * (per unit), no volatility or time (intrinsic is model-free). `underlyingPrice` and `strike` must be
+ * finite and `>= 0` — zero is legal on either leg (a worthless underlying or a zero strike still has
+ * a well-defined intrinsic value).
+ *
+ * @example
+ * ```ts
+ * import { vanillaIntrinsic } from '@insiderfinance/totalfinance/options/payoff';
+ *
+ * vanillaIntrinsic({ type: 'call', underlyingPrice: 112, strike: 100 }); // 12
+ * vanillaIntrinsic({ type: 'put', underlyingPrice: 88, strike: 100 }); // 12
+ * vanillaIntrinsic({ type: 'put', underlyingPrice: 112, strike: 100 }); // 0
+ * ```
+ */
+export function vanillaIntrinsic(input) {
+    requireArgumentObject('vanillaIntrinsic', 'input', input);
+    // Law 12: a `premium`, `quantity`, or `strkie` key must teach, never be silently ignored.
+    ensureKnownKeys('vanillaIntrinsic', 'input', input, VANILLA_INTRINSIC_KEYS);
+    // A meaning-changing field is never coerced (design law #4): `type: 'Call'` must teach, not
+    // silently value the other leg.
+    ensureEnum(input.type, OPTION_TYPES, 'type', 'vanillaIntrinsic');
+    // PRESENCE before DOMAIN (the facade/kernel parity convention): a missing leg is named as missing,
+    // not reported as "not finite".
+    requireFiniteFields('vanillaIntrinsic', input, VANILLA_INTRINSIC_FIELDS, {
+        exampleCall: VANILLA_INTRINSIC_EXAMPLE_CALL,
+        hints: VANILLA_INTRINSIC_HINTS,
+    });
+    // `>= 0`, not `> 0`: unlike the pricing facades, a zero underlying or strike is a legal input here.
+    ensureNonNegative(input.underlyingPrice, 'underlyingPrice', 'vanillaIntrinsic', ErrorCode.InputNegativeSpot);
+    ensureNonNegative(input.strike, 'strike', 'vanillaIntrinsic', ErrorCode.InputNegativeStrike);
+    return vanillaIntrinsicUnchecked(input);
+}
+//# sourceMappingURL=payoff.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"payoff.js","sourceRoot":"","sources":["../src/payoff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,SAAS,EACT,UAAU,EACV,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,0BAAoB,CAAC;AAC5B,OAAO,EAAE,yBAAyB,EAA8B,MAAM,oBAAoB,CAAC;AAE3F,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,KAAK,CAAU,CAAC;AAE9C,MAAM,wBAAwB,GAAG,CAAC,iBAAiB,EAAE,QAAQ,CAAU,CAAC;AAExE,mGAAmG;AACnG,MAAM,sBAAsB,GAAG,CAAC,MAAM,EAAE,GAAG,wBAAwB,CAAU,CAAC;AAE9E,MAAM,8BAA8B,GAClC,uEAAuE,CAAC;AAE1E,MAAM,uBAAuB,GAA2B;IACtD,eAAe,EAAE,oEAAoE;IACrF,MAAM,EAAE,yEAAyE;CAClF,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAA4B;IAC3D,qBAAqB,CAAC,kBAAkB,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;IAC1D,0FAA0F;IAC1F,eAAe,CAAC,kBAAkB,EAAE,OAAO,EAAE,KAAK,EAAE,sBAAsB,CAAC,CAAC;IAC5E,4FAA4F;IAC5F,gCAAgC;IAChC,UAAU,CAAC,KAAK,CAAC,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,kBAAkB,CAAC,CAAC;IACjE,mGAAmG;IACnG,gCAAgC;IAChC,mBAAmB,CAAC,kBAAkB,EAAE,KAAK,EAAE,wBAAwB,EAAE;QACvE,WAAW,EAAE,8BAA8B;QAC3C,KAAK,EAAE,uBAAuB;KAC/B,CAAC,CAAC;IACH,oGAAoG;IACpG,iBAAiB,CACf,KAAK,CAAC,eAAe,EACrB,iBAAiB,EACjB,kBAAkB,EAClB,SAAS,CAAC,iBAAiB,CAC5B,CAAC;IACF,iBAAiB,CAAC,KAAK,CAAC,MAAM,EAAE,QAAQ,EAAE,kBAAkB,EAAE,SAAS,CAAC,mBAAmB,CAAC,CAAC;IAC7F,OAAO,yBAAyB,CAAC,KAAK,CAAC,CAAC;AAC1C,CAAC"}

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

@@ -0,0 +1,44 @@
+/**
+ * The Gate C reference adapter: `option.price` exposed through the `@insiderfinance/totalfinance/core/pricing`
+ * `Pricer` protocol (`docs/specs/gate-c-extension-contracts.md`).
+ *
+ * This file contains ZERO pricing mathematics — it is the existence proof that the protocol adds
+ * none (the no-second-engine law). It declares what `option.price` consumes as typed market
+ * requirements, maps satisfied observations onto the EXISTING `OptionMarket` shape, calls the
+ * EXISTING `option.price`, and returns the EXISTING `PriceResult` envelope untouched — except for
+ * one additive disclosure: an explicit-mode `diagnostics.selection` report when the caller pinned
+ * the engine (the automatic report is emitted by `engines.auto()` itself, at the routing site
+ * that owns the decision).
+ *
+ * The adapter therefore has a PROVABLE parity law: for the same contract and equivalent market,
+ * `pricer.price(...)` and `option.price(...)` agree bit-for-bit on value, Greeks, and assumptions
+ * (`packages/options/test/pricer-adapter.test.ts`).
+ */
+import { type OptionContract } from '../../core/dist/index.js';
+import { type Pricer } from '../../core/dist/pricing.js';
+import { type OptionPricingEngine } from './engines.js';
+import type { PriceResult } from './types.js';
+/** Adapter identity, reported via `definePricer` and usable in selection/diagnostics tooling. */
+export declare const OPTION_CONTRACT_PRICER_NAME = "options.option-contract";
+export interface OptionContractPricerOptions {
+    /**
+     * Explicit engine selection — the same engine objects `option.price` accepts (`engines.*` or
+     * `defineOptionPricingEngine(...)`). Omit for automatic selection via `engines.auto()`; either
+     * way the result's `diagnostics.selection` discloses who priced and why. Passing `engines.auto()`
+     * here yields an AUTOMATIC report — auto genuinely chose, and the report never pretends
+     * otherwise.
+     */
+    engine?: OptionPricingEngine;
+}
+/**
+ * Build a `Pricer<OptionContract, PriceResult>` around the EXISTING `option.price`.
+ *
+ * `optionContractPricer()` — automatic engine selection (`engines.auto()`), disclosed candidate by
+ * candidate in `diagnostics.selection`. `optionContractPricer({ engine: engines.binomial({ steps:
+ * 501 }) })` — explicit selection, disclosed as explicit. The `greeks` capability is inherited from
+ * the chosen engine's own verified capabilities, never re-asserted; `randomness` is `'none'` for
+ * every engine (see the capabilities note below — engine randomness is construction-seeded, so the
+ * wrapped engine is per-instance deterministic).
+ */
+export declare function optionContractPricer(options?: OptionContractPricerOptions): Pricer<OptionContract, PriceResult>;
+//# sourceMappingURL=pricer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pricer.d.ts","sourceRoot":"","sources":["../src/pricer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAKL,KAAK,cAAc,EACpB,MAAM,0BAAoB,CAAC;AAC5B,OAAO,EAKL,KAAK,MAAM,EAEZ,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAA0B,KAAK,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAEhF,OAAO,KAAK,EAAgB,WAAW,EAAE,MAAM,YAAY,CAAC;AAE5D,iGAAiG;AACjG,eAAO,MAAM,2BAA2B,4BAA4B,CAAC;AAWrE,MAAM,WAAW,2BAA2B;IAC1C;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,mBAAmB,CAAC;CAC9B;AAwBD;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,GAAE,2BAAgC,GACxC,MAAM,CAAC,cAAc,EAAE,WAAW,CAAC,CA2HrC"}

package/modules/options/dist/pricer.js

@@ -0,0 +1,179 @@
+/**
+ * The Gate C reference adapter: `option.price` exposed through the `@insiderfinance/totalfinance/core/pricing`
+ * `Pricer` protocol (`docs/specs/gate-c-extension-contracts.md`).
+ *
+ * This file contains ZERO pricing mathematics — it is the existence proof that the protocol adds
+ * none (the no-second-engine law). It declares what `option.price` consumes as typed market
+ * requirements, maps satisfied observations onto the EXISTING `OptionMarket` shape, calls the
+ * EXISTING `option.price`, and returns the EXISTING `PriceResult` envelope untouched — except for
+ * one additive disclosure: an explicit-mode `diagnostics.selection` report when the caller pinned
+ * the engine (the automatic report is emitted by `engines.auto()` itself, at the routing site
+ * that owns the decision).
+ *
+ * The adapter therefore has a PROVABLE parity law: for the same contract and equivalent market,
+ * `pricer.price(...)` and `option.price(...)` agree bit-for-bit on value, Greeks, and assumptions
+ * (`packages/options/test/pricer-adapter.test.ts`).
+ */
+import { ErrorCode, InputError, ensureKnownKeys, requireArgumentObject, } from '../../core/dist/index.js';
+import { definePricer, optionalObservationValue, requireObservationValue, } from '../../core/dist/pricing.js';
+import { engines, requireEngine } from './engines.js';
+import { priceOption } from './pro.js';
+/** Adapter identity, reported via `definePricer` and usable in selection/diagnostics tooling. */
+export const OPTION_CONTRACT_PRICER_NAME = 'options.option-contract';
+const PRICER_VERSION = '0.0.1';
+const FACTORY_KEYS = ['engine'];
+const PRICE_KEYS = ['instrument', 'observations', 'request'];
+// `seed` is part of the closed protocol request grammar (PricerValuationRequest) and is accepted
+// here so the randomness-'none' seed-ignoring law holds: this adapter never reads it (see the
+// capabilities note below), and refusing it as an unknown key would break the law that a 'none'
+// pricer ignores a supplied seed entirely.
+const REQUEST_KEYS = ['greeks', 'seed'];
+/**
+ * The market requirements pricing `contract` consumes, as data. `riskFreeRate` is keyed by the
+ * contract's currency, defaulting to `'USD'` exactly as the contract metadata does; `dividendYield`
+ * is OPTIONAL with the workspace-disclosed default of 0 (`assumptions.dividendModel` on the result
+ * says which model actually applied — the no-silent-economics disclosure already lives in the
+ * wrapped function, not in this adapter).
+ */
+function contractRequirements(contract) {
+    return [
+        { kind: 'valuationInstant' },
+        { kind: 'spot', symbol: contract.underlying },
+        {
+            kind: 'impliedVolatility',
+            symbol: contract.underlying,
+            strike: contract.strike,
+            expiresAt: contract.expiresAt,
+        },
+        { kind: 'riskFreeRate', currency: contract.currency ?? 'USD' },
+        { kind: 'dividendYield', symbol: contract.underlying, optional: true },
+    ];
+}
+/**
+ * Build a `Pricer<OptionContract, PriceResult>` around the EXISTING `option.price`.
+ *
+ * `optionContractPricer()` — automatic engine selection (`engines.auto()`), disclosed candidate by
+ * candidate in `diagnostics.selection`. `optionContractPricer({ engine: engines.binomial({ steps:
+ * 501 }) })` — explicit selection, disclosed as explicit. The `greeks` capability is inherited from
+ * the chosen engine's own verified capabilities, never re-asserted; `randomness` is `'none'` for
+ * every engine (see the capabilities note below — engine randomness is construction-seeded, so the
+ * wrapped engine is per-instance deterministic).
+ */
+export function optionContractPricer(options = {}) {
+    const factoryName = 'optionContractPricer';
+    requireArgumentObject(factoryName, 'options', options);
+    ensureKnownKeys(factoryName, 'options', options, FACTORY_KEYS);
+    const explicit = options.engine;
+    if (explicit !== undefined)
+        requireEngine(factoryName, explicit);
+    const engine = explicit ?? engines.auto();
+    const functionName = `${factoryName}.price`;
+    return definePricer({
+        name: OPTION_CONTRACT_PRICER_NAME,
+        version: PRICER_VERSION,
+        capabilities: {
+            greeks: engine.capabilities.greeks,
+            // 'none' for EVERY engine, including the stochastic ones (2026-08-23, second external
+            // review — PricerCapabilities.deterministic → randomness): options engines that draw
+            // (Monte Carlo, local vol) REQUIRE their seed at engine construction and echo it on the
+            // result, so the engine object this adapter wraps is a pure function of
+            // (contract, market) — its randomness was consumed when the caller built the engine, never
+            // per call. That makes repeat-call byte-identity (the 'none' law) the verifiable truth
+            // here, while a per-call `request.seed` has no engine input to flow into and is ignored
+            // (callers who want a different draw build a different engine; the engine's own
+            // `deterministic` flag keeps meaning "closed-form vs seeded method" in the options
+            // engine-contract suite).
+            randomness: 'none',
+            // The options batch paths (`@insiderfinance/totalfinance/options/batch`) are strike/vol-columnar over ONE
+            // market, not instrument-columnar over one observation set; the batch adapter is specified
+            // in the Gate C design doc and lands with a measured consumer. Claiming `batch: true` here
+            // would be unverified capability marketing.
+            batch: false,
+        },
+        supports: (instrument) => engine.supports(instrument),
+        requirements: (instrument) => {
+            requireArgumentObject(factoryName, 'instrument', instrument);
+            return contractRequirements(instrument);
+        },
+        price: (input) => {
+            requireArgumentObject(functionName, 'input', input);
+            ensureKnownKeys(functionName, 'input', input, PRICE_KEYS);
+            const { instrument, observations, request } = input;
+            requireArgumentObject(functionName, 'input.instrument', instrument);
+            if (request !== undefined) {
+                requireArgumentObject(functionName, 'input.request', request);
+                ensureKnownKeys(functionName, 'input.request', request, REQUEST_KEYS);
+                if (request.greeks !== undefined && typeof request.greeks !== 'boolean') {
+                    throw new InputError(`${functionName}: input.request.greeks must be a boolean.`, {
+                        code: ErrorCode.InputWrongType,
+                        context: { function: functionName, field: 'input.request.greeks' },
+                    });
+                }
+                if (request.seed !== undefined &&
+                    (typeof request.seed !== 'number' ||
+                        !Number.isSafeInteger(request.seed) ||
+                        request.seed < 0)) {
+                    throw new InputError(`${functionName}: input.request.seed must be a non-negative safe integer when supplied.`, {
+                        code: ErrorCode.InputOutOfRange,
+                        context: { function: functionName, field: 'input.request.seed' },
+                    });
+                }
+            }
+            // Satisfy the declared requirements — nothing more. A missing required observation throws
+            // the protocol's teaching error; an undeclared observation is structurally unreachable from
+            // here, which is exactly what the conformance kit's independence probe verifies.
+            const asOf = requireObservationValue(functionName, observations, {
+                kind: 'valuationInstant',
+            });
+            const spot = requireObservationValue(functionName, observations, {
+                kind: 'spot',
+                symbol: instrument.underlying,
+            });
+            const volatility = requireObservationValue(functionName, observations, {
+                kind: 'impliedVolatility',
+                symbol: instrument.underlying,
+                strike: instrument.strike,
+                expiresAt: instrument.expiresAt,
+            });
+            const riskFreeRate = requireObservationValue(functionName, observations, {
+                kind: 'riskFreeRate',
+                currency: instrument.currency ?? 'USD',
+            });
+            const dividendYield = optionalObservationValue(functionName, observations, {
+                kind: 'dividendYield',
+                symbol: instrument.underlying,
+            });
+            // The EXISTING market shape and the EXISTING entrypoint — the adapter maps, never re-prices.
+            const market = {
+                spot,
+                riskFreeRate,
+                volatility,
+                asOf,
+                ...(dividendYield !== undefined ? { dividendYield } : {}),
+            };
+            const result = priceOption({
+                contract: instrument,
+                market,
+                engine,
+                ...(request?.greeks !== undefined ? { greeks: request.greeks } : {}),
+            });
+            // Selection disclosure: a meta-engine (auto) reports its own automatic selection at the
+            // routing site; any result that already carries a report keeps it. Otherwise the caller
+            // pinned this engine, and the report says so — explicitly, with nothing "considered".
+            if (result.diagnostics.selection !== undefined)
+                return result;
+            return {
+                ...result,
+                diagnostics: {
+                    ...result.diagnostics,
+                    selection: {
+                        mode: 'explicit',
+                        selected: { name: engine.name, version: engine.version },
+                        reason: `caller-selected: optionContractPricer({ engine }) named "${engine.name}" explicitly.`,
+                    },
+                },
+            };
+        },
+    });
+}
+//# sourceMappingURL=pricer.js.map

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

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

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

@@ -0,0 +1,82 @@
+/**
+ * The pro API namespace `option` (spec §5.2, §5.3).
+ *
+ * Pro APIs take cohesive named request objects and always return rich `Computed` envelopes (value +
+ * assumptions + diagnostics). There is no `.explain()` here — that is a facade-only affordance;
+ * pro results are already explained. Quantitative failures are reported via
+ * `diagnostics.converged`, not thrown.
+ */
+import { type OptionContract } from '../../core/dist/index.js';
+import { callContract, european, putContract, usEquityCall, usEquityOption, usEquityPut } from './contract.js';
+import { compareEngines, type OptionPricingEngine, type PriceOptions } from './engines.js';
+import type { ImpliedVolatilityOptions, ImpliedVolatilitySolveResult } from './iv.js';
+import type { OptionMarket, PriceResult } from './types.js';
+/** Input for {@link priceOption} — ONE options-bearing object (alignment spec P3.5b). */
+export interface PriceOptionInput extends PriceOptions {
+    contract: OptionContract;
+    /** Market snapshot. `asOf` is required on the market; the clock is never read. */
+    market: OptionMarket;
+    /** Engine override; defaults to {@link engines.auto} (European → BSM, American → lattice/approx). */
+    engine?: OptionPricingEngine;
+}
+export declare function priceOption(input: PriceOptionInput): PriceResult;
+/**
+ * Solve implied volatility from `market.price`, returning a rich envelope with diagnostics. Routes on
+ * contract style and on whether an engine is named (WS4.2): a European contract with no engine
+ * inverts closed-form Black–Scholes–Merton (`method` chooses `auto`/`brent`/`newton`/`halley`/
+ * `householder`, `fallback` and `failFast` shape it); an American contract, or any contract with an
+ * `engine`, inverts that engine (default Bjerksund–Stensland 2002 for American) over a safeguarded
+ * Brent bracket, where the closed-form knobs do not apply and are refused. The engine and
+ * actually-used method are reported in `diagnostics`.
+ */
+/** Input for {@link impliedVolatilityOption} — one object: `{ contract, market, ...solver options }`. */
+export interface ImpliedVolatilityOptionInput extends ImpliedVolatilityOptions {
+    contract: OptionContract;
+    market: OptionMarket;
+    /**
+     * Engine to invert numerically. An American contract always inverts an engine (default
+     * `engines.bjerksundStensland2002()`); a European contract inverts closed-form
+     * Black–Scholes–Merton unless an engine is named here, in which case THAT engine is inverted —
+     * e.g. a lattice for discrete dividends, or a custom model. `method`/`fallback`/`failFast` belong
+     * to the closed-form route and are refused alongside an engine.
+     */
+    engine?: OptionPricingEngine;
+}
+export declare function impliedVolatilityOption(input: ImpliedVolatilityOptionInput): ImpliedVolatilitySolveResult;
+/**
+ * The `option` namespace combines contract builders with pro pricing:
+ *   - `option.call(...)` / `option.put(...)` build contracts,
+ *   - `option.price({ contract, market, engine? })` prices them,
+ *   - `option.impliedVolatility({ contract, market, engine? })` inverts a price,
+ *   - `option.compareEngines({ contract, market, options? })` benchmarks engines against each other.
+ *
+ * @example
+ * ```ts
+ * import { market, option } from '@insiderfinance/totalfinance/options';
+ *
+ * const contract = option.usEquityCall({ underlying: 'AAPL', strike: 200, expiry: '2026-09-18' });
+ * const result = option.price({
+ *   contract,
+ *   market: market({ spot: 195.3, riskFreeRate: 0.045, volatility: 0.24, asOf: '2026-07-20T10:30:00-04:00' }),
+ * });
+ * result.value;          // premium per share
+ * result.greeks?.delta;  // engine-reported Greeks
+ * const solved = option.impliedVolatility({
+ *   contract,
+ *   market: market({ spot: 195.3, riskFreeRate: 0.045, price: 4.1, asOf: '2026-07-20T10:30:00-04:00' }),
+ * });
+ * solved.diagnostics.converged; // check before trusting solved.value
+ * ```
+ */
+export declare const option: {
+    readonly call: typeof callContract;
+    readonly put: typeof putContract;
+    readonly usEquityCall: typeof usEquityCall;
+    readonly usEquityPut: typeof usEquityPut;
+    readonly usEquityOption: typeof usEquityOption;
+    readonly european: typeof european;
+    readonly price: typeof priceOption;
+    readonly impliedVolatility: typeof impliedVolatilityOption;
+    readonly compareEngines: typeof compareEngines;
+};
+//# sourceMappingURL=pro.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pro.d.ts","sourceRoot":"","sources":["../src/pro.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAGL,KAAK,cAAc,EAIpB,MAAM,0BAAoB,CAAC;AAE5B,OAAO,EACL,YAAY,EACZ,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,cAAc,EACd,WAAW,EACZ,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,cAAc,EAGd,KAAK,mBAAmB,EACxB,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,wBAAwB,EAAE,4BAA4B,EAAE,MAAM,SAAS,CAAC;AACtF,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAW5D,yFAAyF;AACzF,MAAM,WAAW,gBAAiB,SAAQ,YAAY;IACpD,QAAQ,EAAE,cAAc,CAAC;IACzB,kFAAkF;IAClF,MAAM,EAAE,YAAY,CAAC;IACrB,qGAAqG;IACrG,MAAM,CAAC,EAAE,mBAAmB,CAAC;CAC9B;AAuED,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,WAAW,CAwBhE;AAED;;;;;;;;GAQG;AACH,yGAAyG;AACzG,MAAM,WAAW,4BAA6B,SAAQ,wBAAwB;IAC5E,QAAQ,EAAE,cAAc,CAAC;IACzB,MAAM,EAAE,YAAY,CAAC;IACrB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,mBAAmB,CAAC;CAC9B;AAID,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,4BAA4B,GAClC,4BAA4B,CAyD9B;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,MAAM;;;;;;;;;;CAUT,CAAC"}

package/modules/options/dist/pro.js

@@ -0,0 +1,177 @@
+/**
+ * The pro API namespace `option` (spec §5.2, §5.3).
+ *
+ * Pro APIs take cohesive named request objects and always return rich `Computed` envelopes (value +
+ * assumptions + diagnostics). There is no `.explain()` here — that is a facade-only affordance;
+ * pro results are already explained. Quantitative failures are reported via
+ * `diagnostics.converged`, not thrown.
+ */
+import { InputError, ErrorCode, UnsupportedError, ensureKnownKeys, requireArgumentObject, } from '../../core/dist/index.js';
+import { americanImpliedVolatility, engineImpliedVolatility } from './american-iv.js';
+import { callContract, european, putContract, usEquityCall, usEquityOption, usEquityPut, } from './contract.js';
+import { impliedVolatilityContract } from './engine-bsm.js';
+import { compareEngines, engines, requireEngine, } from './engines.js';
+const DEFAULT_IV_CONFIG = { name: 'black-scholes-merton', useDividends: true };
+/**
+ * The default engine auto-selects by contract (spec §9.3 / WS4.1): European contracts price with the
+ * closed-form Black–Scholes–Merton model — byte-identical to the prior default — while American
+ * contracts now route to the appropriate lattice/closed-form approximation instead of throwing.
+ */
+const defaultEngine = engines.auto();
+/**
+ * Price a contract. ONE object input — `option.price({ contract, market, engine?, greeks?,
+ * extendedGreeks? })` — so requesting per-call options never requires a positional
+ * `undefined` hole (spec P3.5b; the positional form is deleted, pre-release). `greeks: false`
+ * flows to the engine: a Monte-Carlo engine skips its Greek budget, and the result's `greeks`
+ * is then absent rather than fabricated.
+ */
+const PRICE_INPUT_KEYS = ['contract', 'market', 'engine', 'greeks', 'extendedGreeks'];
+/**
+ * When-present ladders for the pro option shape (the 350c2796 ruling): `engine: null` used to
+ * coalesce into the default engine — the caller thought THEIR engine priced — and a truthy-string
+ * flag silently toggled greeks or the failFast path.
+ */
+function requirePriceOptionLadders(functionName, input) {
+    if (input['engine'] === null) {
+        throw new InputError(`${functionName}: engine must not be null — omit the field to use the auto default. Received null.`, { code: ErrorCode.InputWrongType, context: { field: 'engine' } });
+    }
+    const engineValue = input['engine'];
+    if (engineValue !== undefined && (engineValue === null || typeof engineValue !== 'object')) {
+        throw new InputError(`${functionName}: engine must be a pricing engine object when provided — omit the field to use the auto default. Received ${engineValue === null ? 'null' : typeof engineValue}.`, { code: ErrorCode.InputWrongType, context: { field: 'engine' } });
+    }
+    const methodValue = input['method'];
+    if (methodValue !== undefined &&
+        methodValue !== 'auto' &&
+        methodValue !== 'brent' &&
+        methodValue !== 'newton' &&
+        methodValue !== 'halley' &&
+        methodValue !== 'householder') {
+        throw new InputError(`${functionName}: method must be 'auto' | 'brent' | 'newton' | 'halley' | 'householder' when provided. Received ${methodValue === null ? 'null' : JSON.stringify(methodValue)}.`, { code: ErrorCode.InputInvalidEnum, context: { field: 'method' } });
+    }
+    const fallbackValue = input['fallback'];
+    if (fallbackValue !== undefined && typeof fallbackValue !== 'boolean') {
+        throw new InputError(`${functionName}: fallback must be a boolean when provided. Received ${fallbackValue === null ? 'null' : typeof fallbackValue}.`, { code: ErrorCode.InputWrongType, context: { field: 'fallback' } });
+    }
+    for (const flag of ['greeks', 'extendedGreeks', 'failFast']) {
+        const value = input[flag];
+        if (value !== undefined && typeof value !== 'boolean') {
+            throw new InputError(`${functionName}: ${flag} must be a boolean when provided. Received ${value === null ? 'null' : typeof value}.`, { code: ErrorCode.InputWrongType, context: { field: flag } });
+        }
+    }
+    for (const field of ['confidence', 'boundaryPoints']) {
+        const value = input[field];
+        if (value !== undefined && (typeof value !== 'number' || !Number.isFinite(value))) {
+            throw new InputError(`${functionName}: ${field} must be a finite number when provided. Received ${value === null ? 'null' : typeof value}.`, { code: ErrorCode.InputWrongType, context: { field } });
+        }
+    }
+}
+export function priceOption(input) {
+    requireArgumentObject('option.price', 'input', input);
+    requirePriceOptionLadders('option.price', input);
+    // Law 12: a misspelled option (`greek: false`) must teach, never silently compute Greeks anyway.
+    ensureKnownKeys('option.price', 'input', input, PRICE_INPUT_KEYS);
+    const { contract, market, engine, ...options } = input;
+    requireArgumentObject('option.price', 'input.contract', contract);
+    requireArgumentObject('option.price', 'input.market', market);
+    const chosen = engine ?? defaultEngine;
+    // A non-engine value would crash as `chosen.supports is not a function` — teach instead.
+    requireEngine('option.price', chosen);
+    // The framework enforces `supports()` so every engine — built-in, custom, or the auto default —
+    // fails the same way on an unsupported contract, rather than relying on each engine to self-police.
+    if (!chosen.supports(contract)) {
+        throw new UnsupportedError(`option.price: Engine "${chosen.name}" does not support this contract ` +
+            `(style "${contract.style}", type "${contract.type}").`, {
+            code: ErrorCode.EngineUnsupportedContract,
+            context: { engine: chosen.name, style: contract.style, type: contract.type },
+        });
+    }
+    return chosen.price({ contract, market, options });
+}
+const IV_INPUT_KEYS = ['contract', 'market', 'method', 'fallback', 'failFast', 'engine'];
+export function impliedVolatilityOption(input) {
+    requireArgumentObject('option.impliedVolatility', 'input', input);
+    requirePriceOptionLadders('option.impliedVolatility', input);
+    ensureKnownKeys('option.impliedVolatility', 'input', input, IV_INPUT_KEYS);
+    const { contract, market, engine, ...options } = input;
+    requireArgumentObject('option.impliedVolatility', 'input.contract', contract);
+    requireArgumentObject('option.impliedVolatility', 'input.market', market);
+    const inverting = contract.style === 'american' || engine !== undefined;
+    if (inverting) {
+        // Law 12: an engine route inverts the ENGINE over a safeguarded Brent bracket — there is no
+        // closed-form derivative to run Newton/Halley/Householder on, and no second method to fall back
+        // to or fail fast between. Accepting `method`/`fallback`/`failFast` here and dropping them on the
+        // floor would answer a question the caller did not ask (and read as "newton ran"), so say so.
+        const ignored = ['method', 'fallback', 'failFast'].filter((key) => options[key] !== undefined);
+        if (ignored.length > 0) {
+            const named = `${ignored.map((k) => `"${k}"`).join(', ')} ${ignored.length === 1 ? 'is' : 'are'}`;
+            throw new UnsupportedError(contract.style === 'american'
+                ? `option.impliedVolatility: ${named} not supported for an AMERICAN contract — that route ` +
+                    'inverts an American pricing engine over a safeguarded Brent bracket, so solver-method ' +
+                    'selection does not apply. It honors "engine" (default engines.bjerksundStensland2002(); ' +
+                    'pass e.g. engines.binomial({ variant: "leisen-reimer" }) for discrete dividends). ' +
+                    'Method selection applies to EUROPEAN contracts, which invert closed-form Black–Scholes–Merton.'
+                : `option.impliedVolatility: ${named} not supported when an "engine" is named — that route ` +
+                    `inverts engine "${engine.name}" over a safeguarded Brent bracket, so solver-method ` +
+                    'selection does not apply. Omit "engine" to invert closed-form Black–Scholes–Merton with ' +
+                    'the method suite, or omit the solver knobs to invert the engine.', {
+                code: ErrorCode.EngineUnsupportedContract,
+                context: {
+                    function: 'option.impliedVolatility',
+                    style: contract.style,
+                    ignored,
+                    honored: ['engine'],
+                },
+            });
+        }
+        if (contract.style === 'american')
+            return americanImpliedVolatility({
+                contract,
+                market,
+                options: engine ? { engine } : {},
+            });
+        return engineImpliedVolatility({
+            functionName: 'option.impliedVolatility',
+            contract,
+            market,
+            engine: engine,
+        });
+    }
+    return impliedVolatilityContract(DEFAULT_IV_CONFIG, contract, market, options);
+}
+/**
+ * The `option` namespace combines contract builders with pro pricing:
+ *   - `option.call(...)` / `option.put(...)` build contracts,
+ *   - `option.price({ contract, market, engine? })` prices them,
+ *   - `option.impliedVolatility({ contract, market, engine? })` inverts a price,
+ *   - `option.compareEngines({ contract, market, options? })` benchmarks engines against each other.
+ *
+ * @example
+ * ```ts
+ * import { market, option } from '@insiderfinance/totalfinance/options';
+ *
+ * const contract = option.usEquityCall({ underlying: 'AAPL', strike: 200, expiry: '2026-09-18' });
+ * const result = option.price({
+ *   contract,
+ *   market: market({ spot: 195.3, riskFreeRate: 0.045, volatility: 0.24, asOf: '2026-07-20T10:30:00-04:00' }),
+ * });
+ * result.value;          // premium per share
+ * result.greeks?.delta;  // engine-reported Greeks
+ * const solved = option.impliedVolatility({
+ *   contract,
+ *   market: market({ spot: 195.3, riskFreeRate: 0.045, price: 4.1, asOf: '2026-07-20T10:30:00-04:00' }),
+ * });
+ * solved.diagnostics.converged; // check before trusting solved.value
+ * ```
+ */
+export const option = {
+    call: callContract,
+    put: putContract,
+    usEquityCall,
+    usEquityPut,
+    usEquityOption,
+    european,
+    price: priceOption,
+    impliedVolatility: impliedVolatilityOption,
+    compareEngines,
+};
+//# sourceMappingURL=pro.js.map