@insiderfinance/totalfinance 0.1.0

package/modules/volatility/src/metrics.ts

@@ -0,0 +1,176 @@
+/**
+ * Cross-sectional implied-volatility metrics (spec §10.2): IV rank and IV percentile against a
+ * trailing history of ATM (or any fixed-reference) implied volatilities.
+ */
+
+import {
+  CONVENTIONS_VERSION,
+  type Computed,
+  ErrorCode,
+  InputError,
+  type QuantWarning,
+  ensureFinite,
+  requireArgumentArray,
+  facade,
+  ensureKnownKeys,
+  WarningCode,
+} from '@totalfinance/core';
+import { max as arrMax, mean as arrMean, min as arrMin } from '@totalfinance/math';
+
+/** The conventions echoed by an empirical IV metric: the sample window and which statistic. */
+type ImpliedVolatilityMetricExtra = { window: number; method: 'rank' | 'percentile' | 'stats' };
+
+function requireHistory(history: ArrayLike<number>, functionName: string): void {
+  if (history.length === 0) {
+    throw new InputError(`${functionName}: history must be non-empty.`, {
+      code: ErrorCode.InputOutOfRange,
+      context: { length: 0 },
+    });
+  }
+  // A single NaN/∞ in the history poisons min/max/mean and yields a silently-wrong rank — reject it.
+  for (let i = 0; i < history.length; i++) {
+    if (!Number.isFinite(history[i]!)) {
+      throw new InputError(`${functionName}: history[${i}] must be finite, got ${history[i]}.`, {
+        code: ErrorCode.InputNotFinite,
+        context: { index: i, value: history[i] },
+      });
+    }
+  }
+}
+
+/**
+ * IV rank: where `current` sits in the trailing [min, max] range, as a percentage in `[0, 100]`.
+ * `(current − min) / (max − min) × 100`, clamped. Returns `NaN` only when the history is flat
+ * (min == max) — there is no defined rank, and we never fabricate one.
+ */
+/** Input for {@link impliedVolatilityRank}/{@link impliedVolatilityPercentile}/{@link impliedVolatilityStatistics}: current IV vs its history. */
+export interface ImpliedVolatilityMetricInput {
+  /** Current implied volatility (annualized decimal). */
+  current: number;
+  /** Trailing IV history (chronological or not — order-insensitive). */
+  history: ArrayLike<number>;
+}
+
+function impliedVolatilityRankExplain(
+  input: ImpliedVolatilityMetricInput,
+): Computed<number | null, ImpliedVolatilityMetricExtra> {
+  const { current, history } = input;
+  ensureKnownKeys('impliedVolatilityRank', 'input', input, ['current', 'history']);
+  requireArgumentArray('impliedVolatilityRank', 'history', history);
+  ensureFinite(current, 'current', 'impliedVolatilityRank');
+  requireHistory(history, 'impliedVolatilityRank');
+  const lo = arrMin(history);
+  const hi = arrMax(history);
+  const warnings: QuantWarning[] = [];
+  let value: number | null;
+  if (hi === lo) {
+    // Flat history ⇒ no defined rank ⇒ null-with-reason (Law 7: JSON-safe, never NaN).
+    value = null;
+    warnings.push({
+      code: WarningCode.ImpliedVolatilityFlatHistory,
+      message: `IV rank is undefined for a flat history (min == max == ${lo}); reported as null.`,
+      severity: 'warn',
+      context: { min: lo, max: hi },
+    });
+  } else {
+    value = Math.min(100, Math.max(0, ((current - lo) / (hi - lo)) * 100));
+  }
+  return {
+    value,
+    assumptions: {
+      conventionsVersion: CONVENTIONS_VERSION,
+      window: history.length,
+      method: 'rank',
+    },
+    diagnostics: { warnings },
+  };
+}
+
+/**
+ * IV percentile: the share of the trailing history strictly below `current`, in `[0, 100]`. Unlike
+ * IV rank this is robust to outliers (it counts observations, not the range).
+ */
+function impliedVolatilityPercentileExplain(
+  input: ImpliedVolatilityMetricInput,
+): Computed<number, ImpliedVolatilityMetricExtra> {
+  const { current, history } = input;
+  ensureKnownKeys('impliedVolatilityPercentile', 'input', input, ['current', 'history']);
+  requireArgumentArray('impliedVolatilityPercentile', 'history', history);
+  ensureFinite(current, 'current', 'impliedVolatilityPercentile');
+  requireHistory(history, 'impliedVolatilityPercentile');
+  let below = 0;
+  for (let i = 0; i < history.length; i++) if (history[i]! < current) below++;
+  return {
+    value: (below / history.length) * 100,
+    assumptions: {
+      conventionsVersion: CONVENTIONS_VERSION,
+      window: history.length,
+      method: 'percentile',
+    },
+    diagnostics: { warnings: [] },
+  };
+}
+
+export interface ImpliedVolatilityStatistics {
+  current: number;
+  /** `null` for a flat history (rank undefined — disclosed via `implied_volatility.flat_history`). */
+  rank: number | null;
+  percentile: number;
+  min: number;
+  max: number;
+  mean: number;
+  observations: number;
+}
+
+/** Combined IV rank/percentile plus the trailing min/max/mean used to compute them. */
+function impliedVolatilityStatsExplain(
+  input: ImpliedVolatilityMetricInput,
+): Computed<ImpliedVolatilityStatistics, ImpliedVolatilityMetricExtra> {
+  const { current, history } = input;
+  ensureKnownKeys('impliedVolatilityStatistics', 'input', input, ['current', 'history']);
+  requireArgumentArray('impliedVolatilityStatistics', 'history', history);
+  ensureFinite(current, 'current', 'impliedVolatilityStatistics');
+  requireHistory(history, 'impliedVolatilityStatistics');
+  const rank = impliedVolatilityRankExplain(input);
+  const percentile = impliedVolatilityPercentileExplain(input);
+  return {
+    value: {
+      current,
+      rank: rank.value,
+      percentile: percentile.value,
+      min: arrMin(history),
+      max: arrMax(history),
+      mean: arrMean(history),
+      observations: history.length,
+    },
+    assumptions: {
+      conventionsVersion: CONVENTIONS_VERSION,
+      window: history.length,
+      method: 'stats',
+    },
+    // propagate the flat-history caveat from the inner rank, if any.
+    diagnostics: { warnings: rank.diagnostics.warnings },
+  };
+}
+
+/**
+ * FACADES (P3.2, one gesture): plain value from the call; the same call's `.explain()` returns the
+ * envelope (window, method, and the flat-history caveat when rank is undefined). Single-object
+ * input per Decision 3 — `impliedVolatilityRank({ current, history })`.
+ */
+export const impliedVolatilityRank = facade(
+  'impliedVolatilityRank',
+  (input: ImpliedVolatilityMetricInput): number | null => impliedVolatilityRankExplain(input).value,
+  impliedVolatilityRankExplain,
+);
+export const impliedVolatilityPercentile = facade(
+  'impliedVolatilityPercentile',
+  (input: ImpliedVolatilityMetricInput): number => impliedVolatilityPercentileExplain(input).value,
+  impliedVolatilityPercentileExplain,
+);
+export const impliedVolatilityStatistics = facade(
+  'impliedVolatilityStatistics',
+  (input: ImpliedVolatilityMetricInput): ImpliedVolatilityStatistics =>
+    impliedVolatilityStatsExplain(input).value,
+  impliedVolatilityStatsExplain,
+);

package/modules/volatility/src/min-variance-delta.ts

@@ -0,0 +1,167 @@
+/**
+ * Minimum-variance (smile-adjusted) delta (spec §10.x, roadmap Tier 2). The hedge ratio that accounts
+ * for the systematic co-movement of implied vol with spot:
+ *
+ *   Δ_MV = ∂V/∂S + ∂V/∂σ · (∂σ/∂S) = Δ_BS + Vega · β,   β ≡ ∂σ/∂S
+ *
+ * `β` is the vol–spot sensitivity in decimal vol per $1 of spot. The **honest** β is empirical — the
+ * regression of realized IV changes on spot changes (the leverage effect; negative for equities) — and
+ * is the primary input. Deriving β from the current smile needs a **regime** (sticky-strike ⇒ 0;
+ * sticky-moneyness ⇒ −skewSlope/spot), offered as a labeled convenience. See
+ * `docs/specs/min-variance-delta.md`.
+ */
+
+import {
+  type ClosedRequestSpecification,
+  CONVENTIONS_VERSION,
+  type Computed,
+  ErrorCode,
+  InputError,
+  type OptionType,
+  ensurePositive,
+  validateClosedRequest,
+} from '@totalfinance/core';
+import { blackScholesGreeks } from '@totalfinance/options/black-scholes';
+import { VALIDATION_SPECS } from './generated/validation-specs.js';
+
+/**
+ * Generated closed-request spec (spec 3B.1b): the allowlist projected from the declaration.
+ * Resolved at module load so a stale key fails at import.
+ */
+function minVarianceDeltaSpecOf(key: string): ClosedRequestSpecification {
+  const spec = VALIDATION_SPECS[key];
+  if (spec === undefined) {
+    throw new Error(
+      `min-variance-delta: no generated validation spec for '${key}' — run \`pnpm validation:update\``,
+    );
+  }
+  return spec;
+}
+
+const MINIMUM_VARIANCE_DELTA_SPEC = minVarianceDeltaSpecOf('minimumVarianceDelta#0');
+
+const MINIMUM_VARIANCE_DELTA_EXAMPLE = (): string =>
+  "minimumVarianceDelta({ type: 'call', spot: 100, strike: 105, timeToExpiryYears: 0.25, " +
+  'riskFreeRate: 0.04, volatility: 0.2, volatilitySpotBeta: -0.001 })';
+
+/** Inputs for {@link minimumVarianceDelta}. Provide exactly one of `volatilitySpotBeta` or `skewSlope`. */
+export interface MinimumVarianceDeltaOptions {
+  type: OptionType;
+  spot: number;
+  strike: number;
+  /** Time to expiry in years. */
+  timeToExpiryYears: number;
+  riskFreeRate: number;
+  /** The option's implied vol (decimal). */
+  volatility: number;
+  /** Continuous dividend yield (decimal, default 0). */
+  dividendYield?: number;
+  /**
+   * ∂σ/∂S directly (decimal vol **per $1 of spot**) — the empirical / minimum-variance β (preferred).
+   * Take it from `estimateVolatilitySpotBeta(...).value.volatilitySpotBeta`, which is already in
+   * these units. `stickyRegime`'s `volatilitySpotBetaPerLogSpot` is ∂σ/∂lnS — `S ×` larger — so
+   * divide it by spot before passing it here, or the smile adjustment is scaled by the spot price.
+   */
+  volatilitySpotBeta?: number;
+  /** ∂σ/∂ln(K) (`SkewMetrics.skewSlope`) — mapped to β via `regime`. */
+  skewSlope?: number;
+  /** How `skewSlope` maps to β. Default `'sticky-moneyness'`. */
+  regime?: 'sticky-strike' | 'sticky-moneyness';
+}
+
+/** The minimum-variance delta read-out. */
+export interface MinimumVarianceDeltaResult {
+  /** `Δ_BS + Vega_raw · β` — the hedge ratio. */
+  minimumVarianceDelta: number;
+  /** The Black-Scholes spot delta `∂V/∂S`. */
+  blackScholesDelta: number;
+  /** Display vega (per 1% vol) at the option. */
+  vega: number;
+  /** The `β = ∂σ/∂S` actually used (decimal vol **per $1 of spot**, never per log-spot). */
+  volatilitySpotBeta: number;
+  /** `minimumVarianceDelta − blackScholesDelta` — the smile adjustment. */
+  skewAdjustment: number;
+}
+
+const FN = 'minimumVarianceDelta';
+
+/**
+ * The minimum-variance (smile-adjusted) delta for one option. Composes `blackScholesGreeks` (for `Δ_BS` and
+ * vega) with a vol–spot sensitivity `β`. See the spec — β should be empirical (leverage) for a true
+ * minimum-variance hedge; the skew-derived regimes are smile models, not the leverage effect.
+ */
+export function minimumVarianceDelta(
+  options: MinimumVarianceDeltaOptions,
+): Computed<
+  MinimumVarianceDeltaResult,
+  { measure: 'real-world-hedge'; betaSource: string; regime?: string }
+> {
+  validateClosedRequest(FN, options, MINIMUM_VARIANCE_DELTA_SPEC, {
+    argumentName: 'options',
+    exampleCall: MINIMUM_VARIANCE_DELTA_EXAMPLE,
+  });
+  ensurePositive(options.spot, 'spot', FN);
+  ensurePositive(options.strike, 'strike', FN);
+  ensurePositive(options.timeToExpiryYears, 'timeToExpiryYears', FN);
+  ensurePositive(options.volatility, 'volatility', FN);
+  const q = options.dividendYield ?? 0;
+
+  // Resolve β = ∂σ/∂S. A supplied β wins; else derive it from the skew slope under a regime; a missing
+  // β is an error, not a silent 0 (which would masquerade the BSM delta as "minimum-variance").
+  let beta: number;
+  let betaSource: string;
+  let regime: string | undefined;
+  if (options.volatilitySpotBeta !== undefined) {
+    beta = options.volatilitySpotBeta;
+    betaSource = 'supplied';
+  } else if (options.skewSlope !== undefined) {
+    regime = options.regime ?? 'sticky-moneyness';
+    if (regime === 'sticky-strike') {
+      beta = 0;
+      betaSource = 'skew-sticky-strike';
+    } else if (regime === 'sticky-moneyness') {
+      beta = -options.skewSlope / options.spot;
+      betaSource = 'skew-sticky-moneyness';
+    } else {
+      throw new InputError(
+        `${FN}: regime must be 'sticky-strike' | 'sticky-moneyness', got "${regime}".`,
+        { code: ErrorCode.InputInvalidEnum, context: { regime } },
+      );
+    }
+  } else {
+    throw new InputError(
+      `${FN}: a vol–spot sensitivity is required — pass volatilitySpotBeta (∂σ/∂S) or skewSlope (+ regime). A minimum-variance delta with no β is just the BSM delta.`,
+      { code: ErrorCode.InputMissingField, context: { field: 'volatilitySpotBeta|skewSlope' } },
+    );
+  }
+
+  const greeks = blackScholesGreeks({
+    type: options.type,
+    spot: options.spot,
+    strike: options.strike,
+    timeToExpiryYears: options.timeToExpiryYears,
+    riskFreeRate: options.riskFreeRate,
+    dividendYield: q,
+    volatility: options.volatility,
+  });
+  const vegaRaw = greeks.vega * 100; // display (per 1%) → raw (per 1.00 vol), so vegaRaw·β is a delta
+  const skewAdjustment = vegaRaw * beta;
+
+  return {
+    value: {
+      minimumVarianceDelta: greeks.delta + skewAdjustment,
+      blackScholesDelta: greeks.delta,
+      vega: greeks.vega,
+      volatilitySpotBeta: beta,
+      skewAdjustment,
+    },
+    assumptions: {
+      conventionsVersion: CONVENTIONS_VERSION,
+      timeToExpiryYears: options.timeToExpiryYears,
+      measure: 'real-world-hedge',
+      betaSource,
+      ...(regime !== undefined ? { regime } : {}),
+    },
+    diagnostics: { warnings: [] },
+  };
+}