gloomberb 0.18.2 → 0.18.4

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

@@ -0,0 +1,165 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { DataTableView, PaneStatusBody, QueryBar, usePaneFooter, usePaneNoticeFooter, type DataTableColumn, type DataTableKeyEvent } from "../../../components";
+import { useAsyncResource } from "../../../react/async-resource";
+import { useAutoRefresh } from "../../../react/auto-refresh";
+import { usePaneSettingValue, usePluginAppActions } from "../../../public/react";
+import { useThemeColors } from "../../../theme/theme-context";
+import type { PaneProps } from "../../../types/plugin";
+import { Box } from "../../../ui";
+import { parsePublicTickerKey } from "../../../utils/exchanges";
+import { compareSortValues, nextHeaderSort, type SortDirection } from "../../../utils/sort-values";
+import { useAssetData } from "../../runtime";
+import { createScenarioDependencies } from "./client";
+import { cspScreenNotes, cspScreenReportRow, type CspScreenReportRow } from "./csp-screen-headless";
+import { CSP_SCREEN_DEFAULTS, CSP_SCREEN_LIMIT, cspScreenCriteriaText, cspTargetDate, loadCspScreen, readCspScreenCriteria, type CspScreenRow } from "./csp-screen";
+import { formatHedgePrice } from "./hedge";
+
+type ScreenRow = CspScreenReportRow & { source: CspScreenRow };
+
+const COLUMNS: DataTableColumn[] = [
+  { id: "rank", label: "#", width: 3, align: "right" },
+  { id: "symbol", label: "Symbol", width: 7, align: "left" },
+  { id: "expiry", label: "Expiry", width: 10, align: "right" },
+  { id: "days", label: "DTE", width: 4, align: "right" },
+  { id: "strike", label: "Strike", width: 8, align: "right" },
+  { id: "bid", label: "Bid", width: 7, align: "right" },
+  { id: "ask", label: "Ask", width: 7, align: "right" },
+  { id: "spread", label: "Spread", width: 11, align: "right" },
+  { id: "delta", label: "Delta", width: 6, align: "right" },
+  { id: "otm", label: "OTM", width: 6, align: "right" },
+  { id: "midYield", label: "Mid yield/yr", width: 12, align: "right" },
+  { id: "bidYield", label: "Bid yield/yr", width: 12, align: "right" },
+  { id: "ivRank", label: "IVR", width: 4, align: "right" },
+  { id: "earnings", label: "Earnings", width: 17, align: "left" },
+];
+
+const DELTA_OPTIONS = ["0.10", "0.15", "0.20", "0.25", "0.30", "0.35", "0.40", "0.50"];
+const DAYS_OPTIONS = ["7", "14", "21", "30", "45", "60", "90"];
+const SYMBOLS_FIELD_WIDTH = 24;
+/** Symbols apply once typing pauses, so a half-typed ticker does not start a screen. */
+const SYMBOLS_DEBOUNCE_MS = 700;
+
+const symbolList = (text: string) => [...new Set(text.split(/[\s,;]+/).map((symbol) => symbol.trim().toUpperCase()).filter(Boolean))];
+const percentText = (value: unknown, digits: number) => typeof value === "number" ? `${value.toFixed(digits)}%` : "--";
+const priceText = (value: unknown) => typeof value === "number" ? formatHedgePrice(value) : "--";
+/** A column's value to sort on: earnings by date, a flag as a number. */
+function sortValue(row: CspScreenReportRow, columnId: string): string | number | null {
+  if (columnId === "earnings") return row.earningsDate;
+  const value = row[columnId as keyof CspScreenReportRow];
+  return typeof value === "boolean" ? Number(value) : value;
+}
+/** A select's options with the current value kept when it is not a preset (a delta typed on the command line). */
+const withCurrent = (presets: readonly string[], current: string, label: (value: string) => string) =>
+  [...new Set([...presets, current])].sort((a, b) => Number(a) - Number(b)).map((value) => ({ value, label: label(value) }));
+
+export function CspScreenPane({ width, height, focused }: PaneProps) {
+  const colors = useThemeColors();
+  const [symbolsText, setSymbolsText] = usePaneSettingValue<string>("symbols", "");
+  const [delta, setDelta] = usePaneSettingValue<string | number>("delta", "");
+  const [days, setDays] = usePaneSettingValue<string | number>("days", "");
+  const [expiration, setExpiration] = usePaneSettingValue<string | number>("expiration", "");
+  const [maxSpread] = usePaneSettingValue<string | number>("maxSpread", "");
+  const [symbolsActive, setSymbolsActive] = useState(false);
+  const { createPaneFromTemplate } = usePluginAppActions();
+  const assetData = useAssetData();
+  const typed = useMemo(() => symbolList(String(symbolsText ?? "")), [symbolsText]);
+  // The screen reads the first names it can rank; the footer names the rest.
+  const symbols = useMemo(() => typed.slice(0, CSP_SCREEN_LIMIT), [typed]);
+  const leftOut = typed.slice(CSP_SCREEN_LIMIT);
+  const criteria = useMemo(() => {
+    try { return { value: readCspScreenCriteria({ delta, days, expiration, maxSpread }), error: null }; }
+    catch (error) { return { value: null, error: error instanceof Error ? error.message : String(error) }; }
+  }, [delta, days, expiration, maxSpread]);
+  const controller = useRef<AbortController | null>(null);
+  const key = JSON.stringify([symbols, criteria.value]);
+  const loader = useCallback(async () => {
+    controller.current?.abort();
+    const current = new AbortController();
+    controller.current = current;
+    return loadCspScreen(symbols.map((symbol) => parsePublicTickerKey(symbol)), criteria.value!,
+      { scenario: createScenarioDependencies(), earnings: assetData }, current.signal);
+  }, [key, assetData]);
+  const resource = useAsyncResource(symbols.length && criteria.value ? loader : null);
+  useEffect(() => () => controller.current?.abort(), [loader]);
+  useAutoRefresh(resource.updatedAt, resource.load);
+  const [sort, setSort] = useState<{ columnId: string; direction: SortDirection }>({ columnId: "rank", direction: "asc" });
+  const rows = useMemo<ScreenRow[]>(() => {
+    const flat = (resource.data?.rows ?? []).map((row) => ({ ...cspScreenReportRow(row), source: row }));
+    // Unranked names stay under the ranked ones whichever way rank sorts.
+    return flat.sort((left, right) => sort.columnId === "rank"
+      ? compareSortValues(left.rank ?? Number.POSITIVE_INFINITY, right.rank ?? Number.POSITIVE_INFINITY, sort.direction)
+      : compareSortValues(sortValue(left, sort.columnId), sortValue(right, sort.columnId), sort.direction));
+  }, [resource.data, sort]);
+  const [selected, setSelected] = useState<string | null>(null);
+  const screen = resource.data;
+  const notices = [criteria.error, resource.data ? null : resource.error,
+    leftOut.length ? `Ranks the first ${CSP_SCREEN_LIMIT} symbols; ${leftOut.length} left out: ${leftOut.join(", ")}` : null,
+    ...(screen?.ivRankError ? [`IV rank unavailable: ${screen.ivRankError}`] : []),
+    ...(screen?.rows ?? []).flatMap((row) => row.note ? [`${row.symbol}: ${row.note}`] : []),
+    ...(screen ? cspScreenNotes(screen).slice(1) : [])].filter((value): value is string => !!value);
+  usePaneNoticeFooter({ registrationId: "csp-screen-notices", notices, focused });
+  // The bar names the delta and the expiry; the footer says only what changes.
+  usePaneFooter("csp-screen", () => ({ info: [
+    ...(resource.loading ? [{ id: "loading", parts: [{ text: "loading", tone: "muted" as const }] }] : []),
+  ] }), [resource.loading]);
+  const criteriaText = criteria.value ? cspScreenCriteriaText(criteria.value, Date.now()) : "";
+  // Enter opens the name's put in OSA, at the strike and expiry the screen read.
+  const openScenario = (row: ScreenRow) => {
+    const csp = row.source.csp;
+    if (!csp) return;
+    createPaneFromTemplate("options-scenario-pane", { symbol: row.symbol, values: { strategy: "csp", strike: String(csp.strike), expiration: csp.expiry } });
+  };
+  const handleKey = (event: DataTableKeyEvent): boolean => {
+    if (event.ctrl || event.alt || event.meta || event.name !== "r") return false;
+    void resource.reload();
+    event.preventDefault?.(); event.stopPropagation?.(); return true;
+  };
+  const cell = (row: ScreenRow, id: string): { text: string; color?: string } => {
+    switch (id) {
+      case "rank": return { text: row.rank == null ? "" : String(row.rank), color: colors.textDim };
+      case "symbol": return { text: row.symbol, color: colors.textBright };
+      case "expiry": return { text: String(row.expiry ?? "--"), color: colors.textDim };
+      case "days": return { text: row.days == null ? "--" : String(row.days) };
+      case "strike": return { text: row.strike == null ? "--" : String(row.strike) };
+      case "bid": return { text: priceText(row.bid) };
+      case "ask": return { text: priceText(row.ask) };
+      case "spread": return { text: `${percentText(row.spread, 1)}${row.wide ? " wide" : ""}`, color: row.wide ? colors.warning : undefined };
+      case "delta": return { text: typeof row.delta === "number" ? row.delta.toFixed(2) : "--" };
+      case "otm": return { text: percentText(row.otm, 1) };
+      case "midYield": return { text: percentText(row.midYield, 2), color: colors.textDim };
+      case "bidYield": return { text: percentText(row.bidYield, 2), color: colors.positive };
+      case "ivRank": return { text: typeof row.ivRank === "number" ? row.ivRank.toFixed(0) : "--" };
+      case "earnings": return { text: String(row.earnings), color: row.earningsBeforeExpiry === true ? colors.warning : colors.textDim };
+      default: return { text: "" };
+    }
+  };
+  const deltaValue = criteria.value ? criteria.value.delta.toFixed(2) : CSP_SCREEN_DEFAULTS.delta.toFixed(2);
+  const daysValue = String(criteria.value?.days ?? CSP_SCREEN_DEFAULTS.days);
+  // A date typed on the command line is the expiry's choice until a number of days is picked.
+  const typedDate = criteria.value?.expiration != null ? cspTargetDate(criteria.value, Date.now()) : null;
+  return <Box width={width} height={height} flexDirection="column" overflow="hidden">
+    <QueryBar width={width} filters={[
+      { id: "symbols", kind: "text" as const, label: "Symbols", value: String(symbolsText ?? ""), placeholder: "JPM, GS, KO",
+        width: SYMBOLS_FIELD_WIDTH, debounceMs: SYMBOLS_DEBOUNCE_MS, focused, active: symbolsActive, onActiveChange: setSymbolsActive,
+        onChange: setSymbolsText },
+      { id: "delta", label: "Delta", value: deltaValue, defaultValue: CSP_SCREEN_DEFAULTS.delta.toFixed(2),
+        options: withCurrent(DELTA_OPTIONS, deltaValue, (value) => value), onChange: (value: string) => setDelta(value) },
+      { id: "expiry", label: "Expiry", value: typedDate ?? daysValue, defaultValue: String(CSP_SCREEN_DEFAULTS.days),
+        options: [...withCurrent(DAYS_OPTIONS, daysValue, (value) => `${value} days`), ...(typedDate ? [{ value: typedDate, label: typedDate }] : [])],
+        onChange: (value: string) => { if (value === typedDate) return; setExpiration(""); setDays(value); } },
+    ]} />
+    <PaneStatusBody subject="cash-secured puts" loading={resource.loading && !resource.data}
+      error={criteria.error && !criteria.value ? criteria.error : !resource.data ? resource.error : null}>
+      <DataTableView<ScreenRow> focused={focused && !symbolsActive} columns={COLUMNS} items={rows} rootWidth={width}
+        rootHeight={Math.max(2, height - 1)}
+        getItemKey={(row) => row.symbol} sortColumnId={sort.columnId} sortDirection={sort.direction}
+        emptyStateTitle={symbols.length ? "No puts to rank." : "Type symbols to rank their cash-secured puts."}
+        onHeaderClick={(id) => setSort((current) => nextHeaderSort(current, id, { firstDirection: id === "rank" || id === "symbol" ? "asc" : "desc" }))}
+        selection={{ kind: "id", selectedId: selected ?? rows[0]?.symbol ?? "", getId: (row) => row.symbol, onChange: (id) => setSelected(id) }}
+        onActivate={openScenario} onRootKeyDown={handleKey}
+        getExportMetadata={() => [["puts", criteriaText || undefined], ["ranked by", "annualised yield on cash at the bid"],
+          ["wide", criteria.value ? `spread over ${criteria.value.maxSpreadPercent}% of the mid` : undefined]]}
+        renderCell={(row, column) => cell(row, column.id)} />
+    </PaneStatusBody>
+  </Box>;
+}

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" },