gloomberb 0.16.3 → 0.16.4

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

@@ -0,0 +1,284 @@
+import type { StatItem } from "../../../components";
+import type { OptionsChain } from "../../../types/financials";
+import type { HeadlessPaneEntry } from "../../../types/headless";
+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(`--budget-bps must be a number of basis points, such as 50 for 0.5% of NAV; got "${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.");

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

@@ -21,10 +21,14 @@ import { buildOptionQuoteKey, freshOptionQuote, OPTIONS_QUOTE_EXCHANGE } from ".
 import { liveScenarioPosition, scenarioLegContractSymbol } from "./live";
 import { ScenarioPayoffChart } from "./charts";
 import { ScenarioLegEditor, ScenarioSaveForm, ScenarioInputsForm } from "./editor";
-import { loadScenarioMarket, scenarioPositionFromSettings, scenarioControlsFromSettings, type ScenarioMarketSnapshot } from "./client";
-import { buildScenario, type ScenarioLeg, type ScenarioPosition, type ScenarioControls, validatePosition } from "./model";
+import { loadScenarioMarket, scenarioControlsFromSettings, scenarioPositionFromSettings, type ScenarioMarketSnapshot } from "./client";
+import { buildScenario, currencyLabel, scenarioCurrency, scenarioValueUnit, UNKNOWN_CURRENCY, type ScenarioLeg, type ScenarioPosition,
+  type ScenarioControls, validatePosition } from "./model";
 import { EMPTY_SAVED_STRATEGIES, restoreSavedStrategies, type SavedScenarioStrategy } from "./state";
 import { useScenarioEvidence } from "./evidence";
+import { hedgeStatItems, scenarioHedgeBudget, type HedgeQuote } from "./hedge";
+import { readOptionExpiration } from "../../../utils/option-expiry";
+import { parsePublicTickerKey } from "../../../utils/exchanges";
 
 const EMPTY_ERRORS: string[] = [];
 const TABS = [{ value: "payoff", label: "Payoff" }, { value: "grid", label: "P&L grid" }, { value: "legs", label: "Legs" }];
@@ -44,9 +48,12 @@ export function OptionsScenarioPane({ width, height, focused }: PaneProps) {
   const [snapshotErrors] = usePaneSettingValue<string[]>("scenarioSnapshotErrors", EMPTY_ERRORS);
   const [frozenMarket] = usePaneSettingValue<ScenarioMarketSnapshot | null>("scenarioMarketSnapshot", null);
   const target = resolveOptionsTarget(ticker);
-  const underlying = target?.effectiveTicker ?? symbol ?? String(settings.symbol ?? "");
-  const exchange = target?.effectiveExchange || undefined;
-  const [expiration, setExpiration] = usePluginPaneState<number | null>("chainExpiration", null);
+  // A listing is keyed "SPY:ARCX", both in the pane's binding and in the ticker record opened under it: split either.
+  const listed = parsePublicTickerKey(target?.effectiveTicker ?? symbol ?? String(settings.symbol ?? ""));
+  const underlying = listed.symbol;
+  const exchange = listed.exchange || target?.effectiveExchange || undefined;
+  // A strategy seeded for an expiry (`OSA SPY --strategy put --expiration 2027-01-15`) opens that expiry's chain.
+  const [expiration, setExpiration] = usePluginPaneState<number | null>("chainExpiration", readOptionExpiration(settings.expiration));
   const [tab, setTab] = usePluginPaneState("activeTabId", "payoff");
   const [detail, setDetail] = useState<"chain" | "leg" | "save" | "inputs" | null>(null);
   const [editingLeg, setEditingLeg] = useState<ScenarioLeg | null>(null);
@@ -62,9 +69,9 @@ export function OptionsScenarioPane({ width, height, focused }: PaneProps) {
   const loadMarket = useCallback(async (force: boolean) => {
     controller.current?.abort();
     const abort = new AbortController(); controller.current = abort;
-    return loadScenarioMarket({ instrument: { symbol: underlying, exchange: target?.effectiveExchange },
+    return loadScenarioMarket({ instrument: { symbol: underlying, exchange },
       expiration: expiration ?? undefined, forceRefresh: force, signal: abort.signal });
-  }, [underlying, target?.effectiveExchange, expiration]);
+  }, [underlying, exchange, expiration]);
   // Fully specified calculations and screenshot snapshots never need a quote refresh.
   const needsMarket = !frozen && (!["spot", "rate", "dividendYield"].every((key) => settings[key] != null && settings[key] !== "") || detail === "chain");
   const resource = useAsyncResource(underlying && needsMarket ? loadMarket : null);
@@ -98,18 +105,20 @@ export function OptionsScenarioPane({ width, height, focused }: PaneProps) {
     if (!follow || !storedPosition) return null;
     const spotQuote = resolveEntryData(liveEntries.get(buildQuoteKey({ symbol: underlying, exchange: exchange ?? "" })));
     if (!spotQuote || spotQuote.stale || !(spotQuote.price > 0) || !Number.isFinite(spotQuote.price)
-      || (spotQuote.currency && storedPosition.currency !== "UNKNOWN" && spotQuote.currency !== storedPosition.currency)) return null;
+      || (spotQuote.currency && storedPosition.currency !== UNKNOWN_CURRENCY && spotQuote.currency !== storedPosition.currency)) return null;
     const freshness = { now: Math.max(freshnessNow, Date.now()), subscriptionStartedAt };
     const mids = new Map<string, number>();
+    const quotes = new Map<string, HedgeQuote>();
     let delayed = spotQuote.dataSource !== "live";
     for (const [id, symbol] of legSymbols) {
       const quote = freshOptionQuote(liveEntries.get(buildOptionQuoteKey(symbol)), freshness);
       const mid = quote && quote.bid != null && quote.ask != null ? optionMid({ bid: quote.bid, ask: quote.ask }) : null;
       if (mid == null) continue;
       mids.set(id, mid);
+      quotes.set(id, { bid: quote!.bid!, ask: quote!.ask! });
       delayed ||= quote!.dataSource !== "live";
     }
-    return { position: liveScenarioPosition(storedPosition, spotQuote.price, Date.now(), mids),
+    return { position: liveScenarioPosition(storedPosition, spotQuote.price, Date.now(), mids), quotes,
       observedAt: spotQuote.lastUpdated, basis: delayed ? "delayed" : "real-time" };
   }, [follow, storedPosition, liveEntries, underlying, exchange, legSymbols, freshnessNow, subscriptionStartedAt]);
   const position = live?.position ?? storedPosition;
@@ -132,7 +141,16 @@ export function OptionsScenarioPane({ width, height, focused }: PaneProps) {
   }, [frozen, position, controls, seeded.error, controlState, baseControls.error]);
   const scenario = result.scenario;
   const error = localError ?? result.error;
-  const baseline = (): ScenarioPosition => position ?? { symbol: underlying, exchange, currency: String(settings.currency ?? (market?.currency || "UNKNOWN")),
+  // The report's Hedge budget, from the same position and quotes; a live position sizes at its live quotes and spot.
+  const hedge = useMemo(() => {
+    if (!scenario) return { value: null, error: null };
+    try {
+      return { value: scenarioHedgeBudget(settings, scenario.position,
+        live ? { chain: market?.chain, liveQuotes: live.quotes } : market), error: null };
+    } catch (error) { return { value: null, error: error instanceof Error ? error.message : String(error) }; }
+  }, [settings, scenario, market, live]);
+  const baseline = (): ScenarioPosition => position ?? { symbol: underlying, exchange,
+    currency: scenarioCurrency(settings.currency, market?.currency || ticker?.metadata.currency, exchange ?? market?.exchange),
     spot: Number.isFinite(explicitSpot) ? explicitSpot : market?.spot ?? NaN,
     rate: settings.rate != null ? Number(settings.rate) / 100 : market?.rate ?? NaN,
     dividendYield: settings.dividendYield != null ? Number(settings.dividendYield) / 100 : market?.dividendYield ?? NaN,
@@ -215,9 +233,10 @@ export function OptionsScenarioPane({ width, height, focused }: PaneProps) {
   usePaneFooter("osa", () => ({ info: [
     ...(resource.loading ? [{ id: "loading", parts: [{ text: "loading chain", tone: "muted" as const }] }] : []),
     ...(error ? [{ id: "error", parts: [{ text: error, tone: "warning" as const }] }] : []),
+    ...(hedge.error ? [{ id: "hedge-error", parts: [{ text: hedge.error, tone: "warning" as const }] }] : []),
     ...(live ? [{ id: "asof", parts: [{ text: `${live.basis} · as of ${new Date(live.observedAt).toISOString().slice(11, 19)} UTC`, tone: "muted" as const }] }]
       : position ? [{ id: "asof", parts: [{ text: `${dateLabel(position.asOf)} · ${market?.source ? "market" : "input assumptions"}${midVolatility}`, tone: "muted" as const }] }] : []),
-  ], hints }), [hints, position, market?.source, resource.loading, error, live?.basis, live?.observedAt, midVolatility]);
+  ], hints }), [hints, position, market?.source, resource.loading, error, hedge.error, live?.basis, live?.observedAt, midVolatility]);
   useScenarioEvidence({ scenario, view: tab, loading: !!resource.loading && !scenario, error: error ?? (snapshotErrors.join("; ") || null), notices });
   // A choice dialog (scenario date, saved strategies) owns the keys while open.
   const dialogOpen = useDialogState((state) => state.isOpen);
@@ -238,11 +257,13 @@ export function OptionsScenarioPane({ width, height, focused }: PaneProps) {
   const tabsFocused = focused && !volActive && !detail;
   const { strip: tabStrip, rows: tabRows } = usePaneTabs({ tabs: TABS, activeValue: tab, onSelect: setTab, focused: tabsFocused, dense: true });
   const risk = scenario?.expiryRisk;
+  // Value and P&L add every contract; spot and entry prices are per share.
+  const valueUnit = scenario ? `${currencyLabel(scenario.position.currency)} ${scenarioValueUnit(scenario.position)}` : "";
   const stats: StatItem[] = scenario ? [
-    { id: "pnl", label: "P&L", value: money(scenario.valuation.pnl), detail: scenario.position.currency,
+    { id: "pnl", label: "P&L", value: money(scenario.valuation.pnl), detail: valueUnit,
       tone: cents(scenario.valuation.pnl) >= 0 ? "positive" : "negative" },
-    { id: "spot", label: "Spot", value: money(scenario.position.spot) },
-    { id: "value", label: "Value", value: money(scenario.valuation.price) },
+    { id: "spot", label: "Spot", value: money(scenario.position.spot), detail: "per share" },
+    { id: "value", label: "Value", value: money(scenario.valuation.price), detail: valueUnit },
     { id: "max-profit", label: "Max profit", value: risk?.unlimitedProfit ? "Unlimited" : money(risk?.maxProfit ?? null) },
     { id: "max-loss", label: "Max loss", value: risk?.unlimitedLoss ? "Unlimited" : money(risk?.maxLoss ?? null) },
     { id: "breakevens", label: "Breakevens", value: risk?.breakevens.map(money).join(", ") || "--" },
@@ -252,11 +273,13 @@ export function OptionsScenarioPane({ width, height, focused }: PaneProps) {
     { id: "vega", label: "Vega", value: money(scenario.valuation.vegaPerPoint), detail: "per pt" },
     { id: "rho", label: "Rho", value: money(scenario.valuation.rhoPerPoint), detail: "per pt" },
   ] : [];
+  const hedgeItems = hedge.value ? hedgeStatItems(hedge.value) : [];
   // The query bar and the stat band sit above the content only once a scenario prices.
-  const bodyHeight = Math.max(3, height - tabRows - (scenario ? 1 + statGridRows(stats, width) : 0));
+  const bodyHeight = Math.max(3, height - tabRows - (scenario ? 1 + statGridRows(stats, width) : 0)
+    - (hedgeItems.length ? statGridRows(hedgeItems, width) : 0));
   const legColumns: DataTableColumn[] = [{ id: "quantity", label: "Contracts", width: 10, align: "right" },
     { id: "side", label: "Option", width: 7, align: "left" }, { id: "strike", label: "Strike", width: 11, align: "right" },
-    { id: "expiration", label: "Expiry", width: 12, align: "left" }, { id: "price", label: "Entry / unit", width: 13, align: "right" },
+    { id: "expiration", label: "Expiry", width: 12, align: "left" }, { id: "price", label: "Entry / share", width: 14, align: "right" },
     { id: "volatility", label: "IV %", width: 9, align: "right" }, { id: "multiplier", label: "Units", width: 7, align: "right" }];
   const activeContent = scenario && tab === "payoff" ? <ScenarioPayoffChart scenario={scenario} width={width} height={bodyHeight} focused={tabsFocused} />
     : scenario && tab === "grid" ? <DataTableView focused={focused && !volActive} rootWidth={width}
@@ -308,6 +331,7 @@ export function OptionsScenarioPane({ width, height, focused }: PaneProps) {
         ]}
       />
       <StatGrid items={stats} width={width} />
+      {hedgeItems.length > 0 && <StatGrid items={hedgeItems} width={width} />}
     </>}
     {!position?.legs.length && !scenario ? <PaneStatusBody loading={!!resource.loading && !market} error={seeded.error} subject="scenario inputs">
       <Box paddingX={1}><EmptyState title="Build an options position." actions={<Button label="Add leg" onPress={addTyped} />} /></Box>

package/src/plugins/builtin/pe-band/model.ts

@@ -120,8 +120,8 @@ function epsSeries(financials: TickerFinancials, period: "ttm" | "annual"): Time
  * by the shared statement series, which keeps declared gaps and broken runs
  * of quarters unavailable. A reported fiscal year is itself a trailing
  * twelve-month figure; at a fiscal year end it replaces the quarterly sum.
- * A figure with no publication date of its own is dated by the company's
- * report of that quarter, when `reports` has it.
+ * A figure is known no later than the company's report of that quarter, when
+ * `reports` has it, including one with no publication date of its own.
  */
 export function trailingEpsSteps(financials: TickerFinancials, reports: readonly ReportDate[] = []): EpsStep[] {
   const known = (row: FinancialStatement) => datedByReport(knownWhenFiled(row), reports);

package/src/plugins/builtin/pe-band/report-dates.ts

@@ -65,14 +65,18 @@ function reportedWhen(periodEnd: string, reports: readonly ReportDate[]): string
 }
 
 /**
- * The statement with its EPS dated by the company's report, only when it has no
- * publication date of its own: a date on record always wins. A fiscal year is
- * dated by the report of its last quarter, which shares its period end. A
- * trailing sum takes the latest of its four quarters from the shared series,
- * so it cannot be known before all four are.
+ * The statement with its EPS dated by the company's report when it has no
+ * publication date of its own or a later one: the figure was public once the
+ * period was reported, and a filing that repeats or restates it afterwards (a
+ * split onto a new share count, a comparative in a later 10-K) does not delay
+ * it. A fiscal year is dated by the report of its last quarter, which shares
+ * its period end. A trailing sum takes the latest of its four quarters from
+ * the shared series, so it cannot be known before all four are.
  */
 export function datedByReport(row: FinancialStatement, reports: readonly ReportDate[]): FinancialStatement {
-  if (!reports.length || typeof row.eps !== "number" || !Number.isFinite(row.eps) || statementFieldAvailability(row, "eps") !== undefined) return row;
+  if (!reports.length || typeof row.eps !== "number" || !Number.isFinite(row.eps)) return row;
   const known = reportedWhen(row.date, reports);
-  return known ? { ...row, fieldAvailability: { ...row.fieldAvailability, eps: known } } : row;
+  const onRecord = statementFieldAvailability(row, "eps");
+  if (!known || (onRecord !== undefined && Date.parse(onRecord) <= Date.parse(known))) return row;
+  return { ...row, fieldAvailability: { ...row.fieldAvailability, eps: known } };
 }

package/src/plugins/builtin/perps/equity-row.tsx

@@ -6,7 +6,7 @@ import { useAsyncResource, useAutoRefresh, usePluginAppActions } from "../../../
 import { useResearchCloudSession } from "../shared/research-cloud-session";
 import { perpEquityIdentity } from "./equity-identity";
 import { loadPerpsEquity } from "./client";
-import { compact, marketLabel, percent, price } from "./model";
+import { compact, percent, perpDescription, price, readingTime } from "./model";
 
 /** A failed optional market comparison never blocks a stock's quote. */
 export function PerpEquityRow({ symbol, exchange, instrumentType, maxRows = 3 }: { symbol: string; exchange?: string; instrumentType?: string; maxRows?: number }) {
@@ -23,8 +23,11 @@ export function PerpEquityRow({ symbol, exchange, instrumentType, maxRows = 3 }:
   useAutoRefresh(resource.updatedAt, resource.load, { intervalMs: 60_000 });
   const rows = resource.data?.payload.rows.filter((row) => !row.delisted) ?? [];
   if (!enabled || !rows.length) return null;
-  return <>{rows.slice(0, maxRows).map((row) => <ActionRow key={row.marketId} height={2}
-    // Funding reads per 8h here as it does in PERP, whatever interval the venue pays on.
-    label={`${marketLabel(row)} perp  ${price(row.markPrice)} ${row.quoteCurrency}  ${percent(row.underlyingPremium, 2)} vs last${row.stale || resource.data?.stale ? " · stale" : ""}\nFunding ${percent(row.fundingRate8h, 4)} / 8h · OI ${compact(row.openInterestUsd)} USD · oracle ${percent(row.premium, 2)}`}
-    onPress={() => createPaneFromTemplate("perps-pane", { arg: row.marketId })} />)}</>;
+  return <>{rows.slice(0, maxRows).map((row) => {
+    const read = readingTime(row.observedAt);
+    return <ActionRow key={row.marketId} height={2}
+      // Funding reads per 8h here as it does in PERP, whatever interval the venue pays on.
+      label={`${row.baseAsset} · ${perpDescription(row)}  ${price(row.markPrice)} ${row.quoteCurrency}  ${percent(row.underlyingPremium, 2)} vs last${row.stale || resource.data?.stale ? " · stale" : ""}\nFunding ${percent(row.fundingRate8h, 4)} per 8 h · OI ${compact(row.openInterestUsd)} USD · oracle ${percent(row.premium, 2)}${read ? ` · as of ${read}` : ""}`}
+      onPress={() => createPaneFromTemplate("perps-pane", { arg: row.marketId })} />;
+  })}</>;
 }

package/src/plugins/builtin/perps/model.ts

@@ -22,6 +22,16 @@ export const time = (s: string | null | undefined) => s ? `${s.slice(0, 10)} ${s
 /** A list row's observation, month to minute: the header names UTC and the footer the full as-of. */
 const observed = (s: string | null | undefined) => s ? `${s.slice(5, 10)} ${s.slice(11, 16)}` : "--";
 export const marketLabel = (row: PerpBoardRow) => row.dex && row.dex !== "default" ? `${row.baseAsset} · ${row.dex.toUpperCase()}` : row.baseAsset;
+/** What the contract is, in plain words: perpetual futures never expire and trade around the clock. */
+export const perpDescription = (row: Pick<PerpBoardRow, "venue">) =>
+  `Perpetual futures (24/7 ${row.venue === "hyperliquid" || row.venue === "dydx" ? "on-chain" : venueName(row.venue)} market)`;
+/** When the venue's figures were read, in UTC: the time alone for today, with the date for an older reading. */
+export function readingTime(observedAt: string | null | undefined, now = Date.now()): string | null {
+  const read = observedAt ? Date.parse(observedAt) : Number.NaN;
+  if (!Number.isFinite(read)) return null;
+  const iso = new Date(read).toISOString();
+  return `${iso.slice(0, 10) === new Date(now).toISOString().slice(0, 10) ? "" : `${iso.slice(0, 10)} `}${iso.slice(11, 16)} UTC`;
+}
 export const fundingInterval = (row: Pick<PerpBoardRow, "fundingIntervalHours" | "fundingKind">) => row.fundingIntervalHours ? `${row.fundingIntervalHours}h${row.fundingKind === "last-paid" ? " paid" : row.fundingKind === "continuous" ? " continuous" : ""}` : "--";
 export const HISTORY_METRICS = ["funding", "oi", "premium", "price", "long-short"] as const;
 export type HistoryMetric = typeof HISTORY_METRICS[number];
@@ -116,12 +126,13 @@ const PERP_COLUMNS: Record<PerpColumnId, DataTableColumn> = {
   value: { id: "value", label: "Value %", width: 10, align: "right" },
 };
 // Columns in reading order, then the order a narrow pane gives them up in.
-export const BOARD_COLUMNS: PerpColumnId[] = ["market", "venue", "markPrice", "fundingRate", "fundingApr", "premium", "openInterestUsd", "oiChange24h", "longShare", "priceChange24h", "observedAt"];
+export const BOARD_COLUMNS: PerpColumnId[] = ["market", "venue", "markPrice", "fundingRate", "premium", "openInterestUsd", "oiChange24h", "longShare", "fundingApr", "priceChange24h", "observedAt"];
 // The venue goes last: the same market trades on several, and only the venue tells those rows apart. The long share
-// gives way before every figure a 100-column pane already showed, so it never pushes one of those off.
-const BOARD_DROPS: PerpColumnId[] = ["observedAt", "priceChange24h", "fundingApr", "longShare", "oiChange24h", "premium", "markPrice", "openInterestUsd", "venue"];
-export const COMPARE_COLUMNS: PerpColumnId[] = ["venue", "symbol", "markPrice", "fundingRate", "fundingRate8h", "fundingApr", "premium", "openInterestUsd", "oiChange24h", "longShare", "observedAt"];
-const COMPARE_DROPS: PerpColumnId[] = ["observedAt", "oiChange24h", "fundingApr", "longShare", "fundingRate", "premium", "markPrice", "openInterestUsd", "symbol"];
+// is what the board and the comparison are read for, so a 100-column pane keeps it and the annualised funding, which
+// only restates the funding rate, goes first (the 24h OI change next on the board, the per-interval rate on Compare).
+const BOARD_DROPS: PerpColumnId[] = ["observedAt", "fundingApr", "priceChange24h", "oiChange24h", "longShare", "premium", "markPrice", "openInterestUsd", "venue"];
+export const COMPARE_COLUMNS: PerpColumnId[] = ["venue", "symbol", "markPrice", "fundingRate", "fundingRate8h", "premium", "openInterestUsd", "oiChange24h", "longShare", "fundingApr", "observedAt"];
+const COMPARE_DROPS: PerpColumnId[] = ["observedAt", "fundingApr", "oiChange24h", "fundingRate", "longShare", "premium", "markPrice", "openInterestUsd", "symbol"];
 export const RANKING_COLUMNS: PerpColumnId[] = ["market", "venue", "value", "openInterestUsd"];
 
 /** The columns that fit the pane, the least read going first; before the last of them goes, a long market name gives up its tail. */