@gloom-sh/terminal 0.18.5 → 0.19.1

package/src/plugins/builtin/iv-history/headless.ts

@@ -2,8 +2,8 @@ import type { HeadlessPaneDefinition } from "../../../types/plugin";
 import { resolveHeadlessInstrument } from "../shared/headless-market-data";
 import { createRealizedVolatilityDependencies, loadRealizedVolatilityHistory } from "../realized-vol/client";
 import { createHvDependencies, loadIvHistory, loadIvScreen, loadScreenVolatilities } from "./client";
-import { formatPoints, formatRank, formatSpot, formatStat, formatVol, IMPLIED_VOL_WORDS, readingLabel, sharedDates, skewHeader, VCA_DEFINITIONS, verdictLabel } from "./format";
-import { HV_WINDOWS, type HvWindow, type IvLookback, type IvStatRow, projectIvHistory, projectRichCheap, type RichCheapRow, richCheapDates, screenCoverage, VCA_LIMIT, VCA_PRESETS } from "./model";
+import { formatPoints, formatRank, formatSpot, formatStat, formatVol, IMPLIED_VOL_WORDS, readingLabel, sharedDates, skewHeader, statSource, vcaDefinitions, verdictLabel } from "./format";
+import { HV_WINDOWS, type HvWindow, type IvLookback, type IvStatRow, projectIvHistory, projectRichCheap, type RichCheapRow, richCheapDates, screenCoverage, screenStaleNote, VCA_LIMIT, VCA_PRESETS } from "./model";
 import { vcaUniverse } from "./universe";
 import { offsetText, releaseOffsetRows } from "./events";
 import { loadMacroReleases } from "../macro-day/client";
@@ -16,6 +16,7 @@ import type { HeadlessPaneContext } from "../../../types/headless";
 import { zonedDateKey } from "../../../utils/zoned-date-time";
 import { listingFateNotes, listingFateReport, loadListingFate, MovedSymbolError } from "../../../tickers/listing-fate";
 import { startTickerChangeLookup } from "../../../tickers/ticker-changes";
+import { fxVolatilityRefusal } from "../../../market-data/options-alternatives";
 
 const METHODOLOGY = "docs/research-data.md#implied-volatility-history";
 const percent = (value: unknown) => typeof value === "number" ? formatVol(value) : "--";
@@ -24,6 +25,7 @@ const points = (value: unknown) => typeof value === "number" ? formatPoints(valu
 export const ivHistoryHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle", argument: { kind: "ticker", description: "US option underlying" },
   usListingsOnly: "Implied volatility history",
+  refuseSymbol: fxVolatilityRefusal("HIVG"),
   freshness: { status: "not-a-feed", basis: "daily implied volatility", cadence: "daily", observedKey: "date", oldest: null },
   describe: (args) => `HIVG ${args.symbols[0] ?? ""}`,
   discovery: { aliases: ["HIVG"], suggestFor: IMPLIED_VOL_WORDS, screenshotReadiness: "live-dom", dataRequirements: ["Cloud stored implied volatility", "Daily price history"],
@@ -79,7 +81,7 @@ export const ivHistoryHeadless: HeadlessPaneDefinition<"bundle"> = {
     // With nothing served, the fate is why: no "not a ticker" or missing-history errors beside it.
     const { notes: fateNotes, errors } = listingFateReport(fate, { served },
       [prices.error, ...model.warnings].filter((value): value is string => !!value));
-    const notes = [...fateNotes, ...[model.oneYearNote, model.skewNote].filter((note): note is string => !!note)];
+    const notes = [...fateNotes, ...[model.oneYearNote, model.skewNote, model.staleNote].filter((note): note is string => !!note)];
     if (event && releases) {
       const lookback = String(args.options.lookback) as IvLookback;
       const label = MACRO_EVENT_LABELS[event];
@@ -117,18 +119,27 @@ export const ivHistoryHeadless: HeadlessPaneDefinition<"bundle"> = {
           releaseSource: MACRO_RELEASE_SOURCES[event], unit: "decimal annualized volatility", methodology: METHODOLOGY },
       };
     }
+    // The text report dates a stale measure "stale"; exports keep the bare date and say it in `stale`.
+    const statColumns = [
+      { key: "label", header: "Measure" },
+      { key: "value", header: "Current", format: (value: unknown, row?: unknown) => formatStat(value as number | null, (row as IvStatRow).unit) },
+      { key: "date", header: "As of" }, { key: "method", header: "Method" },
+      { key: "low", header: "52w low", format: (value: unknown, row?: unknown) => formatStat(value as number | null, (row as IvStatRow).unit) },
+      { key: "high", header: "52w high", format: (value: unknown, row?: unknown) => formatStat(value as number | null, (row as IvStatRow).unit) },
+      { key: "rank", header: "Rank", format: (value: unknown) => formatRank(value as number | null) },
+      { key: "percentile", header: "Pctl", format: (value: unknown) => formatRank(value as number | null) },
+      { key: "samples", header: "Sessions" },
+    ];
+    const statTextColumns = statColumns.map((column) => column.key === "date"
+      ? { ...column, textFormat: (value: unknown, row: unknown) => typeof value !== "string" ? "-" : (row as IvStatRow).stale ? `${value} stale` : value }
+      : column.key === "method"
+        // The wording the pane's source column uses; exports keep the raw method and carry the basis.
+        ? { ...column, textFormat: (value: unknown, row: unknown) => typeof value !== "string" ? "-" : statSource(row as IvStatRow) }
+        : column);
     return {
       sections: [
-        { title: "Statistics", columns: [
-          { key: "label", header: "Measure" },
-          { key: "value", header: "Current", format: (value: unknown, row?: unknown) => formatStat(value as number | null, (row as IvStatRow).unit) },
-          { key: "date", header: "As of" }, { key: "method", header: "Method" },
-          { key: "low", header: "52w low", format: (value: unknown, row?: unknown) => formatStat(value as number | null, (row as IvStatRow).unit) },
-          { key: "high", header: "52w high", format: (value: unknown, row?: unknown) => formatStat(value as number | null, (row as IvStatRow).unit) },
-          { key: "rank", header: "Rank", format: (value: unknown) => formatRank(value as number | null) },
-          { key: "percentile", header: "Pctl", format: (value: unknown) => formatRank(value as number | null) },
-          { key: "samples", header: "Sessions" },
-        ], rows: model.stats.map((row) => ({ ...row })) },
+        { title: "Statistics", columns: [...statColumns, { key: "basis", header: "Basis" }, { key: "stale", header: "Stale" }], textColumns: statTextColumns,
+          rows: model.stats.map((row) => ({ ...row })) },
         // Exports always carry the skew columns, so a script's header never moves; the text table drops them when none has a value.
         { title: "Daily history", columns: [...historyColumns, ...skewColumns], rows,
           ...(rows.some((row) => row.skew25d != null) ? {} : { textColumns: historyColumns }) },
@@ -151,6 +162,7 @@ export const ivScreenHeadless: HeadlessPaneDefinition<"bundle"> = {
   freshness: { status: "not-a-feed", basis: "daily implied volatility", cadence: "daily", observedKey: "date" },
   argument: { kind: "symbol-list", optional: true, maximum: VCA_LIMIT, description: "US option underlyings; defaults to index and sector ETFs." },
   usListingsOnly: "Implied volatility",
+  refuseSymbol: fxVolatilityRefusal("VCA"),
   options: [{ key: "preset", type: "enum", values: [{ value: "etfs" }, { value: "megacaps" }], defaultValue: "etfs", description: "Preset when no symbols are given" }],
   describe: "Volatility rich/cheap",
   // The pane names its universe `scope`; symbols typed open their own (custom), which a preset does not replace.
@@ -180,14 +192,15 @@ export const ivScreenHeadless: HeadlessPaneDefinition<"bundle"> = {
     // A listing that stopped trading has its row's note, not a line saying it has no options history.
     const coverage = screenCoverage(rows, { explained: new Set([...noted].filter(([, entry]) => entry.fate.endedOn).map(([symbol]) => symbol)) });
     const dates = richCheapDates(rows);
-    const hasSkew = rows.some((row) => row.skew != null);
+    const hasSkew = rows.some((row) => row.riskReversal != null);
     const hasIv1y = rows.some((row) => row.iv1y != null), hasIv1yRank = rows.some((row) => row.iv1yPercentile != null);
     const dated = (value: unknown) => typeof value === "string" ? value : "--";
     return {
       sections: [{ title: ["Rich/cheap", universe.label, ...sharedDates(dates)].join(" · "), columns: [
         { key: "symbol", header: "Symbol" }, { key: "iv30", header: "IV30", format: percent },
         ...(dates.reading ? [] : [{ key: "date", header: "As of", format: (value: unknown, row?: unknown) =>
-          typeof value === "string" ? readingLabel(value, (row as RichCheapRow).method) : "--" }]),
+          typeof value === "string" ? readingLabel(value, (row as RichCheapRow).method, false,
+            { basis: (row as RichCheapRow).basis, stale: (row as RichCheapRow).stale }) : "--" }]),
         // The underlying price each reading was taken at, on the date the title or the As of column gives.
         { key: "spot", header: "Spot", format: (value: unknown) => typeof value === "number" ? formatSpot(value) : "--" },
         ...(dates.rankApart ? [{ key: "rankDate", header: "Rank as of", format: (value: unknown) => typeof value === "string" ? `${value} close` : "--" }] : []),
@@ -197,16 +210,18 @@ export const ivScreenHeadless: HeadlessPaneDefinition<"bundle"> = {
         ...(hasIv1y ? [{ key: "iv1y", header: "IV1Y", format: percent }] : []),
         ...(hasIv1yRank ? [{ key: "iv1yPercentile", header: "IVP1Y", format: (value: unknown) => formatRank(value as number | null) }] : []),
         { key: "termSlope", header: "30-90", format: (value: unknown) => formatPoints(value as number | null) },
-        ...(hasSkew ? [{ key: "skew", header: skewHeader("25D skew", "put-call"), format: (value: unknown) => formatPoints(value as number | null) }] : []),
-        ...(hasSkew && dates.skewApart ? [{ key: "skewDate", header: "Skew as of", format: dated }] : []),
+        ...(hasSkew ? [{ key: "riskReversal", header: skewHeader("25D RR", "call-put"), format: (value: unknown) => formatPoints(value as number | null) }] : []),
+        ...(hasSkew && dates.skewApart ? [{ key: "skewDate", header: "RR as of", format: dated }] : []),
         { key: "hv", header: "HV20", format: percent },
+        // Said only where an HV is not the one of its IV's date: a stale reading's, or one a few sessions off.
+        ...(dates.hvApart ? [{ key: "hvDate", header: "HV as of", format: dated }] : []),
         { key: "ivHv", header: "IV/HV", format: (value: unknown) => typeof value === "number" ? value.toFixed(2) : "--" },
         ...(noted.size > 0 ? [{ key: "note", header: "Note", underRow: true }] : []),
       ], rows: rows.map((row) => ({ ...row, ...noted.has(row.symbol) ? { note: noted.get(row.symbol)!.note } : {} })) }],
       // A symbol with no options history is final; only history still to come leaves the screen incomplete.
       complete: !coverage.pending.length && !universe.error, unavailableSymbols: coverage.missing,
       errors: [universe.error].filter((value): value is string => !!value),
-      notes: [...coverage.notes, ...VCA_DEFINITIONS],
+      notes: [...coverage.notes, ...[screenStaleNote(rows)].filter((note): note is string => !!note), ...vcaDefinitions({ skew: hasSkew })],
       metadata: { presets: VCA_PRESETS, methodology: METHODOLOGY },
     };
   },

package/src/plugins/builtin/iv-history/index.tsx

@@ -32,13 +32,13 @@ export const ivHistoryModule: PluginModule = {
     { ...createTickerSurfacePaneTemplate({
       id: "iv-history-pane", paneId: "iv-history", label: "Implied Volatility History",
       description: "30-day, 90-day and one-year ATM implied volatility since 2024 against realized, with IV rank and percentile.",
-      keywords: ["hivg", "implied", "volatility", "history", "iv rank", "ivr", "percentile", "vrp", "iv1y", "leaps"], shortcut: "HIVG", publicShare: true,
+      keywords: ["hivg", "implied", "volatility", "vol", "history", "iv rank", "ivr", "percentile", "vrp", "iv1y", "leaps"], shortcut: "HIVG", publicShare: true,
     }), headless: ivHistoryHeadless },
     {
       id: "iv-screen-pane", paneId: "iv-screen", label: "Volatility Rich/Cheap",
       description: "IV rank, percentile, one-year IV, term slope, skew and IV/HV across a list, ranked rich to cheap.",
       // Where a put seller finds rich premium; CSP and OSA own the exact put-selling phrases and rank first on them.
-      keywords: ["vca", "rich", "cheap", "iv rank", "implied volatility", "screen", "cash-secured puts", "selling puts", "short-put candidates",
+      keywords: ["vca", "vol", "rich", "cheap", "iv rank", "implied volatility", "screen", "cash-secured puts", "selling puts", "short-put candidates",
         "csp candidates", "wheel candidates"],
       shortcut: { prefix: "VCA", argKind: "ticker-list" as const, argOptional: true }, headless: ivScreenHeadless,
       createInstance: (_context, options) => ({

package/src/plugins/builtin/iv-history/model.ts

@@ -1,6 +1,7 @@
+import { getPublishedUsEquityCalendarDay } from "../../../market-data/published-us-sessions";
 import type { PricePoint } from "../../../types/financials";
 import { rollingRealizedVolatility } from "../shared/volatility";
-import type { IvCoverageStatus, IvHistoryPayload, IvMethod, IvPoint, IvScreenRow, IvStats } from "./client";
+import type { IvCloseBasis, IvCoverageStatus, IvHistoryPayload, IvMethod, IvPoint, IvScreenRow, IvStats, ScreenHv } from "./client";
 
 /**
  * A history's warnings in words for the reader. A symbol demand coverage could
@@ -18,6 +19,75 @@ export type IvLookback = "1Y" | "2Y" | "ALL";
 const RICH_PERCENTILE = 80;
 const CHEAP_PERCENTILE = 20;
 
+/** A reading trailing the symbol's newest session by more sessions than this is stale. */
+const STALE_AFTER_SESSIONS = 5;
+const DAY_MS = 86_400_000;
+
+/** Whether `date` ("2026-10-23") is a US equity session: the published NYSE calendar where it covers, else a weekday. */
+function isSession(date: string): boolean {
+  const published = getPublishedUsEquityCalendarDay("NYSE", date);
+  if (published) return published === "session";
+  const weekday = new Date(`${date}T00:00:00Z`).getUTCDay();
+  return weekday !== 0 && weekday !== 6;
+}
+
+/** US sessions after `date` up to and including `through`: how far behind that session a reading is. */
+export function sessionsBehind(date: string, through: string): number {
+  const end = Date.parse(`${through}T00:00:00Z`);
+  let behind = 0;
+  for (let time = Date.parse(`${date}T00:00:00Z`) + DAY_MS; time <= end; time += DAY_MS) {
+    if (isSession(new Date(time).toISOString().slice(0, 10))) behind += 1;
+  }
+  return behind;
+}
+
+/** The newest of the dates given: the newest session the symbol's stored readings, backfill and prices reach. */
+function newestSession(...dates: ReadonlyArray<string | null | undefined>): string | null {
+  return dates.filter((date): date is string => !!date).map((date) => date.slice(0, 10)).sort().at(-1) ?? null;
+}
+
+/** How many sessions a reading is behind the newest, and whether that makes it stale. */
+function staleness(date: string | null | undefined, newest: string | null): { sessionsBehind: number | null; stale: boolean } {
+  const behind = date && newest ? sessionsBehind(date.slice(0, 10), newest) : null;
+  return { sessionsBehind: behind, stale: behind != null && behind > STALE_AFTER_SESSIONS };
+}
+
+/** An HV further than this many sessions from the IV's date says nothing about it: IV/HV is left empty. */
+const HV_MAX_SESSIONS_APART = 3;
+
+/**
+ * HV after the close of the last session on or before `date`, when that is within
+ * `HV_MAX_SESSIONS_APART` sessions of it; null before the series starts or when the
+ * nearest HV is older than that.
+ */
+export function hvOn(hv: ScreenHv, date: string): { date: string; value: number } | null {
+  for (let index = hv.series.length - 1; index >= 0; index -= 1) {
+    const [sessionDate, value] = hv.series[index]!;
+    if (sessionDate <= date) return sessionsBehind(sessionDate, date) <= HV_MAX_SESSIONS_APART ? { date: sessionDate, value } : null;
+  }
+  return null;
+}
+
+/**
+ * How a reading's method is worded wherever it is dated: "quote", "close", or "close mid" for a
+ * close solved from quote midpoints (mid or mixed). Two readings that word alike share one label.
+ */
+export function readingSource(method: IvMethod | null | undefined, basis?: IvCloseBasis | null): string {
+  return method === "quote-mid" ? "quote" : basis === "mid" || basis === "mixed" ? "close mid" : "close";
+}
+
+const STALE_NOTE_LIMIT = 5;
+/**
+ * The stale readings, dated, and what that leaves out, in one wording for HIVG and VCA: "Stale, left
+ * out of rank: IV 1Y ATM 2025-01-17 (over 5 sessions behind)." The list stops at five, then "N more".
+ */
+export function staleReadingsNote(leftOut: string, items: ReadonlyArray<{ label: string; date: string }>): string | null {
+  if (!items.length) return null;
+  const listed = items.slice(0, STALE_NOTE_LIMIT).map((item) => `${item.label} ${item.date}`);
+  const more = items.length - listed.length;
+  return `Stale, left out of ${leftOut}: ${listed.join(", ")}${more > 0 ? `, ${more} more` : ""} (over ${STALE_AFTER_SESSIONS} sessions behind).`;
+}
+
 export interface DatedValue { date: Date; value: number | null }
 export type IvStatUnit = "vol" | "points" | "ratio";
 /** One measure's latest value ranked against its own prior 52 weeks. */
@@ -28,11 +98,21 @@ export interface IvStatRow {
   value: number | null;
   date: string | null;
   method: IvMethod | "prices" | null;
+  /** Prices a trade close was solved from, when the server says (see `IvCloseBasis`). */
+  basis: IvCloseBasis | null;
   low: number | null;
   high: number | null;
   rank: number | null;
   percentile: number | null;
   samples: number;
+  /**
+   * The reading trails the symbol's newest session by more than `STALE_AFTER_SESSIONS`
+   * sessions: its rank and percentile are left out, since they would rank an old
+   * figure as though it were current.
+   */
+  stale: boolean;
+  /** Sessions between the reading and the symbol's newest session. */
+  sessionsBehind: number | null;
 }
 /** Rank and percentile need this many prior sessions, matching the server. */
 const MIN_RANK_SAMPLES = 120;
@@ -96,6 +176,8 @@ export interface IvHistoryModel {
   /** "skew from 2026-09-23", or why there is no skew at all. */
   skewNote: string | null;
   stats: IvStatRow[];
+  /** Which measures are stale and what that leaves out, when any is. */
+  staleNote: string | null;
   since: string | null;
   /** Where the 1Y series starts and how deep it is, when that differs from the rest or leaves it unranked. */
   oneYearNote: string | null;
@@ -127,15 +209,16 @@ function lookbackStart(asOf: string, lookback: IvLookback): string | null {
 /** The latest value against the 52 weeks before it, with the same rules as the server's IV rank. */
 function seriesStat(id: string, label: string, unit: IvStatUnit, points: readonly DatedValue[], method: IvStatRow["method"]): IvStatRow {
   const latest = [...points].reverse().find((point) => point.value != null);
-  if (!latest) return { id, label, unit, value: null, date: null, method, low: null, high: null, rank: null, percentile: null, samples: 0 };
+  if (!latest) return { id, label, unit, value: null, date: null, method, basis: null, low: null, high: null, rank: null, percentile: null, samples: 0,
+    stale: false, sessionsBehind: null };
   const start = lookbackStart(day(latest.date), "1Y")!;
   const window = points.filter((point) => point.value != null && day(point.date) >= start && point.date < latest.date).map((point) => point.value!);
   const value = latest.value!;
   const low = window.length ? Math.min(value, ...window) : null, high = window.length ? Math.max(value, ...window) : null;
   const enough = window.length >= MIN_RANK_SAMPLES;
-  return { id, label, unit, value, date: day(latest.date), method, low, high,
+  return { id, label, unit, value, date: day(latest.date), method, basis: null, low, high,
     rank: enough && high! > low! ? (value - low!) / (high! - low!) * 100 : null,
-    percentile: midrankPercentile(window, value), samples: window.length };
+    percentile: midrankPercentile(window, value), samples: window.length, stale: false, sessionsBehind: null };
 }
 
 function byMethod(series: readonly IvPoint[], method: IvMethod, field: "iv30" | "iv90" | "iv365") {
@@ -192,25 +275,37 @@ export function projectIvHistory(
     return { date: point.date, value: point.value == null || iv90 == null || !(iv90 > 0) ? null : point.value / iv90 };
   });
   const fromServer = (id: string, label: string, stats: IvStats | null): IvStatRow => ({ id, label, unit: "vol",
-    value: stats?.value ?? null, date: stats?.date ?? null, method: stats?.method ?? null, low: stats?.low ?? null, high: stats?.high ?? null,
-    rank: stats?.rank ?? null, percentile: stats?.percentile ?? null, samples: stats?.samples ?? 0 });
+    value: stats?.value ?? null, date: stats?.date ?? null, method: stats?.method ?? null, basis: stats?.basis ?? null,
+    low: stats?.low ?? null, high: stats?.high ?? null,
+    rank: stats?.rank ?? null, percentile: stats?.percentile ?? null, samples: stats?.samples ?? 0, stale: false, sessionsBehind: null });
   const stats: IvStatRow[] = [fromServer("iv30", "IV 30d ATM", payload.stats.iv30)];
   // A newer quote capture is shown on its own row: its rank would mix methods.
   if (latest?.method === "quote-mid" && latest.iv30 != null && (!payload.stats.iv30 || latest.date > payload.stats.iv30.date)) {
-    stats.push({ id: "iv30-quote", label: "IV 30d quote", unit: "vol", value: latest.iv30, date: latest.date, method: "quote-mid",
-      low: null, high: null, rank: null, percentile: null, samples: 0 });
+    stats.push({ id: "iv30-quote", label: "IV 30d quote", unit: "vol", value: latest.iv30, date: latest.date, method: "quote-mid", basis: null,
+      low: null, high: null, rank: null, percentile: null, samples: 0, stale: false, sessionsBehind: null });
   }
   // IV1Y ranks trade closes only; until there is one, a stored quote gives its level, unranked.
   const oneYear = payload.stats.iv365 ?? null;
   stats.push(fromServer("iv90", "IV 90d ATM", payload.stats.iv90),
     !oneYear && latest?.iv365 != null
-      ? { id: "iv365", label: "IV 1Y ATM", unit: "vol", value: latest.iv365, date: latest.date, method: latest.method,
-        low: null, high: null, rank: null, percentile: null, samples: 0 }
+      ? { id: "iv365", label: "IV 1Y ATM", unit: "vol", value: latest.iv365, date: latest.date, method: latest.method, basis: latest.basis ?? null,
+        low: null, high: null, rank: null, percentile: null, samples: 0, stale: false, sessionsBehind: null }
       : fromServer("iv365", "IV 1Y ATM", oneYear),
     seriesStat("hv", `HV ${window}`, "vol", rolling, "prices"),
     seriesStat("spread", `IV 30d - HV ${window}`, "points", spreadAll, "trade-close"),
     seriesStat("term", "IV 30d / 90d", "ratio", termAll, "trade-close"));
 
+  // The newest session the symbol reaches, by its prices, its backfill and every reading it has: a reading more
+  // than STALE_AFTER_SESSIONS behind it is shown as it is, marked stale, and ranks nothing.
+  const newest = newestSession(payload.coverage?.backfilledThrough, latest?.date, latestDate,
+    ...payload.series.map((point) => point.sessionDate), ...prices.map((price) => day(price.date)));
+  const measured = stats.map((row): IvStatRow => {
+    const behind = staleness(row.date, newest);
+    return { ...row, ...behind, ...behind.stale ? { rank: null, percentile: null } : {} };
+  });
+  const staleRows = measured.filter((row) => row.stale);
+  const staleText = staleReadingsNote("rank", staleRows.map((row) => ({ label: row.label, date: row.date! })));
+
   // Worded as VCA words each symbol (screenCoverage).
   if (payload.status === "queued") warnings.push(`${payload.symbol} ${queuedText(payload.coverage?.addedAt, options.now ?? Date.now())}.`);
   else if (payload.status === "backfilling") {
@@ -232,7 +327,7 @@ export function projectIvHistory(
     iv30: visible(tradeIv30), iv90: visible(byMethod(payload.series, "trade-close", "iv90")), iv365: visible(tradeIv365),
     quoteIv30: visible(byMethod(payload.series, "quote-mid", "iv30")),
     hv, spread: visible(spreadAll), skew: visible(skew.points),
-    skewSince: skew.points[0] ? day(skew.points[0].date) : null, skewNote: skew.note, stats,
+    skewSince: skew.points[0] ? day(skew.points[0].date) : null, skewNote: skew.note, stats: measured, staleNote: staleText,
     since, oneYearNote, asOf: latestDate, warnings,
   };
 }
@@ -251,6 +346,16 @@ export interface RichCheapRow {
   iv30: number | null;
   date: string | null;
   method: IvMethod | null;
+  /** Prices a trade close was solved from, when the server says (see `IvCloseBasis`). */
+  basis: IvCloseBasis | null;
+  /**
+   * The reading trails the symbol's newest session by more than `STALE_AFTER_SESSIONS`
+   * sessions. It is shown, marked stale, and left out of IV/HV, rank, percentile and
+   * Rich/Cheap, and so are its skew and IV1Y rank when they are as old.
+   */
+  stale: boolean;
+  /** Sessions between the reading and the symbol's newest session. */
+  sessionsBehind: number | null;
   /** The underlying price the reading was taken at: the session's close, or the spot at the quote capture. */
   spot: number | null;
   rank: number | null;
@@ -265,10 +370,18 @@ export interface RichCheapRow {
    * series has no reading that session, or there is no IV1Y beside it to describe.
    */
   iv1yPercentile: number | null;
-  skew: number | null;
-  /** Session of the quote capture the skew comes from. */
+  /** The 25-delta risk reversal at 30 days: call IV minus put IV, so positive means calls are richer, as OVDV signs it. */
+  riskReversal: number | null;
+  /** Session of the quote capture the risk reversal comes from. */
   skewDate: string | null;
+  /**
+   * Realized volatility on the reading's own date, so the row reads as IV30 over HV;
+   * the newest HV for a stale reading or one with no HV on its date.
+   */
   hv: number | null;
+  /** Session of the HV shown. */
+  hvDate: string | null;
+  /** IV30 over the HV of its own date; empty for a stale reading. */
   ivHv: number | null;
   verdict: RichCheap;
 }
@@ -280,24 +393,29 @@ export interface RichCheapRow {
  * is measured on. A group the rows disagree on gets its own column.
  */
 export interface RichCheapDates {
-  reading: { date: string; method: IvMethod } | null;
+  reading: { date: string; method: IvMethod; basis: IvCloseBasis | null } | null;
   /** The trade close every ranked row is ranked on. */
   rank: string | null;
   /** Ranked rows are ranked on different closes. */
   rankApart: boolean;
-  /** Some skew comes from a different session than its row's reading. */
+  /** Some risk reversal comes from a different session than its row's reading. */
   skewApart: boolean;
+  /** Some HV is dated on a different session than the IV it sits beside. */
+  hvApart: boolean;
 }
 export function richCheapDates(rows: readonly RichCheapRow[]): RichCheapDates {
   const read = rows.filter((row) => row.date && row.method);
   const ranked = rows.filter((row) => row.rankDate);
   const first = read[0], firstRanked = ranked[0];
   return {
-    reading: first && read.every((row) => row.date === first.date && row.method === first.method)
-      ? { date: first.date!, method: first.method! } : null,
+    // A stale row's own date is said in its row, never once for all.
+    // The label the rows would be dated with, not the raw basis: a mid and a mixed close are both "close mid".
+    reading: first && read.every((row) => row.date === first.date && readingSource(row.method, row.basis) === readingSource(first.method, first.basis) && !row.stale)
+      ? { date: first.date!, method: first.method!, basis: first.basis } : null,
     rank: firstRanked && ranked.every((row) => row.rankDate === firstRanked.rankDate) ? firstRanked.rankDate : null,
     rankApart: !!firstRanked && ranked.some((row) => row.rankDate !== firstRanked.rankDate),
-    skewApart: rows.some((row) => row.skew != null && row.skewDate !== row.date),
+    skewApart: rows.some((row) => row.riskReversal != null && row.skewDate !== row.date),
+    hvApart: rows.some((row) => row.hv != null && row.hvDate != null && row.hvDate !== row.date),
   };
 }
 
@@ -307,22 +425,34 @@ export function verdictFor(percentile: number | null): RichCheap {
   return percentile >= RICH_PERCENTILE ? "rich" : percentile <= CHEAP_PERCENTILE ? "cheap" : "fair";
 }
 
-export function projectRichCheap(rows: readonly IvScreenRow[], hv: ReadonlyMap<string, number | null> = new Map()): RichCheapRow[] {
+export function projectRichCheap(rows: readonly IvScreenRow[], hv: ReadonlyMap<string, ScreenHv | null> = new Map()): RichCheapRow[] {
   return rows.map((row) => {
     const latest = row.latest;
     const iv30 = latest?.iv30 ?? null;
-    const realized = hv.get(row.symbol) ?? null;
-    const percentile = row.iv30?.percentile ?? null;
+    const series = hv.get(row.symbol) ?? null;
+    // The newest session the symbol reaches: its prices, its backfill and every reading it has.
+    const newest = newestSession(row.coverage?.backfilledThrough, latest?.date, row.iv30?.date, row.iv90?.date, row.iv365?.date,
+      row.skew?.date, series?.date);
+    const { stale, sessionsBehind: behind } = staleness(latest?.date, newest);
+    // A rank on a close that old ranks an old figure; so does a skew.
+    const rankStale = stale || staleness(row.iv30?.date, newest).stale;
+    const skewStale = row.skew ? staleness(row.skew.date, newest).stale : false;
+    const percentile = rankStale ? null : row.iv30?.percentile ?? null;
+    // HV on the reading's own date: today's HV beside an old IV says nothing about it.
+    const atReading = series && !stale && latest?.date ? hvOn(series, latest.date) : null;
+    const shown = atReading ?? (series?.value != null && series.date ? { date: series.date, value: series.value } : null);
     return {
       symbol: row.symbol, status: row.coverageStatus ?? row.status, queuedAt: row.coverage?.addedAt ?? null,
       backfilledThrough: row.coverage?.backfilledThrough ?? null, warning: row.warnings?.[0] ?? null,
-      iv30, date: latest?.date ?? null, method: latest?.method ?? null, spot: latest?.spot ?? null,
-      rank: row.iv30?.rank ?? null, percentile, rankDate: row.iv30?.date ?? null,
+      iv30, date: latest?.date ?? null, method: latest?.method ?? null, basis: latest?.basis ?? null,
+      stale, sessionsBehind: behind, spot: latest?.spot ?? null,
+      rank: rankStale ? null : row.iv30?.rank ?? null, percentile, rankDate: rankStale ? null : row.iv30?.date ?? null,
       termSlope: iv30 != null && latest?.iv90 != null ? iv30 - latest.iv90 : null,
       iv1y: latest?.iv365 ?? null,
-      iv1yPercentile: latest?.iv365 != null && row.iv365 && row.iv365.date === row.iv30?.date ? row.iv365.percentile : null,
-      skew: row.skew?.skew ?? null, skewDate: row.skew?.date ?? null, hv: realized,
-      ivHv: iv30 != null && realized != null && realized > 0 ? iv30 / realized : null,
+      iv1yPercentile: !rankStale && latest?.iv365 != null && row.iv365 && row.iv365.date === row.iv30?.date ? row.iv365.percentile : null,
+      riskReversal: skewStale || !row.skew ? null : row.skew.call25 - row.skew.put25, skewDate: skewStale ? null : row.skew?.date ?? null,
+      hv: shown?.value ?? null, hvDate: shown?.date ?? null,
+      ivHv: iv30 != null && atReading != null && atReading.value > 0 ? iv30 / atReading.value : null,
       verdict: verdictFor(percentile),
     };
   });
@@ -375,6 +505,11 @@ export function screenCoverage(
     missing: pending.filter((row) => row.iv30 == null && row.date == null).map((row) => row.symbol) };
 }
 
+/** The symbols whose reading is stale, dated, and what that leaves out of the screen. */
+export function screenStaleNote(rows: readonly RichCheapRow[]): string | null {
+  return staleReadingsNote("IV/HV, rank and Rich/Cheap", rows.flatMap((row) => row.stale && row.date ? [{ label: row.symbol, date: row.date }] : []));
+}
+
 /**
  * The VCA pane's notices: the report's wording without a time to come back
  * at, since the pane checks again by itself, and a count of ready symbols with
@@ -383,7 +518,8 @@ export function screenCoverage(
 export function screenPaneNotices(rows: readonly RichCheapRow[], now = Date.now()): string[] {
   const empty = rows.filter((row) => row.status === "ready" && row.iv30 == null).length;
   return [...screenCoverage(rows, { now, retry: false }).notes,
-    ...(empty ? [`${empty} symbol${empty === 1 ? " has" : "s have"} no stored implied volatility yet.`] : [])];
+    ...(empty ? [`${empty} symbol${empty === 1 ? " has" : "s have"} no stored implied volatility yet.`] : []),
+    ...[screenStaleNote(rows)].filter((note): note is string => !!note)];
 }
 
 export const VCA_PRESETS = {

package/src/plugins/builtin/iv-history/pane.tsx

@@ -2,6 +2,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { listingIdentity } from "../shared/ticker-request";
 import { DataTableView, EmptyState, PaneStatusBody, QueryBar, usePaneFooter, usePaneNoticeFooter, usePaneTicker, type DataTableColumn } from "../../../components";
 import { instrumentFromTicker } from "../../../market-data/request-types";
+import { fxVolatilityNote } from "../../../market-data/options-alternatives";
 import { usePaneRefreshKey } from "../../../components/data-table/table-pane";
 import { useAsyncResource } from "../../../react/async-resource";
 import { useShortcut } from "../../../react/input";
@@ -24,7 +25,7 @@ const HV_OPTIONS = HV_WINDOWS.map((window) => ({ value: String(window), label: `
 const STAT_COLUMNS: DataTableColumn[] = [
   { id: "label", label: "Measure", width: 16, align: "left" },
   { id: "value", label: "Current", width: 9, align: "right" },
-  { id: "date", label: "As of", width: 17, align: "left" },
+  { id: "date", label: "As of", width: 20, align: "left" },
   { id: "low", label: "52w low", width: 9, align: "right" },
   { id: "high", label: "52w high", width: 9, align: "right" },
   { id: "rank", label: "Rank", width: 6, align: "right" },
@@ -54,7 +55,9 @@ export function IvHistoryPane({ width, height, focused }: PaneProps) {
     ]);
     return { payload, prices };
   }, [instrumentKey]);
-  const resource = useAsyncResource(instrument ? loader : null);
+  // An FX pair has no implied volatility history: the pane says what stands in, and asks for nothing.
+  const fxNote = symbol ? fxVolatilityNote(symbol, ticker?.metadata.exchange) : null;
+  const resource = useAsyncResource(instrument && !fxNote ? loader : null);
   useEffect(() => () => controller.current?.abort(), [loader]);
   useAutoRefresh(resource.updatedAt, resource.load);
   const model = useMemo(() => resource.data
@@ -66,7 +69,7 @@ export function IvHistoryPane({ width, height, focused }: PaneProps) {
     const timer = setTimeout(() => { void resource.reload(); }, 60_000);
     return () => clearTimeout(timer);
   }, [model?.status, resource.updatedAt]);
-  const notices = [identityError, resource.error, resource.data?.prices.error, ...(model?.warnings ?? [])]
+  const notices = [identityError, resource.error, resource.data?.prices.error, ...(model?.warnings ?? []), model?.staleNote]
     .filter((value): value is string => !!value);
   usePaneNoticeFooter({ registrationId: "iv-history-notices", notices: [...new Set(notices)], focused });
   const cycleLookback = () => setLookback(lookback === "1Y" ? "2Y" : lookback === "2Y" ? "ALL" : "1Y");
@@ -104,8 +107,9 @@ export function IvHistoryPane({ width, height, focused }: PaneProps) {
     const tone = row.percentile != null && (row.percentile >= 80 || row.percentile <= 20) ? colors.warning : colors.text;
     switch (id) {
       case "label": return { text: row.label, color: colors.textBright };
-      case "value": return { text: formatStat(row.value, row.unit), color: row.id.startsWith("iv30") ? colors.warning : colors.textBright };
-      case "date": return { text: row.date ? `${row.date} ${statSource(row)}` : "--", color: colors.textDim };
+      case "value": return { text: formatStat(row.value, row.unit), color: row.stale ? colors.textDim : row.id.startsWith("iv30") ? colors.warning : colors.textBright };
+      // A stale reading says so in place of how it was taken: it is no current figure either way.
+      case "date": return { text: row.date ? `${row.date} ${row.stale ? "stale" : statSource(row)}` : "--", color: row.stale ? colors.warning : colors.textDim };
       case "low": return { text: formatStat(row.low, row.unit), color: colors.textDim };
       case "high": return { text: formatStat(row.high, row.unit), color: colors.textDim };
       case "rank": return { text: formatRank(row.rank), color: tone };
@@ -119,7 +123,7 @@ export function IvHistoryPane({ width, height, focused }: PaneProps) {
       { id: "lookback", label: "Lookback", value: lookback, options: LOOKBACKS, onChange: setLookback },
       { id: "realized", label: "Realized", value: String(hvWindow), options: HV_OPTIONS, onChange: setHvWindow },
     ]} />
-    {!symbol ? <EmptyState title="Select a ticker." /> : <PaneStatusBody subject="implied volatility history" loading={resource.loading && !model}
+    {!symbol ? <EmptyState title="Select a ticker." /> : fxNote ? <PaneStatusBody empty emptyTitle={fxNote} /> : <PaneStatusBody subject="implied volatility history" loading={resource.loading && !model}
       error={!model ? resource.error ?? identityError ?? null : null} empty={!!model && !model.iv30.length && !model.quoteIv30.length}
       emptyTitle={model?.status === "queued" || model?.status === "backfilling" ? `Backfilling ${symbol} implied volatility history...` : undefined}>
       {model ? <>