@insiderfinance/totalfinance 0.1.0

package/modules/options/dist/mc/core.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Shared Monte-Carlo machinery for the option path-pricers (spec §8.6, §9.3).
+ *
+ * This is the single estimator the European MC engine, the stochastic-vol models, and the exotic
+ * engines all build on. It is model-agnostic: the caller supplies a `payoff(z)` over a vector of
+ * `dimensions` standard normals and (optionally) a control variate with a known mean. The estimator owns
+ * the sampling discipline:
+ *
+ *   • **pseudo** — a seeded PRNG (mulberry32 / xoshiro128**), optional antithetic variates;
+ *   • **QMC** — Sobol / Halton low-discrepancy points mapped through the inverse normal CDF, with an
+ *     optional Brownian-bridge re-ordering so the best-distributed dimensions carry the path's
+ *     large-scale variance.
+ *
+ * Every estimate carries its standard error, confidence interval, path count, and the echoed seed —
+ * Monte-Carlo uncertainty is reported, never hidden (design laws #4, and "all stochastic APIs accept
+ * and echo seed").
+ */
+import { type QuantWarning } from '../../../core/dist/index.js';
+/** Sampling strategy for a Monte-Carlo estimate. */
+export type MonteCarloMethod = 'pseudo' | 'sobol' | 'halton';
+/** Pseudo-random generator choice for `method: 'pseudo'`. */
+export type MonteCarloRandomNumberGenerator = 'mulberry32' | 'xoshiro128';
+/** Variance-reduction techniques actually applied to an estimate (echoed for reproducibility). */
+export interface VarianceReduction {
+    antithetic: boolean;
+    controlVariate: boolean;
+    brownianBridge: boolean;
+}
+/** The diagnostics block shared by every Monte-Carlo result. */
+export interface MonteCarloStatistics {
+    /**
+     * Standard error of the mean estimate — `null` for the QUASI-random methods (`sobol`, `halton`).
+     *
+     * The sample-variance formula `√(s²/n)` assumes independent draws. A low-discrepancy sequence is
+     * deterministic and negatively correlated by construction, so that formula does not estimate its
+     * error: at 16k Sobol points on a European call it overstated the true deviation by ~75×, and a
+     * confidence interval built from it was neither a confidence nor an interval. QMC error is
+     * estimated by RANDOMIZING the sequence (scrambling/shifting) and taking the variance ACROSS
+     * independent randomizations — which this estimator does not do, so it reports `null` and says so.
+     */
+    standardError: number | null;
+    /** Confidence interval at the requested level (default 95%); `null` whenever `standardError` is. */
+    confidenceInterval: [number, number] | null;
+    /** Number of paths actually evaluated (antithetic pairs count as one path). */
+    paths: number;
+    /** The seed, echoed for reproducibility. */
+    seed: number;
+    /** The sampling method actually used (may differ from the request if QMC fell back to pseudo). */
+    method: MonteCarloMethod;
+    /** Which variance-reduction techniques were applied. */
+    varianceReduction: VarianceReduction;
+}
+/** Options shared by every Monte-Carlo pricer. */
+export interface MonteCarloSamplingOptions {
+    /** Number of paths (antithetic pairs when `antithetic`). Default 50_000. */
+    paths?: number;
+    /** Seed — required and echoed for reproducibility. */
+    seed: number;
+    /** Sampling method (default `'pseudo'`). */
+    method?: MonteCarloMethod;
+    /** Antithetic variates (pseudo only; ignored for QMC). Default `true`. */
+    antithetic?: boolean;
+    /** Brownian-bridge path ordering (QMC only; concentrates variance in the leading dimensions). */
+    brownianBridge?: boolean;
+    /** Confidence level for the interval (default 0.95). */
+    confidence?: number;
+    /** PRNG for `method: 'pseudo'` (default `'mulberry32'`). */
+    randomNumberGenerator?: MonteCarloRandomNumberGenerator;
+}
+/** The raw estimate returned by {@link monteCarloEstimate}, before it is wrapped in a pricing envelope. */
+export interface MonteCarloEstimate extends MonteCarloStatistics {
+    value: number;
+    /** Whether the estimate is trustworthy (finite value and standard error). */
+    converged: boolean;
+    /** Structured warnings (e.g. a QMC dimension fallback). */
+    warnings: QuantWarning[];
+}
+/** A control variate: a per-path quantity `fn(z)` with a known expectation `mean`. */
+export interface ControlVariate {
+    estimate: (normalDraws: number[]) => number;
+    mean: number;
+}
+/** One complete request to the model-agnostic Monte-Carlo estimator. */
+export interface MonteCarloEstimateInput {
+    dimensions: number;
+    payoff: (normalDraws: number[]) => number;
+    options: MonteCarloSamplingOptions;
+    controlVariate?: ControlVariate | undefined;
+    /** Diagnostic label used in validation errors. */
+    label?: string | undefined;
+}
+/**
+ * Validate a Monte-Carlo sampling budget before an engine or estimator captures it.
+ *
+ * Kept in the internal MC module so factory adapters and the estimator share one source of truth
+ * for path, dimension, and product bounds without adding another public package export.
+ */
+export declare function validateMonteCarloSamplingOptions(dimensions: number, options: MonteCarloSamplingOptions, functionName: string): void;
+/**
+ * Estimate `E[payoff(Z)]` where `Z` is a vector of `dimensions` standard normals, with online mean/variance,
+ * optional antithetic sampling, an optional control variate, and pseudo or quasi-random sampling.
+ */
+export declare function monteCarloEstimate(input: MonteCarloEstimateInput): MonteCarloEstimate;
+/**
+ * A geometric-Brownian-motion path from `steps` standard normals: `S[0..steps]` with
+ * `S[k+1] = S[k]·exp((r − q − ½σ²)·dt + σ·√dt·z[k])`, `dt = T/steps`. Exact (no Euler discretisation
+ * error) — GBM has lognormal increments at any step size.
+ *
+ * Expert kernel form (model-subpath surface) — the curated root surface is {@link gbm.path}.
+ */
+export interface GbmPathInput {
+    spot: number;
+    riskFreeRate: number;
+    dividendYield: number;
+    volatility: number;
+    timeToExpiryYears: number;
+    shocks: number[];
+}
+/** The raw path math with NO ladder — see {@link gbmTerminalUnchecked} for why it exists. */
+export declare function gbmPathUnchecked(input: GbmPathInput): Float64Array;
+export declare function gbmPath(input: GbmPathInput): Float64Array;
+/**
+ * The terminal GBM price from a single standard normal — `gbmPath` specialised to one step.
+ *
+ * Expert kernel form (model-subpath surface) — the curated root surface is {@link gbm.terminal}.
+ */
+export interface GbmTerminalInput {
+    spot: number;
+    riskFreeRate: number;
+    dividendYield: number;
+    volatility: number;
+    timeToExpiryYears: number;
+    shock: number;
+}
+/**
+ * The raw GBM math with NO ladder — for callers that validated once at their own boundary and then
+ * sample in a loop (`monteCarloEuropean`, the exotics path engines). Deliberately NOT re-exported
+ * from any public entrypoint: per-sample validation in a Monte-Carlo loop is the exact cost spec
+ * 3B.1b forbids, and an unchecked kernel on the public surface would be an API.
+ */
+export declare function gbmTerminalUnchecked(input: GbmTerminalInput): number;
+export declare function gbmTerminal(input: GbmTerminalInput): number;
+/**
+ * The geometric-Brownian-motion namespace — the grouped surface over the flat `gbm*` kernels.
+ * `gbm.path` / `gbm.terminal` are the same functions; prefer the namespace over the deprecated flats.
+ */
+export declare const gbm: {
+    readonly path: typeof gbmPath;
+    readonly terminal: typeof gbmTerminal;
+};
+//# sourceMappingURL=core.d.ts.map

package/modules/options/dist/mc/core.d.ts.map

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

package/modules/options/dist/mc/core.js

@@ -0,0 +1,319 @@
+/**
+ * Shared Monte-Carlo machinery for the option path-pricers (spec §8.6, §9.3).
+ *
+ * This is the single estimator the European MC engine, the stochastic-vol models, and the exotic
+ * engines all build on. It is model-agnostic: the caller supplies a `payoff(z)` over a vector of
+ * `dimensions` standard normals and (optionally) a control variate with a known mean. The estimator owns
+ * the sampling discipline:
+ *
+ *   • **pseudo** — a seeded PRNG (mulberry32 / xoshiro128**), optional antithetic variates;
+ *   • **QMC** — Sobol / Halton low-discrepancy points mapped through the inverse normal CDF, with an
+ *     optional Brownian-bridge re-ordering so the best-distributed dimensions carry the path's
+ *     large-scale variance.
+ *
+ * Every estimate carries its standard error, confidence interval, path count, and the echoed seed —
+ * Monte-Carlo uncertainty is reported, never hidden (design laws #4, and "all stochastic APIs accept
+ * and echo seed").
+ */
+import { ErrorCode, InputError, warning, WarningCode, requireArgumentArray, requireArgumentObject, requireFiniteFields, } from '../../../core/dist/index.js';
+import { SOBOL_MAX_DIMENSIONS, brownianBridge, haltonSequence, mulberry32, normalInverseCdf, normalSample, sobolSequence, xoshiro128ss, } from '../../../math/dist/index.js';
+/** Halton supports the first 25 primes as bases. */
+const HALTON_MAX_DIM = 25;
+/** Keep mapped uniforms strictly inside (0, 1) so `normalInverseCdf` never returns ±∞ (Sobol emits exact 0). */
+const U_EPS = 1e-12;
+/**
+ * The most paths one estimate will run (2026-08-23 review, P0 "unbounded work" — a reviewer-named
+ * case): `Number.isInteger(1e308)` is `true`, so the old check admitted a path budget the loop could
+ * never finish, and above 2^53 the loop counter stops advancing — a literal hang. Even at ONE
+ * dimension a path costs a normal draw (~37 ns measured) plus the payoff, so 10^7 paths is already
+ * ~0.5 s before any model work; standard error ∝ 1/√n gains only 3× per extra decade.
+ */
+const MAX_MC_PATHS = 10_000_000;
+/**
+ * The most path-dimensions (paths × dimensions normal draws) one estimate will run (2026-08-23
+ * review, P0): the two factors multiply into the real workload — 10^7 paths of a 1,000-step path
+ * simulation is 10^10 draws, hours — so each being under its own cap proves nothing. 5×10^7 draws is
+ * ~2 s (measured ~37 ns/draw) before the payoff runs; the QMC methods also MATERIALIZE the whole
+ * `(paths + 1) × dimensions` point matrix, which this cap keeps inside the low-discrepancy
+ * generators' own 2^26-cell allocation bound.
+ */
+const MAX_MC_PATH_DIMENSIONS = 50_000_000;
+/** Valid runtime enum values — unknown ones throw rather than silently defaulting. */
+const MC_METHODS = ['pseudo', 'sobol', 'halton'];
+const MC_RNGS = ['mulberry32', 'xoshiro128'];
+function rngFactory(kind) {
+    return kind === 'xoshiro128' ? xoshiro128ss : mulberry32;
+}
+/**
+ * Validate a Monte-Carlo sampling budget before an engine or estimator captures it.
+ *
+ * Kept in the internal MC module so factory adapters and the estimator share one source of truth
+ * for path, dimension, and product bounds without adding another public package export.
+ */
+export function validateMonteCarloSamplingOptions(dimensions, options, functionName) {
+    if (!Number.isFinite(options.seed)) {
+        throw new InputError(`${functionName}: seed must be a finite number, got ${options.seed}.`, {
+            code: ErrorCode.InputNotFinite,
+            context: { seed: options.seed },
+        });
+    }
+    // Safe integer (2026-08-23 review, P0): dimensions sizes the per-path draw arrays; its true scale
+    // bound is the paths × dimensions product below.
+    if (!Number.isSafeInteger(dimensions) || dimensions < 1) {
+        throw new InputError(`${functionName}: dimension must be a positive integer, got ${dimensions}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { dimensions },
+        });
+    }
+    const paths = options.paths ?? 50_000;
+    // Safe integer AND a work cap (2026-08-23 review, P0, reviewer-named): see MAX_MC_PATHS.
+    if (!Number.isSafeInteger(paths) || paths < 2 || paths > MAX_MC_PATHS) {
+        throw new InputError(`${functionName}: paths must be an integer in [2, ${MAX_MC_PATHS.toLocaleString('en-US')}] — every path draws ${dimensions} normal(s) (~37 ns each) and evaluates the payoff, so the cap is already sub-second-to-seconds of synchronous work, and standard error ∝ 1/√n gains only 3× per extra decade. Received ${paths}.\n  e.g. { paths: 100_000, seed: 42 }`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { paths, max: MAX_MC_PATHS },
+        });
+    }
+    // The PRODUCT paths × dimensions is the number of normal draws — and, for the QMC methods, the
+    // materialized point matrix — so bound it even when each factor alone is under its cap
+    // (2026-08-23 review, P0: multiplying counts must be bounded together). See MAX_MC_PATH_DIMENSIONS.
+    if (paths * dimensions > MAX_MC_PATH_DIMENSIONS) {
+        throw new InputError(`${functionName}: paths × dimensions must not exceed ${MAX_MC_PATH_DIMENSIONS.toLocaleString('en-US')} — the product is the total normal-draw workload (~2 s at the cap, measured ~37 ns/draw) and, for QMC, the materialized point matrix. Received ${paths} × ${dimensions} = ${(paths * dimensions).toLocaleString('en-US')}; reduce paths or the path resolution (steps/averaging points) that sets dimensions.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { paths, dimensions, maxPathDimensions: MAX_MC_PATH_DIMENSIONS },
+        });
+    }
+    const confidence = options.confidence ?? 0.95;
+    if (!(confidence > 0 && confidence < 1)) {
+        throw new InputError(`${functionName}: confidence must be in (0, 1), got ${confidence}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { confidence },
+        });
+    }
+    // Reject unknown enum values rather than silently treating them as Halton / mulberry32 — these
+    // options often come from JSON/config, so a typo must fail loudly (design law #4).
+    if (options.method !== undefined && !MC_METHODS.includes(options.method)) {
+        throw new InputError(`${functionName}: method must be one of ${MC_METHODS.join(', ')}; got "${options.method}".`, { code: ErrorCode.InputInvalidEnum, context: { method: options.method } });
+    }
+    if (options.randomNumberGenerator !== undefined &&
+        !MC_RNGS.includes(options.randomNumberGenerator)) {
+        throw new InputError(`${functionName}: randomNumberGenerator must be one of ${MC_RNGS.join(', ')}; got "${options.randomNumberGenerator}".`, {
+            code: ErrorCode.InputInvalidEnum,
+            context: { randomNumberGenerator: options.randomNumberGenerator },
+        });
+    }
+    if (options.brownianBridge !== undefined && typeof options.brownianBridge !== 'boolean') {
+        throw new InputError(`${functionName}: brownianBridge must be a boolean when provided. Received ${options.brownianBridge === null ? 'null' : typeof options.brownianBridge}.`, {
+            code: ErrorCode.InputWrongType,
+            context: { function: functionName, field: 'brownianBridge' },
+        });
+    }
+    if (options.antithetic !== undefined && typeof options.antithetic !== 'boolean') {
+        throw new InputError(`${functionName}: antithetic must be a boolean when provided. Received ${options.antithetic === null ? 'null' : typeof options.antithetic}.`, {
+            code: ErrorCode.InputWrongType,
+            context: { function: functionName, field: 'antithetic' },
+        });
+    }
+}
+/** Map a low-discrepancy point to standard normals, optionally Brownian-bridge re-ordered. */
+function pointToNormals(point, bridge) {
+    const z = new Array(point.length);
+    for (let i = 0; i < point.length; i++) {
+        const u = Math.min(1 - U_EPS, Math.max(U_EPS, point[i]));
+        z[i] = normalInverseCdf(u);
+    }
+    if (!bridge || z.length === 1)
+        return z;
+    // Build a Brownian path on a unit grid from the (significance-ordered) normals, then return its
+    // increments — these are the per-step N(0,1) draws in time order. The leading QMC dimensions now
+    // control the path's coarse shape, which is where QMC's low discrepancy buys the most.
+    const W = brownianBridge(z, 1);
+    const inc = new Array(z.length);
+    for (let k = 0; k < z.length; k++)
+        inc[k] = W[k + 1] - W[k];
+    return inc;
+}
+/**
+ * Estimate `E[payoff(Z)]` where `Z` is a vector of `dimensions` standard normals, with online mean/variance,
+ * optional antithetic sampling, an optional control variate, and pseudo or quasi-random sampling.
+ */
+export function monteCarloEstimate(input) {
+    const { dimensions, payoff, options, controlVariate: control, label: fn = 'monteCarlo' } = input;
+    requireArgumentObject(fn, 'options', options);
+    validateMonteCarloSamplingOptions(dimensions, options, fn);
+    const paths = options.paths ?? 50_000;
+    const confidence = options.confidence ?? 0.95;
+    const z = normalInverseCdf(0.5 + confidence / 2);
+    const warnings = [];
+    let method = options.method ?? 'pseudo';
+    // QMC dimension limits: fall back to pseudo with a reported warning rather than silently degrade.
+    if (method === 'sobol' && dimensions > SOBOL_MAX_DIMENSIONS) {
+        warnings.push(warning(WarningCode.MonteCarloQuasiMonteCarloDimensionFallback, `Sobol supports at most ${SOBOL_MAX_DIMENSIONS} dimensions; ${dimensions} requested — falling back to pseudo-random sampling.`, 'warn', { requested: 'sobol', dimensions, max: SOBOL_MAX_DIMENSIONS }));
+        method = 'pseudo';
+    }
+    else if (method === 'halton' && dimensions > HALTON_MAX_DIM) {
+        warnings.push(warning(WarningCode.MonteCarloQuasiMonteCarloDimensionFallback, `Halton supports at most ${HALTON_MAX_DIM} dimensions; ${dimensions} requested — falling back to pseudo-random sampling.`, 'warn', { requested: 'halton', dimensions, max: HALTON_MAX_DIM }));
+        method = 'pseudo';
+    }
+    // Resolve variance-reduction flags after any QMC fallback so diagnostics describe what actually ran.
+    const bridge = method !== 'pseudo' && (options.brownianBridge ?? false);
+    const antithetic = method === 'pseudo' && (options.antithetic ?? true);
+    const hasControl = control !== undefined;
+    // Online sums for the mean, variance, and (with a control) the control's variance and covariance.
+    let n = 0;
+    let sY = 0;
+    let sYY = 0;
+    let sX = 0;
+    let sXX = 0;
+    let sXY = 0;
+    const accumulate = (y, x) => {
+        if (!Number.isFinite(y) || (hasControl && !Number.isFinite(x))) {
+            throw new InputError(`${fn}: payoff produced a non-finite sample (${y}); a NaN/∞ draw must not surface as a successful estimate.`, { code: ErrorCode.InputNotFinite, context: { value: y } });
+        }
+        n++;
+        sY += y;
+        sYY += y * y;
+        if (hasControl) {
+            sX += x;
+            sXX += x * x;
+            sXY += x * y;
+        }
+    };
+    if (method === 'pseudo') {
+        const randomNumberGenerator = rngFactory(options.randomNumberGenerator)(options.seed);
+        const zv = new Array(dimensions);
+        const zn = new Array(dimensions);
+        for (let i = 0; i < paths; i++) {
+            for (let d = 0; d < dimensions; d++) {
+                zv[d] = normalSample(randomNumberGenerator);
+                zn[d] = -zv[d];
+            }
+            if (antithetic) {
+                accumulate(0.5 * (payoff(zv) + payoff(zn)), hasControl ? 0.5 * (control.estimate(zv) + control.estimate(zn)) : 0);
+            }
+            else {
+                accumulate(payoff(zv), hasControl ? control.estimate(zv) : 0);
+            }
+        }
+    }
+    else {
+        const points = method === 'sobol'
+            ? sobolSequence(paths + 1, dimensions).slice(1)
+            : haltonSequence(paths, dimensions, { start: 1 });
+        for (let i = 0; i < points.length; i++) {
+            const zd = pointToNormals(points[i], bridge);
+            accumulate(payoff(zd), hasControl ? control.estimate(zd) : 0);
+        }
+    }
+    const meanY = sY / n;
+    const varY = n > 1 ? (sYY - n * meanY * meanY) / (n - 1) : NaN;
+    let value = meanY;
+    let resVar = varY;
+    let usedControl = false;
+    if (hasControl && n > 1) {
+        const meanX = sX / n;
+        const varX = (sXX - n * meanX * meanX) / (n - 1);
+        if (varX > 0) {
+            const covXY = (sXY - n * meanX * meanY) / (n - 1);
+            const c = covXY / varX;
+            value = meanY - c * (meanX - control.mean);
+            resVar = Math.max(0, varY - 2 * c * covXY + c * c * varX);
+            usedControl = true;
+        }
+    }
+    // An iid standard error is meaningless for a deterministic low-discrepancy sequence (see
+    // MonteCarloStatistics.standardError): report null with the reason, never a 75×-overstated number.
+    const quasiRandom = method !== 'pseudo';
+    const se = quasiRandom ? null : Math.sqrt(resVar / n);
+    if (quasiRandom) {
+        warnings.push(warning(WarningCode.ModelLimitation, `quasi-random sampling (${method}): an iid standard error is not applicable to a deterministic ` +
+            'low-discrepancy sequence, so standardError and confidenceInterval are null rather than an ' +
+            'overstated sample-variance figure. For a QMC error estimate, average independent RANDOMIZED ' +
+            '(scrambled/shifted) replications and take the variance across them; for a reported error bar ' +
+            "from this estimator, use method: 'pseudo'.", 'info', { method }));
+    }
+    const converged = Number.isFinite(value) && (se === null || Number.isFinite(se));
+    return {
+        value,
+        standardError: se,
+        confidenceInterval: se === null ? null : [value - z * se, value + z * se],
+        paths: n,
+        seed: options.seed >>> 0,
+        method,
+        varianceReduction: {
+            antithetic,
+            controlVariate: usedControl,
+            brownianBridge: bridge,
+        },
+        converged,
+        warnings,
+    };
+}
+const GBM_PATH_FIELDS = [
+    'spot',
+    'riskFreeRate',
+    'dividendYield',
+    'volatility',
+    'timeToExpiryYears',
+];
+/** The raw path math with NO ladder — see {@link gbmTerminalUnchecked} for why it exists. */
+export function gbmPathUnchecked(input) {
+    const { spot: s0, riskFreeRate: r, dividendYield: q, volatility: sigma, timeToExpiryYears: T, shocks, } = input;
+    const steps = shocks.length;
+    const timeStepYears = T / steps;
+    const drift = (r - q - 0.5 * sigma * sigma) * timeStepYears;
+    const vol = sigma * Math.sqrt(timeStepYears);
+    const S = new Float64Array(steps + 1);
+    S[0] = s0;
+    let logS = Math.log(s0);
+    for (let k = 0; k < steps; k++) {
+        logS += drift + vol * shocks[k];
+        S[k + 1] = Math.exp(logS);
+    }
+    return S;
+}
+export function gbmPath(input) {
+    requireArgumentObject('gbmPath', 'input', input);
+    requireFiniteFields('gbmPath', input, GBM_PATH_FIELDS, {
+        exampleCall: 'gbmPath({ spot: 100, riskFreeRate: 0.04, dividendYield: 0, volatility: 0.2, timeToExpiryYears: 1, shocks: [0.3, -0.1] })',
+    });
+    requireArgumentArray('gbmPath', 'shocks', input.shocks);
+    return gbmPathUnchecked(input);
+}
+const GBM_TERMINAL_FIELDS = [
+    'spot',
+    'riskFreeRate',
+    'dividendYield',
+    'volatility',
+    'timeToExpiryYears',
+    'shock',
+];
+/**
+ * The raw GBM math with NO ladder — for callers that validated once at their own boundary and then
+ * sample in a loop (`monteCarloEuropean`, the exotics path engines). Deliberately NOT re-exported
+ * from any public entrypoint: per-sample validation in a Monte-Carlo loop is the exact cost spec
+ * 3B.1b forbids, and an unchecked kernel on the public surface would be an API.
+ */
+export function gbmTerminalUnchecked(input) {
+    const { spot, riskFreeRate, dividendYield, volatility, timeToExpiryYears, shock } = input;
+    return (spot *
+        Math.exp((riskFreeRate - dividendYield - 0.5 * volatility * volatility) * timeToExpiryYears +
+            volatility * Math.sqrt(timeToExpiryYears) * shock));
+}
+export function gbmTerminal(input) {
+    requireArgumentObject('gbmTerminal', 'input', input);
+    // Every leg runs the ladder: a null dividendYield used to coerce to 0 inside the drift and
+    // return a price as if it had succeeded (first-touch law).
+    requireFiniteFields('gbmTerminal', input, GBM_TERMINAL_FIELDS, {
+        exampleCall: 'gbmTerminal({ spot: 100, riskFreeRate: 0.04, dividendYield: 0, volatility: 0.2, timeToExpiryYears: 1, shock: 0.31 })',
+    });
+    return gbmTerminalUnchecked(input);
+}
+/**
+ * The geometric-Brownian-motion namespace — the grouped surface over the flat `gbm*` kernels.
+ * `gbm.path` / `gbm.terminal` are the same functions; prefer the namespace over the deprecated flats.
+ */
+export const gbm = {
+    path: gbmPath,
+    terminal: gbmTerminal,
+};
+//# sourceMappingURL=core.js.map

package/modules/options/dist/mc/core.js.map

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

package/modules/options/dist/monte-carlo.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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 { type OptionContract, type OptionType } from '../../core/dist/index.js';
+import { type MonteCarloEstimate, type MonteCarloStatistics, type MonteCarloSamplingOptions } from './mc/core.js';
+import type { OptionMarket, PriceResult } from './types.js';
+export type { GbmPathInput, GbmTerminalInput, MonteCarloMethod, MonteCarloRandomNumberGenerator, MonteCarloStatistics, MonteCarloEstimate, MonteCarloSamplingOptions, VarianceReduction, ControlVariate, } from './mc/core.js';
+export { gbm, gbmPath, gbmTerminal } from './mc/core.js';
+/** Options for {@link monteCarloPrice}. Extends the shared MC sampling options. */
+export interface MonteCarloPriceOptions extends MonteCarloSamplingOptions {
+    /** Compute Greeks by common-random-number finite differences (default `true`). */
+    greeks?: boolean;
+    /**
+     * Compute the full higher-order (extended) Greek set by CRN finite differences (implies `greeks`).
+     * Third-order Greeks (speed/color/ultima) carry more Monte-Carlo error than the first/second order —
+     * raise `paths` when you need them tight.
+     */
+    extendedGreeks?: boolean;
+}
+/** A pricing result enriched with the Monte-Carlo error statistics. */
+export interface MonteCarloPriceResult extends PriceResult {
+    /** Standard error, confidence interval, path count, seed, method, and variance-reduction flags. */
+    monteCarlo: MonteCarloStatistics;
+}
+/** Required raw inputs for one discounted European GBM estimate. */
+export interface MonteCarloEuropeanInput {
+    type: OptionType;
+    spot: number;
+    strike: number;
+    timeToExpiryYears: number;
+    riskFreeRate: number;
+    dividendYield: number;
+    volatility: number;
+    options: MonteCarloPriceOptions;
+}
+/**
+ * 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 declare function monteCarloEuropean(input: MonteCarloEuropeanInput): MonteCarloEstimate;
+/**
+ * Price a European contract by Monte-Carlo simulation, returning value, Greeks, assumptions, and the
+ * MC error statistics (`result.mc`). Validates the market the same way the analytic engines do, and
+ * applies the escrowed-spot model for discrete dividends.
+ */
+export interface MonteCarloPriceInput {
+    contract: OptionContract;
+    market: OptionMarket;
+    options: MonteCarloPriceOptions;
+}
+export declare function monteCarloPrice(input: MonteCarloPriceInput): MonteCarloPriceResult;
+//# sourceMappingURL=monte-carlo.d.ts.map

package/modules/options/dist/monte-carlo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"monte-carlo.d.ts","sourceRoot":"","sources":["../src/monte-carlo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAWL,KAAK,cAAc,EACnB,KAAK,UAAU,EAQhB,MAAM,0BAAoB,CAAC;AAG5B,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAG/B,MAAM,cAAc,CAAC;AAItB,OAAO,KAAK,EAA0B,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEpF,YAAY,EACV,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EAChB,+BAA+B,EAC/B,oBAAoB,EACpB,kBAAkB,EAClB,yBAAyB,EACzB,iBAAiB,EACjB,cAAc,GACf,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEzD,mFAAmF;AACnF,MAAM,WAAW,sBAAuB,SAAQ,yBAAyB;IACvE,kFAAkF;IAClF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,uEAAuE;AACvE,MAAM,WAAW,qBAAsB,SAAQ,WAAW;IACxD,mGAAmG;IACnG,UAAU,EAAE,oBAAoB,CAAC;CAClC;AAED,oEAAoE;AACpE,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,sBAAsB,CAAC;CACjC;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,GAAG,kBAAkB,CAsFrF;AAwKD;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,cAAc,CAAC;IACzB,MAAM,EAAE,YAAY,CAAC;IACrB,OAAO,EAAE,sBAAsB,CAAC;CACjC;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,qBAAqB,CAwMlF"}