gloomberb 0.18.2 → 0.18.4

package/src/market-data/depositary-pair.ts

@@ -0,0 +1,251 @@
+import type { DepositaryPair, Fundamentals, Quote } from "../types/financials";
+import { canonicalExchange, parsePublicTickerKey } from "../utils/exchanges";
+import { formatNumber } from "../utils/format";
+import { formatUtcDayTime } from "../utils/utc-time";
+import { heldCurrencyUnit } from "../utils/currency-units";
+import { regularSessionCloseOn } from "./market/freshness";
+import { getRegularSessionDisplay, regularSessionDisplayDate } from "./market/status";
+
+/**
+ * A depositary receipt beside its home listing: the ratio Gloom Cloud serves
+ * on both lines, the two prices, and the dollar rate they imply. For GGAL
+ * (1 ADR = 10 shares) at $37.91 and GGAL.BA at ARS 6,260, 6,260 × 10 / 37.91
+ * = 1,651 pesos a dollar: the rate paid by buying the shares in pesos and
+ * selling the receipt abroad, the CCL rate, against an official 1,529.
+ */
+
+/** A served pair, when it is whole: a receipt, a positive ratio, at least one home line. */
+function readDepositaryPair(value: unknown): DepositaryPair | null {
+  if (!value || typeof value !== "object") return null;
+  const { receipt, ratio, ordinary } = value as Partial<DepositaryPair>;
+  if (typeof receipt !== "string" || !receipt.trim()) return null;
+  if (typeof ratio !== "number" || !Number.isFinite(ratio) || ratio <= 0) return null;
+  const lines = Array.isArray(ordinary) ? ordinary.filter((line): line is string => typeof line === "string" && !!line.trim()) : [];
+  return lines.length > 0 ? { receipt: receipt.trim().toUpperCase(), ratio, ordinary: lines } : null;
+}
+
+type PairRecords = { quote?: Pick<Quote, "depositaryPair" | "isDepositaryReceipt"> | null; fundamentals?: Pick<Fundamentals, "depositaryPair" | "isDepositaryReceipt"> | null };
+
+/** The pair a listing's records name: the quote's, else the fundamentals'. */
+export function listingDepositaryPair(records: PairRecords | null | undefined): DepositaryPair | null {
+  return readDepositaryPair(records?.quote?.depositaryPair) ?? readDepositaryPair(records?.fundamentals?.depositaryPair);
+}
+
+/** Whether the listing is the pair's receipt rather than one of its home lines. */
+export function isReceiptSide(records: PairRecords | null | undefined): boolean {
+  return (records?.quote?.isDepositaryReceipt ?? records?.fundamentals?.isDepositaryReceipt) === true;
+}
+
+/** `10`, `0.25`: a ratio without float noise. */
+export function ratioCount(ratio: number): string {
+  return Number.isInteger(ratio) ? String(ratio) : String(Number(ratio.toPrecision(6)));
+}
+
+/** What a home line says of its receipt: `1 GGAL ADR = 10 of these shares`. */
+function homeLineRatioText(pair: DepositaryPair): string {
+  return `1 ${pair.receipt} ADR = ${ratioCount(pair.ratio)} of these share${pair.ratio === 1 ? "" : "s"}`;
+}
+
+/**
+ * The ratio as a listing's report states it, from its side of the pair:
+ * `1 ADR = 10 ordinary shares of GGAL.BA` on the receipt, `1 GGAL ADR = 10
+ * of these shares` on a home line.
+ */
+export function depositaryPairText(pair: DepositaryPair, receiptSide: boolean): string {
+  if (!receiptSide) return homeLineRatioText(pair);
+  return `1 ADR = ${ratioCount(pair.ratio)} ordinary share${pair.ratio === 1 ? "" : "s"} of ${pair.ordinary.join(" / ")}`;
+}
+
+/** A price as the comparison reads it, with when it was observed. */
+export interface PairPriceInput {
+  symbol: string;
+  price: number;
+  currency: string;
+  /** When the price was set: the last trade, or the close of a session that ended. */
+  observedAt: number | null;
+  /** The listing's regular session is trading. */
+  open: boolean;
+}
+
+/**
+ * A listing's regular-session price (an after-hours print never moves it),
+ * observed at its last trade while the session runs, and once it is over at
+ * that trade or the close, whichever came first.
+ */
+export function pairPriceInput(symbol: string, quote: Quote | null | undefined): PairPriceInput | null {
+  const quoted = getRegularSessionDisplay(quote)?.price;
+  if (!quote || quoted == null || !Number.isFinite(quoted) || quoted <= 0 || !quote.currency) return null;
+  // A price in a minor unit (pence, GBp) is read in its currency, as the dollar rate is served for it.
+  const unit = heldCurrencyUnit(quote.currency);
+  if (!unit.currency) return null;
+  const price = quoted / unit.divisor;
+  const open = quote.marketState === "REGULAR";
+  const lastUpdated = Number.isFinite(quote.lastUpdated) && quote.lastUpdated > 0 ? quote.lastUpdated : null;
+  const sessionDate = open ? null : regularSessionDisplayDate(quote);
+  const close = sessionDate ? regularSessionCloseOn(quote.listingExchangeName || quote.exchangeName, sessionDate) : null;
+  const observedAt = close != null && (lastUpdated == null || lastUpdated > close) ? close : lastUpdated;
+  return { symbol, price, currency: unit.currency, observedAt, open };
+}
+
+/** The home currency's dollar rate (units of it per USD) and when it was read. */
+export interface PairSpotInput {
+  rate: number;
+  observedAt: number | null;
+}
+
+/** The spot from a USD value of one unit of the currency, as exchange rates are served. */
+export function spotFromUsdValue(usdPerUnit: number | null | undefined, observedAt?: number | null): PairSpotInput | null {
+  if (usdPerUnit == null || !Number.isFinite(usdPerUnit) || usdPerUnit <= 0) return null;
+  return { rate: 1 / usdPerUnit, observedAt: observedAt ?? null };
+}
+
+export interface DepositaryPairComparison {
+  ratio: number;
+  receipt: PairPriceInput;
+  home: PairPriceInput;
+  /** Units of the home currency per dollar the two prices imply: home × ratio / receipt. */
+  impliedFx: number;
+  spot: PairSpotInput | null;
+  /** The receipt over the home shares it holds at spot, in percent: spot / implied - 1. */
+  premiumPercent: number | null;
+  /** Said when the two prices were not set together; null when they were. */
+  timingNote: string | null;
+}
+
+/** Inputs this far apart are from different times. */
+const SAME_TIME_MS = 30 * 60_000;
+
+/** `14 h 30 min`, `2 days 6 h`. */
+function gapText(ms: number): string {
+  const minutes = Math.round(ms / 60_000);
+  const days = Math.floor(minutes / 1440);
+  const hours = Math.floor((minutes % 1440) / 60);
+  const rest = minutes % 60;
+  if (days > 0) return [`${days} day${days === 1 ? "" : "s"}`, hours ? `${hours} h` : ""].filter(Boolean).join(" ");
+  return [hours ? `${hours} h` : "", rest || !hours ? `${rest} min` : ""].filter(Boolean).join(" ");
+}
+
+/** `Fri 23 Oct 20:00 UTC`. */
+export function pairTimeText(time: number, now = Date.now()): string {
+  return `${formatUtcDayTime({ time, dateOnly: false }, now)} UTC`;
+}
+
+function timingNote(receipt: PairPriceInput, home: PairPriceInput, now: number): string | null {
+  if (receipt.open && home.open) return null;
+  if (receipt.observedAt == null || home.observedAt == null) return null;
+  const gap = Math.abs(receipt.observedAt - home.observedAt);
+  if (receipt.open !== home.open) {
+    const [closed, trading] = receipt.open ? [home, receipt] : [receipt, home];
+    return `${closed.symbol} is closed, its price from ${pairTimeText(closed.observedAt!, now)}, while ${trading.symbol} trades: the prices are ${gapText(gap)} apart.`;
+  }
+  if (gap <= SAME_TIME_MS) return null;
+  const [first, second] = home.observedAt <= receipt.observedAt ? [home, receipt] : [receipt, home];
+  return `Both markets are closed: ${first.symbol} from ${pairTimeText(first.observedAt!, now)}, ${second.symbol} from ${pairTimeText(second.observedAt!, now)}, ${gapText(gap)} apart.`;
+}
+
+/** The comparison, or null when the receipt is not priced in dollars or a price is missing. */
+export function compareDepositaryPair(
+  ratio: number,
+  receipt: PairPriceInput | null,
+  home: PairPriceInput | null,
+  spot: PairSpotInput | null,
+  now = Date.now(),
+): DepositaryPairComparison | null {
+  if (!receipt || !home || !(ratio > 0) || receipt.currency !== "USD") return null;
+  const impliedFx = (home.price * ratio) / receipt.price;
+  if (!Number.isFinite(impliedFx) || impliedFx <= 0) return null;
+  const premiumPercent = spot ? (spot.rate / impliedFx - 1) * 100 : null;
+  return { ratio, receipt, home, impliedFx, spot, premiumPercent, timingNote: timingNote(receipt, home, now) };
+}
+
+/** `1,651.28`, `28.4942`, `0.890625`: a dollar rate to its useful digits. */
+export function formatPairRate(rate: number): string {
+  const size = Math.abs(rate);
+  return formatNumber(rate, size >= 100 ? 2 : size >= 1 ? 4 : 6);
+}
+
+/** `+14.3% premium`, `-7.4% discount`. */
+export function premiumText(percent: number): string {
+  const rounded = Math.round(percent * 10) / 10;
+  if (rounded === 0) return "0.0% at par";
+  return `${rounded > 0 ? "+" : ""}${rounded.toFixed(1)}% ${rounded > 0 ? "premium" : "discount"}`;
+}
+
+/** `USD/ARS`: the home currency's dollar pair, as `fx` names it. */
+export function dollarPairLabel(currency: string): string {
+  return `USD/${currency}`;
+}
+
+/** What the served dollar rate of a currency is, where it is not the one market rate: the peso's official one. */
+export function spotRateKind(currency: string): string | null {
+  return currency.trim().toUpperCase() === "ARS" ? "official wholesale" : null;
+}
+
+/**
+ * Buenos Aires lists a share's dollar lines under its peso symbol with a
+ * letter added: D settles in dollars at home (the MEP line), C abroad (the CCL
+ * line). Null for a listing elsewhere.
+ */
+export function bymaDollarLineKeys(homeKey: string): { mep: string; ccl: string } | null {
+  const { symbol, exchange } = parsePublicTickerKey(homeKey);
+  const suffix = /^(.+)\.BA$/i.exec(homeKey.trim());
+  if (suffix) return { mep: `${suffix[1]!.toUpperCase()}D.BA`, ccl: `${suffix[1]!.toUpperCase()}C.BA` };
+  if (canonicalExchange(exchange) !== "BYMA") return null;
+  return { mep: `${symbol.toUpperCase()}D.BA`, ccl: `${symbol.toUpperCase()}C.BA` };
+}
+
+/** The receipt the peso's implied dollar rates are read through: Galicia, the most traded Argentine pair. */
+export const PESO_REFERENCE_RECEIPT = "GGAL";
+
+type ImpliedDollarRateKind = "ccl-receipt" | "ccl-line" | "mep-line";
+
+/** A dollar rate a pair of prices implies, with the prices it came from. */
+export interface ImpliedDollarRate {
+  kind: ImpliedDollarRateKind;
+  /** `CCL via GGAL ADR`. */
+  label: string;
+  /** Pesos per dollar. */
+  rate: number;
+  /** `6,260 × 10 / 37.91`. */
+  formula: string;
+  inputs: PairPriceInput[];
+}
+
+const PESO_RATE_LABELS: Record<ImpliedDollarRateKind, (symbol: string) => string> = {
+  "ccl-receipt": (receipt) => `CCL via ${receipt} ADR`,
+  "ccl-line": (line) => `CCL via ${line}`,
+  "mep-line": (line) => `MEP via ${line}`,
+};
+
+/**
+ * The peso's market dollar rates from one Argentine pair: the CCL rate its
+ * receipt implies (home × ratio / receipt) and the one its Buenos Aires CCL
+ * line implies (home / C line), and the MEP rate of its D line (home / D
+ * line). A rate whose prices are missing is left out, as is the receipt's
+ * without a ratio on record.
+ */
+export function pesoImpliedRates(
+  receiptRatio: number | null,
+  inputs: { home: PairPriceInput | null; receipt: PairPriceInput | null; mep: PairPriceInput | null; ccl: PairPriceInput | null },
+): ImpliedDollarRate[] {
+  const { home } = inputs;
+  if (!home || home.currency !== "ARS") return [];
+  const rates: ImpliedDollarRate[] = [];
+  const price = (input: PairPriceInput) => formatNumber(input.price, input.price >= 100 ? 2 : 4).replace(/\.?0+$/, "");
+  const add = (kind: ImpliedDollarRateKind, dollar: PairPriceInput | null, ratio: number | null) => {
+    if (!dollar || dollar.currency !== "USD" || ratio == null || !(ratio > 0)) return;
+    const rate = (home.price * ratio) / dollar.price;
+    if (!Number.isFinite(rate) || rate <= 0) return;
+    rates.push({
+      kind,
+      label: PESO_RATE_LABELS[kind](dollar.symbol),
+      rate,
+      formula: `${price(home)}${ratio === 1 ? "" : ` × ${ratioCount(ratio)}`} / ${price(dollar)}`,
+      inputs: [home, dollar],
+    });
+  };
+  add("ccl-receipt", inputs.receipt, receiptRatio);
+  add("ccl-line", inputs.ccl, 1);
+  add("mep-line", inputs.mep, 1);
+  return rates;
+}

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

@@ -37,7 +37,7 @@ export interface FuturesContract {
    * is this future wherever a symbol is typed. Codes a security also uses (NG
    * is NovaGold, CL Colgate, ZM Zoom, GC several venues' listings) leave it
    * unset: the security keeps the code and the future is its `=F` symbol.
-   * Checked with `gloomberb quote <code>` signed out on 2026-10-11: each of
+   * Checked with `gloom quote <code>` signed out on 2026-10-11: each of
    * these was "Not a ticker", or for ZT and ZF a quote last updated in 2023 and
    * 2021 that search no longer lists. The sector, index and energy rows were
    * checked the same way on 2026-10-14: XAR is an ETF, XAU Goldmoney, SXI

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

@@ -4,10 +4,12 @@ import { classifyInstrumentType } from "../tickers/instrument-kind";
 import type { Quote } from "../types/financials";
 import { parsePublicTickerKey } from "../utils/exchanges";
 import { logFailure } from "../utils/log-failure";
-import { futuresBoardContract, type FuturesContract } from "./futures-board";
+import { futuresBoardContract, futuresContractByCode, type FuturesContract } from "./futures-board";
 import { formatMarketPrice, formatMarketPriceWithCurrency, quoteFormatOptions, withCurrencyMinorDigits } from "./market/format";
+import { previousPublishedSession } from "./market/freshness";
 import { minorUnitSign } from "../utils/currency-units";
 import { contractPriceUnit } from "../time-series/price-units";
+import { deliveryMonthLabel } from "../utils/contract-month";
 
 /**
  * What a futures symbol trades, as `ticker`, `quote` and the Overview tab read
@@ -85,6 +87,11 @@ export function futuresContractLines(terms: FuturesContractTermsPayload, symbol:
   const lines: FuturesContractLine[] = [];
   if (terms.contract && terms.contract !== contractCode(symbol)) lines.push({ key: "contract", label: "Contract", value: terms.contract });
   if (terms.spec) lines.push(...futuresSpecLines(terms.spec));
+  else {
+    // A root the server sends no terms for still says what its price counts: Dutch TTF gas is EUR / MWh.
+    const unit = futuresContractByCode(terms.root)?.unit;
+    if (unit) lines.push({ key: "unit", label: "Unit", value: unit });
+  }
   if (terms.firstNotice) {
     lines.push(terms.inDelivery
       ? { key: "firstNotice", label: "First Notice", value: `${terms.firstNotice} (passed)`, warning: true }
@@ -108,48 +115,119 @@ export function fitFuturesContractLines(lines: readonly FuturesContractLine[], m
  * Without a quote currency the price is a bare number, never a guessed `$`: a
  * grain settles in cents. A contract without a confirmed settlement reads
  * `--`: never an older settlement, and never the last trade.
+ *
+ * `movesFrom` is the session the Change line beside it is measured from
+ * (futuresChangeBasis). The settlement is confirmed overnight, after the
+ * quote has moved on to the next session, so for those hours the terms carry
+ * the session before the one the move is from: that settlement would sit
+ * beside a move from another session's close. It reads `--` and says which
+ * session is not confirmed yet. A settlement of that session or a later one
+ * is shown: the same session, or the one the move itself belongs to.
  */
 export function futuresSettleText(
   terms: Pick<FuturesContractTermsPayload, "settlement">,
   quote: Pick<Quote, "currency" | "instrumentType" | "priceBasis" | "providerPriceDivisor"> | null | undefined,
+  movesFrom?: string | null,
 ): string {
   if (!terms.settlement) return FUTURES_MISSING;
+  if (movesFrom && terms.settlement.date < movesFrom) return `${FUTURES_MISSING} (${movesFrom} not confirmed yet)`;
   const currency = quote?.currency;
   const options = withCurrencyMinorDigits(quoteFormatOptions(quote, "FUTURE"), currency);
   const price = currency ? formatMarketPriceWithCurrency(terms.settlement.price, currency, options) : formatMarketPrice(terms.settlement.price, options);
   return `${price} (${terms.settlement.date})`;
 }
 
-const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+/** The quantities a price is per, as traders abbreviate them: 467.25¢/bu for corn, $99.20/bbl for crude. */
+const PER_ABBREVIATIONS: Readonly<Record<string, string>> = {
+  bushel: "bu", bushels: "bu", pound: "lb", pounds: "lb", barrel: "bbl", barrels: "bbl", gallon: "gal", gallons: "gal",
+};
+
+type PricedTerms = Pick<FuturesContractTermsPayload, "spec"> & Partial<Pick<FuturesContractTermsPayload, "root">>;
 
-/** The quantities a cents price is per, as traders abbreviate them: 467.25¢/bu for corn. */
-const PER_ABBREVIATIONS: Readonly<Record<string, string>> = { bushel: "bu", bushels: "bu", pound: "lb", pounds: "lb" };
+/** What a root's price counts: the exchange's unit from the terms, else the catalog's (Dutch TTF gas has none from the server). */
+function termsPriceUnit(terms: PricedTerms | null | undefined): string | null {
+  return futuresPriceUnit(futuresContractByCode(terms?.root), terms);
+}
 
 /**
- * What a price in a minor unit is per, to follow its sign: "/lb" for coffee at
- * 314.95¢/lb, "/bu" for corn, from the contract's unit ("US cents / lb").
- * Empty for a price in a major currency, which reads as it always has, and
- * when the terms name no unit in the quote's own currency.
+ * What a futures price is per, to follow it: "/lb" for coffee at 314.95¢/lb
+ * and "/bu" for corn, where a cents sign alone says nothing of the quantity;
+ * and for every energy contract, "/MWh" for Dutch TTF gas at €90.30/MWh,
+ * "/MMBtu" for natural gas, "/bbl" for crude and "/gal" for gasoline and
+ * heating oil, whose price means little without it. Read from the contract's
+ * unit, the catalog's where the server sends none. Empty for any other price
+ * in a major currency, which reads as it always has, and when the unit is not
+ * in the quote's own currency.
  */
-export function minorUnitPricePer(
-  terms: Pick<FuturesContractTermsPayload, "spec"> | null | undefined,
-  currency: string | null | undefined,
-): string {
-  if (!minorUnitSign(currency)) return "";
-  const per = contractPriceUnit(terms?.spec?.unit, currency)?.split("/")[1]?.trim();
+export function futuresPricePer(terms: PricedTerms | null | undefined, currency: string | null | undefined): string {
+  if (!minorUnitSign(currency) && futuresContractByCode(terms?.root)?.sector !== "energy") return "";
+  const per = contractPriceUnit(termsPriceUnit(terms), currency)?.split("/")[1]?.trim();
   return per ? `/${PER_ABBREVIATIONS[per.toLowerCase()] ?? per}` : "";
 }
 
-const DAY_MS = 86_400_000;
-const isoDate = /^\d{4}-\d{2}-\d{2}$/;
+/** MMBtu in a megawatt hour: 3.412 (3,412,142 Btu). */
+const MMBTU_PER_MWH = 3.412;
 
 /**
- * The weekday on or before a date (`back` 0) or before it (`back` 1), Saturday
- * and Sunday skipped. Futures venues' holidays are not in the app's calendars,
- * so a holiday reads as a session.
+ * A gas price per MWh as dollars per MMBtu, the unit Henry Hub gas (NG)
+ * trades in, so European gas can be set against it: TTF at €90.30/MWh is
+ * $30.832/MMBtu at EUR/USD 1.1650. `usdPerUnit` is one unit of the price's
+ * currency in dollars. Null where the contract is not priced per MWh in that
+ * currency, or the rate is unknown.
  */
-function weekdayBefore(date: string, back: 0 | 1): string {
-  let at = Date.parse(`${date}T00:00:00Z`) - back * DAY_MS;
+export function usdPerMmbtu(
+  price: number,
+  terms: PricedTerms | null | undefined,
+  currency: string | null | undefined,
+  usdPerUnit: number | null | undefined,
+): number | null {
+  const unit = contractPriceUnit(termsPriceUnit(terms), currency);
+  if (!unit || unit.split("/")[1]?.trim().toLowerCase() !== "mwh") return null;
+  if (!Number.isFinite(price) || usdPerUnit == null || !Number.isFinite(usdPerUnit) || usdPerUnit <= 0) return null;
+  return (price * usdPerUnit) / MMBTU_PER_MWH;
+}
+
+/** A per-MWh gas price in dollars per MMBtu, and the rate it was converted at: one unit of its currency in dollars. */
+export interface UsdPerMmbtu {
+  value: number;
+  currency: string;
+  usdPerUnit: number;
+}
+
+/**
+ * A per-MWh gas price (Dutch TTF) in dollars per MMBtu at the rate `rate`
+ * reads for its currency (USD per unit); null for any other contract, or
+ * when the rate does not load.
+ */
+export async function loadUsdPerMmbtu(
+  price: number | null | undefined,
+  terms: PricedTerms | null | undefined,
+  currency: string | null | undefined,
+  rate: (currency: string) => Promise<number | null | undefined>,
+): Promise<UsdPerMmbtu | null> {
+  const code = currency?.trim().toUpperCase();
+  if (price == null || !code || usdPerMmbtu(price, terms, code, 1) == null) return null;
+  const usdPerUnit = code === "USD" ? 1 : await rate(code)
+    .catch(logFailure("futures-contract", "Read the rate for a gas price in USD failed", null));
+  const value = usdPerMmbtu(price, terms, code, usdPerUnit);
+  return value == null ? null : { value, currency: code, usdPerUnit: usdPerUnit! };
+}
+
+/**
+ * The dollar equivalent beside a per-MWh price, marked as a conversion and
+ * with the rate it used, the way converted market caps name theirs:
+ * "≈ $30.832/MMBtu at EUR/USD 1.1650".
+ */
+export function usdPerMmbtuText({ value, currency, usdPerUnit }: UsdPerMmbtu): string {
+  return `≈ $${value.toFixed(3)}/MMBtu at ${currency}/USD ${usdPerUnit.toFixed(4)}`;
+}
+
+const DAY_MS = 86_400_000;
+const isoDate = /^\d{4}-\d{2}-\d{2}$/;
+
+/** The weekday on or before a date, Saturday and Sunday skipped. */
+function weekdayOnOrBefore(date: string): string {
+  let at = Date.parse(`${date}T00:00:00Z`);
   while (new Date(at).getUTCDay() % 6 === 0) at -= DAY_MS;
   return new Date(at).toISOString().slice(0, 10);
 }
@@ -179,43 +257,49 @@ export interface FuturesChangeBasis {
 
 /**
  * What the move a futures quote headlines is measured from, for the words
- * after it ("vs Fri 16 Oct settle", quoteChangeBasis). `sessionDate` is the session the move belongs
- * to (regularSessionDisplayDate); a Saturday or Sunday is Friday's, as no
- * session is dated on one. The basis is only what the numbers show, against
- * the one settlement the contract terms carry: a reference (the price less
- * the move) within half a tick of it is that settlement, of whichever session
- * it is. A reference that is not the settlement of the session just before
- * the move's is that session's last trade. Otherwise, when the terms carry no
- * settlement that old or one the reference can be checked against (the move's
- * own session has settled, and the one before is not in the terms), it is the
- * session before's close, left unnamed. Null without a session date, a move
- * or terms.
+ * after it ("vs Fri 16 Oct settle", quoteChangeBasis). `sessionDate` is the
+ * session the move belongs to (regularSessionDisplayDate); a Saturday or
+ * Sunday is Friday's, as no session is dated on one, and a holiday CME Globex
+ * traded is the next trade date's. The basis is only what the numbers show,
+ * against the one settlement the contract terms carry: a reference (the price
+ * less the move) within half a tick of it is that settlement, of whichever
+ * session it is. A reference that is not the settlement of the session just
+ * before the move's is that session's last trade. Otherwise, when the terms
+ * carry no settlement that old or one the reference can be checked against
+ * (the move's own session has settled, and the one before is not in the
+ * terms), it is the session before's close, left unnamed. The session before
+ * is the trade date before the move's on the `exchange`'s published holiday
+ * calendar (previousPublishedSession), so the Tuesday after Memorial Day
+ * moves from Friday. On a venue without one, only a matching settlement is
+ * named, by the date the terms give it. Null without a session date, a move
+ * or terms, or when nothing but the calendar could date the reference and
+ * there is none.
  */
 export function futuresChangeBasis(
   terms: Pick<FuturesContractTermsPayload, "settlement"> & { spec?: Pick<FuturesContractSpec, "tick"> | null } | null | undefined,
   move: { price: number; change?: number | null; sessionDate?: string | null } | null | undefined,
+  exchange: string | null | undefined,
 ): FuturesChangeBasis | null {
   const dated = move?.sessionDate;
   if (!terms || !move || !dated || !isoDate.test(dated) || move.change == null) return null;
   const reference = move.price - move.change;
   if (!Number.isFinite(reference)) return null;
-  const session = weekdayBefore(dated, 0);
-  const previous = weekdayBefore(session, 1);
+  const session = weekdayOnOrBefore(dated);
+  const previous = previousPublishedSession(exchange ?? undefined, dated, { closedDayRollsForward: true })?.date ?? null;
   const settled = terms.settlement;
   if (settled && settled.date <= session) {
     if (Math.abs(reference - settled.price) <= settlementTolerance(terms.spec?.tick, settled.price)) {
       return { kind: "settle", session: settled.date };
     }
-    if (settled.date < session && settled.date >= previous) return { kind: "last trade", session: settled.date };
+    if (settled.date === previous) return { kind: "last trade", session: settled.date };
   }
-  return { kind: "close", session: previous };
+  return previous ? { kind: "close", session: previous } : null;
 }
 
-/** A listed contract as code and month: "NGX26 (Nov 26)". */
+/** A listed contract as code and month: "NGX26 (Nov 2026)". */
 function contractWithMonth(contract: { contract: string; deliveryMonth: string }): string {
-  const [year, month] = contract.deliveryMonth.split("-");
-  const name = MONTHS[Number(month) - 1];
-  return name && year ? `${contract.contract} (${name} ${year.slice(2)})` : contract.contract;
+  const month = deliveryMonthLabel(contract.deliveryMonth);
+  return month ? `${contract.contract} (${month})` : contract.contract;
 }
 
 /**

package/src/market-data/fx-closes.ts

@@ -108,11 +108,26 @@ const isoDay = (time: number) => new Date(time).toISOString().slice(0, 10);
  * in that week. A cost bought on a date and `fx --date` both read it.
  */
 export async function fxCloseOnDate(leg: FxLeg, date: string, client: FxHistoryClient, now = new Date()): Promise<FxCloseReading | null> {
+  return (await readFxCloseOnDate(leg, date, client, now)).reading;
+}
+
+/**
+ * `fxCloseOnDate`'s reading, and whether the service answered with any daily
+ * bars of the pair at all: an `empty` or `unsupported` answer is a pair it
+ * keeps no daily closes of, not a week without one.
+ */
+export async function readFxCloseOnDate(
+  leg: FxLeg,
+  date: string,
+  client: FxHistoryClient,
+  now = new Date(),
+): Promise<{ reading: FxCloseReading | null; served: boolean }> {
   const day = Date.parse(`${date}T00:00:00Z`);
   const response = await client.getCloudHistory(leg.instrument.symbol, leg.instrument.exchange ?? "", {
     interval: "1day", startDate: isoDay(day - FX_MAX_AGE_DAYS * DAY_MS), endDate: isoDay(day + DAY_MS), outputsize: FX_MAX_AGE_DAYS + 4,
   });
-  if (response.status !== "success" && response.status !== "partial") return null;
+  const served = response.status !== "empty" && response.status !== "unsupported";
+  if (response.status !== "success" && response.status !== "partial") return { reading: null, served };
   const today = isoDay(now.getTime());
   let best: FxCloseReading | null = null;
   for (const row of Array.isArray(response.data) ? response.data : []) {
@@ -122,7 +137,7 @@ export async function fxCloseOnDate(leg: FxLeg, date: string, client: FxHistoryC
     if (rowDay > date || rowDay >= today || Date.parse(`${rowDay}T00:00:00Z`) < day - FX_MAX_AGE_DAYS * DAY_MS) continue;
     if (!best || rowDay > best.date) best = { rate: leg.invert ? 1 / row.close : row.close, date: rowDay };
   }
-  return best;
+  return { reading: best, served };
 }
 
 /**

package/src/market-data/hooks.tsx

@@ -1,4 +1,5 @@
 import { logFailure } from "../utils/log-failure";
+import { fxRateCurrencies } from "../utils/currency-units";
 import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import type { SecFilingDocument, SecFilingItem } from "../types/data-provider";
 import type { OptionsChain, PricePoint, Quote, TickerFinancials } from "../types/financials";
@@ -77,13 +78,7 @@ function useCoordinatorKeysVersion(keys: readonly string[]): number {
   return useSyncExternalStore(subscribe, getSnapshot, () => 0);
 }
 
-function stableCurrencyList(currencies: Array<string | null | undefined>): string[] {
-  return [...new Set(
-    currencies
-      .map((currency) => currency?.trim().toUpperCase() ?? "")
-      .filter(Boolean),
-  )].sort((left, right) => left.localeCompare(right));
-}
+
 
 function buildTickerFinancialsMapKey(tickers: TickerRecord[], options: TickerInstrumentOptions = {}): string {
   return tickers.map((ticker) => {
@@ -570,9 +565,22 @@ export function useArticleSummary(url: string | null | undefined): QueryEntry<st
   return entry;
 }
 
+/** A currency's US dollar rate as the app holds it, and when its source observed it (epoch ms; null when undated, and for USD). */
+export interface FxRateObservation {
+  rate: number;
+  asOf: number | null;
+}
+
 export function useFxRatesMap(currencies: Array<string | null | undefined>): Map<string, number> {
+  const observations = useFxRateObservations(currencies);
+  return useMemo(() => new Map([...observations].map(([currency, observation]) => [currency, observation.rate])), [observations]);
+}
+
+/** useFxRatesMap with each rate's observation time, for a figure that states the rate it was converted at. */
+export function useFxRateObservations(currencies: Array<string | null | undefined>): Map<string, FxRateObservation> {
   const coordinator = getSharedMarketDataCoordinator();
-  const normalizedCurrencyKey = stableCurrencyList(currencies).join("|");
+  // A minor unit's major currency is loaded too: GBX and ILA have no rate of their own.
+  const normalizedCurrencyKey = fxRateCurrencies(currencies).join("|");
   const normalizedCurrencies = useMemo(
     () => (normalizedCurrencyKey ? normalizedCurrencyKey.split("|") : []),
     [normalizedCurrencyKey],
@@ -605,12 +613,12 @@ export function useFxRatesMap(currencies: Array<string | null | undefined>): Map
   }, [appVisible, normalizedCurrencyKey]);
 
   return useMemo(() => {
-    const rates = new Map<string, number>();
-    rates.set("USD", 1);
+    const rates = new Map<string, FxRateObservation>();
+    rates.set("USD", { rate: 1, asOf: null });
     for (const [currency, entry] of entries) {
       const rate = resolveEntryValue(entry);
       if (rate != null) {
-        rates.set(currency, rate);
+        rates.set(currency, { rate, asOf: entry?.asOf ?? null });
       }
     }
     return rates;