@fullstackcraftllc/floe 0.0.14 → 0.0.16

package/dist/exposure/index.d.ts

@@ -1,17 +1,22 @@
-import { OptionChain, ExposurePerExpiry, IVSurface } from '../types';
+import { OptionChain, ExposureVariantsPerExpiry, ExposureCalculationOptions, IVSurface } from '../types';
 /**
- * Calculate Gamma, Vanna, and Charm exposures for an option chain
+ * Calculate canonical, state-weighted, and flow-delta exposure variants.
  *
- * @param chain - Option chain with market context (spot, rates, options)
- * @param ivSurfaces - IV surfaces for all expirations
- * @returns Array of exposure metrics per expiration
+ * canonical:
+ * - GEX: dollars per 1% underlying move
+ * - VEX: dollars per 1 vol-point move
+ * - CEX: dollars per 1 day of time decay
  *
- * @example
- * ```typescript
- * const exposures = calculateGammaVannaCharmExposures(chain, ivSurfaces);
- * ```
+ * stateWeighted:
+ * - Gamma: same as canonical (spot is already the state variable)
+ * - Vanna: canonical vanna weighted by strike IV level
+ * - Charm: canonical charm weighted by days-to-expiration
+ *
+ * flowDelta:
+ * - Canonical exposure formulas using OI deltas:
+ *   (liveOpenInterest - openInterest)
  */
-export declare function calculateGammaVannaCharmExposures(chain: OptionChain, ivSurfaces: IVSurface[]): ExposurePerExpiry[];
+export declare function calculateGammaVannaCharmExposures(chain: OptionChain, ivSurfaces: IVSurface[], options?: ExposureCalculationOptions): ExposureVariantsPerExpiry[];
 /**
  * Calculate shares needed to cover net exposure
  *

package/dist/exposure/index.js

@@ -6,70 +6,62 @@ const types_1 = require("../types");
 const blackscholes_1 = require("../blackscholes");
 const volatility_1 = require("../volatility");
 /**
- * Calculate Gamma, Vanna, and Charm exposures for an option chain
+ * Calculate canonical, state-weighted, and flow-delta exposure variants.
  *
- * @param chain - Option chain with market context (spot, rates, options)
- * @param ivSurfaces - IV surfaces for all expirations
- * @returns Array of exposure metrics per expiration
+ * canonical:
+ * - GEX: dollars per 1% underlying move
+ * - VEX: dollars per 1 vol-point move
+ * - CEX: dollars per 1 day of time decay
  *
- * @example
- * ```typescript
- * const exposures = calculateGammaVannaCharmExposures(chain, ivSurfaces);
- * ```
+ * stateWeighted:
+ * - Gamma: same as canonical (spot is already the state variable)
+ * - Vanna: canonical vanna weighted by strike IV level
+ * - Charm: canonical charm weighted by days-to-expiration
+ *
+ * flowDelta:
+ * - Canonical exposure formulas using OI deltas:
+ *   (liveOpenInterest - openInterest)
  */
-function calculateGammaVannaCharmExposures(chain, ivSurfaces) {
-    const { spot, riskFreeRate, dividendYield, options } = chain;
+function calculateGammaVannaCharmExposures(chain, ivSurfaces, options = {}) {
+    const { spot, riskFreeRate, dividendYield, options: chainOptions } = chain;
+    const asOfTimestamp = options.asOfTimestamp ?? Date.now();
     const exposureRows = [];
-    // Get unique expirations from options
     const expirationsSet = new Set();
-    for (const option of options) {
+    for (const option of chainOptions) {
         expirationsSet.add(option.expirationTimestamp);
     }
     const expirations = Array.from(expirationsSet).sort((a, b) => a - b);
-    // Loop through all expirations
+    const putOptionsByKey = new Map();
+    for (const option of chainOptions) {
+        if (option.optionType === 'put') {
+            putOptionsByKey.set(getOptionKey(option.expirationTimestamp, option.strike), option);
+        }
+    }
     for (const expiration of expirations) {
-        // Skip any expiration that is in the past
-        if (expiration < Date.now()) {
+        if (expiration < asOfTimestamp) {
+            continue;
+        }
+        const timeToExpirationInYears = (expiration - asOfTimestamp) / types_1.MILLISECONDS_PER_YEAR;
+        if (timeToExpirationInYears <= 0) {
             continue;
         }
-        // Reset totals for this expiration
-        let totalGammaExposure = 0.0;
-        let totalVannaExposure = 0.0;
-        let totalCharmExposure = 0.0;
-        let strikeOfMaxGamma = 0.0;
-        let strikeOfMinGamma = 0.0;
-        let strikeOfMaxVanna = 0.0;
-        let strikeOfMinVanna = 0.0;
-        let strikeOfMaxCharm = 0.0;
-        let strikeOfMinCharm = 0.0;
-        let strikeOfMaxNet = 0.0;
-        let strikeOfMinNet = 0.0;
-        const strikeExposures = [];
-        // Process all call options first
-        for (const callOption of options) {
-            // Check if this option is at the expiration we are looking at
-            if (callOption.expirationTimestamp !== expiration || callOption.optionType === 'put') {
+        const timeToExpirationInDays = Math.max(timeToExpirationInYears * types_1.DAYS_PER_YEAR, 0);
+        const strikeExposureVariants = [];
+        for (const callOption of chainOptions) {
+            if (callOption.expirationTimestamp !== expiration || callOption.optionType !== 'call') {
                 continue;
             }
-            // Get the corresponding put option
-            const putOption = options.find((opt) => opt.expirationTimestamp === expiration &&
-                opt.optionType === 'put' &&
-                opt.strike === callOption.strike);
+            const putOption = putOptionsByKey.get(getOptionKey(expiration, callOption.strike));
             if (!putOption) {
-                continue; // Skip if no matching put
+                continue;
             }
-            // Get IV for this strike and expiry from the surface
-            const callIVAtStrike = (0, volatility_1.getIVForStrike)(ivSurfaces, expiration, 'call', callOption.strike);
-            const putIVAtStrike = (0, volatility_1.getIVForStrike)(ivSurfaces, expiration, 'put', putOption.strike);
-            // Get time to expiration in years
-            const timeToExpirationInYears = (0, blackscholes_1.getTimeToExpirationInYears)(expiration);
-            // Calculate Greeks for both call and put
-            // Rates are already decimals in OptionChain, IV from surface is percentage
+            const callIVAtStrike = resolveIVPercent((0, volatility_1.getIVForStrike)(ivSurfaces, expiration, 'call', callOption.strike), callOption.impliedVolatility);
+            const putIVAtStrike = resolveIVPercent((0, volatility_1.getIVForStrike)(ivSurfaces, expiration, 'put', putOption.strike), putOption.impliedVolatility);
             const callGreeks = (0, blackscholes_1.calculateGreeks)({
                 spot,
                 strike: callOption.strike,
                 timeToExpiry: timeToExpirationInYears,
-                volatility: callIVAtStrike / 100.0, // Convert from percentage to decimal
+                volatility: callIVAtStrike / 100.0,
                 riskFreeRate,
                 dividendYield,
                 optionType: 'call',
@@ -83,74 +75,33 @@ function calculateGammaVannaCharmExposures(chain, ivSurfaces) {
                 dividendYield,
                 optionType: 'put',
             });
-            // Calculate exposures from dealer perspective
-            // Dealer is short calls (negative gamma) and long puts (positive gamma)
-            // Multiply by 100 for contract size, multiply by spot for dollar exposure
-            // Multiply by 0.01 for 1% move sensitivity
-            // Gamma: second order with respect to price twice
-            const gammaExposureForStrike = -callOption.openInterest * callGreeks.gamma * (spot * 100.0) * spot * 0.01 +
-                putOption.openInterest * putGreeks.gamma * (spot * 100.0) * spot * 0.01;
-            // Vanna: second order with respect to price and volatility
-            const vannaExposureForStrike = -callOption.openInterest * callGreeks.vanna * (spot * 100.0) * callIVAtStrike * 0.01 +
-                putOption.openInterest * putGreeks.vanna * (spot * 100.0) * putIVAtStrike * 0.01;
-            // Charm: second order with respect to price and time
-            // Already normalized per day in calculateGreeks
-            const charmExposureForStrike = -callOption.openInterest * callGreeks.charm * (spot * 100.0) * types_1.DAYS_PER_YEAR * timeToExpirationInYears +
-                putOption.openInterest * putGreeks.charm * (spot * 100.0) * types_1.DAYS_PER_YEAR * timeToExpirationInYears;
-            // NaN checks
-            const gammaExposure = isNaN(gammaExposureForStrike) ? 0.0 : gammaExposureForStrike;
-            const vannaExposure = isNaN(vannaExposureForStrike) ? 0.0 : vannaExposureForStrike;
-            const charmExposure = isNaN(charmExposureForStrike) ? 0.0 : charmExposureForStrike;
-            // Add to totals
-            totalGammaExposure += gammaExposure;
-            totalVannaExposure += vannaExposure;
-            totalCharmExposure += charmExposure;
-            // Add to strike exposures
-            strikeExposures.push({
+            const callOpenInterest = sanitizeFinite(callOption.openInterest);
+            const putOpenInterest = sanitizeFinite(putOption.openInterest);
+            const canonical = calculateCanonicalVector(spot, callOpenInterest, putOpenInterest, callGreeks.gamma, putGreeks.gamma, callGreeks.vanna, putGreeks.vanna, callGreeks.charm, putGreeks.charm);
+            const stateWeighted = calculateStateWeightedVector(spot, callOpenInterest, putOpenInterest, callGreeks.vanna, putGreeks.vanna, callGreeks.charm, putGreeks.charm, callIVAtStrike, putIVAtStrike, timeToExpirationInDays, canonical.gammaExposure);
+            const callFlowDelta = resolveFlowDeltaOpenInterest(callOption.openInterest, callOption.liveOpenInterest);
+            const putFlowDelta = resolveFlowDeltaOpenInterest(putOption.openInterest, putOption.liveOpenInterest);
+            const flowDelta = calculateCanonicalVector(spot, callFlowDelta, putFlowDelta, callGreeks.gamma, putGreeks.gamma, callGreeks.vanna, putGreeks.vanna, callGreeks.charm, putGreeks.charm);
+            strikeExposureVariants.push({
                 strikePrice: callOption.strike,
-                gammaExposure,
-                vannaExposure,
-                charmExposure,
-                netExposure: gammaExposure + vannaExposure + charmExposure,
+                canonical,
+                stateWeighted,
+                flowDelta,
             });
         }
-        if (strikeExposures.length === 0) {
-            continue; // No options for this expiration
+        if (strikeExposureVariants.length === 0) {
+            continue;
         }
-        // Sort by gamma exposure and find extremes
-        strikeExposures.sort((a, b) => b.gammaExposure - a.gammaExposure);
-        strikeOfMaxGamma = strikeExposures[0].strikePrice;
-        strikeOfMinGamma = strikeExposures[strikeExposures.length - 1].strikePrice;
-        // Sort by vanna exposure and find extremes
-        strikeExposures.sort((a, b) => b.vannaExposure - a.vannaExposure);
-        strikeOfMaxVanna = strikeExposures[0].strikePrice;
-        strikeOfMinVanna = strikeExposures[strikeExposures.length - 1].strikePrice;
-        // Sort by charm exposure and find extremes
-        strikeExposures.sort((a, b) => b.charmExposure - a.charmExposure);
-        strikeOfMaxCharm = strikeExposures[0].strikePrice;
-        strikeOfMinCharm = strikeExposures[strikeExposures.length - 1].strikePrice;
-        // Sort by net exposure and find extremes
-        strikeExposures.sort((a, b) => b.netExposure - a.netExposure);
-        strikeOfMaxNet = strikeExposures[0].strikePrice;
-        strikeOfMinNet = strikeExposures[strikeExposures.length - 1].strikePrice;
-        const totalNetExposure = totalGammaExposure + totalVannaExposure + totalCharmExposure;
-        // Add exposure row
+        const canonical = buildModeBreakdown(strikeExposureVariants, 'canonical');
+        const stateWeighted = buildModeBreakdown(strikeExposureVariants, 'stateWeighted');
+        const flowDelta = buildModeBreakdown(strikeExposureVariants, 'flowDelta');
         exposureRows.push({
             spotPrice: spot,
             expiration,
-            totalGammaExposure,
-            totalVannaExposure,
-            totalCharmExposure,
-            totalNetExposure,
-            strikeOfMaxGamma,
-            strikeOfMinGamma,
-            strikeOfMaxVanna,
-            strikeOfMinVanna,
-            strikeOfMaxCharm,
-            strikeOfMinCharm,
-            strikeOfMaxNet,
-            strikeOfMinNet,
-            strikeExposures
+            canonical,
+            stateWeighted,
+            flowDelta,
+            strikeExposureVariants,
         });
     }
     return exposureRows;
@@ -210,3 +161,110 @@ function calculateSharesNeededToCover(sharesOutstanding, totalNetExposure, under
         resultingSpotToCover: resultingPrice,
     };
 }
+function getOptionKey(expiration, strike) {
+    return `${expiration}:${strike}`;
+}
+function calculateCanonicalVector(spot, callPosition, putPosition, callGamma, putGamma, callVanna, putVanna, callCharm, putCharm) {
+    const gammaExposure = -callPosition * callGamma * (spot * 100.0) * spot * 0.01 +
+        putPosition * putGamma * (spot * 100.0) * spot * 0.01;
+    const vannaExposure = -callPosition * callVanna * (spot * 100.0) * 0.01 +
+        putPosition * putVanna * (spot * 100.0) * 0.01;
+    const charmExposure = -callPosition * callCharm * (spot * 100.0) +
+        putPosition * putCharm * (spot * 100.0);
+    return sanitizeVector({
+        gammaExposure,
+        vannaExposure,
+        charmExposure,
+        netExposure: gammaExposure + vannaExposure + charmExposure,
+    });
+}
+function calculateStateWeightedVector(spot, callPosition, putPosition, callVanna, putVanna, callCharm, putCharm, callIVPercent, putIVPercent, timeToExpirationInDays, canonicalGammaExposure) {
+    const callIVLevel = Math.max(callIVPercent * 0.01, 0);
+    const putIVLevel = Math.max(putIVPercent * 0.01, 0);
+    // Gamma already uses instantaneous price scaling in canonical GEX.
+    const gammaExposure = canonicalGammaExposure;
+    const vannaExposure = -callPosition * callVanna * (spot * 100.0) * 0.01 * callIVLevel +
+        putPosition * putVanna * (spot * 100.0) * 0.01 * putIVLevel;
+    const canonicalCharmComponent = -callPosition * callCharm * (spot * 100.0) +
+        putPosition * putCharm * (spot * 100.0);
+    const charmExposure = canonicalCharmComponent * Math.max(timeToExpirationInDays, 0);
+    return sanitizeVector({
+        gammaExposure,
+        vannaExposure,
+        charmExposure,
+        netExposure: gammaExposure + vannaExposure + charmExposure,
+    });
+}
+function resolveFlowDeltaOpenInterest(openInterest, liveOpenInterest) {
+    if (typeof liveOpenInterest !== 'number' || !isFinite(liveOpenInterest)) {
+        return 0;
+    }
+    return sanitizeFinite(liveOpenInterest - openInterest);
+}
+function resolveIVPercent(ivFromSurface, optionImpliedVolatilityDecimal) {
+    if (isFinite(ivFromSurface) && ivFromSurface > 0) {
+        return ivFromSurface;
+    }
+    const fallback = optionImpliedVolatilityDecimal * 100.0;
+    if (isFinite(fallback) && fallback > 0) {
+        return fallback;
+    }
+    return 0;
+}
+function buildModeBreakdown(strikeExposureVariants, mode) {
+    const strikeExposures = strikeExposureVariants.map((strike) => ({
+        strikePrice: strike.strikePrice,
+        ...strike[mode],
+    }));
+    if (strikeExposures.length === 0) {
+        return {
+            totalGammaExposure: 0,
+            totalVannaExposure: 0,
+            totalCharmExposure: 0,
+            totalNetExposure: 0,
+            strikeOfMaxGamma: 0,
+            strikeOfMinGamma: 0,
+            strikeOfMaxVanna: 0,
+            strikeOfMinVanna: 0,
+            strikeOfMaxCharm: 0,
+            strikeOfMinCharm: 0,
+            strikeOfMaxNet: 0,
+            strikeOfMinNet: 0,
+            strikeExposures: [],
+        };
+    }
+    const totalGammaExposure = strikeExposures.reduce((sum, s) => sum + s.gammaExposure, 0);
+    const totalVannaExposure = strikeExposures.reduce((sum, s) => sum + s.vannaExposure, 0);
+    const totalCharmExposure = strikeExposures.reduce((sum, s) => sum + s.charmExposure, 0);
+    const totalNetExposure = totalGammaExposure + totalVannaExposure + totalCharmExposure;
+    const byGamma = [...strikeExposures].sort((a, b) => b.gammaExposure - a.gammaExposure);
+    const byVanna = [...strikeExposures].sort((a, b) => b.vannaExposure - a.vannaExposure);
+    const byCharm = [...strikeExposures].sort((a, b) => b.charmExposure - a.charmExposure);
+    const byNet = [...strikeExposures].sort((a, b) => b.netExposure - a.netExposure);
+    return {
+        totalGammaExposure: sanitizeFinite(totalGammaExposure),
+        totalVannaExposure: sanitizeFinite(totalVannaExposure),
+        totalCharmExposure: sanitizeFinite(totalCharmExposure),
+        totalNetExposure: sanitizeFinite(totalNetExposure),
+        strikeOfMaxGamma: byGamma[0].strikePrice,
+        strikeOfMinGamma: byGamma[byGamma.length - 1].strikePrice,
+        strikeOfMaxVanna: byVanna[0].strikePrice,
+        strikeOfMinVanna: byVanna[byVanna.length - 1].strikePrice,
+        strikeOfMaxCharm: byCharm[0].strikePrice,
+        strikeOfMinCharm: byCharm[byCharm.length - 1].strikePrice,
+        strikeOfMaxNet: byNet[0].strikePrice,
+        strikeOfMinNet: byNet[byNet.length - 1].strikePrice,
+        strikeExposures: byNet,
+    };
+}
+function sanitizeVector(vector) {
+    return {
+        gammaExposure: sanitizeFinite(vector.gammaExposure),
+        vannaExposure: sanitizeFinite(vector.vannaExposure),
+        charmExposure: sanitizeFinite(vector.charmExposure),
+        netExposure: sanitizeFinite(vector.netExposure),
+    };
+}
+function sanitizeFinite(value) {
+    return isFinite(value) && !isNaN(value) ? value : 0;
+}

package/dist/hedgeflow/charm.d.ts

@@ -0,0 +1,23 @@
+import { ExposurePerExpiry } from '../types';
+import { CharmIntegralConfig, CharmIntegral } from './types';
+/**
+ * Compute the charm integral from now until expiration.
+ *
+ * The charm integral represents the cumulative expected delta change
+ * from time decay alone — i.e., what happens to dealer hedging
+ * regardless of price movement. This is the "unconditional" pressure.
+ *
+ * The dollar CEX values already incorporate Black-Scholes time decay
+ * acceleration (charm ∝ 1/√T near expiry), so no additional time
+ * weighting is needed. Larger CEX values near expiry are the math
+ * doing its job, not something we need to amplify.
+ *
+ * When open interest changes intraday (detected via live OI tracking),
+ * this function should be recomputed with updated exposures to reflect
+ * the new charm landscape.
+ *
+ * @param exposures - Current per-strike exposure data (with live OI if available)
+ * @param config - Optional time step configuration
+ * @returns Charm integral analysis with cumulative curve and per-strike breakdown
+ */
+export declare function computeCharmIntegral(exposures: ExposurePerExpiry, config?: CharmIntegralConfig): CharmIntegral;

package/dist/hedgeflow/charm.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeCharmIntegral = computeCharmIntegral;
+/**
+ * Compute the charm integral from now until expiration.
+ *
+ * The charm integral represents the cumulative expected delta change
+ * from time decay alone — i.e., what happens to dealer hedging
+ * regardless of price movement. This is the "unconditional" pressure.
+ *
+ * The dollar CEX values already incorporate Black-Scholes time decay
+ * acceleration (charm ∝ 1/√T near expiry), so no additional time
+ * weighting is needed. Larger CEX values near expiry are the math
+ * doing its job, not something we need to amplify.
+ *
+ * When open interest changes intraday (detected via live OI tracking),
+ * this function should be recomputed with updated exposures to reflect
+ * the new charm landscape.
+ *
+ * @param exposures - Current per-strike exposure data (with live OI if available)
+ * @param config - Optional time step configuration
+ * @returns Charm integral analysis with cumulative curve and per-strike breakdown
+ */
+function computeCharmIntegral(exposures, config = {}) {
+    const { timeStepMinutes = 15 } = config;
+    const spot = exposures.spotPrice;
+    const expiration = exposures.expiration;
+    const now = Date.now();
+    const msRemaining = expiration - now;
+    const minutesRemaining = Math.max(0, msRemaining / 60000);
+    // Per-strike charm breakdown
+    const totalAbsCharm = exposures.strikeExposures.reduce((sum, s) => sum + Math.abs(s.charmExposure), 0);
+    const strikeContributions = exposures.strikeExposures
+        .filter(s => s.charmExposure !== 0)
+        .map(s => ({
+        strike: s.strikePrice,
+        charmExposure: s.charmExposure,
+        fractionOfTotal: totalAbsCharm > 0
+            ? Math.abs(s.charmExposure) / totalAbsCharm
+            : 0,
+    }))
+        .sort((a, b) => Math.abs(b.charmExposure) - Math.abs(a.charmExposure));
+    // Build time-bucketed charm curve
+    // The total CEX is already a per-day rate. For sub-day intervals,
+    // we scale by the fraction of the day each bucket represents.
+    const totalCEX = exposures.totalCharmExposure;
+    const buckets = [];
+    let cumulativeCEX = 0;
+    if (minutesRemaining <= 0) {
+        // Already expired
+        return {
+            spot,
+            expiration,
+            computedAt: now,
+            minutesRemaining: 0,
+            totalCharmToClose: 0,
+            direction: 'neutral',
+            buckets: [],
+            strikeContributions,
+        };
+    }
+    // Walk from now backward toward expiry in timeStepMinutes increments.
+    // At each step, the charm exposure intensifies because the remaining
+    // options are closer to expiry.
+    //
+    // Since CEX is already the dollar exposure rate that incorporates the
+    // current time to expiry, and charm accelerates as 1/√T, we model
+    // the instantaneous charm at t minutes remaining as:
+    //
+    //   CEX(t) ≈ totalCEX * √(minutesRemaining / t)
+    //
+    // This scaling comes from charm ∝ 1/√T: if current charm is computed
+    // at T minutes out, then at t < T minutes it will be larger by √(T/t).
+    //
+    // The integral of CEX(t) dt from t=minutesRemaining down to t=0
+    // gives the total expected delta change, but note the integral of
+    // 1/√t diverges — in practice, charm exposure is bounded because
+    // deep ITM/OTM options have vanishing charm. We cap at t=1 minute.
+    for (let t = minutesRemaining; t >= Math.max(1, timeStepMinutes); t -= timeStepMinutes) {
+        // Charm at this time: scale by √(minutesRemaining / t)
+        const timeScaling = Math.sqrt(minutesRemaining / t);
+        const instantCEX = totalCEX * timeScaling;
+        // Each bucket represents timeStepMinutes of elapsed time.
+        // Convert to fraction of a trading day for the integral.
+        // 6.5 hours = 390 minutes in a standard session.
+        const bucketFractionOfDay = timeStepMinutes / 390;
+        const bucketContribution = instantCEX * bucketFractionOfDay;
+        cumulativeCEX += bucketContribution;
+        buckets.push({
+            minutesRemaining: t,
+            instantaneousCEX: instantCEX,
+            cumulativeCEX,
+        });
+    }
+    // Determine direction
+    let direction = 'neutral';
+    if (cumulativeCEX > 0) {
+        direction = 'buying';
+    }
+    else if (cumulativeCEX < 0) {
+        direction = 'selling';
+    }
+    return {
+        spot,
+        expiration,
+        computedAt: now,
+        minutesRemaining,
+        totalCharmToClose: cumulativeCEX,
+        direction,
+        buckets,
+        strikeContributions,
+    };
+}

package/dist/hedgeflow/curve.d.ts

@@ -0,0 +1,27 @@
+import { ExposurePerExpiry, IVSurface } from '../types';
+import { HedgeImpulseConfig, HedgeImpulseCurve } from './types';
+/**
+ * Compute the hedge impulse curve across a price grid.
+ *
+ * The hedge impulse H(S) at each price level S combines gamma and vanna
+ * exposures via the empirical spot-vol coupling relationship:
+ *
+ *   H(S) = GEX_smoothed(S) - (k / S) * VEX_smoothed(S)
+ *
+ * where:
+ * - GEX_smoothed(S) is the kernel-smoothed gamma exposure at S
+ * - VEX_smoothed(S) is the kernel-smoothed vanna exposure at S
+ * - k is the spot-vol coupling coefficient derived from the IV surface
+ *
+ * Positive H(S) means a spot move toward S triggers dealer buying that
+ * dampens the move (mean-reversion / "wall" behavior).
+ *
+ * Negative H(S) means a spot move toward S triggers dealer selling that
+ * amplifies the move (trend acceleration / "vacuum" behavior).
+ *
+ * @param exposures - Per-strike gamma, vanna, charm exposures
+ * @param ivSurface - The IV surface for regime derivation
+ * @param config - Optional configuration for grid and kernel parameters
+ * @returns Complete hedge impulse curve analysis
+ */
+export declare function computeHedgeImpulseCurve(exposures: ExposurePerExpiry, ivSurface: IVSurface, config?: HedgeImpulseConfig): HedgeImpulseCurve;