@gloom-sh/terminal 0.18.5 → 0.19.0

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 ? <>

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

@@ -8,14 +8,14 @@ import { Box, Text, useUiCapabilities } from "../../../ui";
 import { wrapTextLines } from "../../../utils/text-wrap";
 import { useAutoRefresh } from "../../../react/auto-refresh";
 import { compareSortValues, nextHeaderSort, type SortDirection } from "../../../utils/sort-values";
-import { loadIvScreen, loadScreenVolatilities } from "./client";
-import { formatPoints, formatRank, formatSpot, formatVol, readingLabel, sharedDates, shortDate, VCA_DEFINITIONS, verdictLabel } from "./format";
-import { projectRichCheap, type RichCheapRow, richCheapDates, screenPaneNotices, type VcaPreset } from "./model";
+import { loadIvScreen, loadScreenVolatilities, type ScreenHv } from "./client";
+import { formatPoints, formatRank, formatSpot, formatVol, readingLabel, sharedDates, shortDate, vcaDefinitions, verdictLabel } from "./format";
+import { projectRichCheap, readingSource, type RichCheapRow, richCheapDates, screenPaneNotices, type VcaPreset } from "./model";
 import { vcaUniverse } from "./universe";
 import { MovedTickerState } from "../../../components/layout/pane/ticker-fate-gate";
 import type { MovedTickerChange } from "../../../tickers/ticker-changes";
 
-type SortId = keyof RichCheapRow;
+type SortId = Exclude<keyof RichCheapRow, "stale">;
 const HV_WINDOW = 20;
 /** Pane borders and the footer's own padding. */
 const FOOTER_MARGIN = 6;
@@ -31,9 +31,10 @@ const COLUMNS: DataTableColumn[] = [
   { id: "iv1y", label: "IV1Y", width: 7, align: "right" },
   { id: "iv1yPercentile", label: "IVP1Y", width: 6, align: "right" },
   { id: "termSlope", label: "30-90", width: 7, align: "right" },
-  { id: "skew", label: "25D skew", width: 9, align: "right" },
-  { id: "skewDate", label: "Skew as of", width: 11, align: "right" },
+  { id: "riskReversal", label: "25D RR", width: 9, align: "right" },
+  { id: "skewDate", label: "RR as of", width: 11, align: "right" },
   { id: "hv", label: `HV${HV_WINDOW}`, width: 7, align: "right" },
+  { id: "hvDate", label: "HV as of", width: 9, align: "right" },
   { id: "ivHv", label: "IV/HV", width: 6, align: "right" },
 ];
 
@@ -49,7 +50,7 @@ export function IvScreenPane({ paneId, width, height, focused }: PaneProps) {
   const universe = useMemo(() => vcaUniverse(scope, symbolsText, collectionId, [...tickers.values()]), [scope, symbolsText, collectionId, tickers]);
   const key = universe.instruments.map((instrument) => instrument.symbol).join(",");
   const controller = useRef<AbortController | null>(null);
-  const [hv, setHv] = useState<Map<string, number | null>>(new Map());
+  const [hv, setHv] = useState<Map<string, ScreenHv | null>>(new Map());
   // Symbols whose company moved: their rows have no HV and the footer says where each company went.
   const [moved, setMoved] = useState<Array<{ symbol: string; change: MovedTickerChange }>>([]);
   const loader = useCallback(async () => {
@@ -83,17 +84,21 @@ export function IvScreenPane({ paneId, width, height, focused }: PaneProps) {
   }, [resource.data, hv, sort]);
   const dates = useMemo(() => richCheapDates(rows), [rows]);
   // A date every row shares moves to the footer; a column no row fills, or whose dates agree, is left out.
+  const hasSkew = useMemo(() => rows.some((row) => row.riskReversal != null), [rows]);
+  // A close solved from quote midpoints names itself, which a date alone has no room for.
+  const dateWidth = useMemo(() => rows.some((row) => !row.stale && readingSource(row.method, row.basis) === "close mid") ? 15 : 11, [rows]);
   const columns = useMemo(() => COLUMNS.filter((column) => {
     switch (column.id) {
       case "date": return !dates.reading;
       case "rankDate": return dates.rankApart;
       case "iv1y": return rows.some((row) => row.iv1y != null);
       case "iv1yPercentile": return rows.some((row) => row.iv1yPercentile != null);
-      case "skew": return rows.some((row) => row.skew != null);
+      case "riskReversal": return hasSkew;
       case "skewDate": return dates.skewApart;
+      case "hvDate": return dates.hvApart;
       default: return true;
     }
-  }), [rows, dates]);
+  }).map((column) => column.id === "date" ? { ...column, width: dateWidth } : column), [rows, dates, hasSkew, dateWidth]);
   const [selected, setSelected] = useState<string | null>(null);
   const coverageNotices = useMemo(() => screenPaneNotices(rows), [rows]);
   // One symbol to screen whose company moved has nothing to show but where it went, as a ticker's panes say.
@@ -117,10 +122,10 @@ export function IvScreenPane({ paneId, width, height, focused }: PaneProps) {
   const cell = (row: RichCheapRow, id: string): { text: string; color?: string } => {
     switch (id) {
       case "symbol": return { text: row.symbol, color: colors.textBright };
-      case "iv30": return { text: formatVol(row.iv30), color: colors.warning };
+      case "iv30": return { text: formatVol(row.iv30), color: row.stale ? colors.textDim : colors.warning };
       case "spot": return { text: formatSpot(row.spot), color: colors.textDim };
-      case "date": return { text: row.date ? readingLabel(row.date, row.method, true)
-        : row.status === "queued" || row.status === "backfilling" ? row.status : "--", color: colors.textDim };
+      case "date": return { text: row.date ? readingLabel(row.date, row.method, true, { basis: row.basis, stale: row.stale })
+        : row.status === "queued" || row.status === "backfilling" ? row.status : "--", color: row.stale ? colors.warning : colors.textDim };
       case "rankDate": return { text: row.rankDate ? `${shortDate(row.rankDate)} close` : "--", color: colors.textDim };
       case "rank": return { text: formatRank(row.rank) };
       case "percentile": return { text: formatRank(row.percentile) };
@@ -128,16 +133,18 @@ export function IvScreenPane({ paneId, width, height, focused }: PaneProps) {
       case "iv1y": return { text: formatVol(row.iv1y) };
       case "iv1yPercentile": return { text: formatRank(row.iv1yPercentile) };
       case "termSlope": return { text: formatPoints(row.termSlope), color: row.termSlope != null && row.termSlope > 0 ? colors.negative : colors.text };
-      case "skew": return { text: formatPoints(row.skew) };
+      case "riskReversal": return { text: formatPoints(row.riskReversal) };
       case "skewDate": return { text: row.skewDate ? readingLabel(row.skewDate, "quote-mid", true) : "--", color: colors.textDim };
       case "hv": return { text: hv.has(row.symbol) ? formatVol(row.hv) : "...", color: colors.positive };
+      case "hvDate": return { text: row.hvDate ? shortDate(row.hvDate) : "--", color: colors.textDim };
       case "ivHv": return { text: row.ivHv == null ? "--" : row.ivHv.toFixed(2) };
       default: return { text: "" };
     }
   };
   const custom = scope === "custom";
   // The skew's sign and VIX beside IV30 are units of the figures above them, so they stay under the table.
-  const definitions = useMemo(() => VCA_DEFINITIONS.flatMap((line) => wrapTextLines(line, Math.max(1, width - 2))), [width]);
+  const definitionLines = useMemo(() => vcaDefinitions({ skew: hasSkew }), [hasSkew]);
+  const definitions = useMemo(() => definitionLines.flatMap((line) => wrapTextLines(line, Math.max(1, width - 2))), [definitionLines, width]);
   return <Box width={width} height={height} flexDirection="column" overflow="hidden">
     <QueryBar width={width} filters={[
       { id: "universe", label: "Universe", value: VCA_SCOPE_OPTIONS.some((option) => option.value === scope) ? scope : "etfs",
@@ -159,7 +166,7 @@ export function IvScreenPane({ paneId, width, height, focused }: PaneProps) {
       {nativePaneChrome ? (
         // The desktop and the web wrap each definition at the pane's width, under a table that fills the rest.
         <Box flexDirection="column" paddingX={1} flexShrink={0}>
-          {VCA_DEFINITIONS.map((line) => <Prose key={line} text={line} width={Math.max(1, width - 2)} color={colors.textDim} figures={false} />)}
+          {definitionLines.map((line) => <Prose key={line} text={line} width={Math.max(1, width - 2)} color={colors.textDim} figures={false} />)}
         </Box>
       ) : (
         <Box flexDirection="column" paddingX={1} height={definitions.length} flexShrink={0}>

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

@@ -1,3 +1,4 @@
+import { fxVolatilityNote } from "../../../market-data/options-alternatives";
 import type { InstrumentRef } from "../../../market-data/request-types";
 import type { TickerRecord } from "../../../types/ticker";
 import { canonicalExchange } from "../../../utils/exchanges";
@@ -33,7 +34,10 @@ export function vcaUniverse(scope: string, symbolsText: string, collectionId: st
     instruments = VCA_PRESETS[preset].map((symbol) => ({ symbol, exchange: "" }));
   }
   const valid = [...new Map(instruments.filter((instrument) => SYMBOL.test(instrument.symbol)).map((instrument) => [instrument.symbol, instrument])).values()];
-  const error = !valid.length ? scope === "collection" ? "Link a watchlist or portfolio with US-listed symbols in pane settings." : "Add symbols in pane settings."
+  // An FX pair or currency future typed in a list is left out with what stands in for it, not as a symbol that does not parse.
+  const fx = scope === "custom" ? instruments.flatMap((instrument) => fxVolatilityNote(instrument.symbol, instrument.exchange) ?? []) : [];
+  const error = !valid.length ? fx[0] ?? (scope === "collection" ? "Link a watchlist or portfolio with US-listed symbols in pane settings." : "Add symbols in pane settings.")
+    : fx.length ? fx[0]!
     : valid.length > VCA_LIMIT ? `Only the first ${VCA_LIMIT} symbols are screened.`
       : skipped ? `${skipped} non-US listing${skipped === 1 ? "" : "s"} left out: stored implied volatility covers US option underlyings.` : null;
   return { label, instruments: valid.slice(0, VCA_LIMIT), error };

package/src/plugins/builtin/jobs/client.ts

@@ -1,4 +1,5 @@
 import { apiClient } from "../../../api-client";
+import { createTtlCache } from "../../../data/ttl-cache";
 import { ApiRequestError } from "../../../api-client/errors";
 import type {
   CloudJobsMoversPayload,
@@ -25,43 +26,38 @@ export type JobsCompanyState =
   | { kind: "denied"; status: 401 | 402 | 403; message: string };
 
 const SUMMARY_TTL_MS = 5 * 60_000;
-const summaryCache = new Map<string, { at: number; state: JobsCompanyState }>();
-
-function cachedJobs(ticker: string): JobsCompanyState | null {
-  const entry = summaryCache.get(ticker.toUpperCase());
-  if (!entry || Date.now() - entry.at > SUMMARY_TTL_MS) return null;
-  return entry.state;
-}
+/**
+ * `pending` is never kept, so the pane's poll reads it afresh each time, and
+ * `denied` is not either: the account can change under the pane.
+ */
+const summaries = createTtlCache<JobsCompanyState>({
+  ttlMs: SUMMARY_TTL_MS,
+  keep: (state) => state.kind === "ready" || state.kind === "uncovered",
+});
 
-export async function fetchJobs(
-  ticker: string,
-  options: { name?: string | null; force?: boolean; client?: JobsCloudClient } = {},
-): Promise<JobsCompanyState> {
-  const key = ticker.toUpperCase();
-  if (!options.force) {
-    const cached = cachedJobs(key);
-    // A pending answer is never served from cache: the point is to poll.
-    if (cached && cached.kind !== "pending") return cached;
-  }
-  const client = options.client ?? apiClient;
-  let state: JobsCompanyState;
+async function loadJobs(key: string, name: string | null | undefined, client: JobsCloudClient): Promise<JobsCompanyState> {
   try {
-    const response: CloudJobsResponse = await client.getCloudJobs(key, options.name);
-    state = response.status === "pending"
+    const response: CloudJobsResponse = await client.getCloudJobs(key, name);
+    return response.status === "pending"
       ? { kind: "pending", ticker: key, message: response.message }
       : { kind: "ready", summary: response };
   } catch (error) {
     if (error instanceof ApiRequestError && error.status === 404) {
-      state = { kind: "uncovered", ticker: key, message: error.message };
-    } else if (error instanceof ApiRequestError && (error.status === 401 || error.status === 402 || error.status === 403)) {
-      // Not cached: the account can change under the pane.
+      return { kind: "uncovered", ticker: key, message: error.message };
+    }
+    if (error instanceof ApiRequestError && (error.status === 401 || error.status === 402 || error.status === 403)) {
       return { kind: "denied", status: error.status, message: error.message };
-    } else {
-      throw error;
     }
+    throw error;
   }
-  summaryCache.set(key, { at: Date.now(), state });
-  return state;
+}
+
+export function fetchJobs(
+  ticker: string,
+  options: { name?: string | null; force?: boolean; client?: JobsCloudClient } = {},
+): Promise<JobsCompanyState> {
+  const key = ticker.toUpperCase();
+  return summaries.load(key, () => loadJobs(key, options.name, options.client ?? apiClient), { force: options.force });
 }
 
 export function fetchJobsPostings(
@@ -81,5 +77,5 @@ export function fetchJobsMovers(
 }
 
 export function resetJobsCache(): void {
-  summaryCache.clear();
+  summaries.clear();
 }