@fullstackcraftllc/floe 0.0.16 → 0.0.18

package/dist/hedgeflow/index.d.ts

@@ -1,9 +1,11 @@
 import { ExposurePerExpiry, IVSurface } from '../types';
 import { HedgeImpulseConfig, CharmIntegralConfig, HedgeFlowAnalysis } from './types';
 export type { MarketRegime, RegimeParams, HedgeImpulseConfig, HedgeImpulsePoint, HedgeImpulseCurve, ZeroCrossing, ImpulseExtremum, DirectionalAsymmetry, ImpulseRegime, CharmIntegralConfig, CharmBucket, CharmIntegral, HedgeFlowAnalysis, } from './types';
+export type { HedgeContractEstimates, PressureZone, RegimeEdge, PressureLevel, PressureCloudConfig, PressureCloud, } from './pressurecloud';
 export { deriveRegimeParams, interpolateIVAtStrike } from './regime';
 export { computeHedgeImpulseCurve } from './curve';
 export { computeCharmIntegral } from './charm';
+export { computePressureCloud } from './pressurecloud';
 /**
  * Compute a complete hedge flow analysis for a single expiration.
  *

package/dist/hedgeflow/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.computeCharmIntegral = exports.computeHedgeImpulseCurve = exports.interpolateIVAtStrike = exports.deriveRegimeParams = void 0;
+exports.computePressureCloud = exports.computeCharmIntegral = exports.computeHedgeImpulseCurve = exports.interpolateIVAtStrike = exports.deriveRegimeParams = void 0;
 exports.analyzeHedgeFlow = analyzeHedgeFlow;
 const regime_1 = require("./regime");
 const curve_1 = require("./curve");
@@ -14,6 +14,9 @@ var curve_2 = require("./curve");
 Object.defineProperty(exports, "computeHedgeImpulseCurve", { enumerable: true, get: function () { return curve_2.computeHedgeImpulseCurve; } });
 var charm_2 = require("./charm");
 Object.defineProperty(exports, "computeCharmIntegral", { enumerable: true, get: function () { return charm_2.computeCharmIntegral; } });
+// Re-export pressure cloud
+var pressurecloud_1 = require("./pressurecloud");
+Object.defineProperty(exports, "computePressureCloud", { enumerable: true, get: function () { return pressurecloud_1.computePressureCloud; } });
 /**
  * Compute a complete hedge flow analysis for a single expiration.
  *

package/dist/hedgeflow/pressurecloud.d.ts

@@ -0,0 +1,166 @@
+import { HedgeImpulseCurve } from './types';
+import { RegimeParams } from './types';
+/**
+ * Expected dealer hedge volume in futures contracts for a 1-point spot move.
+ * Positive = dealers buying, negative = dealers selling.
+ */
+export interface HedgeContractEstimates {
+    /** E-mini Nasdaq 100 (multiplier: 20) */
+    nq: number;
+    /** Micro E-mini Nasdaq 100 (multiplier: 2) */
+    mnq: number;
+    /** E-mini S&P 500 (multiplier: 50) */
+    es: number;
+    /** Micro E-mini S&P 500 (multiplier: 5) */
+    mes: number;
+}
+/**
+ * A zone where price is likely to stabilize (positive impulse)
+ * or accelerate (negative impulse).
+ */
+export interface PressureZone {
+    /** Center price of the zone (peak of the impulse) */
+    center: number;
+    /** Lower bound of the zone (25th percentile of the peak width) */
+    lower: number;
+    /** Upper bound of the zone (75th percentile of the peak width) */
+    upper: number;
+    /** Normalized strength 0-1 (relative to the strongest zone found) */
+    strength: number;
+    /** Whether this zone is above or below current spot */
+    side: 'above-spot' | 'below-spot';
+    /**
+     * Trade type this zone favors:
+     * - Stability zones below spot → long (buy the bounce)
+     * - Stability zones above spot → short (sell the rejection)
+     * - Acceleration zones below spot → short (momentum downside)
+     * - Acceleration zones above spot → long (momentum upside / squeeze)
+     */
+    tradeType: 'long' | 'short';
+    /**
+     * Hedge execution type:
+     * - passive: dealers post resting limit orders (positive gamma → absorption)
+     * - aggressive: dealers send market orders (negative gamma → sweeping)
+     */
+    hedgeType: 'passive' | 'aggressive';
+}
+/**
+ * A regime boundary where behavior flips between mean-reverting and trend-amplifying.
+ */
+export interface RegimeEdge {
+    /** Price at which the impulse curve crosses zero */
+    price: number;
+    /** Direction of the transition relative to a downward price move */
+    transitionType: 'stable-to-unstable' | 'unstable-to-stable';
+}
+/**
+ * Per-price-level detail for the full pressure overlay.
+ */
+export interface PressureLevel {
+    /** Price level */
+    price: number;
+    /**
+     * Stability score: positive means mean-reverting pressure at this level.
+     * Higher = stronger buffering. Weighted by proximity to spot.
+     */
+    stabilityScore: number;
+    /**
+     * Acceleration score: positive means trend-amplifying pressure at this level.
+     * Higher = stronger momentum fuel. Weighted by proximity to spot.
+     */
+    accelerationScore: number;
+    /**
+     * Expected signed hedge contracts (positive = dealers buy, negative = dealers sell)
+     * for a 1-point spot move toward this level. Units depend on product.
+     * @deprecated Use hedgeContracts instead for multi-product estimates.
+     */
+    expectedHedgeContracts: number;
+    /** Multi-product hedge contract estimates */
+    hedgeContracts: HedgeContractEstimates;
+    /**
+     * Whether dealers would hedge passively (limit orders / absorption)
+     * or aggressively (market orders / sweeping) at this level.
+     */
+    hedgeType: 'passive' | 'aggressive';
+}
+/**
+ * Configuration for pressure cloud computation.
+ */
+export interface PressureCloudConfig {
+    /**
+     * Product multiplier for contract conversion.
+     * NQ = 20, MNQ = 2, ES = 50, MES = 5, SPY = 100 (shares).
+     * Default: 20 (NQ)
+     */
+    contractMultiplier?: number;
+    /** Product type hint for primary contract display. Default: 'NQ' */
+    product?: 'NQ' | 'MNQ' | 'ES' | 'MES' | 'SPY';
+    /**
+     * How many expected-daily-moves to consider "reachable".
+     * Levels beyond this get heavily penalized. Default: 2.0
+     */
+    reachabilityMultiple?: number;
+    /**
+     * Minimum impulse magnitude (as fraction of mean abs impulse) to
+     * qualify as a zone. Default: 0.15
+     */
+    zoneThreshold?: number;
+}
+/**
+ * Complete pressure cloud analysis combining stability and acceleration zones.
+ */
+export interface PressureCloud {
+    /** Current spot price */
+    spot: number;
+    /** Expiration timestamp */
+    expiration: number;
+    /** Timestamp when this cloud was computed */
+    computedAt: number;
+    /**
+     * Stability zones: levels where positive dealer impulse creates
+     * mean-reverting pressure. Price decelerates into these zones.
+     * Trade approach: reversal / bounce entries.
+     */
+    stabilityZones: PressureZone[];
+    /**
+     * Acceleration zones: levels where negative dealer impulse creates
+     * trend-amplifying pressure. Price accelerates through these zones.
+     * Trade approach: momentum / breakout continuation.
+     */
+    accelerationZones: PressureZone[];
+    /**
+     * Regime edges: prices where the impulse curve crosses zero,
+     * marking transitions between mean-reverting and trend-amplifying behavior.
+     */
+    regimeEdges: RegimeEdge[];
+    /**
+     * Per-price-level detail for the full chart overlay.
+     * Every point on the impulse curve grid, enriched with scores and contract estimates.
+     */
+    priceLevels: PressureLevel[];
+}
+/**
+ * Compute a pressure cloud from an existing hedge impulse curve.
+ *
+ * The pressure cloud translates the raw impulse curve into actionable
+ * trading zones:
+ *
+ * - **Stability zones** (positive impulse peaks, weighted by proximity):
+ *   Where dealer hedging creates counter-trend flow. These are bounce/rejection
+ *   targets — price decelerates into them and often stalls or reverses.
+ *
+ * - **Acceleration zones** (negative impulse troughs, weighted by proximity):
+ *   Where dealer hedging creates with-trend flow. If price reaches these levels,
+ *   dealers amplify the move. These are momentum/breakout zones — price
+ *   accelerates through them.
+ *
+ * - **Regime edges** (zero crossings):
+ *   Where behavior flips. Critical for understanding "if price breaks past X,
+ *   the character of the tape changes."
+ *
+ * @param impulseCurve - A previously computed hedge impulse curve
+ * @param regimeParams - Regime parameters (for expected daily move / reachability)
+ * @param config - Optional tuning parameters
+ * @returns Complete pressure cloud analysis
+ */
+export declare function computePressureCloud(impulseCurve: HedgeImpulseCurve, regimeParams: RegimeParams, config?: PressureCloudConfig): PressureCloud;

package/dist/hedgeflow/pressurecloud.js

@@ -0,0 +1,243 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computePressureCloud = computePressureCloud;
+/** Product multipliers for contract conversion */
+const PRODUCT_MULTIPLIERS = {
+    NQ: 20,
+    MNQ: 2,
+    ES: 50,
+    MES: 5,
+};
+/**
+ * Convert a dollar impulse value to hedge contracts for a given product multiplier.
+ * contracts = impulse / (multiplier * spot * 0.01)
+ */
+function impulseToContracts(impulse, multiplier, spot) {
+    const denominator = multiplier * spot * 0.01;
+    return denominator > 0 ? sanitize(impulse / denominator) : 0;
+}
+/**
+ * Compute multi-product hedge contract estimates from a dollar impulse value.
+ */
+function computeHedgeContractEstimates(impulse, spot) {
+    return {
+        nq: impulseToContracts(impulse, PRODUCT_MULTIPLIERS.NQ, spot),
+        mnq: impulseToContracts(impulse, PRODUCT_MULTIPLIERS.MNQ, spot),
+        es: impulseToContracts(impulse, PRODUCT_MULTIPLIERS.ES, spot),
+        mes: impulseToContracts(impulse, PRODUCT_MULTIPLIERS.MES, spot),
+    };
+}
+// ============================================================================
+// Implementation
+// ============================================================================
+/**
+ * Compute a pressure cloud from an existing hedge impulse curve.
+ *
+ * The pressure cloud translates the raw impulse curve into actionable
+ * trading zones:
+ *
+ * - **Stability zones** (positive impulse peaks, weighted by proximity):
+ *   Where dealer hedging creates counter-trend flow. These are bounce/rejection
+ *   targets — price decelerates into them and often stalls or reverses.
+ *
+ * - **Acceleration zones** (negative impulse troughs, weighted by proximity):
+ *   Where dealer hedging creates with-trend flow. If price reaches these levels,
+ *   dealers amplify the move. These are momentum/breakout zones — price
+ *   accelerates through them.
+ *
+ * - **Regime edges** (zero crossings):
+ *   Where behavior flips. Critical for understanding "if price breaks past X,
+ *   the character of the tape changes."
+ *
+ * @param impulseCurve - A previously computed hedge impulse curve
+ * @param regimeParams - Regime parameters (for expected daily move / reachability)
+ * @param config - Optional tuning parameters
+ * @returns Complete pressure cloud analysis
+ */
+function computePressureCloud(impulseCurve, regimeParams, config = {}) {
+    const { contractMultiplier = 20, // NQ default
+    reachabilityMultiple = 2.0, zoneThreshold = 0.15, } = config;
+    const { spot, curve, extrema, zeroCrossings } = impulseCurve;
+    const expectedMove = regimeParams.expectedDailySpotMove * spot;
+    // Compute reachability-weighted scores for each price level
+    const priceLevels = computePriceLevels(curve, spot, expectedMove, reachabilityMultiple, contractMultiplier);
+    // Extract stability zones from positive impulse peaks
+    const stabilityZones = extractStabilityZones(extrema, curve, spot, expectedMove, reachabilityMultiple, zoneThreshold);
+    // Extract acceleration zones from negative impulse troughs
+    const accelerationZones = extractAccelerationZones(extrema, curve, spot, expectedMove, reachabilityMultiple, zoneThreshold);
+    // Convert zero crossings to regime edges
+    const regimeEdges = convertZeroCrossingsToEdges(zeroCrossings, spot);
+    return {
+        spot,
+        expiration: impulseCurve.expiration,
+        computedAt: Date.now(),
+        stabilityZones,
+        accelerationZones,
+        regimeEdges,
+        priceLevels,
+    };
+}
+/**
+ * Compute per-price-level detail from the impulse curve.
+ */
+function computePriceLevels(curve, spot, expectedMove, reachabilityMultiple, contractMultiplier) {
+    const reachRange = expectedMove * reachabilityMultiple;
+    return curve.map((point) => {
+        const distance = Math.abs(point.price - spot);
+        const proximity = Math.exp(-((distance / reachRange) ** 2));
+        // Stability: positive impulse weighted by proximity
+        const stabilityScore = point.impulse > 0
+            ? point.impulse * proximity
+            : 0;
+        // Acceleration: negative impulse magnitude weighted by proximity
+        const accelerationScore = point.impulse < 0
+            ? Math.abs(point.impulse) * proximity
+            : 0;
+        // Convert dollar impulse to signed contract count.
+        // impulse is $ of hedging per 1% move. For contracts per 1 point:
+        // contracts = impulse / (contractMultiplier * spot * 0.01)
+        const contractDenominator = contractMultiplier * spot * 0.01;
+        const expectedHedgeContracts = contractDenominator > 0
+            ? point.impulse / contractDenominator
+            : 0;
+        return {
+            price: point.price,
+            stabilityScore,
+            accelerationScore,
+            expectedHedgeContracts: sanitize(expectedHedgeContracts),
+            hedgeContracts: computeHedgeContractEstimates(point.impulse, spot),
+            hedgeType: point.impulse >= 0 ? 'passive' : 'aggressive',
+        };
+    });
+}
+/**
+ * Extract stability zones from positive impulse peaks (basins).
+ */
+function extractStabilityZones(extrema, curve, spot, expectedMove, reachabilityMultiple, zoneThreshold) {
+    const basins = extrema.filter((e) => e.type === 'basin');
+    if (basins.length === 0)
+        return [];
+    const reachRange = expectedMove * reachabilityMultiple;
+    const maxImpulse = Math.max(...basins.map((b) => Math.abs(b.impulse)), 1e-10);
+    // Filter by threshold
+    const significant = basins.filter((b) => Math.abs(b.impulse) / maxImpulse >= zoneThreshold);
+    // Build zones
+    const zones = significant.map((basin) => {
+        const proximity = Math.exp(-((Math.abs(basin.price - spot) / reachRange) ** 2));
+        const rawStrength = (Math.abs(basin.impulse) / maxImpulse) * proximity;
+        // Find zone width: where impulse drops to 50% of peak
+        const halfPeak = basin.impulse * 0.5;
+        const { lower, upper } = findZoneBounds(curve, basin.price, halfPeak);
+        const side = basin.price >= spot ? 'above-spot' : 'below-spot';
+        const tradeType = side === 'below-spot' ? 'long' : 'short';
+        return {
+            center: basin.price,
+            lower,
+            upper,
+            strength: Math.min(1, rawStrength),
+            side,
+            tradeType,
+            hedgeType: 'passive',
+        };
+    });
+    // Sort by strength descending
+    return zones.sort((a, b) => b.strength - a.strength);
+}
+/**
+ * Extract acceleration zones from negative impulse troughs (peaks in the type system).
+ */
+function extractAccelerationZones(extrema, curve, spot, expectedMove, reachabilityMultiple, zoneThreshold) {
+    const peaks = extrema.filter((e) => e.type === 'peak');
+    if (peaks.length === 0)
+        return [];
+    const reachRange = expectedMove * reachabilityMultiple;
+    const maxImpulse = Math.max(...peaks.map((p) => Math.abs(p.impulse)), 1e-10);
+    const significant = peaks.filter((p) => Math.abs(p.impulse) / maxImpulse >= zoneThreshold);
+    const zones = significant.map((peak) => {
+        const proximity = Math.exp(-((Math.abs(peak.price - spot) / reachRange) ** 2));
+        const rawStrength = (Math.abs(peak.impulse) / maxImpulse) * proximity;
+        const halfTrough = peak.impulse * 0.5;
+        const { lower, upper } = findZoneBounds(curve, peak.price, halfTrough);
+        const side = peak.price >= spot ? 'above-spot' : 'below-spot';
+        // Acceleration below spot → momentum short (waterfall)
+        // Acceleration above spot → momentum long (squeeze)
+        const tradeType = side === 'below-spot' ? 'short' : 'long';
+        return {
+            center: peak.price,
+            lower,
+            upper,
+            strength: Math.min(1, rawStrength),
+            side,
+            tradeType,
+            hedgeType: 'aggressive',
+        };
+    });
+    return zones.sort((a, b) => b.strength - a.strength);
+}
+/**
+ * Find the price bounds where impulse drops to the given threshold
+ * around a peak/trough center price.
+ */
+function findZoneBounds(curve, centerPrice, thresholdImpulse) {
+    // Find the center index
+    let centerIdx = 0;
+    let minDist = Infinity;
+    for (let i = 0; i < curve.length; i++) {
+        const d = Math.abs(curve[i].price - centerPrice);
+        if (d < minDist) {
+            minDist = d;
+            centerIdx = i;
+        }
+    }
+    const isPositive = thresholdImpulse > 0;
+    // Scan left for lower bound
+    let lowerIdx = centerIdx;
+    for (let i = centerIdx - 1; i >= 0; i--) {
+        if (isPositive ? curve[i].impulse < thresholdImpulse : curve[i].impulse > thresholdImpulse) {
+            lowerIdx = i;
+            break;
+        }
+        lowerIdx = i;
+    }
+    // Scan right for upper bound
+    let upperIdx = centerIdx;
+    for (let i = centerIdx + 1; i < curve.length; i++) {
+        if (isPositive ? curve[i].impulse < thresholdImpulse : curve[i].impulse > thresholdImpulse) {
+            upperIdx = i;
+            break;
+        }
+        upperIdx = i;
+    }
+    return {
+        lower: curve[lowerIdx].price,
+        upper: curve[upperIdx].price,
+    };
+}
+/**
+ * Convert impulse zero crossings into regime edge descriptors.
+ */
+function convertZeroCrossingsToEdges(crossings, spot) {
+    return crossings.map((crossing) => {
+        // A "falling" crossing means impulse goes from positive to negative.
+        // If this is below spot, moving down into it means going from
+        // stable (positive impulse) to unstable (negative impulse).
+        // If above spot, it's the reverse perspective.
+        const isBelow = crossing.price < spot;
+        let transitionType;
+        if (crossing.direction === 'falling') {
+            // Impulse goes + → -
+            transitionType = isBelow ? 'stable-to-unstable' : 'unstable-to-stable';
+        }
+        else {
+            // Impulse goes - → +
+            transitionType = isBelow ? 'unstable-to-stable' : 'stable-to-unstable';
+        }
+        return {
+            price: crossing.price,
+            transitionType,
+        };
+    });
+}
+function sanitize(value) {
+    return isFinite(value) && !isNaN(value) ? value : 0;
+}

package/dist/index.d.ts

@@ -14,8 +14,8 @@ export { buildOCCSymbol, parseOCCSymbol, generateStrikesAroundSpot, generateOCCS
 export type { OCCSymbolParams, ParsedOCCSymbol, StrikeGenerationParams, } from './utils/occ';
 export { estimateImpliedProbabilityDistribution, estimateImpliedProbabilityDistributions, getProbabilityInRange, getCumulativeProbability, getQuantile, estimateExposureAdjustedPDF, getEdgeAtPrice, getSignificantAdjustmentLevels, DEFAULT_ADJUSTMENT_CONFIG, LOW_VOL_CONFIG, CRISIS_CONFIG, OPEX_CONFIG, } from './impliedpdf';
 export type { StrikeProbability, ImpliedProbabilityDistribution, ImpliedPDFResult, ExposureAdjustmentConfig, AdjustedPDFResult, PDFComparison, } from './impliedpdf';
-export { deriveRegimeParams, interpolateIVAtStrike, computeHedgeImpulseCurve, computeCharmIntegral, analyzeHedgeFlow, } from './hedgeflow';
-export type { MarketRegime, RegimeParams, HedgeImpulseConfig, HedgeImpulsePoint, HedgeImpulseCurve, ZeroCrossing, ImpulseExtremum, DirectionalAsymmetry, ImpulseRegime, CharmIntegralConfig, CharmBucket, CharmIntegral, HedgeFlowAnalysis, } from './hedgeflow';
+export { deriveRegimeParams, interpolateIVAtStrike, computeHedgeImpulseCurve, computeCharmIntegral, computePressureCloud, analyzeHedgeFlow, } from './hedgeflow';
+export type { MarketRegime, RegimeParams, HedgeImpulseConfig, HedgeImpulsePoint, HedgeImpulseCurve, ZeroCrossing, ImpulseExtremum, DirectionalAsymmetry, ImpulseRegime, CharmIntegralConfig, CharmBucket, CharmIntegral, HedgeFlowAnalysis, HedgeContractEstimates, PressureZone, RegimeEdge, PressureLevel, PressureCloudConfig, PressureCloud, } from './hedgeflow';
 export { FloeClient, Broker } from './client/FloeClient';
 export { TradierClient } from './client/brokers/TradierClient';
 export { TastyTradeClient } from './client/brokers/TastyTradeClient';
@@ -26,3 +26,5 @@ export { computeVarianceSwapIV, computeImpliedVolatility, } from './iv';
 export type { VarianceSwapResult, ImpliedVolatilityResult, } from './iv';
 export { computeRealizedVolatility, } from './rv';
 export type { PriceObservation, RealizedVolatilityResult, } from './rv';
+export { computeVolResponseZScore, buildVolResponseObservation, } from './volresponse';
+export type { VolResponseObservation, VolResponseCoefficients, VolResponseConfig, VolResponseResult, } from './volresponse';

package/dist/index.js

@@ -20,7 +20,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.computeRealizedVolatility = exports.computeImpliedVolatility = exports.computeVarianceSwapIV = exports.createOptionChain = exports.getAdapter = exports.brokerAdapters = exports.tdaAdapter = exports.ibkrAdapter = exports.schwabAdapter = exports.genericAdapter = exports.TradeStationClient = exports.TastyTradeClient = exports.TradierClient = exports.Broker = exports.FloeClient = exports.analyzeHedgeFlow = exports.computeCharmIntegral = exports.computeHedgeImpulseCurve = exports.interpolateIVAtStrike = exports.deriveRegimeParams = exports.OPEX_CONFIG = exports.CRISIS_CONFIG = exports.LOW_VOL_CONFIG = exports.DEFAULT_ADJUSTMENT_CONFIG = exports.getSignificantAdjustmentLevels = exports.getEdgeAtPrice = exports.estimateExposureAdjustedPDF = exports.getQuantile = exports.getCumulativeProbability = exports.getProbabilityInRange = exports.estimateImpliedProbabilityDistributions = exports.estimateImpliedProbabilityDistribution = exports.generateOCCSymbolsAroundSpot = exports.generateOCCSymbolsForStrikes = exports.generateStrikesAroundSpot = exports.parseOCCSymbol = exports.buildOCCSymbol = exports.normalPDF = exports.cumulativeNormalDistribution = exports.calculateSharesNeededToCover = exports.calculateGammaVannaCharmExposures = exports.smoothTotalVarianceSmile = exports.getIVForStrike = exports.getIVSurfaces = exports.getTimeToExpirationInYears = exports.getMillisecondsToExpiration = exports.calculateImpliedVolatility = exports.calculateGreeks = exports.blackScholes = void 0;
+exports.computeRealizedVolatility = exports.computeImpliedVolatility = exports.computeVarianceSwapIV = exports.createOptionChain = exports.getAdapter = exports.brokerAdapters = exports.tdaAdapter = exports.ibkrAdapter = exports.schwabAdapter = exports.genericAdapter = exports.TradeStationClient = exports.TastyTradeClient = exports.TradierClient = exports.Broker = exports.FloeClient = exports.analyzeHedgeFlow = exports.computePressureCloud = exports.computeCharmIntegral = exports.computeHedgeImpulseCurve = exports.interpolateIVAtStrike = exports.deriveRegimeParams = exports.OPEX_CONFIG = exports.CRISIS_CONFIG = exports.LOW_VOL_CONFIG = exports.DEFAULT_ADJUSTMENT_CONFIG = exports.getSignificantAdjustmentLevels = exports.getEdgeAtPrice = exports.estimateExposureAdjustedPDF = exports.getQuantile = exports.getCumulativeProbability = exports.getProbabilityInRange = exports.estimateImpliedProbabilityDistributions = exports.estimateImpliedProbabilityDistribution = exports.generateOCCSymbolsAroundSpot = exports.generateOCCSymbolsForStrikes = exports.generateStrikesAroundSpot = exports.parseOCCSymbol = exports.buildOCCSymbol = exports.normalPDF = exports.cumulativeNormalDistribution = exports.calculateSharesNeededToCover = exports.calculateGammaVannaCharmExposures = exports.smoothTotalVarianceSmile = exports.getIVForStrike = exports.getIVSurfaces = exports.getTimeToExpirationInYears = exports.getMillisecondsToExpiration = exports.calculateImpliedVolatility = exports.calculateGreeks = exports.blackScholes = void 0;
+exports.buildVolResponseObservation = exports.computeVolResponseZScore = void 0;
 // Core types
 __exportStar(require("./types"), exports);
 // Black-Scholes pricing and Greeks
@@ -67,7 +68,7 @@ Object.defineProperty(exports, "DEFAULT_ADJUSTMENT_CONFIG", { enumerable: true,
 Object.defineProperty(exports, "LOW_VOL_CONFIG", { enumerable: true, get: function () { return impliedpdf_1.LOW_VOL_CONFIG; } });
 Object.defineProperty(exports, "CRISIS_CONFIG", { enumerable: true, get: function () { return impliedpdf_1.CRISIS_CONFIG; } });
 Object.defineProperty(exports, "OPEX_CONFIG", { enumerable: true, get: function () { return impliedpdf_1.OPEX_CONFIG; } });
-// Hedge flow analysis (impulse curve, charm integral, regime derivation)
+// Hedge flow analysis (impulse curve, charm integral, regime derivation, pressure cloud)
 var hedgeflow_1 = require("./hedgeflow");
 // Regime derivation from IV surface
 Object.defineProperty(exports, "deriveRegimeParams", { enumerable: true, get: function () { return hedgeflow_1.deriveRegimeParams; } });
@@ -76,6 +77,8 @@ Object.defineProperty(exports, "interpolateIVAtStrike", { enumerable: true, get:
 Object.defineProperty(exports, "computeHedgeImpulseCurve", { enumerable: true, get: function () { return hedgeflow_1.computeHedgeImpulseCurve; } });
 // Charm integral
 Object.defineProperty(exports, "computeCharmIntegral", { enumerable: true, get: function () { return hedgeflow_1.computeCharmIntegral; } });
+// Pressure cloud (stability/acceleration zones)
+Object.defineProperty(exports, "computePressureCloud", { enumerable: true, get: function () { return hedgeflow_1.computePressureCloud; } });
 // Combined analysis
 Object.defineProperty(exports, "analyzeHedgeFlow", { enumerable: true, get: function () { return hedgeflow_1.analyzeHedgeFlow; } });
 // Client
@@ -104,3 +107,7 @@ Object.defineProperty(exports, "computeImpliedVolatility", { enumerable: true, g
 // Realized volatility (tick-based quadratic variation)
 var rv_1 = require("./rv");
 Object.defineProperty(exports, "computeRealizedVolatility", { enumerable: true, get: function () { return rv_1.computeRealizedVolatility; } });
+// Vol response model (IV response residual / vol bid-offered z-score)
+var volresponse_1 = require("./volresponse");
+Object.defineProperty(exports, "computeVolResponseZScore", { enumerable: true, get: function () { return volresponse_1.computeVolResponseZScore; } });
+Object.defineProperty(exports, "buildVolResponseObservation", { enumerable: true, get: function () { return volresponse_1.buildVolResponseObservation; } });

package/dist/volresponse/index.d.ts

@@ -0,0 +1,42 @@
+import { VolResponseObservation, VolResponseConfig, VolResponseResult } from './types';
+export type { VolResponseObservation, VolResponseCoefficients, VolResponseConfig, VolResponseResult, } from './types';
+/**
+ * Build a VolResponseObservation from consecutive IV/RV/spot readings.
+ *
+ * The consumer calls this on each tick after the first, passing the
+ * current and previous IV/spot values. The resulting observation can
+ * then be accumulated and passed to computeVolResponseZScore.
+ *
+ * @param current - Current tick values
+ * @param previous - Previous tick values (IV and spot only)
+ * @returns A VolResponseObservation ready for the regression
+ */
+export declare function buildVolResponseObservation(current: {
+    iv: number;
+    rv: number;
+    spot: number;
+    timestamp: number;
+}, previous: {
+    iv: number;
+    spot: number;
+}): VolResponseObservation;
+/**
+ * Compute the vol response z-score from accumulated observations.
+ *
+ * Fits an expanding-window OLS regression:
+ *
+ *   deltaIV(t) ~ a + b1*return + b2*|return| + b3*RV + b4*IV_level
+ *
+ * Then computes the residual of the most recent observation and
+ * normalizes it by the residual standard deviation to produce a z-score.
+ *
+ * Interpretation:
+ * - z >> 0: vol is bid relative to baseline (stress / demand)
+ * - z << 0: vol is offered relative to baseline (supply / crush)
+ * - z ~ 0: normal vol response given the price path
+ *
+ * @param observations - All accumulated VolResponseObservation for the session
+ * @param config - Optional configuration overrides
+ * @returns VolResponseResult with z-score and signal classification
+ */
+export declare function computeVolResponseZScore(observations: VolResponseObservation[], config?: VolResponseConfig): VolResponseResult;

package/dist/volresponse/index.js

@@ -0,0 +1,251 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildVolResponseObservation = buildVolResponseObservation;
+exports.computeVolResponseZScore = computeVolResponseZScore;
+// Number of features in the regression (intercept + 4 regressors)
+const NUM_FEATURES = 5;
+// Small ridge penalty for numerical stability of the normal equations
+const RIDGE_LAMBDA = 1e-8;
+/**
+ * Build a VolResponseObservation from consecutive IV/RV/spot readings.
+ *
+ * The consumer calls this on each tick after the first, passing the
+ * current and previous IV/spot values. The resulting observation can
+ * then be accumulated and passed to computeVolResponseZScore.
+ *
+ * @param current - Current tick values
+ * @param previous - Previous tick values (IV and spot only)
+ * @returns A VolResponseObservation ready for the regression
+ */
+function buildVolResponseObservation(current, previous) {
+    const deltaIV = current.iv - previous.iv;
+    const spotReturn = Math.log(current.spot / previous.spot);
+    return {
+        timestamp: current.timestamp,
+        deltaIV,
+        spotReturn,
+        absSpotReturn: Math.abs(spotReturn),
+        rvLevel: current.rv,
+        ivLevel: current.iv,
+    };
+}
+/**
+ * Compute the vol response z-score from accumulated observations.
+ *
+ * Fits an expanding-window OLS regression:
+ *
+ *   deltaIV(t) ~ a + b1*return + b2*|return| + b3*RV + b4*IV_level
+ *
+ * Then computes the residual of the most recent observation and
+ * normalizes it by the residual standard deviation to produce a z-score.
+ *
+ * Interpretation:
+ * - z >> 0: vol is bid relative to baseline (stress / demand)
+ * - z << 0: vol is offered relative to baseline (supply / crush)
+ * - z ~ 0: normal vol response given the price path
+ *
+ * @param observations - All accumulated VolResponseObservation for the session
+ * @param config - Optional configuration overrides
+ * @returns VolResponseResult with z-score and signal classification
+ */
+function computeVolResponseZScore(observations, config = {}) {
+    const { minObservations = 30, volBidThreshold = 1.5, volOfferedThreshold = -1.5, } = config;
+    const emptyCoefficients = {
+        intercept: 0,
+        betaReturn: 0,
+        betaAbsReturn: 0,
+        betaRV: 0,
+        betaIVLevel: 0,
+    };
+    if (observations.length < minObservations) {
+        return {
+            isValid: false,
+            minObservations,
+            numObservations: observations.length,
+            coefficients: emptyCoefficients,
+            rSquared: 0,
+            residualStdDev: 0,
+            expectedDeltaIV: 0,
+            observedDeltaIV: observations.length > 0 ? observations[observations.length - 1].deltaIV : 0,
+            residual: 0,
+            zScore: 0,
+            signal: 'insufficient_data',
+            timestamp: observations.length > 0 ? observations[observations.length - 1].timestamp : 0,
+        };
+    }
+    // Build design matrix X and response vector y
+    const n = observations.length;
+    const X = new Array(n);
+    const y = new Array(n);
+    for (let i = 0; i < n; i++) {
+        const obs = observations[i];
+        X[i] = [1, obs.spotReturn, obs.absSpotReturn, obs.rvLevel, obs.ivLevel];
+        y[i] = obs.deltaIV;
+    }
+    // Solve OLS via normal equations with ridge regularization
+    const ols = solveOLS(X, y);
+    if (!ols) {
+        return {
+            isValid: false,
+            minObservations,
+            numObservations: n,
+            coefficients: emptyCoefficients,
+            rSquared: 0,
+            residualStdDev: 0,
+            expectedDeltaIV: 0,
+            observedDeltaIV: observations[n - 1].deltaIV,
+            residual: 0,
+            zScore: 0,
+            signal: 'insufficient_data',
+            timestamp: observations[n - 1].timestamp,
+        };
+    }
+    const { beta, residuals, rSquared, residualStdDev } = ols;
+    const lastObs = observations[n - 1];
+    const lastX = X[n - 1];
+    // Predicted deltaIV for the most recent observation
+    let expectedDeltaIV = 0;
+    for (let j = 0; j < NUM_FEATURES; j++) {
+        expectedDeltaIV += beta[j] * lastX[j];
+    }
+    const residual = lastObs.deltaIV - expectedDeltaIV;
+    const zScore = residualStdDev > 0 ? residual / residualStdDev : 0;
+    let signal = 'neutral';
+    if (zScore > volBidThreshold) {
+        signal = 'vol_bid';
+    }
+    else if (zScore < volOfferedThreshold) {
+        signal = 'vol_offered';
+    }
+    const coefficients = {
+        intercept: beta[0],
+        betaReturn: beta[1],
+        betaAbsReturn: beta[2],
+        betaRV: beta[3],
+        betaIVLevel: beta[4],
+    };
+    return {
+        isValid: true,
+        minObservations,
+        numObservations: n,
+        coefficients,
+        rSquared,
+        residualStdDev,
+        expectedDeltaIV,
+        observedDeltaIV: lastObs.deltaIV,
+        residual,
+        zScore,
+        signal,
+        timestamp: lastObs.timestamp,
+    };
+}
+/**
+ * Solve ordinary least squares: beta = (X'X + lambda*I)^{-1} X'y
+ *
+ * For a small system (5 features), direct inversion via Gauss-Jordan
+ * elimination is efficient and avoids external dependencies.
+ */
+function solveOLS(X, y) {
+    const n = X.length;
+    const p = NUM_FEATURES;
+    // Compute X'X (p x p)
+    const XtX = new Array(p);
+    for (let i = 0; i < p; i++) {
+        XtX[i] = new Array(p).fill(0);
+        for (let j = 0; j < p; j++) {
+            let sum = 0;
+            for (let k = 0; k < n; k++) {
+                sum += X[k][i] * X[k][j];
+            }
+            XtX[i][j] = sum;
+        }
+    }
+    // Add ridge penalty to diagonal (skip intercept at index 0)
+    for (let i = 1; i < p; i++) {
+        XtX[i][i] += RIDGE_LAMBDA;
+    }
+    // Compute X'y (p x 1)
+    const Xty = new Array(p).fill(0);
+    for (let i = 0; i < p; i++) {
+        let sum = 0;
+        for (let k = 0; k < n; k++) {
+            sum += X[k][i] * y[k];
+        }
+        Xty[i] = sum;
+    }
+    // Solve (X'X + lambda*I) * beta = X'y via Gauss-Jordan elimination
+    // Augment [XtX | Xty] into a (p x p+1) matrix
+    const aug = new Array(p);
+    for (let i = 0; i < p; i++) {
+        aug[i] = new Array(p + 1);
+        for (let j = 0; j < p; j++) {
+            aug[i][j] = XtX[i][j];
+        }
+        aug[i][p] = Xty[i];
+    }
+    // Forward elimination with partial pivoting
+    for (let col = 0; col < p; col++) {
+        // Find pivot
+        let maxVal = Math.abs(aug[col][col]);
+        let maxRow = col;
+        for (let row = col + 1; row < p; row++) {
+            const val = Math.abs(aug[row][col]);
+            if (val > maxVal) {
+                maxVal = val;
+                maxRow = row;
+            }
+        }
+        if (maxVal < 1e-14) {
+            return null; // Singular matrix
+        }
+        // Swap rows
+        if (maxRow !== col) {
+            const temp = aug[col];
+            aug[col] = aug[maxRow];
+            aug[maxRow] = temp;
+        }
+        // Eliminate below and above
+        const pivot = aug[col][col];
+        for (let j = col; j <= p; j++) {
+            aug[col][j] /= pivot;
+        }
+        for (let row = 0; row < p; row++) {
+            if (row === col)
+                continue;
+            const factor = aug[row][col];
+            for (let j = col; j <= p; j++) {
+                aug[row][j] -= factor * aug[col][j];
+            }
+        }
+    }
+    // Extract beta
+    const beta = new Array(p);
+    for (let i = 0; i < p; i++) {
+        beta[i] = aug[i][p];
+        if (!isFinite(beta[i]))
+            return null;
+    }
+    // Compute residuals and statistics
+    const residuals = new Array(n);
+    let ssRes = 0;
+    let yMean = 0;
+    for (let i = 0; i < n; i++) {
+        yMean += y[i];
+    }
+    yMean /= n;
+    let ssTot = 0;
+    for (let i = 0; i < n; i++) {
+        let predicted = 0;
+        for (let j = 0; j < p; j++) {
+            predicted += beta[j] * X[i][j];
+        }
+        residuals[i] = y[i] - predicted;
+        ssRes += residuals[i] * residuals[i];
+        ssTot += (y[i] - yMean) * (y[i] - yMean);
+    }
+    const rSquared = ssTot > 0 ? Math.max(0, 1 - ssRes / ssTot) : 0;
+    // Residual standard deviation (using n - p degrees of freedom)
+    const dof = Math.max(n - p, 1);
+    const residualStdDev = Math.sqrt(ssRes / dof);
+    return { beta, residuals, rSquared, residualStdDev };
+}

package/dist/volresponse/types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * A single observation for the vol response regression model.
+ * The consumer accumulates these as the 0DTE session progresses.
+ */
+export interface VolResponseObservation {
+    /** Timestamp in milliseconds */
+    timestamp: number;
+    /** Change in IV from previous observation: IV(t) - IV(t-1), as decimal */
+    deltaIV: number;
+    /** Log return of spot: ln(S(t) / S(t-1)) */
+    spotReturn: number;
+    /** Absolute value of the log return */
+    absSpotReturn: number;
+    /** Current realized volatility level (annualized, decimal) */
+    rvLevel: number;
+    /** Current IV level (annualized, decimal) */
+    ivLevel: number;
+}
+/**
+ * Regression coefficients from the IV response model.
+ *
+ *   deltaIV(t) ~ intercept + b1*return + b2*|return| + b3*RV + b4*IV_level
+ */
+export interface VolResponseCoefficients {
+    /** Intercept */
+    intercept: number;
+    /** Coefficient on signed spot return (captures spot-vol correlation) */
+    betaReturn: number;
+    /** Coefficient on |return| (captures vol-of-vol / convexity response) */
+    betaAbsReturn: number;
+    /** Coefficient on RV level (captures RV mean-reversion effect) */
+    betaRV: number;
+    /** Coefficient on IV level (captures IV mean-reversion effect) */
+    betaIVLevel: number;
+}
+/**
+ * Configuration for the vol response model.
+ */
+export interface VolResponseConfig {
+    /** Minimum observations before the model is considered valid. Default: 30 */
+    minObservations?: number;
+    /** Z-score threshold for vol_bid signal. Default: 1.5 */
+    volBidThreshold?: number;
+    /** Z-score threshold for vol_offered signal. Default: -1.5 */
+    volOfferedThreshold?: number;
+}
+/**
+ * Full result of the vol response residual model.
+ */
+export interface VolResponseResult {
+    /** Whether the model has enough data to be meaningful */
+    isValid: boolean;
+    /** Minimum number of observations required (for reference) */
+    minObservations: number;
+    /** Number of observations used in the regression */
+    numObservations: number;
+    /** Fitted regression coefficients */
+    coefficients: VolResponseCoefficients;
+    /** R-squared of the regression */
+    rSquared: number;
+    /** Standard deviation of the residuals */
+    residualStdDev: number;
+    /** The most recent predicted (expected) deltaIV */
+    expectedDeltaIV: number;
+    /** The most recent observed deltaIV */
+    observedDeltaIV: number;
+    /** The residual: observed - expected */
+    residual: number;
+    /** The z-score: residual / residualStdDev */
+    zScore: number;
+    /** Discrete signal classification */
+    signal: 'vol_bid' | 'vol_offered' | 'neutral' | 'insufficient_data';
+    /** Timestamp of the most recent observation */
+    timestamp: number;
+}

package/dist/volresponse/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fullstackcraftllc/floe",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "description": "Production-ready options analytics toolkit. Normalize broker data structures and calculate Black-Scholes, Greeks, and exposures with a clean, type-safe API. Built for trading platforms and fintech applications.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -8,7 +8,9 @@
     "build": "tsc",
     "test": "jest",
     "prepublishOnly": "npm run build",
-    "type-check": "tsc --noEmit"
+    "type-check": "tsc --noEmit",
+    "prepare": "husky",
+    "copy-whitepaper": "cp whitepaper/whitepaper.pdf site/public/whitepaper.pdf"
   },
   "keywords": [
     "options",
@@ -42,6 +44,7 @@
     "@types/jest": "^29.5.0",
     "@types/node": "^20.0.0",
     "dotenv": "^17.2.3",
+    "husky": "^9.1.7",
     "jest": "^29.5.0",
     "ts-jest": "^29.1.0",
     "typescript": "^5.9.3"