@insiderfinance/totalfinance 0.1.0

package/modules/volatility/src/variance-index.ts

@@ -0,0 +1,396 @@
+/**
+ * VIX-style model-free variance index + VRP term structure (spec §10, roadmap Tier 2). The
+ * trader-facing layer over the single-expiry DDKZ replication (`varianceSwapRate`): from a raw option
+ * **chain** it extracts each expiry's forward (put–call parity), selects the OTM strip, computes the
+ * per-expiry model-free fair variance, and **time-interpolates** two expiries to a constant maturity —
+ * the actual CBOE VIX construction — plus the variance-risk-premium term structure vs a realized vol.
+ *
+ * Composes `varianceSwapRate` (analytics.ts) and `varianceRiskPremium` / `realizedImpliedSpread`
+ * (event.ts). No fabricated points: an expiry that can't be replicated is dropped with a disclosed
+ * warning; an un-bracketed horizonPeriods is extrapolated from the nearest expiry, disclosed. See
+ * `docs/specs/variance-index.md`.
+ */
+
+import {
+  type ClosedRequestSpecification,
+  CONVENTIONS_VERSION,
+  type Diagnostics,
+  type EpochMs,
+  ErrorCode,
+  InputError,
+  type OptionQuote,
+  type QuantWarning,
+  WarningCode,
+  ensureNonNegative,
+  ensurePositive,
+  validateClosedRequest,
+  warning,
+} from '@totalfinance/core';
+import { varianceSwapRate } from './analytics.js';
+import { realizedImpliedSpread, varianceRiskPremium } from './event.js';
+import { extractOtmStrips } from './otm-strip.js';
+import { VALIDATION_SPECS } from './generated/validation-specs.js';
+
+/**
+ * Generated closed-request specs (spec 3B.1b): allowlists projected from the declarations.
+ * Resolved at module load so a stale key fails at import.
+ */
+function varianceIndexSpecOf(key: string): ClosedRequestSpecification {
+  const spec = VALIDATION_SPECS[key];
+  if (spec === undefined) {
+    throw new Error(
+      `variance-index: no generated validation spec for '${key}' — run \`pnpm validation:update\``,
+    );
+  }
+  return spec;
+}
+
+const VARIANCE_INDEX_SPEC = varianceIndexSpecOf('varianceIndex#0');
+const VRP_TERM_STRUCTURE_SPEC = varianceIndexSpecOf('varianceRiskPremiumTermStructure#0');
+
+const VARIANCE_INDEX_EXAMPLE = (): string =>
+  "varianceIndex({ quotes, spot: 100, riskFreeRate: 0.04, asOf: '2026-05-15T16:00:00Z' })";
+const VRP_TERM_STRUCTURE_EXAMPLE = (): string =>
+  'varianceRiskPremiumTermStructure({ quotes, spot: 100, riskFreeRate: 0.04, ' +
+  "asOf: '2026-05-15T16:00:00Z', realizedVolatility: 0.18 })";
+
+/** Inputs for {@link varianceIndex}. */
+export interface VarianceIndexOptions {
+  /** Option chain across ≥ 1 expiries — call + put quotes with a usable mid. */
+  quotes: readonly OptionQuote[];
+  spot: number;
+  riskFreeRate: number;
+  asOf: EpochMs | string;
+  /** Constant-maturity target in calendar days. Default 30 (VIX). */
+  horizonDays?: number;
+  /** Reserved for the forward; default 0 (the parity forward already carries dividend/borrow). */
+  dividendYield?: number;
+}
+
+/** One expiry's model-free fair variance/vol. */
+export interface ExpiryVariance {
+  expiry: string;
+  /** Calendar days to expiry. */
+  daysToExpiry: number;
+  /** Year fraction (ACT/365F). */
+  timeToExpiryYears: number;
+  /** Parity forward. */
+  forward: number;
+  /** Annualized fair variance (decimal). */
+  variance: number;
+  /** `√variance` — model-free implied vol (decimal, e.g. 0.20). */
+  fairVolatility: number;
+  /** OTM strikes used in the replication. */
+  strikesUsed: number;
+}
+
+/** The variance-index read-out. */
+export interface VarianceIndexResult {
+  /** Constant-maturity model-free vol in VIX-style points (e.g. 20.0 = 20% annualized). */
+  index: number;
+  /** Constant-maturity annualized fair variance (decimal). */
+  variance: number;
+  /** Constant-maturity fair vol as a decimal (`index / 100`). */
+  fairVolatility: number;
+  horizonDays: number;
+  /** Per-expiry fair variance/vol — the whole term structure, ascending by DTE. */
+  termStructure: ExpiryVariance[];
+  /** The two expiries that bracketed the horizonPeriods (absent when extrapolated from one). */
+  interpolatedBetween?: { near: string; far: string };
+  assumptions: {
+    conventionsVersion: string;
+    horizonDays: number;
+    measure: 'risk-neutral';
+    method: string;
+  };
+  diagnostics: Diagnostics;
+}
+
+/** Inputs for {@link varianceRiskPremiumTermStructure}. */
+export interface VarianceRiskPremiumTermStructureOptions extends VarianceIndexOptions {
+  /** Realized vol to compare (decimal): one number for the whole curve, or per-expiry by ISO date. */
+  realizedVolatility: number | Record<string, number>;
+}
+
+/** One expiry's variance-risk-premium point. */
+export interface VarianceRiskPremiumPoint extends ExpiryVariance {
+  realizedVolatility: number;
+  /** `iv² − rv²` (annualized) — the variance risk premium. */
+  varianceRiskPremium: number;
+  /** `iv − rv` — the vol-point spread. */
+  volatilitySpread: number;
+}
+
+/** The VRP term-structure read-out. */
+export interface VarianceRiskPremiumTermStructureResult {
+  points: VarianceRiskPremiumPoint[];
+  /** VRP at the constant-maturity index vs the reference realized vol. */
+  indexVarianceRiskPremium: number;
+  assumptions: { conventionsVersion: string; measure: 'risk-neutral'; method: string };
+  diagnostics: Diagnostics;
+}
+
+/**
+ * Build the per-expiry fair-variance term structure (ascending by DTE) from a chain, disclosing every
+ * dropped expiry. Shares the OTM-strip extraction with the tail-risk index (`extractOtmStrips`); the
+ * DDKZ replication (`varianceSwapRate`) is applied per strip here.
+ */
+function termStructureOf(
+  options: VarianceIndexOptions,
+  functionName: string,
+): { term: ExpiryVariance[]; warnings: QuantWarning[]; asOfMs: EpochMs } {
+  // Shape/type/closedness ran at the public heads (spec 3B.1b); the domain residue is spot > 0.
+  ensurePositive(options.spot, 'spot', functionName);
+
+  const { strips, warnings, asOfMs } = extractOtmStrips(
+    options.quotes,
+    { rate: options.riskFreeRate, asOf: options.asOf },
+    functionName,
+  );
+  const term: ExpiryVariance[] = [];
+  for (const s of strips) {
+    let variance: number;
+    let fairVolatility: number;
+    try {
+      const vs = varianceSwapRate({
+        strikes: s.strikes,
+        otmPrices: s.otmPrices,
+        forward: s.forward,
+        riskFreeRate: options.riskFreeRate,
+        timeToExpiryYears: s.timeToExpiryYears,
+        // `extractOtmStrips` already averages the K₀ call and put (the CBOE convention), so the
+        // put-only bias disclosure does not apply to this path — say so instead of carrying a
+        // warning that is false here.
+        boundaryPriceAveraged: true,
+      });
+      variance = vs.value.variance;
+      fairVolatility = vs.value.fairVolatility;
+    } catch (err) {
+      if (err instanceof InputError) {
+        warnings.push(
+          warning(
+            WarningCode.ModelLimitation,
+            `expiry ${s.expiry} dropped: ${err.message}.`,
+            'info',
+            {
+              expiry: s.expiry,
+            },
+          ),
+        );
+        continue;
+      }
+      throw err;
+    }
+    if (!(variance >= 0) || !Number.isFinite(fairVolatility)) {
+      warnings.push(
+        warning(
+          WarningCode.ModelLimitation,
+          `expiry ${s.expiry} dropped: negative/undefined fair variance (${variance}) — arbitrageable or too-sparse strip.`,
+          'info',
+          { expiry: s.expiry },
+        ),
+      );
+      continue;
+    }
+    term.push({
+      expiry: s.expiry,
+      daysToExpiry: s.daysToExpiry,
+      timeToExpiryYears: s.timeToExpiryYears,
+      forward: s.forward,
+      variance,
+      fairVolatility,
+      strikesUsed: s.strikes.length,
+    });
+  }
+  if (term.length === 0) {
+    throw new InputError(
+      `${functionName}: no expiry could be replicated from the chain (need ≥ 3 OTM strikes with a bracketing forward per expiry). See diagnostics for per-expiry reasons.`,
+      { code: ErrorCode.InputOutOfRange, context: { quotes: options.quotes.length } },
+    );
+  }
+  return { term, warnings, asOfMs };
+}
+
+/** Time-interpolate two expiries' variance to the constant maturity, or extrapolate from the nearest. */
+function constantMaturityVariance(
+  term: ExpiryVariance[],
+  horizonDays: number,
+): { variance: number; near?: string; far?: string; extrapolated: boolean } {
+  // Bracket: the last expiry with dte ≤ horizonPeriods and the first with dte ≥ horizonPeriods.
+  let nearIdx = -1;
+  for (let i = 0; i < term.length; i++) if (term[i]!.daysToExpiry <= horizonDays) nearIdx = i;
+  const near = nearIdx >= 0 ? term[nearIdx] : undefined;
+  const far = nearIdx + 1 < term.length ? term[nearIdx + 1] : undefined;
+  if (
+    near &&
+    far &&
+    far.daysToExpiry > near.daysToExpiry &&
+    near.daysToExpiry <= horizonDays &&
+    far.daysToExpiry >= horizonDays
+  ) {
+    const n1 = near.daysToExpiry;
+    const n2 = far.daysToExpiry;
+    const w1 = (n2 - horizonDays) / (n2 - n1);
+    const w2 = (horizonDays - n1) / (n2 - n1);
+    // CBOE: interpolate total variance (T·σ²) then annualize to the horizonPeriods (×365/N). Use the SAME
+    // calendar-day time base (dte/365) as the weights and the horizonPeriods — mixing the 16:00-ET `t` here
+    // with dte-based weights biases the constant-maturity variance by ~(1 + δ/N).
+    const variance =
+      ((n1 / 365) * near.variance * w1 + (n2 / 365) * far.variance * w2) * (365 / horizonDays);
+    return { variance, near: near.expiry, far: far.expiry, extrapolated: false };
+  }
+  // Un-bracketed → nearest expiry's fair variance (disclosed as extrapolated).
+  const nearest = term.reduce((a, b) =>
+    Math.abs(b.daysToExpiry - horizonDays) < Math.abs(a.daysToExpiry - horizonDays) ? b : a,
+  );
+  return { variance: nearest.variance, extrapolated: true };
+}
+
+/**
+ * The VIX-style constant-maturity, model-free implied vol from an option chain, with the per-expiry
+ * fair-variance term structure. See `docs/specs/variance-index.md`.
+ */
+export function varianceIndex(options: VarianceIndexOptions): VarianceIndexResult {
+  const functionName = 'varianceIndex';
+  // Guard before any field access (first-touch law).
+  validateClosedRequest(functionName, options, VARIANCE_INDEX_SPEC, {
+    argumentName: 'options',
+    exampleCall: VARIANCE_INDEX_EXAMPLE,
+  });
+  return varianceIndexOf(options, functionName);
+}
+
+/** The validated index construction, shared with {@link varianceRiskPremiumTermStructure} (whose options superset it). */
+function varianceIndexOf(options: VarianceIndexOptions, functionName: string): VarianceIndexResult {
+  const horizonDays = options.horizonDays ?? 30;
+  if (!(horizonDays > 0) || !Number.isFinite(horizonDays)) {
+    throw new InputError(
+      `${functionName}: horizonDays must be a positive finite number; got ${horizonDays}.`,
+      {
+        code: ErrorCode.InputOutOfRange,
+        context: { horizonDays },
+      },
+    );
+  }
+  const { term, warnings } = termStructureOf(options, functionName);
+  const cm = constantMaturityVariance(term, horizonDays);
+  if (cm.extrapolated) {
+    warnings.push(
+      warning(
+        WarningCode.ModelLimitation,
+        `horizonPeriods ${horizonDays}d is not bracketed by two listed expiries; the index is extrapolated from the nearest expiry (${term.length} usable).`,
+        'warn',
+        { horizonDays },
+      ),
+    );
+  }
+  const variance = cm.variance;
+  const fairVolatility = Math.sqrt(Math.max(0, variance));
+  return {
+    index: 100 * fairVolatility,
+    variance,
+    fairVolatility,
+    horizonDays,
+    termStructure: term,
+    ...(cm.near !== undefined && cm.far !== undefined
+      ? { interpolatedBetween: { near: cm.near, far: cm.far } }
+      : {}),
+    assumptions: {
+      conventionsVersion: CONVENTIONS_VERSION,
+      horizonDays,
+      measure: 'risk-neutral',
+      method: 'ddkz-replication + vix-interpolation',
+    },
+    diagnostics: { engine: 'variance-index', method: 'vix-style', converged: true, warnings },
+  };
+}
+
+/** Resolve the realized vol for one expiry (a scalar applies to all; a record is looked up by date). */
+function realizedFor(
+  expiry: string,
+  realizedVolatility: number | Record<string, number>,
+  functionName: string,
+): number {
+  if (typeof realizedVolatility === 'number') {
+    ensureNonNegative(realizedVolatility, 'realizedVolatility', functionName);
+    return realizedVolatility;
+  }
+  const rv = realizedVolatility[expiry];
+  if (rv === undefined) {
+    throw new InputError(`${functionName}: realizedVolatility has no entry for expiry ${expiry}.`, {
+      code: ErrorCode.InputMissingField,
+      context: { expiry },
+    });
+  }
+  ensureNonNegative(rv, `realizedVolatility["${expiry}"]`, functionName);
+  return rv;
+}
+
+/**
+ * The variance-risk-premium term structure — per-expiry implied variance (from {@link varianceIndex})
+ * minus realized variance — plus the VRP at the constant-maturity index. See the spec.
+ */
+export function varianceRiskPremiumTermStructure(
+  options: VarianceRiskPremiumTermStructureOptions,
+): VarianceRiskPremiumTermStructureResult {
+  const functionName = 'varianceRiskPremiumTermStructure';
+  validateClosedRequest(functionName, options, VRP_TERM_STRUCTURE_SPEC, {
+    argumentName: 'options',
+    exampleCall: VRP_TERM_STRUCTURE_EXAMPLE,
+  });
+  // `realizedVolatility` is a mixed number-or-record union the spec leaves UNCHECKED — the curated
+  // type teaching stays here.
+  if (
+    options.realizedVolatility === null ||
+    (typeof options.realizedVolatility !== 'number' &&
+      typeof options.realizedVolatility !== 'object')
+  ) {
+    throw new InputError(
+      `${functionName}: realizedVolatility must be a number or a per-expiry record.`,
+      {
+        code: ErrorCode.InputWrongType,
+        context: { realizedVolatility: typeof options.realizedVolatility },
+      },
+    );
+  }
+  const idx = varianceIndexOf(options, functionName);
+  const points: VarianceRiskPremiumPoint[] = idx.termStructure.map((e) => {
+    const rv = realizedFor(e.expiry, options.realizedVolatility, functionName);
+    return {
+      ...e,
+      realizedVolatility: rv,
+      varianceRiskPremium: varianceRiskPremium({
+        impliedVolatility: e.fairVolatility,
+        realizedVolatility: rv,
+      }),
+      volatilitySpread: realizedImpliedSpread({
+        impliedVolatility: e.fairVolatility,
+        realizedVolatility: rv,
+      }),
+    };
+  });
+  // Reference realized for the constant-maturity index: the scalar, else the nearest-expiry realized.
+  const horizonDays = options.horizonDays ?? 30;
+  const refExpiry = idx.termStructure.reduce((a, b) =>
+    Math.abs(b.daysToExpiry - horizonDays) < Math.abs(a.daysToExpiry - horizonDays) ? b : a,
+  ).expiry;
+  const refRealized = realizedFor(refExpiry, options.realizedVolatility, functionName);
+  return {
+    points,
+    indexVarianceRiskPremium: varianceRiskPremium({
+      impliedVolatility: idx.fairVolatility,
+      realizedVolatility: refRealized,
+    }),
+    assumptions: {
+      conventionsVersion: CONVENTIONS_VERSION,
+      measure: 'risk-neutral',
+      method: 'ddkz-replication + vix-interpolation',
+    },
+    diagnostics: {
+      engine: 'variance-risk-premium-term-structure',
+      method: 'vix-style',
+      converged: true,
+      warnings: idx.diagnostics.warnings,
+    },
+  };
+}

package/modules/volatility/src/volatility-spot-beta.ts

@@ -0,0 +1,252 @@
+/**
+ * Empirical vol–spot β — the leverage effect (roadmap Tier 2 — the `minimumVarianceDelta` follow-up).
+ *
+ * `minimumVarianceDelta` needs `β = ∂σ/∂S`, and its spec is explicit that the honest β is **empirical**: the
+ * regression slope of realized IV changes on spot changes (negative for equities — the leverage effect). This
+ * estimates it from a `(spot, impliedVolatility)` history via OLS (with optional Newey–West HAC standard errors) so
+ * the `volatilitySpotBeta` output feeds straight into `minimumVarianceDelta({ volatilitySpotBeta })`.
+ * See `docs/specs/volatility-spot-beta.md`.
+ */
+
+import {
+  type Assumptions,
+  CONVENTIONS_VERSION,
+  type Computed,
+  ErrorCode,
+  InputError,
+  type QuantWarning,
+  WarningCode,
+  ensureEnum,
+  ensureKnownKeys,
+  ensurePositive,
+  requireArgumentArray,
+  requireArgumentObject,
+  warning,
+  type ClosedRequestSpecification,
+  validateClosedRequest,
+} from '@totalfinance/core';
+import { VALIDATION_SPECS } from './generated/validation-specs.js';
+import { ols } from '@totalfinance/math';
+
+/** Input for {@link estimateVolatilitySpotBeta}. */
+export interface VolatilitySpotBetaInput {
+  /** Chronological spot prices. */
+  spot: number[];
+  /** The option's implied vol (decimal), aligned to `spot`. */
+  impliedVolatility: number[];
+  /** Regress IV changes on log-returns (`'log'`, default) or dollar spot changes (`'level'`). */
+  basis?: 'log' | 'level';
+  /** Reference spot to convert a log-basis slope to `∂σ/∂S` (default: the latest spot). */
+  referenceSpot?: number;
+  /** Newey–West HAC bandwidth for autocorrelation-robust errors (default 0 = White). */
+  hacLags?: number;
+}
+
+/** The empirical vol–spot β and its regression diagnostics. */
+export interface VolatilitySpotBeta {
+  /**
+   * `β = ∂σ/∂S` in decimal vol **per $1 of spot** — feed straight to
+   * `minimumVarianceDelta({ volatilitySpotBeta })`, which expects the same per-dollar units.
+   *
+   * Units matter here: `stickyRegime` reports `volatilitySpotBetaPerLogSpot` = `∂σ/∂lnS` (per 100%
+   * spot move), which is `S ×` this number. On a `'log'` basis the conversion is done for you
+   * (`slope / referenceSpot`); {@link slope} is the raw regression coefficient in its own basis.
+   */
+  volatilitySpotBeta: number;
+  /** The regression slope: `∂σ/∂ln S` (`'log'`) or `∂σ/∂S` (`'level'`). */
+  slope: number;
+  /** Standard error of the slope. */
+  slopeStandardError: number;
+  /** t-statistic of the slope. */
+  slopeTStatistic: number;
+  /** Correlation of the IV change with the spot-change regressor (leverage ⇒ negative). */
+  correlation: number;
+  /** Coefficient of determination `R²`. */
+  rSquared: number;
+  /** Change observations used (after dropping bad pairs). */
+  observationCount: number;
+  /** Dropped (non-finite / non-positive) change observations. */
+  dropped: number;
+  /** Reference spot used for the `∂σ/∂S` conversion. */
+  referenceSpot: number;
+}
+
+const FN = 'estimateVolatilitySpotBeta';
+
+/**
+ * Hard cap on Newey-West lags (2026-08-23 review, P0): ols()'s HAC outer loop runs `lags`
+ * iterations regardless of the sample size, so an astronomical "integer" was a non-terminating
+ * regression. The Newey-West bandwidth rule 4·(n/100)^(2/9) stays below 30 for any market-sized
+ * sample; 1,000 is ~30× beyond that while keeping the O(lags × n) sum well under a second.
+ */
+const MAX_HAC_LAGS = 1_000;
+
+/**
+ * Estimate the empirical vol–spot sensitivity `β = ∂σ/∂S` (the leverage effect) from a `(spot, impliedVolatility)`
+ * history by OLS of one-step IV changes on spot changes. The `volatilitySpotBeta` output is the minimum-variance
+ * hedge input for {@link minimumVarianceDelta}; the slope's standard error / t-stat / R² and a
+ * significance warning are reported so a β that is really noise does not masquerade as a hedge input.
+ * See `docs/specs/volatility-spot-beta.md`.
+ */
+const SPOT_BETA_SPEC: ClosedRequestSpecification = (() => {
+  const spec = VALIDATION_SPECS['estimateVolatilitySpotBeta#0'];
+  if (spec === undefined)
+    throw new Error('volatility-spot-beta: missing generated spec — run `pnpm validation:update`');
+  return spec;
+})();
+
+export function estimateVolatilitySpotBeta(
+  input: VolatilitySpotBetaInput,
+): Computed<
+  VolatilitySpotBeta,
+  { measure: 'real-world-hedge'; basis: 'log' | 'level'; hacLags: number }
+> {
+  validateClosedRequest('estimateVolatilitySpotBeta', input, SPOT_BETA_SPEC, {
+    exampleCall: 'estimateVolatilitySpotBeta({ volatilityChanges, spotReturns })',
+  });
+  requireArgumentObject(FN, 'input', input);
+  ensureKnownKeys(FN, 'input', input, [
+    'spot',
+    'impliedVolatility',
+    'basis',
+    'referenceSpot',
+    'hacLags',
+  ]);
+  requireArgumentArray(FN, 'spot', (input as { spot?: unknown }).spot);
+  requireArgumentArray(
+    FN,
+    'impliedVolatility',
+    (input as { impliedVolatility?: unknown }).impliedVolatility,
+  );
+  const { spot, impliedVolatility } = input;
+  if (spot.length !== impliedVolatility.length) {
+    throw new InputError(
+      `${FN}: spot and impliedVolatility must be the same length (got ${spot.length} and ${impliedVolatility.length}).`,
+      {
+        code: ErrorCode.InputOutOfRange,
+        context: { spot: spot.length, impliedVolatility: impliedVolatility.length },
+      },
+    );
+  }
+  const basis = input.basis ?? 'log';
+  ensureEnum(basis, ['log', 'level'] as const, 'basis', FN);
+  const hacLags = input.hacLags ?? 0;
+  // Safe integer AND a work cap (2026-08-23 review, P0): hacLags is forwarded to ols(), whose
+  // Newey-West outer loop spins `lags` times REGARDLESS of the sample size (lags beyond n just add
+  // empty passes) — so `Number.isInteger(1e15)` passing made this call take hours and 2^53 made it
+  // non-terminating. The Newey-West bandwidth rule 4·(n/100)^(2/9) stays below 30 even at n = 10^9
+  // observations, so 1,000 lags is ~30× beyond any defensible bandwidth while keeping the O(lags × n)
+  // covariance sum well under a second on realistic samples.
+  if (!Number.isSafeInteger(hacLags) || hacLags < 0 || hacLags > MAX_HAC_LAGS) {
+    throw new InputError(
+      `${FN}: hacLags must be an integer in [0, ${MAX_HAC_LAGS.toLocaleString('en-US')}] — each lag adds a full pass over the regression sample, and the Newey-West bandwidth rule 4·(n/100)^(2/9) never comes close to ${MAX_HAC_LAGS.toLocaleString('en-US')}; got ${String(hacLags)}.`,
+      {
+        code: ErrorCode.InputOutOfRange,
+        context: { hacLags, max: MAX_HAC_LAGS },
+      },
+    );
+  }
+
+  // One-step change pairs (Δσ, regressor). Drop any pair with a non-finite change or non-positive spot.
+  const y: number[] = [];
+  const x: number[] = [];
+  let dropped = 0;
+  for (let t = 1; t < spot.length; t++) {
+    const s0 = spot[t - 1]!;
+    const s1 = spot[t]!;
+    const dSig = impliedVolatility[t]! - impliedVolatility[t - 1]!;
+    const reg = basis === 'log' ? Math.log(s1 / s0) : s1 - s0;
+    if (!(s0 > 0) || !(s1 > 0) || !Number.isFinite(dSig) || !Number.isFinite(reg)) {
+      dropped++;
+      continue;
+    }
+    y.push(dSig);
+    x.push(reg);
+  }
+  const n = y.length;
+  if (n < 3) {
+    throw new InputError(
+      `${FN}: need ≥ 3 usable one-step changes for a slope + intercept regression; got ${n} (from ${spot.length} observation(s), ${dropped} dropped).`,
+      {
+        code: ErrorCode.InputOutOfRange,
+        context: { usableChanges: n, dropped, observations: spot.length },
+      },
+    );
+  }
+
+  const reg = ols(
+    y,
+    x.map((xi) => [xi]),
+    hacLags > 0 ? { hac: { lags: hacLags } } : {},
+  );
+  const slope = reg.coefficients[1]!;
+  const slopeStandardError = reg.standardErrors[1]!;
+  const slopeTStatistic = reg.tStatistics[1]!;
+  const rSquared = reg.rSquared;
+  // Single regressor with intercept ⇒ R² is the squared correlation; sign follows the slope.
+  const correlation = Math.sign(slope) * Math.sqrt(Math.max(0, rSquared));
+
+  const referenceSpot = input.referenceSpot ?? spot[spot.length - 1]!;
+  ensurePositive(referenceSpot, 'referenceSpot', FN);
+  // Log basis: slope is ∂σ/∂ln S ⇒ ∂σ/∂S = slope / S at the reference spot. Level basis: slope IS ∂σ/∂S.
+  const volatilitySpotBeta = basis === 'log' ? slope / referenceSpot : slope;
+
+  const warnings: QuantWarning[] = [];
+  if (dropped > 0) {
+    warnings.push(
+      warning(
+        WarningCode.ModelLimitation,
+        `dropped ${dropped} change observation(s) with a non-finite IV change or non-positive spot.`,
+        'info',
+        { dropped },
+      ),
+    );
+  }
+  if (n < 20) {
+    warnings.push(
+      warning(
+        WarningCode.ModelLimitation,
+        `only ${n} change observation(s) — the β estimate is low-power; use a longer history.`,
+        'warn',
+        { changeObservations: n },
+      ),
+    );
+  }
+  if (!(Math.abs(slopeTStatistic) >= 2)) {
+    warnings.push(
+      warning(
+        WarningCode.ModelLimitation,
+        `the vol–spot slope is statistically insignificant (|t| = ${Math.abs(slopeTStatistic).toFixed(2)} < 2) — β may be noise, not a real leverage effect.`,
+        'warn',
+        { tStatistic: slopeTStatistic },
+      ),
+    );
+  }
+
+  const assumptions: Assumptions<{
+    measure: 'real-world-hedge';
+    basis: 'log' | 'level';
+    hacLags: number;
+  }> = {
+    conventionsVersion: CONVENTIONS_VERSION,
+    measure: 'real-world-hedge',
+    basis,
+    hacLags,
+  };
+
+  return {
+    value: {
+      volatilitySpotBeta,
+      slope,
+      slopeStandardError,
+      slopeTStatistic,
+      correlation,
+      rSquared,
+      observationCount: n,
+      dropped,
+      referenceSpot,
+    },
+    assumptions,
+    diagnostics: { warnings },
+  };
+}

package/modules/workflows/dist/capabilities.d.ts

@@ -0,0 +1,8 @@
+/** What a caller holds when it names nothing: read, analyze, propose. */
+export declare const DEFAULT_CAPABILITIES: readonly string[];
+/** The capabilities this stage names; a runtime may grant others (the registry does not enumerate them). */
+export declare const KNOWN_CAPABILITIES: readonly string[];
+export declare function requireCapabilities(functionName: string, field: string, value: unknown): readonly string[];
+/** The required capabilities the caller does not hold, sorted — the runtime's gate. Both lists are validated. */
+export declare function missingCapabilities(required: readonly string[], capabilities: readonly string[]): string[];
+//# sourceMappingURL=capabilities.d.ts.map

package/modules/workflows/dist/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAQA,yEAAyE;AACzE,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EAIhD,CAAC;AAEH,4GAA4G;AAC5G,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAO9C,CAAC;AAIH,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,OAAO,GACb,SAAS,MAAM,EAAE,CAwBnB;AAED,iHAAiH;AACjH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,YAAY,EAAE,SAAS,MAAM,EAAE,GAC9B,MAAM,EAAE,CAKV"}