@insiderfinance/totalfinance 0.1.0

package/modules/math/dist/linalg.js

@@ -0,0 +1,1503 @@
+/**
+ * Dense linear algebra for small matrices (spec §8.3).
+ *
+ * Cholesky factorization, a symmetric Jacobi eigensolver, covariance-matrix construction, and
+ * nearest positive-semidefinite / correlation repair (eigenvalue clipping). Pure TypeScript
+ * reference implementations; acceleration is a later concern.
+ */
+import { ensureKnownKeys, requireArgumentObject, CONVENTIONS_VERSION, ConvergenceError, ErrorCode, InputError, warning, WarningCode, } from '../../core/dist/index.js';
+import { requireMathIterationBudgetWhenPresent } from './resource-validation.js';
+import { covarianceValidated, POPULATION_OPTIONS_SPEC, validateOptions, } from './statistics-internal.js';
+/** Cholesky factorization: lower-triangular `L` with `A = L Lᵀ`. Throws if `A` is not PD. */
+export function cholesky(matrix) {
+    const n = matrix.length;
+    const L = Array.from({ length: n }, () => new Array(n).fill(0));
+    for (let i = 0; i < n; i++) {
+        for (let j = 0; j <= i; j++) {
+            let s = 0;
+            for (let k = 0; k < j; k++)
+                s += L[i][k] * L[j][k];
+            if (i === j) {
+                const d = matrix[i][i] - s;
+                // `!(d > 0)` (not `d <= 0`) so a NaN pivot — a NaN-carrying covariance matrix — throws the
+                // documented not-positive-definite error instead of flowing NaN into every simulation path.
+                if (!(d > 0)) {
+                    throw new InputError(`cholesky: matrix is not positive definite (pivot ${d} at ${i}).`, {
+                        code: ErrorCode.LinalgNotPositiveDefinite,
+                        context: { pivot: d, index: i },
+                    });
+                }
+                L[i][j] = Math.sqrt(d);
+            }
+            else {
+                L[i][j] = (matrix[i][j] - s) / L[j][j];
+            }
+        }
+    }
+    return L;
+}
+/** Solve `A x = b` given the Cholesky factor `L` of `A`. */
+export function choleskySolve(L, b) {
+    const n = L.length;
+    const y = new Array(n).fill(0);
+    for (let i = 0; i < n; i++) {
+        let s = b[i];
+        for (let k = 0; k < i; k++)
+            s -= L[i][k] * y[k];
+        y[i] = s / L[i][i];
+    }
+    const x = new Array(n).fill(0);
+    for (let i = n - 1; i >= 0; i--) {
+        let s = y[i];
+        for (let k = i + 1; k < n; k++)
+            s -= L[k][i] * x[k];
+        x[i] = s / L[i][i];
+    }
+    return x;
+}
+/** Covariance matrix of a set of equal-length variables (`series[k]` is variable k). */
+export function covarianceMatrix(series, options) {
+    // Law 12 at THIS boundary, against THIS declaration — validated ONCE, with the same
+    // compiler-exact spec the statistics module uses. The pairwise loop below goes through the
+    // package-internal `covarianceValidated`, so no per-pair revalidation and no forwarding into
+    // `covariance`'s wider allowlist (which would accept a `nanPolicy` this signature never
+    // declared, engaging pairwise deletion no caller was offered).
+    validateOptions('covarianceMatrix', options, POPULATION_OPTIONS_SPEC);
+    const k = series.length;
+    const M = Array.from({ length: k }, () => new Array(k).fill(0));
+    for (let i = 0; i < k; i++) {
+        for (let j = i; j < k; j++) {
+            const c = covarianceValidated(series[i], series[j], options, 'covarianceMatrix');
+            M[i][j] = c;
+            M[j][i] = c;
+        }
+    }
+    return M;
+}
+/**
+ * Validate a variable-observation series (`series[k]` = variable k's observations): a non-empty,
+ * rectangular array of ≥ 2 finite observations per variable. Returns the shape `{ p, T }`. Shared by the
+ * covariance estimators so they all reject the same malformed inputs the same way.
+ */
+function validateReturnsSeries(series, functionName) {
+    if (!Array.isArray(series) || series.length === 0) {
+        throw new InputError(`${functionName}: series must be a non-empty array of variable observations.`, {
+            code: ErrorCode.InputWrongType,
+            context: { series },
+        });
+    }
+    const p = series.length;
+    if (!Array.isArray(series[0])) {
+        throw new InputError(`${functionName}: series[0] must be an array of observations.`, {
+            code: ErrorCode.InputWrongType,
+            context: { row: 0 },
+        });
+    }
+    const T = series[0].length;
+    if (!(T >= 2)) {
+        throw new InputError(`${functionName}: need at least 2 observations per variable, got ${T}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { observations: T },
+        });
+    }
+    for (let k = 0; k < p; k++) {
+        const row = series[k];
+        if (!Array.isArray(row) || row.length !== T) {
+            throw new InputError(`${functionName}: every variable must have the same number of observations (${T}); series[${k}] has ${Array.isArray(row) ? row.length : 'non-array'}.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { row: k, length: Array.isArray(row) ? row.length : null },
+            });
+        }
+        for (let t = 0; t < T; t++) {
+            if (!Number.isFinite(row[t])) {
+                throw new InputError(`${functionName}: series[${k}][${t}] is not finite (${row[t]}).`, {
+                    code: ErrorCode.InputNotFinite,
+                    context: { row: k, index: t, value: row[t] },
+                });
+            }
+        }
+    }
+    return { p, T };
+}
+/**
+ * Ledoit–Wolf (2004) linear covariance shrinkage toward the scaled identity `μI` (`μ = tr(S)/p`):
+ * `Σ* = δ·μI + (1−δ)·S` with the analytically optimal intensity `δ = min(b̄², d²)/d²`, where
+ * `d² = ‖S − μI‖²_F` and `b̄² = (1/T²)·Σₜ‖xₜxₜᵀ − S‖²_F` estimates the sampling error in `S`. The result
+ * is always SPD (for non-degenerate data), so it is invertible even when the raw sample covariance `S`
+ * is singular (`T < p`). `series[k]` is variable k's observations (p variables × T), matching
+ * {@link covarianceMatrix}. See `docs/specs/ledoit-wolf-shrinkage.md`.
+ */
+function linalgOptionLadder(functionName, options, allowed, numericFields) {
+    requireArgumentObject(functionName, 'options', options);
+    ensureKnownKeys(functionName, 'options', options, allowed);
+    for (const field of numericFields) {
+        const value = options[field];
+        if (value !== undefined && (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 ledoitWolfShrinkage(series, options = {}) {
+    const functionName = 'ledoitWolfShrinkage';
+    const { p, T } = validateReturnsSeries(series, functionName);
+    linalgOptionLadder('ledoitWolfShrinkage', options, ['target', 'market'], []);
+    if (options.target !== undefined &&
+        !['identity', 'constant-correlation', 'single-index'].includes(options.target)) {
+        throw new InputError(`ledoitWolfShrinkage: target must be identity | constant-correlation | single-index when provided. Received ${options.target === null ? 'null' : JSON.stringify(options.target)}.`, { code: ErrorCode.InputInvalidEnum, context: { field: 'target' } });
+    }
+    if (options.market !== undefined &&
+        !Array.isArray(options.market) &&
+        !ArrayBuffer.isView(options.market)) {
+        throw new InputError(`ledoitWolfShrinkage: market must be an array of market returns when provided. Received ${options.market === null ? 'null' : typeof options.market}.`, { code: ErrorCode.InputWrongType, context: { field: 'market' } });
+    }
+    const target = options.target ?? 'identity';
+    const means = new Array(p);
+    for (let k = 0; k < p; k++) {
+        let sum = 0;
+        for (let t = 0; t < T; t++)
+            sum += series[k][t];
+        means[k] = sum / T;
+    }
+    // Sample covariance S (1/T / MLE) and the average variance μ.
+    const S = covarianceMatrix(series, { population: true });
+    let mu = 0;
+    for (let i = 0; i < p; i++)
+        mu += S[i][i];
+    mu /= p;
+    if (target === 'constant-correlation') {
+        return constantCorrelationShrinkage(series, S, means, mu, p, T, functionName);
+    }
+    if (target === 'single-index') {
+        return singleIndexShrinkage(series, S, means, mu, p, T, functionName, options.market);
+    }
+    // ── identity target: Σ* = δ·μI + (1−δ)·S ──
+    // d² = ‖S − μI‖²_F (how far the sample is from the target).
+    let d2 = 0;
+    for (let i = 0; i < p; i++) {
+        for (let j = 0; j < p; j++) {
+            const difference = S[i][j] - (i === j ? mu : 0);
+            d2 += difference * difference;
+        }
+    }
+    // b̄² = (1/T²)·Σₜ ‖xₜxₜᵀ − S‖²_F (the sampling error in S), clamped so δ ∈ [0, 1].
+    let bbar = 0;
+    const x = new Array(p);
+    for (let t = 0; t < T; t++) {
+        for (let i = 0; i < p; i++)
+            x[i] = series[i][t] - means[i];
+        for (let i = 0; i < p; i++) {
+            for (let j = 0; j < p; j++) {
+                const difference = x[i] * x[j] - S[i][j];
+                bbar += difference * difference;
+            }
+        }
+    }
+    bbar /= T * T;
+    const b2 = Math.min(bbar, d2);
+    const delta = d2 > 0 ? b2 / d2 : 0;
+    // Σ* = δ·μI + (1−δ)·S.
+    const covariance = S.map((row, i) => row.map((v, j) => delta * (i === j ? mu : 0) + (1 - delta) * v));
+    return {
+        covariance,
+        shrinkage: delta,
+        sampleCovariance: S,
+        averageVariance: mu,
+        observations: T,
+        target: 'identity',
+    };
+}
+/**
+ * Ledoit–Wolf (2004, "Honey, I Shrunk the Sample Covariance Matrix") shrinkage toward the
+ * **constant-correlation** target `F` (`Fᵢᵢ = Sᵢᵢ`, `Fᵢⱼ = r̄·√(SᵢᵢSⱼⱼ)`, `r̄` the average sample
+ * correlation), with the paper's closed-form intensity `δ* = (π̂ − ρ̂)/γ̂ / T` clamped to `[0, 1]`. See
+ * `docs/specs/ledoit-wolf-constant-correlation.md`.
+ */
+function constantCorrelationShrinkage(series, S, means, mu, p, T, functionName) {
+    // Correlations need positive variances; a constant (zero-variance) variable makes the target undefined.
+    const sd = new Array(p);
+    for (let i = 0; i < p; i++) {
+        if (!(S[i][i] > 0)) {
+            throw new InputError(`${functionName}: the constant-correlation target needs positive variances; variable ${i} has zero sample variance.`, { code: ErrorCode.InputOutOfRange, context: { variable: i } });
+        }
+        sd[i] = Math.sqrt(S[i][i]);
+    }
+    // r̄ = mean of the p(p−1)/2 off-diagonal sample correlations.
+    let rsum = 0;
+    let cnt = 0;
+    for (let i = 0; i < p; i++) {
+        for (let j = i + 1; j < p; j++) {
+            rsum += S[i][j] / (sd[i] * sd[j]);
+            cnt++;
+        }
+    }
+    const rbar = cnt > 0 ? rsum / cnt : 0;
+    // Target F.
+    const F = Array.from({ length: p }, (_, i) => Array.from({ length: p }, (_, j) => (i === j ? S[i][i] : rbar * sd[i] * sd[j])));
+    // Demeaned observations x[i][t].
+    const x = series.map((row, i) => row.map((v) => v - means[i]));
+    // π̂ᵢⱼ = (1/T)Σₜ (xᵢₜxⱼₜ − Sᵢⱼ)² (asymptotic variance of Sᵢⱼ); π̂ = Σπ̂ᵢⱼ.
+    const piHat = Array.from({ length: p }, () => new Array(p).fill(0));
+    let pi = 0;
+    for (let i = 0; i < p; i++) {
+        for (let j = 0; j < p; j++) {
+            let s = 0;
+            for (let t = 0; t < T; t++) {
+                const d = x[i][t] * x[j][t] - S[i][j];
+                s += d * d;
+            }
+            piHat[i][j] = s / T;
+            pi += piHat[i][j];
+        }
+    }
+    // γ̂ = ‖F − S‖²_F (target misspecification).
+    let gamma = 0;
+    for (let i = 0; i < p; i++) {
+        for (let j = 0; j < p; j++) {
+            const d = F[i][j] - S[i][j];
+            gamma += d * d;
+        }
+    }
+    // ρ̂ = Σᵢ π̂ᵢᵢ + Σ_{i≠j} (r̄/2)(√(Sⱼⱼ/Sᵢᵢ)·ϑ̂ᵢ,ᵢⱼ + √(Sᵢᵢ/Sⱼⱼ)·ϑ̂ⱼ,ᵢⱼ),
+    //   ϑ̂ₖ,ᵢⱼ = (1/T)Σₜ (xₖₜ² − Sₖₖ)(xᵢₜxⱼₜ − Sᵢⱼ) (cov of the diagonal & off-diagonal estimates).
+    const thetaTerm = (k, i, j) => {
+        let s = 0;
+        for (let t = 0; t < T; t++) {
+            s += (x[k][t] * x[k][t] - S[k][k]) * (x[i][t] * x[j][t] - S[i][j]);
+        }
+        return s / T;
+    };
+    let rho = 0;
+    for (let i = 0; i < p; i++)
+        rho += piHat[i][i];
+    for (let i = 0; i < p; i++) {
+        for (let j = 0; j < p; j++) {
+            if (i === j)
+                continue;
+            rho +=
+                (rbar / 2) *
+                    ((sd[j] / sd[i]) * thetaTerm(i, i, j) + (sd[i] / sd[j]) * thetaTerm(j, i, j));
+        }
+    }
+    const kappa = gamma > 0 ? (pi - rho) / gamma : 0;
+    const delta = Math.max(0, Math.min(1, kappa / T));
+    // Σ* = δ·F + (1−δ)·S.
+    const covariance = S.map((row, i) => row.map((v, j) => delta * F[i][j] + (1 - delta) * v));
+    return {
+        covariance,
+        shrinkage: delta,
+        sampleCovariance: S,
+        averageVariance: mu,
+        observations: T,
+        target: 'constant-correlation',
+        averageCorrelation: rbar,
+    };
+}
+/**
+ * Ledoit–Wolf (2003, "Improved estimation of the covariance matrix of stock returns…") shrinkage toward the
+ * **single-index (market-model)** target `F`: `Fᵢⱼ = covmktᵢ·covmktⱼ/varmkt` off-diagonal, `Fᵢᵢ = Sᵢᵢ`, where
+ * the market proxy is the equal-weighted average return, `covmktᵢ = Cov(xᵢ, x_mkt)`, `varmkt = Var(x_mkt)`.
+ * Intensity `δ* = (π̂ − ρ̂)/γ̂ / T` clamped to `[0, 1]` with the paper's market-specific `ρ̂`. See
+ * `docs/specs/ledoit-wolf-single-index.md`.
+ */
+function singleIndexShrinkage(series, S, means, mu, p, T, functionName, market) {
+    // Demeaned observations x[i][t].
+    const x = series.map((row, i) => row.map((v) => v - means[i]));
+    // Market factor: the caller's observed series when given (demeaned), else the equal-weighted
+    // cross-sectional average return — the Ledoit–Wolf (2003) proxy, disclosed by the front door.
+    const xmkt = new Array(T);
+    if (market !== undefined) {
+        if (market.length !== T) {
+            throw new InputError(`${functionName}: market series length ${market.length} must equal the observation count T = ${T}.`, { code: ErrorCode.InputWrongShape, context: { marketLength: market.length, T } });
+        }
+        let mmean = 0;
+        for (let t = 0; t < T; t++) {
+            const v = market[t];
+            if (!Number.isFinite(v)) {
+                throw new InputError(`${functionName}: market[${t}] must be a finite number. Received ${v}.`, {
+                    code: ErrorCode.InputNotFinite,
+                    context: { index: t },
+                });
+            }
+            mmean += v;
+        }
+        mmean /= T;
+        for (let t = 0; t < T; t++)
+            xmkt[t] = market[t] - mmean;
+    }
+    else {
+        for (let t = 0; t < T; t++) {
+            let s = 0;
+            for (let i = 0; i < p; i++)
+                s += x[i][t];
+            xmkt[t] = s / p;
+        }
+    }
+    let varmkt = 0;
+    for (let t = 0; t < T; t++)
+        varmkt += xmkt[t] * xmkt[t];
+    varmkt /= T;
+    if (!(varmkt > 0)) {
+        throw new InputError(`${functionName}: the single-index target needs a non-degenerate market (Var of the equal-weighted average return is 0) — the market-model target is undefined.`, { code: ErrorCode.InputOutOfRange, context: { varmkt } });
+    }
+    // covmkt[i] = Cov(x_i, x_mkt).
+    const covmkt = new Array(p);
+    for (let i = 0; i < p; i++) {
+        let s = 0;
+        for (let t = 0; t < T; t++)
+            s += x[i][t] * xmkt[t];
+        covmkt[i] = s / T;
+    }
+    // Target F: off-diagonal from the single market factor, diagonal keeps the sample variance.
+    const F = Array.from({ length: p }, (_, i) => Array.from({ length: p }, (_, j) => (i === j ? S[i][i] : (covmkt[i] * covmkt[j]) / varmkt)));
+    // π̂ᵢⱼ = (1/T)Σₜ (xᵢₜxⱼₜ − Sᵢⱼ)²; π̂ = Σπ̂ᵢⱼ; rdiag = Σᵢ π̂ᵢᵢ. γ̂ = ‖F − S‖²_F.
+    const piHat = Array.from({ length: p }, () => new Array(p).fill(0));
+    let pi = 0;
+    let gamma = 0;
+    for (let i = 0; i < p; i++) {
+        for (let j = 0; j < p; j++) {
+            let s = 0;
+            for (let t = 0; t < T; t++) {
+                const d = x[i][t] * x[j][t] - S[i][j];
+                s += d * d;
+            }
+            piHat[i][j] = s / T;
+            pi += s / T;
+            const g = F[i][j] - S[i][j];
+            gamma += g * g;
+        }
+    }
+    let rdiag = 0;
+    for (let i = 0; i < p; i++)
+        rdiag += piHat[i][i];
+    // roff₁ = (1/varmkt)Σ_{i≠j} v1ᵢⱼ·covmktⱼ,  v1ᵢⱼ = (1/T)Σₜ xᵢₜ²·xⱼₜ·x_mkt,t − covmktᵢ·Sᵢⱼ.
+    // roff₃ = (1/varmkt²)Σ_{i≠j} v3ᵢⱼ·covmktᵢ·covmktⱼ,  v3ᵢⱼ = (1/T)Σₜ xᵢₜxⱼₜ·x_mkt,t² − varmkt·Sᵢⱼ.
+    let roff1 = 0;
+    let roff3 = 0;
+    for (let i = 0; i < p; i++) {
+        for (let j = 0; j < p; j++) {
+            if (i === j)
+                continue;
+            let s1 = 0;
+            let s3 = 0;
+            for (let t = 0; t < T; t++) {
+                const xi = x[i][t];
+                const xj = x[j][t];
+                const mkt = xmkt[t];
+                s1 += xi * xi * xj * mkt;
+                s3 += xi * xj * mkt * mkt;
+            }
+            const v1 = s1 / T - covmkt[i] * S[i][j];
+            const v3 = s3 / T - varmkt * S[i][j];
+            roff1 += v1 * covmkt[j];
+            roff3 += v3 * covmkt[i] * covmkt[j];
+        }
+    }
+    roff1 /= varmkt;
+    roff3 /= varmkt * varmkt;
+    const rho = rdiag + 2 * roff1 - roff3;
+    const kappa = gamma > 0 ? (pi - rho) / gamma : 0;
+    const delta = Math.max(0, Math.min(1, kappa / T));
+    // Σ* = δ·F + (1−δ)·S.
+    const covariance = S.map((row, i) => row.map((v, j) => delta * F[i][j] + (1 - delta) * v));
+    return {
+        covariance,
+        shrinkage: delta,
+        sampleCovariance: S,
+        averageVariance: mu,
+        observations: T,
+        target: 'single-index',
+        marketVariance: varmkt,
+    };
+}
+/** Eigenvalue conditioning of a symmetric matrix. */
+function conditioning(M) {
+    const { values } = jacobiEigen(M);
+    const min = Math.min(...values);
+    const max = Math.max(...values);
+    const cond = min > 0 ? max / min : Infinity;
+    const spd = min > 1e-12 * max;
+    const effectiveRank = values.filter((v) => v > 1e-9 * max).length;
+    return { min, max, cond, spd, effectiveRank };
+}
+/**
+ * The exponentially-weighted (RiskMetrics) covariance of a `p × T` chronological series (oldest first).
+ * Weights `wₜ ∝ λ^{(T−1)−t}` (newest weighted most) normalized to sum 1; demeaned with the EWMA-weighted
+ * mean; `population` selects the biased (`c = 1`) or unbiased weighted-covariance (`c = 1/(1 − Σwₜ²)`)
+ * normalization. Returns the covariance and the Kish effective sample size `1/Σwₜ²`.
+ */
+function ewmaCovariance(series, lambda, population) {
+    const p = series.length;
+    const T = series[0].length;
+    const w = new Array(T);
+    let wsum = 0;
+    for (let t = 0; t < T; t++) {
+        w[t] = Math.pow(lambda, T - 1 - t);
+        wsum += w[t];
+    }
+    let w2 = 0;
+    for (let t = 0; t < T; t++) {
+        w[t] /= wsum;
+        w2 += w[t] * w[t];
+    }
+    const mean = series.map((row) => {
+        let m = 0;
+        for (let t = 0; t < T; t++)
+            m += w[t] * row[t];
+        return m;
+    });
+    const c = population ? 1 : 1 / (1 - w2);
+    const covariance = Array.from({ length: p }, () => new Array(p).fill(0));
+    for (let i = 0; i < p; i++) {
+        for (let j = i; j < p; j++) {
+            let s = 0;
+            for (let t = 0; t < T; t++)
+                s += w[t] * (series[i][t] - mean[i]) * (series[j][t] - mean[j]);
+            covariance[i][j] = s * c;
+            covariance[j][i] = covariance[i][j];
+        }
+    }
+    return { covariance, effectiveObservations: 1 / w2 };
+}
+/**
+ * The covariance-estimation front door: turn a returns matrix into a well-conditioned (usually
+ * invertible) covariance and report its **conditioning** so a caller knows whether it is safe to invert.
+ * `'sample'` and `'ewma'` are the raw estimators (never altered; flagged + `converged: false` when
+ * singular); `'ledoit-wolf'` and `'ridge'` GUARANTEE an SPD result — degenerate/collinear inputs are
+ * eigenvalue-floored with a `math.covariance_floored` warning rather than returned singular; `'auto'`
+ * (default) uses the sample when it is SPD and well-conditioned, else shrinks (inheriting the SPD
+ * guarantee). `series[k]` is variable
+ * k's observations (p × T), matching {@link covarianceMatrix}. See `docs/specs/estimate-covariance.md`.
+ */
+export function estimateCovariance(series, options = {}) {
+    const functionName = 'estimateCovariance';
+    const { p, T } = validateReturnsSeries(series, functionName);
+    linalgOptionLadder('estimateCovariance', options, [
+        'method',
+        'ridge',
+        'conditionThreshold',
+        'population',
+        'lambda',
+        'halfLife',
+        'ledoitWolfTarget',
+        'market',
+    ], ['ridge', 'conditionThreshold', 'lambda', 'halfLife']);
+    if (options.method !== undefined &&
+        !['auto', 'sample', 'ledoit-wolf', 'ridge', 'ewma'].includes(options.method)) {
+        throw new InputError(`estimateCovariance: method must be auto | sample | ledoit-wolf | ridge | ewma when provided. Received ${options.method === null ? 'null' : JSON.stringify(options.method)}.`, { code: ErrorCode.InputInvalidEnum, context: { field: 'method' } });
+    }
+    if (options.population !== undefined && typeof options.population !== 'boolean') {
+        throw new InputError(`estimateCovariance: population must be a boolean when provided. Received ${options.population === null ? 'null' : typeof options.population}.`, { code: ErrorCode.InputWrongType, context: { field: 'population' } });
+    }
+    if (options.ledoitWolfTarget !== undefined &&
+        !['identity', 'constant-correlation', 'single-index'].includes(options.ledoitWolfTarget)) {
+        throw new InputError(`estimateCovariance: ledoitWolfTarget must be identity | constant-correlation | single-index when provided. Received ${options.ledoitWolfTarget === null ? 'null' : JSON.stringify(options.ledoitWolfTarget)}.`, { code: ErrorCode.InputInvalidEnum, context: { field: 'ledoitWolfTarget' } });
+    }
+    if (options.market !== undefined &&
+        !Array.isArray(options.market) &&
+        !ArrayBuffer.isView(options.market)) {
+        throw new InputError(`estimateCovariance: market must be an array of market returns when provided. Received ${options.market === null ? 'null' : typeof options.market}.`, { code: ErrorCode.InputWrongType, context: { field: 'market' } });
+    }
+    const method = options.method ?? 'auto';
+    const population = options.population ?? true;
+    const conditionThreshold = options.conditionThreshold ?? 1e4;
+    const sample = covarianceMatrix(series, { population });
+    const warnings = [];
+    let covariance;
+    let resolved;
+    let shrinkage;
+    let ewmaLambda;
+    let effectiveObservations;
+    if (method === 'ewma') {
+        let lambda;
+        if (options.lambda !== undefined) {
+            lambda = options.lambda;
+            if (!(lambda > 0 && lambda < 1)) {
+                throw new InputError(`${functionName}: lambda must be in (0, 1) (got ${lambda}).`, {
+                    code: ErrorCode.InputOutOfRange,
+                    context: { lambda },
+                });
+            }
+        }
+        else if (options.halfLife !== undefined) {
+            if (!(options.halfLife > 0)) {
+                throw new InputError(`${functionName}: halfLife must be > 0 (got ${options.halfLife}).`, {
+                    code: ErrorCode.InputOutOfRange,
+                    context: { halfLife: options.halfLife },
+                });
+            }
+            lambda = Math.pow(2, -1 / options.halfLife);
+        }
+        else {
+            lambda = 0.94; // RiskMetrics default
+        }
+        const ewma = ewmaCovariance(series, lambda, population);
+        covariance = ewma.covariance;
+        resolved = 'ewma';
+        ewmaLambda = lambda;
+        effectiveObservations = ewma.effectiveObservations;
+        if (effectiveObservations < p) {
+            warnings.push(warning(WarningCode.MathCovarianceEwmaEffectiveSample, `${functionName}: the EWMA effective sample (${effectiveObservations.toFixed(1)}) is below the ${p} variables (λ = ${lambda.toFixed(3)}) — the estimate is noisy; raise λ or add history.`, 'warn', { effectiveObservations, variables: p, lambda }));
+        }
+    }
+    else if (method === 'ridge') {
+        const ridge = options.ridge ?? 0.1;
+        if (!(ridge > 0)) {
+            throw new InputError(`${functionName}: ridge must be > 0 (got ${ridge}).`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { ridge },
+            });
+        }
+        let averageVar = 0;
+        for (let i = 0; i < p; i++)
+            averageVar += sample[i][i];
+        averageVar /= p;
+        const lambda = ridge * averageVar;
+        covariance = sample.map((row, i) => row.map((v, j) => (i === j ? v + lambda : v)));
+        resolved = 'ridge';
+    }
+    else if (method === 'ledoit-wolf') {
+        const lw = ledoitWolfShrinkage(series, {
+            target: options.ledoitWolfTarget ?? 'identity',
+            ...(options.market !== undefined ? { market: options.market } : {}),
+        });
+        covariance = lw.covariance;
+        shrinkage = lw.shrinkage;
+        resolved = 'ledoit-wolf';
+    }
+    else if (method === 'sample') {
+        covariance = sample;
+        resolved = 'sample';
+    }
+    else {
+        // 'auto' — use the sample when it is SPD and well-conditioned, otherwise shrink.
+        const sc = conditioning(sample);
+        if (sc.spd && sc.cond <= conditionThreshold) {
+            covariance = sample;
+            resolved = 'sample';
+            warnings.push(warning(WarningCode.MathCovarianceMethodAuto, `${functionName}: the sample covariance is well-conditioned (condition number ${sc.cond.toExponential(1)} ≤ ${conditionThreshold.toExponential(0)}) — used as-is.`, 'info', { chosen: 'sample', conditionNumber: sc.cond }));
+        }
+        else {
+            const lw = ledoitWolfShrinkage(series, {
+                target: options.ledoitWolfTarget ?? 'identity',
+                ...(options.market !== undefined ? { market: options.market } : {}),
+            });
+            covariance = lw.covariance;
+            shrinkage = lw.shrinkage;
+            resolved = 'ledoit-wolf';
+            warnings.push(warning(WarningCode.MathCovarianceMethodAuto, `${functionName}: the sample covariance is ${sc.spd ? `ill-conditioned (condition number ${sc.cond.toExponential(1)})` : 'singular'} — shrank to Ledoit–Wolf (δ = ${lw.shrinkage.toFixed(3)}).`, 'info', { chosen: 'ledoit-wolf', sampleSpd: sc.spd, sampleCondition: sc.cond }));
+        }
+    }
+    let cond = conditioning(covariance);
+    // The front door's postcondition (Law 7 / spec P2.2): the SPD-PROMISING methods ('ledoit-wolf',
+    // 'ridge' — and 'auto' when it resolves to them) always return an SPD covariance. Degenerate
+    // inputs (constant series → zero matrix, perfectly collinear variables → singular shrunk
+    // target) get a documented eigenvalue floor — Σ' = Σ + bump·I — plus a warning, never a silent
+    // `isPositiveDefinite: false` "success". The explicitly-RAW estimators ('sample', 'ewma') are
+    // never altered: they flag singularity honestly and report `converged: false` instead.
+    if ((resolved === 'ledoit-wolf' || resolved === 'ridge') && !cond.spd) {
+        let averageVar = 0;
+        for (let i = 0; i < p; i++)
+            averageVar += covariance[i][i];
+        averageVar /= p;
+        const scale = cond.max > 0 ? cond.max : averageVar > 0 ? averageVar : 1;
+        const floor = 1e-10 * scale;
+        const minEigenvalueBefore = cond.min;
+        const bump = floor - Math.min(cond.min, 0) + floor;
+        covariance = covariance.map((row, i) => row.map((v, j) => (i === j ? v + bump : v)));
+        cond = conditioning(covariance);
+        warnings.push(warning(WarningCode.CovarianceFloored, `${functionName}: the ${resolved} covariance was not positive-definite (degenerate/collinear input) — applied an eigenvalue floor (bump ${bump.toExponential(1)}) to keep the SPD postcondition. Treat the result as regularized, not estimated.`, 'warn', { method: resolved, bump, minEigenvalueBefore }));
+    }
+    if ((resolved === 'sample' || resolved === 'ewma') && !cond.spd) {
+        warnings.push(warning(WarningCode.MathCovarianceSingular, `${functionName}: the ${resolved} covariance is singular (effective rank ${cond.effectiveRank} < ${p}; T = ${T}) — it is NOT invertible. Use method 'ledoit-wolf' or 'ridge' for an SPD estimate.`, 'warn', { effectiveRank: cond.effectiveRank, variables: p, observations: T }));
+    }
+    else if (cond.spd && cond.cond > conditionThreshold) {
+        warnings.push(warning(WarningCode.MathCovarianceIllConditioned, `${functionName}: the ${resolved} covariance is ill-conditioned (condition number ${cond.cond.toExponential(1)} > ${conditionThreshold.toExponential(0)}); inverting it amplifies estimation noise.`, 'warn', { conditionNumber: cond.cond, method: resolved }));
+    }
+    return {
+        covariance,
+        method: resolved,
+        variables: p,
+        observations: T,
+        minEigenvalue: cond.min,
+        maxEigenvalue: cond.max,
+        conditionNumber: cond.cond,
+        isPositiveDefinite: cond.spd,
+        effectiveRank: cond.effectiveRank,
+        ...(shrinkage !== undefined ? { shrinkage } : {}),
+        ...(ewmaLambda !== undefined ? { lambda: ewmaLambda } : {}),
+        ...(effectiveObservations !== undefined ? { effectiveObservations } : {}),
+        assumptions: {
+            conventionsVersion: CONVENTIONS_VERSION,
+            method: resolved,
+            population,
+            ...(resolved === 'ledoit-wolf' && (options.ledoitWolfTarget ?? 'identity') === 'single-index'
+                ? { marketProxy: options.market ? 'observed-series' : 'equal-weight' }
+                : {}),
+        },
+        diagnostics: {
+            engine: 'estimate-covariance',
+            method: resolved,
+            converged: cond.spd,
+            warnings,
+        },
+    };
+}
+/**
+ * Symmetric eigendecomposition via cyclic Jacobi rotations. The tolerance is RELATIVE to the input's
+ * off-diagonal Frobenius norm, so a matrix scaled by any constant converges identically (an absolute
+ * tolerance would spin to `maximumIterations` on a large-scaled covariance matrix). Throws `ConvergenceError`
+ * (`linalg.no_convergence`) if the sweeps do not reach the tolerance within `maximumIterations`.
+ *
+ * The input must be SQUARE and finite. It used to be neither checked nor needed: every loop is
+ * indexed by `input.length`, so a `2×3` matrix quietly returned the eigenvalues of its leading `2×2`
+ * block — the right shape, the wrong matrix, and no way for the caller to tell. (Non-symmetric square
+ * input is still accepted and still reports non-convergence through `ConvergenceError` when the
+ * rotations cannot diagonalize it; use {@link eigenvalues} for the general case.)
+ */
+export function jacobiEigen(input, options = {}) {
+    const n = input.length;
+    linalgOptionLadder('jacobiEigen', options, ['maximumIterations', 'tolerance'], ['maximumIterations', 'tolerance']);
+    requireMathIterationBudgetWhenPresent('jacobiEigen', options.maximumIterations);
+    const maximumIterations = options.maximumIterations ?? 100;
+    const tolerance = options.tolerance ?? 1e-14;
+    if (n === 0) {
+        throw new InputError('jacobiEigen: matrix must be non-empty.', {
+            code: ErrorCode.InputOutOfRange,
+            context: { rows: n },
+        });
+    }
+    for (let i = 0; i < n; i++) {
+        const row = input[i];
+        if (row.length !== n) {
+            throw new InputError(`jacobiEigen: matrix must be square (row ${i} has ${row.length} entries, expected ${n}); the eigendecomposition of a non-square matrix is undefined — use svd() for its singular values.`, { code: ErrorCode.InputOutOfRange, context: { rows: n, row: i, cols: row.length } });
+        }
+        for (let j = 0; j < n; j++) {
+            if (!Number.isFinite(row[j])) {
+                throw new InputError(`jacobiEigen: matrix[${i}][${j}] is ${row[j]}; a non-finite entry makes every eigenvalue NaN.`, { code: ErrorCode.InputNotFinite, context: { row: i, col: j, value: row[j] } });
+            }
+        }
+    }
+    const a = input.map((row) => row.slice());
+    const v = Array.from({ length: n }, (_, i) => Array.from({ length: n }, (_, j) => (i === j ? 1 : 0)));
+    // Scale the tolerance by the initial off-diagonal norm (relative convergence). A diagonal input
+    // (norm0 === 0) is already converged.
+    let norm0 = 0;
+    for (let p = 0; p < n; p++)
+        for (let q = p + 1; q < n; q++)
+            norm0 += a[p][q] * a[p][q];
+    norm0 = Math.sqrt(norm0);
+    const threshold = tolerance * (norm0 > 0 ? norm0 : 1);
+    let sweeps = 0;
+    for (; sweeps < maximumIterations; sweeps++) {
+        let off = 0;
+        for (let p = 0; p < n; p++)
+            for (let q = p + 1; q < n; q++)
+                off += a[p][q] * a[p][q];
+        if (Math.sqrt(off) <= threshold)
+            break;
+        for (let p = 0; p < n; p++) {
+            for (let q = p + 1; q < n; q++) {
+                const apq = a[p][q];
+                if (apq === 0)
+                    continue;
+                const tau = (a[q][q] - a[p][p]) / (2 * apq);
+                const t = Math.sign(tau || 1) / (Math.abs(tau) + Math.sqrt(1 + tau * tau));
+                const c = 1 / Math.sqrt(1 + t * t);
+                const s = t * c;
+                for (let i = 0; i < n; i++) {
+                    const aip = a[i][p];
+                    const aiq = a[i][q];
+                    a[i][p] = c * aip - s * aiq;
+                    a[i][q] = s * aip + c * aiq;
+                }
+                for (let i = 0; i < n; i++) {
+                    const api = a[p][i];
+                    const aqi = a[q][i];
+                    a[p][i] = c * api - s * aqi;
+                    a[q][i] = s * api + c * aqi;
+                }
+                for (let i = 0; i < n; i++) {
+                    const vip = v[i][p];
+                    const viq = v[i][q];
+                    v[i][p] = c * vip - s * viq;
+                    v[i][q] = s * vip + c * viq;
+                }
+            }
+        }
+    }
+    // Honest convergence check on the final matrix: if the sweeps ran out before the off-diagonal norm
+    // fell under the (relative) threshold, report it rather than returning silently-wrong eigenvalues.
+    let finalOff = 0;
+    for (let p = 0; p < n; p++)
+        for (let q = p + 1; q < n; q++)
+            finalOff += a[p][q] * a[p][q];
+    if (Math.sqrt(finalOff) > threshold) {
+        throw new ConvergenceError('jacobiEigen: Jacobi rotations did not converge within maximumIterations.', {
+            code: ErrorCode.LinalgNoConvergence,
+            context: { iterations: sweeps, offDiagNorm: Math.sqrt(finalOff), threshold },
+        });
+    }
+    const values = a.map((row, i) => row[i]);
+    return { values, vectors: v };
+}
+function reconstruct(values, vectors) {
+    const n = values.length;
+    const out = Array.from({ length: n }, () => new Array(n).fill(0));
+    for (let i = 0; i < n; i++) {
+        for (let j = 0; j < n; j++) {
+            let s = 0;
+            for (let k = 0; k < n; k++)
+                s += vectors[i][k] * values[k] * vectors[j][k];
+            out[i][j] = s;
+        }
+    }
+    return out;
+}
+/** Nearest positive-semidefinite matrix (eigenvalue clipping). */
+export function nearestPsd(matrix) {
+    const { values, vectors } = jacobiEigen(matrix);
+    const clipped = values.map((v) => Math.max(v, 0));
+    return reconstruct(clipped, vectors);
+}
+/**
+ * A valid correlation matrix near `matrix`: ONE eigenvalue-clipping pass to PSD ({@link nearestPsd}),
+ * then a rescale to a unit diagonal.
+ *
+ * Not the Frobenius-NEAREST correlation matrix. That is Higham's (2002) alternating-projections
+ * problem, iterated to convergence between the PSD cone and the unit-diagonal set; the rescale here
+ * is a single projection that can push the result slightly off the PSD cone again (the output is PSD
+ * to within the rescale, not by construction). It is the standard cheap repair — good enough to make
+ * a noisy correlation estimate usable for Cholesky/simulation — and it is deterministic and O(n³),
+ * but a caller who needs the true minimizer needs Higham's iteration, not this.
+ */
+export function nearestCorrelation(matrix) {
+    const psd = nearestPsd(matrix);
+    const n = psd.length;
+    const d = new Array(n);
+    for (let i = 0; i < n; i++)
+        d[i] = psd[i][i] > 0 ? 1 / Math.sqrt(psd[i][i]) : 0;
+    const out = Array.from({ length: n }, () => new Array(n).fill(0));
+    for (let i = 0; i < n; i++) {
+        for (let j = 0; j < n; j++) {
+            out[i][j] = i === j ? 1 : d[i] * psd[i][j] * d[j];
+        }
+    }
+    return out;
+}
+// ───────────────────────── basic matrix algebra (spec §8.3) ─────────────────────────
+/** The `n × n` identity matrix. */
+export function identity(size) {
+    return Array.from({ length: size }, (_, i) => Array.from({ length: size }, (_, j) => (i === j ? 1 : 0)));
+}
+/** Transpose of an `m × n` matrix → `n × m`. */
+export function transpose(matrix) {
+    const m = matrix.length;
+    const n = matrix[0]?.length ?? 0;
+    const out = Array.from({ length: n }, () => new Array(m).fill(0));
+    for (let i = 0; i < m; i++)
+        for (let j = 0; j < n; j++)
+            out[j][i] = matrix[i][j];
+    return out;
+}
+/** Matrix product `A (m×k) · B (k×n)` → `m×n`. Throws on a dimension mismatch. */
+export function matrixMultiply(left, right) {
+    const m = left.length;
+    const k = left[0]?.length ?? 0;
+    const k2 = right.length;
+    const n = right[0]?.length ?? 0;
+    if (k !== k2) {
+        throw new InputError(`matrixMultiply: inner dimensions disagree (${k} vs ${k2}).`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { aCols: k, bRows: k2 },
+        });
+    }
+    const out = Array.from({ length: m }, () => new Array(n).fill(0));
+    for (let i = 0; i < m; i++) {
+        for (let p = 0; p < k; p++) {
+            const aip = left[i][p];
+            if (aip === 0)
+                continue;
+            const brow = right[p];
+            const orow = out[i];
+            for (let j = 0; j < n; j++)
+                orow[j] += aip * brow[j];
+        }
+    }
+    return out;
+}
+/** Matrix–vector product `A (m×n) · x (n)` → `m`. */
+export function matrixVectorProduct(matrix, vector) {
+    const m = matrix.length;
+    const n = matrix[0]?.length ?? 0;
+    if (vector.length !== n) {
+        throw new InputError(`matrixVectorProduct: the matrix has ${n} columns but the vector has length ${vector.length}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { cols: n, vectorLength: vector.length },
+        });
+    }
+    const out = new Array(m).fill(0);
+    for (let i = 0; i < m; i++) {
+        let s = 0;
+        const row = matrix[i];
+        for (let j = 0; j < n; j++)
+            s += row[j] * vector[j];
+        out[i] = s;
+    }
+    return out;
+}
+/** LU decomposition with partial pivoting: `P·A = L·U`. Throws on a singular matrix. */
+export function luDecompose(matrix) {
+    const n = matrix.length;
+    if (n === 0 || (matrix[0]?.length ?? 0) !== n) {
+        throw new InputError('luDecompose: a non-empty square matrix is required.', {
+            code: ErrorCode.InputOutOfRange,
+            context: { rows: n, cols: matrix[0]?.length ?? 0 },
+        });
+    }
+    const lu = matrix.map((row) => row.slice());
+    const pivotIndices = Array.from({ length: n }, (_, i) => i);
+    let sign = 1;
+    for (let k = 0; k < n; k++) {
+        let p = k;
+        let max = Math.abs(lu[k][k]);
+        for (let i = k + 1; i < n; i++) {
+            const v = Math.abs(lu[i][k]);
+            if (v > max) {
+                max = v;
+                p = i;
+            }
+        }
+        if (max === 0) {
+            throw new InputError(`luDecompose: matrix is singular (zero pivot at ${k}).`, {
+                code: ErrorCode.LinalgSingular,
+                context: { index: k },
+            });
+        }
+        if (p !== k) {
+            const tmp = lu[k];
+            lu[k] = lu[p];
+            lu[p] = tmp;
+            const tp = pivotIndices[k];
+            pivotIndices[k] = pivotIndices[p];
+            pivotIndices[p] = tp;
+            sign = -sign;
+        }
+        const pivot = lu[k][k];
+        for (let i = k + 1; i < n; i++) {
+            const f = (lu[i][k] /= pivot);
+            for (let j = k + 1; j < n; j++)
+                lu[i][j] -= f * lu[k][j];
+        }
+    }
+    return { lu, pivotIndices, sign };
+}
+const LU_RESULT_KEYS = ['lu', 'pivotIndices', 'sign'];
+/**
+ * A closed structural guard for an `LuResult` handed BACK to the library: the factors must be a
+ * square finite matrix, the permutation a valid index list of the same order, the sign ±1. A
+ * decomposition edited by hand is refused with the field named, never solved into nonsense.
+ */
+function requireLuResult(functionName, result) {
+    const refuse = (message, field, code = ErrorCode.InputWrongType) => {
+        throw new InputError(`${functionName}: ${message}`, {
+            code,
+            context: { function: functionName, field },
+        });
+    };
+    if (result === null || typeof result !== 'object' || Array.isArray(result)) {
+        refuse('result must be the LuResult returned by luDecompose ({ lu, pivotIndices, sign }).', 'result');
+    }
+    for (const key of Object.keys(result)) {
+        if (!LU_RESULT_KEYS.includes(key)) {
+            refuse(`unknown field "${key}" in result. Allowed fields: ${LU_RESULT_KEYS.join(', ')}.`, 'result', ErrorCode.InputUnknownField);
+        }
+    }
+    const { lu, pivotIndices, sign } = result;
+    if (!Array.isArray(lu) || lu.length === 0 || lu.some((row) => !Array.isArray(row))) {
+        refuse('result.lu must be a non-empty square matrix (an array of number rows).', 'result.lu');
+    }
+    const n = lu.length;
+    for (const [index, row] of lu.entries()) {
+        if (row.length !== n) {
+            refuse(`result.lu must be square: row ${index} has ${row.length} entries, expected ${n}.`, 'result.lu', ErrorCode.InputWrongShape);
+        }
+        if (row.some((value) => typeof value !== 'number'))
+            refuse(`result.lu[${index}] must contain only numbers.`, 'result.lu');
+        if (row.some((value) => !Number.isFinite(value))) {
+            refuse(`result.lu[${index}] must contain only finite numbers.`, 'result.lu', ErrorCode.InputNotFinite);
+        }
+    }
+    if (!Array.isArray(pivotIndices) || pivotIndices.length !== n) {
+        refuse(`result.pivotIndices must be an array of ${n} row indices.`, 'result.pivotIndices', Array.isArray(pivotIndices) ? ErrorCode.InputWrongShape : ErrorCode.InputWrongType);
+    }
+    for (const [index, pivot] of pivotIndices.entries()) {
+        if (typeof pivot !== 'number') {
+            refuse(`result.pivotIndices[${index}] must be a number.`, 'result.pivotIndices');
+        }
+        const row = pivot;
+        if (!Number.isInteger(row) || row < 0 || row >= n) {
+            refuse(`result.pivotIndices[${index}] must be an integer row index in [0, ${n}).`, 'result.pivotIndices', Number.isFinite(row) ? ErrorCode.InputOutOfRange : ErrorCode.InputNotFinite);
+        }
+    }
+    if (typeof sign !== 'number')
+        refuse('result.sign must be a number (+1 or -1).', 'result.sign');
+    if (sign !== 1 && sign !== -1)
+        refuse('result.sign must be +1 or -1.', 'result.sign', Number.isFinite(sign) ? ErrorCode.InputOutOfRange : ErrorCode.InputNotFinite);
+}
+/** Solve `A·x = b` from a precomputed {@link luDecompose} result. */
+export function luSolve(result, b) {
+    requireLuResult('luSolve', result);
+    const { lu, pivotIndices } = result;
+    const n = lu.length;
+    if (!Array.isArray(b) || b.some((value) => typeof value !== 'number')) {
+        throw new InputError('luSolve: b must be an array of numbers.', {
+            code: ErrorCode.InputWrongType,
+            context: { function: 'luSolve', field: 'b' },
+        });
+    }
+    if (b.some((value) => !Number.isFinite(value))) {
+        throw new InputError('luSolve: b must contain only finite numbers.', {
+            code: ErrorCode.InputNotFinite,
+            context: { function: 'luSolve', field: 'b' },
+        });
+    }
+    if (b.length !== n) {
+        throw new InputError(`luSolve: b has ${b.length} entries but the system is ${n}×${n}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { expected: n, received: b.length },
+        });
+    }
+    const y = new Array(n).fill(0);
+    for (let i = 0; i < n; i++) {
+        let s = b[pivotIndices[i]];
+        for (let j = 0; j < i; j++)
+            s -= lu[i][j] * y[j];
+        y[i] = s;
+    }
+    const x = new Array(n).fill(0);
+    for (let i = n - 1; i >= 0; i--) {
+        let s = y[i];
+        for (let j = i + 1; j < n; j++)
+            s -= lu[i][j] * x[j];
+        x[i] = s / lu[i][i];
+    }
+    return x;
+}
+/** Determinant via LU; returns 0 for a singular matrix instead of throwing. */
+export function determinant(matrix) {
+    let result;
+    try {
+        result = luDecompose(matrix);
+    }
+    catch {
+        return 0;
+    }
+    let det = result.sign;
+    const n = result.lu.length;
+    for (let i = 0; i < n; i++)
+        det *= result.lu[i][i];
+    return det;
+}
+/** Householder QR of an `m × n` matrix (`m ≥ n`): `A = Q·R`, `Q` thin with orthonormal columns. */
+export function qrDecompose(matrix) {
+    const m = matrix.length;
+    const n = matrix[0]?.length ?? 0;
+    if (m < n) {
+        throw new InputError(`qrDecompose: requires m ≥ n (got ${m}×${n}).`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { rows: m, cols: n },
+        });
+    }
+    const R = matrix.map((row) => row.slice());
+    const Q = identity(m);
+    for (let k = 0; k < n; k++) {
+        // Householder vector for column k below the diagonal.
+        let norm = 0;
+        for (let i = k; i < m; i++)
+            norm += R[i][k] * R[i][k];
+        norm = Math.sqrt(norm);
+        if (norm === 0)
+            continue;
+        const alpha = R[k][k] > 0 ? -norm : norm;
+        const v = new Array(m).fill(0);
+        v[k] = R[k][k] - alpha;
+        for (let i = k + 1; i < m; i++)
+            v[i] = R[i][k];
+        let vNorm2 = 0;
+        for (let i = k; i < m; i++)
+            vNorm2 += v[i] * v[i];
+        if (vNorm2 === 0)
+            continue;
+        // Apply (I − 2 v vᵀ / vᵀv) to R (columns k..n-1) and to Q (all columns).
+        for (let j = k; j < n; j++) {
+            let dot = 0;
+            for (let i = k; i < m; i++)
+                dot += v[i] * R[i][j];
+            const f = (2 * dot) / vNorm2;
+            for (let i = k; i < m; i++)
+                R[i][j] -= f * v[i];
+        }
+        for (let j = 0; j < m; j++) {
+            let dot = 0;
+            for (let i = k; i < m; i++)
+                dot += v[i] * Q[i][j];
+            const f = (2 * dot) / vNorm2;
+            for (let i = k; i < m; i++)
+                Q[i][j] -= f * v[i];
+        }
+    }
+    // Thin Q (first n columns of Qᵀ) and the n×n R block.
+    const qThin = Array.from({ length: m }, () => new Array(n).fill(0));
+    for (let i = 0; i < m; i++)
+        for (let j = 0; j < n; j++)
+            qThin[i][j] = Q[j][i];
+    const rTop = Array.from({ length: n }, (_, i) => Array.from({ length: n }, (_, j) => (i <= j ? R[i][j] : 0)));
+    return { q: qThin, r: rTop };
+}
+/**
+ * Least-squares solve of `A·x ≈ b` (`m ≥ n`) via QR back-substitution.
+ *
+ * Rejects a rank-deficient (numerically singular) system rather than silently returning zeroed or
+ * blown-up coefficients: if the smallest `|Rᵢᵢ|` pivot falls below `rcond × max|Rᵢᵢ|`, the columns
+ * of `A` are collinear and the least-squares solution is not well defined (design law #4 — no silent
+ * garbage). Raise `rcond` to reject more aggressively; lower it to admit borderline-conditioned fits.
+ */
+export function qrSolve(matrix, b, options = {}) {
+    if (b.length !== matrix.length) {
+        throw new InputError(`qrSolve: b has ${b.length} entries but A has ${matrix.length} rows — the least-squares system needs one observation per row.`, { code: ErrorCode.InputOutOfRange, context: { rows: matrix.length, received: b.length } });
+    }
+    const { q, r } = qrDecompose(matrix);
+    const n = r.length;
+    const rcond = options.rcond ?? 1e-12;
+    // Rank check on the R diagonal: a pivot tiny relative to the largest means collinear columns.
+    let maxDiag = 0;
+    for (let i = 0; i < n; i++)
+        maxDiag = Math.max(maxDiag, Math.abs(r[i][i]));
+    for (let i = 0; i < n; i++) {
+        if (maxDiag === 0 || Math.abs(r[i][i]) <= rcond * maxDiag) {
+            throw new InputError(`qrSolve: matrix is rank-deficient (pivot ${r[i][i]} at ${i} vs max ${maxDiag}); the least-squares system is singular — check for collinear columns.`, { code: ErrorCode.LinalgSingular, context: { index: i, pivot: r[i][i], maxDiag, rcond } });
+        }
+    }
+    // Qᵀ b (n entries).
+    const qtb = new Array(n).fill(0);
+    for (let j = 0; j < n; j++) {
+        let s = 0;
+        for (let i = 0; i < q.length; i++)
+            s += q[i][j] * b[i];
+        qtb[j] = s;
+    }
+    const x = new Array(n).fill(0);
+    for (let i = n - 1; i >= 0; i--) {
+        let s = qtb[i];
+        for (let j = i + 1; j < n; j++)
+            s -= r[i][j] * x[j];
+        x[i] = s / r[i][i]; // pivot is guaranteed nonzero by the rank check above
+    }
+    return x;
+}
+/**
+ * Thin singular value decomposition `A = U·diag(s)·Vᵀ` via the one-sided Jacobi (Hestenes) method —
+ * accurate and dependency-free for the small matrices TotalFinance handles. `s` is sorted descending.
+ */
+export function svd(matrix, options = {}) {
+    linalgOptionLadder('svd', options, ['maxSweeps', 'tolerance'], ['maxSweeps', 'tolerance']);
+    const m0 = matrix.length;
+    const n0 = matrix[0]?.length ?? 0;
+    const transposed = m0 < n0;
+    // Work on a tall matrix; if A is wide, factor Aᵀ and swap U/V at the end.
+    const W = transposed ? transpose(matrix) : matrix.map((row) => row.slice());
+    const m = W.length;
+    const n = W[0]?.length ?? 0;
+    const maxSweeps = options.maxSweeps ?? 60;
+    const tolerance = options.tolerance ?? 1e-14;
+    const U = W.map((row) => row.slice()); // m × n, columns get orthogonalized in place
+    const V = identity(n);
+    let converged = false;
+    let offMax = 0;
+    for (let sweep = 0; sweep < maxSweeps; sweep++) {
+        offMax = 0;
+        for (let i = 0; i < n - 1; i++) {
+            for (let j = i + 1; j < n; j++) {
+                let alpha = 0;
+                let beta = 0;
+                let gamma = 0;
+                for (let k = 0; k < m; k++) {
+                    const uki = U[k][i];
+                    const ukj = U[k][j];
+                    alpha += uki * uki;
+                    beta += ukj * ukj;
+                    gamma += uki * ukj;
+                }
+                offMax = Math.max(offMax, Math.abs(gamma) / Math.sqrt(alpha * beta || 1));
+                if (Math.abs(gamma) <= tolerance * Math.sqrt(alpha * beta) || gamma === 0)
+                    continue;
+                const zeta = (beta - alpha) / (2 * gamma);
+                const t = Math.sign(zeta || 1) / (Math.abs(zeta) + Math.sqrt(1 + zeta * zeta));
+                const c = 1 / Math.sqrt(1 + t * t);
+                const s = c * t;
+                for (let k = 0; k < m; k++) {
+                    const uki = U[k][i];
+                    const ukj = U[k][j];
+                    U[k][i] = c * uki - s * ukj;
+                    U[k][j] = s * uki + c * ukj;
+                }
+                for (let k = 0; k < n; k++) {
+                    const vki = V[k][i];
+                    const vkj = V[k][j];
+                    V[k][i] = c * vki - s * vkj;
+                    V[k][j] = s * vki + c * vkj;
+                }
+            }
+        }
+        if (offMax < tolerance) {
+            converged = true;
+            break;
+        }
+    }
+    if (!converged) {
+        // Same honesty rule as jacobiEigen: never hand back a silently unconverged factorization
+        // (design law #4 — fail loudly instead of fabricating numbers).
+        throw new ConvergenceError(`svd: Jacobi sweeps did not converge within ${maxSweeps} sweeps (off-diagonal ${offMax.toExponential(2)} vs tolerance ${tolerance.toExponential(2)}). Raise options.maxSweeps or check the matrix for NaN/Infinity.`, { code: ErrorCode.LinalgNoConvergence, context: { maxSweeps, offMax, tolerance } });
+    }
+    // Singular values = column norms of U; normalize U columns.
+    const sVals = new Array(n).fill(0);
+    for (let j = 0; j < n; j++) {
+        let norm = 0;
+        for (let k = 0; k < m; k++)
+            norm += U[k][j] * U[k][j];
+        sVals[j] = Math.sqrt(norm);
+    }
+    for (let j = 0; j < n; j++) {
+        const sj = sVals[j];
+        if (sj > 0)
+            for (let k = 0; k < m; k++)
+                U[k][j] /= sj;
+    }
+    // Sort descending by singular value, permuting U and V columns to match.
+    const order = Array.from({ length: n }, (_, i) => i).sort((a, b) => sVals[b] - sVals[a]);
+    const sSorted = order.map((i) => sVals[i]);
+    const Us = Array.from({ length: m }, () => new Array(n).fill(0));
+    const Vs = Array.from({ length: n }, () => new Array(n).fill(0));
+    order.forEach((src, dst) => {
+        for (let k = 0; k < m; k++)
+            Us[k][dst] = U[k][src];
+        for (let k = 0; k < n; k++)
+            Vs[k][dst] = V[k][src];
+    });
+    return transposed ? { u: Vs, s: sSorted, v: Us } : { u: Us, s: sSorted, v: Vs };
+}
+/** Moore–Penrose pseudoinverse `A⁺` via SVD (singular values below `rcond·σ_max` are dropped). */
+export function pseudoInverse(matrix, options = {}) {
+    linalgOptionLadder('pseudoInverse', options, ['rcond'], ['rcond']);
+    const { u, s, v } = svd(matrix);
+    const rcond = options.rcond ?? 1e-12;
+    const sMax = s[0] ?? 0;
+    const cutoff = rcond * sMax;
+    const r = s.length;
+    const m = u.length;
+    const n = v.length;
+    // A⁺ = V · diag(1/s) · Uᵀ  →  (n × m).
+    const out = Array.from({ length: n }, () => new Array(m).fill(0));
+    for (let i = 0; i < n; i++) {
+        for (let j = 0; j < m; j++) {
+            let sum = 0;
+            for (let k = 0; k < r; k++) {
+                const sk = s[k];
+                if (sk <= cutoff)
+                    continue;
+                sum += (v[i][k] * u[j][k]) / sk;
+            }
+            out[i][j] = sum;
+        }
+    }
+    return out;
+}
+/** Reduce a square matrix to upper-Hessenberg form by Householder similarity (eigenvalue-preserving). */
+function toHessenberg(matrix) {
+    const n = matrix.length;
+    const H = matrix.map((row) => row.slice());
+    for (let k = 1; k < n - 1; k++) {
+        let scale = 0;
+        for (let i = k; i < n; i++)
+            scale += Math.abs(H[i][k - 1]);
+        if (scale === 0)
+            continue;
+        let h = 0;
+        const ort = new Array(n).fill(0);
+        for (let i = k; i < n; i++) {
+            ort[i] = H[i][k - 1] / scale;
+            h += ort[i] * ort[i];
+        }
+        let g = Math.sqrt(h);
+        if (ort[k] > 0)
+            g = -g;
+        h -= ort[k] * g;
+        ort[k] -= g;
+        for (let j = k; j < n; j++) {
+            let f = 0;
+            for (let i = n - 1; i >= k; i--)
+                f += ort[i] * H[i][j];
+            f /= h;
+            for (let i = k; i < n; i++)
+                H[i][j] -= f * ort[i];
+        }
+        for (let i = 0; i < n; i++) {
+            let f = 0;
+            for (let j = n - 1; j >= k; j--)
+                f += ort[j] * H[i][j];
+            f /= h;
+            for (let j = k; j < n; j++)
+                H[i][j] -= f * ort[j];
+        }
+        H[k][k - 1] = scale * g;
+        for (let i = k + 1; i < n; i++)
+            H[i][k - 1] = 0;
+    }
+    return H;
+}
+/**
+ * Eigenvalues of a general real matrix via the **Francis double-shift QR** algorithm on its Hessenberg
+ * form (the EISPACK/JAMA `hqr2` reduction to real Schur form). Returns real eigenvalues and
+ * complex-conjugate pairs. For symmetric matrices prefer {@link jacobiEigen} (which also gives vectors).
+ */
+export function eigenvalues(matrix) {
+    const n = matrix.length;
+    if (n === 0 || (matrix[0]?.length ?? 0) !== n) {
+        throw new InputError('eigenvalues: a non-empty square matrix is required.', {
+            code: ErrorCode.InputOutOfRange,
+            context: { rows: n, cols: matrix[0]?.length ?? 0 },
+        });
+    }
+    if (n === 1)
+        return [{ re: matrix[0][0], im: 0 }];
+    const H = toHessenberg(matrix);
+    const d = new Array(n).fill(0); // real parts
+    const e = new Array(n).fill(0); // imaginary parts
+    const eps = 2 ** -52;
+    let norm = 0;
+    for (let i = 0; i < n; i++)
+        for (let j = Math.max(i - 1, 0); j < n; j++)
+            norm += Math.abs(H[i][j]);
+    let nn = n - 1;
+    let exshift = 0;
+    let iter = 0;
+    let p = 0;
+    let q = 0;
+    let r = 0;
+    let s = 0;
+    let z = 0;
+    let x = 0;
+    let y = 0;
+    let w = 0;
+    while (nn >= 0) {
+        // Find a small sub-diagonal element to deflate the active block.
+        let l = nn;
+        while (l > 0) {
+            let sl = Math.abs(H[l - 1][l - 1]) + Math.abs(H[l][l]);
+            if (sl === 0)
+                sl = norm;
+            if (Math.abs(H[l][l - 1]) < eps * sl)
+                break;
+            l--;
+        }
+        if (l === nn) {
+            // One real root.
+            d[nn] = H[nn][nn] + exshift;
+            e[nn] = 0;
+            nn--;
+            iter = 0;
+        }
+        else if (l === nn - 1) {
+            // Two roots (a 2×2 block).
+            w = H[nn][nn - 1] * H[nn - 1][nn];
+            p = (H[nn - 1][nn - 1] - H[nn][nn]) / 2;
+            q = p * p + w;
+            z = Math.sqrt(Math.abs(q));
+            H[nn][nn] += exshift;
+            H[nn - 1][nn - 1] += exshift;
+            x = H[nn][nn];
+            if (q >= 0) {
+                z = p >= 0 ? p + z : p - z;
+                d[nn - 1] = x + z;
+                d[nn] = d[nn - 1];
+                if (z !== 0)
+                    d[nn] = x - w / z;
+                e[nn - 1] = 0;
+                e[nn] = 0;
+            }
+            else {
+                d[nn - 1] = x + p;
+                d[nn] = x + p;
+                e[nn - 1] = z;
+                e[nn] = -z;
+            }
+            nn -= 2;
+            iter = 0;
+        }
+        else {
+            // No convergence yet — perform a double QR sweep.
+            x = H[nn][nn];
+            y = 0;
+            w = 0;
+            if (l < nn) {
+                y = H[nn - 1][nn - 1];
+                w = H[nn][nn - 1] * H[nn - 1][nn];
+            }
+            if (iter === 10) {
+                // Exceptional shift to break a cycle.
+                exshift += x;
+                for (let i = 0; i <= nn; i++)
+                    H[i][i] -= x;
+                s = Math.abs(H[nn][nn - 1]) + Math.abs(H[nn - 1][nn - 2]);
+                x = y = 0.75 * s;
+                w = -0.4375 * s * s;
+            }
+            if (iter === 30) {
+                s = (y - x) / 2;
+                s = s * s + w;
+                if (s > 0) {
+                    s = Math.sqrt(s);
+                    if (y < x)
+                        s = -s;
+                    s = x - w / ((y - x) / 2 + s);
+                    for (let i = 0; i <= nn; i++)
+                        H[i][i] -= s;
+                    exshift += s;
+                    x = y = w = 0.964;
+                }
+            }
+            if (iter > 60) {
+                // Same failure family as jacobiEigen: linear-algebra non-convergence, not a root-find.
+                throw new ConvergenceError('eigenvalues: QR iteration did not converge.', {
+                    code: ErrorCode.LinalgNoConvergence,
+                    context: { block: nn },
+                });
+            }
+            iter++;
+            // Look for two consecutive small sub-diagonal elements.
+            let m = nn - 2;
+            while (m >= l) {
+                z = H[m][m];
+                r = x - z;
+                s = y - z;
+                p = (r * s - w) / H[m + 1][m] + H[m][m + 1];
+                q = H[m + 1][m + 1] - z - r - s;
+                r = H[m + 2][m + 1];
+                s = Math.abs(p) + Math.abs(q) + Math.abs(r);
+                p /= s;
+                q /= s;
+                r /= s;
+                if (m === l)
+                    break;
+                if (Math.abs(H[m][m - 1]) * (Math.abs(q) + Math.abs(r)) <
+                    eps *
+                        (Math.abs(p) *
+                            (Math.abs(H[m - 1][m - 1]) + Math.abs(z) + Math.abs(H[m + 1][m + 1])))) {
+                    break;
+                }
+                m--;
+            }
+            for (let i = m + 2; i <= nn; i++) {
+                H[i][i - 2] = 0;
+                if (i > m + 2)
+                    H[i][i - 3] = 0;
+            }
+            // Double QR step over rows/columns l..nn.
+            for (let k = m; k <= nn - 1; k++) {
+                const notlast = k !== nn - 1;
+                if (k !== m) {
+                    p = H[k][k - 1];
+                    q = H[k + 1][k - 1];
+                    r = notlast ? H[k + 2][k - 1] : 0;
+                    x = Math.abs(p) + Math.abs(q) + Math.abs(r);
+                    if (x !== 0) {
+                        p /= x;
+                        q /= x;
+                        r /= x;
+                    }
+                }
+                if (x === 0)
+                    break;
+                s = Math.sqrt(p * p + q * q + r * r);
+                if (p < 0)
+                    s = -s;
+                if (s !== 0) {
+                    if (k !== m)
+                        H[k][k - 1] = -s * x;
+                    else if (l !== m)
+                        H[k][k - 1] = -H[k][k - 1];
+                    p += s;
+                    x = p / s;
+                    y = q / s;
+                    z = r / s;
+                    q /= p;
+                    r /= p;
+                    for (let j = k; j < n; j++) {
+                        p = H[k][j] + q * H[k + 1][j];
+                        if (notlast) {
+                            p += r * H[k + 2][j];
+                            H[k + 2][j] -= p * z;
+                        }
+                        H[k + 1][j] -= p * y;
+                        H[k][j] -= p * x;
+                    }
+                    const iMax = Math.min(nn, k + 3);
+                    for (let i = 0; i <= iMax; i++) {
+                        p = x * H[i][k] + y * H[i][k + 1];
+                        if (notlast) {
+                            p += z * H[i][k + 2];
+                            H[i][k + 2] -= p * r;
+                        }
+                        H[i][k + 1] -= p * q;
+                        H[i][k] -= p;
+                    }
+                }
+            }
+        }
+    }
+    return d.map((re, i) => ({ re, im: e[i] }));
+}
+/** Eigenvector of `A` for a real eigenvalue `lambda`, by inverse iteration (or `null` on breakdown). */
+function eigenvectorReal(matrix, lambda) {
+    const n = matrix.length;
+    const shift = 1e-9 * (Math.abs(lambda) + 1);
+    const M = matrix.map((row, i) => row.map((v, j) => v - (i === j ? lambda + shift : 0)));
+    let lu;
+    try {
+        lu = luDecompose(M);
+    }
+    catch {
+        return null;
+    }
+    let v = new Array(n).fill(1 / Math.sqrt(n));
+    for (let iter = 0; iter < 6; iter++) {
+        const w = luSolve(lu, v);
+        let norm = 0;
+        for (const x of w)
+            norm += x * x;
+        norm = Math.sqrt(norm);
+        if (!(norm > 0) || !Number.isFinite(norm))
+            return null;
+        v = w.map((x) => x / norm);
+    }
+    // Sign convention: make the largest-magnitude component positive.
+    let mi = 0;
+    for (let i = 1; i < n; i++)
+        if (Math.abs(v[i]) > Math.abs(v[mi]))
+            mi = i;
+    if (v[mi] < 0)
+        v = v.map((x) => -x);
+    return v;
+}
+/**
+ * Eigenvalues and (for real eigenvalues) eigenvectors of a general real matrix. Eigenvalues come from
+ * the Francis QR algorithm ({@link eigenvalues}); each real eigenvalue's eigenvector is recovered by
+ * inverse iteration. Complex eigenvalues report a `null` vector in this real-valued interface.
+ */
+export function eigen(matrix) {
+    const values = eigenvalues(matrix);
+    const tolerance = 1e-9;
+    const vectors = values.map((lambda) => Math.abs(lambda.im) < tolerance ? eigenvectorReal(matrix, lambda.re) : null);
+    return { values, vectors };
+}
+//# sourceMappingURL=linalg.js.map