gloomberb 0.18.3 → 0.18.4

package/src/plugins/builtin/options-scenario/csp-screen.ts

@@ -0,0 +1,258 @@
+import type { InstrumentRef } from "../../../market-data/request-types";
+import type { DataProvider } from "../../../types/data-provider";
+import type { HeadlessPaneFreshness } from "../../../types/plugin";
+import { mapWithConcurrency } from "../../../utils/concurrency";
+import { numberErrorMessage, wholeNumberOptionMessage } from "../../../utils/decimal-comma";
+import { errorMessage } from "../../../utils/errors";
+import { expirationHint, expiredExpiryText, expiryIsoDate, isLiveOptionExpiry, readOptionExpiration } from "../../../utils/option-expiry";
+import { zonedDateKey } from "../../../utils/zoned-date-time";
+import { ivRankReason, loadIvScreen, type ImpliedVolatilityApi, type IvScreenRow } from "../iv-history/client";
+import { quoteObservation } from "../shared/report-freshness";
+import { loadScenarioMarket, scenarioPositionFromSettings, scenarioSpotBasis, type ScenarioLoaderDependencies, type ScenarioMarketSnapshot } from "./client";
+import { cashSecuredPut, loadNextEarningsDates, type CashSecuredPut } from "./csp";
+import { seededLegQuotes } from "./hedge";
+import { scenarioValue } from "./model";
+
+/**
+ * A cash-secured put screen (docs/research-data.md#cash-secured-put-screen):
+ * for each name, the put OSA's `--strategy csp --delta` seed sells on the
+ * listed expiry nearest the target, read by the same `cashSecuredPut`, ranked
+ * by its annualised yield at the bid.
+ */
+export interface CspScreenCriteria {
+  /** The absolute put delta each name's put is nearest, such as 0.30. */
+  delta: number;
+  /** Calendar days out the expiry is nearest, when no date is given. */
+  days: number;
+  /** The date the expiry is nearest, in Unix seconds, in place of `days`; null when none is given. */
+  expiration: number | null;
+  /** A spread over this percent of the midpoint marks the put wide. */
+  maxSpreadPercent: number;
+}
+
+export const CSP_SCREEN_DEFAULTS: Readonly<Omit<CspScreenCriteria, "expiration">> = { delta: 0.3, days: 30, maxSpreadPercent: 10 };
+/** The most names one screen reads: each is two chain requests. */
+export const CSP_SCREEN_LIMIT = 20;
+const DAY_MS = 86_400_000;
+const CONCURRENCY = 4;
+
+export interface CspScreenRow {
+  symbol: string;
+  /** 1 for the highest yield at the bid; null for a name with no put to rank. */
+  rank: number | null;
+  csp: CashSecuredPut | null;
+  /** The put's delta per share, negative, at the IV its midpoint implies. */
+  delta: number | null;
+  /** 30-day IV rank, 0 to 100, against the prior 52 weeks; null when IV history has none. */
+  ivRank: number | null;
+  /** Its spread is over the screen's `maxSpreadPercent` of the midpoint. */
+  wideSpread: boolean;
+  /** Why the name has no put to rank. */
+  note: string | null;
+}
+
+export interface CspScreen {
+  rows: CspScreenRow[];
+  criteria: CspScreenCriteria;
+  /** Names IV history has no rank for, with why when it can say, such as `XYZ (no options history)`; a bare symbol has no reason to give. */
+  missingRanks: string[];
+  /** The IV rank request failed for every name. */
+  ivRankError: string | null;
+  freshness: HeadlessPaneFreshness;
+}
+
+const supplied = (value: unknown) => value != null && value !== "";
+
+function readNumber(value: unknown, flag: string, example: string): number {
+  const text = typeof value === "number" ? String(value) : typeof value === "string" ? value.trim().replace(/%$/, "") : "";
+  const number = Number(text);
+  if (!text || !/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)$/.test(text) || !Number.isFinite(number)) {
+    throw new Error(numberErrorMessage(`Invalid --${flag} "${String(value)}". Use ${example}.`, text));
+  }
+  return number;
+}
+
+/** `--days`: whole calendar days. A decimal is told the whole numbers beside it, never a decimal to type. */
+function readDays(value: unknown): number {
+  const decimal = wholeNumberOptionMessage("--days", "days", value);
+  if (decimal) throw new Error(decimal);
+  const days = readNumber(value, "days", "whole calendar days, such as 30");
+  if (!Number.isInteger(days) || days < 1) throw new Error(`Invalid --days "${String(value)}". Use whole calendar days, such as 30.`);
+  return days;
+}
+
+/** The screen's criteria from `fn CSP` options or the pane's settings, each default where not set. */
+export function readCspScreenCriteria(options: Record<string, unknown>): CspScreenCriteria {
+  const delta = supplied(options.delta) ? Math.abs(readNumber(options.delta, "delta", "a put's delta between 0 and 1, such as 0.30")) : CSP_SCREEN_DEFAULTS.delta;
+  if (!(delta > 0 && delta < 1)) throw new Error(`Invalid --delta "${String(options.delta)}". Use a put's delta between 0 and 1, such as 0.30.`);
+  const days = supplied(options.days) ? readDays(options.days) : CSP_SCREEN_DEFAULTS.days;
+  const maxSpreadPercent = supplied(options.maxSpread)
+    ? readNumber(options.maxSpread, "max-spread", "a percent of the midpoint above 0, such as 10") : CSP_SCREEN_DEFAULTS.maxSpreadPercent;
+  if (!(maxSpreadPercent > 0)) throw new Error(`Invalid --max-spread "${String(options.maxSpread)}". Use a percent of the midpoint above 0, such as 10.`);
+  const expiration = supplied(options.expiration) ? readOptionExpiration(options.expiration) : null;
+  if (supplied(options.expiration) && expiration == null) throw new Error(`Invalid --expiration "${String(options.expiration)}". Use a date such as 2026-11-20.${expirationHint(String(options.expiration))}`);
+  if (expiration != null && supplied(options.days)) throw new Error("--days and --expiration each pick the expiry; give one of them");
+  return { delta, days, expiration, maxSpreadPercent };
+}
+
+/** The date each name's expiry is nearest, YYYY-MM-DD: the typed date, else `days` out from today in New York. */
+export function cspTargetDate(criteria: Pick<CspScreenCriteria, "days" | "expiration">, now: number): string {
+  if (criteria.expiration != null) return expiryIsoDate(criteria.expiration);
+  return new Date(Date.parse(`${zonedDateKey(now, "America/New_York")}T00:00:00Z`) + criteria.days * DAY_MS).toISOString().slice(0, 10);
+}
+
+/** The listed expiry whose date is nearest `target` (YYYY-MM-DD), the earlier on a tie; undefined when none is listed. */
+export function nearestListedExpiry(expirations: readonly number[], target: string): number | undefined {
+  const targetTime = Date.parse(`${target}T00:00:00Z`);
+  let best: { expiration: number; distance: number } | undefined;
+  for (const expiration of [...expirations].sort((a, b) => a - b)) {
+    const distance = Math.abs(Date.parse(`${expiryIsoDate(expiration)}T00:00:00Z`) - targetTime);
+    if (Number.isFinite(distance) && (!best || distance < best.distance)) best = { expiration, distance };
+  }
+  return best?.expiration;
+}
+
+const bidYield = (row: CspScreenRow) => row.csp?.quote?.bidAnnualizedYield ?? null;
+
+/**
+ * Highest annualised yield at the bid first; a wide spread is ranked with the
+ * rest and flagged, never left out. A put with no yield to rank (it expires
+ * today) follows, then the names with no put, by symbol.
+ */
+export function rankCspScreen(rows: readonly Omit<CspScreenRow, "rank">[]): CspScreenRow[] {
+  const tier = (row: Omit<CspScreenRow, "rank">) => bidYield(row as CspScreenRow) != null ? 0 : row.csp ? 1 : 2;
+  const sorted = [...rows].sort((left, right) => tier(left) - tier(right)
+    || (bidYield(right as CspScreenRow) ?? 0) - (bidYield(left as CspScreenRow) ?? 0)
+    || left.symbol.localeCompare(right.symbol));
+  let rank = 0;
+  return sorted.map((row) => ({ ...row, rank: tier(row) === 0 ? ++rank : null }));
+}
+
+/** Whether a put's spread is over the screen's limit. */
+function cspWideSpread(csp: CashSecuredPut | null, maxSpreadPercent: number): boolean {
+  return csp?.quote != null && csp.quote.spreadOfMid * 100 > maxSpreadPercent;
+}
+
+export interface CspScreenDependencies {
+  scenario: ScenarioLoaderDependencies;
+  /** The earnings calendar's source. */
+  earnings: DataProvider | null | undefined;
+  /** Gloom Cloud's IV history; the app's client when omitted. */
+  ivApi?: ImpliedVolatilityApi;
+}
+
+interface ScreenedPut { csp: CashSecuredPut; delta: number | null; market: ScenarioMarketSnapshot }
+
+/** One name's put: OSA's csp seed at `--delta` on the listed expiry nearest the target, read as OSA reads it. */
+async function screenPut(
+  instrument: InstrumentRef, criteria: CspScreenCriteria, dependencies: ScenarioLoaderDependencies, target: string,
+  earningsDate: string | null, signal: AbortSignal | undefined,
+): Promise<ScreenedPut> {
+  const first = await loadScenarioMarket({ instrument, signal }, dependencies);
+  // A typed date whose last session has closed is not stood in for by the next one: it says so, and names it.
+  const now = dependencies.now?.() ?? Date.now();
+  if (criteria.expiration != null && !isLiveOptionExpiry(criteria.expiration, now, instrument.exchange)) {
+    throw new Error(`Expiry ${expiryIsoDate(criteria.expiration)} `
+      + expiredExpiryText(criteria.expiration, first.expirationDates, now, { exchange: instrument.exchange, flag: "expiration" }));
+  }
+  const expiration = nearestListedExpiry(first.expirationDates, target);
+  if (expiration == null) {
+    throw new Error(first.warnings.find((warning) => warning.startsWith("Options chain")) ?? "No listed option expiries");
+  }
+  const loaded = first.chain ? [...first.chain.puts, ...first.chain.calls][0]?.expiration : undefined;
+  const market = loaded != null && expiryIsoDate(loaded) === expiryIsoDate(expiration)
+    ? first : await loadScenarioMarket({ instrument, expiration, signal }, dependencies);
+  const settings = { symbol: instrument.symbol, exchange: instrument.exchange, strategy: "csp", delta: criteria.delta };
+  const position = scenarioPositionFromSettings(settings, market);
+  const leg = position?.legs[0];
+  if (!position || !leg) throw new Error("No put to sell on this chain");
+  const quote = seededLegQuotes(position, market.chain).get(leg.id);
+  const csp = cashSecuredPut(position, scenarioSpotBasis(settings, position, market), earningsDate, quote);
+  if (!csp) throw new Error("No put to sell on this chain");
+  const shares = leg.quantity * leg.multiplier;
+  const delta = scenarioValue(position, position.spot, position.asOf).delta / shares;
+  return { csp, delta: Number.isFinite(delta) ? delta : null, market };
+}
+
+async function loadIvRanks(symbols: readonly string[], signal: AbortSignal | undefined, api: ImpliedVolatilityApi | undefined) {
+  try {
+    const payload = await loadIvScreen(symbols, { signal }, api);
+    return { rows: new Map<string, IvScreenRow>(payload.rows.map((row) => [row.symbol.toUpperCase(), row])), error: null };
+  } catch (error) {
+    if (signal?.aborted) throw error;
+    return { rows: new Map<string, IvScreenRow>(), error: errorMessage(error) ?? "no response" };
+  }
+}
+
+/**
+ * How current the screen is: each name's underlying quote dates its row, and
+ * the chains' feed (delayed when any is) says how far behind they run.
+ */
+function screenFreshness(markets: readonly ScenarioMarketSnapshot[], now: number): HeadlessPaneFreshness {
+  const chains = markets.flatMap((market) => market.chain ? [market.chain] : []);
+  const delayed = chains.some((chain) => chain.dataSource === "delayed");
+  const live = chains.length > 0 && chains.every((chain) => chain.dataSource === "live");
+  const delayMinutes = Math.max(0, ...chains.map((chain) => chain.delayMinutes ?? 0));
+  const observations = markets.flatMap((market) => market.underlyingQuote ? [{ ...quoteObservation(market.underlyingQuote, now) }] : []);
+  return {
+    ...(delayed ? { status: "delayed" as const } : live ? { status: "live" as const } : {}),
+    ...(delayed && delayMinutes ? { delayMinutes } : {}),
+    ...(observations.length ? { observations } : markets[0] ? { asOf: markets[0].asOf } : {}),
+  };
+}
+
+/**
+ * Each name's cash-secured put, ranked: one IV rank request, one earnings
+ * calendar request and one Treasury curve for all of them.
+ */
+export async function loadCspScreen(
+  instruments: readonly InstrumentRef[], criteria: CspScreenCriteria, dependencies: CspScreenDependencies, signal?: AbortSignal,
+): Promise<CspScreen> {
+  const now = dependencies.scenario.now?.() ?? Date.now();
+  // Every name reads the same curve, up to twice (the catalogue, then its expiry): asked for once, when the first name needs it.
+  let curve: ReturnType<ScenarioLoaderDependencies["loadYieldCurve"]> | null = null;
+  const scenario: ScenarioLoaderDependencies = { ...dependencies.scenario, loadYieldCurve: () => curve ??= dependencies.scenario.loadYieldCurve() };
+  const symbols = instruments.map((instrument) => instrument.symbol.trim().toUpperCase());
+  const [ivRanks, earnings] = await Promise.all([
+    loadIvRanks(symbols, signal, dependencies.ivApi),
+    loadNextEarningsDates(dependencies.earnings, symbols, zonedDateKey(now, "America/New_York")),
+  ]);
+  signal?.throwIfAborted();
+  const target = cspTargetDate(criteria, now);
+  const markets: ScenarioMarketSnapshot[] = [];
+  const missingRanks: string[] = [];
+  const rows = await mapWithConcurrency(instruments, CONCURRENCY, async (instrument, index): Promise<Omit<CspScreenRow, "rank">> => {
+    const symbol = symbols[index]!;
+    const ivRow = ivRanks.rows.get(symbol);
+    const rank = ivRow?.iv30?.rank;
+    const ivRank = rank != null && Number.isFinite(rank) ? rank : null;
+    try {
+      const screened = await screenPut(instrument, criteria, scenario, target, earnings.get(symbol) ?? null, signal);
+      markets.push(screened.market);
+      if (ivRank == null && !ivRanks.error) {
+        const reason = ivRankReason(ivRow);
+        missingRanks.push(reason ? `${symbol} (${reason})` : symbol);
+      }
+      return { symbol, csp: screened.csp, delta: screened.delta, ivRank, wideSpread: cspWideSpread(screened.csp, criteria.maxSpreadPercent), note: null };
+    } catch (error) {
+      if (signal?.aborted) throw error;
+      return { symbol, csp: null, delta: null, ivRank, wideSpread: false, note: errorMessage(error) ?? "No put to sell" };
+    }
+  });
+  return { rows: rankCspScreen(rows), criteria, missingRanks: missingRanks.sort(), ivRankError: ivRanks.error,
+    freshness: screenFreshness(markets, now) };
+}
+
+/** `nearest 0.30 delta · expiry nearest 2026-11-21 (30 days)`: what each name's put is. */
+export function cspScreenCriteriaText(criteria: CspScreenCriteria, now: number): string {
+  return `nearest ${criteria.delta.toFixed(2)} delta · expiry nearest ${cspTargetDate(criteria, now)}`
+    + (criteria.expiration == null ? ` (${criteria.days} days)` : "");
+}
+
+/** `before 2026-11-04`, `after 2027-01-19`, `unknown`: whether the next report falls before the put expires, and its date. */
+export function cspEarningsText(csp: CashSecuredPut | null): string {
+  if (!csp) return "--";
+  const { beforeExpiry, date } = csp.earnings;
+  return beforeExpiry == null ? "unknown" : `${beforeExpiry ? "before" : "after"} ${date}`;
+}
+

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

@@ -2,8 +2,11 @@ import type { StatItem } from "../../../components";
 import type { DataProvider } from "../../../types/data-provider";
 import type { HeadlessPaneEntry } from "../../../types/headless";
 import { loadEarningsCalendar } from "../earnings/data/cache";
+import { optionSpread } from "../options/market-reference";
+import { newYorkDay, resolveListingEvents, upcomingReportDate } from "../shared/earnings-calendar";
+import { parsePublicTickerKey } from "../../../utils/exchanges";
 import { formatHedgePrice } from "./hedge";
-import { UNKNOWN_CURRENCY, type ScenarioPosition } from "./model";
+import { amountUnit, exportPercent, UNKNOWN_CURRENCY, type ScenarioPosition } from "./model";
 
 /**
  * A cash-secured put (docs/research-data.md#cash-secured-put): one short put
@@ -15,6 +18,9 @@ import { UNKNOWN_CURRENCY, type ScenarioPosition } from "./model";
  *   seed enters at the quote midpoint
  * - yield on cash = premium / cash secured
  * - annualised yield = yield on cash x 365 / days to expiry (simple, not compounded)
+ * - the same premium and yields at the bid, the price a sell order fills at
+ *   without crossing the spread, when the put has a two-sided quote
+ * - spread = ask - bid, and as a percent of the midpoint
  * - out of the money = (spot - strike) / spot, against the scenario's spot
  * - break-even = strike - entry price
  * - days to expiry = calendar days from the valuation date in New York to the expiry date
@@ -38,6 +44,8 @@ export interface CashSecuredPut {
   yieldOnCash: number;
   /** Null on the expiry day, when there is no day to annualise over. */
   annualizedYield: number | null;
+  /** The put's two-sided quote and what selling at its bid yields; null without one. */
+  quote: CspQuote | null;
   daysToExpiry: number;
   /** Valuation date in New York, YYYY-MM-DD. */
   valuationDate: string;
@@ -50,6 +58,20 @@ export interface CashSecuredPut {
   earnings: CspEarnings;
 }
 
+interface CspQuote {
+  bid: number;
+  ask: number;
+  /** ask - bid, per share. */
+  spread: number;
+  /** The spread over the midpoint, as a fraction. */
+  spreadOfMid: number;
+  /** Premium at the bid, for every contract. */
+  bidPremium: number;
+  bidYieldOnCash: number;
+  /** Null on the expiry day. */
+  bidAnnualizedYield: number | null;
+}
+
 export interface CspEarnings {
   /** The next report date, YYYY-MM-DD, or null when none is published. */
   date: string | null;
@@ -71,12 +93,22 @@ export function earningsBeforeExpiry(earningsDate: string | null | undefined, va
   return { date: earningsDate, beforeExpiry: earningsDate <= expiry };
 }
 
+/** What selling at `price` per share earns on the cash secured: the one yield calculation, at the entry price and at the bid alike. */
+function putYield(price: number, cashSecured: number, sharesSold: number, daysToExpiry: number) {
+  const premium = Math.round(price * sharesSold * 1e6) / 1e6;
+  const yieldOnCash = premium / cashSecured;
+  return { premium, yieldOnCash, annualizedYield: daysToExpiry > 0 ? yieldOnCash * 365 / daysToExpiry : null };
+}
+
 /**
  * The position as a cash-secured put, or null when it is not one short put.
- * `spotBasis` names the spot the out-of-the-money distance is read against.
+ * `spotBasis` names the spot the out-of-the-money distance is read against;
+ * `quote` is the put's bid and ask, for a put seeded from the chain
+ * (`seededLegQuotes`).
  */
 export function cashSecuredPut(
   position: ScenarioPosition, spotBasis: string, earningsDate: string | null | undefined,
+  quote?: { bid: number; ask: number } | null,
 ): CashSecuredPut | null {
   const [leg] = position.legs;
   if (position.legs.length !== 1 || !leg || leg.side !== "put" || leg.quantity >= 0 || position.underlying) return null;
@@ -85,12 +117,19 @@ export function cashSecuredPut(
   const valuationDate = newYorkCalendarDate(position.asOf);
   const daysToExpiry = Math.max(0, Math.round((Date.parse(`${expiry}T00:00:00Z`) - Date.parse(`${valuationDate}T00:00:00Z`)) / DAY_MS));
   const cashSecured = leg.strike * leg.multiplier * contracts;
-  const premium = Math.round(leg.price * leg.multiplier * contracts * 1e6) / 1e6;
-  const yieldOnCash = premium / cashSecured;
+  const sharesSold = leg.multiplier * contracts;
+  const atEntry = putYield(leg.price, cashSecured, sharesSold, daysToExpiry);
+  const spread = quote ? optionSpread(quote) : null;
+  let bidQuote: CspQuote | null = null;
+  if (quote && spread?.kind === "two-sided") {
+    const atBid = putYield(quote.bid, cashSecured, sharesSold, daysToExpiry);
+    bidQuote = { bid: quote.bid, ask: quote.ask, spread: spread.spread, spreadOfMid: spread.percentOfMid / 100,
+      bidPremium: atBid.premium, bidYieldOnCash: atBid.yieldOnCash, bidAnnualizedYield: atBid.annualizedYield };
+  }
   return {
     currency: position.currency, strike: leg.strike, expiry, contracts, multiplier: leg.multiplier,
     price: leg.price, priceBasis: leg.priceSource === "mid" ? "mid" : "entry",
-    cashSecured, premium, yieldOnCash, annualizedYield: daysToExpiry > 0 ? yieldOnCash * 365 / daysToExpiry : null,
+    cashSecured, ...atEntry, quote: bidQuote,
     daysToExpiry, valuationDate, spot: position.spot, spotBasis,
     outOfTheMoney: position.spot > 0 ? (position.spot - leg.strike) / position.spot : null,
     breakEven: leg.strike - leg.price,
@@ -99,15 +138,31 @@ export function cashSecuredPut(
 }
 
 /**
- * The next report date from the earnings calendar, YYYY-MM-DD; null when the
- * calendar has none for the symbol or cannot be read.
+ * The next report date, YYYY-MM-DD, as every earnings surface resolves it
+ * (shared/earnings-calendar): the calendar's, or once that date has passed
+ * the next one on record; null when there is none or the calendar cannot be
+ * read.
  */
-export async function loadNextEarningsDate(provider: DataProvider | null | undefined, symbol: string): Promise<string | null> {
-  const key = symbol.trim().toUpperCase();
-  const result = await loadEarningsCalendar(provider, [key]).catch(() => null);
-  const event = result?.events.find((entry) => entry.symbol.trim().toUpperCase() === key);
-  const time = event?.earningsDate.getTime();
-  return time != null && Number.isFinite(time) ? new Date(time).toISOString().slice(0, 10) : null;
+export async function loadNextEarningsDate(provider: DataProvider | null | undefined, symbol: string, today = newYorkDay()): Promise<string | null> {
+  return (await loadNextEarningsDates(provider, [symbol], today)).get(symbol.trim().toUpperCase()) ?? null;
+}
+
+/** The next report date of each symbol, by its upper-case symbol, from one calendar request; a symbol with none is left out. */
+export async function loadNextEarningsDates(
+  provider: DataProvider | null | undefined, symbols: readonly string[], today = newYorkDay(),
+): Promise<Map<string, string>> {
+  const keys = [...new Set(symbols.map((symbol) => symbol.trim().toUpperCase()))];
+  const result = await loadEarningsCalendar(provider, keys).catch(() => null);
+  if (!provider || !result?.events.length) return new Map();
+  const listings = keys.map((key) => {
+    const listing = parsePublicTickerKey(key);
+    return { key, symbol: listing.symbol, exchange: listing.exchange ?? "" };
+  });
+  const resolved = await resolveListingEvents(provider, listings, result.events, today);
+  return new Map(keys.flatMap((key) => {
+    const date = upcomingReportDate(resolved.get(key));
+    return date ? [[key, date] as const] : [];
+  }));
 }
 
 const money = (value: number) => value.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 });
@@ -129,22 +184,40 @@ function earningsText(earnings: CspEarnings): string {
 
 const priceWord = (csp: CashSecuredPut) => csp.priceBasis === "mid" ? "quote mid" : "entry price";
 
-/** The report's Cash-secured put section; `value` keeps full precision, `formatted` is what text output prints. */
+/**
+ * The report's Cash-secured put section. Each figure's `value` is in its
+ * `unit`, every digit (a percent as a percent), so an export writes the number
+ * and its unit; `formatted` is what text output prints.
+ */
 export function cspReportEntries(csp: CashSecuredPut): HeadlessPaneEntry[] {
   const unit = unitOf(csp);
+  const amount = { unit: amountUnit(csp.currency) };
+  const perShare = `${amount.unit} per share`;
+  const quote = csp.quote;
   return [
-    { key: "cashSecured", label: "Cash secured", value: csp.cashSecured,
+    { key: "cashSecured", label: "Cash secured", value: csp.cashSecured, ...amount,
       formatted: `${money(csp.cashSecured)}${unit} (${strikeText(csp.strike)} x ${csp.multiplier} x ${csp.contracts})` },
-    { key: "premium", label: "Premium received", value: csp.premium,
+    { key: "premium", label: "Premium received", value: csp.premium, ...amount,
       formatted: `${money(csp.premium)}${unit} (${formatHedgePrice(csp.price)} per share, ${priceWord(csp)})` },
-    { key: "yieldOnCash", label: "Yield on cash", value: csp.yieldOnCash,
+    { key: "yieldOnCash", label: "Yield on cash", value: exportPercent(csp.yieldOnCash), unit: "%",
       formatted: `${percent(csp.yieldOnCash)} (${money(csp.premium)} / ${money(csp.cashSecured)})` },
-    { key: "annualizedYield", label: "Annualised yield", value: csp.annualizedYield,
+    { key: "annualizedYield", label: "Annualised yield", value: exportPercent(csp.annualizedYield), unit: "%",
       formatted: csp.annualizedYield == null ? "-- (expires today)" : `${percent(csp.annualizedYield)} (yield on cash x 365 / ${csp.daysToExpiry})` },
-    { key: "outOfTheMoney", label: "Out of the money", value: csp.outOfTheMoney, formatted: otmText(csp) },
-    { key: "breakEven", label: "Break-even", value: csp.breakEven,
+    ...(quote ? [
+      { key: "bid", label: "Bid", value: quote.bid, unit: perShare, formatted: `${formatHedgePrice(quote.bid)} per share` },
+      { key: "ask", label: "Ask", value: quote.ask, unit: perShare, formatted: `${formatHedgePrice(quote.ask)} per share` },
+      { key: "spread", label: "Spread", value: exportPercent(quote.spreadOfMid), unit: "% of mid",
+        formatted: `${formatHedgePrice(quote.spread)} per share (${percent(quote.spreadOfMid, 1)} of the mid)` },
+      { key: "bidPremium", label: "Premium at the bid", value: quote.bidPremium, ...amount,
+        formatted: `${money(quote.bidPremium)}${unit} (${formatHedgePrice(quote.bid)} x ${csp.multiplier} x ${csp.contracts})` },
+      { key: "bidAnnualizedYield", label: "Annualised yield at the bid", value: exportPercent(quote.bidAnnualizedYield), unit: "%",
+        formatted: quote.bidAnnualizedYield == null ? "-- (expires today)"
+          : `${percent(quote.bidAnnualizedYield)} (${percent(quote.bidYieldOnCash)} on cash x 365 / ${csp.daysToExpiry})` },
+    ] : []),
+    { key: "outOfTheMoney", label: "Out of the money", value: exportPercent(csp.outOfTheMoney), unit: "%", formatted: otmText(csp) },
+    { key: "breakEven", label: "Break-even", value: csp.breakEven, unit: perShare,
       formatted: `${formatHedgePrice(csp.breakEven)} per share (${strikeText(csp.strike)} - ${formatHedgePrice(csp.price)})` },
-    { key: "daysToExpiry", label: "Days to expiry", value: csp.daysToExpiry,
+    { key: "daysToExpiry", label: "Days to expiry", value: csp.daysToExpiry, unit: "days",
       formatted: `${csp.daysToExpiry} (${csp.valuationDate} to ${csp.expiry})` },
     { key: "earningsBeforeExpiry", label: "Earnings before expiry", value: csp.earnings.beforeExpiry, formatted: earningsText(csp.earnings) },
   ];
@@ -153,11 +226,18 @@ export function cspReportEntries(csp: CashSecuredPut): HeadlessPaneEntry[] {
 /** The pane's figures: the same numbers as the report, sized for a StatGrid. */
 export function cspStatItems(csp: CashSecuredPut): StatItem[] {
   const earnings = csp.earnings;
+  const quote = csp.quote;
   return [
     { id: "csp-cash", label: "Cash secured", value: money(csp.cashSecured), detail: `${strikeText(csp.strike)} x ${csp.multiplier * csp.contracts}` },
     { id: "csp-premium", label: "Premium", value: money(csp.premium), detail: `${priceWord(csp)} ${formatHedgePrice(csp.price)}` },
     { id: "csp-yield", label: "Yield", value: percent(csp.yieldOnCash),
       detail: csp.annualizedYield == null ? "expires today" : `${percent(csp.annualizedYield)} a year` },
+    ...(quote ? [
+      { id: "csp-bid", label: "Bid / ask", value: `${formatHedgePrice(quote.bid)} / ${formatHedgePrice(quote.ask)}`,
+        detail: `spread ${percent(quote.spreadOfMid, 1)} of mid` },
+      { id: "csp-bid-yield", label: "At the bid", value: quote.bidAnnualizedYield == null ? "--" : percent(quote.bidAnnualizedYield),
+        detail: quote.bidAnnualizedYield == null ? "expires today" : "a year" },
+    ] : []),
     { id: "csp-otm", label: "OTM", value: csp.outOfTheMoney == null ? "--" : percent(csp.outOfTheMoney, 1),
       detail: `vs ${money(csp.spot)} ${csp.spotBasis === "implied by option quotes" ? "implied" : csp.spotBasis}` },
     { id: "csp-break-even", label: "Break-even", value: formatHedgePrice(csp.breakEven), detail: "per share" },

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

@@ -1,5 +1,6 @@
 import type { HeadlessPaneDefinition } from "../../../types/plugin";
 import { parsePublicTickerKey } from "../../../utils/exchanges";
+import { DATE_OPTION_EXAMPLES } from "../../../utils/calendar-date";
 import {
   expirationOptionSeconds, OPTION_EXPIRATION_FORMAT, OPTION_EXPIRATION_PLACEHOLDER, readOptionExpiration,
 } from "../../../utils/option-expiry";
@@ -11,8 +12,8 @@ import {
 import { scenarioFreshness } from "./freshness";
 import { cashSecuredPut, cspReportEntries, loadNextEarningsDate } from "./csp";
 import { formatSpotTime } from "../options/model-spot";
-import { buildScenario, currencyLabel, parseLegs, scenarioValueUnit } from "./model";
-import { hedgeInputsFromSettings, hedgeReportEntries, scenarioHedgeBudget } from "./hedge";
+import { amountUnit, buildScenario, currencyLabel, exportPercent, parseLegs, scenarioValueUnit } from "./model";
+import { hedgeInputsFromSettings, hedgeReportEntries, scenarioHedgeBudget, seededLegQuotes } from "./hedge";
 import { collarReportEntries, scenarioCollar } from "./collar";
 import { modelDividendYieldNote } from "../../../market-data/model-dividend-yield";
 import { listingFateEmpty, loadListingFate } from "../../../tickers/listing-fate";
@@ -32,6 +33,12 @@ const VALUATION_LABELS: Record<string, (currency: string) => string> = {
   thetaPerDay: (currency) => `Theta (${currency} per day)`, vegaPerPoint: (currency) => `Vega (${currency} per vol point)`,
   rhoPerPoint: (currency) => `Rho (${currency} per rate point)`,
 };
+/** The unit an export names beside each Valuation figure: `per` is the currency for the position (`USD per contract`). */
+const VALUATION_UNITS: Record<string, (currency: string, per: string) => string> = {
+  price: (_currency, per) => per, pnl: (_currency, per) => per, delta: () => "shares", gamma: () => "shares per 1.00 move",
+  thetaPerDay: (currency) => `${currency} per day`, vegaPerPoint: (currency) => `${currency} per vol point`,
+  rhoPerPoint: (currency) => `${currency} per rate point`,
+};
 
 export const optionsScenarioHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle", argument: { kind: "ticker", description: "Underlying ticker" },
@@ -40,7 +47,8 @@ export const optionsScenarioHeadless: HeadlessPaneDefinition<"bundle"> = {
   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. --strategy csp sells a cash-secured put: cash secured, premium, yield on cash, annualised yield, "
-    + "distance out of the money, break-even, days to expiry and whether earnings fall before expiry. --strategy collar buys a put and sells "
+    + "the bid, ask and spread with the yield at the bid, distance out of the money, break-even, days to expiry and whether earnings fall "
+    + "before expiry; CSP ranks the same put across several names. --strategy collar buys a put and sells "
     + "a call against the shares they cover: net premium, floor, cap and breakevens of the hedged position.",
   discovery: { screenshotReadiness: "ready", limitations: ["European scenario values do not model early assignment or exercise."] },
   options: [
@@ -53,6 +61,8 @@ export const optionsScenarioHeadless: HeadlessPaneDefinition<"bundle"> = {
         + "csp, one short put sold at its midpoint with the cash to buy the shares set aside (a cash-secured put), "
         + "or collar, one long put and one short call on the same expiry with the shares they cover" },
     { key: "strike", type: "string", description: "The --strategy strike: the put, the vertical's long call or the straddle. Nearest the money when omitted" },
+    { key: "delta", type: "string", placeholder: "0.30", example: "--strategy csp --delta 0.30 --expiration 2026-11-20",
+      description: "The --strategy csp or put put by its delta instead of --strike: the one whose delta is nearest this, as a put's delta reads without its sign" },
     { key: "putStrike", aliases: ["put-strike"], type: "string",
       description: "The --strategy collar put bought. The quoted strike nearest 10% below spot when omitted" },
     { key: "callStrike", aliases: ["call-strike"], type: "string",
@@ -67,8 +77,8 @@ export const optionsScenarioHeadless: HeadlessPaneDefinition<"bundle"> = {
     { 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: "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: "asOf", aliases: ["as-of"], type: "string", description: `Position valuation date, as ${DATE_OPTION_EXAMPLES}, or a UTC ISO timestamp` },
+    { key: "date", type: "string", description: `Scenario date, as ${DATE_OPTION_EXAMPLES}, or a UTC ISO timestamp` },
     { 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" },
@@ -78,6 +88,11 @@ export const optionsScenarioHeadless: HeadlessPaneDefinition<"bundle"> = {
   ],
   async load(args, ctx) {
     const symbol = args.symbols[0]!;
+    // Several names to sell puts on are a screen, not one scenario.
+    const names = args.rawArgument.split(/[\s,;]+/).filter(Boolean);
+    if (names.length > 1 && args.options.strategy === "csp") {
+      throw new Error(`OSA values one underlying. To rank cash-secured puts across ${names.join(", ")}: gloom fn CSP ${names.join(" ")}`);
+    }
     const settings: Record<string, unknown> = { ...ctx.settings, ...args.options, symbol };
     // Bad hedge inputs fail before any market request.
     hedgeInputsFromSettings(settings);
@@ -118,7 +133,8 @@ export const optionsScenarioHeadless: HeadlessPaneDefinition<"bundle"> = {
     const lastPrint = midVolatility && !supplied(settings.spot) && market.spot != null && money(market.spot) !== money(position!.spot)
       ? market.spot : null;
     const spotBasis = position ? scenarioSpotBasis(settings, position, market) : null;
-    const csp = position && settings.strategy === "csp" ? cashSecuredPut(position, spotBasis!, earningsDate) : null;
+    const csp = position && settings.strategy === "csp"
+      ? cashSecuredPut(position, spotBasis!, earningsDate, seededLegQuotes(position, market.chain).get(position.legs[0]?.id ?? "")) : null;
     // A collar seeded, or one typed with the shares it hedges.
     const collar = position && (settings.strategy === "collar" || position.underlying) ? scenarioCollar(position, spotBasis!) : null;
     const lastSession = market.underlyingQuote && spotBasis === "implied by option quotes"
@@ -129,6 +145,10 @@ export const optionsScenarioHeadless: HeadlessPaneDefinition<"bundle"> = {
     // 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}`;
+    // What an export names beside each number: the currency (or `currency unknown`) and what it is for.
+    const exportCurrency = position ? amountUnit(position.currency) : "";
+    const exportPer = `${exportCurrency} ${valueUnit}`;
+    const perShare = `${exportCurrency} ${PRICE_UNIT}`;
     return {
       freshness: scenarioFreshness(market, suppliedInputs),
       sections: scenario ? [
@@ -141,16 +161,16 @@ export const optionsScenarioHeadless: HeadlessPaneDefinition<"bundle"> = {
         ], rows: position!.legs.map((leg) => ({ ...leg, expiry: new Date(leg.expiration * 1000).toISOString().slice(0, 10),
           ...(midVolatility ? { volatilityFrom: leg.volatilitySource === "mid" ? "quote mid" : "provider" } : {}) })) },
         { title: "Inputs", entries: [
-          { key: "spot", label: lastPrint != null ? "Spot implied by option quotes" : "Spot", value: position!.spot,
+          { key: "spot", label: lastPrint != null ? "Spot implied by option quotes" : "Spot", value: position!.spot, unit: perShare,
             formatted: `${money(position!.spot)} ${PRICE_UNIT}${lastPrint == null && spotBasis !== "last price" ? ` (${scenarioSpotStamp(spotBasis!, position!.asOf)})` : ""}` },
-          ...(lastPrint != null ? [{ key: "last", label: "Last price", value: lastPrint,
+          ...(lastPrint != null ? [{ key: "last", label: "Last price", value: lastPrint, unit: perShare,
             formatted: `${money(lastPrint)} ${PRICE_UNIT}${lastSession && lastSession !== "last price" ? ` (${scenarioSpotStamp(lastSession, market.asOf)})` : ""}` }] : []),
-          ...(position!.underlying ? [{ key: "shares", label: "Shares held", value: position!.underlying.quantity,
+          ...(position!.underlying ? [{ key: "shares", label: "Shares held", value: position!.underlying.quantity, unit: "shares",
             formatted: `${position!.underlying.quantity.toLocaleString("en-US")} at ${money(position!.underlying.price)} ${PRICE_UNIT}` }] : []),
           { key: "asOf", label: "Valued at", value: new Date(position!.asOf).toISOString(), formatted: formatSpotTime(position!.asOf) },
-          { key: "rate", label: "Rate", value: position!.rate, formatted: percent(position!.rate) },
+          { key: "rate", label: "Rate", value: exportPercent(position!.rate), unit: "%", formatted: percent(position!.rate) },
           // A yield read as 0 because no dividend was paid, or the dividend stopped, says so; a stated or typed one is the figure alone.
-          { key: "dividendYield", label: "Dividend yield", value: position!.dividendYield, formatted: percent(position!.dividendYield)
+          { key: "dividendYield", label: "Dividend yield", value: exportPercent(position!.dividendYield), unit: "%", formatted: percent(position!.dividendYield)
             + (dividendNote ? ` (${dividendNote})` : "") },
           { key: "currency", label: "Currency", value: position!.currency, formatted: currency! },
         ] },
@@ -158,12 +178,13 @@ export const optionsScenarioHeadless: HeadlessPaneDefinition<"bundle"> = {
         ...(csp ? [{ title: "Cash-secured put", entries: cspReportEntries(csp) }] : []),
         ...(collar ? [{ title: "Collar", entries: collarReportEntries(collar) }] : []),
         { title: `Valuation (${per})`, entries: Object.entries(scenario.valuation).map(([key, value]) => ({ key,
-          label: VALUATION_LABELS[key]?.(currency!) ?? key, value, formatted: money(value) })) },
+          label: VALUATION_LABELS[key]?.(currency!) ?? key, value, formatted: money(value),
+          ...(VALUATION_UNITS[key] ? { unit: VALUATION_UNITS[key]!(exportCurrency, exportPer) } : {}) })) },
         { title: `Expiry risk (${per})`, entries: [
-          { key: "breakevens", label: "Breakevens (spot)", value: scenario.expiryRisk.breakevens,
+          { key: "breakevens", label: "Breakevens (spot)", value: scenario.expiryRisk.breakevens, unit: perShare,
             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) },
+          { key: "maxProfit", label: "Max profit", value: scenario.expiryRisk.maxProfit, unit: exportPer, formatted: scenario.expiryRisk.unlimitedProfit ? "Unlimited" : money(scenario.expiryRisk.maxProfit) },
+          { key: "maxLoss", label: "Max loss", value: scenario.expiryRisk.maxLoss, unit: exportPer, formatted: scenario.expiryRisk.unlimitedLoss ? "Unlimited" : money(scenario.expiryRisk.maxLoss) },
           ...(scenario.expiryRisk.reason ? [{ key: "limitation", label: "Limitation", value: scenario.expiryRisk.reason }] : []),
         ] },
         { title: `Scenario grid (P&L, ${per})`, columns: [