@fullstackcraftllc/floe 0.0.14 → 0.0.16

package/dist/hedgeflow/types.js

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

package/dist/impliedpdf/adjusted.d.ts

@@ -114,7 +114,7 @@ export declare const OPEX_CONFIG: ExposureAdjustmentConfig;
  * @param symbol - Underlying ticker symbol
  * @param underlyingPrice - Current spot price
  * @param callOptions - Call options for a single expiry
- * @param exposures - Exposure metrics from calculateGammaVannaCharmExposures()
+ * @param exposures - Canonical exposure metrics from calculateGammaVannaCharmExposures()
  * @param config - Adjustment configuration (uses defaults if not provided)
  * @returns Baseline and adjusted PDFs with comparison metrics
  *
@@ -122,7 +122,10 @@ export declare const OPEX_CONFIG: ExposureAdjustmentConfig;
  * ```typescript
  * // Get exposures first
  * const allExposures = calculateGammaVannaCharmExposures(chain, ivSurfaces);
- * const expiryExposures = allExposures.find(e => e.expiration === targetExpiry);
+ * const expiry = allExposures.find(e => e.expiration === targetExpiry);
+ * const expiryExposures = expiry
+ *   ? { spotPrice: expiry.spotPrice, expiration: expiry.expiration, ...expiry.canonical }
+ *   : undefined;
  *
  * // Calculate adjusted PDF
  * const result = estimateExposureAdjustedPDF(

package/dist/impliedpdf/adjusted.js

@@ -122,7 +122,7 @@ exports.OPEX_CONFIG = {
  * @param symbol - Underlying ticker symbol
  * @param underlyingPrice - Current spot price
  * @param callOptions - Call options for a single expiry
- * @param exposures - Exposure metrics from calculateGammaVannaCharmExposures()
+ * @param exposures - Canonical exposure metrics from calculateGammaVannaCharmExposures()
  * @param config - Adjustment configuration (uses defaults if not provided)
  * @returns Baseline and adjusted PDFs with comparison metrics
  *
@@ -130,7 +130,10 @@ exports.OPEX_CONFIG = {
  * ```typescript
  * // Get exposures first
  * const allExposures = calculateGammaVannaCharmExposures(chain, ivSurfaces);
- * const expiryExposures = allExposures.find(e => e.expiration === targetExpiry);
+ * const expiry = allExposures.find(e => e.expiration === targetExpiry);
+ * const expiryExposures = expiry
+ *   ? { spotPrice: expiry.spotPrice, expiration: expiry.expiration, ...expiry.canonical }
+ *   : undefined;
  *
  * // Calculate adjusted PDF
  * const result = estimateExposureAdjustedPDF(

package/dist/index.d.ts

@@ -14,11 +14,15 @@ 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, normalizeExposures, calculatePressureAt, buildPressureGrid, calculateIVPressures, predictIVSurfaceEvolution, runCascadeSimulation, analyzeIVPath, getIVPathOfLeastResistance, DEFAULT_IV_PATH_CONFIG, } from './pressure';
-export type { MarketRegime, RegimeParams, NormalizedExposure, NormalizedExposureSummary, HedgingPressure, PressureGridCell, KeyLevels, PathOfLeastResistance, PressureGrid, StrikeIVPressure, IVSurfaceEvolution, CascadeStep, CascadeSimulation, IVPathConfig, } from './pressure';
+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 { FloeClient, Broker } from './client/FloeClient';
 export { TradierClient } from './client/brokers/TradierClient';
 export { TastyTradeClient } from './client/brokers/TastyTradeClient';
 export { TradeStationClient } from './client/brokers/TradeStationClient';
 export type { AggressorSide, IntradayTrade } from './client/brokers/TradierClient';
 export { genericAdapter, schwabAdapter, ibkrAdapter, tdaAdapter, brokerAdapters, getAdapter, createOptionChain, } from './adapters';
+export { computeVarianceSwapIV, computeImpliedVolatility, } from './iv';
+export type { VarianceSwapResult, ImpliedVolatilityResult, } from './iv';
+export { computeRealizedVolatility, } from './rv';
+export type { PriceObservation, RealizedVolatilityResult, } from './rv';

package/dist/index.js

@@ -20,8 +20,7 @@ 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.brokerAdapters = exports.tdaAdapter = exports.ibkrAdapter = exports.schwabAdapter = exports.genericAdapter = exports.TradeStationClient = exports.TastyTradeClient = exports.TradierClient = exports.Broker = exports.FloeClient = 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 = 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.createOptionChain = exports.getAdapter = 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.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;
 // Core types
 __exportStar(require("./types"), exports);
 // Black-Scholes pricing and Greeks
@@ -68,23 +67,17 @@ 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; } });
-// Pressure field and IV path prediction
-var pressure_1 = require("./pressure");
-// Regime derivation
-Object.defineProperty(exports, "deriveRegimeParams", { enumerable: true, get: function () { return pressure_1.deriveRegimeParams; } });
-Object.defineProperty(exports, "interpolateIVAtStrike", { enumerable: true, get: function () { return pressure_1.interpolateIVAtStrike; } });
-// Exposure normalization
-Object.defineProperty(exports, "normalizeExposures", { enumerable: true, get: function () { return pressure_1.normalizeExposures; } });
-// Pressure field
-Object.defineProperty(exports, "calculatePressureAt", { enumerable: true, get: function () { return pressure_1.calculatePressureAt; } });
-Object.defineProperty(exports, "buildPressureGrid", { enumerable: true, get: function () { return pressure_1.buildPressureGrid; } });
-// IV path prediction
-Object.defineProperty(exports, "calculateIVPressures", { enumerable: true, get: function () { return pressure_1.calculateIVPressures; } });
-Object.defineProperty(exports, "predictIVSurfaceEvolution", { enumerable: true, get: function () { return pressure_1.predictIVSurfaceEvolution; } });
-Object.defineProperty(exports, "runCascadeSimulation", { enumerable: true, get: function () { return pressure_1.runCascadeSimulation; } });
-Object.defineProperty(exports, "analyzeIVPath", { enumerable: true, get: function () { return pressure_1.analyzeIVPath; } });
-Object.defineProperty(exports, "getIVPathOfLeastResistance", { enumerable: true, get: function () { return pressure_1.getIVPathOfLeastResistance; } });
-Object.defineProperty(exports, "DEFAULT_IV_PATH_CONFIG", { enumerable: true, get: function () { return pressure_1.DEFAULT_IV_PATH_CONFIG; } });
+// Hedge flow analysis (impulse curve, charm integral, regime derivation)
+var hedgeflow_1 = require("./hedgeflow");
+// Regime derivation from IV surface
+Object.defineProperty(exports, "deriveRegimeParams", { enumerable: true, get: function () { return hedgeflow_1.deriveRegimeParams; } });
+Object.defineProperty(exports, "interpolateIVAtStrike", { enumerable: true, get: function () { return hedgeflow_1.interpolateIVAtStrike; } });
+// Hedge impulse curve
+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; } });
+// Combined analysis
+Object.defineProperty(exports, "analyzeHedgeFlow", { enumerable: true, get: function () { return hedgeflow_1.analyzeHedgeFlow; } });
 // Client
 var FloeClient_1 = require("./client/FloeClient");
 Object.defineProperty(exports, "FloeClient", { enumerable: true, get: function () { return FloeClient_1.FloeClient; } });
@@ -104,3 +97,10 @@ Object.defineProperty(exports, "tdaAdapter", { enumerable: true, get: function (
 Object.defineProperty(exports, "brokerAdapters", { enumerable: true, get: function () { return adapters_1.brokerAdapters; } });
 Object.defineProperty(exports, "getAdapter", { enumerable: true, get: function () { return adapters_1.getAdapter; } });
 Object.defineProperty(exports, "createOptionChain", { enumerable: true, get: function () { return adapters_1.createOptionChain; } });
+// Model-free implied volatility (variance swap / VIX methodology)
+var iv_1 = require("./iv");
+Object.defineProperty(exports, "computeVarianceSwapIV", { enumerable: true, get: function () { return iv_1.computeVarianceSwapIV; } });
+Object.defineProperty(exports, "computeImpliedVolatility", { enumerable: true, get: function () { return iv_1.computeImpliedVolatility; } });
+// Realized volatility (tick-based quadratic variation)
+var rv_1 = require("./rv");
+Object.defineProperty(exports, "computeRealizedVolatility", { enumerable: true, get: function () { return rv_1.computeRealizedVolatility; } });

package/dist/iv/index.d.ts

@@ -0,0 +1,52 @@
+import { NormalizedOption } from '../types';
+import { VarianceSwapResult, ImpliedVolatilityResult } from './types';
+export type { VarianceSwapResult, ImpliedVolatilityResult } from './types';
+/**
+ * Compute the model-free implied variance for a single expiration
+ * using the CBOE variance swap methodology.
+ *
+ * This implements the formula:
+ *
+ *   σ² = (2/T) × Σᵢ (ΔKᵢ/Kᵢ²) × e^(rT) × Q(Kᵢ) - (1/T) × (F/K₀ - 1)²
+ *
+ * Where:
+ * - K₀ is the strike where |call_mid - put_mid| is minimized
+ * - F = K₀ + e^(rT) × (call(K₀) - put(K₀)) is the forward price
+ * - Q(Kᵢ) = put mid for Kᵢ < K₀, call mid for Kᵢ > K₀,
+ *   average of call and put mids at K₀
+ * - ΔKᵢ = (Kᵢ₊₁ - Kᵢ₋₁) / 2 (actual strike spacing, not hardcoded)
+ *
+ * Two consecutive zero-bid options terminate the summation in each
+ * direction (puts walking down, calls walking up), per CBOE rules.
+ *
+ * @param options - All options for one expiration (calls and puts)
+ * @param spot - Current underlying price
+ * @param riskFreeRate - Annual risk-free rate as decimal (e.g. 0.05)
+ * @returns Variance swap result with annualized IV
+ */
+export declare function computeVarianceSwapIV(options: NormalizedOption[], spot: number, riskFreeRate: number): VarianceSwapResult;
+/**
+ * Compute implied volatility from option prices using the CBOE
+ * variance swap methodology.
+ *
+ * If only nearTermOptions are provided, computes the single-expiration
+ * model-free implied volatility directly.
+ *
+ * If farTermOptions are also provided, performs CBOE VIX-style
+ * interpolation between the two terms to produce a constant-maturity
+ * measure at `targetDays` (defaults to the far term's DTE).
+ *
+ * The interpolation formula (in variance space):
+ *
+ *   VIX = 100 × √{ [T₁σ₁² × (N₂ - N_target)/(N₂ - N₁)
+ *                   + T₂σ₂² × (N_target - N₁)/(N₂ - N₁)]
+ *                   × N_365 / N_target }
+ *
+ * @param nearTermOptions - Options for the near-term expiration
+ * @param spot - Current underlying price
+ * @param riskFreeRate - Annual risk-free rate as decimal
+ * @param farTermOptions - Options for the far-term expiration (optional)
+ * @param targetDays - Target constant maturity in days for interpolation
+ *                     (defaults to far term DTE if far term provided)
+ */
+export declare function computeImpliedVolatility(nearTermOptions: NormalizedOption[], spot: number, riskFreeRate: number, farTermOptions?: NormalizedOption[] | null, targetDays?: number): ImpliedVolatilityResult;

package/dist/iv/index.js

@@ -0,0 +1,287 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeVarianceSwapIV = computeVarianceSwapIV;
+exports.computeImpliedVolatility = computeImpliedVolatility;
+const types_1 = require("../types");
+const blackscholes_1 = require("../blackscholes");
+// ============================================================================
+// Internal helpers
+// ============================================================================
+/**
+ * Compute ΔK for each strike: half the distance between adjacent strikes.
+ * For endpoints, use the distance to the single neighbor.
+ */
+function computeDeltaK(strikes) {
+    const deltaK = new Map();
+    if (strikes.length === 0)
+        return deltaK;
+    if (strikes.length === 1) {
+        deltaK.set(strikes[0], 1); // fallback
+        return deltaK;
+    }
+    for (let i = 0; i < strikes.length; i++) {
+        if (i === 0) {
+            deltaK.set(strikes[i], strikes[i + 1] - strikes[i]);
+        }
+        else if (i === strikes.length - 1) {
+            deltaK.set(strikes[i], strikes[i] - strikes[i - 1]);
+        }
+        else {
+            deltaK.set(strikes[i], (strikes[i + 1] - strikes[i - 1]) / 2);
+        }
+    }
+    return deltaK;
+}
+/**
+ * Group options by strike, pairing calls and puts.
+ */
+function pairOptionsByStrike(options) {
+    const pairs = new Map();
+    for (const opt of options) {
+        const existing = pairs.get(opt.strike) || {};
+        if (opt.optionType === 'call') {
+            existing.call = opt;
+        }
+        else {
+            existing.put = opt;
+        }
+        pairs.set(opt.strike, existing);
+    }
+    return pairs;
+}
+/**
+ * Get mid price for an option. Returns 0 if no valid quote.
+ */
+function midPrice(opt) {
+    if (!opt)
+        return 0;
+    if (opt.bid > 0 && opt.ask > 0)
+        return (opt.bid + opt.ask) / 2;
+    if (opt.mark > 0)
+        return opt.mark;
+    return 0;
+}
+/**
+ * Compute the model-free implied variance for a single expiration
+ * using the CBOE variance swap methodology.
+ *
+ * This implements the formula:
+ *
+ *   σ² = (2/T) × Σᵢ (ΔKᵢ/Kᵢ²) × e^(rT) × Q(Kᵢ) - (1/T) × (F/K₀ - 1)²
+ *
+ * Where:
+ * - K₀ is the strike where |call_mid - put_mid| is minimized
+ * - F = K₀ + e^(rT) × (call(K₀) - put(K₀)) is the forward price
+ * - Q(Kᵢ) = put mid for Kᵢ < K₀, call mid for Kᵢ > K₀,
+ *   average of call and put mids at K₀
+ * - ΔKᵢ = (Kᵢ₊₁ - Kᵢ₋₁) / 2 (actual strike spacing, not hardcoded)
+ *
+ * Two consecutive zero-bid options terminate the summation in each
+ * direction (puts walking down, calls walking up), per CBOE rules.
+ *
+ * @param options - All options for one expiration (calls and puts)
+ * @param spot - Current underlying price
+ * @param riskFreeRate - Annual risk-free rate as decimal (e.g. 0.05)
+ * @returns Variance swap result with annualized IV
+ */
+function computeVarianceSwapIV(options, spot, riskFreeRate) {
+    // Pair calls and puts by strike
+    const pairs = pairOptionsByStrike(options);
+    const strikes = Array.from(pairs.keys()).sort((a, b) => a - b);
+    if (strikes.length === 0) {
+        return emptyResult(spot);
+    }
+    // Use first option's expiration (all should be same expiry)
+    const expiration = options[0].expirationTimestamp;
+    const T = (0, blackscholes_1.getTimeToExpirationInYears)(expiration);
+    if (T <= 0) {
+        return emptyResult(spot);
+    }
+    const r = riskFreeRate;
+    const eRT = Math.exp(r * T);
+    // Step 1: Find K₀ — strike where |call_mid - put_mid| is minimized
+    // Only consider strikes within reasonable range of spot
+    let k0 = strikes[0];
+    let minDiff = Infinity;
+    let callAtK0 = 0;
+    let putAtK0 = 0;
+    for (const strike of strikes) {
+        const pair = pairs.get(strike);
+        const callMid = midPrice(pair.call);
+        const putMid = midPrice(pair.put);
+        if (callMid > 0 && putMid > 0) {
+            const diff = Math.abs(callMid - putMid);
+            if (diff < minDiff) {
+                minDiff = diff;
+                k0 = strike;
+                callAtK0 = callMid;
+                putAtK0 = putMid;
+            }
+        }
+    }
+    // Step 2: Forward price via put-call parity
+    const F = k0 + eRT * (callAtK0 - putAtK0);
+    // Step 3: Compute ΔK for each strike
+    const deltaKMap = computeDeltaK(strikes);
+    // Step 4: Sum OTM contributions
+    // Puts below K₀ (walk down, stop after two consecutive zero bids)
+    let putContribution = 0;
+    let callContribution = 0;
+    let numStrikes = 0;
+    // Put side: strikes ≤ K₀, walking downward from K₀
+    const putStrikes = strikes.filter(k => k <= k0).reverse(); // descending
+    let consecutiveZeroBids = 0;
+    for (const strike of putStrikes) {
+        const pair = pairs.get(strike);
+        const dk = deltaKMap.get(strike) || 1;
+        let Q = 0;
+        if (strike === k0) {
+            // At K₀: average of call and put
+            Q = (midPrice(pair.call) + midPrice(pair.put)) / 2;
+        }
+        else {
+            // Below K₀: use put
+            if (!pair.put || pair.put.bid === 0) {
+                consecutiveZeroBids++;
+                if (consecutiveZeroBids >= 2)
+                    break;
+                continue;
+            }
+            consecutiveZeroBids = 0;
+            Q = midPrice(pair.put);
+        }
+        if (Q > 0) {
+            putContribution += (dk / (strike * strike)) * eRT * Q;
+            numStrikes++;
+        }
+    }
+    // Call side: strikes ≥ K₀, walking upward from K₀
+    const callStrikes = strikes.filter(k => k >= k0); // ascending
+    consecutiveZeroBids = 0;
+    for (const strike of callStrikes) {
+        const pair = pairs.get(strike);
+        const dk = deltaKMap.get(strike) || 1;
+        let Q = 0;
+        if (strike === k0) {
+            // Already counted in put side, skip to avoid double-counting
+            continue;
+        }
+        else {
+            // Above K₀: use call
+            if (!pair.call || pair.call.bid === 0) {
+                consecutiveZeroBids++;
+                if (consecutiveZeroBids >= 2)
+                    break;
+                continue;
+            }
+            consecutiveZeroBids = 0;
+            Q = midPrice(pair.call);
+        }
+        if (Q > 0) {
+            callContribution += (dk / (strike * strike)) * eRT * Q;
+            numStrikes++;
+        }
+    }
+    // Step 5: Compute σ²
+    const totalContribution = putContribution + callContribution;
+    const variance = (2 / T) * totalContribution - (1 / T) * Math.pow(F / k0 - 1, 2);
+    // Guard against negative variance (can happen with bad data)
+    const clampedVariance = Math.max(0, variance);
+    const iv = Math.sqrt(clampedVariance);
+    return {
+        impliedVolatility: iv,
+        annualizedVariance: clampedVariance,
+        forward: F,
+        k0,
+        timeToExpiry: T,
+        expiration,
+        numStrikes,
+        putContribution,
+        callContribution,
+    };
+}
+/**
+ * Compute implied volatility from option prices using the CBOE
+ * variance swap methodology.
+ *
+ * If only nearTermOptions are provided, computes the single-expiration
+ * model-free implied volatility directly.
+ *
+ * If farTermOptions are also provided, performs CBOE VIX-style
+ * interpolation between the two terms to produce a constant-maturity
+ * measure at `targetDays` (defaults to the far term's DTE).
+ *
+ * The interpolation formula (in variance space):
+ *
+ *   VIX = 100 × √{ [T₁σ₁² × (N₂ - N_target)/(N₂ - N₁)
+ *                   + T₂σ₂² × (N_target - N₁)/(N₂ - N₁)]
+ *                   × N_365 / N_target }
+ *
+ * @param nearTermOptions - Options for the near-term expiration
+ * @param spot - Current underlying price
+ * @param riskFreeRate - Annual risk-free rate as decimal
+ * @param farTermOptions - Options for the far-term expiration (optional)
+ * @param targetDays - Target constant maturity in days for interpolation
+ *                     (defaults to far term DTE if far term provided)
+ */
+function computeImpliedVolatility(nearTermOptions, spot, riskFreeRate, farTermOptions, targetDays) {
+    const nearResult = computeVarianceSwapIV(nearTermOptions, spot, riskFreeRate);
+    // Single-term mode
+    if (!farTermOptions || farTermOptions.length === 0) {
+        return {
+            impliedVolatility: nearResult.impliedVolatility,
+            nearTerm: nearResult,
+            farTerm: null,
+            targetDays: null,
+            isInterpolated: false,
+        };
+    }
+    // Two-term interpolation mode
+    const farResult = computeVarianceSwapIV(farTermOptions, spot, riskFreeRate);
+    const N1 = nearResult.timeToExpiry * types_1.MILLISECONDS_PER_YEAR; // near term ms
+    const N2 = farResult.timeToExpiry * types_1.MILLISECONDS_PER_YEAR; // far term ms
+    const T1 = nearResult.timeToExpiry;
+    const T2 = farResult.timeToExpiry;
+    const sigma1sq = nearResult.annualizedVariance;
+    const sigma2sq = farResult.annualizedVariance;
+    // Target in milliseconds
+    const N365 = types_1.MILLISECONDS_PER_YEAR;
+    const effectiveTargetDays = targetDays ?? Math.round(farResult.timeToExpiry * 365);
+    const Ntarget = effectiveTargetDays * (types_1.MILLISECONDS_PER_YEAR / 365);
+    // Guard: if near and far are the same expiration, just return near
+    if (Math.abs(N2 - N1) < 1) {
+        return {
+            impliedVolatility: nearResult.impliedVolatility,
+            nearTerm: nearResult,
+            farTerm: farResult,
+            targetDays: effectiveTargetDays,
+            isInterpolated: false,
+        };
+    }
+    // CBOE interpolation in variance space
+    const weight1 = (N2 - Ntarget) / (N2 - N1);
+    const weight2 = (Ntarget - N1) / (N2 - N1);
+    const interpolatedVariance = (T1 * sigma1sq * weight1 + T2 * sigma2sq * weight2) * (N365 / Ntarget);
+    const clampedVariance = Math.max(0, interpolatedVariance);
+    const iv = Math.sqrt(clampedVariance);
+    return {
+        impliedVolatility: iv,
+        nearTerm: nearResult,
+        farTerm: farResult,
+        targetDays: effectiveTargetDays,
+        isInterpolated: true,
+    };
+}
+function emptyResult(spot) {
+    return {
+        impliedVolatility: 0,
+        annualizedVariance: 0,
+        forward: spot,
+        k0: spot,
+        timeToExpiry: 0,
+        expiration: 0,
+        numStrikes: 0,
+        putContribution: 0,
+        callContribution: 0,
+    };
+}

package/dist/iv/types.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Result of computing model-free implied variance for a single expiration
+ * using the CBOE variance swap methodology.
+ */
+export interface VarianceSwapResult {
+    /** Annualized implied volatility as decimal (e.g. 0.20 = 20%) */
+    impliedVolatility: number;
+    /** Annualized variance σ² */
+    annualizedVariance: number;
+    /** Forward price F derived from put-call parity at K₀ */
+    forward: number;
+    /** At-the-money strike K₀ (strike where |call - put| is minimized) */
+    k0: number;
+    /** Time to expiry in years */
+    timeToExpiry: number;
+    /** Expiration timestamp (ms) */
+    expiration: number;
+    /** Number of strikes that contributed to the variance sum */
+    numStrikes: number;
+    /** Total put-side contribution to variance */
+    putContribution: number;
+    /** Total call-side contribution to variance */
+    callContribution: number;
+}
+/**
+ * Result of computing implied volatility, either single-term or
+ * interpolated between two terms (CBOE VIX-style).
+ */
+export interface ImpliedVolatilityResult {
+    /** Final annualized implied volatility as decimal */
+    impliedVolatility: number;
+    /** Near-term (or only-term) variance swap result */
+    nearTerm: VarianceSwapResult;
+    /** Far-term variance swap result, if two terms provided */
+    farTerm: VarianceSwapResult | null;
+    /** Target days for interpolation (null if single-term) */
+    targetDays: number | null;
+    /** Whether the result is interpolated between two terms */
+    isInterpolated: boolean;
+}

package/dist/iv/types.js

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

package/dist/rv/index.d.ts

@@ -0,0 +1,26 @@
+import { PriceObservation, RealizedVolatilityResult } from './types';
+export type { PriceObservation, RealizedVolatilityResult } from './types';
+/**
+ * Compute annualized realized volatility from price observations.
+ *
+ * Uses the standard quadratic variation estimator:
+ *
+ *   QV = Σᵢ (ln(Pᵢ / Pᵢ₋₁))²
+ *
+ * Annualized as:
+ *
+ *   σ_realized = √(QV × (N_year / elapsed_time))
+ *
+ * This function is stateless and tick-based: pass all observed prices
+ * and it computes from the full set. No windowing, no sampling — the
+ * consumer decides what observations to include. As the session
+ * progresses and more ticks arrive, the estimate naturally converges.
+ *
+ * Observations are sorted by timestamp internally, so order does not
+ * matter. Duplicate timestamps are preserved (both contribute).
+ * Zero or negative prices are filtered out.
+ *
+ * @param observations - Array of { price, timestamp } observations
+ * @returns Realized volatility result with annualized RV
+ */
+export declare function computeRealizedVolatility(observations: PriceObservation[]): RealizedVolatilityResult;

package/dist/rv/index.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeRealizedVolatility = computeRealizedVolatility;
+const types_1 = require("../types");
+/**
+ * Compute annualized realized volatility from price observations.
+ *
+ * Uses the standard quadratic variation estimator:
+ *
+ *   QV = Σᵢ (ln(Pᵢ / Pᵢ₋₁))²
+ *
+ * Annualized as:
+ *
+ *   σ_realized = √(QV × (N_year / elapsed_time))
+ *
+ * This function is stateless and tick-based: pass all observed prices
+ * and it computes from the full set. No windowing, no sampling — the
+ * consumer decides what observations to include. As the session
+ * progresses and more ticks arrive, the estimate naturally converges.
+ *
+ * Observations are sorted by timestamp internally, so order does not
+ * matter. Duplicate timestamps are preserved (both contribute).
+ * Zero or negative prices are filtered out.
+ *
+ * @param observations - Array of { price, timestamp } observations
+ * @returns Realized volatility result with annualized RV
+ */
+function computeRealizedVolatility(observations) {
+    // Filter invalid observations and sort by timestamp
+    const valid = observations
+        .filter(o => o.price > 0 && isFinite(o.price) && isFinite(o.timestamp))
+        .sort((a, b) => a.timestamp - b.timestamp);
+    if (valid.length < 2) {
+        return emptyResult(valid);
+    }
+    // Compute sum of squared log returns
+    let quadraticVariation = 0;
+    let numReturns = 0;
+    for (let i = 1; i < valid.length; i++) {
+        const logReturn = Math.log(valid[i].price / valid[i - 1].price);
+        quadraticVariation += logReturn * logReturn;
+        numReturns++;
+    }
+    // Elapsed time
+    const firstTs = valid[0].timestamp;
+    const lastTs = valid[valid.length - 1].timestamp;
+    const elapsedMs = lastTs - firstTs;
+    const elapsedMinutes = elapsedMs / 60000;
+    const elapsedYears = elapsedMs / types_1.MILLISECONDS_PER_YEAR;
+    // Guard against zero elapsed time
+    if (elapsedYears <= 0) {
+        return emptyResult(valid);
+    }
+    // Annualize: σ² = QV × (year / elapsed)
+    const annualizedVariance = quadraticVariation / elapsedYears;
+    const realizedVolatility = Math.sqrt(annualizedVariance);
+    return {
+        realizedVolatility,
+        annualizedVariance,
+        quadraticVariation,
+        numObservations: valid.length,
+        numReturns,
+        elapsedMinutes,
+        elapsedYears,
+        firstObservation: firstTs,
+        lastObservation: lastTs,
+    };
+}
+function emptyResult(valid) {
+    return {
+        realizedVolatility: 0,
+        annualizedVariance: 0,
+        quadraticVariation: 0,
+        numObservations: valid.length,
+        numReturns: 0,
+        elapsedMinutes: 0,
+        elapsedYears: 0,
+        firstObservation: valid.length > 0 ? valid[0].timestamp : 0,
+        lastObservation: valid.length > 0 ? valid[valid.length - 1].timestamp : 0,
+    };
+}

package/dist/rv/types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A single price observation for realized volatility computation.
+ */
+export interface PriceObservation {
+    /** Price of the underlying (mid, last, or whatever the consumer provides) */
+    price: number;
+    /** Timestamp in milliseconds */
+    timestamp: number;
+}
+/**
+ * Result of computing realized volatility from price observations.
+ */
+export interface RealizedVolatilityResult {
+    /** Annualized realized volatility as decimal (e.g. 0.18 = 18%) */
+    realizedVolatility: number;
+    /** Annualized realized variance */
+    annualizedVariance: number;
+    /** Raw quadratic variation: Σ (ln(Pᵢ/Pᵢ₋₁))² */
+    quadraticVariation: number;
+    /** Number of price observations used */
+    numObservations: number;
+    /** Number of returns computed (observations - 1) */
+    numReturns: number;
+    /** Elapsed time in minutes from first to last observation */
+    elapsedMinutes: number;
+    /** Elapsed time in years (for annualization reference) */
+    elapsedYears: number;
+    /** Timestamp of first observation */
+    firstObservation: number;
+    /** Timestamp of last observation */
+    lastObservation: number;
+}

package/dist/rv/types.js

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