@insiderfinance/totalfinance 0.1.0

package/modules/volatility/dist/analytics.js

@@ -0,0 +1,320 @@
+/**
+ * Model-free volatility analytics (spec §10): the risk-neutral probability distribution implied by an
+ * option smile (Breeden–Litzenberger), a realized-volatility cone, and the VIX-style variance-swap
+ * fair volatility. These turn a fitted smile or a price history into the "probability of landing in a
+ * range" and "is vol cheap/rich" read-outs an options dashboard leads with.
+ */
+import { CONVENTIONS_VERSION, ErrorCode, InputError, WarningCode, ensureFinite, ensureNonNegative, ensurePositive, finalizeResult, requireArgumentArray, validateClosedRequest, warning, } from '../../core/dist/index.js';
+import { quantile, standardDeviation } from '../../math/dist/index.js';
+import { blackScholesPrice } from '../../options/dist/black-scholes.js';
+import { RISK_NEUTRAL_ESTIMATE } from './estimate.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. The `volatilitySmile` CALLBACK and the
+ * `returns` ARRAY arguments carry no generated keys and keep their curated checks.
+ */
+function analyticsSpecOf(key) {
+    const spec = VALIDATION_SPECS[key];
+    if (spec === undefined) {
+        throw new Error(`analytics: no generated validation spec for '${key}' — run \`pnpm validation:update\``);
+    }
+    return spec;
+}
+const RISK_NEUTRAL_OPTIONS_SPEC = analyticsSpecOf('riskNeutralDistribution#1');
+const VOLATILITY_CONE_OPTIONS_SPEC = analyticsSpecOf('volatilityCone#1');
+const VARIANCE_SWAP_RATE_SPEC = analyticsSpecOf('varianceSwapRate#0');
+const RISK_NEUTRAL_EXAMPLE = () => 'riskNeutralDistribution((strike) => 0.2, { spot: 100, timeToExpiryYears: 0.25, riskFreeRate: 0.04 })';
+const VOLATILITY_CONE_EXAMPLE = () => 'volatilityCone(returns, { windows: [21, 63], periodsPerYear: 252 })';
+const VARIANCE_SWAP_RATE_EXAMPLE = () => 'varianceSwapRate({ strikes: [90, 100, 110], otmPrices: [2.1, 4.2, 1.8], forward: 100.5, ' +
+    'riskFreeRate: 0.04, timeToExpiryYears: 0.083 })';
+/**
+ * Breeden–Litzenberger (1978): the risk-neutral terminal distribution implied by a call-price curve.
+ * Given the smile `volatilitySmile(strike)`, prices calls via BSM and differentiates numerically:
+ * `f(K) = e^{rT}·∂²C/∂K²` and `F(K) = 1 + e^{rT}·∂C/∂K`. Use it for probability cones / expected-range
+ * bands. The smile must be arbitrage-free for the density to stay non-negative.
+ *
+ * Where it repairs itself, it SAYS SO on the returned `diagnostics`: a negative (arbitrageable)
+ * density clamped to zero, and the one-sided difference used for strikes within `step` of zero (a
+ * deep-downside probe like `density(0.05)` on a $100 name, which used to price a negative strike and
+ * return `NaN`). `diagnostics.warnings` fills in as the closures are queried — read it after use.
+ */
+export function riskNeutralDistribution(volatilitySmile, options) {
+    const functionName = 'riskNeutralDistribution';
+    if (typeof volatilitySmile !== 'function') {
+        throw new InputError(`${functionName}: volatilitySmile must be a function mapping strike → implied vol (e.g. () => 0.2 for a flat smile), got ${volatilitySmile === null ? 'null' : typeof volatilitySmile}.`, {
+            code: ErrorCode.InputWrongType,
+            context: { function: functionName, field: 'volatilitySmile' },
+        });
+    }
+    validateClosedRequest(functionName, options, RISK_NEUTRAL_OPTIONS_SPEC, {
+        argumentName: 'options',
+        exampleCall: RISK_NEUTRAL_EXAMPLE,
+    });
+    ensurePositive(options.spot, 'spot', functionName);
+    ensurePositive(options.timeToExpiryYears, 'timeToExpiryYears', functionName);
+    const q = options.dividendYield ?? 0;
+    // A zero/negative step collapses the finite-difference into a division blow-up — reject it.
+    if (options.step !== undefined)
+        ensurePositive(options.step, 'step', functionName);
+    const h = options.step ?? Math.max(1e-4, options.spot * 0.001);
+    const disc = Math.exp(options.riskFreeRate * options.timeToExpiryYears);
+    const C = (K) => blackScholesPrice({
+        type: 'call',
+        spot: options.spot,
+        strike: K,
+        timeToExpiryYears: options.timeToExpiryYears,
+        riskFreeRate: options.riskFreeRate,
+        dividendYield: q,
+        volatility: volatilitySmile(K),
+    });
+    const warnings = [];
+    let clampDisclosed = false;
+    let oneSidedDisclosed = false;
+    const discloseClamp = (K, raw) => {
+        if (clampDisclosed)
+            return;
+        clampDisclosed = true;
+        warnings.push(warning(WarningCode.ModelLimitation, `riskNeutralDistribution: the implied density went NEGATIVE (${raw.toExponential(3)} at strike ${K}) and was clamped to 0 — the smile is butterfly-arbitrageable there, so this is a repaired curve, not the market's distribution. Check the smile with checkButterfly / calibrateSvi before integrating it.`, 'warn', { strike: K, rawDensity: raw }));
+    };
+    const discloseOneSided = (K) => {
+        if (oneSidedDisclosed)
+            return;
+        oneSidedDisclosed = true;
+        warnings.push(warning(WarningCode.ModelLimitation, `riskNeutralDistribution: strike ${K} is within one difference step (${h}) of zero, so the centred difference would price a NEGATIVE strike (which returns NaN). A ONE-SIDED difference on [K, K+h, K+2h] was used there instead; it is first-order accurate rather than second-order.`, 'info', { strike: K, step: h }));
+    };
+    const cdf = (K) => {
+        if (!(K > 0))
+            return 0;
+        // Below one step from zero, `C(K − h)` is a negative-strike Black-Scholes call — undefined, and
+        // it came back NaN, so a perfectly legal deep-downside probe (`cdf(0.05)` on a $100 name)
+        // returned NaN from a function whose whole contract is a probability in [0, 1].
+        if (K <= h) {
+            discloseOneSided(K);
+            const dC = (C(K + h) - C(K)) / h; // forward difference
+            return Math.min(1, Math.max(0, 1 + disc * dC));
+        }
+        const dC = (C(K + h) - C(K - h)) / (2 * h);
+        return Math.min(1, Math.max(0, 1 + disc * dC));
+    };
+    const density = (K) => {
+        if (!(K > 0))
+            return 0;
+        // Same guard, second derivative: the one-sided second difference uses K, K+h, K+2h.
+        const raw = K <= h
+            ? (discloseOneSided(K), (disc * (C(K + 2 * h) - 2 * C(K + h) + C(K))) / (h * h))
+            : (disc * (C(K + h) - 2 * C(K) + C(K - h))) / (h * h);
+        if (raw < 0)
+            discloseClamp(K, raw);
+        return Math.max(0, raw);
+    };
+    return {
+        density,
+        cdf,
+        probabilityBelow: cdf,
+        probabilityAbove: (K) => 1 - cdf(K),
+        probabilityBetween: (a, b) => Math.max(0, cdf(b) - cdf(a)),
+        // The SAME array the closures push into — a caller who holds this object sees the disclosures
+        // its own queries produced (a fresh copy per read would hide them).
+        diagnostics: { engine: 'risk-neutral-distribution', method: 'breeden-litzenberger', warnings },
+    };
+}
+function volatilityConeComputation(functionName, returns, options) {
+    requireArgumentArray(functionName, 'returns', returns);
+    // `windows` names the cone's rows — a missing/scalar value would die on `.map`; the spec teaches.
+    validateClosedRequest(functionName, options, VOLATILITY_CONE_OPTIONS_SPEC, {
+        argumentName: 'options',
+        exampleCall: VOLATILITY_CONE_EXAMPLE,
+    });
+    const ppy = options.periodsPerYear ?? 252;
+    ensurePositive(ppy, 'periodsPerYear', functionName);
+    const n = returns.length;
+    const scale = Math.sqrt(ppy);
+    // A single non-finite return would poison every rolling stddev that overlaps it — reject up front.
+    const r = Array.from({ length: n }, (_, i) => {
+        ensureFinite(returns[i], `returns[${i}]`, functionName);
+        return returns[i];
+    });
+    const rows = options.windows.map((window) => {
+        // Safe integer (2026-08-23 review, P0): the rolling loop runs `n − window + 1` times, so the
+        // sample bounds the work — but a window above 2^53 is no longer an exact count, and the
+        // window-vs-history check below must compare real integers.
+        if (!Number.isSafeInteger(window) || window < 2) {
+            throw new InputError(`${functionName}: each window must be an integer ≥ 2, got ${window}.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { window },
+            });
+        }
+        const rvs = [];
+        for (let end = window; end <= n; end++) {
+            rvs.push(standardDeviation(r.slice(end - window, end)) * scale);
+        }
+        if (rvs.length === 0) {
+            // window > n: no complete rolling window exists. Emitting an all-NaN row would silently pass a
+            // useless result downstream — fail loudly so the caller shortens the window or feeds more history.
+            throw new InputError(`${functionName}: window ${window} exceeds the ${n}-observation return history — no complete rolling window exists.`, { code: ErrorCode.InputOutOfRange, context: { window, observations: n } });
+        }
+        return {
+            window,
+            min: Math.min(...rvs),
+            p25: quantile(rvs, 0.25),
+            median: quantile(rvs, 0.5),
+            p75: quantile(rvs, 0.75),
+            max: Math.max(...rvs),
+            current: rvs[rvs.length - 1],
+        };
+    });
+    return { rows, periodsPerYear: ppy, observationCount: n, annualizationFactor: scale };
+}
+/**
+ * Realized-volatility cone: for each lookback `window`, the percentile spread of annualized realized
+ * volatility across all rolling windows of the return series, plus the current reading. The classic
+ * "is implied vol rich or cheap vs the underlying's own realized history" view.
+ *
+ * Facade (H27): the plain call returns the rows array; `.explain()` discloses the applied
+ * `periodsPerYear`, windows, and annualization convention in `assumptions`, and the observation
+ * count / annualization factor in `diagnostics.decomposition`. Hand-attached (not `seriesFacade`)
+ * so the closed-request teaching errors for the options bag stay byte-identical.
+ */
+export const volatilityCone = Object.assign((returns, options) => volatilityConeComputation('volatilityCone', returns, options).rows, {
+    explain: (returns, options) => {
+        const c = volatilityConeComputation('volatilityCone.explain', returns, options);
+        return finalizeResult('volatilityCone', {
+            value: c.rows,
+            assumptions: {
+                conventionsVersion: CONVENTIONS_VERSION,
+                windows: [...options.windows],
+                periodsPerYear: c.periodsPerYear,
+                annualization: 'sqrt-periods-per-year',
+            },
+            diagnostics: {
+                method: 'rolling-window-percentiles',
+                // The scaling the rows came from: each realized vol is a rolling stddev multiplied by
+                // annualizationFactor = √periodsPerYear, over observationCount return observations.
+                decomposition: {
+                    observationCount: c.observationCount,
+                    annualizationFactor: c.annualizationFactor,
+                },
+                warnings: [],
+            },
+        });
+    },
+});
+/**
+ * Model-free implied volatility via the CBOE VIX replication (Demeterfi–Derman–Kamal–Zou): a strip of
+ * out-of-the-money option mid-prices integrates to the fair variance
+ * `σ² = (2/T)·Σ (ΔKᵢ/Kᵢ²)·e^{rT}·Q(Kᵢ) − (1/T)·(F/K₀ − 1)²`, where `K₀` is the highest strike below the
+ * forward `F`. `otmPrices[i]` is the OTM option (put below `F`, call above) mid at `strikes[i]`.
+ *
+ * **At `K₀` the CBOE strip is the AVERAGE of the put and the call**, and the `−(1/T)(F/K₀ − 1)²`
+ * correction subtracted here is derived for exactly that convention. Supply the `K₀` call as
+ * `boundaryCallPrice` and pass the `K₀` PUT in `otmPrices` — the two are averaged for you. With a
+ * put-only `K₀` price and no `boundaryCallPrice` the strip under-states variance by
+ * `ΔK₀·(F − K₀)/(T·K₀²)` (by put–call parity the missing half-difference is `(C−P)/2 = e^{−rT}(F−K₀)/2`),
+ * which on a typical 1-month index chain is ~1.7 vol points — so the disclosure rides the result.
+ */
+export function varianceSwapRate(options) {
+    validateClosedRequest('varianceSwapRate', options, VARIANCE_SWAP_RATE_SPEC, {
+        argumentName: 'options',
+        exampleCall: VARIANCE_SWAP_RATE_EXAMPLE,
+    });
+    if (options.boundaryCallPrice !== undefined && options.boundaryPriceAveraged === true) {
+        throw new InputError(`varianceSwapRate: boundaryCallPrice and boundaryPriceAveraged are mutually exclusive — the first says "otmPrices at K₀ is the PUT, average it with this call", the second says "it is already the average". Pass one.`, { code: ErrorCode.InputOutOfRange, context: { function: 'varianceSwapRate' } });
+    }
+    const functionName = 'varianceSwapRate';
+    const { strikes, otmPrices, forward, riskFreeRate, timeToExpiryYears } = options;
+    if (strikes.length < 3 || strikes.length !== otmPrices.length) {
+        throw new InputError(`${functionName}: need ≥ 3 strikes and matching otmPrices.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { strikes: strikes.length, prices: otmPrices.length },
+        });
+    }
+    ensurePositive(forward, 'forward', functionName);
+    ensurePositive(timeToExpiryYears, 'timeToExpiryYears', functionName);
+    for (let i = 0; i < strikes.length; i++) {
+        ensurePositive(strikes[i], `strikes[${i}]`, functionName);
+        ensureNonNegative(otmPrices[i], `otmPrices[${i}]`, functionName);
+    }
+    // strikes ascending
+    const order = strikes.map((_, i) => i).sort((a, b) => strikes[a] - strikes[b]);
+    const K = order.map((i) => strikes[i]);
+    const Q = order.map((i) => otmPrices[i]);
+    for (let i = 1; i < K.length; i++) {
+        if (K[i] === K[i - 1]) {
+            throw new InputError(`${functionName}: duplicate strike ${K[i]}.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { strike: K[i] },
+            });
+        }
+    }
+    // K0 = highest strike ≤ forward; the replication is undefined if no strike straddles below F.
+    if (K[0] > forward) {
+        throw new InputError(`${functionName}: need a strike at or below the forward ${forward} (lowest is ${K[0]}).`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { forward, lowestStrike: K[0] },
+        });
+    }
+    let k0 = 0;
+    for (let i = 0; i < K.length; i++)
+        if (K[i] <= forward)
+            k0 = i;
+    const warnings = [RISK_NEUTRAL_ESTIMATE];
+    // CBOE: the K₀ term is (put + call)/2 — apply it when the caller supplies the K₀ call.
+    const boundaryAveraged = options.boundaryCallPrice !== undefined || options.boundaryPriceAveraged === true;
+    if (options.boundaryCallPrice !== undefined) {
+        ensureNonNegative(options.boundaryCallPrice, 'boundaryCallPrice', functionName);
+        Q[k0] = (Q[k0] + options.boundaryCallPrice) / 2;
+    }
+    // The K₀ strike spacing, shared by the strip sum and the put-only bias estimate below.
+    const dK0 = k0 === 0
+        ? K[1] - K[0]
+        : k0 === K.length - 1
+            ? K[k0] - K[k0 - 1]
+            : (K[k0 + 1] - K[k0 - 1]) / 2;
+    const disc = Math.exp(riskFreeRate * timeToExpiryYears);
+    let sum = 0;
+    for (let i = 0; i < K.length; i++) {
+        const dK = i === 0
+            ? K[1] - K[0]
+            : i === K.length - 1
+                ? K[i] - K[i - 1]
+                : (K[i + 1] - K[i - 1]) / 2;
+        sum += (dK / (K[i] * K[i])) * disc * Q[i];
+    }
+    const variance = (2 / timeToExpiryYears) * sum - (1 / timeToExpiryYears) * (forward / K[k0] - 1) ** 2;
+    if (!boundaryAveraged) {
+        // Quantified, not hand-waved: the missing half of the K₀ put/call average is (C−P)/2, which by
+        // parity is e^{−rT}(F−K₀)/2; carried through the strip that is ΔK₀·(F−K₀)/(T·K₀²) of variance.
+        const varianceBias = (dK0 * (forward - K[k0])) / (timeToExpiryYears * K[k0] * K[k0]);
+        const volatilityPoints = (Math.sqrt(Math.max(0, variance + varianceBias)) - Math.sqrt(Math.max(0, variance))) * 100;
+        warnings.push(warning(WarningCode.ModelLimitation, `varianceSwapRate: no boundaryCallPrice was supplied, so the K₀=${K[k0]} term used the single price you passed. The CBOE replication averages the K₀ put AND call there, and the (F/K₀−1)² correction subtracted here is derived for that average: with a put-only K₀ the fair variance is understated by ≈ ${varianceBias.toExponential(3)} (${volatilityPoints.toFixed(2)} vol points on this strip). Pass boundaryCallPrice to remove it.`, 'warn', {
+            boundaryStrike: K[k0],
+            forward,
+            varianceBias,
+            volatilityPointBias: volatilityPoints,
+        }));
+    }
+    let fairVolatility;
+    if (variance < 0) {
+        // A negative fair variance means the OTM strip is internally inconsistent (arbitrageable prices
+        // or a strip far too sparse around the forward). Silently returning { variance: -x, fairVolatility: 0 }
+        // would hide that; the variance is reported as computed, fairVolatility has no real value (NaN), and the
+        // caveat says so explicitly (design law #4 — NaN only alongside a disclosed reason).
+        fairVolatility = NaN;
+        warnings.push(warning(WarningCode.ModelLimitation, `fair variance is negative (${variance}) — the OTM strip is arbitrageable or too sparse for the DDKZ replication; fairVolatility is NaN (no real √variance exists).`, 'warn', { variance }));
+    }
+    else {
+        fairVolatility = Math.sqrt(variance);
+    }
+    return {
+        value: { variance, fairVolatility },
+        assumptions: {
+            conventionsVersion: CONVENTIONS_VERSION,
+            timeToExpiryYears,
+            measure: 'risk-neutral',
+            method: 'ddkz-replication',
+        },
+        diagnostics: { warnings },
+    };
+}
+//# sourceMappingURL=analytics.js.map

package/modules/volatility/dist/analytics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.js","sourceRoot":"","sources":["../src/analytics.ts"],"names":[],"mappings":"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"}

package/modules/volatility/dist/arbitrage.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Static no-arbitrage diagnostics for an implied-volatility surface (spec §10.1).
+ *
+ * Two model-free checks, both expressed in **total variance** `w(k) = σ(k)²·t` over forward
+ * log-moneyness `k = ln(K/F)` — the coordinates in which the no-arbitrage conditions are clean:
+ *
+ *   • **Calendar arbitrage** — total variance must be non-decreasing in maturity at every fixed `k`.
+ *     A drop `w(k, Tᵢ) > w(k, Tᵢ₊₁)` is a calendar spread you could lock in for free.
+ *   • **Butterfly arbitrage** — the risk-neutral density implied by a smile is proportional to
+ *     Gatheral's `g(k)`; `g(k) ≥ 0` everywhere ⇔ no butterfly arbitrage. This *is* the convexity of
+ *     the call-price-in-strike function, so it covers the "convexity" check; monotonicity of the
+ *     implied CDF follows from a non-negative density with finite wings.
+ *
+ * The checks operate on a light {@link ArbitrageSlice} abstraction (forward, maturity, an `iv(strike)`
+ * function, and the fitted strike range), so they apply equally to raw, interpolated, SVI, and SABR
+ * surfaces. {@link surfaceArbitrageReport} adapts a {@link VolatilitySurface} to it.
+ */
+import { type Computed, type Diagnostics } from '../../core/dist/index.js';
+import type { VolatilitySurface } from './surface.js';
+/** A single expiry slice, as the arbitrage checks see it. */
+export interface ArbitrageSlice {
+    expiry: string;
+    /** Time to expiry in years. */
+    timeToExpiryYears: number;
+    /** Forward price `S·e^{(r−q)t}`. */
+    forward: number;
+    /** Implied volatility at an absolute strike. */
+    impliedVolatility: (strike: number) => number;
+    /** Fitted strike range `[Kmin, Kmax]`. */
+    strikeRange: [number, number];
+    /**
+     * The slice's actual strike ladder, when known. Used ONLY to size the DEFAULT scan grids: the
+     * checks then sample at least {@link SAMPLES_PER_STRIKE_GAP} points per adjacent-strike gap, so a
+     * violation planted at a single strike cannot hide between two scan points (an explicit
+     * `butterflyPoints`/`calendarPoints` still wins). Omitted ⇒ the fixed 40/21-point defaults.
+     */
+    strikes?: readonly number[];
+}
+export type ArbitrageKind = 'calendar' | 'butterfly';
+export interface ArbitrageViolation {
+    kind: ArbitrageKind;
+    /** The expiry where the breach occurs (the later expiry for a calendar breach). */
+    expiry: string;
+    /** Approximate strike of the worst breach. */
+    strike: number;
+    /** Forward log-moneyness of the worst breach. */
+    logMoneyness: number;
+    /** Severity: the total-variance drop (calendar) or the most-negative `g(k)` (butterfly). */
+    magnitude: number;
+    message: string;
+}
+export interface ArbitrageReport {
+    /** True when no calendar or butterfly violation was found. */
+    arbitrageFree: boolean;
+    violations: ArbitrageViolation[];
+    /** Per-check pass/fail summary. */
+    checks: {
+        calendar: boolean;
+        butterfly: boolean;
+    };
+    /** Applied conventions/knobs, echoed (Law 2 report grammar). */
+    assumptions: {
+        conventionsVersion: string;
+        tolerance: number;
+        butterflyPoints: number;
+        calendarPoints: number;
+        step: number;
+    };
+    /** Structured warnings (carried-through surface warnings live here); always present. */
+    diagnostics: Diagnostics;
+}
+/** The conventions echoed by the per-check envelopes ({@link checkCalendar} / {@link checkButterfly}). */
+type ArbitrageCheckExtra = {
+    tolerance: number;
+    points: number;
+    step?: number;
+};
+/** Knobs used only by the butterfly-density scan. */
+export interface ButterflyCheckOptions {
+    /** Log-moneyness samples per slice for the butterfly check (default 40, must be ≥ 3). */
+    butterflyPoints?: number;
+    /** Central-difference step in log-moneyness for the density derivatives (default 0.01, must be > 0). */
+    step?: number;
+    /** Tolerance below which a breach is reported (default 1e-4, must be finite ≥ 0). */
+    tolerance?: number;
+}
+/** Knobs used only by the calendar total-variance scan. */
+export interface CalendarCheckOptions {
+    /** Log-moneyness samples for each calendar pair (default 21, must be ≥ 2). */
+    calendarPoints?: number;
+    /** Tolerance below which a breach is reported (default 1e-4, must be finite ≥ 0). */
+    tolerance?: number;
+}
+/** Combined knobs for reports that deliberately run both checks. */
+export interface ArbitrageCheckOptions extends ButterflyCheckOptions, CalendarCheckOptions {
+}
+/**
+ * Calendar arbitrage: total variance must not fall as maturity increases (at fixed
+ * forward-moneyness). Envelope-shaped: `value` is the violation list, `assumptions` echoes the
+ * scan knobs (`points` is the resolution actually scanned — see {@link ArbitrageSlice.strikes}), and
+ * `diagnostics` is the standard warnings carrier (Law 2 analysis grammar).
+ */
+export declare function checkCalendar(slices: ArbitrageSlice[], options?: CalendarCheckOptions): Computed<ArbitrageViolation[], ArbitrageCheckExtra>;
+/**
+ * Butterfly arbitrage: Gatheral's `g(k)` (∝ risk-neutral density) must stay non-negative.
+ * Envelope-shaped: `value` is the violation list, `assumptions.points` the resolution actually
+ * scanned (density-scaled from {@link ArbitrageSlice.strikes} when present) (Law 2 analysis grammar).
+ */
+export declare function checkButterfly(slice: ArbitrageSlice, options?: ButterflyCheckOptions): Computed<ArbitrageViolation[], ArbitrageCheckExtra>;
+/** Run all static no-arbitrage checks over a set of slices (Law 2 report grammar). */
+export declare function arbitrageReport(slices: ArbitrageSlice[], options?: ArbitrageCheckOptions): ArbitrageReport;
+/**
+ * Adapt a {@link VolatilitySurface} to {@link arbitrageReport}, carrying its sparse-data warnings through
+ * into `diagnostics.warnings`.
+ */
+export declare function surfaceArbitrageReport(surface: VolatilitySurface, options?: ArbitrageCheckOptions): ArbitrageReport;
+export {};
+//# sourceMappingURL=arbitrage.d.ts.map

package/modules/volatility/dist/arbitrage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arbitrage.d.ts","sourceRoot":"","sources":["../src/arbitrage.ts"],"names":[],"mappings":"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"}