gloomberb 0.16.3 → 0.16.5

package/src/plugins/builtin/options-scenario/headless.ts

@@ -1,38 +1,67 @@
 import type { HeadlessPaneDefinition } from "../../../types/plugin";
 import { parsePublicTickerKey } from "../../../utils/exchanges";
+import {
+  expirationOptionSeconds, OPTION_EXPIRATION_FORMAT, OPTION_EXPIRATION_PLACEHOLDER, readOptionExpiration,
+} from "../../../utils/option-expiry";
 import { resolveHeadlessInstrument } from "../shared/headless-market-data";
 import {
   createScenarioDependencies, loadScenarioMarket, scenarioControlsFromSettings, scenarioPositionFromSettings,
   type ScenarioMarketSnapshot,
 } from "./client";
-import { buildScenario, parseLegs } from "./model";
+import { buildScenario, currencyLabel, parseLegs, scenarioValueUnit } from "./model";
+import { hedgeInputsFromSettings, hedgeReportEntries, scenarioHedgeBudget } from "./hedge";
 
 // Float noise at a flat origin or a breakeven prints as 0.00, not -0.00.
 const money = (value: unknown) => typeof value === "number" ? (Math.abs(value) < 0.005 ? 0 : value).toFixed(2) : "--";
+const percent = (value: unknown) => typeof value === "number" ? `${(value * 100).toFixed(2)}%` : "--";
 const supplied = (value: unknown) => value != null && value !== "";
+// A seeded entry is a quote midpoint, often to the half cent (5.495), so it keeps up to four decimals.
+const premium = (value: unknown) => typeof value === "number"
+  ? value.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 4, useGrouping: false }) : "--";
+/** Entry prices and spot are quoted per share of the underlying. */
+const PRICE_UNIT = "per share";
+/** The Valuation entries, in model order, with the unit each is in. */
+const VALUATION_LABELS: Record<string, (currency: string) => string> = {
+  price: () => "Value", pnl: () => "P&L", delta: () => "Delta (shares)", gamma: () => "Gamma (shares per 1.00 move)",
+  thetaPerDay: (currency) => `Theta (${currency} per day)`, vegaPerPoint: (currency) => `Vega (${currency} per vol point)`,
+  rhoPerPoint: (currency) => `Rho (${currency} per rate point)`,
+};
 
 export const optionsScenarioHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle", argument: { kind: "ticker", description: "Underlying ticker" },
+  usListingsOnly: "Options data",
   describe: (args) => `OSA ${args.symbols[0] ?? ""}`,
+  description: "A typed or chain-seeded options position valued across spot, date and volatility: its legs, value and Greeks, expiry risk and a "
+    + "scenario P&L grid. With --nav and --budget-bps, how many contracts a hedge budget buys, the premium spent, the notional protected and "
+    + "coverage of an equity sleeve.",
   discovery: { screenshotReadiness: "ready", limitations: ["European scenario values do not model early assignment or exercise."] },
   options: [
     { key: "tab", type: "enum", values: ["payoff", "grid", "legs"].map((value) => ({ value })), defaultValue: "payoff",
       description: "Initial view", pluginState: { pluginId: "ticker-research", key: "activeTabId" } },
-    { key: "legs", type: "string", description: "Semicolon-separated side,strike,YYYY-MM-DD,signed quantity,entry price,IV percent[,multiplier]" },
-    { key: "strategy", type: "enum", values: [{ value: "vertical" }, { value: "straddle" }], description: "Build an explicit example from current two-sided chain quotes" },
-    { key: "expiration", type: "integer", minimum: 1, description: "Chain expiration in Unix seconds" },
+    { key: "legs", type: "string", description: "Semicolon-separated side,strike,YYYY-MM-DD,signed quantity,entry price per share,IV percent[,multiplier]" },
+    { key: "strategy", type: "enum", values: [{ value: "vertical" }, { value: "straddle" }, { value: "put" }],
+      description: "Build a position from current two-sided chain quotes: a call vertical, a straddle, or one long put (a protective put)" },
+    { key: "strike", type: "string", description: "The --strategy strike: the put, the vertical's long call or the straddle. Nearest the money when omitted" },
+    { key: "expiration", type: "string", placeholder: OPTION_EXPIRATION_PLACEHOLDER, example: "--strategy vertical --expiration 2027-01-15",
+      description: `Chain expiry for --strategy, as ${OPTION_EXPIRATION_FORMAT}`, normalize: (value) => expirationOptionSeconds(value) },
     { key: "spot", type: "string", description: "Underlying price override, per share" },
     { key: "rate", type: "string", description: "Continuously compounded annual risk-free rate, percent" },
     { key: "dividendYield", aliases: ["dividend-yield"], type: "string", description: "Continuous annual dividend yield, percent" },
-    { key: "currency", type: "string", description: "Monetary unit for supplied inputs, such as USD" },
+    { key: "currency", type: "string", description: "Currency of the inputs, such as USD; the underlying's when omitted" },
     { key: "asOf", aliases: ["as-of"], type: "string", description: "Position valuation timestamp: UTC ISO or YYYY-MM-DD" },
     { key: "date", type: "string", description: "Scenario date: UTC ISO or YYYY-MM-DD" },
     { key: "volShift", aliases: ["vol-shift"], type: "string", defaultValue: "0", description: "Parallel volatility shift, percentage points" },
     { key: "spotRange", aliases: ["spot-range"], type: "string", defaultValue: "30", description: "Spot grid range above and below current spot, percent" },
+    { key: "nav", type: "string", description: "Portfolio NAV for a hedge budget, such as 100m, 2.5bn, 250k, 1,000,000 or $100m. Needs --budget-bps" },
+    { key: "budgetBps", aliases: ["budget-bps"], type: "string", example: "--strategy put --strike 700 --expiration 2027-01-15 --nav 100m --budget-bps 50",
+      description: "Hedge budget in basis points of --nav (50 is 0.5%): the report says how many of the position it buys, the premium, and the notional protected" },
+    { key: "sleeve", aliases: ["equity-sleeve"], type: "string", description: "Equity sleeve the hedge protects, for coverage = notional / sleeve. Same amount forms as --nav" },
   ],
   async load(args, ctx) {
     const symbol = args.symbols[0]!;
     const settings: Record<string, unknown> = { ...ctx.settings, ...args.options, symbol };
+    // Bad hedge inputs fail before any market request.
+    hedgeInputsFromSettings(settings);
     const suppliedInputs = !!settings.legs && ["spot", "rate", "dividendYield"].every((key) => settings[key] != null && settings[key] !== "");
     let market: ScenarioMarketSnapshot;
     if (suppliedInputs) {
@@ -42,8 +71,8 @@ export const optionsScenarioHeadless: HeadlessPaneDefinition<"bundle"> = {
     } else {
       const instrument = await resolveHeadlessInstrument(ctx, symbol);
       const typedExpiries = typeof settings.legs === "string" && settings.legs.trim() ? parseLegs(settings.legs).map((leg) => leg.expiration) : [];
-      market = await loadScenarioMarket({ instrument,
-        expiration: typeof args.options.expiration === "number" ? args.options.expiration : undefined,
+      const expiration = readOptionExpiration(args.options.expiration);
+      market = await loadScenarioMarket({ instrument, expiration: expiration ?? undefined,
         rateExpiration: typedExpiries.length ? Math.min(...typedExpiries) : undefined, signal: ctx.signal,
       }, createScenarioDependencies(ctx.marketData, ctx.apiClient));
     }
@@ -51,13 +80,21 @@ export const optionsScenarioHeadless: HeadlessPaneDefinition<"bundle"> = {
     const position = scenarioPositionFromSettings(settings, market);
     const controls = position ? scenarioControlsFromSettings(settings, position) : null;
     const scenario = position && controls ? buildScenario(position, controls) : null;
-    const errors = scenario ? [...new Set([...market.warnings, ...scenario.warnings])]
-      : [...market.warnings, "No position supplied; add --legs or select --strategy"];
+    const hedge = scenarioHedgeBudget(settings, position, market);
+    // A typed rate or yield stands in for the source that could not supply one.
+    const marketWarnings = market.warnings.filter((warning) => !(supplied(settings.dividendYield) && warning.startsWith("Dividend yield unavailable"))
+      && !(supplied(settings.rate) && warning.startsWith("Treasury")));
+    const errors = scenario ? [...new Set([...marketWarnings, ...scenario.warnings])]
+      : [...marketWarnings, "No position supplied; add --legs or select --strategy"];
     const midVolatility = !!position?.legs.some((leg) => leg.volatilitySource === "mid");
     // A seeded strategy starts at the spot its quote mids imply; the last print is reported beside it.
     const lastPrint = midVolatility && !supplied(settings.spot) && market.spot != null && money(market.spot) !== money(position!.spot)
       ? market.spot : null;
     const chain = market.chain;
+    const currency = position ? currencyLabel(position.currency) : null;
+    // Value, P&L, risk and the grid add every contract; entry prices and spot are per share.
+    const valueUnit = position ? scenarioValueUnit(position) : null;
+    const per = `${currency} ${valueUnit}`;
     return {
       freshness: suppliedInputs
         ? { source: "Your inputs", status: "not-a-feed", basis: "scenario" }
@@ -66,33 +103,44 @@ export const optionsScenarioHeadless: HeadlessPaneDefinition<"bundle"> = {
       sections: scenario ? [
         { title: "Position", columns: [
           { key: "side", header: "Side" }, { key: "strike", header: "Strike" }, { key: "expiry", header: "Expiry" },
-          { key: "quantity", header: "Quantity" }, { key: "price", header: "Entry", format: money },
+          { key: "quantity", header: "Contracts" }, { key: "price", header: "Entry/share", format: premium },
           { key: "volatility", header: "IV", format: (value) => typeof value === "number" ? `${(value * 100).toFixed(2)}%` : "--" },
           ...(midVolatility ? [{ key: "volatilityFrom", header: "IV from" }] : []),
           { key: "multiplier", header: "Multiplier" },
         ], rows: position!.legs.map((leg) => ({ ...leg, expiry: new Date(leg.expiration * 1000).toISOString().slice(0, 10),
           ...(midVolatility ? { volatilityFrom: leg.volatilitySource === "mid" ? "quote mid" : "provider" } : {}) })) },
-        ...(lastPrint != null ? [{ title: "Spot", entries: [
-          { key: "spot", label: "Implied by option quotes", value: position!.spot, formatted: money(position!.spot) },
-          { key: "last", label: "Last price", value: lastPrint, formatted: money(lastPrint) },
-        ] }] : []),
-        { title: "Valuation", entries: Object.entries(scenario.valuation).map(([key, value]) => ({ key, label: key, value, formatted: money(value) })) },
-        { title: "Expiry risk", entries: [
-          { label: "Breakevens", value: scenario.expiryRisk.breakevens },
-          { label: "Max profit", value: scenario.expiryRisk.maxProfit, formatted: scenario.expiryRisk.unlimitedProfit ? "Unlimited" : money(scenario.expiryRisk.maxProfit) },
-          { label: "Max loss", value: scenario.expiryRisk.maxLoss, formatted: scenario.expiryRisk.unlimitedLoss ? "Unlimited" : money(scenario.expiryRisk.maxLoss) },
-          ...(scenario.expiryRisk.reason ? [{ label: "Limitation", value: scenario.expiryRisk.reason }] : []),
+        { title: "Inputs", entries: [
+          { key: "spot", label: lastPrint != null ? "Spot implied by option quotes" : "Spot", value: position!.spot,
+            formatted: `${money(position!.spot)} ${PRICE_UNIT}` },
+          ...(lastPrint != null ? [{ key: "last", label: "Last price", value: lastPrint, formatted: `${money(lastPrint)} ${PRICE_UNIT}` }] : []),
+          { key: "rate", label: "Rate", value: position!.rate, formatted: percent(position!.rate) },
+          { key: "dividendYield", label: "Dividend yield", value: position!.dividendYield, formatted: percent(position!.dividendYield) },
+          { key: "currency", label: "Currency", value: position!.currency, formatted: currency! },
+        ] },
+        ...(hedge ? [{ title: "Hedge budget", entries: hedgeReportEntries(hedge) }] : []),
+        { title: `Valuation (${per})`, entries: Object.entries(scenario.valuation).map(([key, value]) => ({ key,
+          label: VALUATION_LABELS[key]?.(currency!) ?? key, value, formatted: money(value) })) },
+        { title: `Expiry risk (${per})`, entries: [
+          { key: "breakevens", label: "Breakevens (spot)", value: scenario.expiryRisk.breakevens,
+            formatted: scenario.expiryRisk.breakevens.map(money).join(", ") || "none" },
+          { key: "maxProfit", label: "Max profit", value: scenario.expiryRisk.maxProfit, formatted: scenario.expiryRisk.unlimitedProfit ? "Unlimited" : money(scenario.expiryRisk.maxProfit) },
+          { key: "maxLoss", label: "Max loss", value: scenario.expiryRisk.maxLoss, formatted: scenario.expiryRisk.unlimitedLoss ? "Unlimited" : money(scenario.expiryRisk.maxLoss) },
+          ...(scenario.expiryRisk.reason ? [{ key: "limitation", label: "Limitation", value: scenario.expiryRisk.reason }] : []),
         ] },
-        { title: "Scenario grid", columns: [
-          { key: "spot", header: "Spot" }, { key: "move", header: "Move", format: (value) => typeof value === "number" && Number.isFinite(value) ? `${(value * 100).toFixed(1)}%` : "--" },
+        { title: `Scenario grid (P&L, ${per})`, columns: [
+          { key: "spot", header: "Spot/share", format: money },
+          { key: "move", header: "Move", format: (value) => typeof value === "number" && Number.isFinite(value) ? `${(value * 100).toFixed(1)}%` : "--" },
           ...scenario.dates.map((date, index) => ({ key: `date${index}`, header: new Date(date).toISOString().slice(0, 10), format: money })),
         ], rows: scenario.grid.map((row) => ({ spot: row.spot, move: row.move,
           ...Object.fromEntries(row.values.map((value, index) => [`date${index}`, value])) })) },
       ] : [],
       complete: scenario != null && errors.length === 0,
       unavailableSymbols: scenario ? [] : [symbol], errors,
-      metadata: { scenario, position, controls, market, inputSource: suppliedInputs ? "user" : "market",
-        unit: position?.currency || "currency unspecified", methodology: "docs/research-data.md#options-scenario-analysis" },
+      metadata: { scenario, position, controls, market, ...(hedge ? { hedge } : {}), inputSource: suppliedInputs ? "user" : "market",
+        unit: position?.currency || "currency unspecified",
+        // Leg entry prices and spot are per share; value, P&L, risk, Greeks in currency and the grid are for valueUnit.
+        ...(position ? { units: { currency: position.currency, price: PRICE_UNIT, value: valueUnit } } : {}),
+        methodology: "docs/research-data.md#options-scenario-analysis" },
     };
   },
 };

package/src/plugins/builtin/options-scenario/hedge.ts

@@ -0,0 +1,285 @@
+import type { StatItem } from "../../../components";
+import type { OptionsChain } from "../../../types/financials";
+import type { HeadlessPaneEntry } from "../../../types/headless";
+import { numberErrorMessage } from "../../../utils/decimal-comma";
+import { formatCompact } from "../../../utils/format";
+import { UNKNOWN_CURRENCY, type ScenarioPosition } from "./model";
+
+/**
+ * Hedge budget sizing (docs/research-data.md#options-scenario-analysis): how
+ * many of the position as entered a budget of NAV buys, what that spends, and
+ * how much of the underlying it protects.
+ *
+ * The position is scaled as a whole, in sets of its smallest whole ratio (a
+ * put, a 1x1 spread, a 2x1 ratio), so the hedge keeps its shape. A set costs
+ * its net debit: each leg's price times its signed contracts and multiplier.
+ * The price is the entry price as entered, except for a leg a strategy seed
+ * entered at its contract's midpoint (`priceSource: "mid"`, its id the
+ * contract's symbol in the loaded chain), which buys at the ask and sells at
+ * the bid, so a seeded hedge never spends past its budget.
+ * The protecting legs are the long puts, or the long calls when the position
+ * holds no long put; notional protected is their contracts times multiplier
+ * times spot.
+ */
+export interface HedgeBudgetInputs {
+  /** Portfolio NAV, in the position's currency. */
+  nav: number;
+  /** The budget as basis points of NAV: 50 is 0.5%. */
+  budgetBps: number;
+  /** The equity sleeve the hedge protects; coverage is notional over it. */
+  sleeve: number | null;
+}
+
+/** How the set was priced: the legs as entered, chain quotes (long at the ask, short at the bid), or some of each. */
+type HedgePriceBasis = "entry" | "quote" | "mixed";
+
+export interface HedgeBudget extends HedgeBudgetInputs {
+  currency: string;
+  /** NAV times budget bps. */
+  budget: number;
+  basis: HedgePriceBasis;
+  /** True for a single long leg: the price is that leg's own, not a net debit. */
+  singleLeg: boolean;
+  /** Per underlying unit of one protecting contract; null when the legs' multipliers differ. */
+  sizingPrice: number | null;
+  /** What one protecting contract costs, all legs of its set included. */
+  costPerContract: number;
+  /** Units of the underlying one protecting contract covers. */
+  multiplier: number;
+  /** Protecting contracts bought: whole sets, rounded down, times the protecting contracts in a set. */
+  contracts: number;
+  /** Premium spent: whole sets times what a set costs. */
+  premium: number;
+  /** Premium over NAV in basis points: what the budget actually spends. */
+  premiumBps: number;
+  /** The underlying price notional is read at. */
+  spot: number;
+  /** Protecting contracts times multiplier times spot. */
+  notional: number;
+  /** Notional over NAV, as a fraction. */
+  notionalOfNav: number;
+  /** Notional over the sleeve, as a fraction; null without a sleeve. */
+  coverage: number | null;
+}
+
+const supplied = (value: unknown) => value != null && value !== "";
+
+const AMOUNT_SCALES: Record<string, number> = { k: 1e3, m: 1e6, mm: 1e6, mn: 1e6, b: 1e9, bn: 1e9, t: 1e12, tn: 1e12 };
+const AMOUNT = /^\$?\s*(\d{1,3}(?:,\d{3})+|\d+)(\.\d+)?\s*([a-z]{1,2})?$/i;
+const AMOUNT_FORMS = "such as 100m, 2.5bn, 250k, 1,000,000 or $100m";
+
+/** `100m`, `2.5bn`, `250k`, `1,000,000` and `$100m` as a positive amount; anything else names the flag and the forms. */
+export function parseHedgeAmount(value: unknown, flag: string): number {
+  const text = typeof value === "number" ? String(value) : typeof value === "string" ? value.trim() : "";
+  if (/^-/.test(text)) throw new Error(`--${flag} must be greater than zero.`);
+  const match = AMOUNT.exec(text);
+  const scale = match ? match[3] ? AMOUNT_SCALES[match[3].toLowerCase()] : 1 : undefined;
+  const amount = match && scale ? Number(`${match[1]!.replaceAll(",", "")}${match[2] ?? ""}`) * scale : Number.NaN;
+  if (!Number.isFinite(amount)) throw new Error(`--${flag} must be an amount ${AMOUNT_FORMS}; got "${text}".`);
+  if (!(amount > 0)) throw new Error(`--${flag} must be greater than zero.`);
+  return amount;
+}
+
+function parseBudgetBps(value: unknown): number {
+  const text = typeof value === "number" ? String(value) : typeof value === "string" ? value.trim() : "";
+  const bps = /^-?(?:\d+(?:\.\d+)?|\.\d+)$/.test(text) ? Number(text) : Number.NaN;
+  if (!Number.isFinite(bps)) throw new Error(numberErrorMessage(`--budget-bps must be a number of basis points, such as 50 for 0.5% of NAV; got "${text}".`, text));
+  if (!(bps > 0)) throw new Error("--budget-bps must be greater than zero.");
+  if (bps > 10_000) throw new Error("--budget-bps must be at most 10,000 (all of NAV).");
+  return bps;
+}
+
+/**
+ * `--nav`, `--budget-bps` and `--sleeve` as pane settings or report options.
+ * Null when none is set; each needs the others it depends on.
+ */
+export function hedgeInputsFromSettings(settings: Record<string, unknown>): HedgeBudgetInputs | null {
+  const hasNav = supplied(settings.nav);
+  const hasBudget = supplied(settings.budgetBps);
+  const hasSleeve = supplied(settings.sleeve);
+  if (!hasNav && !hasBudget) {
+    if (hasSleeve) throw new Error("--sleeve needs --nav and --budget-bps: coverage is the notional a hedge budget buys over the sleeve.");
+    return null;
+  }
+  if (!hasBudget) throw new Error("--nav needs --budget-bps: the share of NAV to spend, in basis points (50 is 0.5%).");
+  if (!hasNav) throw new Error("--budget-bps needs --nav: the portfolio value the budget is a share of, such as 100m.");
+  return { nav: parseHedgeAmount(settings.nav, "nav"), budgetBps: parseBudgetBps(settings.budgetBps),
+    sleeve: hasSleeve ? parseHedgeAmount(settings.sleeve, "sleeve") : null };
+}
+
+function gcd(left: number, right: number): number {
+  return right === 0 ? left : gcd(right, left % right);
+}
+
+/** Float noise off a cent-quoted premium times a multiplier, so 5.495 x 100 is 549.5. */
+const clean = (value: number) => Math.round(value * 1e6) / 1e6;
+
+export interface HedgeQuote { bid: number; ask: number }
+
+/**
+ * The bid and ask of each leg a strategy seeded from the chain, by leg id: the
+ * chain's, or the leg's streamed quote when the pane follows the market.
+ */
+function hedgeLegQuotes(
+  position: ScenarioPosition, chain: OptionsChain | null | undefined, liveQuotes?: ReadonlyMap<string, HedgeQuote>,
+): Map<string, HedgeQuote> {
+  const contracts = new Map([...(chain?.calls ?? []), ...(chain?.puts ?? [])].map((contract) => [contract.contractSymbol, contract]));
+  const quotes = new Map<string, HedgeQuote>();
+  for (const leg of position.legs) {
+    const contract = leg.priceSource === "mid" ? contracts.get(leg.id) : undefined;
+    if (contract && contract.strike === leg.strike && contract.expiration === leg.expiration
+      && contract.bid > 0 && contract.ask >= contract.bid && Number.isFinite(contract.ask)) {
+      const live = liveQuotes?.get(leg.id);
+      quotes.set(leg.id, live && live.bid > 0 && live.ask >= live.bid ? live : { bid: contract.bid, ask: contract.ask });
+    }
+  }
+  return quotes;
+}
+
+/**
+ * The underlying price notional is read at: the last price when the scenario
+ * starts at a spot the option quotes imply (a seeded strategy) and no spot was
+ * typed, otherwise the scenario's own spot.
+ */
+function hedgeSpot(position: ScenarioPosition, marketSpot: number | null | undefined, spotTyped: boolean): number {
+  const quoteImplied = position.legs.some((leg) => leg.volatilitySource === "mid");
+  return quoteImplied && !spotTyped && marketSpot != null && Number.isFinite(marketSpot) && marketSpot > 0 ? marketSpot : position.spot;
+}
+
+const money = (value: number) => value.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+
+export function sizeHedgeBudget(
+  position: ScenarioPosition,
+  inputs: HedgeBudgetInputs,
+  { quotes = new Map(), spot = position.spot }: { quotes?: ReadonlyMap<string, HedgeQuote>; spot?: number } = {},
+): HedgeBudget {
+  const longs = position.legs.filter((leg) => leg.quantity > 0);
+  if (!longs.length) throw new Error("A hedge budget buys options; this position has no long option.");
+  const step = position.legs.reduce((divisor, leg) => gcd(divisor, Math.abs(leg.quantity)), 0);
+  const protecting = longs.some((leg) => leg.side === "put") ? longs.filter((leg) => leg.side === "put") : longs;
+  const priced = position.legs.map((leg) => {
+    const quote = quotes.get(leg.id);
+    return { leg, quoted: !!quote, price: quote ? leg.quantity > 0 ? quote.ask : quote.bid : leg.price };
+  });
+  const quotedCount = priced.filter((entry) => entry.quoted).length;
+  const basis: HedgePriceBasis = quotedCount === 0 ? "entry" : quotedCount === priced.length ? "quote" : "mixed";
+  const setCost = clean(priced.reduce((sum, { leg, price }) => sum + price * leg.quantity / step * leg.multiplier, 0));
+  const currency = position.currency === UNKNOWN_CURRENCY ? "" : ` ${position.currency}`;
+  if (!(setCost > 0)) {
+    throw new Error(setCost < 0
+      ? `This position takes in a net credit of ${money(-setCost)}${currency} per set, so a budget does not size it; a hedge budget buys a net debit.`
+      : "This position costs nothing at these prices, so a budget does not size it.");
+  }
+  const contractsPerSet = protecting.reduce((sum, leg) => sum + leg.quantity / step, 0);
+  const unitsPerSet = protecting.reduce((sum, leg) => sum + leg.quantity / step * leg.multiplier, 0);
+  const multipliers = new Set(position.legs.map((leg) => leg.multiplier));
+  const multiplier = unitsPerSet / contractsPerSet;
+  const costPerContract = setCost / contractsPerSet;
+  const sizingPrice = multipliers.size === 1 ? clean(costPerContract / multiplier) : null;
+  const budget = clean(inputs.nav * inputs.budgetBps / 10_000);
+  // A budget that is an exact multiple of the set's cost buys that many sets, despite float division.
+  const sets = Math.floor(budget / setCost * (1 + 1e-12));
+  if (sets < 1) {
+    const single = position.legs.length === 1 && contractsPerSet === 1;
+    const at = single && sizingPrice != null ? ` at ${describePrice(basis, true, sizingPrice)}` : "";
+    throw new Error(`A ${formatBps(inputs.budgetBps)} budget of ${money(inputs.nav)}${currency} NAV is ${money(budget)}${currency}; `
+      + `one ${single ? "contract" : "set of the position"} costs ${money(setCost)}${currency}${at}.`);
+  }
+  const contracts = sets * contractsPerSet;
+  const premium = clean(sets * setCost);
+  const notional = sets * unitsPerSet * spot;
+  return { ...inputs, currency: position.currency, budget, basis, singleLeg: position.legs.length === 1, sizingPrice,
+    costPerContract, multiplier, contracts, premium, premiumBps: premium / inputs.nav * 10_000, spot, notional,
+    notionalOfNav: notional / inputs.nav, coverage: inputs.sleeve == null ? null : notional / inputs.sleeve };
+}
+
+/**
+ * Hedge sizing for a scenario, read the same way by the report and the pane:
+ * null without `--nav` and `--budget-bps`; throws on a bad input or a
+ * position a budget cannot size.
+ */
+export function scenarioHedgeBudget(
+  settings: Record<string, unknown>,
+  position: ScenarioPosition | null,
+  market: { chain?: OptionsChain | null; spot?: number | null; liveQuotes?: ReadonlyMap<string, HedgeQuote> } | null | undefined,
+): HedgeBudget | null {
+  const inputs = hedgeInputsFromSettings(settings);
+  if (!inputs) return null;
+  if (!position?.legs.length) throw new Error("A hedge budget needs a position; add --legs or select --strategy.");
+  return sizeHedgeBudget(position, inputs, { quotes: hedgeLegQuotes(position, market?.chain, market?.liveQuotes),
+    spot: hedgeSpot(position, market?.spot, supplied(settings.spot)) });
+}
+
+/** `50 bps`, `12.5 bps`. */
+function formatBps(value: number): string {
+  return `${Number(value.toFixed(2))} bps`;
+}
+
+/** A per-unit premium with the decimals it was quoted to: 5.51, 5.495. */
+export function formatHedgePrice(value: number): string {
+  return value.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 4 });
+}
+
+/** The price a budget is sized at, and where it came from: `5.51 per share, the ask`, `2.30 per share net debit at entry prices`. */
+function describePrice(basis: HedgePriceBasis, singleLeg: boolean, price: number): string {
+  const value = `${formatHedgePrice(price)} per share`;
+  if (singleLeg) return basis === "quote" ? `${value}, the ask` : `${value}, the entry price`;
+  return basis === "quote" ? `${value} net debit: long legs at the ask, short at the bid`
+    : basis === "mixed" ? `${value} net debit: quoted legs at the ask or bid, the rest at entry`
+      : `${value} net debit at entry prices`;
+}
+
+/** The price basis in a word or two, for a figure's detail: `ask 5.51`, `entry 5.495`, `net debit 2.30`. */
+function shortPrice(hedge: HedgeBudget): string {
+  if (hedge.sizingPrice == null) return `${money(hedge.costPerContract)} each`;
+  const word = !hedge.singleLeg ? "net debit" : hedge.basis === "quote" ? "ask" : "entry";
+  return `${word} ${formatHedgePrice(hedge.sizingPrice)}`;
+}
+
+const percent = (fraction: number) => `${(fraction * 100).toFixed(1)}%`;
+
+/** `551.00 USD (5.51 x 100)`: what one protecting contract costs, and the price behind it. */
+function costText(cost: number, sizingPrice: number | null, multiplier: number, unit: string): string {
+  return `${money(cost)}${unit}${sizingPrice == null ? "" : ` (${formatHedgePrice(sizingPrice)} x ${multiplier})`}`;
+}
+
+/** The report's Hedge budget section; `value` keeps full precision, `formatted` is what text output prints. */
+export function hedgeReportEntries(hedge: HedgeBudget): HeadlessPaneEntry[] {
+  const unit = hedge.currency && hedge.currency !== UNKNOWN_CURRENCY ? ` ${hedge.currency}` : "";
+  return [
+    { key: "nav", label: "NAV", value: hedge.nav, formatted: `${money(hedge.nav)}${unit}` },
+    { key: "budget", label: "Budget", value: hedge.budget, formatted: `${money(hedge.budget)}${unit} (${formatBps(hedge.budgetBps)} of NAV)` },
+    { key: "sizingPrice", label: "Sizing price", value: hedge.sizingPrice,
+      formatted: hedge.sizingPrice == null ? "--" : describePrice(hedge.basis, hedge.singleLeg, hedge.sizingPrice) },
+    { key: "costPerContract", label: "Cost per contract", value: hedge.costPerContract, formatted: costText(hedge.costPerContract, hedge.sizingPrice, hedge.multiplier, unit) },
+    { key: "contracts", label: "Contracts", value: hedge.contracts, formatted: hedge.contracts.toLocaleString("en-US") },
+    { key: "premium", label: "Premium spent", value: hedge.premium, formatted: `${money(hedge.premium)}${unit}` },
+    { key: "premiumBps", label: "Premium / NAV", value: hedge.premiumBps, formatted: `${formatBps(hedge.premiumBps)} (${(hedge.premiumBps / 100).toFixed(2)}% of NAV)` },
+    { key: "notional", label: "Notional protected", value: hedge.notional,
+      formatted: `${money(hedge.notional)}${unit} (${hedge.contracts.toLocaleString("en-US")} x ${hedge.multiplier} x ${formatHedgePrice(hedge.spot)})` },
+    { key: "notionalOfNav", label: "Notional / NAV", value: hedge.notionalOfNav, formatted: percent(hedge.notionalOfNav) },
+    hedge.coverage == null || hedge.sleeve == null
+      ? { key: "coverage", label: "Coverage", value: null, formatted: "No equity sleeve given; add --sleeve <amount> to read notional against it" }
+      : { key: "coverage", label: "Coverage", value: hedge.coverage, formatted: `${percent(hedge.coverage)} of a ${money(hedge.sleeve)}${unit} sleeve` },
+  ];
+}
+
+/** `100M`, `70.62M`: an amount short enough for a figure. */
+const short = (value: number) => formatCompact(value);
+
+/**
+ * The pane's Hedge budget figures: the same numbers as the report, sized for a
+ * StatGrid. The currency is the P&L figure's, so it is not repeated here.
+ */
+export function hedgeStatItems(hedge: HedgeBudget): StatItem[] {
+  return [
+    { id: "hedge-budget", label: "Hedge budget", value: money(hedge.budget), detail: `${formatBps(hedge.budgetBps)} of ${short(hedge.nav)}` },
+    { id: "hedge-contracts", label: "Contracts", value: hedge.contracts.toLocaleString("en-US"), detail: shortPrice(hedge) },
+    { id: "hedge-premium", label: "Premium", value: money(hedge.premium), detail: `${formatBps(hedge.premiumBps)} of NAV` },
+    { id: "hedge-notional", label: "Notional", value: short(hedge.notional),
+      detail: `${percent(hedge.notionalOfNav)} of NAV at ${formatHedgePrice(hedge.spot)}` },
+    hedge.coverage == null || hedge.sleeve == null
+      ? { id: "hedge-coverage", label: "Coverage", value: "--", detail: "no sleeve set" }
+      : { id: "hedge-coverage", label: "Coverage", value: percent(hedge.coverage), detail: `of ${short(hedge.sleeve)} sleeve` },
+  ];
+}

package/src/plugins/builtin/options-scenario/index.tsx

@@ -3,7 +3,8 @@ import { createTickerSurfacePaneTemplate } from "../shared/ticker-surface";
 import { OptionsScenarioPane } from "./pane";
 import { optionsScenarioHeadless } from "./headless";
 
-const scenarioSettingKeys = ["legs", "strategy", "expiration", "spot", "rate", "dividendYield", "currency", "asOf", "date", "volShift", "spotRange", "seedLeg"];
+const scenarioSettingKeys = ["legs", "strategy", "strike", "expiration", "spot", "rate", "dividendYield", "currency", "asOf", "date", "volShift",
+  "spotRange", "seedLeg", "nav", "budgetBps", "sleeve"];
 
 export const optionsScenarioModule: PluginModule = {
   panes: [{
@@ -14,13 +15,19 @@ export const optionsScenarioModule: PluginModule = {
       title: "Options Scenario Settings",
       fields: [
         { key: "spotRange", label: "Spot grid range (%)", type: "text" },
+        { key: "nav", label: "Hedge NAV", type: "text", placeholder: "100m",
+          description: "Portfolio NAV a hedge budget is a share of, such as 100m, 2.5bn or 1,000,000. Set with a budget to size the position." },
+        { key: "budgetBps", label: "Hedge budget (bps)", type: "text", placeholder: "50",
+          description: "Share of NAV to spend on the position, in basis points: 50 is 0.5%." },
+        { key: "sleeve", label: "Equity sleeve", type: "text", placeholder: "100m",
+          description: "The equity the hedge protects, for coverage: notional protected over the sleeve." },
       ],
     },
   }],
   paneTemplates: [createTickerSurfacePaneTemplate({
     id: "options-scenario-pane", paneId: "options-scenario", label: "Options Scenario",
     description: "Build multi-leg positions and compare scenario P&L, payoff and aggregate Greeks.",
-    keywords: ["osa", "options", "scenario", "payoff", "strategy", "greeks"],
+    keywords: ["osa", "options", "scenario", "payoff", "strategy", "greeks", "hedge", "hedging", "collar", "protective put", "put spread"],
     shortcut: "OSA", publicShare: true,
     settings: (symbol, _context, options) => ({ symbol, ...Object.fromEntries(scenarioSettingKeys
       .filter((key) => options?.values?.[key] != null).map((key) => [key, options!.values![key]])) }),

package/src/plugins/builtin/options-scenario/model.ts

@@ -1,5 +1,6 @@
 import { daysToExpiryFrom, valueOption, type OptionValuation } from "../shared/volatility";
 import { isFiniteNumber } from "../../../utils/guards";
+import { isUsListingExchange } from "../../../utils/exchanges";
 
 const DAY_MS = 86_400_000;
 const MAX_DATE_MS = Date.UTC(9999, 11, 31);
@@ -19,6 +20,12 @@ export interface ScenarioLeg {
   volatility: number;
   /** "mid" when the IV was solved from the quote midpoint rather than taken from the provider. */
   volatilitySource?: "mid";
+  /**
+   * "mid" when a strategy seed entered the leg at the midpoint of the chain
+   * contract its id names; a hedge budget then buys it at the ask. Saving the
+   * leg from the editor drops it: the price is then as typed.
+   */
+  priceSource?: "mid";
   multiplier: number;
 }
 
@@ -129,6 +136,32 @@ export function validateScenarioInputs(position: ScenarioPosition): string | nul
   return null;
 }
 
+/** The stored stand-in for a currency nothing names; shown as `currency unknown`. */
+export const UNKNOWN_CURRENCY = "UNKNOWN";
+export const currencyLabel = (currency: string) => currency === UNKNOWN_CURRENCY ? "currency unknown" : currency;
+
+/**
+ * The position's currency: the one typed, else the underlying's quote
+ * currency, else USD for a US listing (a bare symbol is one, as Gloom Cloud
+ * lists only US options). A listing abroad with no quote stays unknown.
+ */
+export function scenarioCurrency(typed: unknown, quoted: string | null | undefined, exchange: string | undefined): string {
+  const explicit = typed == null ? "" : String(typed).trim().toUpperCase();
+  if (explicit) return explicit;
+  if (quoted?.trim()) return quoted.trim().toUpperCase();
+  return !exchange || isUsListingExchange(exchange) ? "USD" : UNKNOWN_CURRENCY;
+}
+
+/**
+ * What the position's money figures (value, P&L, risk, Greeks in currency) are
+ * for: they add every contract times its multiplier, while entry prices and
+ * spot are per share. One contract reads `per contract`.
+ */
+export function scenarioValueUnit(position: Pick<ScenarioPosition, "legs">): string {
+  const contracts = position.legs.reduce((sum, leg) => sum + Math.abs(leg.quantity), 0);
+  return contracts === 1 ? "per contract" : `for ${contracts.toLocaleString("en-US")} contracts`;
+}
+
 /** Also validates restored persistence values at the model boundary. */
 export function validatePosition(position: ScenarioPosition): string | null {
   return validateScenarioInputs(position) ?? (position.legs.length ? null : "Add at least one option leg.");