# Concepts

For per-endpoint fields see [api.md](api.md); for index and futures pricing see
the repository document `futures-and-index-methodology.md`.

## Gamma regime vs net GEX

`net_gex` measures aggregate exposure at the current underlying price. `gamma_flip`
is an underlying-price boundary computed by repricing the option book. `regime`
compares the current price with that published boundary when its side is certified.

| Field | Definition |
|-------|------------|
| `net_gex` | Sum of convention-signed gamma exposure across the selected chain at the current price. |
| `gamma_flip` | Negative-to-positive zero crossing of aggregate repriced GEX as the underlying price changes. Nullable. Certified when `gamma_flip_status` is `available`; otherwise an unverified level. |
| `gamma_flip_status` | `available` when the level is certified. A numeric `gamma_flip` with any of `sensitive_root`, `uncertain_root_path`, `quality_budget`, `uncertain_gamma_variance`, `insufficient_local_coverage` or `insufficient_quote_quality` is an **unverified level**: the root exists but failed that publication gate, and `regime` is `unknown`. Any other status means no supportable root and `gamma_flip` is null. |
| `regime` | `positive_gamma` when `spot >= gamma_flip`, `negative_gamma` below it, and `unknown` when the level is unverified, absent, or its stressed side at spot is uncertain. Only certified levels drive the regime. |

The regime label is computed from spot and flip, not directly from the sign of
`net_gex`. The boundary search nevertheless reconciles the repriced book with the
stored spot-GEX sign and selects the boundary of spot's current sign region.
For a published level on the same chain and price anchor, the two should therefore
agree on the side, apart from numerical behavior at zero. A historical example
from the former strike-profile method is not evidence that conflicting signs are
expected under this method.

Compare chain scope, price anchor and timestamp before comparing fields. In
particular, a 0DTE-only chain can have a different regime from the full chain, and
live effective OI can differ from settled OI.

## Gamma flip determination

Convention gamma flips solve `GEX(S) = 0` by repricing each retained contract's
Black-Scholes gamma at candidate underlying prices. The contract's total implied
volatility is inferred from its stored gamma at the current price; the smaller
fitting solution is a model convention, not a uniquely observed volatility.

The calculation seeks a supported upward crossing within 8% of spot: below spot
for positive spot GEX, above spot for negative spot GEX. It checks reconciliation,
root support and materiality, local priced coverage, quote quality where required,
and sensitivity before publishing. Failure to resolve or support a boundary
produces `gamma_flip: null`, with a reason in `gamma_flip_status`. It does not
substitute a strike-profile crossing or a zero price.

The September 11 policy first certifies stressed roots within
**[root - 0.001 * spot, root + 0.001 * spot]**, then tries
**[root - 0.0025 * spot, root + 0.0025 * spot]** if needed, within the same total
work budget. These are windows around the root, not restrictions on its distance
from spot. For spot 100 and root 105, the strict window is [104.9, 105.1]. An
exhausted strict budget prevents a retry; if a retry fails, the strict failure
reason is retained. The successful tolerance determines the coverage shoulder
on the spot-to-root path, including the wider window when fallback is used.

Publication gates do not hide the root. When coverage, expiry-day quote quality or the stress
certificate fails, `gamma_flip` still carries the numeric root and `gamma_flip_status` names the
failing gate: an unverified level. Its `regime` is `unknown`, so regime-conditioned scores and
setups stay off. Only the absence of a supportable root (`no_boundary`, `stored_sign_mismatch`,
`immaterial_root`, `weak_shoulders`, `unresolved_search`, and the data-integrity statuses) leaves
`gamma_flip` null.

Level availability and regime certainty are separate. If spot lies inside the
successful window, the level remains available even when the stressed sign at
spot cannot be certified. The response carries `gamma_flip_status: available`
and `regime: unknown`; a numeric `gamma_flip` with `regime: unknown` therefore
means spot sits at the flip. This includes an exact upward root at spot. A known
regime requires a certified side; the sign check can also fail on insufficient
remaining certificate budget. A missing level has `regime: unknown` with its
specific withholding reason in `gamma_flip_status`.

The underlying root calculation, expiry-day quote checks, raw -25%/+25% gamma
stresses and additional feasible peak-capped +25% scenario are unchanged. This is
a discrete sensitivity test, not a probability guarantee or a guarantee for
intermediate gamma values, simultaneous strike changes, or future snapshots.

Availability figures in the September 9 validation reports describe the prior
0.1% policy; they are not publication rates for this relaxed policy.

Examples of withholding reasons include `invalid_gamma`, `no_priced_exposure`,
`stored_sign_mismatch`, `no_boundary`, `insufficient_local_coverage`,
`insufficient_quote_quality`, `sensitive_root`, `uncertain_root_path`,
`search_budget` and `quality_budget`. Clients should handle additional reason
strings as unavailable. `available` describes the current calculation; it does
not promise that the next snapshot or a changed option book will publish a level.
The status field is additive; older persisted payloads can omit it.

**Flow-polarity exception:** requests using `polarity=flow` on flow levels/GEX/live
retain a crossing of the dealer-position-signed **per-strike profile**. That is a
different metric from the convention repriced zero-gamma boundary. Do not apply
the convention certificate or its status contract to that profile result.

## Missing gamma data

`unknown` is not a positive or negative regime. Gamma-dependent VRP outputs become
null when the flip is unavailable: GEX/vanna-conditioned blocks, VRP regime,
short-put-spread/short-strangle/iron-condor scores, and net harvest score.
Independent IV/RV/VRP values and calendar-spread scoring remain usable when their
own inputs exist. Earnings scoring applies no gamma adjustment in this case.

Gamma-dependent iron-fly and iron-condor setups in the 0DTE flow snapshot are
unavailable while the regime is unknown; the setup catalog can return `wait`.
For alerts targeting a known gamma regime, an unknown evaluation neither fires
nor clears an existing match. Recovery to the same known regime does not manufacture a new
edge. A definite false condition still resets the match; a definite true branch
of an OR condition can still fire. Custom comparisons explicitly targeting
`unknown` use normal alert edges, allowing data-availability alerts. Ordinary
numeric `gamma_flip` filters retain their existing null semantics.

## Definition by endpoint

| Endpoint | Regime basis |
|----------|-------------|
| `/v1/exposure/summary/{symbol}`, `/v1/stock/{symbol}/summary`, `/v1/exposure/narrative/{symbol}` | Spot versus the published full-chain flip; `unknown` when withheld. |
| `/v1/exposure/zero-dte/{symbol}` | Spot versus the published 0DTE-only flip; `unknown` when withheld. |
| `/v1/flow/zero-dte/snapshot/{symbol}` | Same 0DTE calculation using live effective OI, under `body.regime`. |
| `/v1/exposure/basket` | Sign of constituent `net_gex`: nonnegative means `positive_gamma`. No flip is required. |
| `/v1/strategies/dealer-regime/{symbol}` | Sign of chain-wide net dealer gamma; distinct labels `positive_gamma_compression`, `negative_gamma_acceleration`, and `transition`. |