@insiderfinance/totalfinance 0.1.0

package/modules/math/dist/montecarlo.js

@@ -0,0 +1,248 @@
+/**
+ * Monte Carlo runner and variance-reduction primitives (spec §8.6).
+ *
+ * The runner accumulates online (Welford) mean/variance and reports a typed `MonteCarloResult` with
+ * standard error, confidence interval, and the seed. It is model-agnostic: the caller supplies a
+ * `sampler` callback — no option-payoff logic lives here.
+ */
+import { ensureKnownKeys, requireArgumentObject, ErrorCode, InputError } from '../../core/dist/index.js';
+import { cholesky } from './linalg.js';
+import { normalInverseCdf } from './normal.js';
+import { mulberry32, normalSample } from './random.js';
+import { covariance, mean, variance } from './statistics.js';
+/**
+ * The most paths one `monteCarlo` run will draw (2026-08-23 review, P0 "unbounded work"):
+ * `Number.isInteger(1e308)` is `true`, so the old check admitted a budget the path loop could never
+ * finish — and above 2^53 the loop counter stops advancing entirely, a literal hang. The runner's own
+ * Welford update costs ~10 ns/path before the caller's sampler runs (a bare normal draw was measured
+ * at ~37 ns), so 10^8 paths is already 1–4 s with a FREE sampler; standard error shrinks only ∝ 1/√n,
+ * so the cap's last decade buys a mere 3× precision.
+ */
+const MAX_MONTE_CARLO_PATHS = 100_000_000;
+/**
+ * The most dimensions one antithetic sampler will draw per path (2026-08-23 review, P0 "unbounded
+ * work"): the wrapper allocates TWO scratch arrays of `dimensions` doubles and fills both with
+ * normal draws (~37 ns each, measured) on EVERY path — at the cap that is 16 MB of scratch and
+ * ~75 ms per path, already an extreme problem; beyond it the "dimension count" is an allocation
+ * request, and above 2^53 the fill loop cannot terminate.
+ */
+const MAX_SAMPLER_DIMENSIONS = 1_000_000;
+/**
+ * The most strata one `stratifiedUniforms` call will materialize (2026-08-23 review, P0 "unbounded
+ * work"): one 8-byte double per stratum — 0.8 GB at the cap, filled in ~1 s (measured ~9 ns/sample) —
+ * and the old `Number.isInteger` check let 1e308 reach `new Array(count)` as if it were a sample size.
+ * Matches MAX_SAMPLE_COUNT in random.ts, its per-sample sibling.
+ */
+const MAX_STRATIFIED_COUNT = 100_000_000;
+/** Run a Monte Carlo estimate of `E[sampler(randomNumberGenerator)]` with online statistics and a stopping rule. */
+function finiteWhenPresent(value, functionName, field) {
+    if (value === undefined)
+        return;
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new InputError(`${functionName}: ${field} must be a finite number when provided — omit the field to use the default. Received ${value === null ? 'null' : typeof value}.`, { code: ErrorCode.InputWrongType, context: { function: functionName, field } });
+    }
+}
+export function monteCarlo(sampler, options) {
+    if (typeof sampler !== 'function') {
+        throw new InputError(`monteCarlo: sampler must be a function of the RNG — monteCarlo((rng) => rng.next(), { seed: 1 }). Received ${sampler === null ? 'null' : typeof sampler}.`, { code: ErrorCode.InputWrongType, context: { field: 'sampler' } });
+    }
+    requireArgumentObject('monteCarlo', 'options', options);
+    ensureKnownKeys('monteCarlo', 'options', options, [
+        'paths',
+        'seed',
+        'targetStandardError',
+        'minPaths',
+        'confidence',
+    ]);
+    for (const field of ['paths', 'targetStandardError', 'minPaths', 'confidence']) {
+        finiteWhenPresent(options[field], 'monteCarlo', field);
+    }
+    const maxPaths = options.paths ?? 100_000;
+    const minPaths = options.minPaths ?? 1000;
+    const confidence = options.confidence ?? 0.95;
+    // Validate the budget up front — a meaningful estimate needs ≥ 2 paths; an invalid budget must
+    // throw, never return a successful-looking NaN/∞ result (design law #4).
+    if (!Number.isFinite(options.seed)) {
+        throw new InputError(`monteCarlo: seed must be a finite number, got ${options.seed}.`, {
+            code: ErrorCode.InputNotFinite,
+            context: { seed: options.seed },
+        });
+    }
+    // Safe integer AND a work cap (2026-08-23 review, P0): see MAX_MONTE_CARLO_PATHS.
+    if (!Number.isSafeInteger(maxPaths) || maxPaths < 2 || maxPaths > MAX_MONTE_CARLO_PATHS) {
+        throw new InputError(`monteCarlo: paths must be an integer in [2, ${MAX_MONTE_CARLO_PATHS.toLocaleString('en-US')}] — every path runs the sampler plus a ~10 ns accumulator update, so the cap is already seconds of synchronous work even for a free sampler, and standard error ∝ 1/√n gains only 3× per extra decade. Received ${maxPaths}.\n  e.g. monteCarlo((rng) => rng.next(), { paths: 100_000, seed: 42 })`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { paths: maxPaths, max: MAX_MONTE_CARLO_PATHS },
+        });
+    }
+    // Safe integer only (2026-08-23 review, P0): minPaths bounds NO loop — the path loop is bounded by
+    // `paths` above; this is merely the threshold before the stopping rule may fire. Above 2^53 it is
+    // no longer an exact integer, so the `count >= minPaths` comparison would silently misfire instead.
+    if (!Number.isSafeInteger(minPaths) || minPaths < 1) {
+        throw new InputError(`monteCarlo: minPaths must be a positive integer, got ${minPaths}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { minPaths },
+        });
+    }
+    if (!(confidence > 0 && confidence < 1)) {
+        throw new InputError(`monteCarlo: confidence must be in (0, 1), got ${confidence}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { confidence },
+        });
+    }
+    if (options.targetStandardError !== undefined && !(options.targetStandardError > 0)) {
+        throw new InputError(`monteCarlo: targetStandardError must be positive, got ${options.targetStandardError}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { targetStandardError: options.targetStandardError },
+        });
+    }
+    const z = normalInverseCdf(0.5 + confidence / 2);
+    const randomNumberGenerator = (options.randomNumberGenerator ?? mulberry32)(options.seed);
+    let m = 0;
+    let m2 = 0;
+    let count = 0;
+    let converged = options.targetStandardError === undefined;
+    for (let i = 1; i <= maxPaths; i++) {
+        const x = sampler(randomNumberGenerator);
+        if (!Number.isFinite(x)) {
+            throw new InputError(`monteCarlo: sampler returned a non-finite value (${x}) at path ${i}; a NaN/∞ sample must not surface as a successful estimate.`, { code: ErrorCode.InputNotFinite, context: { path: i, value: x } });
+        }
+        count++;
+        const delta = x - m;
+        m += delta / count;
+        m2 += delta * (x - m);
+        if (options.targetStandardError !== undefined && count >= minPaths) {
+            const v = m2 / (count - 1);
+            if (Math.sqrt(v / count) <= options.targetStandardError) {
+                converged = true;
+                break;
+            }
+        }
+    }
+    const v = count > 1 ? m2 / (count - 1) : NaN;
+    const se = Math.sqrt(v / count);
+    return {
+        value: m,
+        variance: v,
+        standardError: se,
+        confidenceInterval: [m - z * se, m + z * se],
+        paths: count,
+        // The caller's literal seed, not `seed >>> 0`: a run seeded with -1 reported 4294967295, which
+        // reproduces the run but is not the number anyone passed in.
+        seed: options.seed,
+        converged,
+    };
+}
+/**
+ * Wrap a payoff over a standard-normal vector into an antithetic sampler: each path evaluates the
+ * payoff at `Z` and `-Z` and averages, reducing variance for monotone payoffs.
+ */
+export function antitheticSampler(payoff, dimensions) {
+    // Safe integer AND a work cap (2026-08-23 review, P0): see MAX_SAMPLER_DIMENSIONS — the old
+    // `Number.isInteger` check let 1e308 through to `new Array(dimensions)` inside every path.
+    if (!Number.isSafeInteger(dimensions) || dimensions < 1 || dimensions > MAX_SAMPLER_DIMENSIONS) {
+        throw new InputError(`antitheticSampler: dimensions must be an integer in [1, ${MAX_SAMPLER_DIMENSIONS.toLocaleString('en-US')}] — every path fills TWO scratch arrays of this length with normal draws (~37 ns each), so the cap is already ~75 ms per path and 16 MB of scratch. Received ${dimensions}.\n  e.g. antitheticSampler((z) => Math.max(0, z[0]), 1)`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { dimensions, max: MAX_SAMPLER_DIMENSIONS },
+        });
+    }
+    return (randomNumberGenerator) => {
+        const z = new Array(dimensions);
+        const zNeg = new Array(dimensions);
+        for (let i = 0; i < dimensions; i++) {
+            z[i] = normalSample(randomNumberGenerator);
+            zNeg[i] = -z[i];
+        }
+        return 0.5 * (payoff(z) + payoff(zNeg));
+    };
+}
+/**
+ * Control-variate adjusted estimate: `E[Y] ≈ Ȳ − c·(X̄ − E[X])`, with `c = cov(Y,X)/var(X)`.
+ * `samples` are the target outputs, `controls` the control outputs, `controlMean` the known `E[X]`.
+ */
+export function controlVariateEstimate(samples, controls, controlMean) {
+    // The control's true mean is positional: omitted, the correction subtracted NaN and the
+    // "variance-reduced" estimate WAS the noise it claimed to remove.
+    if (typeof controlMean !== 'number' || !Number.isFinite(controlMean)) {
+        throw new InputError(`controlVariateEstimate: controlMean must be a finite number — controlVariateEstimate(samples, controls, 0.5). Received ${controlMean === null ? 'null' : controlMean === undefined ? 'undefined' : typeof controlMean}.`, { code: ErrorCode.InputWrongType, context: { field: 'controlMean' } });
+    }
+    const vx = variance(controls);
+    if (vx === 0)
+        return mean(samples);
+    const c = covariance(samples, controls) / vx;
+    return mean(samples) - c * (mean(controls) - controlMean);
+}
+/** `n` stratified uniforms — one sample in each stratum `[i/n, (i+1)/n)`. */
+export function stratifiedUniforms(randomNumberGenerator, count) {
+    if (randomNumberGenerator === null ||
+        typeof randomNumberGenerator !== 'object' ||
+        typeof randomNumberGenerator.next !== 'function') {
+        throw new InputError(`stratifiedUniforms: randomNumberGenerator must be a generator with next() — build one with createRandomNumberGenerator(seed). Received ${randomNumberGenerator === null ? 'null' : typeof randomNumberGenerator}.`, { code: ErrorCode.InputWrongType, context: { field: 'randomNumberGenerator' } });
+    }
+    // `new Array(-1)` / `new Array(2.5)` throw a raw `RangeError: Invalid array length` that names
+    // neither this function nor the argument. Its siblings (uniformSamples, antitheticSampler) all
+    // validate; this one didn't. Safe integer AND a work cap (2026-08-23 review, P0): see
+    // MAX_STRATIFIED_COUNT — `Number.isInteger(1e308)` is `true`, so an absurd count sailed through
+    // to the allocator (below 2^32 as a multi-gigabyte allocation, above it as that same raw RangeError).
+    if (!Number.isSafeInteger(count) || count < 1 || count > MAX_STRATIFIED_COUNT) {
+        throw new InputError(`stratifiedUniforms: count must be an integer in [1, ${MAX_STRATIFIED_COUNT.toLocaleString('en-US')}] (one sample per stratum) — the call materializes one 8-byte double per stratum, 0.8 GB at the cap, filled in ~1 s. Received ${count}.\n  e.g. stratifiedUniforms(createRandomNumberGenerator(42), 1_000)`, { code: ErrorCode.InputOutOfRange, context: { count, max: MAX_STRATIFIED_COUNT } });
+    }
+    const out = new Array(count);
+    for (let i = 0; i < count; i++)
+        out[i] = (i + randomNumberGenerator.next()) / count;
+    return out;
+}
+/**
+ * Brownian-bridge path construction on a uniform grid of `n` steps of size `stepSize` (a DIMENSIONLESS
+ * grid spacing — callers building a unit grid pass `1` and scale later, so this is deliberately not
+ * a `*Years` quantity). Consumes `n`
+ * standard normals, assigning the most significant (endpoint, then successive midpoints) first —
+ * ideal for quasi-Monte Carlo. Returns `W[0..n]` with `W[0] = 0`.
+ */
+export function brownianBridge(normals, stepSize) {
+    if (!(stepSize > 0) || !Number.isFinite(stepSize)) {
+        throw new InputError(`brownianBridge: stepSize must be a positive number, got ${stepSize}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { stepSize },
+        });
+    }
+    const n = normals.length;
+    const W = new Array(n + 1).fill(0);
+    if (n === 0)
+        return W;
+    let k = 0;
+    W[n] = Math.sqrt(n * stepSize) * normals[k++];
+    const queue = [[0, n]];
+    while (queue.length) {
+        const [l, r] = queue.shift();
+        if (r - l <= 1)
+            continue;
+        const mid = (l + r) >> 1;
+        const tl = l * stepSize;
+        const tm = mid * stepSize;
+        const tr = r * stepSize;
+        W[mid] =
+            W[l] +
+                ((W[r] - W[l]) * (tm - tl)) / (tr - tl) +
+                Math.sqrt(((tr - tm) * (tm - tl)) / (tr - tl)) * normals[k++];
+        queue.push([l, mid]);
+        queue.push([mid, r]);
+    }
+    return W;
+}
+/** Build a sampler of correlated standard normals from a covariance/correlation matrix (via Cholesky). */
+export function correlatedNormalSampler(covarianceOrCorrelation) {
+    const L = cholesky(covarianceOrCorrelation);
+    const n = L.length;
+    return (randomNumberGenerator) => {
+        const z = new Array(n);
+        for (let i = 0; i < n; i++)
+            z[i] = normalSample(randomNumberGenerator);
+        const out = new Array(n).fill(0);
+        for (let i = 0; i < n; i++)
+            for (let j = 0; j <= i; j++)
+                out[i] += L[i][j] * z[j];
+        return out;
+    };
+}
+//# sourceMappingURL=montecarlo.js.map

package/modules/math/dist/montecarlo.js.map

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

package/modules/math/dist/normal.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The standard normal distribution (spec §8.1).
+ *
+ * `normalCdf` uses Graeme West's 2009 algorithm ("Better approximations to cumulative normal
+ * functions"), accurate to roughly 1e-15 across the domain — the same routine option-pricing
+ * libraries rely on. `normalInverseCdf` uses Acklam's rational approximation refined by one Halley step,
+ * giving full double precision.
+ */
+/** Standard normal probability density function φ(x). */
+export declare function normalPdf(x: number): number;
+/** Log of the standard normal PDF — exact and stable everywhere. */
+export declare function normalLogPdf(x: number): number;
+/** Standard normal cumulative distribution function Φ(x). */
+export declare function normalCdf(x: number): number;
+/**
+ * Inverse standard normal CDF (quantile function). Returns `-Infinity` at p<=0 and `+Infinity` at
+ * p>=1.
+ */
+export declare function normalInverseCdf(probability: number): number;
+/** Standard normal survival function: 1 − Φ(x) = Φ(−x) (stable in the right tail). */
+export declare function normalSurvivalFunction(x: number): number;
+/**
+ * Log of the standard normal CDF, stable into the far-left tail (where Φ(x) underflows to 0).
+ * Uses `log(Φ(x))` for `x ≥ -20` and the asymptotic expansion
+ * `Φ(x) = φ(x)/(-x)·(1 − 1/x² + 3/x⁴ − 15/x⁶ + …)` below that.
+ */
+export declare function normalLogCdf(x: number): number;
+/** Log of the standard normal survival function (stable in the far-right tail). */
+export declare function normalLogSurvivalFunction(x: number): number;
+/** Convenience namespace mirroring the spec's `normal.pdf/cdf/inverseCdf` facade. */
+export declare const normal: {
+    readonly pdf: typeof normalPdf;
+    readonly cdf: typeof normalCdf;
+    readonly inverseCdf: typeof normalInverseCdf;
+    readonly survivalFunction: typeof normalSurvivalFunction;
+    readonly logPdf: typeof normalLogPdf;
+    readonly logCdf: typeof normalLogCdf;
+    readonly logSurvivalFunction: typeof normalLogSurvivalFunction;
+};
+//# sourceMappingURL=normal.d.ts.map

package/modules/math/dist/normal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normal.d.ts","sourceRoot":"","sources":["../src/normal.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,yDAAyD;AACzD,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED,oEAAoE;AACpE,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE9C;AAoBD,6DAA6D;AAC7D,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAgB3C;AAmBD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CA0C5D;AAED,sFAAsF;AACtF,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAS9C;AAED,mFAAmF;AACnF,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,qFAAqF;AACrF,eAAO,MAAM,MAAM;;;;;;;;CAQT,CAAC"}

package/modules/math/dist/normal.js

@@ -0,0 +1,157 @@
+/**
+ * The standard normal distribution (spec §8.1).
+ *
+ * `normalCdf` uses Graeme West's 2009 algorithm ("Better approximations to cumulative normal
+ * functions"), accurate to roughly 1e-15 across the domain — the same routine option-pricing
+ * libraries rely on. `normalInverseCdf` uses Acklam's rational approximation refined by one Halley step,
+ * giving full double precision.
+ */
+const SQRT_2PI = Math.sqrt(2 * Math.PI);
+const INV_SQRT_2PI = 1 / SQRT_2PI;
+const LOG_SQRT_2PI = 0.5 * Math.log(2 * Math.PI);
+/** Standard normal probability density function φ(x). */
+export function normalPdf(x) {
+    return INV_SQRT_2PI * Math.exp(-0.5 * x * x);
+}
+/** Log of the standard normal PDF — exact and stable everywhere. */
+export function normalLogPdf(x) {
+    return -0.5 * x * x - LOG_SQRT_2PI;
+}
+// West 2009 coefficients.
+const N0 = 220.2068679123761;
+const N1 = 221.2135961699311;
+const N2 = 112.0792914978709;
+const N3 = 33.912866078383;
+const N4 = 6.37396220353165;
+const N5 = 0.7003830644436881;
+const N6 = 0.03526249659989109;
+const M0 = 440.4137358247522;
+const M1 = 793.8265125199484;
+const M2 = 637.3336333788311;
+const M3 = 296.5642487796737;
+const M4 = 86.78073220294608;
+const M5 = 16.06417757920695;
+const M6 = 1.755667163182642;
+const M7 = 0.08838834764831844;
+const SPLIT = 7.07106781186547;
+/** Standard normal cumulative distribution function Φ(x). */
+export function normalCdf(x) {
+    if (Number.isNaN(x))
+        return NaN;
+    const z = Math.abs(x);
+    let c = 0;
+    if (z <= 37) {
+        const e = Math.exp(-0.5 * z * z);
+        if (z < SPLIT) {
+            const n = (((((N6 * z + N5) * z + N4) * z + N3) * z + N2) * z + N1) * z + N0;
+            const d = ((((((M7 * z + M6) * z + M5) * z + M4) * z + M3) * z + M2) * z + M1) * z + M0;
+            c = (e * n) / d;
+        }
+        else {
+            const f = z + 1 / (z + 2 / (z + 3 / (z + 4 / (z + 13 / 20))));
+            c = e / (SQRT_2PI * f);
+        }
+    }
+    return x <= 0 ? c : 1 - c;
+}
+// Acklam coefficients.
+const A = [
+    -3.969683028665376e1, 2.209460984245205e2, -2.759285104469687e2, 1.38357751867269e2,
+    -3.066479806614716e1, 2.506628277459239,
+];
+const B = [
+    -5.447609879822406e1, 1.615858368580409e2, -1.556989798598866e2, 6.680131188771972e1,
+    -1.328068155288572e1,
+];
+const C = [
+    -7.784894002430293e-3, -3.223964580411365e-1, -2.400758277161838, -2.549732539343734,
+    4.374664141464968, 2.938163982698783,
+];
+const D = [7.784695709041462e-3, 3.224671290700398e-1, 2.445134137142996, 3.754408661907416];
+const P_LOW = 0.02425;
+const P_HIGH = 1 - P_LOW;
+/**
+ * Inverse standard normal CDF (quantile function). Returns `-Infinity` at p<=0 and `+Infinity` at
+ * p>=1.
+ */
+export function normalInverseCdf(probability) {
+    if (Number.isNaN(probability))
+        return NaN;
+    if (probability <= 0)
+        return -Infinity;
+    if (probability >= 1)
+        return Infinity;
+    let x;
+    if (probability < P_LOW) {
+        const q = Math.sqrt(-2 * Math.log(probability));
+        x =
+            (((((C[0] * q + C[1]) * q + C[2]) * q + C[3]) * q + C[4]) * q + C[5]) /
+                ((((D[0] * q + D[1]) * q + D[2]) * q + D[3]) * q + 1);
+    }
+    else if (probability <= P_HIGH) {
+        const q = probability - 0.5;
+        const r = q * q;
+        x =
+            ((((((A[0] * r + A[1]) * r + A[2]) * r + A[3]) * r + A[4]) * r + A[5]) * q) /
+                (((((B[0] * r + B[1]) * r + B[2]) * r + B[3]) * r + B[4]) * r + 1);
+    }
+    else {
+        const q = Math.sqrt(-2 * Math.log(1 - probability));
+        x =
+            -(((((C[0] * q + C[1]) * q + C[2]) * q + C[3]) * q + C[4]) * q + C[5]) /
+                ((((D[0] * q + D[1]) * q + D[2]) * q + D[3]) * q + 1);
+    }
+    // One Halley refinement step → full double precision. In the last denormal decades
+    // (p ≲ 1e-308) exp(x²/2) overflows; the rational seed is already exact there, so skip the step
+    // rather than return NaN.
+    //
+    // It must ALSO be skipped once `normalCdf(x)` flushes to exactly 0 (|x| > 37, i.e. p ≲ 1e-301).
+    // There the residual `e = Φ(x) − p` degenerates to `−p` — a pure statement about the underflow,
+    // carrying no information about x — while `exp(x²/2)` is still finite, so the step is computed
+    // from noise and DRAGS the accurate seed off: at p = 1e-300 it moved the answer from −37.0471
+    // (correct) to −37.0291, an error 10⁷× the seed's own.
+    const c = normalCdf(x);
+    if (c > 0) {
+        const e = c - probability;
+        const u = e * SQRT_2PI * Math.exp(0.5 * x * x);
+        if (Number.isFinite(u)) {
+            x = x - u / (1 + (x * u) / 2);
+        }
+    }
+    return x;
+}
+/** Standard normal survival function: 1 − Φ(x) = Φ(−x) (stable in the right tail). */
+export function normalSurvivalFunction(x) {
+    return normalCdf(-x);
+}
+/**
+ * Log of the standard normal CDF, stable into the far-left tail (where Φ(x) underflows to 0).
+ * Uses `log(Φ(x))` for `x ≥ -20` and the asymptotic expansion
+ * `Φ(x) = φ(x)/(-x)·(1 − 1/x² + 3/x⁴ − 15/x⁶ + …)` below that.
+ */
+export function normalLogCdf(x) {
+    if (Number.isNaN(x))
+        return NaN;
+    if (x >= -20) {
+        const c = normalCdf(x);
+        return c > 0 ? Math.log(c) : -Infinity;
+    }
+    const ix2 = 1 / (x * x);
+    const series = 1 - ix2 * (1 - ix2 * (3 - ix2 * (15 - ix2 * 105)));
+    return normalLogPdf(x) - Math.log(-x) + Math.log(series);
+}
+/** Log of the standard normal survival function (stable in the far-right tail). */
+export function normalLogSurvivalFunction(x) {
+    return normalLogCdf(-x);
+}
+/** Convenience namespace mirroring the spec's `normal.pdf/cdf/inverseCdf` facade. */
+export const normal = {
+    pdf: normalPdf,
+    cdf: normalCdf,
+    inverseCdf: normalInverseCdf,
+    survivalFunction: normalSurvivalFunction,
+    logPdf: normalLogPdf,
+    logCdf: normalLogCdf,
+    logSurvivalFunction: normalLogSurvivalFunction,
+};
+//# sourceMappingURL=normal.js.map

package/modules/math/dist/normal.js.map

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

package/modules/math/dist/optimize.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Optimization (spec §8.4).
+ *
+ * Scalar minimization (golden-section, Brent), multivariate Nelder–Mead and BFGS (numerical
+ * gradient + Armijo backtracking line search), and Levenberg–Marquardt least squares (numerical
+ * Jacobian). All report convergence honestly.
+ */
+import type { ScalarFunction } from './solvers.js';
+export interface MinResult {
+    argMin: number;
+    minimum: number;
+    converged: boolean;
+    iterations: number;
+    /** Objective evaluations performed (interpretability parity across optimizers). */
+    evaluations?: number;
+    reason?: 'max_iterations' | 'non_finite';
+}
+export interface MultiMinResult {
+    argMin: number[];
+    minimum: number;
+    converged: boolean;
+    iterations: number;
+    /** Objective evaluations performed. */
+    evaluations?: number;
+    /** Seeded global optimizers (differential evolution) echo the PRNG seed actually used. */
+    seed?: number;
+    reason?: 'max_iterations' | 'non_finite' | 'line_search_failed';
+}
+export interface MinOptions {
+    tolerance?: number;
+    maximumIterations?: number;
+}
+export declare function goldenSectionMin(objective: ScalarFunction, lowerBound: number, upperBound: number, options?: MinOptions): MinResult;
+/** Brent's method for 1-D minimization (parabolic interpolation with a golden-section safeguard). */
+export declare function brentMin(objective: ScalarFunction, a0: number, b0: number, options?: MinOptions): MinResult;
+export type MultivariateFunction = (x: number[]) => number;
+export interface MultiMinOptions {
+    tolerance?: number;
+    maximumIterations?: number;
+    /** Analytic gradient; if omitted, a central-difference gradient is used (BFGS only). */
+    grad?: (point: number[]) => number[];
+}
+/** Nelder–Mead simplex minimization (derivative-free). */
+export declare function nelderMead(objective: MultivariateFunction, start: number[], options?: MultiMinOptions): MultiMinResult;
+/** BFGS quasi-Newton minimization with a backtracking (Armijo) line search. */
+export declare function bfgs(objective: MultivariateFunction, start: number[], options?: MultiMinOptions): MultiMinResult;
+export interface LevenbergMarquardtResult {
+    parameters: number[];
+    residualNorm: number;
+    converged: boolean;
+    iterations: number;
+    /** Residual-vector evaluations performed (interpretability parity with the other optimizers). */
+    evaluations?: number;
+    reason?: 'max_iterations';
+}
+export interface LMOptions {
+    tolerance?: number;
+    maximumIterations?: number;
+    lambda0?: number;
+}
+/** Levenberg–Marquardt least-squares minimization of `||residuals(parameters)||²`. */
+export declare function levenbergMarquardt(residuals: (p: number[]) => number[], p0: number[], options?: LMOptions): LevenbergMarquardtResult;
+export interface DifferentialEvolutionOptions {
+    /** Population size. Default `max(20, 10·dim)`. */
+    populationSize?: number;
+    /** Maximum generations. Default 300. */
+    maxGenerations?: number;
+    /** Differential weight `F ∈ (0, 2]`. Default 0.8. */
+    mutation?: number;
+    /** Crossover probability `CR ∈ [0, 1]`. Default 0.9. */
+    crossover?: number;
+    /** Seed for the deterministic PRNG. Default 0x5eed. */
+    seed?: number;
+    /** Converge when the population's objective spread falls below this. Default 1e-12. */
+    tolerance?: number;
+}
+/**
+ * Differential evolution (Storn–Price `rand/1/bin`): a seeded, bound-constrained **global** optimizer
+ * for multimodal objectives the local methods (Nelder–Mead/BFGS) get stuck on. Deterministic given the
+ * seed; trial vectors are reflected back inside `bounds`. Returns the best member found.
+ */
+export declare function differentialEvolution(objective: MultivariateFunction, bounds: ReadonlyArray<readonly [number, number]>, options?: DifferentialEvolutionOptions): MultiMinResult;
+//# sourceMappingURL=optimize.d.ts.map

package/modules/math/dist/optimize.d.ts.map

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