gloomberb 0.17.0 → 0.17.2

package/src/plugins/builtin/options/view.tsx

@@ -6,7 +6,9 @@ import { isPlainKey } from "../../../utils/keyboard";
 import { formatCompact, formatPercentRaw } from "../../../utils/format";
 import { formatMarketPrice, formatSignedMarketPrice, liveQuoteFormatOptions } from "../../../market-data/market/format";
 import { formatExpDate, resolveOptionsTarget } from "../../../utils/options";
-import { expiryIsoDate, findListedExpiry, formatDaysToExpiry, daysToExpiry, missingExpiryText, readOptionExpiration } from "../../../utils/option-expiry";
+import {
+  expiryIsoDate, findListedExpiry, formatDaysToExpiry, daysToExpiry, missingExpiryMessage, missingExpiryText, readOptionExpiration,
+} from "../../../utils/option-expiry";
 import { canonicalTickerKey } from "../../../utils/exchanges";
 import { isOptionsUnavailableError, listedOptionsAlternative, optionsUnavailableTitle } from "../../../market-data/options-alternatives";
 import { useChartQueries, useOptionsQuery, useResolvedEntryValue, useTickerFinancials } from "../../../market-data/hooks";
@@ -72,6 +74,9 @@ import { useIvRank } from "../iv-history/rank";
 import { useOptionsSessionOpen, useThrottledValue } from "../shared/volatility/live-session";
 import { useRemoteUiNode } from "../../../remote/semantic-tree";
 import { optionCarry, optionCostOfSpot } from "./carry";
+import { formatModelSpotPrice, modelSpotLabel, optionModelSpot } from "./model-spot";
+import { chainOpenInterestAsOf, loadListedOpenInterest, openInterestAsOfLabel, statedOpenInterestAsOf } from "./open-interest-as-of";
+import { useAsyncResource } from "../../../react/async-resource";
 import {
   ALL_STRIKES,
   STRIKE_WINDOW_PRESETS,
@@ -374,9 +379,12 @@ export function OptionsView({ width, height, focused, nestedInTabs = false, ivRa
     () => resolveDefaultStrikeTarget(parsed?.strike, underlyingPrice),
     [strikeChain, parsed?.strike, underlyingPrice == null],
   );
-  const windowSpot = useMemo(() => spot, [strikeChain, spot == null]);
+  // The band reads deltas at the spot and instant the chain's Greeks are valued at, so a strike in it prints a delta in it.
+  const windowSpot = useMemo(() => optionModelSpot(underlyingStale ? null : underlying?.quote, strikeChain, Date.now(), effectiveExchange),
+    [strikeChain, spot == null]);
   const windowDeltas = useMemo(
-    () => strikeWindow.kind === "delta" && strikeChain ? chainDeltasByStrike(strikeChain, windowSpot, dividendYield) : null,
+    () => strikeWindow.kind === "delta" && strikeChain
+      ? chainDeltasByStrike(strikeChain, windowSpot?.price, dividendYield, windowSpot?.valuationTime) : null,
     [dividendYield, strikeChain, strikeWindow.kind, windowSpot],
   );
   const strikeWindowResult = useMemo(
@@ -396,7 +404,7 @@ export function OptionsView({ width, height, focused, nestedInTabs = false, ivRa
   const expiryAsOfMs = Number.isFinite(chainAsOfMs) ? chainAsOfMs : Date.now();
   const expiryDate = selectedExpiration == null ? "" : expiryIsoDate(selectedExpiration);
   const expiryDays = selectedExpiration == null ? "" : formatDaysToExpiry(selectedExpiration, expiryAsOfMs);
-  useRemoteUiNode(expiryDate && chain ? {
+  useRemoteUiNode(expiryDate && chain && !expirationUnavailable ? {
     role: "report-notice",
     label: "Expiry",
     getMetadata: () => ({
@@ -405,6 +413,12 @@ export function OptionsView({ width, height, focused, nestedInTabs = false, ivRa
       value: { date: expiryDate, daysToExpiry: daysToExpiry(selectedExpiration!, expiryAsOfMs) },
     }),
   } : null);
+  // `fn OMON --expiration` on a date the chain cannot show fails as `options --expiration` does.
+  useRemoteUiNode(expirationUnavailable && selectedExpiration != null && effectiveTicker ? {
+    role: "report-failure",
+    label: "Expiry unavailable",
+    getMetadata: () => missingExpiryMessage(effectiveTicker, selectedExpiration, availableExpirations),
+  } : null);
   // A refresh that failed keeps the last chain, which is then stale.
   const asOfEntry = strikeChain == null ? null : strikeChain === expirationChain ? expirationChainEntry : initialChainEntry;
   const chainDelay = asOfChain?.delayMinutes ?? 0;
@@ -494,11 +508,18 @@ export function OptionsView({ width, height, focused, nestedInTabs = false, ivRa
     () => new Map(liveChain?.puts.map((p) => [p.strike, p]) ?? []),
     [liveChain],
   );
+  // IV and the Greeks are valued at one spot and instant, which the footer
+  // names: the close a chain from the close was quoted against, else the
+  // latest price (docs/research-data.md#greeks-spot-and-time).
+  const underlyingQuote = underlyingStale ? null : underlying?.quote;
+  const modelSpot = useMemo(() => liveChain ? optionModelSpot(underlyingQuote, liveChain, Date.now(), effectiveExchange) : null,
+    [liveChain, underlyingQuote, effectiveExchange]);
+  const greeksSpot = modelSpot?.price;
   // One solve per applied batch: a streamed contract's IV comes from its live
   // midpoint, the rest from the snapshot, all against the same forward.
   const volatilities = useMemo(
-    () => liveChain ? solveChainVolatilities(liveChain, spot, dividendYield) : null,
-    [dividendYield, spot, liveChain],
+    () => liveChain ? solveChainVolatilities(liveChain, greeksSpot, dividendYield, modelSpot?.valuationTime) : null,
+    [dividendYield, greeksSpot, modelSpot?.valuationTime, liveChain],
   );
   const rows = useMemo<OptionTableRow[]>(() => strikes.map((strike) => {
     const call = callsByStrike.get(strike);
@@ -508,14 +529,51 @@ export function OptionsView({ width, height, focused, nestedInTabs = false, ivRa
       call,
       put,
       impliedVolatility: volatilities?.byStrike.get(strike),
-      callGreeks: volatilities ? calculateOptionGreeks(call, "call", spot, dividendYield, volatilities) : undefined,
-      putGreeks: volatilities ? calculateOptionGreeks(put, "put", spot, dividendYield, volatilities) : undefined,
-      callExtrinsicPerYear: call && volatilities ? optionCarry(call, "call", spot, volatilities.valuationTime)?.extrinsicPerYear ?? null : null,
-      putExtrinsicPerYear: put && volatilities ? optionCarry(put, "put", spot, volatilities.valuationTime)?.extrinsicPerYear ?? null : null,
+      callGreeks: volatilities ? calculateOptionGreeks(call, "call", greeksSpot, dividendYield, volatilities) : undefined,
+      putGreeks: volatilities ? calculateOptionGreeks(put, "put", greeksSpot, dividendYield, volatilities) : undefined,
+      callExtrinsicPerYear: call && volatilities ? optionCarry(call, "call", greeksSpot, volatilities.valuationTime)?.extrinsicPerYear ?? null : null,
+      putExtrinsicPerYear: put && volatilities ? optionCarry(put, "put", greeksSpot, volatilities.valuationTime)?.extrinsicPerYear ?? null : null,
       putCostOfSpot: put ? optionCostOfSpot(put, spot) : null,
       isPositionStrike: !!parsed && strike === parsed.strike,
     };
-  }), [callsByStrike, dividendYield, parsed, putsByStrike, spot, strikes, volatilities]);
+  }), [callsByStrike, dividendYield, greeksSpot, parsed, putsByStrike, spot, strikes, volatilities]);
+  // The open interest's session: the chain's own, or for a chain that does not say, OPX's listing of the
+  // same expiry, stated only when the counts are OPX's.
+  const statedOpenInterest = useMemo(() => strikeChain ? statedOpenInterestAsOf(strikeChain) : undefined, [strikeChain]);
+  const listedExpiry = selectedExpiration == null || !effectiveTicker || !strikeChain || statedOpenInterest
+    ? null : expiryIsoDate(selectedExpiration);
+  const listedLoader = useCallback(() => loadListedOpenInterest(effectiveTicker, listedExpiry!), [effectiveTicker, listedExpiry]);
+  const listedOpenInterest = useAsyncResource(listedExpiry ? listedLoader : null);
+  const openInterestAsOf = useMemo(() => statedOpenInterest
+    ?? (strikeChain && listedOpenInterest.data ? chainOpenInterestAsOf(strikeChain, listedOpenInterest.data) : null),
+  [statedOpenInterest, strikeChain, listedOpenInterest.data]);
+  // A report of the pane (`gloomberb fn OMON`) names them too.
+  useRemoteUiNode(modelSpot ? {
+    role: "report-notice",
+    label: "Greeks spot",
+    getMetadata: () => ({
+      text: `Greeks at spot ${formatModelSpotPrice(modelSpot.price)} (${modelSpotLabel(modelSpot)})`,
+      key: "greeksSpot",
+      value: { spot: modelSpot.price, basis: modelSpot.basis === "close" ? "close" : modelSpot.session ?? "last",
+        asOf: new Date(modelSpot.observedAt).toISOString(), valuationTime: new Date(modelSpot.valuationTime).toISOString() },
+    }),
+  } : null);
+  useRemoteUiNode(strikeChain && !listedOpenInterest.loading ? {
+    role: "report-notice",
+    label: "Open interest as of",
+    getMetadata: () => ({ text: openInterestAsOfLabel(openInterestAsOf), key: "openInterestAsOf", value: openInterestAsOf?.date ?? null }),
+  } : null);
+  // What IV and the Greeks are valued at, and the open interest's date. In a
+  // crowded footer it shortens, then gives way to the contract under the cursor.
+  const basisText = [modelSpot ? `spot ${formatModelSpotPrice(modelSpot.price)} ${modelSpotLabel(modelSpot)}` : null,
+    strikeChain && !listedOpenInterest.loading ? openInterestAsOfLabel(openInterestAsOf) : null].filter(Boolean).join(" · ");
+  const shortBasisText = [modelSpot ? `${formatModelSpotPrice(modelSpot.price)} ${modelSpot.basis === "close" ? "close" : modelSpot.session ?? "last"} `
+    + `${new Date(modelSpot.observedAt).toISOString().slice(11, 16)} UTC` : null,
+  strikeChain && !listedOpenInterest.loading ? openInterestAsOf?.date ? `OI ${openInterestAsOf.date.slice(5)}` : "OI undated" : null]
+    .filter(Boolean).join(" · ");
+  usePaneFooter("options-basis", () => ({ info: basisText ? [{ id: "greeks-basis",
+    parts: [{ text: basisText, tone: "muted" as const }],
+    variants: [[{ text: shortBasisText, tone: "muted" as const }], []] }] : [] }), [basisText, shortBasisText]);
   // Figures that summarise the whole expiry move at most once a second, so a
   // busy stream reads as a steady strip rather than flicker.
   // A new expiry, a refreshed snapshot or the underlying price arriving or

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

@@ -1,11 +1,12 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { FieldGrid, KeyValueRow, QueryBar, usePaneFooter, usePaneNoticeFooter, type GridField } from "../../../components";
+import { CompositeChart } from "../../../components/chart/composite/composite-chart";
 import { useAsyncResource, useInputCapture } from "../../../public/react";
 import { useShortcut } from "../../../react/input";
 import { useAppSelector, usePaneInstance, usePaneStateValue } from "../../../state/app/context";
 import { colors } from "../../../theme/colors";
 import type { PaneProps } from "../../../types/plugin";
-import { Box, ScrollBox } from "../../../ui";
+import { Box, ScrollBox, Text } from "../../../ui";
 import { formatNumber } from "../../../utils/format";
 import { isPlainKey } from "../../../utils/keyboard";
 import { OPTIONS_CALCULATOR_PANE_ID, describeDraftProblem, draftFromParams, reconcileOptionCalcDraft, updateOptionCalcDraft, type OptionCalcDraft } from "./model";
@@ -20,6 +21,8 @@ import { useThrottledValue } from "../shared/volatility/live-session";
 import { valueBinomialOption, solveBinomialImpliedVolatility, effectiveBinomialSteps } from "./binomial";
 import { draftFromCalculatorInputs, parseCashDividends } from "./inputs";
 import { loadCalculatorSurfaceVol } from "./surface";
+import { loadContractPremiumHistory, premiumSeries } from "./premium-history";
+import type { ResolvedSeries } from "../../../time-series/types";
 import { OptionQuoteContext, optionQuoteContextHeight } from "../options/quote-context";
 import { useCalculatorEvidence, CALCULATOR_IGNORED_DIVIDENDS_NOTICE, type CalculatorScreenshotSnapshot } from "./evidence";
 
@@ -89,6 +92,12 @@ export function OptionsCalculatorPane({ focused, width, height }: PaneProps) {
   // any edit is theirs and ends the link for that input.
   const liveStreaming = useLiveStreamingSetting();
   const reference = draft.marketReference;
+  const contractSymbol = screenshotSnapshot ? null : reference?.contractSymbol ?? null;
+  const loadPremium = useCallback(async () => {
+    if (!contractSymbol) return [];
+    return loadContractPremiumHistory(contractSymbol);
+  }, [contractSymbol]);
+  const premiumResource = useAsyncResource(contractSymbol ? loadPremium : null);
   const priceLinked = !screenshotSnapshot && !!draft.marketPriceSource && !!reference && !!draft.symbol;
   const spotLinked = priceLinked && draft.spot === seed.spot;
   // One stable subscription while the price is linked: dropping the
@@ -331,6 +340,15 @@ export function OptionsCalculatorPane({ focused, width, height }: PaneProps) {
         {linkedDraft.marketReference && <Box paddingX={1} height={referenceHeight} flexShrink={0}>
           <OptionQuoteContext reference={linkedDraft.marketReference} width={resultWidth} height={referenceHeight} snapshot={!liveInputs} scrollable={false} />
         </Box>}
+        {contractSymbol ? (
+          <ContractPremiumChart
+            series={premiumSeries(premiumResource.data ?? [], colors.positive)}
+            loading={premiumResource.loading && !premiumResource.data}
+            unavailable={premiumResource.error != null && !premiumResource.data}
+            width={resultWidth}
+            focused={focused}
+          />
+        ) : null}
 
         <Box flexDirection={pairMetrics ? "row" : "column"} paddingX={1}>
           <KeyValueRow
@@ -366,6 +384,43 @@ export function OptionsCalculatorPane({ focused, width, height }: PaneProps) {
   );
 }
 
+const PREMIUM_CHART_ROWS = 8;
+
+function ContractPremiumChart({
+  series,
+  loading,
+  unavailable,
+  width,
+  focused,
+}: {
+  series: ResolvedSeries[];
+  loading: boolean;
+  unavailable: boolean;
+  width: number;
+  focused: boolean;
+}) {
+  const empty = unavailable ? "Premium history unavailable." : series.length < 1 ? "No premium history." : undefined;
+  return (
+    <Box flexDirection="column" paddingX={1} height={PREMIUM_CHART_ROWS} flexShrink={0}>
+      {empty && !loading ? (
+        <Text fg={colors.textDim}>{empty}</Text>
+      ) : (
+        <CompositeChart
+          series={series}
+          panels={[{ id: "main" }]}
+          width={width}
+          height={PREMIUM_CHART_ROWS}
+          focused={focused}
+          navigable={false}
+          remoteKind="option-premium-history"
+          formatValue={(value) => formatNumber(value, 2)}
+          emptyMessage={loading ? "Loading..." : "No premium history."}
+        />
+      )}
+    </Box>
+  );
+}
+
 function SurfaceNotices({ notices, focused }: { notices: string[]; focused: boolean }) {
   usePaneNoticeFooter({ registrationId: "ovme-surface-notices", notices, focused });
   return null;

package/src/plugins/builtin/options-calculator/premium-history.ts

@@ -0,0 +1,34 @@
+import { apiClient } from "../../../api-client";
+import { scalarPoint, staticSeries } from "../../../components/chart/static/series";
+import type { ResolvedSeries } from "../../../time-series/types";
+import { OPTIONS_QUOTE_EXCHANGE } from "../options/live-quotes";
+
+/** Daily closes for one listed contract. A typed premium has no contract to chart. */
+export async function loadContractPremiumHistory(
+  contractSymbol: string,
+  signal?: AbortSignal,
+): Promise<{ date: string; close: number }[]> {
+  const response = await apiClient.getCloudHistory(contractSymbol, OPTIONS_QUOTE_EXCHANGE, {
+    interval: "1day",
+    outputsize: 400,
+  }, signal ? { signal } : {});
+  const rows = response.data ?? [];
+  return rows.flatMap((row) => {
+    const close = row.close;
+    if (!row.date || !Number.isFinite(close) || close < 0) return [];
+    const time = Date.parse(row.date);
+    if (!Number.isFinite(time)) return [];
+    return [{ date: row.date, close }];
+  });
+}
+
+export function premiumSeries(
+  rows: readonly { date: string; close: number }[],
+  color: string,
+): ResolvedSeries[] {
+  if (rows.length < 2) return [];
+  return [staticSeries(
+    rows.map((row) => scalarPoint(new Date(row.date), row.close)),
+    { id: "premium", label: "Premium", color, calendarSpaced: true },
+  )];
+}

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

@@ -12,6 +12,7 @@ import { daysToExpiryFrom, extractImpliedForward, optionMid, solveImpliedVolatil
 import type { YieldPoint } from "../yield-curve/treasury-data";
 import { parseLegs, scenarioCurrency, validatePosition, type ScenarioControls, type ScenarioLeg, type ScenarioPosition } from "./model";
 import { abortable, abortError } from "../../../utils/async-deadline";
+import { extendedSession } from "../options/model-spot";
 import { errorMessage } from "../../../utils/errors";
 
 export interface ScenarioMarketSnapshot {
@@ -153,6 +154,26 @@ export async function loadScenarioMarket(
 
 const sentence = (text: string) => text.charAt(0).toUpperCase() + text.slice(1);
 
+const cents = (value: number) => value.toFixed(2);
+
+/**
+ * What the scenario's spot is, in words, for the labels that name it: `typed`
+ * for a what-if, `implied by option quotes` for a seeded strategy whose quote
+ * mids imply another spot than the last print, else the last price and its
+ * session (`pre-market`, `after hours`), or `input` without a market.
+ */
+export function scenarioSpotBasis(
+  settings: Record<string, unknown>,
+  position: Pick<ScenarioPosition, "spot" | "legs">,
+  market: Pick<ScenarioMarketSnapshot, "spot" | "underlyingQuote"> | null | undefined,
+): string {
+  if (supplied(settings.spot)) return "typed";
+  const marketSpot = market?.spot;
+  if (marketSpot == null) return "input";
+  if (position.legs.some((leg) => leg.volatilitySource === "mid") && cents(marketSpot) !== cents(position.spot)) return "implied by option quotes";
+  return (market?.underlyingQuote ? extendedSession(market.underlyingQuote) : null) ?? "last price";
+}
+
 function supplied(value: unknown): boolean { return value != null && value !== ""; }
 
 function numericSetting(settings: Record<string, unknown>, key: string): number | undefined {
@@ -204,9 +225,9 @@ export function scenarioPositionFromSettings(
   let legs = legText.trim() ? parseLegs(legText) : [];
   const strike = numericSetting(settings, "strike");
   if (strike != null && !(strike > 0)) throw new Error("strike must be positive");
-  if (strike != null && !supplied(settings.strategy)) throw new Error("strike picks the strike of --strategy; add --strategy put, vertical or straddle");
+  if (strike != null && !supplied(settings.strategy)) throw new Error("strike picks the strike of --strategy; add --strategy put, csp, vertical or straddle");
   if (!legs.length && supplied(settings.strategy)) {
-    if (!isScenarioStrategy(settings.strategy)) throw new Error("strategy must be vertical, straddle or put");
+    if (!isScenarioStrategy(settings.strategy)) throw new Error("strategy must be vertical, straddle, put or csp");
     if (!market?.chain || market.warnings.includes("Options chain is stale")) {
       throw new Error(market?.missingExpiry ?? "A current options chain is required to seed a strategy");
     }
@@ -242,8 +263,10 @@ export function scenarioPositionFromSettings(
   return position;
 }
 
-type ScenarioStrategy = "vertical" | "straddle" | "put";
-const isScenarioStrategy = (value: unknown): value is ScenarioStrategy => value === "vertical" || value === "straddle" || value === "put";
+/** The seeds `--strategy` builds: a call vertical, a straddle, one long put, or one short put (a cash-secured put). */
+export const SCENARIO_STRATEGIES = ["vertical", "straddle", "put", "csp"] as const;
+type ScenarioStrategy = typeof SCENARIO_STRATEGIES[number];
+const isScenarioStrategy = (value: unknown): value is ScenarioStrategy => SCENARIO_STRATEGIES.includes(value as ScenarioStrategy);
 
 interface StrategyPricing { spot: number; asOf: number; rate: number }
 
@@ -267,8 +290,9 @@ interface StrategyParity { forward: number; daysToExpiry: number }
  * scenario at the spot it implies.
  *
  * Each strategy is anchored at the strike nearest spot, or at `strike` when
- * one is given: a long put (a protective put), a call vertical from the
- * anchor to the next listed strike up, or a straddle at the anchor.
+ * one is given: a long put (a protective put), a short put (a cash-secured
+ * put, sold at the midpoint like every seed), a call vertical from the anchor
+ * to the next listed strike up, or a straddle at the anchor.
  */
 function scenarioStrategyLegs(
   chain: OptionsChain, spot: number, strategy: ScenarioStrategy, pricing: StrategyPricing | null, strike?: number,
@@ -304,13 +328,13 @@ function scenarioStrategyLegs(
     if (strike == null) return new Error("The selected chain has no complete quoted strategy with usable IV");
     const listed = [...new Set(candidates.map(({ contract }) => contract.strike))]
       .sort((a, b) => Math.abs(a - strike) - Math.abs(b - strike)).slice(0, 4).sort((a, b) => a - b);
-    return new Error(`The selected chain has no complete quoted ${strategy} at strike ${strike} with usable IV`
+    return new Error(`The selected chain has no complete quoted ${strategy === "csp" ? "put to sell" : strategy} at strike ${strike} with usable IV`
       + (listed.length ? `; nearest quoted strikes: ${listed.join(", ")}` : ""));
   };
-  if (strategy === "put") {
+  if (strategy === "put" || strategy === "csp") {
     const put = puts.find(anchored);
     if (!put) throw missing(puts);
-    return { legs: [{ id: put.contract.contractSymbol, side: "put", quantity: 1, strike: put.contract.strike,
+    return { legs: [{ id: put.contract.contractSymbol, side: "put", quantity: strategy === "csp" ? -1 : 1, strike: put.contract.strike,
       expiration: put.contract.expiration, price: put.mid, priceSource: "mid", volatility: put.volatility, multiplier: 100,
       ...(put.solved ? { volatilitySource: "mid" as const } : {}) }],
     parity: put.solved ? parityFor(put.contract.expiration) : null };

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

@@ -0,0 +1,168 @@
+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 { formatHedgePrice } from "./hedge";
+import { UNKNOWN_CURRENCY, type ScenarioPosition } from "./model";
+
+/**
+ * A cash-secured put (docs/research-data.md#cash-secured-put): one short put
+ * with the cash to buy the shares at the strike set aside. Figures, for the
+ * position as entered:
+ *
+ * - cash secured = strike x multiplier x contracts
+ * - premium received = entry price x multiplier x contracts; a `--strategy csp`
+ *   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)
+ * - 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
+ * - earnings before expiry: yes when the next report is on or before the expiry date,
+ *   no when it is after, unknown when the calendar has no upcoming date
+ */
+export interface CashSecuredPut {
+  currency: string;
+  strike: number;
+  /** Expiry calendar date, YYYY-MM-DD. */
+  expiry: string;
+  contracts: number;
+  multiplier: number;
+  /** Per share: what the put is sold at. */
+  price: number;
+  /** "mid" when a strategy seed entered the put at its quote midpoint, else the entry price as typed. */
+  priceBasis: "mid" | "entry";
+  cashSecured: number;
+  premium: number;
+  /** Premium over cash secured, as a fraction. */
+  yieldOnCash: number;
+  /** Null on the expiry day, when there is no day to annualise over. */
+  annualizedYield: number | null;
+  daysToExpiry: number;
+  /** Valuation date in New York, YYYY-MM-DD. */
+  valuationDate: string;
+  spot: number;
+  /** What the spot is: `implied by option quotes`, `typed`, `last price`. */
+  spotBasis: string;
+  /** (spot - strike) / spot as a fraction; negative when the put is in the money. */
+  outOfTheMoney: number | null;
+  breakEven: number;
+  earnings: CspEarnings;
+}
+
+export interface CspEarnings {
+  /** The next report date, YYYY-MM-DD, or null when none is published. */
+  date: string | null;
+  /** Null is unknown: no upcoming date to compare. */
+  beforeExpiry: boolean | null;
+}
+
+const DAY_MS = 86_400_000;
+const newYorkDate = new Intl.DateTimeFormat("en-CA", { timeZone: "America/New_York", year: "numeric", month: "2-digit", day: "2-digit" });
+
+/** The calendar date of a moment in New York, YYYY-MM-DD. */
+function newYorkCalendarDate(time: number): string {
+  return newYorkDate.format(time);
+}
+
+/** Whether the next report falls before the put expires; unknown without an upcoming date. */
+export function earningsBeforeExpiry(earningsDate: string | null | undefined, valuationDate: string, expiry: string): CspEarnings {
+  if (!earningsDate || !/^\d{4}-\d{2}-\d{2}$/.test(earningsDate) || earningsDate < valuationDate) return { date: null, beforeExpiry: null };
+  return { date: earningsDate, beforeExpiry: earningsDate <= expiry };
+}
+
+/**
+ * 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.
+ */
+export function cashSecuredPut(
+  position: ScenarioPosition, spotBasis: string, earningsDate: string | null | undefined,
+): CashSecuredPut | null {
+  const [leg] = position.legs;
+  if (position.legs.length !== 1 || !leg || leg.side !== "put" || leg.quantity >= 0) return null;
+  const contracts = -leg.quantity;
+  const expiry = new Date(leg.expiration * 1000).toISOString().slice(0, 10);
+  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;
+  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,
+    daysToExpiry, valuationDate, spot: position.spot, spotBasis,
+    outOfTheMoney: position.spot > 0 ? (position.spot - leg.strike) / position.spot : null,
+    breakEven: leg.strike - leg.price,
+    earnings: earningsBeforeExpiry(earningsDate, valuationDate, expiry),
+  };
+}
+
+/**
+ * The next report date from the earnings calendar, YYYY-MM-DD; null when the
+ * calendar has none for the symbol or 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;
+}
+
+const money = (value: number) => value.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+const percent = (fraction: number, digits = 2) => `${(fraction * 100).toFixed(digits)}%`;
+const unitOf = (csp: CashSecuredPut) => csp.currency && csp.currency !== UNKNOWN_CURRENCY ? ` ${csp.currency}` : "";
+const strikeText = (value: number) => formatHedgePrice(value).replace(/\.00$/, "");
+
+/** `5.5% below spot 89.98 (implied by option quotes)`, or above it for a put in the money. */
+function otmText(csp: CashSecuredPut): string {
+  if (csp.outOfTheMoney == null) return "--";
+  const side = csp.outOfTheMoney >= 0 ? "below" : "above";
+  return `${percent(Math.abs(csp.outOfTheMoney), 1)} ${side} spot ${money(csp.spot)} (${csp.spotBasis})`;
+}
+
+function earningsText(earnings: CspEarnings): string {
+  if (earnings.beforeExpiry == null) return "unknown (no upcoming date published)";
+  return `${earnings.beforeExpiry ? "yes" : "no"} (next report ${earnings.date})`;
+}
+
+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. */
+export function cspReportEntries(csp: CashSecuredPut): HeadlessPaneEntry[] {
+  const unit = unitOf(csp);
+  return [
+    { key: "cashSecured", label: "Cash secured", value: csp.cashSecured,
+      formatted: `${money(csp.cashSecured)}${unit} (${strikeText(csp.strike)} x ${csp.multiplier} x ${csp.contracts})` },
+    { key: "premium", label: "Premium received", value: csp.premium,
+      formatted: `${money(csp.premium)}${unit} (${formatHedgePrice(csp.price)} per share, ${priceWord(csp)})` },
+    { key: "yieldOnCash", label: "Yield on cash", value: csp.yieldOnCash,
+      formatted: `${percent(csp.yieldOnCash)} (${money(csp.premium)} / ${money(csp.cashSecured)})` },
+    { key: "annualizedYield", label: "Annualised yield", value: csp.annualizedYield,
+      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,
+      formatted: `${formatHedgePrice(csp.breakEven)} per share (${strikeText(csp.strike)} - ${formatHedgePrice(csp.price)})` },
+    { key: "daysToExpiry", label: "Days to expiry", value: csp.daysToExpiry,
+      formatted: `${csp.daysToExpiry} (${csp.valuationDate} to ${csp.expiry})` },
+    { key: "earningsBeforeExpiry", label: "Earnings before expiry", value: csp.earnings.beforeExpiry, formatted: earningsText(csp.earnings) },
+  ];
+}
+
+/** The pane's figures: the same numbers as the report, sized for a StatGrid. */
+export function cspStatItems(csp: CashSecuredPut): StatItem[] {
+  const earnings = csp.earnings;
+  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` },
+    { 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" },
+    { id: "csp-days", label: "DTE", value: String(csp.daysToExpiry), detail: csp.expiry },
+    { id: "csp-earnings", label: "Earnings", value: earnings.beforeExpiry == null ? "unknown" : earnings.beforeExpiry ? "before expiry" : "after expiry",
+      detail: earnings.date ?? "no date", tone: earnings.beforeExpiry ? "warning" : undefined },
+  ];
+}

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

@@ -83,6 +83,7 @@ export const scenarioScreenshotEvidence: PaneScreenshotEvidenceHook<ScenarioEvid
       controls?: ScenarioControls | null;
       market?: unknown;
       inputSource?: string;
+      csp?: { earnings: { date: string | null } };
     } | undefined;
     const position = metadata?.position;
     const controls = metadata?.controls;
@@ -96,6 +97,8 @@ export const scenarioScreenshotEvidence: PaneScreenshotEvidenceHook<ScenarioEvid
         scenarioSnapshot: metadata?.scenario ?? null,
         scenarioMarketSnapshot: metadata?.market ?? null,
         scenarioSnapshotErrors: loaded.result.errors ?? [],
+        // A cash-secured put shows the earnings date the report read, not another lookup's.
+        ...(metadata?.csp ? { scenarioEarningsDate: metadata.csp.earnings.date } : {}),
         ...(position ? { seedPosition: position } : {}),
         ...(controls ? { date: new Date(controls.date).toISOString(), volShift: controls.volShift * 100,
           spotRange: controls.spotRange * 100 } : {}),

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

@@ -5,9 +5,11 @@ import {
 } from "../../../utils/option-expiry";
 import { resolveHeadlessInstrument } from "../shared/headless-market-data";
 import {
-  createScenarioDependencies, loadScenarioMarket, scenarioControlsFromSettings, scenarioPositionFromSettings,
-  type ScenarioMarketSnapshot,
+  createScenarioDependencies, loadScenarioMarket, SCENARIO_STRATEGIES, scenarioControlsFromSettings, scenarioPositionFromSettings,
+  scenarioSpotBasis, type ScenarioMarketSnapshot,
 } from "./client";
+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";
 
@@ -33,14 +35,17 @@ export const optionsScenarioHeadless: HeadlessPaneDefinition<"bundle"> = {
   describe: (args) => `OSA ${args.symbols[0] ?? ""}`,
   description: "A typed or chain-seeded options position valued across spot, date and volatility: its legs, value and Greeks, expiry risk and a "
     + "scenario P&L grid. With --nav and --budget-bps, how many contracts a hedge budget buys, the premium spent, the notional protected and "
-    + "coverage of an equity sleeve.",
+    + "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.",
   discovery: { screenshotReadiness: "ready", limitations: ["European scenario values do not model early assignment or exercise."] },
   options: [
     { key: "tab", type: "enum", values: ["payoff", "grid", "legs"].map((value) => ({ value })), defaultValue: "payoff",
       description: "Initial view", pluginState: { pluginId: "ticker-research", key: "activeTabId" } },
     { key: "legs", type: "string", description: "Semicolon-separated side,strike,YYYY-MM-DD,signed quantity,entry price per share,IV percent[,multiplier]" },
-    { key: "strategy", type: "enum", values: [{ value: "vertical" }, { value: "straddle" }, { value: "put" }],
-      description: "Build a position from current two-sided chain quotes: a call vertical, a straddle, or one long put (a protective put)" },
+    { key: "strategy", type: "enum", values: SCENARIO_STRATEGIES.map((value) => ({ value })),
+      example: "--strategy csp --strike 85 --expiration 2026-11-20",
+      description: "Build a position from current two-sided chain quotes: a call vertical, a straddle, one long put (a protective put), "
+        + "or csp, one short put sold at its midpoint with the cash to buy the shares set aside (a cash-secured put)" },
     { key: "strike", type: "string", description: "The --strategy strike: the put, the vertical's long call or the straddle. Nearest the money when omitted" },
     { key: "expiration", type: "string", placeholder: OPTION_EXPIRATION_PLACEHOLDER, example: "--strategy vertical --expiration 2027-01-15",
       description: `Chain expiry for --strategy, as ${OPTION_EXPIRATION_FORMAT}`, normalize: (value) => expirationOptionSeconds(value) },
@@ -76,6 +81,8 @@ export const optionsScenarioHeadless: HeadlessPaneDefinition<"bundle"> = {
         rateExpiration: typedExpiries.length ? Math.min(...typedExpiries) : undefined, signal: ctx.signal,
       }, createScenarioDependencies(ctx.marketData, ctx.apiClient));
     }
+    // A cash-secured put says whether earnings fall before it expires; the calendar is read only for one.
+    const earningsDate = settings.strategy === "csp" ? await loadNextEarningsDate(ctx.marketData, symbol) : null;
     ctx.signal.throwIfAborted();
     const position = scenarioPositionFromSettings(settings, market);
     const controls = position ? scenarioControlsFromSettings(settings, position) : null;
@@ -90,6 +97,10 @@ export const optionsScenarioHeadless: HeadlessPaneDefinition<"bundle"> = {
     // A seeded strategy starts at the spot its quote mids imply; the last print is reported beside it.
     const lastPrint = midVolatility && !supplied(settings.spot) && market.spot != null && money(market.spot) !== money(position!.spot)
       ? market.spot : null;
+    const spotBasis = position ? scenarioSpotBasis(settings, position, market) : null;
+    const csp = position && settings.strategy === "csp" ? cashSecuredPut(position, spotBasis!, earningsDate) : null;
+    const lastSession = market.underlyingQuote && spotBasis === "implied by option quotes"
+      ? scenarioSpotBasis({}, { spot: market.spot!, legs: [] }, market) : null;
     const chain = market.chain;
     const currency = position ? currencyLabel(position.currency) : null;
     // Value, P&L, risk and the grid add every contract; entry prices and spot are per share.
@@ -111,13 +122,16 @@ export const optionsScenarioHeadless: HeadlessPaneDefinition<"bundle"> = {
           ...(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,
-            formatted: `${money(position!.spot)} ${PRICE_UNIT}` },
-          ...(lastPrint != null ? [{ key: "last", label: "Last price", value: lastPrint, formatted: `${money(lastPrint)} ${PRICE_UNIT}` }] : []),
+            formatted: `${money(position!.spot)} ${PRICE_UNIT}${lastPrint == null && spotBasis !== "last price" ? ` (${spotBasis})` : ""}` },
+          ...(lastPrint != null ? [{ key: "last", label: "Last price", value: lastPrint,
+            formatted: `${money(lastPrint)} ${PRICE_UNIT}${lastSession && lastSession !== "last price" ? ` (${lastSession})` : ""}` }] : []),
+          { 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: "dividendYield", label: "Dividend yield", value: position!.dividendYield, formatted: percent(position!.dividendYield) },
           { key: "currency", label: "Currency", value: position!.currency, formatted: currency! },
         ] },
         ...(hedge ? [{ title: "Hedge budget", entries: hedgeReportEntries(hedge) }] : []),
+        ...(csp ? [{ title: "Cash-secured put", entries: cspReportEntries(csp) }] : []),
         { title: `Valuation (${per})`, entries: Object.entries(scenario.valuation).map(([key, value]) => ({ key,
           label: VALUATION_LABELS[key]?.(currency!) ?? key, value, formatted: money(value) })) },
         { title: `Expiry risk (${per})`, entries: [
@@ -136,7 +150,9 @@ export const optionsScenarioHeadless: HeadlessPaneDefinition<"bundle"> = {
       ] : [],
       complete: scenario != null && errors.length === 0,
       unavailableSymbols: scenario ? [] : [symbol], errors,
-      metadata: { scenario, position, controls, market, ...(hedge ? { hedge } : {}), inputSource: suppliedInputs ? "user" : "market",
+      metadata: { scenario, position, controls, market, ...(hedge ? { hedge } : {}), ...(csp ? { csp } : {}),
+        ...(position ? { spot: { price: position.spot, basis: spotBasis, valuedAt: new Date(position.asOf).toISOString() } } : {}),
+        inputSource: suppliedInputs ? "user" : "market",
         unit: position?.currency || "currency unspecified",
         // Leg entry prices and spot are per share; value, P&L, risk, Greeks in currency and the grid are for valueUnit.
         ...(position ? { units: { currency: position.currency, price: PRICE_UNIT, value: valueUnit } } : {}),