@insiderfinance/totalfinance 0.1.0

package/modules/structure/OPTION-FLOW-DRIFT.md

@@ -0,0 +1,126 @@
+# Option trade-premium drift
+
+`optionFlowDrift` is raw premium accounting for an explicit trading session. It is **not**
+`exposure(...).netDrift()` (dealer hedging estimates), `deltaAdjustedPremium()` (delta-weighted
+premium), profit/loss, or an income prediction.
+
+```ts
+import { optionFlowDrift, type OptionFlowDriftTrade } from '@insiderfinance/totalfinance/structure';
+import { NYSE } from '@insiderfinance/totalfinance/calendars';
+
+const trades: OptionFlowDriftTrade[] = []; // canonical core OptionTrade inputs, epoch milliseconds
+const result = optionFlowDrift({
+  trades,
+  session: { date: '2026-06-04', calendar: NYSE },
+  config: {
+    symbol: 'SPY',
+    classificationSource: 'provided-first',
+    bucketMinutes: 5,
+    asOf: Date.parse('2026-06-04T15:00:00Z'),
+  },
+});
+
+result.value.minutes; // separate change/cumulative totals and print provenance
+result.value.buckets; // open-anchored five-minute intervals
+result.value.summary;
+result.assumptions; // calendar/version, policies, multipliers, threshold, cutoff
+result.diagnostics.warnings; // model limitations; no probability claims
+```
+
+## Classification authority
+
+| `classificationSource` | Supplied buy/sell | Supplied unknown | Absent classification |
+| ---------------------- | ----------------- | ---------------- | --------------------- |
+| `provided-or-quotes`   | Preserve          | Quote fallback   | Quote fallback        |
+| `provided-first`       | Preserve          | Preserve         | Quote fallback        |
+| `provided-only`        | Preserve          | Preserve         | Unknown               |
+| `quotes-only`          | Quote rule        | Quote rule       | Quote rule            |
+
+`flow()` retains `provided-or-quotes` as its backwards-compatible default. The new drift API
+defaults to `provided-first`. Every print reports `classificationProvenance`, including the
+applied policy, actual source/reason and `providedSide`: `null` means absent, whereas `'unknown'`
+means an explicit provider label. A supplied label is authoritative under the chosen policy, not
+independently verified. Bad source enums fail even when the policy would ignore the label.
+
+The existing quote rule compares price to NBBO: at/above ask buys, at/below bid sells, and
+inside-spread prices compare to the midpoint. Midpoint, locked/crossed and missing quote cases
+stay unknown. There is no tick test or inferred opening/closing position in drift.
+
+## Accounting and output meaning
+
+- Premium is supplied `premium` (including zero), otherwise `price * size * multiplier`.
+  Contract multiplier overrides `config.multiplier` (default 100). Volume remains contracts,
+  never shares. Combined premiums must already be in one currency; no FX conversion occurs.
+- Call drift = call buy premium − call sell premium. Put drift = put buy premium − put sell
+  premium. Net directional drift = call drift − put drift.
+- Call buys / put sells map to bullish premium and contracts. Call sells / put buys map to
+  bearish premium and contracts. These are trade-initiation heuristics, not position intent.
+- Unknown prints contribute neither signed drift nor signed volume. They remain in gross
+  premium, volume and counts. Bounds are drift ± the corresponding unknown premium; net bounds
+  include all unknown premium. These are worst-case sign-assignment bounds, **not statistical
+  confidence intervals**.
+- `classificationCoverage` = classified premium / total premium, or `null` at zero premium.
+  It is data coverage, not confidence in a trade, future price move or profitable outcome.
+- Each minute and larger bucket has `change` (that interval only) and `cumulative` (from open).
+  The summary uses the same accounting over the whole selected interval. Empty intervals remain,
+  including leading/trailing ones; changes are zero and cumulative values carry forward.
+- `volumeConfirmation` is `aligned`, `opposed`, or `none` according to nonzero net premium and
+  volume signs in the **same window**. Heuristic precedence is: empty/zero premium → `no-signal`;
+  coverage below the configured threshold (default 0.6) → `low-coverage`; opposing volume →
+  `volume-opposed`; call positive / put negative → `bullish-expansion`; the reverse →
+  `bearish-expansion`; other nonzero net → `mixed-flow`; otherwise `no-signal`.
+
+The five-print synthetic probe recorded in the September comparison yields call drift 1,500,
+put drift −200, net 1,700, unknown premium 310, classification coverage 3,900/4,210, and net
+bounds [1,390, 2,010]. Opting into legacy fallback instead classifies its unknown print and
+produces net 2,010. The fixture is a recorded **synthetic comparison**, not a live market tape.
+
+## Sessions, ordering and prices
+
+`session.date` is mandatory and belongs to the calendar's timezone. NYSE is the default; core
+`Calendar` and calendars `TradingCalendar` implementations are accepted. Open, close, holidays,
+and early closes come from `calendar.session(date)`. Closed dates return no intervals and zero
+summary totals with null coverage. Custom calendars support `24:00` close; ambiguous/nonexistent
+DST boundaries and invalid/reversed session hours fail rather than being guessed.
+
+Open is inclusive; close and `config.asOf` are exclusive. An as-of cutoff is clamped to the
+selected session. No future buckets are emitted. A cutoff inside a minute produces a shortened
+final bucket marked `partial`. All values are available at the **end** of the interval, not at
+its start. Labeling a bucket with its start does not make its final totals usable at that time.
+
+Scope uses exact, case-sensitive `config.symbol`; omission means marketwide. A single-symbol
+scope defaults its overlay to that symbol's `OptionTrade.underlyingPrice`. Marketwide has no
+default overlay: specify `config.priceOverlay: { symbol: 'SPY', quotes?, trades? }`. External
+overlay rows use core `Quote` / `Trade` objects and can come from a symbol outside the premium
+scope. Non-crossed positive bid/ask quotes yield midpoint prices; zero-sided/crossed quotes are
+unavailable. Locked underlying quotes still provide a price (but no option aggressor signal).
+
+Only observations within the session and strictly before the bucket end are eligible. The
+latest one carries forward; missing stays `null`. No pre-session carry-in or future-price
+backfill occurs. Ties prefer underlying trades, then quote midpoints, then option-print
+underlying prices; last input wins within a source. Every price reports its symbol, timestamp,
+and source. Input timestamps must reflect availability; embedded `underlyingPrice` is assumed
+available at its option print timestamp. Publication delays, later corrections and staleness
+are not reconstructed; the output retains price timestamps so callers can apply their own limits.
+
+All supplied prints are validated, even outside the selected date/scope/cutoff. Finite numbers
+are not coerced from strings; timestamps must be representable integer epoch milliseconds.
+An epoch-seconds number is interpreted literally as milliseconds, not rescaled or guessed.
+Trades are stably sorted by timestamp without modifying the caller's tape; equal timestamps
+preserve input order and each output print retains its original `inputIndex`.
+
+Repeated `id` values fail, even across symbols or with changed values. IDs must be tape-wide
+unique; namespace provider/venue IDs when combining feeds. Without IDs, identical prints in
+the consumed identity/accounting/quote fields (including sequence and venue) fail. Distinct
+executions that otherwise look identical need distinct IDs. There is no silent deduplication.
+Vendor decoration on data rows stays open; request, session, config and overlay option bags
+reject unknown keys. Invalid inputs and non-finite arithmetic produce typed `InputError`s.
+
+## Public availability
+
+`optionFlowDrift` is exported from `@insiderfinance/totalfinance/structure` and through the root's structure
+re-export; no deep subpath is required. Raw trade-premium drift remains distinct from dealer
+hedging drift.
+
+This is a provider-free calculation, not a data feed or execution transport. SDK availability does
+not imply a dedicated MCP tool or access to an application's licensed trade tape.

package/modules/structure/dist/exposure.d.ts

@@ -0,0 +1,350 @@
+/**
+ * Options market-structure exposure (spec §11.1–11.5): per-contract and aggregate dealer-positioning
+ * estimates — GEX, DEX, vega/vanna/charm exposure — plus levels (walls, zero-gamma, max pain, pin
+ * risk), by-strike/by-expiry profiles, and scenario maps.
+ *
+ * IMPORTANT: these analytics ESTIMATE positioning from open interest and a sign convention. They do
+ * not know true dealer books. Every result echoes its sign convention in `assumptions.convention`
+ * and carries its model limitations as `model.limitation` entries in `diagnostics.warnings` (R2 —
+ * no hoisted fields). There is no ambiguous canonical `vex`; vega-of-spot is `vega` and
+ * vega-of-spot/vol cross is `vanna`.
+ *
+ * GEX (per-1%-move convention, the spec formula): `Γ · openInterest · multiplier · spot² · 0.01`.
+ */
+import { type Assumptions, type Diagnostics, type EpochMs, type MarketInputs, type OptionQuote, type OptionType, type PriceSource } from '../../core/dist/index.js';
+export type ExposureConvention = 'callsPositivePutsNegative' | 'dealerShortGamma' | 'tradeSignedAggressor' | {
+    calls: 1 | -1;
+    puts: 1 | -1;
+};
+export type GammaUnit = 'per1PercentMove' | 'perPoint';
+export type ExposureMetric = 'gex' | 'dex' | 'vega' | 'vanna' | 'charm' | 'theta' | 'vomma' | 'speed' | 'color';
+/**
+ * Market snapshot for `exposure()` — the workspace-canonical {@link MarketInputs}, except `spot` is
+ * optional here because it falls back to each quote's `underlyingPrice` when omitted (WS3.2), and
+ * `asOf` also accepts the ONE canonical "when" grammar (core `resolveAsOf`): epoch ms, `YYYY-MM-DD`
+ * (UTC midnight), or a ZONED ISO datetime — a bare zone-less datetime throws the teaching error.
+ */
+export type ExposureMarket = Omit<MarketInputs, 'spot' | 'asOf'> & {
+    /** Spot price. Falls back to each quote's `underlyingPrice` when omitted. */
+    spot?: number;
+    /** Snapshot time: epoch ms, `'YYYY-MM-DD'`, or a zoned ISO datetime (core `resolveAsOf` grammar). */
+    asOf: EpochMs | string;
+};
+/** Non-market exposure configuration: the sign convention and computation knobs (WS3.2). */
+export interface ExposureConfig {
+    /** REQUIRED sign convention; echoed in `assumptions.convention` with its caveat in diagnostics. */
+    convention: ExposureConvention;
+    priceSource?: PriceSource;
+    /** `per1PercentMove` (default, the spec GEX formula) or `perPoint`. */
+    gammaUnit?: GammaUnit;
+    /** Skip contracts with time-to-expiry below this many years (default 0). */
+    minTimeToExpiry?: number;
+    /** Contract multiplier when a quote omits one (default 100). */
+    defaultMultiplier?: number;
+}
+export interface ContractExposure {
+    expiry: string;
+    strike: number;
+    type: OptionType;
+    timeToExpiryYears: number;
+    impliedVolatility: number;
+    openInterest: number;
+    multiplier: number;
+    /** Applied position sign (+1/−1) from the convention. */
+    sign: number;
+    gamma: number;
+    delta: number;
+    gex: number;
+    dex: number;
+    vega: number;
+    vanna: number;
+    charm: number;
+    theta: number;
+    vomma: number;
+    speed: number;
+    color: number;
+}
+export interface ExposureTotals {
+    /** Dollar gamma exposure (`Γ·OI·mult·spot²·0.01` per-1%-move, signed by convention). */
+    gex: number;
+    /** Dollar delta exposure (`Δ·OI·mult·spot`). */
+    dex: number;
+    /** Vega exposure (`vega/1%·OI·mult`). */
+    vega: number;
+    /** Vanna exposure: dollar-delta change per +1% vol. */
+    vanna: number;
+    /**
+     * Charm exposure: signed dollar-delta change as ONE calendar day ELAPSES (positive ⇒ dealer delta
+     * increases day-over-day). Reported as `−∂DEX/∂T` per day, so its sign matches the passage of time.
+     */
+    charm: number;
+    /** Theta exposure: dollar option-price decay per calendar day. */
+    theta: number;
+    /** Vomma (volga) exposure: change in vega exposure per +1% vol. */
+    vomma: number;
+    /**
+     * Speed exposure: the CHANGE IN `gex` for a **+1% spot move**, in the same unit as `gex`
+     * (`gammaUnit`). It is the full derivative of the GEX definition, not the bare third-order greek:
+     * per-1%-move, `Δgex = (speed·S + 2·Γ)·OI·mult·sign·S²·1e-4`; per-point, `(speed·S + Γ)·OI·mult·sign·S·0.01`.
+     * So `aggregate.speed ≈ atSpot(spot·1.01).gex − atSpot(spot).gex` (a first-order estimate of it).
+     */
+    speed: number;
+    /**
+     * Color exposure: signed change in GEX as ONE calendar day ELAPSES (`−∂GEX/∂T` per day), so a
+     * positive value means dealer gamma exposure grows as time passes.
+     */
+    color: number;
+}
+/**
+ * The call/put GEX + OI split attached to a by-strike row WHEN `'gex'` is requested (WS4.5): the
+ * canonical dashboard chart draws `callGex` bars up and `putGex` bars down. `callGex + putGex`
+ * equals the row's net `gex`; `callOpenInterest + putOpenInterest` equals the total open interest at that strike.
+ */
+export type GexSplit = {
+    callGex: number;
+    putGex: number;
+    callOpenInterest: number;
+    putOpenInterest: number;
+};
+/**
+ * A by-strike row narrowed to the requested metrics: only the selected `M` keys are present (WS2.4),
+ * never a zero-filled full set. `StrikeRow` with no type argument is the full-metrics row. When `M`
+ * includes `'gex'` the row additionally carries the {@link GexSplit} call/put columns (WS4.5); when it
+ * does not, the conditional intersects with `unknown` (a no-op) so non-gex rows stay lean.
+ */
+export type StrikeRow<M extends ExposureMetric = ExposureMetric> = {
+    strike: number;
+} & Pick<ExposureTotals, M> & ('gex' extends M ? GexSplit : unknown);
+/** A by-expiry row narrowed to the requested metrics (see {@link StrikeRow}). */
+export type ExpiryRow<M extends ExposureMetric = ExposureMetric> = {
+    expiry: string;
+} & Pick<ExposureTotals, M>;
+export interface Levels {
+    /**
+     * Spot level where net GEX flips sign, chosen as the interpolated gamma-flip NEAREST spot when the
+     * profile has more than one flip in [0.8·spot, 1.2·spot]. Null when no flip exists in range.
+     */
+    zeroGamma: number | null;
+    /** All interpolated gamma-flip levels in [0.8·spot, 1.2·spot], sorted ascending (may be empty). */
+    gammaFlips: number[];
+    /** Direction at the current spot: `positive` (mean-reverting) or `negative` (trending), or null. */
+    gammaRegime: 'positive' | 'negative' | null;
+    /**
+     * Strike with the largest summed |call GEX| across ALL expiries (resistance). Magnitude, not signed:
+     * the wall is where the most call gamma sits, which is the same strike whichever way the convention
+     * signs it.
+     */
+    callWall: number | null;
+    /** Strike with the largest summed |put GEX| across ALL expiries, under the convention (support). */
+    putWall: number | null;
+    maxGammaStrike: number | null;
+    minGammaStrike: number | null;
+    /**
+     * Strike minimizing total in-the-money option value to holders (max writer profit), computed for the
+     * NEAREST expiry only — max pain is expiry-specific and cannot be aggregated across expirations.
+     */
+    maxPain: number | null;
+    largestCallOpenInterest: number | null;
+    largestPutOpenInterest: number | null;
+    vannaWall: number | null;
+    charmWall: number | null;
+    /** Nearest high-gamma strike to spot, with `atRisk` true when spot is within `pinRiskBand`. */
+    pinRisk: {
+        strike: number;
+        atRisk: boolean;
+    } | null;
+    /**
+     * Largest net-|GEX| strike (calls + puts summed per strike) among 0DTE contracts — expiring on the
+     * snapshot's own **America/New_York** trading date (not its UTC date: after 20:00 ET the UTC date is
+     * already tomorrow, which flagged the NEXT session's expiry as 0DTE).
+     */
+    zeroDaysToExpiryWall: number | null;
+    /** Largest net-|GEX| strike (calls + puts summed per strike) in the nearest Friday (weekly) expiry. */
+    weeklyOpexWall: number | null;
+    /** Largest net-|GEX| strike (calls + puts summed per strike) in the nearest monthly OPEX (3rd-Friday). */
+    monthlyOpexWall: number | null;
+}
+/** Net dealer-hedging drift estimate (spec §11.5). */
+export interface NetDrift {
+    /** `positive` (mean-reverting/pinning) or `negative` (trending), or null. */
+    gammaRegime: 'positive' | 'negative' | null;
+    /** The zero-gamma level (gamma flip) — the attractor in positive gamma, repeller in negative. */
+    zeroGamma: number | null;
+    /** Signed distance from spot to zero-gamma as a fraction of spot (positive ⇒ flip is above spot). */
+    distanceToZeroGamma: number | null;
+    /** `pin` (gamma pulls spot toward zero-gamma) / `trend` (pushes away) / null. */
+    bias: 'pin' | 'trend' | null;
+    /**
+     * Aggregate charm exposure: signed dealer delta to re-hedge as ONE calendar day ELAPSES (drift into
+     * expiry). Positive ⇒ dealers accumulate long delta day-over-day. Uses the elapsed-time sign
+     * (`−∂DEX/∂T` per day), so it reads the same direction as the passage of time.
+     */
+    charmFlowPerDay: number;
+    /**
+     * Aggregate vanna exposure: signed dealer delta to re-hedge per +1 VOL POINT (a +0.01 move in
+     * implied volatility), matching the per-1%-move convention `gex` uses. The unit is in the name
+     * because the value is 100x smaller than a per-unit-volatility reading of the same greek.
+     */
+    vannaFlowPerVolatilityPoint: number;
+}
+/** The metrics a `scenarioMap` computes when none are requested. */
+export type DefaultScenarioMetric = 'gex' | 'dex' | 'vanna' | 'charm';
+export interface ScenarioMapOptions<M extends ExposureMetric = ExposureMetric> {
+    /** Spot grid: explicit prices, or `{ from, to, steps }`. Defaults to ±10% around spot, 41 steps. */
+    spot?: number[] | {
+        from: number;
+        to: number;
+        steps: number;
+    };
+    /** Additive vol shocks (decimal), e.g. `[-0.05, 0, 0.05]`. Default `[0]`. */
+    volatilityShock?: number[];
+    /** Years to advance time (reducing each T), e.g. `[0, 1/365]`. Default `[0]`. */
+    timeAdvance?: number[];
+    /** Which metrics to compute. Default `['gex','dex','vanna','charm']`. */
+    metrics?: readonly M[];
+}
+/** A scenario-grid cell carrying ONLY the requested metrics (WS2.4), plus its grid coordinates. */
+export type ScenarioCell<M extends ExposureMetric = ExposureMetric> = {
+    spot: number;
+    volatilityShock: number;
+    timeAdvance: number;
+} & Pick<ExposureTotals, M>;
+export interface ScenarioMap<M extends ExposureMetric = ExposureMetric> {
+    cells: ScenarioCell<M>[];
+    metrics: M[];
+    /** Total greek recomputations performed (for the acceleration-need benchmark). */
+    evaluations: number;
+}
+/**
+ * A computed exposure profile with levels, by-strike/by-expiry views, and scenario maps. R2
+ * envelope: the sign convention and every resolved knob live in `assumptions`; model limitations
+ * ride `diagnostics.warnings` as `model.limitation` entries — nothing is hoisted top-level.
+ */
+export declare class ExposureProfile {
+    readonly spot: number;
+    /** Frozen result rows — a profile is a snapshot; mutate a copy, never the result. */
+    readonly contracts: readonly Readonly<ContractExposure>[];
+    readonly aggregate: ExposureTotals;
+    readonly assumptions: Assumptions<{
+        /** Charm/color are reported per calendar day ELAPSED (`−∂/∂T`), matching the passage of time. */
+        timeDecayDirection: 'perCalendarDayElapsed';
+        /** Spot-shift scans (zeroGamma, scenarioMap) hold each contract's IV fixed (sticky-strike). */
+        scanVolatilityPolicy: 'stickyStrike';
+        /** The resolved sign convention (echoed; its caveat rides `diagnostics.warnings`). */
+        convention: {
+            name: string;
+            calls: number;
+            puts: number;
+        };
+        /** GEX unit: `per1PercentMove` (spec formula) or `perPoint`. */
+        gammaUnit: GammaUnit;
+        /** Quote price used for the IV fallback when a quote has no usable `impliedVolatility`. */
+        priceSource: PriceSource;
+        /** Contracts with time-to-expiry (years) at/below this were skipped. */
+        minTimeToExpiry: number;
+        /** Contract multiplier applied when a quote omits one. */
+        defaultMultiplier: number;
+    }>;
+    readonly diagnostics: Diagnostics;
+    private readonly resolved;
+    /** Resolved per-type position signs (also echoed in `assumptions.convention`). */
+    private readonly signs;
+    private readonly r;
+    private readonly q;
+    private readonly gammaUnit;
+    private readonly asOf;
+    /** The snapshot's America/New_York trading-DAY index — the 0DTE bucket's day boundary. */
+    private readonly asOfDayIndex;
+    constructor(request: ExposureInput);
+    /**
+     * Per-contract exposure at a given spot/iv/t (used for the base profile and scenario maps). The
+     * second-order (`blackScholesExtendedGreeks`) pass — vanna/charm/vomma/speed/color — is computed only when
+     * `computeExtended` is set; a gex/dex-only scenario map skips it entirely (WS2.4), which roughly
+     * halves its work. When skipped, those five fields are 0 and MUST NOT be read (callers gate on the
+     * requested-metric set so they never are).
+     */
+    private exposureFor;
+    /**
+     * Per-tick fast path: re-evaluate NET dollar-gamma (`gex`) and NET dollar-delta (`dex`) exposure at
+     * a new `spot`, holding each contract's IV, time-to-expiry, and open interest FIXED (sticky-strike,
+     * echoed in `assumptions.scanVolatilityPolicy`) — only spot moves and gamma/delta are re-evaluated. This is
+     * the intraday dashboard path (one cheap greek pass per tick); a full {@link exposure} re-run — which
+     * re-derives IV, the extended greeks, and levels — is the per-refresh path. At the profile's original
+     * spot this reproduces `aggregate.gex`/`aggregate.dex` exactly (same operations, same order).
+     */
+    atSpot(spot: number): {
+        gex: number;
+        dex: number;
+    };
+    /**
+     * Single-pass net GEX + DEX at spot `S` under sticky-strike (IV/T/OI held fixed; gamma/delta
+     * re-evaluated). Backs both {@link atSpot} and {@link netGexAtSpot}: `blackScholesGreeks` returns gamma AND
+     * delta from one pass, so the DEX is a free ride on the gamma re-evaluation already needed for GEX.
+     */
+    private netExposureAtSpot;
+    /** Net signed GEX recomputed with spot shifted to `S` (gamma re-evaluated; IV/T/OI fixed). */
+    private netGexAtSpot;
+    /**
+     * Chart-ready by-strike profile (one row per strike, totals summed), narrowed to `metrics`. When
+     * `'gex'` is requested each row ALSO carries the call/put split — `callGex`/`putGex`/`callOpenInterest`/`putOpenInterest`
+     * (the {@link GexSplit} columns) — for the canonical dashboard chart (call bars up, put bars down).
+     * `callGex + putGex` equals the row's net `gex` and `callOpenInterest + putOpenInterest` the strike's total OI (WS4.5).
+     */
+    byStrike<M extends ExposureMetric = ExposureMetric>(metrics?: readonly M[]): StrikeRow<M>[];
+    /** Chart-ready by-expiry profile (one row per expiry), narrowed to `metrics`. */
+    byExpiry<M extends ExposureMetric = ExposureMetric>(metrics?: readonly M[]): ExpiryRow<M>[];
+    /** Dealer-positioning levels (walls, zero-gamma, max pain, pin risk). */
+    levels(options?: {
+        pinRiskBand?: number;
+    }): Levels;
+    /**
+     * The strike with the largest net gamma wall within `bucket`'s soonest matching expiry: signed GEX
+     * (calls + puts) is summed PER STRIKE across that expiry and the max-|sum| strike wins. "weekly" is
+     * the nearest Friday and "monthly" the nearest 3rd-Friday OPEX.
+     */
+    private opexWall;
+    /**
+     * Net dealer-hedging drift estimate (spec §11.5): the gamma regime (pinning vs trending), the
+     * zero-gamma attractor, and the aggregate charm/vanna hedging flows that push spot over time and as
+     * vol moves. An ESTIMATE from the positioning model — not a price forecast. An empty or
+     * identically-zero book has no gamma structure: `zeroGamma`/`distanceToZeroGamma`/`gammaRegime`/
+     * `bias` are all `null` (never fabricated), and the charm/vanna flows echo the (zero) aggregate.
+     */
+    netDrift(): NetDrift;
+    /**
+     * Zero-gamma (gamma flip) by scanning net GEX across the [0.8·spot, 1.2·spot] grid. Collects ALL
+     * sign-change roots (books can have several); `zeroGamma` is the one NEAREST spot, `gammaFlips` is
+     * the full sorted list. IV is held fixed per contract during the scan (sticky-strike, echoed in
+     * `assumptions.scanVolatilityPolicy`).
+     *
+     * Honesty guards (review finding): an EMPTY resolved book, or a profile that is identically zero
+     * across the whole scan, has no gamma structure — return nulls rather than fabricate a "flip" at
+     * every grid point (netGEX ≡ 0 made the old `prevG === 0` branch push all 81 of them, and an empty
+     * book reported `zeroGamma: spot`). A RUN of consecutive exact-zero grid points collapses to at
+     * most one flip (the run's first point).
+     */
+    private gammaProfileLevels;
+    /**
+     * Max-pain strike for the NEAREST expiry — the strike that minimizes total in-the-money value paid
+     * out to holders (max writer profit). Max pain is EXPIRY-SPECIFIC: settlement only nets contracts of
+     * the SAME expiration, so summing intrinsic value across unrelated expiries produces a meaningless
+     * number. We scope it to the soonest expiry present, mirroring the expiry-scoped OPEX walls.
+     */
+    private maxPain;
+    /** Pin risk: nearest high-gamma·OI strike to spot, flagged when spot is within `band` of it. */
+    private pinRisk;
+    /**
+     * Recompute aggregate metrics across a spot × volatilityShock × time grid. With no `metrics` the default
+     * set is `['gex','dex','vanna','charm']` — and the return type narrows to exactly those, so it never
+     * over-claims the metrics not actually computed (WS2.4).
+     */
+    scenarioMap<M extends ExposureMetric = DefaultScenarioMetric>(options?: ScenarioMapOptions<M>): ScenarioMap<M>;
+}
+export interface ExposureInput {
+    quotes: OptionQuote[];
+    market: ExposureMarket;
+    config: ExposureConfig;
+}
+/** Compute an exposure profile from an option chain. */
+export declare function exposure(input: ExposureInput): ExposureProfile;
+//# sourceMappingURL=exposure.d.ts.map

package/modules/structure/dist/exposure.d.ts.map

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