gloomberb 0.16.3 → 0.16.5

package/src/plugins/builtin/futures-curve/client.ts

@@ -1,6 +1,7 @@
 import { apiClient } from "../../../api-client";
 import type { FuturesCurvePayload } from "../../../api-client/futures-curve";
 import { createPluginCache } from "../../../data/plugin-cache";
+import { isFuturesContractSpec } from "../../../market-data/futures-contract";
 import { loadCloudResource, unavailableOnServer } from "../shared/cloud-resource";
 import type { DataProvider } from "../../../types/data-provider";
 import { archivedFuturesCurve, curveLookbackDate, curveSpot, normalizeCurveRoot, unsupportedCurveRootMessage, type CurveSpot } from "./model";
@@ -13,13 +14,17 @@ const finiteOrNull = (value: unknown) => value === null || typeof value === "num
 const timestamp = (value: unknown) => typeof value === "string" && Number.isFinite(Date.parse(value));
 const date = (value: unknown) => timestamp(value) && new Date(value as string).toISOString().slice(0, 10) === value;
 const rank = (value: unknown) => value === null || typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 100;
+const optionalDate = (value: unknown) => value === undefined || value === null || date(value);
+/** Contract terms the pane computes with; a curve from before the server sent them has none. */
+const validSpec = (spec: unknown) => spec === undefined || spec === null || isFuturesContractSpec(spec);
 
 export function validateFuturesCurve(data: FuturesCurvePayload, root: string): FuturesCurvePayload {
   if (!data || data.root !== root || !Array.isArray(data.contracts) || !Array.isArray(data.ghosts)
     || !Array.isArray(data.gaps) || !data.gaps.every((gap) => typeof gap === "string")
     || !data.catalogue || !data.slope || !timestamp(data.fetchedAt)
     || data.asOf !== null && !timestamp(data.asOf)
-    || !["gloom", "cboe"].includes(data.source) || !["available", "partial", "unavailable"].includes(data.status)) {
+    || !["gloom", "cboe"].includes(data.source) || !["available", "partial", "unavailable"].includes(data.status)
+    || !optionalDate(data.settlementDate) || !validSpec(data.spec)) {
     throw new Error("The server returned an invalid futures curve");
   }
   const symbols = new Set<string>();
@@ -30,7 +35,9 @@ export function validateFuturesCurve(data: FuturesCurvePayload, root: string): F
       || typeof row.currency !== "string"
       || !rank(row.percentile) || !Number.isInteger(row.samples) || row.samples < 0
       || row.asOf !== null && !timestamp(row.asOf)
-      || ![row.volume, row.openInterest, row.delayMinutes].every((value) => finiteOrNull(value) && (value === null || value >= 0))) {
+      || ![row.volume, row.openInterest, row.delayMinutes].every((value) => finiteOrNull(value) && (value === null || value >= 0))
+      || row.settlement !== undefined && !finiteOrNull(row.settlement) || !optionalDate(row.lastTrade) || !optionalDate(row.firstNotice)
+      || row.inDelivery !== undefined && typeof row.inDelivery !== "boolean") {
       throw new Error("The server returned an invalid futures contract");
     }
     symbols.add(row.symbol);
@@ -80,7 +87,9 @@ export async function loadFuturesCurveAsOf(root: string, date: string,
       client.getCloudFuturesCurveAsOf(normalized, curveLookbackDate(date, 30)).catch(() => null),
     ]);
     if (!curve || curve.root !== normalized || !Array.isArray(curve.contracts) || !Array.isArray(curve.gaps)
-      || curve.contracts.some((row) => !row || typeof row.symbol !== "string" || !Number.isFinite(row.price))) {
+      || curve.contracts.some((row) => !row || typeof row.symbol !== "string" || !Number.isFinite(row.price)
+        || row.settled !== undefined && typeof row.settled !== "boolean" || !optionalDate(row.firstNotice) || !optionalDate(row.lastTrade))
+      || !validSpec(curve.spec)) {
       throw new Error("The server returned an invalid past futures curve");
     }
     return archivedFuturesCurve(normalized, curve, { "1W": week, "1M": month }, new Date().toISOString());

package/src/plugins/builtin/futures-curve/headless.ts

@@ -1,7 +1,9 @@
-import type { HeadlessPaneDefinition, HeadlessPaneFreshness } from "../../../types/plugin";
+import type { FuturesContract, FuturesCurvePayload } from "../../../api-client/futures-curve";
+import { futuresSpecLines } from "../../../market-data/futures-contract";
+import type { HeadlessPaneColumn, HeadlessPaneDefinition, HeadlessPaneEntry, HeadlessPaneFreshness } from "../../../types/plugin";
 import { newestReportTime, oldestReportTime } from "../../../utils/utc-time";
 import { fetchFuturesCurve, loadCurveSpot, loadFuturesCurveAsOf } from "./client";
-import { basisSpotSymbol, contractBasis, curveAsOfDate, curveSpotLabel, normalizeCurveRoot, thinContractCount, unsupportedCurveRootMessage } from "./model";
+import { basisSpotSymbol, catalogueCurveUnit, contractBasis, curveAsOfDate, curveBasisPercent, curveChangeText, curveContractCode, curvePrice, curveRoundedPrice, curveSpotLabel, curveSpreadLabel, curveTimestamp, curveUnitLabel, normalizeCurveRoot, thinContractCount, unsupportedCurveRootMessage, type ContractBasis } from "./model";
 
 /** The root a report shows when none is given. */
 const DEFAULT_ROOT = "ES";
@@ -12,6 +14,63 @@ const rank = (value: number | null) => value == null ? null : Math.round(value);
 /** The basis fields are read to four decimals, finer than any cell shows. */
 const basisValue = (value: number | null) => value == null ? null : Number(value.toFixed(4));
 
+/**
+ * One contract as the report reads it, the same fields in the same order for
+ * every root. Prices and changes are at the root's tick precision. `price` is
+ * the latest trade and `settlement` the exchange settlement for the curve's
+ * settlement session (a past curve's settled rows have no separate trade).
+ */
+function contractRow(row: FuturesContract, data: FuturesCurvePayload, root: string, past: boolean, basis?: ContractBasis) {
+  const price = (value: number | null | undefined) => curveRoundedPrice(value, root);
+  return {
+    symbol: row.symbol, label: row.label, expiration: row.expiration, lastTrade: row.lastTrade ?? row.expiration,
+    firstNotice: row.firstNotice ?? null, inDelivery: row.inDelivery ?? false,
+    settlement: price(row.settlement), settlementDate: row.settlement != null ? data.settlementDate ?? null : null,
+    price: past && row.settlement != null ? null : price(row.price), change: price(row.change),
+    asOf: row.asOf, stale: row.stale, volume: row.volume, openInterest: row.openInterest, percentile: rank(row.percentile),
+    samples: row.samples, historyStart: row.historyStart, historyEnd: row.historyEnd,
+    currency: row.currency, quoteUnit: curveUnitLabel(data) ?? row.quoteUnit, delayMinutes: row.delayMinutes,
+    ...(basis ? { vsSpotPct: basisValue(basis.vsSpotPct), annualisedBasisPct: basisValue(basis.annualisedBasisPct) } : {}),
+  };
+}
+
+/** The text table: what a hedge reads, in one order for every root; JSON keeps every field. */
+function contractColumns(root: string, settlementDate: string | null, options: { basis: boolean; last: boolean; notice: boolean }): HeadlessPaneColumn[] {
+  const price = (value: unknown) => typeof value === "number" ? curvePrice(value, root) : "--";
+  const date = (value: unknown) => typeof value === "string" ? value : "--";
+  return [
+    { key: "symbol", header: "Contract", shrink: false, format: (value) => curveContractCode(String(value)) },
+    { key: "lastTrade", header: "Last Trade", shrink: false, format: date },
+    // Cash-settled roots have no first notice day.
+    ...options.notice ? [{ key: "firstNotice", header: "1st Notice", shrink: false,
+      format: (value: unknown, row: Record<string, unknown>) => typeof value === "string" ? `${value}${row.inDelivery ? " passed" : ""}` : "--" }] : [],
+    { key: "settlement", header: settlementDate ? `Settle ${settlementDate}` : "Settle", align: "right", format: price },
+    // A Cboe price is the settlement itself, with no separate last trade.
+    ...options.last ? [{ key: "price", header: "Last", align: "right" as const, format: price }] : [],
+    { key: "change", header: "Change", align: "right", format: (value) => typeof value === "number" ? curveChangeText(value, root) : "--" },
+    ...options.basis ? [{ key: "vsSpotPct", header: "Vs Spot", align: "right" as const, format: (value: unknown) => curveBasisPercent(typeof value === "number" ? value : null, 2) },
+      { key: "annualisedBasisPct", header: "Ann Basis", align: "right" as const, format: (value: unknown) => curveBasisPercent(typeof value === "number" ? value : null, 1) }] : [],
+    { key: "asOf", header: "As Of UTC", shrink: false, format: (value) => typeof value === "string" ? curveTimestamp(value) : "--" },
+    { key: "openInterest", header: "Open Int", align: "right", format: (value) => typeof value === "number" ? value.toLocaleString("en-US") : "--" },
+    { key: "volume", header: "Volume", align: "right", format: (value) => typeof value === "number" ? value.toLocaleString("en-US") : "--" },
+    { key: "percentile", header: "Pctl", align: "right", format: (value) => typeof value === "number" ? String(value) : "--" },
+  ];
+}
+
+/** What one contract is: the terms a hedge is sized on, once rather than on every row, worded as `ticker` words them. */
+function specEntries(data: FuturesCurvePayload): HeadlessPaneEntry[] {
+  const spec = data.spec;
+  // A root without terms still says what its prices count: Dutch TTF gas is euros per MWh.
+  if (!spec) {
+    const unit = catalogueCurveUnit(data.root);
+    return unit ? [{ key: "unit", label: "Unit", value: unit }] : [];
+  }
+  return futuresSpecLines(spec).map((line) => {
+    const value = spec[line.key as keyof typeof spec];
+    return { key: line.key, label: line.label, value, ...line.value === String(value) ? {} : { formatted: line.value } };
+  });
+}
+
 export const futuresCurveHeadless: HeadlessPaneDefinition<"bundle"> = {
   discovery: { aliases: ["CTM"], dataRequirements: ["Gloom Cloud futures curve endpoint"],
     limitations: ["Listed-contract catalogues can be incomplete", "Ghosts and percentiles use the same listed contracts", "Cboe VIX is daily settlement"] },
@@ -35,6 +94,8 @@ export const futuresCurveHeadless: HeadlessPaneDefinition<"bundle"> = {
       spotSymbol ? loadCurveSpot(spotSymbol, ctx.marketData, now) : null,
     ]);
     const bases = spot ? data.contracts.map((row) => contractBasis(row, spot)) : [];
+    const unit = curveUnitLabel(data);
+    const terms = specEntries(data);
     const notices = [...args.argument ? [] : [`Showing ${DEFAULT_ROOT}. Try fn CTM ${EXAMPLE_ROOT}.`],
       ...spot ? [spot.status === "ok" ? `Basis against ${curveSpotLabel(spot, root, now)}.` : `Basis blank: ${spot.reason}.`] : []];
     // Dated by the contracts' own quotes; the same-contract history rows are a year of context, not observations.
@@ -46,17 +107,17 @@ export const futuresCurveHeadless: HeadlessPaneDefinition<"bundle"> = {
     return {
       freshness,
       sections: [
-        { title: "Contracts", rows: data.contracts.map((row, index) => {
-          const basis = bases[index];
-          return { ...row, percentile: rank(row.percentile),
-            ...(basis ? { vsSpotPct: basisValue(basis.vsSpotPct), annualisedBasisPct: basisValue(basis.annualisedBasisPct) } : {}) };
-        }) },
-        { title: "Front spread", rows: [{ ...data.slope, annualizedRollYield: data.slope.annualizedRollYield == null ? null : Number(data.slope.annualizedRollYield.toFixed(2)),
+        { title: "Contracts", columns: contractColumns(root, data.settlementDate ?? null,
+          { basis: !!spot, last: data.source !== "cboe", notice: data.contracts.some((row) => row.firstNotice) }),
+          rows: data.contracts.map((row, index) => contractRow(row, data, root, !!date, bases[index])) },
+        { title: "Front spread", rows: [{ label: curveSpreadLabel(data.slope), ...data.slope, value: curveRoundedPrice(data.slope.value, root),
+          annualizedRollYield: data.slope.annualizedRollYield == null ? null : Number(data.slope.annualizedRollYield.toFixed(2)),
           percentile: rank(data.slope.percentile), rollPercentile: rank(data.slope.rollPercentile) }] },
+        ...terms.length ? [{ title: "Contract terms", entries: terms }] : [],
         ...data.ghosts.map((ghost) => ({ title: `${ghost.label} same-contract history`, rows: ghost.points.map((point) => ({ ...point })) })),
       ],
       errors: data.gaps,
-      metadata: { ...data, ...(spot ? { spot, basisBlankedThin: thinContractCount(bases) } : {}), ...(args.argument ? {} : { defaultArgument: DEFAULT_ROOT }),
+      metadata: { ...data, quoteUnit: unit, ...(spot ? { spot, basisBlankedThin: thinContractCount(bases) } : {}), ...(args.argument ? {} : { defaultArgument: DEFAULT_ROOT }),
         ...(notices.length ? { notices } : {}),
         complete: data.status === "available", percentileBasis: "Same-contract observations within one year; actual sample start/end retained" },
     };

package/src/plugins/builtin/futures-curve/index.tsx

@@ -18,7 +18,7 @@ export const futuresCurveModule: PluginModule = {
   }],
   paneTemplates: [{ id: "futures-curve-pane", paneId: "futures-curve", label: "Futures Curve",
     description: "Listed futures contracts, historical curves, roll yield and open interest including VIX and CME crypto futures.",
-    keywords: ["ctm", "futures", "curve", "contango", "backwardation", "roll", "vix"],
+    keywords: ["ctm", "futures", "curve", "contango", "backwardation", "roll", "vix", "crude oil", "natural gas"],
     shortcut: { prefix: "CTM", aliases: ["CT"], argKind: "text", argPlaceholder: "root", argOptional: true,
       argOptions: () => CURVE_ROOTS },
     headless: futuresCurveHeadless,

package/src/plugins/builtin/futures-curve/model.ts

@@ -3,7 +3,7 @@ import type { CurvePalette, CurveSeries } from "../../../components/chart/curve/
 import { spanDigits } from "../../../components/chart-table";
 import { compositeAxisTicks } from "../../../components/chart/composite/format";
 import type { CompositeAxisDomain } from "../../../components/chart/composite/types";
-import { FUTURES_CONTRACTS, tickDecimals } from "../futures/contracts";
+import { FUTURES_CONTRACTS, futuresBoardContractForTicker, futuresContractByCode, tickDecimals } from "../../../market-data/futures-board";
 import { formatPercentileRank } from "../../../utils/format";
 import { cryptoPairCoin, isFuturesSymbol } from "../shared/crypto-pair";
 import { parseReportTime } from "../../../utils/utc-time";
@@ -21,7 +21,7 @@ const CRYPTO_CURVE_ROOTS: readonly { code: string; name: string; tick: number }[
 const rootLabel = (code: string, name: string) => name === code ? code : `${code} ${name}`;
 
 export const CURVE_ROOTS = [
-  ...FUTURES_CONTRACTS.filter((row) => row.curve !== false).map((row) => ({ value: row.code, label: rootLabel(row.code, row.name) })),
+  ...FUTURES_CONTRACTS.map((row) => ({ value: row.code, label: rootLabel(row.code, row.name) })),
   { value: "VX", label: "VX VIX Futures" },
   ...CRYPTO_CURVE_ROOTS.map((row) => ({ value: row.code, label: rootLabel(row.code, row.name) })),
 ];
@@ -34,24 +34,40 @@ export function normalizeCurveRoot(value: unknown): string | null {
   return CURVE_ROOTS.some((row) => row.value === root) ? root : null;
 }
 
-/** What a root nothing lists is told, with roots that work. */
+/** What a root CTM does not list is told: the roots that work, with the FUT board's, VIX and CME crypto named by group. */
 export function unsupportedCurveRootMessage(value: unknown): string {
+  const typed = String(value).trim().toUpperCase().replace(/=F$/, "");
   const examples = ["ES", "CL", "GC", "ZN"].filter((root) => CURVE_ROOTS.some((row) => row.value === root));
-  return `Unsupported futures root: ${String(value)}. Try ${examples.join(", ")}.`;
+  return `No futures curve for ${typed || "that root"}: CTM covers the FUT board's roots, VIX and CME crypto, such as ${examples.join(", ")}.`;
 }
 
+/**
+ * Board roots whose bare code opens their curve from the ticker under the
+ * cursor. Several are also listed securities (ES Eversource, NG NovaGold, PL
+ * Planet Labs), but they followed the cursor before the board was checked
+ * against listed securities and keep doing so. A root added after that (ZM is
+ * Zoom, KE, LE, HE and ALI are tickers too) follows the cursor only as its
+ * `=F` symbol or a code no security answers to (`bareCode`: ZL, OJ, LBR), the
+ * rule FUT and COT apply, so a new board row defaults to the security.
+ */
+const CURSOR_BARE_ROOTS: ReadonlySet<string> = new Set(["ES", "CL", "BZ", "NG", "RB", "HO", "GC", "SI", "HG", "PL", "PA", "ZC", "ZS", "KC", "SB", "CC"]);
+
 /**
  * The root for the ticker under the cursor, when CTM is opened without an
  * argument. The crypto roots are also US ticker symbols (Grayscale's mini
  * trusts are BTC and ETH), so a bare one is the equity's, never the future's:
  * only a futures symbol (BTC=F) or a coin pair (BTC-USD) names the crypto curve.
+ * A typed argument is different: `CTM ZM` is soybean meal even though ZM is also Zoom.
  */
 export function curveRootForTicker(ticker: unknown): string | null {
   if (typeof ticker !== "string") return null;
   const coin = cryptoPairCoin(ticker);
   if (coin) return CRYPTO_CURVE_ROOTS.some((row) => row.code === coin) ? coin : null;
   const root = normalizeCurveRoot(ticker);
-  return root && CRYPTO_CURVE_ROOTS.some((row) => row.code === root) && !isFuturesSymbol(ticker) ? null : root;
+  if (!root) return null;
+  if (CRYPTO_CURVE_ROOTS.some((row) => row.code === root)) return isFuturesSymbol(ticker) ? root : null;
+  const isBoardRoot = futuresContractByCode(root) != null;
+  return isBoardRoot && !CURSOR_BARE_ROOTS.has(root) ? futuresBoardContractForTicker(ticker)?.code ?? null : root;
 }
 
 /**
@@ -67,7 +83,7 @@ function curvePriceDecimals(root: string): number {
   const rateTick = RATE_TICKS[root];
   if (rateTick != null) return tickDecimals(rateTick);
   if (root === "VX") return 4;
-  const tick = FUTURES_CONTRACTS.find((row) => row.code === root)?.tick ?? CRYPTO_CURVE_ROOTS.find((row) => row.code === root)?.tick;
+  const tick = futuresContractByCode(root)?.tick ?? CRYPTO_CURVE_ROOTS.find((row) => row.code === root)?.tick;
   return tick == null ? 5 : Math.max(2, tickDecimals(tick));
 }
 
@@ -84,6 +100,39 @@ export function curveChangeText(value: number | null, root: string): string {
   return value != null && value > 0 && /[1-9]/.test(text) ? `+${text}` : text;
 }
 
+/** A price as a number at the root's display precision, for reports: 59.299805 reads 59.3, never float noise. */
+export function curveRoundedPrice(value: number | null | undefined, root: string): number | null {
+  return value == null || !Number.isFinite(value) ? null : Number(value.toFixed(curvePriceDecimals(root)));
+}
+
+/** The unit the catalogue gives a root whose contract terms the server does not send: "EUR / MWh" for Dutch TTF gas. */
+export function catalogueCurveUnit(root: string): string | null {
+  return futuresContractByCode(root)?.unit ?? null;
+}
+
+/**
+ * What a price counts: the exchange's unit ("USD / troy oz") where the root's
+ * terms are known, the catalogue's where they are not, else the quote unit.
+ */
+export function curveUnitLabel(data: Pick<FuturesCurvePayload, "root" | "spec" | "quoteUnit" | "currency">): string | null {
+  return data.spec?.unit ?? catalogueCurveUnit(data.root) ?? data.quoteUnit ?? data.currency ?? null;
+}
+
+/** A contract as traders write it: GCZ26.CMX is GCZ26; a VX symbol stays as Cboe lists it. */
+export function curveContractCode(symbol: string): string {
+  return symbol.replace(/\.[A-Z]+$/, "");
+}
+
+/**
+ * The front spread named by the contracts it subtracts, "GCF27-GCZ26": the
+ * next contract less the front one. The front is the first contract the
+ * market trades, which can be past a delivery month nobody holds, so a bare
+ * "M2-M1" would not say which rows it means.
+ */
+export function curveSpreadLabel(slope: Pick<FuturesCurvePayload["slope"], "frontSymbol" | "nextSymbol">): string {
+  return slope.frontSymbol && slope.nextSymbol ? `${curveContractCode(slope.nextSymbol)}-${curveContractCode(slope.frontSymbol)}` : "M2-M1";
+}
+
 /**
  * Axis gridlines sit on round values, so they need no tick precision: one
  * decimal count across the gutter, as many as the plotted range asks for and
@@ -188,13 +237,14 @@ export function curveContractChanges(data: FuturesCurvePayload): CurveContractCh
 
 const CHANGE_COLUMNS: Readonly<Record<string, CurveLookback>> = { change1w: "1W", change1m: "1M" };
 
-type CurveSortKey = "symbol" | "expiration" | "price" | "change" | "openInterest" | "volume" | "percentile" | "asOf";
+type CurveSortKey = "symbol" | "expiration" | "price" | "settlement" | "firstNotice" | "change" | "openInterest" | "volume" | "percentile" | "asOf";
 
 const BASIS_COLUMNS: Readonly<Record<string, "vsSpotPct" | "annualisedBasisPct">> = { vsSpot: "vsSpotPct", annBasis: "annualisedBasisPct" };
 
 export function sortCurveContracts(rows: readonly FuturesContract[], id: string, direction: SortDirection,
   changes?: CurveContractChanges, basis?: CurveBasisRows): FuturesContract[] {
-  const keys: Record<string, CurveSortKey> = { symbol: "symbol", expiry: "expiration", price: "price", change: "change", oi: "openInterest", volume: "volume", percentile: "percentile", asOf: "asOf" };
+  const keys: Record<string, CurveSortKey> = { symbol: "symbol", expiry: "expiration", price: "price", settle: "settlement", notice: "firstNotice",
+    change: "change", oi: "openInterest", volume: "volume", percentile: "percentile", asOf: "asOf" };
   const key = keys[id] ?? "expiration";
   const lookback = CHANGE_COLUMNS[id];
   const basisKey = BASIS_COLUMNS[id];
@@ -399,6 +449,9 @@ export function archivedFuturesCurve(root: string, curve: FuturesCurveAsOfPayloa
       symbol: row.symbol, label: row.label, expiration: row.expiration, price: row.price, change: null, asOf: rowDate(row, stale),
       currency: curve.currency ?? "USD", quoteUnit: curve.quoteUnit ?? curve.currency ?? "USD", volume: row.volume,
       openInterest: row.openInterest, delayMinutes: null, stale, percentile: null, samples: 0, historyStart: null, historyEnd: null,
+      // Only a row the archive confirms is a settlement; an unconfirmed one is that session's last trade.
+      settlement: !stale && row.settled === true ? row.price : null,
+      lastTrade: row.lastTrade ?? row.expiration, firstNotice: row.firstNotice ?? null, inDelivery: row.inDelivery ?? false,
     }];
   }).sort((a, b) => a.expiration.localeCompare(b.expiration));
   const ghosts = (["1W", "1M"] as const).map((label) => {
@@ -407,8 +460,10 @@ export function archivedFuturesCurve(root: string, curve: FuturesCurveAsOfPayloa
       points: past ? past.contracts.flatMap((row) => row.expiration
         ? [{ symbol: row.symbol, expiration: row.expiration, price: row.price, asOf: rowDate(row, archivedRowStale(row, past)) }] : []) : [] };
   });
-  // The front pair on the curve's own session; carried prices do not make a spread.
-  const [front, next] = contracts.filter((row) => !row.stale);
+  // The front pair on the curve's own session: settlements where the archive has them, else that session's
+  // last trades. Carried prices, and a last trade beside a settlement, do not make a spread.
+  const settled = contracts.filter((row) => row.settlement != null);
+  const [front, next] = settled.length >= 2 ? settled : settled.length ? [] : contracts.filter((row) => !row.stale);
   const value = front && next ? next.price! - front.price! : null;
   const days = front && next ? (Date.parse(next.expiration) - Date.parse(front.expiration)) / DAY_MS : 0;
   const roll = front && next && front.price! > 0 && next.price! > 0 && days > 0 ? (front.price! / next.price! - 1) * 365 / days * 100 : null;
@@ -419,6 +474,6 @@ export function archivedFuturesCurve(root: string, curve: FuturesCurveAsOfPayloa
     slope: { frontSymbol: front?.symbol ?? null, nextSymbol: next?.symbol ?? null, value, annualizedRollYield: roll, percentile: null,
       rollPercentile: null, samples: 0, historyStart: null, historyEnd: null, asOf: front && next ? curve.asOf : null,
       state: value == null ? "unavailable" : Math.abs(value) < 1e-10 ? "flat" : value > 0 ? "contango" : "backwardation" },
-    gaps: curve.gaps,
+    gaps: curve.gaps, spec: curve.spec ?? null, settlementDate: settled.length ? curve.asOf : null,
   };
 }

package/src/plugins/builtin/futures-curve/pane.tsx

@@ -4,6 +4,7 @@ import { fitChartTableColumns } from "../../../components/chart-table";
 import { curveStrip, curveSurfaceMinRows } from "../../../components/chart/curve";
 import { isAccessDenied } from "../../../api-client/errors";
 import type { FuturesContract } from "../../../api-client/futures-curve";
+import { futuresTickText } from "../../../market-data/futures-contract";
 import { useAsyncResource, usePaneSettingValue, usePluginPaneState, useShortcut } from "../../../public/react";
 import { usePaneInstance, usePaneTitle } from "../../../state/app/context";
 import { useThemeColors } from "../../../theme/theme-context";
@@ -16,14 +17,19 @@ import { futuresSessionRefreshInterval } from "../shared/futures-session";
 import { useResearchCloudSession } from "../shared/research-cloud-session";
 import { useQuoteBoard } from "../shared/use-quote-board";
 import { getCachedFuturesCurve, loadFuturesCurve, loadFuturesCurveAsOf } from "./client";
-import { basisSpotSymbol, curveAsOfDate, curveAxisPrice, curveBasisPercent, curveBasisRows, curveChangeText, curveContractChanges, curvePrice, curveRank, curveSpot, curveSpotLabel, curveTimestamp, DEFAULT_CURVE_HORIZON, futuresCurveSeries, newestQuote, normalizeCurveRoot, sortCurveContracts, thinContractCount, thinContractsNotice, unsupportedCurveRootMessage, type CurveContractChanges } from "./model";
+import { basisSpotSymbol, curveAsOfDate, curveAxisPrice, curveBasisPercent, curveBasisRows, curveChangeText, curveContractChanges, curveContractCode, curvePrice, curveRank, curveSpot, curveSpotLabel, curveSpreadLabel, curveTimestamp, curveUnitLabel, DEFAULT_CURVE_HORIZON, futuresCurveSeries, newestQuote, normalizeCurveRoot, sortCurveContracts, thinContractCount, thinContractsNotice, unsupportedCurveRootMessage, type CurveContractChanges } from "./model";
 
 const TABS = [{ value: "curve", label: "Curve" }, { value: "contracts", label: "Contracts" }];
+// One column order for every root. SETTLE is the exchange settlement for the
+// curve's settlement session, LAST the latest trade; the header dates SETTLE.
 const COLUMNS: DataTableColumn[] = [
   // The longest symbol is a three-letter root with its month and venue: RTYH27.CME.
   { id: "symbol", label: "CONTRACT", width: 11, align: "left" },
   { id: "expiry", label: "EXPIRY", width: 10, align: "left" },
-  { id: "price", label: "PRICE", width: 12, align: "right" },
+  { id: "notice", label: "1ST NOTICE", width: 10, align: "left" },
+  // A Treasury price keeps its 1/256 tick: 103.50000000.
+  { id: "settle", label: "SETTLE", width: 12, align: "right" },
+  { id: "price", label: "LAST", width: 12, align: "right" },
   // A Treasury change keeps its 1/256 tick: +0.11718750.
   { id: "change", label: "CHG", width: 11, align: "right" },
   { id: "percentile", label: "PCTL", width: 5, align: "right" },
@@ -31,25 +37,28 @@ const COLUMNS: DataTableColumn[] = [
   { id: "volume", label: "VOLUME", width: 10, align: "right" },
   { id: "asOf", label: "AS OF UTC", width: 16, align: "left" },
 ];
+const CONTRACTS_DROP_ORDER = ["percentile", "volume", "oi", "notice"];
+const column = (id: string) => COLUMNS.find((entry) => entry.id === id)!;
 // The curve's rows move with the look-back curves drawn above them; the
 // footer carries the quote time every row would otherwise repeat. The session
 // change stays on Contracts, where the full table has the width for it.
 const CURVE_COLUMNS: DataTableColumn[] = [
-  ...COLUMNS.slice(0, 3),
+  column("symbol"), column("expiry"), column("settle"), column("price"),
   { id: "change1w", label: "VS 1W", width: 10, align: "right" },
   { id: "change1m", label: "VS 1M", width: 10, align: "right" },
-  ...COLUMNS.slice(4, -1),
+  column("percentile"), column("oi"), column("volume"),
 ];
+const CURVE_DROP_ORDER = ["percentile", "volume", "change1m", "oi"];
 // A crypto curve also reads against spot. Its widths are the tightest each column
 // holds (BTCV26.CME, 128000.00), so the two new columns fit beside the rest, and
 // a narrow pane drops the least useful ones before a number would be clipped.
 const BASIS_CURVE_COLUMNS: DataTableColumn[] = [
-  { ...CURVE_COLUMNS[0]!, width: 10 }, CURVE_COLUMNS[1]!, { ...CURVE_COLUMNS[2]!, width: 10 },
+  { ...column("symbol"), width: 10 }, column("expiry"), { ...column("settle"), width: 10 }, { ...column("price"), width: 10 },
   { id: "vsSpot", label: "VS SPOT", width: 9, align: "right" },
   { id: "annBasis", label: "ANN BASIS", width: 11, align: "right" },
-  ...CURVE_COLUMNS.slice(3),
+  ...CURVE_COLUMNS.slice(4),
 ];
-const BASIS_DROP_ORDER = ["percentile", "volume", "change1m", "oi"];
+const BASIS_DROP_ORDER = ["percentile", "volume", "change1m", "oi", "settle"];
 const NO_SYMBOLS: string[] = [];
 /** The spot's age is judged against the clock, so a quote that stops moving still goes stale on screen. */
 const SPOT_CLOCK_MS = 30_000;
@@ -135,17 +144,31 @@ function FuturesCurveView({ width, height, focused, root }: PaneProps & { root:
   const statItems: StatItem[] = data ? [
     { id: "roll", label: "Ann. roll yield", value: signedPercent(data.slope.annualizedRollYield),
       detail: curveRank(data.slope.rollPercentile, data.slope.samples) },
-    { id: "spread", label: "M2-M1", value: data.slope.value == null ? "--" : curvePrice(data.slope.value, root),
+    // Named by the contracts it subtracts: the front is the first month the market trades, not always the first row.
+    { id: "spread", label: curveSpreadLabel(data.slope), value: data.slope.value == null ? "--" : curvePrice(data.slope.value, root),
       detail: [data.slope.state, curveRank(data.slope.percentile, data.slope.samples), slopeDate].filter(Boolean).join(" · ") },
+    ...data.spec ? [{ id: "contract", label: "Contract", value: data.spec.size, detail: `tick ${futuresTickText(data.spec)}` }] : [],
   ] : [];
   const { strip: tabStrip, rows: tabRows } = usePaneTabs({ tabs: TABS, activeValue: tab, onSelect: setTab, focused, dense: true });
   // The query bar takes one row below the tabs, and a refused date one more.
   const bodyHeight = Math.max(1, height - tabRows - 1 - (dateError ? 1 : 0));
-  const columns = useMemo(() => !curveTab ? COLUMNS : basisActive ? fitChartTableColumns(BASIS_CURVE_COLUMNS, width, BASIS_DROP_ORDER) : CURVE_COLUMNS,
-    [basisActive, curveTab, width]);
+  // A Cboe price is the settlement itself, so its curve has no separate last trade.
+  const settlesOnly = data?.source === "cboe";
+  const settleLabel = data?.settlementDate ? `SETTLE ${data.settlementDate.slice(5)}` : "SETTLE";
+  // Cash-settled roots (ES, CL's Brent, VX) have no first notice day to show.
+  const noNotice = !data?.contracts.some((row) => row.firstNotice);
+  const columns = useMemo(() => {
+    // Labelled before fitting: a dated header is wider than the column's numbers.
+    const shown = (list: DataTableColumn[]) => list.filter((entry) => !(settlesOnly && entry.id === "price") && !(noNotice && entry.id === "notice"))
+      .map((entry) => entry.id === "settle" ? { ...entry, label: settleLabel } : entry);
+    return !curveTab ? fitChartTableColumns(shown(COLUMNS), width, CONTRACTS_DROP_ORDER)
+      : basisActive ? fitChartTableColumns(shown(BASIS_CURVE_COLUMNS), width, BASIS_DROP_ORDER)
+        : fitChartTableColumns(shown(CURVE_COLUMNS), width, CURVE_DROP_ORDER);
+  }, [basisActive, curveTab, noNotice, settleLabel, settlesOnly, width]);
   const formatValue = useCallback((value: number) => curvePrice(value, root), [root]);
   const formatChange = useCallback((value: number) => curveChangeText(value, root), [root]);
-  const caption = `${sentenceCase(data?.quoteUnit ?? data?.currency ?? "price")} by contract month`;
+  const unit = data ? curveUnitLabel(data) : null;
+  const caption = `${sentenceCase(unit ?? "price")} by contract month`;
   // The strip keeps the curve's shape and the selected contract in one row.
   const strip = curveTab ? curveStrip(curves, formatValue, { caption: "Price", selectedPointId: selectedId }) : null;
   // Delayed contract quotes move all session; the curve follows them once a
@@ -177,8 +200,11 @@ function FuturesCurveView({ width, height, focused, root }: PaneProps & { root:
   // A past date with no archived curve says why in the body, not behind the warning.
   const emptyPast = !!requestedDate && !!data && !data.contracts.length;
   // Thin contracts join the data warnings: the info row has no room for them beside the quote times.
+  // A long in these can be assigned delivery: the hedge a trader rolls before first notice.
+  const delivering = data?.contracts.filter((row) => row.inDelivery).map((row) => curveContractCode(row.symbol)) ?? [];
   usePaneNoticeFooter({ registrationId: "futures-curve:notices", focused,
-    notices: emptyPast ? [] : [...data?.gaps ?? [], ...thinCount ? [thinContractsNotice(thinCount)] : []] });
+    notices: emptyPast ? [] : [...data?.gaps ?? [], ...thinCount ? [thinContractsNotice(thinCount)] : [],
+      ...delivering.length ? [`${delivering.join(", ")} ${delivering.length === 1 ? "is" : "are"} past first notice.`] : []] });
   const delay = Math.max(0, ...(data?.contracts.map((row) => row.delayMinutes ?? 0) ?? []));
   usePaneStatusFooter({ registrationId: "futures-curve", loading: resource.loading, error: resource.error,
     hints: [
@@ -186,7 +212,7 @@ function FuturesCurveView({ width, height, focused, root }: PaneProps & { root:
       ...requestedDate ? [{ id: "latest", key: "c", label: "urrent", title: "Current Curve", onPress: () => selectDate("") }] : [],
     ],
     info: data ? [
-      { id: "source", parts: [{ text: `${requestedDate ? "daily archive" : data.source === "cboe" ? "settlement" : delay > 0 ? `${delay}m delayed` : "dated quotes"} · ${data.quoteUnit ?? data.currency ?? "units unavailable"} · ${curveTimestamp(newest)}${newest?.includes("T") ? " UTC" : ""}`, tone: "muted" }] },
+      { id: "source", parts: [{ text: `${requestedDate ? "daily archive" : data.source === "cboe" ? "settlement" : delay > 0 ? `${delay}m delayed` : "dated quotes"} · ${unit ?? "units unavailable"} · ${curveTimestamp(newest)}${newest?.includes("T") ? " UTC" : ""}`, tone: "muted" }] },
       ...(staleCount ? [{ id: "stale", parts: [{ text: `${staleCount} of ${data.contracts.length} stale`, tone: "warning" as const }] }] : []),
       ...(spot ? [{ id: "spot", parts: [spot.status === "ok" ? { text: curveSpotLabel(spot, root, clock), tone: "muted" as const }
         : { text: `Basis blank: ${spot.reason}`, tone: "warning" as const }] }] : []),
@@ -202,10 +228,18 @@ function FuturesCurveView({ width, height, focused, root }: PaneProps & { root:
     strip,
   } : null;
   const renderCell = useCallback((row: FuturesContract, column: DataTableColumn) => {
-    if (column.id === "symbol") return { text: row.symbol };
-    if (column.id === "expiry") return { text: row.expiration, color: colors.textMuted };
-    // Without the AS OF column, a stale quote shows on its price, and so does a print too old for the spot.
-    if (column.id === "price") return { text: curvePrice(row.price, root), color: curveTab && (row.stale || basis.get(row.symbol)?.thin) ? colors.warning : undefined };
+    // A contract past first notice can be assigned delivery.
+    if (column.id === "symbol") return { text: row.symbol, color: row.inDelivery ? colors.warning : undefined };
+    if (column.id === "expiry") return { text: row.lastTrade ?? row.expiration, color: colors.textMuted };
+    if (column.id === "notice") return { text: row.firstNotice ?? "--", color: row.inDelivery ? colors.warning : colors.textMuted };
+    if (column.id === "settle") return { text: curvePrice(row.settlement ?? null, root) };
+    // A past curve's settled row has no separate last trade: its price is the settlement.
+    if (column.id === "price") {
+      const lastTrade = requestedDate && row.settlement != null ? null : row.price;
+      // Beside its settlement the last trade is the secondary price; without one it is the row's price.
+      return { text: curvePrice(lastTrade, root), color: curveTab && (row.stale || basis.get(row.symbol)?.thin) ? colors.warning
+        : row.settlement != null ? colors.textMuted : undefined };
+    }
     if (column.id === "change") {
       const text = curveChangeText(row.change ?? null, root);
       return { text, color: text.startsWith("+") ? colors.positive : text.startsWith("-") && /[1-9]/.test(text) ? colors.negative : colors.textMuted };
@@ -222,7 +256,7 @@ function FuturesCurveView({ width, height, focused, root }: PaneProps & { root:
     if (column.id === "oi") return { text: integer(row.openInterest) };
     if (column.id === "volume") return { text: integer(row.volume) };
     return { text: curveTimestamp(row.asOf), color: row.stale ? colors.warning : colors.textMuted };
-  }, [basis, changes, colors, curveTab, root]);
+  }, [basis, changes, colors, curveTab, requestedDate, root]);
   return <Box width={width} height={height} flexDirection="column">
     {tabStrip}
     <QueryBar width={width} filters={[{

package/src/plugins/builtin/fx-matrix/index.tsx

@@ -12,6 +12,7 @@ import { CountryFlag } from "../../../components/ui/country-flag";
 import { getSharedMarketDataCoordinator } from "../../../market-data/coordinator";
 import { useFxRatesMap } from "../../../market-data/hooks";
 import { resolveEntryData } from "../../../market-data/selectors";
+import { useRemoteUiNode } from "../../../remote/semantic-tree";
 import { usePaneSettingValue } from "../../../state/app/context";
 import { colors } from "../../../theme/colors";
 import type { PaneProps } from "../../../types/plugin";
@@ -19,13 +20,14 @@ import { TextAttributes, useUiCapabilities } from "../../../ui";
 import { useAssetData } from "../../runtime";
 import { summarizeFxRates, fxStatusLabel } from "../../../utils/fx-status";
 import type { PluginModule } from "../plugin-module";
+import { fxRateObservations } from "../shared/fx-rate-freshness";
 import { useLiveQuoteEntries } from "../../../state/hooks/quote-streaming";
 import { useAutoRefresh, useUpdatedAgo } from "../../../react/auto-refresh";
 import { useLiveStreamingSetting } from "../../../state/hooks/live-streaming";
 import { fxLegQuoteKey, fxLegReferenceRate, fxLegTargets, fxLegs, fxLegsBehind, liveFxLegEntry } from "./live-legs";
 import { CURRENCY_FLAG_REGIONS, FX_CURRENCIES, formatRate, resolveCurrencies, type FxCurrency } from "./pairs";
 import { crossMovePercent, directionTint, nextTintLevel } from "./direction";
-import { fxMatrixSettings } from "./settings";
+import { FX_MATRIX_REPORT_OPTIONS, fxMatrixReportNotices, fxMatrixSettings } from "./settings";
 import { createFxExportMetadata } from "./export";
 
 const FX_MATRIX_PANE_ID = "fx-matrix";
@@ -114,6 +116,23 @@ function FxMatrixPane({ focused, width, height }: PaneProps) {
       ? { ...entry, error: entry.error ? { ...entry.error } : null }
       : undefined] as const;
   }));
+  // A report or capture of the board is dated by the rates it draws: when each
+  // was observed, whether it is delayed or stale, and where the FX market
+  // stands. The pane draws none of this; its footer keeps its own status.
+  useRemoteUiNode({
+    role: "report-freshness",
+    label: "Rate freshness",
+    getMetadata: () => {
+      const legQuotes = new Map(legs.map((leg) => [leg.currency, resolveEntryData(legEntries.get(fxLegQuoteKey(leg)))] as const));
+      return {
+        observations: fxRateObservations(currencies, rates, (currency) => ({
+          entry: rateEntries.get(currency),
+          // Only a rate that is the pair quote's own says what that quote says.
+          legQuote: liveEntries.has(currency) ? legQuotes.get(currency) : null,
+        })),
+      };
+    },
+  });
   const status = summarizeFxRates(currencies, rates, (currency) => rateEntries.get(currency));
   const statusText = fxStatusLabel(status);
   const snapshotFetchedAt = summarizeFxRates(currencies, snapshotRates, (currency) => (
@@ -253,6 +272,8 @@ export const fxMatrixModule: PluginModule = {
       defaultFloatingSize: { width: 105, height: 14 },
       tableExport: true,
       settings: fxMatrixSettings,
+      reportOptions: FX_MATRIX_REPORT_OPTIONS,
+      reportNotices: fxMatrixReportNotices,
     },
   ],
 

package/src/plugins/builtin/fx-matrix/pairs.ts

@@ -60,7 +60,7 @@ export function formatRate(rate: number, referenceRate = rate): string {
   return rate.toFixed(decimals);
 }
 
-function isFxCurrency(code: unknown): code is FxCurrency {
+export function isFxCurrency(code: unknown): code is FxCurrency {
   return typeof code === "string" && FX_CURRENCIES.includes(code as FxCurrency);
 }
 

package/src/plugins/builtin/fx-matrix/settings.ts

@@ -1,5 +1,5 @@
-import type { PaneSettingsContext, PaneSettingsDef } from "../../../types/plugin";
-import { CURRENCY_SETS, FX_CURRENCIES, resolveCurrencies } from "./pairs";
+import type { PaneReportOptionDef, PaneSettingsContext, PaneSettingsDef } from "../../../types/plugin";
+import { CURRENCY_SETS, FX_CURRENCIES, MAJOR_CURRENCIES, isFxCurrency, resolveCurrencies } from "./pairs";
 
 const CUSTOM_SET = "custom";
 
@@ -60,3 +60,43 @@ export function fxMatrixSettings(context: PaneSettingsContext): PaneSettingsDef
     },
   };
 }
+
+const SET_NAMES = CURRENCY_SETS.map((set) => set.id).join(", ");
+
+/**
+ * `--currencies` as typed: codes and set names in any case, separated by
+ * commas or spaces, returned as the codes in order without repeats. A token
+ * that is neither fails, naming it and the codes the board carries, where the
+ * pane setting would drop it and quietly show the majors.
+ */
+function parseCurrenciesOption(value: string): string {
+  const tokens = value.split(/[\s,]+/).filter(Boolean);
+  const unknown = tokens.filter((token) => (
+    !isFxCurrency(token.toUpperCase()) && !CURRENCY_SETS.some((set) => set.id === token.toLowerCase())
+  ));
+  if (unknown.length > 0) {
+    throw new Error(
+      `Unknown ${unknown.length > 1 ? "currencies" : "currency"} ${unknown.join(", ")} for --currencies. `
+      + `Use codes from ${FX_CURRENCIES.join(", ")}, or a set: ${SET_NAMES}.`,
+    );
+  }
+  if (tokens.length === 0) throw new Error("--currencies needs at least one code, such as USD,ZAR,NGN.");
+  return resolveCurrencies(value).join(",");
+}
+
+/** `fn FXC --currencies USD,ZAR,NGN`: the board's currency list, as its settings choose it. */
+export const FX_MATRIX_REPORT_OPTIONS: readonly PaneReportOptionDef[] = [{
+  key: "currencies",
+  type: "string",
+  placeholder: "codes",
+  description: `The currencies to cross, in order: codes separated by commas, or a set (${SET_NAMES}). `
+    + `Without it, the ${MAJOR_CURRENCIES.length} majors. Codes: ${FX_CURRENCIES.join(", ")}`,
+  example: "--currencies USD,ZAR,NGN,SAR,ILS",
+  normalize: parseCurrenciesOption,
+}];
+
+/** A report of the default board says it is only the majors, and how to choose others. */
+export function fxMatrixReportNotices(settings: Readonly<Record<string, unknown>>): string[] {
+  if (settings.currencies != null) return [];
+  return [`Showing the ${MAJOR_CURRENCIES.length} majors. Choose others with --currencies USD,ZAR,NGN; gloomberb catalog FXC lists all ${FX_CURRENCIES.length}.`];
+}