@fullstackcraftllc/floe 0.0.13 → 0.0.14

package/dist/pressure/grid.js

@@ -0,0 +1,220 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculatePressureAt = calculatePressureAt;
+exports.buildPressureGrid = buildPressureGrid;
+const types_1 = require("../types");
+const regime_1 = require("./regime");
+/**
+ * Calculate hedging pressure at a specific (spot, time) point
+ */
+function calculatePressureAt(spot, timeToExpiry, exposures, regimeParams) {
+    const { expectedDailySpotMove, expectedDailyVolMove, impliedSpotVolCorr, regime } = regimeParams;
+    let gammaFlow = 0;
+    let vannaFlow = 0;
+    let charmFlow = 0;
+    for (const strike of exposures.strikeExposures) {
+        const gammaContrib = strike.gammaExposure * Math.pow(expectedDailySpotMove, 2);
+        gammaFlow += gammaContrib;
+        const corrAmplifier = 1 + Math.abs(impliedSpotVolCorr);
+        const vannaContrib = strike.vannaExposure * expectedDailySpotMove * expectedDailyVolMove * corrAmplifier;
+        vannaFlow += vannaContrib;
+        const daysToExpiry = timeToExpiry * 252;
+        const charmContrib = strike.charmExposure * Math.min(daysToExpiry, 1);
+        charmFlow += charmContrib;
+    }
+    const netPressure = gammaFlow + vannaFlow + charmFlow;
+    const regimeWeights = {
+        calm: { gamma: 0.3, vanna: 0.1, charm: 0.6 },
+        normal: { gamma: 0.4, vanna: 0.2, charm: 0.4 },
+        stressed: { gamma: 0.35, vanna: 0.4, charm: 0.25 },
+        crisis: { gamma: 0.25, vanna: 0.6, charm: 0.15 },
+    };
+    const w = regimeWeights[regime];
+    const effectivePressure = gammaFlow * w.gamma + vannaFlow * w.vanna + charmFlow * w.charm;
+    let direction = 'neutral';
+    const threshold = Math.abs(effectivePressure) * 0.1;
+    if (effectivePressure > threshold) {
+        direction = 'supportive';
+    }
+    else if (effectivePressure < -threshold) {
+        direction = 'resistive';
+    }
+    const hoursRemaining = timeToExpiry * 252 * 6.5;
+    return {
+        spot,
+        timeToExpiry,
+        hoursRemaining,
+        gammaFlow,
+        vannaFlow,
+        charmFlow,
+        netPressure,
+        effectivePressure,
+        direction,
+    };
+}
+/**
+ * Build a complete pressure grid for visualization
+ */
+function buildPressureGrid(symbol, chain, exposures, ivSurface, options = {}) {
+    const { spotRangePercent = 2, spotStepPercent = 0.1, timeStepMinutes = 15, } = options;
+    const spot = chain.spot;
+    const expiration = exposures.expiration;
+    const timeToExpiry = (expiration - Date.now()) / types_1.MILLISECONDS_PER_YEAR;
+    const regimeParams = (0, regime_1.deriveRegimeParams)(ivSurface, spot);
+    const spotMin = spot * (1 - spotRangePercent / 100);
+    const spotMax = spot * (1 + spotRangePercent / 100);
+    const spotStep = spot * (spotStepPercent / 100);
+    const hoursRemaining = timeToExpiry * 252 * 6.5;
+    const timeMin = 0;
+    const timeMax = Math.max(hoursRemaining, 0.25);
+    const timeStep = timeStepMinutes / 60;
+    const cells = [];
+    const spotLevels = [];
+    const timeLevels = [];
+    for (let s = spotMin; s <= spotMax; s += spotStep) {
+        spotLevels.push(s);
+    }
+    for (let t = timeMax; t >= timeMin; t -= timeStep) {
+        timeLevels.push(t);
+    }
+    for (let i = 0; i < spotLevels.length; i++) {
+        cells[i] = [];
+        const s = spotLevels[i];
+        for (let j = 0; j < timeLevels.length; j++) {
+            const hoursLeft = timeLevels[j];
+            const t = hoursLeft / (252 * 6.5);
+            const pressure = calculatePressureAt(s, t, exposures, regimeParams);
+            cells[i][j] = {
+                spot: s,
+                hoursRemaining: hoursLeft,
+                pressure,
+                spotGradient: 0,
+                timeGradient: 0,
+            };
+        }
+    }
+    computeGradients(cells, spotStep, timeStep);
+    const keyLevels = findKeyLevels(cells, spotLevels, exposures);
+    const pathOfLeastResistance = computePathOfLeastResistance(cells, spotLevels, spot);
+    return {
+        symbol,
+        expiration,
+        currentSpot: spot,
+        timestamp: Date.now(),
+        regime: regimeParams.regime,
+        spotRange: { min: spotMin, max: spotMax, step: spotStep },
+        timeRange: { min: timeMin, max: timeMax, step: timeStep },
+        cells,
+        keyLevels,
+        pathOfLeastResistance,
+    };
+}
+function computeGradients(cells, spotStep, timeStep) {
+    const numSpot = cells.length;
+    const numTime = cells[0]?.length ?? 0;
+    for (let i = 0; i < numSpot; i++) {
+        for (let j = 0; j < numTime; j++) {
+            if (i > 0 && i < numSpot - 1) {
+                cells[i][j].spotGradient =
+                    (cells[i + 1][j].pressure.effectivePressure - cells[i - 1][j].pressure.effectivePressure) /
+                        (2 * spotStep);
+            }
+            if (j > 0 && j < numTime - 1) {
+                cells[i][j].timeGradient =
+                    (cells[i][j + 1].pressure.effectivePressure - cells[i][j - 1].pressure.effectivePressure) /
+                        (2 * timeStep);
+            }
+        }
+    }
+}
+function findKeyLevels(cells, spotLevels, exposures) {
+    const support = [];
+    const resistance = [];
+    const pinning = [];
+    let gammaFlip = null;
+    const currentSlice = cells.map(row => row[0]);
+    for (let i = 1; i < currentSlice.length; i++) {
+        const prev = currentSlice[i - 1].pressure.effectivePressure;
+        const curr = currentSlice[i].pressure.effectivePressure;
+        if (prev < 0 && curr >= 0) {
+            support.push((spotLevels[i - 1] + spotLevels[i]) / 2);
+        }
+        else if (prev >= 0 && curr < 0) {
+            resistance.push((spotLevels[i - 1] + spotLevels[i]) / 2);
+        }
+    }
+    for (const strike of exposures.strikeExposures) {
+        if (strike.gammaExposure > 0 && strike.gammaExposure > exposures.totalGammaExposure * 0.1) {
+            pinning.push(strike.strikePrice);
+        }
+    }
+    return { support, resistance, pinning, gammaFlip };
+}
+function computePathOfLeastResistance(cells, spotLevels, currentSpot) {
+    let currentSpotIdx = 0;
+    let minDist = Infinity;
+    for (let i = 0; i < spotLevels.length; i++) {
+        const dist = Math.abs(spotLevels[i] - currentSpot);
+        if (dist < minDist) {
+            minDist = dist;
+            currentSpotIdx = i;
+        }
+    }
+    const pressureAbove = [];
+    const pressureBelow = [];
+    for (let i = currentSpotIdx + 1; i < spotLevels.length; i++) {
+        pressureAbove.push(cells[i][0].pressure.effectivePressure);
+    }
+    for (let i = currentSpotIdx - 1; i >= 0; i--) {
+        pressureBelow.push(cells[i][0].pressure.effectivePressure);
+    }
+    const avgPressureAbove = pressureAbove.length > 0
+        ? pressureAbove.reduce((a, b) => a + b, 0) / pressureAbove.length
+        : 0;
+    const avgPressureBelow = pressureBelow.length > 0
+        ? pressureBelow.reduce((a, b) => a + b, 0) / pressureBelow.length
+        : 0;
+    const currentPressure = cells[currentSpotIdx][0].pressure.effectivePressure;
+    let direction = 'pin';
+    let targetSpot = currentSpot;
+    let confidence = 0;
+    let rationale = '';
+    if (currentPressure > 0 && Math.abs(currentPressure) > Math.abs(avgPressureAbove) &&
+        Math.abs(currentPressure) > Math.abs(avgPressureBelow)) {
+        direction = 'pin';
+        targetSpot = currentSpot;
+        confidence = Math.min(1, Math.abs(currentPressure) / (Math.abs(avgPressureAbove) + Math.abs(avgPressureBelow) + 1));
+        rationale = `Strong positive gamma at current level suggests pinning`;
+    }
+    else if (avgPressureAbove > 0 && avgPressureBelow < 0) {
+        direction = 'up';
+        for (let i = currentSpotIdx + 1; i < spotLevels.length; i++) {
+            if (cells[i][0].pressure.effectivePressure < 0) {
+                targetSpot = spotLevels[i];
+                break;
+            }
+            targetSpot = spotLevels[i];
+        }
+        confidence = Math.min(1, (avgPressureAbove - avgPressureBelow) / (Math.abs(avgPressureAbove) + Math.abs(avgPressureBelow) + 1));
+        rationale = `Supportive pressure above vs resistive below`;
+    }
+    else if (avgPressureAbove < 0 && avgPressureBelow > 0) {
+        direction = 'down';
+        for (let i = currentSpotIdx - 1; i >= 0; i--) {
+            if (cells[i][0].pressure.effectivePressure > 0) {
+                targetSpot = spotLevels[i];
+                break;
+            }
+            targetSpot = spotLevels[i];
+        }
+        confidence = Math.min(1, (avgPressureBelow - avgPressureAbove) / (Math.abs(avgPressureAbove) + Math.abs(avgPressureBelow) + 1));
+        rationale = `Resistive pressure above vs supportive below`;
+    }
+    else {
+        direction = 'pin';
+        targetSpot = currentSpot;
+        confidence = 0.3;
+        rationale = `Mixed pressure signals; defaulting to pin hypothesis`;
+    }
+    return { direction, targetSpot, confidence, rationale };
+}

package/dist/pressure/index.d.ts

@@ -0,0 +1,5 @@
+export type { MarketRegime, RegimeParams, NormalizedExposure, NormalizedExposureSummary, HedgingPressure, PressureGridCell, KeyLevels, PathOfLeastResistance, PressureGrid, StrikeIVPressure, IVSurfaceEvolution, CascadeStep, CascadeSimulation, IVPathConfig, } from './types';
+export { deriveRegimeParams, interpolateIVAtStrike } from './regime';
+export { normalizeExposures } from './normalize';
+export { calculatePressureAt, buildPressureGrid } from './grid';
+export { calculateIVPressures, predictIVSurfaceEvolution, runCascadeSimulation, analyzeIVPath, getIVPathOfLeastResistance, DEFAULT_IV_PATH_CONFIG, } from './ivpath';

package/dist/pressure/index.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_IV_PATH_CONFIG = exports.getIVPathOfLeastResistance = exports.analyzeIVPath = exports.runCascadeSimulation = exports.predictIVSurfaceEvolution = exports.calculateIVPressures = exports.buildPressureGrid = exports.calculatePressureAt = exports.normalizeExposures = exports.interpolateIVAtStrike = exports.deriveRegimeParams = void 0;
+// Regime derivation
+var regime_1 = require("./regime");
+Object.defineProperty(exports, "deriveRegimeParams", { enumerable: true, get: function () { return regime_1.deriveRegimeParams; } });
+Object.defineProperty(exports, "interpolateIVAtStrike", { enumerable: true, get: function () { return regime_1.interpolateIVAtStrike; } });
+// Exposure normalization
+var normalize_1 = require("./normalize");
+Object.defineProperty(exports, "normalizeExposures", { enumerable: true, get: function () { return normalize_1.normalizeExposures; } });
+// Pressure field
+var grid_1 = require("./grid");
+Object.defineProperty(exports, "calculatePressureAt", { enumerable: true, get: function () { return grid_1.calculatePressureAt; } });
+Object.defineProperty(exports, "buildPressureGrid", { enumerable: true, get: function () { return grid_1.buildPressureGrid; } });
+// IV path prediction
+var ivpath_1 = require("./ivpath");
+Object.defineProperty(exports, "calculateIVPressures", { enumerable: true, get: function () { return ivpath_1.calculateIVPressures; } });
+Object.defineProperty(exports, "predictIVSurfaceEvolution", { enumerable: true, get: function () { return ivpath_1.predictIVSurfaceEvolution; } });
+Object.defineProperty(exports, "runCascadeSimulation", { enumerable: true, get: function () { return ivpath_1.runCascadeSimulation; } });
+Object.defineProperty(exports, "analyzeIVPath", { enumerable: true, get: function () { return ivpath_1.analyzeIVPath; } });
+Object.defineProperty(exports, "getIVPathOfLeastResistance", { enumerable: true, get: function () { return ivpath_1.getIVPathOfLeastResistance; } });
+Object.defineProperty(exports, "DEFAULT_IV_PATH_CONFIG", { enumerable: true, get: function () { return ivpath_1.DEFAULT_IV_PATH_CONFIG; } });

package/dist/pressure/ivpath.d.ts

@@ -0,0 +1,31 @@
+import { IVSurface, ExposurePerExpiry } from '../types';
+import { RegimeParams, StrikeIVPressure, IVSurfaceEvolution, CascadeSimulation, IVPathConfig } from './types';
+export declare const DEFAULT_IV_PATH_CONFIG: IVPathConfig;
+/**
+ * Calculate IV pressure at each strike based on dealer positioning
+ */
+export declare function calculateIVPressures(ivSurface: IVSurface, exposures: ExposurePerExpiry, regimeParams: RegimeParams, spotMove: number, config?: Partial<IVPathConfig>): StrikeIVPressure[];
+/**
+ * Predict how the IV surface will evolve given dealer positioning
+ */
+export declare function predictIVSurfaceEvolution(ivSurface: IVSurface, exposures: ExposurePerExpiry, spot: number, spotMoveScenario?: number, config?: Partial<IVPathConfig>): IVSurfaceEvolution;
+/**
+ * Run a cascade simulation showing feedback loops
+ */
+export declare function runCascadeSimulation(ivSurface: IVSurface, exposures: ExposurePerExpiry, spot: number, spotShock?: number, config?: Partial<IVPathConfig>): CascadeSimulation;
+/**
+ * Analyze IV path for multiple spot scenarios
+ */
+export declare function analyzeIVPath(ivSurface: IVSurface, exposures: ExposurePerExpiry, spot: number, options?: {
+    spotScenarios?: number[];
+    config?: Partial<IVPathConfig>;
+}): Map<number, IVSurfaceEvolution>;
+/**
+ * Get the IV path of least resistance
+ */
+export declare function getIVPathOfLeastResistance(ivSurface: IVSurface, exposures: ExposurePerExpiry, spot: number): {
+    direction: 'up' | 'down' | 'stable';
+    magnitude: number;
+    confidence: number;
+    rationale: string;
+};

package/dist/pressure/ivpath.js

@@ -0,0 +1,304 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_IV_PATH_CONFIG = void 0;
+exports.calculateIVPressures = calculateIVPressures;
+exports.predictIVSurfaceEvolution = predictIVSurfaceEvolution;
+exports.runCascadeSimulation = runCascadeSimulation;
+exports.analyzeIVPath = analyzeIVPath;
+exports.getIVPathOfLeastResistance = getIVPathOfLeastResistance;
+const regime_1 = require("./regime");
+exports.DEFAULT_IV_PATH_CONFIG = {
+    spotMoveScenario: 0,
+    timeStepHours: 1,
+    cascadeIterations: 5,
+    cascadeDampening: 0.5,
+    ivImpactPerMillion: 0.0005,
+    ivFloor: 0.05,
+    ivCeiling: 2.0,
+};
+/**
+ * Calculate IV pressure at each strike based on dealer positioning
+ */
+function calculateIVPressures(ivSurface, exposures, regimeParams, spotMove, config = {}) {
+    const cfg = { ...exports.DEFAULT_IV_PATH_CONFIG, ...config };
+    const { strikes, smoothedIVs } = ivSurface;
+    const { impliedSpotVolCorr, impliedVolOfVol, expectedDailyVolMove } = regimeParams;
+    const pressures = [];
+    const exposureByStrike = new Map();
+    for (const exp of exposures.strikeExposures) {
+        exposureByStrike.set(exp.strikePrice, exp);
+    }
+    for (let i = 0; i < strikes.length; i++) {
+        const strike = strikes[i];
+        const currentIV = smoothedIVs[i] / 100;
+        const exposure = exposureByStrike.get(strike) ?? findNearestExposure(strike, exposures);
+        const vannaIVPressure = calculateVannaIVPressure(exposure?.vannaExposure ?? 0, spotMove, impliedSpotVolCorr, cfg.ivImpactPerMillion);
+        const vommaIVPressure = calculateVommaIVPressure(exposure?.vannaExposure ?? 0, expectedDailyVolMove, impliedVolOfVol, cfg.ivImpactPerMillion);
+        const vetaIVPressure = calculateVetaIVPressure(exposure?.charmExposure ?? 0, cfg.timeStepHours, cfg.ivImpactPerMillion);
+        const liquidityScore = estimateLiquidity(strike, exposures.spotPrice, currentIV);
+        const netIVPressure = vannaIVPressure + vommaIVPressure + vetaIVPressure;
+        const liquidityMultiplier = 1 / (liquidityScore + 0.1);
+        const expectedIVMove = netIVPressure * liquidityMultiplier;
+        pressures.push({
+            strike,
+            currentIV,
+            vannaIVPressure,
+            vommaIVPressure,
+            vetaIVPressure,
+            netIVPressure,
+            liquidityScore,
+            expectedIVMove,
+        });
+    }
+    return pressures;
+}
+function calculateVannaIVPressure(vannaExposure, spotMove, spotVolCorr, ivImpactPerMillion) {
+    const vannaHedgingFlow = -vannaExposure * spotMove;
+    const ivImpact = (vannaHedgingFlow / 1000000) * ivImpactPerMillion;
+    const corrMultiplier = 1 + Math.abs(spotVolCorr) * 0.5;
+    return ivImpact * corrMultiplier;
+}
+function calculateVommaIVPressure(vannaExposure, expectedVolMove, volOfVol, ivImpactPerMillion) {
+    const vommaProxy = vannaExposure * 0.1;
+    const vommaHedgingFlow = vommaProxy * Math.pow(expectedVolMove, 2) * volOfVol * 10;
+    return (vommaHedgingFlow / 1000000) * ivImpactPerMillion;
+}
+function calculateVetaIVPressure(charmExposure, timeStepHours, ivImpactPerMillion) {
+    const timeDecayFlow = charmExposure * (timeStepHours / 6.5);
+    return (timeDecayFlow / 1000000) * ivImpactPerMillion * 0.1;
+}
+function estimateLiquidity(strike, spot, iv) {
+    const moneyness = Math.abs(Math.log(strike / spot)) / iv;
+    return Math.max(0.1, 1 - moneyness * 0.4);
+}
+function findNearestExposure(strike, exposures) {
+    let nearest;
+    let minDist = Infinity;
+    for (const exp of exposures.strikeExposures) {
+        const dist = Math.abs(exp.strikePrice - strike);
+        if (dist < minDist) {
+            minDist = dist;
+            nearest = exp;
+        }
+    }
+    return nearest;
+}
+/**
+ * Predict how the IV surface will evolve given dealer positioning
+ */
+function predictIVSurfaceEvolution(ivSurface, exposures, spot, spotMoveScenario = 0, config = {}) {
+    const cfg = { ...exports.DEFAULT_IV_PATH_CONFIG, ...config, spotMoveScenario };
+    const regimeParams = (0, regime_1.deriveRegimeParams)(ivSurface, spot);
+    const strikePressures = calculateIVPressures(ivSurface, exposures, regimeParams, spotMoveScenario, cfg);
+    const predictedIVs = ivSurface.smoothedIVs.map((iv, i) => {
+        const pressure = strikePressures[i];
+        const newIV = iv / 100 + pressure.expectedIVMove;
+        return Math.max(cfg.ivFloor, Math.min(cfg.ivCeiling, newIV)) * 100;
+    });
+    const predictedSurface = {
+        ...ivSurface,
+        smoothedIVs: predictedIVs,
+        rawIVs: predictedIVs,
+    };
+    const atmIdx = findATMIndex(ivSurface.strikes, spot);
+    const atmIVMove = (predictedIVs[atmIdx] - ivSurface.smoothedIVs[atmIdx]) / 100;
+    const skewChange = calculateSkewChange(ivSurface, predictedSurface, spot);
+    const curvatureChange = calculateCurvatureChange(ivSurface, predictedSurface, spot);
+    const netSurfacePressure = strikePressures.reduce((sum, p) => sum + p.netIVPressure * (p.liquidityScore + 0.1), 0);
+    const confidence = Math.min(1, calculatePositioningClarity(exposures) * 0.8);
+    return {
+        currentSurface: ivSurface,
+        predictedSurface,
+        strikePressures,
+        netSurfacePressure,
+        atmIVMove,
+        skewChange,
+        curvatureChange,
+        confidence,
+    };
+}
+function findATMIndex(strikes, spot) {
+    let minDist = Infinity;
+    let atmIdx = 0;
+    for (let i = 0; i < strikes.length; i++) {
+        const dist = Math.abs(strikes[i] - spot);
+        if (dist < minDist) {
+            minDist = dist;
+            atmIdx = i;
+        }
+    }
+    return atmIdx;
+}
+function calculateSkewChange(current, predicted, spot) {
+    const { strikes } = current;
+    const atmIdx = findATMIndex(strikes, spot);
+    const atmIV = current.smoothedIVs[atmIdx] / 100;
+    const stdDev = spot * atmIV * Math.sqrt(1 / 252);
+    const putIdx = findATMIndex(strikes, spot - stdDev);
+    const callIdx = findATMIndex(strikes, spot + stdDev);
+    const currentSkew = (current.smoothedIVs[putIdx] - current.smoothedIVs[callIdx]) / 100;
+    const predictedSkew = (predicted.smoothedIVs[putIdx] - predicted.smoothedIVs[callIdx]) / 100;
+    return predictedSkew - currentSkew;
+}
+function calculateCurvatureChange(current, predicted, spot) {
+    const { strikes } = current;
+    const atmIdx = findATMIndex(strikes, spot);
+    if (atmIdx === 0 || atmIdx === strikes.length - 1)
+        return 0;
+    const deltaK = (strikes[atmIdx + 1] - strikes[atmIdx - 1]) / 2;
+    if (deltaK === 0)
+        return 0;
+    const currentCurv = (current.smoothedIVs[atmIdx - 1] + current.smoothedIVs[atmIdx + 1] - 2 * current.smoothedIVs[atmIdx]) / (deltaK * deltaK);
+    const predictedCurv = (predicted.smoothedIVs[atmIdx - 1] + predicted.smoothedIVs[atmIdx + 1] - 2 * predicted.smoothedIVs[atmIdx]) / (deltaK * deltaK);
+    return predictedCurv - currentCurv;
+}
+function calculatePositioningClarity(exposures) {
+    const totalAbs = Math.abs(exposures.totalGammaExposure) +
+        Math.abs(exposures.totalVannaExposure) +
+        Math.abs(exposures.totalCharmExposure);
+    if (totalAbs === 0)
+        return 0;
+    const netExposure = exposures.totalNetExposure;
+    const directionalClarity = Math.abs(netExposure) / totalAbs;
+    const maxStrikeExposure = Math.max(...exposures.strikeExposures.map(e => Math.abs(e.netExposure)));
+    const concentration = maxStrikeExposure / (totalAbs + 1);
+    return (directionalClarity + concentration) / 2;
+}
+/**
+ * Run a cascade simulation showing feedback loops
+ */
+function runCascadeSimulation(ivSurface, exposures, spot, spotShock = 0, config = {}) {
+    const cfg = { ...exports.DEFAULT_IV_PATH_CONFIG, ...config };
+    const steps = [];
+    let currentSpot = spot * (1 + spotShock);
+    let currentSurface = ivSurface;
+    let currentExposures = exposures;
+    let cumulativeIVMove = 0;
+    let cumulativeSpotMove = spotShock;
+    const initialRegime = (0, regime_1.deriveRegimeParams)(ivSurface, spot);
+    const initial = {
+        step: 0,
+        spot,
+        ivSurface,
+        exposures,
+        regime: initialRegime.regime,
+        ivPressure: 0,
+        spotPressure: 0,
+        cumulativeIVMove: 0,
+        cumulativeSpotMove: 0,
+    };
+    for (let i = 0; i < cfg.cascadeIterations; i++) {
+        const regime = (0, regime_1.deriveRegimeParams)(currentSurface, currentSpot);
+        const evolution = predictIVSurfaceEvolution(currentSurface, currentExposures, currentSpot, i === 0 ? spotShock : 0, cfg);
+        const dampenedIVMove = evolution.atmIVMove * Math.pow(cfg.cascadeDampening, i);
+        cumulativeIVMove += dampenedIVMove;
+        currentSurface = evolution.predictedSurface;
+        const spotPressure = estimateSpotPressureFromIVChange(dampenedIVMove, currentExposures, currentSpot);
+        const dampenedSpotMove = spotPressure * Math.pow(cfg.cascadeDampening, i);
+        cumulativeSpotMove += dampenedSpotMove;
+        currentSpot = currentSpot * (1 + dampenedSpotMove);
+        steps.push({
+            step: i + 1,
+            spot: currentSpot,
+            ivSurface: currentSurface,
+            exposures: currentExposures,
+            regime: regime.regime,
+            ivPressure: dampenedIVMove,
+            spotPressure: dampenedSpotMove,
+            cumulativeIVMove,
+            cumulativeSpotMove,
+        });
+    }
+    const outcome = determineOutcome(steps);
+    const insight = generateInsight(initial, steps, outcome, spotShock);
+    return {
+        initial,
+        steps,
+        terminal: steps[steps.length - 1],
+        outcome,
+        insight,
+    };
+}
+function estimateSpotPressureFromIVChange(ivChange, exposures, spot) {
+    const deltaChange = exposures.totalVannaExposure * ivChange;
+    return (deltaChange / 1000000000) * 0.001;
+}
+function determineOutcome(steps) {
+    if (steps.length < 3)
+        return 'converged';
+    const lastSteps = steps.slice(-3);
+    const ivMoves = lastSteps.map(s => Math.abs(s.ivPressure));
+    const isDiverging = ivMoves[2] > ivMoves[1] && ivMoves[1] > ivMoves[0];
+    if (isDiverging)
+        return 'diverged';
+    const signs = lastSteps.map(s => Math.sign(s.ivPressure));
+    const isOscillating = signs[0] !== signs[1] && signs[1] !== signs[2];
+    if (isOscillating)
+        return 'oscillating';
+    return 'converged';
+}
+function generateInsight(initial, steps, outcome, spotShock) {
+    const terminal = steps[steps.length - 1];
+    const totalIVMove = terminal.cumulativeIVMove * 100;
+    const totalSpotMove = terminal.cumulativeSpotMove * 100;
+    const direction = spotShock < 0 ? 'down' : spotShock > 0 ? 'up' : 'flat';
+    if (outcome === 'diverged') {
+        return `Warning: Cascade diverged after ${spotShock * 100}% spot ${direction} shock. ` +
+            `IV moved ${totalIVMove.toFixed(2)} vol points cumulatively.`;
+    }
+    if (outcome === 'oscillating') {
+        return `Cascade oscillated after ${spotShock * 100}% spot ${direction} shock. ` +
+            `Net IV move: ${totalIVMove.toFixed(2)} vol points.`;
+    }
+    if (Math.abs(totalIVMove) > 2) {
+        return `Significant IV reaction: ${spotShock * 100}% spot ${direction} shock triggered ` +
+            `${totalIVMove.toFixed(2)} vol point IV move through feedback loop.`;
+    }
+    return `Minimal cascade effect: ${spotShock * 100}% spot ${direction} shock absorbed ` +
+        `with only ${totalIVMove.toFixed(2)} vol point IV move.`;
+}
+/**
+ * Analyze IV path for multiple spot scenarios
+ */
+function analyzeIVPath(ivSurface, exposures, spot, options = {}) {
+    const scenarios = options.spotScenarios ?? [-0.03, -0.02, -0.01, 0, 0.01, 0.02, 0.03];
+    const results = new Map();
+    for (const scenario of scenarios) {
+        const evolution = predictIVSurfaceEvolution(ivSurface, exposures, spot, scenario, options.config);
+        results.set(scenario, evolution);
+    }
+    return results;
+}
+/**
+ * Get the IV path of least resistance
+ */
+function getIVPathOfLeastResistance(ivSurface, exposures, spot) {
+    const regimeParams = (0, regime_1.deriveRegimeParams)(ivSurface, spot);
+    const upPressures = calculateIVPressures(ivSurface, exposures, regimeParams, 0.01);
+    const downPressures = calculateIVPressures(ivSurface, exposures, regimeParams, -0.01);
+    const neutralPressures = calculateIVPressures(ivSurface, exposures, regimeParams, 0);
+    const upNetPressure = upPressures.reduce((sum, p) => sum + p.netIVPressure, 0);
+    const downNetPressure = downPressures.reduce((sum, p) => sum + p.netIVPressure, 0);
+    const neutralNetPressure = neutralPressures.reduce((sum, p) => sum + p.netIVPressure, 0);
+    let direction = 'stable';
+    let magnitude = 0;
+    let rationale = '';
+    const netBias = (downNetPressure + neutralNetPressure) - upNetPressure;
+    if (netBias > 0.001) {
+        direction = 'up';
+        magnitude = Math.abs(netBias);
+        rationale = `Positioning suggests IV upside bias. Vanna hedging would add ${(magnitude * 100).toFixed(2)} vol points on down moves.`;
+    }
+    else if (netBias < -0.001) {
+        direction = 'down';
+        magnitude = Math.abs(netBias);
+        rationale = `Positioning suggests IV downside bias. Vol selling pressure would reduce IV by ${(magnitude * 100).toFixed(2)} vol points.`;
+    }
+    else {
+        direction = 'stable';
+        magnitude = 0;
+        rationale = `Balanced positioning suggests IV stability.`;
+    }
+    const confidence = calculatePositioningClarity(exposures);
+    return { direction, magnitude, confidence, rationale };
+}

package/dist/pressure/normalize.d.ts

@@ -0,0 +1,6 @@
+import { ExposurePerExpiry } from '../types';
+import { RegimeParams, NormalizedExposureSummary } from './types';
+/**
+ * Normalize raw exposures to comparable "expected daily flow" units
+ */
+export declare function normalizeExposures(exposures: ExposurePerExpiry, regimeParams: RegimeParams): NormalizedExposureSummary;

package/dist/pressure/normalize.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeExposures = normalizeExposures;
+/**
+ * Normalize raw exposures to comparable "expected daily flow" units
+ */
+function normalizeExposures(exposures, regimeParams) {
+    const { expectedDailySpotMove, expectedDailyVolMove, impliedSpotVolCorr, regime } = regimeParams;
+    const corrAmplifier = 1 + Math.abs(impliedSpotVolCorr);
+    const volOfVolMultiplier = {
+        calm: 0.5,
+        normal: 1.0,
+        stressed: 2.5,
+        crisis: 5.0,
+    };
+    const normalizedStrikes = [];
+    let totalEffectiveGamma = 0;
+    let totalEffectiveVanna = 0;
+    let totalEffectiveCharm = 0;
+    for (const strike of exposures.strikeExposures) {
+        const effectiveGamma = Math.abs(strike.gammaExposure) * expectedDailySpotMove;
+        const effectiveVanna = Math.abs(strike.vannaExposure) *
+            expectedDailySpotMove *
+            expectedDailyVolMove *
+            volOfVolMultiplier[regime] *
+            corrAmplifier;
+        const effectiveCharm = Math.abs(strike.charmExposure);
+        const totalEffective = effectiveGamma + effectiveVanna + effectiveCharm;
+        let dominant = 'gamma';
+        if (effectiveVanna > effectiveGamma && effectiveVanna > effectiveCharm) {
+            dominant = 'vanna';
+        }
+        else if (effectiveCharm > effectiveGamma && effectiveCharm > effectiveVanna) {
+            dominant = 'charm';
+        }
+        normalizedStrikes.push({
+            strike: strike.strikePrice,
+            rawGamma: strike.gammaExposure,
+            rawVanna: strike.vannaExposure,
+            rawCharm: strike.charmExposure,
+            effectiveGamma,
+            effectiveVanna,
+            effectiveCharm,
+            totalEffective,
+            dominant,
+        });
+        totalEffectiveGamma += effectiveGamma;
+        totalEffectiveVanna += effectiveVanna;
+        totalEffectiveCharm += effectiveCharm;
+    }
+    const totalEffective = totalEffectiveGamma + totalEffectiveVanna + totalEffectiveCharm;
+    const weights = {
+        gamma: totalEffective > 0 ? totalEffectiveGamma / totalEffective : 0.33,
+        vanna: totalEffective > 0 ? totalEffectiveVanna / totalEffective : 0.33,
+        charm: totalEffective > 0 ? totalEffectiveCharm / totalEffective : 0.34,
+    };
+    let dominantGreek = 'gamma';
+    if (weights.vanna > weights.gamma && weights.vanna > weights.charm) {
+        dominantGreek = 'vanna';
+    }
+    else if (weights.charm > weights.gamma && weights.charm > weights.vanna) {
+        dominantGreek = 'charm';
+    }
+    return {
+        spot: exposures.spotPrice,
+        expiration: exposures.expiration,
+        regimeParams,
+        strikeExposures: normalizedStrikes,
+        totalEffectiveGamma,
+        totalEffectiveVanna,
+        totalEffectiveCharm,
+        totalEffective,
+        dominantGreek,
+        weights,
+    };
+}

package/dist/pressure/regime.d.ts

@@ -0,0 +1,7 @@
+import { IVSurface } from '../types';
+import { RegimeParams } from './types';
+/**
+ * Derive regime parameters from the IV surface
+ */
+export declare function deriveRegimeParams(ivSurface: IVSurface, spot: number): RegimeParams;
+export declare function interpolateIVAtStrike(strikes: number[], ivs: number[], targetStrike: number): number;