@insiderfinance/totalfinance 0.1.0

package/modules/volatility/dist/sticky-regime.js.map

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

package/modules/volatility/dist/surface-pca.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Volatility-surface PCA (spec: `docs/specs/surface-pca.md`, roadmap Tier 2). The package fits a surface at a
+ * point in time; this answers how it *moves*. Given a history of surface snapshots, it runs a principal-
+ * component analysis of the surface CHANGES and reports the dominant modes — the same
+ * Litterman–Scheinkman shapes as a yield curve (level / slope / curvature) — each with its variance
+ * explained and a factor-score time series, the raw material for surface risk and scenario models.
+ */
+import { type Diagnostics } from '../../core/dist/index.js';
+/** Inputs for {@link surfacePCA}. */
+export interface SurfacePcaInput {
+    /** IV snapshots over time; `snapshots[t]` is the vol vector at a FIXED set of grid points. */
+    snapshots: number[][];
+    /** Ordered grid coordinates (moneyness or tenor), one per column — used to label mode shapes. */
+    gridPoints?: number[];
+    /** How to difference consecutive snapshots; default `'absolute'`. */
+    changes?: 'absolute' | 'relative';
+    /** Retain only the top-k modes; default all (= grid size). */
+    maxComponents?: number;
+}
+/** One principal mode of surface motion. */
+export interface SurfaceMode {
+    /** The eigenvector across the grid (sign-canonicalized so the loadings sum ≥ 0). */
+    loadings: number[];
+    eigenvalue: number;
+    /** Fraction of the total change variance this mode explains. */
+    varianceExplained: number;
+    /** Shape labeled from the loadings' sign-change count along the grid. */
+    shape: 'level' | 'slope' | 'curvature' | 'higher-order';
+    /** Factor score per change observation: the projection of each centered change onto `loadings`. */
+    scores: number[];
+}
+/** Result of {@link surfacePCA}. */
+export interface SurfacePcaResult {
+    modes: SurfaceMode[];
+    /** Cumulative variance explained up to and including each mode. */
+    cumulativeVarianceExplained: number[];
+    totalVariance: number;
+    /** Number of change vectors (`snapshots.length − 1`). */
+    observations: number;
+    gridSize: number;
+    changeType: 'absolute' | 'relative';
+    assumptions: {
+        conventionsVersion: string;
+        changeType: 'absolute' | 'relative';
+        ordered: boolean;
+    };
+    diagnostics: Diagnostics;
+}
+/**
+ * Principal-component analysis of vol-surface changes: the dominant modes of surface motion
+ * (level / slope / curvature), each with its variance explained and factor-score series. See the spec.
+ */
+export declare function surfacePCA(input: SurfacePcaInput): SurfacePcaResult;
+/** Inputs for {@link surfacePcaScenarios}. */
+export interface SurfacePcaScenarioInput {
+    /** The result of {@link surfacePCA} — its modes drive the shocks. */
+    pca: SurfacePcaResult;
+    /** Current volatilities to shock, at the SAME grid points as the PCA (length = `pca.gridSize`). */
+    base: number[];
+    /** Shock magnitudes in standard deviations, applied to each mode. Default `[-1, 1]`. */
+    sigmas?: number[];
+    /** Shock only the top-N modes. Default all of `pca.modes`. */
+    maxModes?: number;
+    /** Floor for the shocked volatilities (a vol can't go negative). Default 0. */
+    floor?: number;
+    /** Optional per-mode sigma moves → one combined shocked surface. */
+    combined?: number[];
+}
+/** One shocked-surface scenario (a `sigma`-standard-deviation move along one mode). */
+export interface SurfaceScenario {
+    /** 0-indexed mode. */
+    mode: number;
+    shape: SurfaceMode['shape'];
+    sigma: number;
+    /**
+     * `sigma·√λ·loadings` — the (unclamped) surface change vector, in the PCA's own units: VOL POINTS
+     * for an `absolute` PCA, FRACTIONS of the base vol for a `relative` one.
+     */
+    shockVector: number[];
+    /**
+     * The shocked surface, floored: `max(floor, base + shockVector)` for an `absolute` PCA,
+     * `max(floor, base · (1 + shockVector))` for a `relative` one.
+     */
+    shockedSurface: number[];
+}
+/** Result of {@link surfacePcaScenarios}. */
+export interface SurfacePcaScenarios {
+    base: number[];
+    /** One per `(mode, sigma)`, in mode-major order. */
+    scenarios: SurfaceScenario[];
+    /** `base + Σ sᵢ·√λᵢ·loadingsᵢ`, floored — present only when `combined` is supplied. */
+    combinedSurface?: number[];
+    assumptions: {
+        conventionsVersion: string;
+        changeType: 'absolute' | 'relative';
+        floor: number;
+    };
+    diagnostics: Diagnostics;
+}
+/**
+ * Turn a fitted {@link surfacePCA} into **stress scenarios**: shock a base surface by `±k` standard
+ * deviations along each principal mode (`k·√λ·loadings`, since `√λ` is the mode's 1-sigma move and the
+ * loadings are unit-norm), and optionally by a combined per-mode move. Shocked volatilities are floored (default 0)
+ * so a large downside shock can't go negative.
+ *
+ * The shock is applied in the units the PCA was FITTED in (`pca.changeType`): `absolute` adds the
+ * vector to the base vols, `relative` scales them (`base·(1 + shock)`), because a relative PCA's
+ * modes are proportional moves. See `docs/specs/surface-pca-scenarios.md`.
+ */
+export declare function surfacePcaScenarios(input: SurfacePcaScenarioInput): SurfacePcaScenarios;
+//# sourceMappingURL=surface-pca.d.ts.map

package/modules/volatility/dist/surface-pca.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-pca.d.ts","sourceRoot":"","sources":["../src/surface-pca.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAGL,KAAK,WAAW,EAOjB,MAAM,0BAAoB,CAAC;AA2B5B,qCAAqC;AACrC,MAAM,WAAW,eAAe;IAC9B,8FAA8F;IAC9F,SAAS,EAAE,MAAM,EAAE,EAAE,CAAC;IACtB,iGAAiG;IACjG,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,qEAAqE;IACrE,OAAO,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IAClC,8DAA8D;IAC9D,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,4CAA4C;AAC5C,MAAM,WAAW,WAAW;IAC1B,oFAAoF;IACpF,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,yEAAyE;IACzE,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,WAAW,GAAG,cAAc,CAAC;IACxD,mGAAmG;IACnG,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,oCAAoC;AACpC,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,mEAAmE;IACnE,2BAA2B,EAAE,MAAM,EAAE,CAAC;IACtC,aAAa,EAAE,MAAM,CAAC;IACtB,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,UAAU,GAAG,UAAU,CAAC;IACpC,WAAW,EAAE;QACX,kBAAkB,EAAE,MAAM,CAAC;QAC3B,UAAU,EAAE,UAAU,GAAG,UAAU,CAAC;QACpC,OAAO,EAAE,OAAO,CAAC;KAClB,CAAC;IACF,WAAW,EAAE,WAAW,CAAC;CAC1B;AAwBD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,gBAAgB,CAsJnE;AAID,8CAA8C;AAC9C,MAAM,WAAW,uBAAuB;IACtC,qEAAqE;IACrE,GAAG,EAAE,gBAAgB,CAAC;IACtB,mGAAmG;IACnG,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,wFAAwF;IACxF,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,uFAAuF;AACvF,MAAM,WAAW,eAAe;IAC9B,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB;;;OAGG;IACH,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,6CAA6C;AAC7C,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,oDAAoD;IACpD,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,uFAAuF;IACvF,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,WAAW,EAAE;QAAE,kBAAkB,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,UAAU,GAAG,UAAU,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAChG,WAAW,EAAE,WAAW,CAAC;CAC1B;AAwBD;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,uBAAuB,GAAG,mBAAmB,CA6FvF"}

package/modules/volatility/dist/surface-pca.js

@@ -0,0 +1,297 @@
+/**
+ * Volatility-surface PCA (spec: `docs/specs/surface-pca.md`, roadmap Tier 2). The package fits a surface at a
+ * point in time; this answers how it *moves*. Given a history of surface snapshots, it runs a principal-
+ * component analysis of the surface CHANGES and reports the dominant modes — the same
+ * Litterman–Scheinkman shapes as a yield curve (level / slope / curvature) — each with its variance
+ * explained and a factor-score time series, the raw material for surface risk and scenario models.
+ */
+import { CONVENTIONS_VERSION, ErrorCode, InputError, ensureFinite, requireArgumentArray, requireArgumentObject, validateClosedRequest, } from '../../core/dist/index.js';
+import { jacobiEigen } from '../../math/dist/index.js';
+import { VALIDATION_SPECS } from './generated/validation-specs.js';
+/**
+ * Generated closed-request specs (spec 3B.1b): allowlists projected from the declarations.
+ * Resolved at module load so a stale key fails at import. Array ELEMENTS (snapshots rows, modes)
+ * keep their curated per-element checks — the spec closes the containers.
+ */
+function surfacePcaSpecOf(key) {
+    const spec = VALIDATION_SPECS[key];
+    if (spec === undefined) {
+        throw new Error(`surface-pca: no generated validation spec for '${key}' — run \`pnpm validation:update\``);
+    }
+    return spec;
+}
+const SURFACE_PCA_SPEC = surfacePcaSpecOf('surfacePCA#0');
+const SURFACE_PCA_SCENARIOS_SPEC = surfacePcaSpecOf('surfacePcaScenarios#0');
+const SURFACE_PCA_EXAMPLE = () => 'surfacePCA({ snapshots: [[0.2, 0.22], [0.21, 0.23], [0.2, 0.21]], gridPoints: [0.9, 1.1] })';
+const SURFACE_PCA_SCENARIOS_EXAMPLE = () => 'surfacePcaScenarios({ pca: surfacePCA({ snapshots }), base: [0.2, 0.22], sigmas: [-1, 1] })';
+/** Count sign changes along the loadings ordered by the grid; near-zero loadings are skipped. */
+function shapeFromLoadings(loadings, order) {
+    const peak = Math.max(...loadings.map((x) => Math.abs(x)));
+    const threshold = 0.15 * peak;
+    let changes = 0;
+    let previousSign = 0;
+    for (const idx of order) {
+        const v = loadings[idx];
+        if (Math.abs(v) < threshold)
+            continue; // ignore a wiggle near zero — not a real crossing
+        const sign = v > 0 ? 1 : -1;
+        if (previousSign !== 0 && sign !== previousSign)
+            changes++;
+        previousSign = sign;
+    }
+    return changes === 0
+        ? 'level'
+        : changes === 1
+            ? 'slope'
+            : changes === 2
+                ? 'curvature'
+                : 'higher-order';
+}
+/**
+ * Principal-component analysis of vol-surface changes: the dominant modes of surface motion
+ * (level / slope / curvature), each with its variance explained and factor-score series. See the spec.
+ */
+export function surfacePCA(input) {
+    const functionName = 'surfacePCA';
+    validateClosedRequest(functionName, input, SURFACE_PCA_SPEC, {
+        exampleCall: SURFACE_PCA_EXAMPLE,
+    });
+    const snapshots = input.snapshots;
+    const T = snapshots.length;
+    if (T < 2) {
+        throw new InputError(`${functionName}: need ≥ 2 snapshots to form a change; got ${T}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { snapshots: T },
+        });
+    }
+    requireArgumentArray(functionName, 'snapshots[0]', snapshots[0]);
+    const G = snapshots[0].length;
+    if (G < 2) {
+        throw new InputError(`${functionName}: need ≥ 2 grid points; got ${G}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { gridSize: G },
+        });
+    }
+    const changeType = input.changes ?? 'absolute';
+    if (input.gridPoints !== undefined) {
+        if (input.gridPoints.length !== G) {
+            throw new InputError(`${functionName}: gridPoints has length ${input.gridPoints.length} but each snapshot has ${G} points.`, { code: ErrorCode.InputOutOfRange, context: { gridPoints: input.gridPoints.length, G } });
+        }
+        input.gridPoints.forEach((g, i) => ensureFinite(g, `gridPoints[${i}]`, functionName));
+    }
+    const maxComponents = input.maxComponents ?? G;
+    // Safe integer (2026-08-23 review, P0): `Math.min(maxComponents, G)` below keeps the retained
+    // count data-bounded, but the count itself must be exact — above 2^53 it is not.
+    if (!Number.isSafeInteger(maxComponents) || maxComponents < 1) {
+        throw new InputError(`${functionName}: maxComponents must be a positive integer; got ${maxComponents}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { maxComponents },
+        });
+    }
+    // Build the T−1 change vectors (validating shapes and values along the way).
+    const changes = [];
+    for (let t = 1; t < T; t++) {
+        requireArgumentArray(functionName, `snapshots[${t}]`, snapshots[t]);
+        if (snapshots[t].length !== G) {
+            throw new InputError(`${functionName}: snapshots[${t}] has ${snapshots[t].length} points but snapshots[0] has ${G}.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { snapshotIndex: t, length: snapshots[t].length, G },
+            });
+        }
+        const row = new Array(G);
+        for (let i = 0; i < G; i++) {
+            const cur = snapshots[t][i];
+            const prev = snapshots[t - 1][i];
+            ensureFinite(cur, `snapshots[${t}][${i}]`, functionName);
+            ensureFinite(prev, `snapshots[${t - 1}][${i}]`, functionName);
+            if (changeType === 'relative') {
+                if (prev === 0) {
+                    throw new InputError(`${functionName}: relative changes need a non-zero prior vol; snapshots[${t - 1}][${i}] = 0.`, { code: ErrorCode.InputOutOfRange, context: { snapshotIndex: t - 1, i } });
+                }
+                row[i] = (cur - prev) / prev;
+            }
+            else {
+                row[i] = cur - prev;
+            }
+        }
+        changes.push(row);
+    }
+    const m = changes.length; // T − 1
+    // Column-center the changes.
+    const mean = new Array(G).fill(0);
+    for (const row of changes)
+        for (let i = 0; i < G; i++)
+            mean[i] += row[i] / m;
+    const centered = changes.map((row) => row.map((v, i) => v - mean[i]));
+    // G×G covariance of the centered changes.
+    const covariance = Array.from({ length: G }, () => new Array(G).fill(0));
+    const denom = m > 1 ? m - 1 : 1;
+    for (const row of centered) {
+        for (let i = 0; i < G; i++) {
+            for (let j = i; j < G; j++) {
+                covariance[i][j] += (row[i] * row[j]) / denom;
+            }
+        }
+    }
+    for (let i = 0; i < G; i++)
+        for (let j = i + 1; j < G; j++)
+            covariance[j][i] = covariance[i][j];
+    const { values, vectors } = jacobiEigen(covariance);
+    const order = values.map((_, i) => i).sort((a, b) => values[b] - values[a]);
+    const total = values.reduce((s, v) => s + Math.max(0, v), 0);
+    // Grid order for the shape label: indices sorted by gridPoints (or the natural column order).
+    const gridOrder = input.gridPoints !== undefined
+        ? input.gridPoints
+            .map((_, i) => i)
+            .sort((a, b) => input.gridPoints[a] - input.gridPoints[b])
+        : Array.from({ length: G }, (_, i) => i);
+    const keep = Math.min(maxComponents, G);
+    const modes = [];
+    const cumulative = [];
+    let acc = 0;
+    for (let k = 0; k < keep; k++) {
+        const col = order[k];
+        let loadings = vectors.map((rowVec) => rowVec[col]);
+        // Sign-canonicalize: orient so the loadings sum ≥ 0 (a stable, reproducible orientation).
+        const sum = loadings.reduce((s, x) => s + x, 0);
+        if (sum < 0)
+            loadings = loadings.map((x) => -x);
+        const eigenvalue = values[col];
+        const varianceExplained = total > 0 ? Math.max(0, eigenvalue) / total : 0;
+        acc += varianceExplained;
+        cumulative.push(acc);
+        const scores = centered.map((row) => {
+            let s = 0;
+            for (let i = 0; i < G; i++)
+                s += row[i] * loadings[i];
+            return s;
+        });
+        modes.push({
+            loadings,
+            eigenvalue,
+            varianceExplained,
+            shape: shapeFromLoadings(loadings, gridOrder),
+            scores,
+        });
+    }
+    return {
+        modes,
+        cumulativeVarianceExplained: cumulative,
+        totalVariance: total,
+        observations: m,
+        gridSize: G,
+        changeType,
+        assumptions: {
+            conventionsVersion: CONVENTIONS_VERSION,
+            changeType,
+            ordered: input.gridPoints !== undefined,
+        },
+        diagnostics: { engine: 'surface-pca', method: 'jacobi-eigen', converged: true, warnings: [] },
+    };
+}
+/** The 1-sigma surface change of a mode: `√max(0, eigenvalue)·loadings` (loadings are unit-norm). */
+function sigmaMove(mode, G, functionName, idx) {
+    requireArgumentObject(functionName, `pca.modes[${idx}]`, mode);
+    requireArgumentArray(functionName, `pca.modes[${idx}].loadings`, mode.loadings);
+    if (mode.loadings.length !== G) {
+        throw new InputError(`${functionName}: pca.modes[${idx}].loadings has length ${mode.loadings.length} but the grid size is ${G}.`, { code: ErrorCode.InputOutOfRange, context: { index: idx, length: mode.loadings.length, G } });
+    }
+    ensureFinite(mode.eigenvalue, `pca.modes[${idx}].eigenvalue`, functionName);
+    mode.loadings.forEach((x, i) => ensureFinite(x, `pca.modes[${idx}].loadings[${i}]`, functionName));
+    const sd = Math.sqrt(Math.max(0, mode.eigenvalue));
+    return mode.loadings.map((x) => sd * x);
+}
+/**
+ * Turn a fitted {@link surfacePCA} into **stress scenarios**: shock a base surface by `±k` standard
+ * deviations along each principal mode (`k·√λ·loadings`, since `√λ` is the mode's 1-sigma move and the
+ * loadings are unit-norm), and optionally by a combined per-mode move. Shocked volatilities are floored (default 0)
+ * so a large downside shock can't go negative.
+ *
+ * The shock is applied in the units the PCA was FITTED in (`pca.changeType`): `absolute` adds the
+ * vector to the base vols, `relative` scales them (`base·(1 + shock)`), because a relative PCA's
+ * modes are proportional moves. See `docs/specs/surface-pca-scenarios.md`.
+ */
+export function surfacePcaScenarios(input) {
+    const functionName = 'surfacePcaScenarios';
+    validateClosedRequest(functionName, input, SURFACE_PCA_SCENARIOS_SPEC, {
+        exampleCall: SURFACE_PCA_SCENARIOS_EXAMPLE,
+    });
+    if (input.pca.modes.length === 0) {
+        throw new InputError(`${functionName}: pca.modes must have at least one mode.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { modes: 0 },
+        });
+    }
+    const G = input.base.length;
+    if (G < 1) {
+        throw new InputError(`${functionName}: base must be a non-empty array.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { base: 0 },
+        });
+    }
+    input.base.forEach((v, i) => ensureFinite(v, `base[${i}]`, functionName));
+    const sigmas = input.sigmas ?? [-1, 1];
+    sigmas.forEach((s, i) => ensureFinite(s, `sigmas[${i}]`, functionName));
+    const maxModes = input.maxModes ?? input.pca.modes.length;
+    // Safe integer (2026-08-23 review, P0): `Math.min(maxModes, modes.length)` below keeps the
+    // scenario count data-bounded, but the count itself must be exact — above 2^53 it is not.
+    if (!Number.isSafeInteger(maxModes) || maxModes < 1) {
+        throw new InputError(`${functionName}: maxModes must be a positive integer; got ${maxModes}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { maxModes },
+        });
+    }
+    const nModes = Math.min(maxModes, input.pca.modes.length);
+    const floor = input.floor ?? 0;
+    // Apply a shock in the SAME space the PCA was run in. A `relative` PCA differenced
+    // `(σₜ − σₜ₋₁)/σₜ₋₁`, so its loadings — and therefore `√λ·loadings` — are FRACTIONS, not vol
+    // points: adding 0.12 to a 0.30 vol when the mode says "+12%" gave 0.42 instead of 0.336, and the
+    // error grows with the base vol (a 1.00 vol moved by the same 0.12 either way).
+    const relative = input.pca.changeType === 'relative';
+    const applyShock = (shock) => input.base.map((v, i) => Math.max(floor, relative ? v * (1 + shock[i]) : v + shock[i]));
+    const scenarios = [];
+    for (let k = 0; k < nModes; k++) {
+        const mode = input.pca.modes[k];
+        const move = sigmaMove(mode, G, functionName, k); // √λ·loadings
+        for (const sigma of sigmas) {
+            const shockVector = move.map((x) => sigma * x);
+            scenarios.push({
+                mode: k,
+                shape: mode.shape,
+                sigma,
+                shockVector,
+                shockedSurface: applyShock(shockVector),
+            });
+        }
+    }
+    const result = {
+        base: [...input.base],
+        scenarios,
+        assumptions: {
+            conventionsVersion: CONVENTIONS_VERSION,
+            changeType: input.pca.changeType,
+            floor,
+        },
+        diagnostics: {
+            engine: 'surface-pca-scenarios',
+            method: 'mode-sigma-shock',
+            converged: true,
+            warnings: [],
+        },
+    };
+    if (input.combined !== undefined) {
+        if (input.combined.length > input.pca.modes.length) {
+            throw new InputError(`${functionName}: combined has ${input.combined.length} entries but there are only ${input.pca.modes.length} modes.`, { code: ErrorCode.InputOutOfRange, context: { combined: input.combined.length } });
+        }
+        const shock = new Array(G).fill(0);
+        input.combined.forEach((s, k) => {
+            ensureFinite(s, `combined[${k}]`, functionName);
+            const move = sigmaMove(input.pca.modes[k], G, functionName, k);
+            for (let i = 0; i < G; i++)
+                shock[i] += s * move[i];
+        });
+        result.combinedSurface = applyShock(shock);
+    }
+    return result;
+}
+//# sourceMappingURL=surface-pca.js.map

package/modules/volatility/dist/surface-pca.js.map

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