gloomberb 0.18.4 → 0.19.0

package/src/market-data/market/dated-previous-close.ts

@@ -0,0 +1,203 @@
+import type { MarketDataRequestContext } from "../../types/data-provider";
+import type { PricePoint, Quote } from "../../types/financials";
+import { abortable, settleWithin, withDeadline } from "../../utils/async-deadline";
+import { canonicalExchange } from "../../utils/exchanges";
+import { logFailure } from "../../utils/log-failure";
+import { dailyBarDate } from "../../utils/price-history";
+import { classifyInstrumentType } from "../../tickers/instrument-kind";
+import { changeBasisSessionDate, isChangeBasisDatedWithoutCloses, quoteChangeBasis } from "./change-basis";
+
+/** History closes come as float32 (30.93000030517578) where the quote says 30.93: one close. */
+const SAME_CLOSE_RELATIVE = 1e-5;
+/**
+ * How long a reading that named no day stands before the closes are read
+ * again: a history a session behind catches up, a failed read is retried.
+ */
+const UNDATED_RETRY_MS = 10 * 60_000;
+/** Readings kept at once; the oldest goes first. */
+const MAX_READINGS = 2_000;
+/** Daily histories read at once. */
+const MAX_READS_IN_FLIGHT = 6;
+/** How long one read may take before its slot goes to the next: a hung read must not stall the rest. */
+const READ_DEADLINE_MS = 10_000;
+
+/** The listing a quote was asked for, as its daily closes are read: its context names a broker's contract. */
+export interface DatedCloseListing {
+  symbol: string;
+  exchange: string;
+  context?: MarketDataRequestContext;
+}
+
+/** A listing's recent daily closes (a month is enough). */
+export type ReadDailyCloses = (listing: DatedCloseListing) => Promise<readonly Pick<PricePoint, "date" | "close">[]>;
+
+export interface PreviousCloseDatesOptions {
+  /** Called with the latest copy of a quote, dated, when a read lands that names its day. */
+  onDated?: (listing: DatedCloseListing, quote: Quote) => void;
+  now?: () => number;
+  maxReadsInFlight?: number;
+  readDeadlineMs?: number;
+}
+
+interface Reading {
+  date: string | null;
+  at: number;
+}
+
+/** One listing whatever spelling of its exchange a request used. */
+export function datedCloseListingKey(listing: DatedCloseListing): string {
+  return `${listing.symbol.trim().toUpperCase()}|${canonicalExchange(listing.exchange)}`;
+}
+
+function sameClose(left: number, right: number): boolean {
+  return Math.abs(left - right) <= Math.max(Math.abs(left), Math.abs(right)) * SAME_CLOSE_RELATIVE;
+}
+
+/**
+ * What dates a quote's previous close by its listing's daily closes: the
+ * listing, the session the move is dated to and the close itself. Null for a
+ * quote something else dates (its venue's calendar, a coin's UTC day, a
+ * future's terms, a close the source dated), one with no move from a previous
+ * close, and an option, whose chain would read a history per contract. The
+ * venue's calendar is checked first, since this runs on every tick.
+ */
+function readingKey(quote: Quote | null | undefined, listing: DatedCloseListing, now: number): string | null {
+  if (!quote || isChangeBasisDatedWithoutCloses(quote, now) || classifyInstrumentType(quote.instrumentType) === "option") return null;
+  if (quoteChangeBasis(quote)?.kind !== "previous close") return null;
+  const previousClose = quote.previousClose;
+  const sessionDate = changeBasisSessionDate(quote);
+  if (previousClose == null || !Number.isFinite(previousClose) || !sessionDate) return null;
+  return `${datedCloseListingKey(listing)}|${sessionDate}|${previousClose}`;
+}
+
+/**
+ * The day of the latest daily close before the move's session, when that
+ * close is the quote's previous close; null otherwise, so a gap in the
+ * history never names the wrong day.
+ */
+function latestCloseBefore(points: readonly Pick<PricePoint, "date" | "close">[], quote: Quote): string | null {
+  const sessionDate = changeBasisSessionDate(quote)!;
+  const exchange = quote.listingExchangeName ?? quote.exchangeName ?? "";
+  const before = points
+    .map((point) => ({ time: new Date(point.date).getTime(), close: point.close }))
+    .filter((point) => Number.isFinite(point.time) && Number.isFinite(point.close))
+    .map((point) => ({ date: dailyBarDate(point.time, exchange), close: point.close }))
+    .filter((point) => point.date < sessionDate)
+    .sort((left, right) => left.date.localeCompare(right.date))
+    .at(-1);
+  return before && sameClose(before.close, quote.previousClose!) ? before.date : null;
+}
+
+function withDate<T extends Quote | null | undefined>(quote: T, date: string | null | undefined): T {
+  return date && quote ? { ...quote, previousCloseDate: date } : quote;
+}
+
+/**
+ * Dates the previous close a quote's move is from where the venue's calendar
+ * cannot (LSE and Helsinki publish none the app carries), by the listing's
+ * own daily closes, so every surface that reads quotes through the app's
+ * quote router names the day (`quoteChangeBasis`). The closes are read once
+ * per listing, session and close, and the answer is kept: a refresh, a tick
+ * or a cached read of the same quote is dated without another read. A few
+ * reads run at once, each for at most ten seconds.
+ */
+export class PreviousCloseDates {
+  private readonly readings = new Map<string, Reading>();
+  private readonly pending = new Map<string, Promise<string | null>>();
+  /** The latest copy of each quote a read is pending for, which the read dates when it lands. */
+  private readonly latestCopies = new Map<string, { quote: Quote; listing: DatedCloseListing }>();
+  private readonly waiting: Array<() => void> = [];
+  private active = 0;
+  private readonly now: () => number;
+  private readonly maxReadsInFlight: number;
+  private readonly readDeadlineMs: number;
+
+  constructor(private readonly readCloses: ReadDailyCloses, private readonly options: PreviousCloseDatesOptions = {}) {
+    this.now = options.now ?? (() => Date.now());
+    this.maxReadsInFlight = options.maxReadsInFlight ?? MAX_READS_IN_FLIGHT;
+    this.readDeadlineMs = options.readDeadlineMs ?? READ_DEADLINE_MS;
+  }
+
+  /** The quote dated by what was already read for it; as it was when nothing was. Never reads. */
+  known<T extends Quote | null | undefined>(quote: T, listing: DatedCloseListing): T {
+    const key = readingKey(quote, listing, this.now());
+    return key ? withDate(quote, this.readings.get(key)?.date) : quote;
+  }
+
+  /**
+   * The quote dated by what was already read for it, starting the read when
+   * no reading for it stands. Never waits: the read dates the copies after
+   * it, and `onDated` the latest one.
+   */
+  observe<T extends Quote | null | undefined>(quote: T, listing: DatedCloseListing): T {
+    const key = readingKey(quote, listing, this.now());
+    if (!key) return quote;
+    const reading = this.readings.get(key);
+    if (!this.stands(reading)) void this.start(key, quote!, listing);
+    return withDate(quote, reading?.date);
+  }
+
+  /**
+   * Starts the reads these quotes need and waits for them, at most `waitMs`
+   * in all and no longer than `signal` lets it; `known` then dates them.
+   */
+  async settle(
+    entries: ReadonlyArray<{ quote: Quote; listing: DatedCloseListing }>,
+    { waitMs, signal }: { waitMs: number; signal?: AbortSignal },
+  ): Promise<void> {
+    if (signal?.aborted) return;
+    const reads: Promise<string | null>[] = [];
+    for (const { quote, listing } of entries) {
+      const key = readingKey(quote, listing, this.now());
+      if (key && !this.stands(this.readings.get(key))) reads.push(this.start(key, quote, listing));
+    }
+    if (reads.length) await settleWithin(abortable(Promise.all(reads), signal, "Stopped waiting for daily closes"), waitMs);
+  }
+
+  /** Whether a reading answers without another read: a day it named, or no day named lately. */
+  private stands(reading: Reading | undefined): boolean {
+    return !!reading && (!!reading.date || this.now() - reading.at < UNDATED_RETRY_MS);
+  }
+
+  private start(key: string, quote: Quote, listing: DatedCloseListing): Promise<string | null> {
+    this.latestCopies.set(key, { quote, listing });
+    return this.pending.get(key) ?? this.read(key, quote, listing);
+  }
+
+  private read(key: string, quote: Quote, listing: DatedCloseListing): Promise<string | null> {
+    const read = this.inSlot(() => withDeadline(Promise.resolve().then(() => this.readCloses(listing)), this.readDeadlineMs, "Reading daily closes timed out"))
+      .then((points) => latestCloseBefore(points, quote))
+      .catch(logFailure("market-data.dated-previous-close", "Read daily closes failed", null))
+      .then((date) => {
+        this.pending.delete(key);
+        this.readings.delete(key);
+        if (this.readings.size >= MAX_READINGS) this.readings.delete(this.readings.keys().next().value!);
+        this.readings.set(key, { date, at: this.now() });
+        const latest = this.latestCopies.get(key);
+        this.latestCopies.delete(key);
+        if (date && latest && this.options.onDated) {
+          try {
+            this.options.onDated(latest.listing, withDate(latest.quote, date));
+          } catch (error) {
+            logFailure("market-data.dated-previous-close", "Passing on a dated quote failed")(error);
+          }
+        }
+        return date;
+      });
+    this.pending.set(key, read);
+    return read;
+  }
+
+  private async inSlot<T>(work: () => Promise<T>): Promise<T> {
+    if (this.active < this.maxReadsInFlight) this.active += 1;
+    else await new Promise<void>((resolve) => this.waiting.push(resolve));
+    try {
+      return await work();
+    } finally {
+      // A finished read hands its slot to the next one waiting.
+      const next = this.waiting.shift();
+      if (next) next();
+      else this.active -= 1;
+    }
+  }
+}

package/src/market-data/market/format.ts

@@ -628,6 +628,31 @@ function currencyMarks(currency: string, normalizedCurrency: string, code = fals
   return code ? { prefix: "", suffix: ` ${normalizedCurrency}` } : { prefix: getCurrencySymbol(normalizedCurrency), suffix: "" };
 }
 
+/**
+ * A London line shown in pounds and served in the pence it trades in. The
+ * code is compared in its own case: `GBp` (and `GBX`) is a price already in
+ * pence, which says so itself (630.8p) and needs no pence figure beside it.
+ */
+export function isPenceQuotedLine(quote: Pick<Quote, "currency" | "providerPriceDivisor"> | null | undefined): boolean {
+  return quote?.currency?.trim() === "GBP" && quote.providerPriceDivisor === 100;
+}
+
+/**
+ * A London line's price in the pence it trades in, as the exchange and its
+ * announcements write it: `630.8p` for £6.308, with the decimals of a penny
+ * the pounds are shown to (`poundDecimals`) beyond two. Null for a price not
+ * quoted in pence.
+ */
+export function penceFigure(
+  value: number | null | undefined,
+  quote: Pick<Quote, "currency" | "providerPriceDivisor"> | null | undefined,
+  poundDecimals: number,
+): string | null {
+  if (value == null || !Number.isFinite(value) || !isPenceQuotedLine(quote)) return null;
+  const digits = Math.max(0, Math.min(4, poundDecimals - 2));
+  return `${getNumberFormatter(digits, digits, true).format(value * 100)}${minorUnitSign("GBp")}`;
+}
+
 export function formatMarketPriceWithCurrency(
   value: number | undefined,
   currency = "USD",

package/src/market-data/market/freshness.ts

@@ -32,7 +32,8 @@ const REGULAR_OPEN_MINUTES: Record<string, number> = {
   TSXV: 9 * 60 + 30,
   CSE: 9 * 60 + 30,
   FWB2: 8 * 60,
-  XETRA: 8 * 60,
+  // Continuous trading opens at 09:00 Berlin time, after the opening auction; before it is pre-trading.
+  XETRA: 9 * 60,
   LSE: 8 * 60,
   EPA: 9 * 60,
   AMS: 9 * 60,

package/src/market-data/market/futures-week.ts

@@ -0,0 +1,68 @@
+import { canonicalExchange } from "../../utils/exchanges";
+import { zonedDateTimeParts, zonedWallClockToUtcMs } from "../../utils/zoned-date-time";
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+const FRIDAY = 5;
+
+/**
+ * CME Group's Globex week runs from Sunday 17:00 Central to Friday 16:00
+ * Central, 17:00 in New York, which ICE Futures U.S. keeps too
+ * (cmegroup.com/trading-hours, ice.com). Nothing trades between, whatever
+ * state a quote stamped before the Friday close still carries. The venues
+ * have no other calendar here: their daily breaks and holiday sessions vary
+ * by contract, so the quote's own state says those.
+ */
+const WEEK_ZONE = "America/Chicago";
+const WEEK_CLOSE_MINUTES = 16 * 60;
+const WEEK_OPEN_MINUTES = 17 * 60;
+
+/**
+ * The futures venues the weekly gap covers, and whether the week's first open
+ * is theirs to name: every Globex contract opens by Sunday 17:00 Central, but
+ * an ICE U.S. one opens when its own hours say, from Sunday evening (cotton)
+ * to Monday morning (coffee), so the venue has no one reopen to give.
+ */
+const WEEK_VENUES: Readonly<Record<string, { reopens: boolean }>> = {
+  CME: { reopens: true },
+  CBT: { reopens: true },
+  NYM: { reopens: true },
+  CMX: { reopens: true },
+  NYB: { reopens: false },
+};
+
+export interface FuturesWeekendClosure {
+  /** The Friday close that began it. */
+  closedAt: number;
+  /** The Sunday open that ends it, when the venue's contracts all open then or later. */
+  reopensAt?: number;
+  /** That open's local date, `YYYY-MM-DD` (always a Sunday). */
+  reopensOn?: string;
+}
+
+/**
+ * The weekend gap of a futures venue's week that `time` falls in, from the
+ * Friday close to the Sunday open; null on any other instant, and for a venue
+ * that is not a futures exchange here. Only ever the closed side: a moment
+ * outside it is not known to be open.
+ */
+export function futuresWeekendClosure(exchange: string | undefined, time: number): FuturesWeekendClosure | null {
+  const venue = WEEK_VENUES[canonicalExchange(exchange)];
+  if (!venue || !Number.isFinite(time)) return null;
+  const { year, month, day } = zonedDateTimeParts(time, WEEK_ZONE);
+  const today = Date.UTC(year, month - 1, day) / MS_PER_DAY;
+  const weekday = new Date(today * MS_PER_DAY).getUTCDay();
+  // The latest Friday on or before the local date: a Monday to Thursday reads last week's, whose gap has ended.
+  const friday = today - ((weekday - FRIDAY + 7) % 7);
+  const at = (days: number, minutes: number) => {
+    const date = new Date(days * MS_PER_DAY);
+    return zonedWallClockToUtcMs(WEEK_ZONE, date.getUTCFullYear(), date.getUTCMonth() + 1, date.getUTCDate(),
+      Math.floor(minutes / 60), minutes % 60, 0);
+  };
+  const closedAt = at(friday, WEEK_CLOSE_MINUTES);
+  const reopensAt = at(friday + 2, WEEK_OPEN_MINUTES);
+  if (time < closedAt || time >= reopensAt) return null;
+  return {
+    closedAt,
+    ...(venue.reopens ? { reopensAt, reopensOn: new Date((friday + 2) * MS_PER_DAY).toISOString().slice(0, 10) } : {}),
+  };
+}

package/src/market-data/market/status.ts

@@ -6,6 +6,7 @@ import { quoteTradingDay } from "../quotes/day-range";
 import { isQuoteBeforeLatestSession } from "../quotes/freshness";
 import { delistingLabel, delistingStateLabel } from "../quotes/delisting";
 import { preMarketOpenOn, regularSessionCloseOn } from "./freshness";
+import { futuresWeekendClosure } from "./futures-week";
 
 const CLOSED_CHANGE_MUTING_RATIO = 0.55;
 const US_SESSION_TIME = new Intl.DateTimeFormat("en-US", {
@@ -97,6 +98,17 @@ function closeLabel(date: string): string {
   return `${WEEKDAYS[new Date(`${date}T00:00:00Z`).getUTCDay()]} close`;
 }
 
+/**
+ * The market state a quote's venue is in now. A futures venue's weekend gap
+ * closes every contract, so it outranks the state a quote stamped before the
+ * Friday close (a stale print reading REGULAR on a Sunday); every other quote
+ * keeps the state its source reported.
+ */
+function quoteMarketState(quote: Quote | null | undefined, now = Date.now()): MarketState | undefined {
+  if (!quote?.marketState) return undefined;
+  return futuresWeekendClosure(quote.listingExchangeName || quote.exchangeName, now) ? "CLOSED" : quote.marketState;
+}
+
 /**
  * A quote's market state as a status cell names it (marketStateLabel), STALE
  * for a print older than its venue's latest session, and the close it stands
@@ -109,7 +121,7 @@ export function quoteMarketStateLabel(quote: Quote | null | undefined, now = Dat
   if (!quote?.marketState) return null;
   if (isQuoteBeforeLatestSession(quote, now)) return STALE_SESSION_LABEL;
   const awaiting = preMarketCloseAwaitingPrint(quote);
-  return awaiting ? closeLabel(awaiting.date) : marketStateLabel(quote.marketState);
+  return awaiting ? closeLabel(awaiting.date) : marketStateLabel(quoteMarketState(quote, now)!);
 }
 
 /** An extended session's column, named as marketStateLabel names its state. */
@@ -216,7 +228,7 @@ function sessionLabel(quote: Quote | null | undefined, now: number, standingClos
   if (isQuoteBeforeLatestSession(quote, now)) return STALE_SESSION_LABEL;
   if (overnightSessionDisplay(quote)) return "OVERNIGHT";
   const awaiting = standingClose ? preMarketCloseAwaitingPrint(quote) : null;
-  return awaiting ? closeLabel(awaiting.date) : marketStateLabel(quote.marketState);
+  return awaiting ? closeLabel(awaiting.date) : marketStateLabel(quoteMarketState(quote, now)!);
 }
 
 /**
@@ -230,7 +242,7 @@ export function quoteSessionColor(quote: Quote | null | undefined, palette: Them
   if (!quote?.marketState) return palette.textDim;
   if (isQuoteBeforeLatestSession(quote, now)) return palette.warning;
   if (overnightSessionDisplay(quote)) return marketStateColor("POST", palette);
-  return marketStateColor(preMarketCloseAwaitingPrint(quote) ? "CLOSED" : quote.marketState, palette);
+  return marketStateColor(preMarketCloseAwaitingPrint(quote) ? "CLOSED" : quoteMarketState(quote, now)!, palette);
 }
 
 /**
@@ -239,7 +251,7 @@ export function quoteSessionColor(quote: Quote | null | undefined, palette: Them
  * with no known session rather than an open market.
  */
 export function quoteDotMarketState(quote: Quote | null | undefined, now = Date.now()): MarketState | undefined {
-  return quote && !quote.delisting && !isQuoteBeforeLatestSession(quote, now) ? quote.marketState : undefined;
+  return quote && !quote.delisting && !isQuoteBeforeLatestSession(quote, now) ? quoteMarketState(quote, now) : undefined;
 }
 
 /** Closed prices are final snapshots, so they should not look live or directional. */

package/src/market-data/options-alternatives.ts

@@ -1,3 +1,6 @@
+import { isRoundTheClockCoin } from "../utils/crypto-pair";
+import { currencyPairCode, isCurrencyCode } from "../utils/currency-pair";
+import { parsePublicTickerKey } from "../utils/exchanges";
 import { parseFuturesGeneric } from "../utils/futures-generic";
 
 /** A US-listed fund whose options track an instrument that has none of its own. */
@@ -32,23 +35,24 @@ const FUTURES_ALTERNATIVES: Readonly<Record<string, ListedOptionsAlternative>> =
   ZN: { symbol: "IEF", name: "iShares 7-10 Year Treasury Bond ETF" },
   "6E": { symbol: "FXE", name: "Invesco CurrencyShares Euro Trust" },
   "6J": { symbol: "FXY", name: "Invesco CurrencyShares Japanese Yen Trust" },
+  "6B": { symbol: "FXB", name: "Invesco CurrencyShares British Pound Sterling Trust" },
   BTC: { symbol: "IBIT", name: "iShares Bitcoin Trust" },
   ETH: { symbol: "ETHA", name: "iShares Ethereum Trust" },
 };
 
 const MONTH_CODE_CONTRACT = /^([A-Z0-9]{1,3}?)[FGHJKMNQUVXZ]\d{1,4}$/;
 
-/** The futures root a symbol names: GC=F, GCZ26 and the generic GC1 all give GC. */
-function futuresRoot(symbol: string): string | null {
+/** The futures root a symbol names: GC=F, GCZ26 and the generic GC1 all give GC. `known` says which roots a bare contract may carry. */
+function futuresRoot(symbol: string, known: (root: string) => boolean = (root) => !!FUTURES_ALTERNATIVES[root]): string | null {
   const ticker = symbol.trim().toUpperCase().replace(/[.:][A-Z]+$/, "");
   if (ticker.endsWith("=F")) {
     const body = ticker.slice(0, -2);
-    return FUTURES_ALTERNATIVES[body] ? body : MONTH_CODE_CONTRACT.exec(body)?.[1] ?? body;
+    return known(body) ? body : MONTH_CODE_CONTRACT.exec(body)?.[1] ?? body;
   }
   const generic = parseFuturesGeneric(ticker);
   if (generic) return generic.root;
   const contract = MONTH_CODE_CONTRACT.exec(ticker)?.[1];
-  return contract && FUTURES_ALTERNATIVES[contract] ? contract : null;
+  return contract && known(contract) ? contract : null;
 }
 
 /** The listed fund whose options stand in for an instrument with no chain, if there is one. */
@@ -67,3 +71,136 @@ export function isOptionsUnavailableError(error: unknown): boolean {
 export function optionsUnavailableTitle(symbol: string): string {
   return `Options are not available for ${symbol.trim().toUpperCase()}.`;
 }
+
+/**
+ * The coins whose options Gloom Cloud serves, from Deribit, as BTC-USD and
+ * ETH-USD: the standard options path (options, OMON, OPX, OVDV).
+ */
+const COIN_OPTION_UNDERLYINGS: Readonly<Record<string, string>> = { BTC: "BTC-USD", ETH: "ETH-USD" };
+
+/** BTC-USD or ETH-USD for a coin pair whose options are listed (on the coin board or bare); null otherwise. */
+export function listedCoinOptions(symbol: string): string | null {
+  const parsed = parsePublicTickerKey(symbol.trim().toUpperCase());
+  if (!isRoundTheClockCoin(parsed.symbol, parsed.exchange)) return null;
+  const pair = /^([A-Z0-9]+)-USD$/.exec(parsed.symbol)?.[1];
+  return pair ? COIN_OPTION_UNDERLYINGS[pair] ?? null : null;
+}
+
+/** A coin (SOL-USD, DOGE-USD) nothing lists options on: only BTC and ETH have them. */
+export function isCoinWithoutOptions(symbol: string): boolean {
+  const parsed = parsePublicTickerKey(symbol.trim().toUpperCase());
+  return isRoundTheClockCoin(parsed.symbol, parsed.exchange) && listedCoinOptions(symbol) == null;
+}
+
+/**
+ * What exists instead for a coin without options, worded for the CLI:
+ * BTC and ETH options, and the bitcoin-linked US listings with their own,
+ * each as the command that reads it (`options`, or `fn OPX`).
+ */
+export function coinOptionsAlternativesText(command = "options"): string {
+  const run = (symbol: string) => `gloomberb ${command} ${symbol}`;
+  return `Listed crypto options cover BTC and ETH: ${run("BTC-USD")}, ${run("ETH-USD")}.`
+    + ` Bitcoin-linked US listings have their own: ${run("IBIT")}.`;
+}
+
+/** The same for a pane, which has no commands to give. */
+export const COIN_OPTIONS_HINT = "Listed crypto options cover BTC-USD and ETH-USD; bitcoin-linked US funds such as IBIT list their own.";
+
+/**
+ * An options function's `refuseSymbol`: a coin nothing lists options on
+ * (SOL-USD) is answered before any request, with what exists instead.
+ */
+export function coinWithoutOptionsRefusal(code: string) {
+  return (key: string): { message: string; details: string } | null => isCoinWithoutOptions(key)
+    ? { message: optionsUnavailableTitle(parsePublicTickerKey(key.trim().toUpperCase()).symbol), details: coinOptionsAlternativesText(`fn ${code}`) }
+    : null;
+}
+
+/**
+ * A CLI options function's `symbolAlias` (`gloomberb fn OPX BTC`, `shot`): a
+ * bare BTC or ETH is read as the coin, with a note naming the Grayscale fund's
+ * listing (BTC:ARCA) for its own options (`code` is the function, OPX). The
+ * command bar and panes keep a bare BTC as the fund, as everywhere else.
+ */
+export function coinOptionsAlias(code: string) {
+  return (typed: string): { symbol: string; note: string } | null => {
+    const key = typed.trim().toUpperCase();
+    const pair = COIN_OPTION_UNDERLYINGS[key];
+    return pair ? { symbol: pair, note: `${key} read as ${pair}, the coin's options. For the US fund that trades as ${key}: gloomberb fn ${code} ${key}:ARCA` } : null;
+  };
+}
+
+/**
+ * The CME currency futures, each as the pair it settles on, in the order the
+ * pair is quoted: 6E is EUR/USD, 6J USD/JPY. No chain of options on any of
+ * them is served here, as none is on the spot pair.
+ */
+const FX_FUTURES_PAIRS: Readonly<Record<string, string>> = {
+  "6E": "EURUSD", "6J": "USDJPY", "6B": "GBPUSD", "6A": "AUDUSD", "6C": "USDCAD", "6S": "USDCHF", "6N": "NZDUSD", "6M": "USDMXN",
+};
+
+/** The US-listed currency funds whose options stand in for an FX pair's volatility, by the currency they hold. */
+const FX_VOL_FUNDS: Readonly<Record<string, string>> = { EUR: "FXE", JPY: "FXY", GBP: "FXB" };
+/** The fund that holds the dollar against a basket, for a pair none of the single-currency funds holds. */
+const DOLLAR_FUND = "UUP";
+const FX_VOL_FUND_LIST = [...Object.values(FX_VOL_FUNDS), DOLLAR_FUND];
+
+/** The pair a symbol is: a spot pair in any spelling (EURUSD=X, EUR/USD), or a currency future (6E=F, 6EZ26, 6E1) as the pair it settles on; null for anything else. */
+export function fxVolatilityPair(symbol: string, exchange?: string): string | null {
+  const spot = currencyPairCode(symbol, exchange);
+  // Metals quoted against a currency (XAUUSD=X) are no currency pair.
+  if (spot) return isCurrencyCode(spot.slice(0, 3)) && isCurrencyCode(spot.slice(3)) ? spot : null;
+  const root = futuresRoot(symbol, (candidate) => !!FX_FUTURES_PAIRS[candidate]);
+  return root ? FX_FUTURES_PAIRS[root] ?? null : null;
+}
+
+/**
+ * The listed fund that stands in for an FX pair's volatility: the one that
+ * holds the pair's euro, yen or pound, else the dollar index fund.
+ */
+function fxVolatilityFunds(pair: string): string[] {
+  const held = [pair.slice(0, 3), pair.slice(3)].map((code) => FX_VOL_FUNDS[code]).filter((fund): fund is string => !!fund);
+  return held.length > 0 ? held : FX_VOL_FUND_LIST;
+}
+
+/**
+ * What exists instead for the volatility of an FX pair or currency future,
+ * worded as one line for the CLI: OTC FX volatility is not served, the
+ * currency funds' options are the nearest listed thing (the one that holds
+ * the pair's euro, yen or pound, else any of them), and HVT reads the pair's
+ * realized volatility. Null for anything that is no FX pair. `code` is the
+ * function asked (OVDV), `symbol` as typed.
+ */
+function fxVolatilityAnswer(code: string, symbol: string): string | null {
+  const pair = fxVolatilityPair(symbol);
+  if (!pair) return null;
+  const typed = symbol.trim().toUpperCase();
+  const funds = fxVolatilityFunds(pair);
+  // VCA screens every fund; the others read the pair's own, or the dollar's when it has none.
+  const read = code === "VCA" ? funds.join(",") : funds === FX_VOL_FUND_LIST ? DOLLAR_FUND : funds[0]!;
+  return `OTC FX volatility is not covered for ${typed}. Currency-ETF options are the listed proxy: `
+    + `${funds.join(", ")} (gloom fn ${code} ${read}). Realized volatility: gloom fn HVT ${typed}.`;
+}
+
+/**
+ * The same for a pane, which has no commands to give: what is not covered,
+ * the funds whose options stand in, and HVT for realized volatility.
+ */
+export function fxVolatilityNote(symbol: string, exchange?: string): string | null {
+  const pair = fxVolatilityPair(symbol, exchange);
+  if (!pair) return null;
+  return `OTC FX volatility is not covered for ${symbol.trim().toUpperCase()}. Currency-ETF options are the listed proxy: `
+    + `${fxVolatilityFunds(pair).join(", ")}. HVT shows the pair's realized volatility.`;
+}
+
+/**
+ * A volatility function's `refuseSymbol` for FX (OVDV, VCA, HIVG): an FX pair
+ * or currency future is answered before any request, with one line saying
+ * OTC FX volatility is not covered and what to read instead.
+ */
+export function fxVolatilityRefusal(code: string) {
+  return (key: string): { message: string; details?: string } | null => {
+    const message = fxVolatilityAnswer(code, key);
+    return message ? { message } : null;
+  };
+}

package/src/market-data/quotes/contributions.ts

@@ -20,7 +20,7 @@ const PRICE_DENOMINATED_DESCRIPTIVE_FIELDS: ReadonlySet<string> = new Set(["high
  * reconciled separately (reconcileQuoteDayRange).
  */
 const TRADING_DAY_FIELDS = [
-  "changeSessionDate", "previousClose", "open", "volume", "mark", "bid", "ask", "bidSize", "askSize",
+  "changeSessionDate", "previousClose", "previousCloseDate", "open", "volume", "mark", "bid", "ask", "bidSize", "askSize",
   "lastTradePrice", "lastTradeTime",
 ] as const;
 
@@ -36,6 +36,12 @@ function isOtherTradingDay(current: Quote, next: Quote): boolean {
   return currentDay !== null && nextDay !== null && nextDay !== currentDay;
 }
 
+/** Whether two observations are known to describe the same trading day. */
+function isSameTradingDay(current: Quote, next: Quote): boolean {
+  const currentDay = quoteTradingDay(current);
+  return currentDay !== null && currentDay === quoteTradingDay(next);
+}
+
 function inferQuoteProviderId(quote: Quote | QuoteContribution): string {
   if (quote.providerId?.trim()) return quote.providerId;
   return "quote";
@@ -195,7 +201,7 @@ export function mergeQuoteContribution(
     // Close provenance belongs to this observation; never borrow an anchor
     // from another session, listing or currency when a new quote omits it.
     ...(!samePriceBasis ? {
-      previousClose: next.previousClose, bid: next.bid, ask: next.ask,
+      previousClose: next.previousClose, previousCloseDate: next.previousCloseDate, bid: next.bid, ask: next.ask,
       open: next.open, mark: next.mark, high52w: next.high52w, low52w: next.low52w,
       lastTradePrice: next.lastTradePrice, lastTradeTime: next.lastTradeTime,
       preMarketPrice: next.preMarketPrice, preMarketChange: next.preMarketChange,
@@ -232,6 +238,18 @@ export function mergeQuoteContribution(
     delete merged.changeBasis;
   } else if (next.previousClose === undefined) {
     delete merged.previousClose;
+    delete merged.previousCloseDate;
+  }
+  // The day a previous close is from is said of that close and that session: a tick that names
+  // none keeps it while both are the same, and drops it otherwise. A close can repeat across
+  // sessions (a flat day), so the trading day decides, not the close alone.
+  if (next.previousCloseDate === undefined) {
+    const sameClose = next.previousClose === undefined || next.previousClose === current.previousClose;
+    if (samePriceBasis && sameClose && merged.previousClose === current.previousClose && current.previousCloseDate && isSameTradingDay(current, next)) {
+      merged.previousCloseDate = current.previousCloseDate;
+    } else {
+      delete merged.previousCloseDate;
+    }
   }
 
   if (isOtherTradingDay(current, next)) {

package/src/market-data/quotes/resolution.ts

@@ -221,6 +221,8 @@ function assignDailyChangeFields(
   }
 
   assignField(target, provenance, "previousClose", referenceProvider);
+  // The day that close is from comes with it, from the same source.
+  if (referenceProvider.previousCloseDate) target.previousCloseDate = referenceProvider.previousCloseDate;
   const price = target.price;
   const previousClose = target.previousClose;
   if (!finitePositiveNumber(price) || !finitePositiveNumber(previousClose)) {
@@ -500,6 +502,7 @@ export function resolveCanonicalQuote(
     // What that move is from when it is not previousClose; absent when it is.
     ...(resolved.changeBasis ? { changeBasis: resolved.changeBasis } : {}),
     previousClose: resolved.previousClose as Quote["previousClose"],
+    ...(resolved.previousCloseDate ? { previousCloseDate: resolved.previousCloseDate } : {}),
     regularClose: priceProvider?.regularClose,
     regularCloseSessionDate: priceProvider?.regularClose != null ? priceProvider.regularCloseSessionDate : undefined,
     regularChange: priceProvider?.regularClose != null ? priceProvider.regularChange : undefined,

package/src/market-data/selectors.ts

@@ -6,6 +6,7 @@ import { hasLikelyQuoteUnitMismatch } from "../utils/currency-units";
 import { normalizePriceHistory } from "../utils/price-history";
 import { resolveTickerFinancialsQuoteState } from "./quotes/resolution";
 import { instrumentIdentityKey } from "../utils/instrument-identity";
+import { withSavedCopyMarkOf } from "../data/saved-copies";
 
 export function toMarketDataContext(instrument: InstrumentRef): MarketDataRequestContext {
   return {
@@ -123,6 +124,8 @@ export function buildTickerFinancialsSnapshot(
 
   return {
     ...resolved,
+    // The quote shown is a saved copy when the newest quote answered was one.
+    ...(resolved.quote ? { quote: withSavedCopyMarkOf(resolved.quote, quote ?? snapshot?.quote) } : {}),
     priceHistory: normalizePriceHistory(priceHistory ?? snapshot?.priceHistory ?? []),
   };
 }