gloomberb 0.16.1 → 0.16.2

package/src/plugins/builtin/equity-screener/headless.ts

@@ -14,6 +14,7 @@ import {
 
 export const equityScreenerHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle",
+  freshness: { status: "not-a-feed", basis: "screener snapshot" },
   argument: { kind: "none" },
   options: [
     {
@@ -49,6 +50,7 @@ export const equityScreenerHeadless: HeadlessPaneDefinition<"bundle"> = {
     // Payload status also counts ordinary per-field sparsity; only generation
     // warnings are failures, and more pages are not an error.
     return {
+      freshness: { asOf: data.snapshot?.sourceNewestAt ?? null },
       complete: !data.nextCursor && data.warnings.length === 0,
       errors: data.warnings,
       sections: [

package/src/plugins/builtin/estimate-revisions/headless.ts

@@ -3,6 +3,7 @@ import { fetchEstimates } from "./client";
 import { estimateCurrent, periodLabel, pinnedEstimatePeriods } from "./model";
 export const estimateRevisionsHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle",
+  freshness: { status: "not-a-feed", basis: "analyst estimates" },
   argument: {
     kind: "ticker",
     placeholder: "ticker",

package/src/plugins/builtin/executives/index.tsx

@@ -30,6 +30,7 @@ export const executivesModule: PluginModule = {
   panes: [
     {
       id: EXECUTIVES_PANE_ID,
+      reportFreshness: { source: "SEC EDGAR", status: "not-a-feed", basis: "proxy statements" },
       name: "Executives",
       icon: "X",
       component: ExecutivesPane,

package/src/plugins/builtin/exposure/headless.ts

@@ -5,7 +5,9 @@ import { DEFAULT_SCENARIO, parseCustomScenario, parseHoldings, TABS } from "./mo
 import { portfolioHoldings, watchlistHoldings } from "./holdings";
 
 export const exposureHeadless: HeadlessPaneDefinition<"bundle"> = {
-  shape: "bundle", argument: { kind: "free-text", optional: true, placeholder: "AAPL=60% NVDA=40%", description: "Tickers, signed NAV weights, PORT:<id>, or WATCH:<id>. Unweighted lists and watchlists use equal weights." },
+  shape: "bundle",
+  freshness: { status: "not-a-feed", basis: "company disclosures" },
+  argument: { kind: "free-text", optional: true, placeholder: "AAPL=60% NVDA=40%", description: "Tickers, signed NAV weights, PORT:<id>, or WATCH:<id>. Unweighted lists and watchlists use equal weights." },
   discovery: { aliases: ["EXPO"], dataRequirements: ["Gloom Cloud geographic revenue, disclosed supply chains, KPIs, guidance and credit disclosures", "Portfolio NAV for local PORT weights"],
     limitations: ["Pro: full holdings and up to four-hop paths; free: one holding, one hop", "Operating exposure estimates, never predicted stock returns", "Missing relationships and sensitivities remain unknown", "Basis and reporting period are kept separate"] },
   options: [

package/src/plugins/builtin/fear-greed/headless.ts

@@ -76,6 +76,8 @@ export function createFearGreedHeadless(
       return {
         ...projected,
         ...(result.refreshError ? { errors: [result.refreshError] } : {}),
+        // A cached index the refresh could not replace is stale; otherwise CNN's published reading.
+        freshness: { source: "CNN", status: result.stale ? "stale" : "not-a-feed", basis: "published index" },
         metadata: { fetchedAt: result.fetchedAt, stale: result.stale },
       };
     },

package/src/plugins/builtin/filing-events/index.tsx

@@ -21,6 +21,7 @@ export const filingEventsModule: PluginModule = {
   panes: [
     {
       id: FILING_EVENTS_PANE_ID,
+      reportFreshness: { source: "SEC EDGAR", status: "not-a-feed", basis: "filed data" },
       name: "8-K Filings",
       icon: "K",
       component: FilingEventsPane,

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

@@ -2,7 +2,8 @@ import { apiClient } from "../../../api-client";
 import type { FuturesCurvePayload } from "../../../api-client/futures-curve";
 import { createPluginCache } from "../../../data/plugin-cache";
 import { loadCloudResource, unavailableOnServer } from "../shared/cloud-resource";
-import { archivedFuturesCurve, curveLookbackDate, normalizeCurveRoot } from "./model";
+import type { DataProvider } from "../../../types/data-provider";
+import { archivedFuturesCurve, curveLookbackDate, curveSpot, normalizeCurveRoot, unsupportedCurveRootMessage, type CurveSpot } from "./model";
 
 export const futuresCurveCache = createPluginCache<FuturesCurvePayload>({
   kind: "futures-curve", source: "gloom-cloud", schemaVersion: 1,
@@ -51,7 +52,7 @@ export function validateFuturesCurve(data: FuturesCurvePayload, root: string): F
 
 export async function fetchFuturesCurve(root: string, client: Pick<typeof apiClient, "getCloudFuturesCurve"> = apiClient): Promise<FuturesCurvePayload> {
   const normalized = normalizeCurveRoot(root);
-  if (!normalized) throw new Error(`Unsupported futures root: ${root}`);
+  if (!normalized) throw new Error(unsupportedCurveRootMessage(root));
   try { return validateFuturesCurve(await client.getCloudFuturesCurve(normalized), normalized); }
   catch (error) { throw unavailableOnServer(error, "Futures curves are not available yet."); }
 }
@@ -71,7 +72,7 @@ export async function loadFuturesCurve(root: string, force = false): Promise<Fut
 export async function loadFuturesCurveAsOf(root: string, date: string,
   client: Pick<typeof apiClient, "getCloudFuturesCurveAsOf"> = apiClient): Promise<FuturesCurvePayload> {
   const normalized = normalizeCurveRoot(root);
-  if (!normalized) throw new Error(`Unsupported futures root: ${root}`);
+  if (!normalized) throw new Error(unsupportedCurveRootMessage(root));
   try {
     const [curve, week, month] = await Promise.all([
       client.getCloudFuturesCurveAsOf(normalized, date),
@@ -85,3 +86,11 @@ export async function loadFuturesCurveAsOf(root: string, date: string,
     return archivedFuturesCurve(normalized, curve, { "1W": week, "1M": month }, new Date().toISOString());
   } catch (error) { throw unavailableOnServer(error, "Past futures curves are not available yet."); }
 }
+
+/**
+ * The spot behind a crypto curve's basis, read through the same quote path every pane uses.
+ * A failed read is a missing spot, never a failed report: the curve stands without its basis.
+ */
+export async function loadCurveSpot(symbol: string, provider: Pick<DataProvider, "getQuote">, now = Date.now()): Promise<CurveSpot> {
+  return curveSpot(symbol, await provider.getQuote(symbol, "").catch(() => null), now);
+}

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

@@ -1,35 +1,64 @@
-import type { HeadlessPaneDefinition } from "../../../types/plugin";
-import { fetchFuturesCurve, loadFuturesCurveAsOf } from "./client";
-import { curveAsOfDate, normalizeCurveRoot } from "./model";
+import type { HeadlessPaneDefinition, 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";
+
+/** The root a report shows when none is given. */
+const DEFAULT_ROOT = "ES";
+const EXAMPLE_ROOT = "CL";
 
 /** Percentiles read as the pane shows them, a whole rank. */
 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));
 
 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"] },
-  shape: "bundle", argument: { kind: "free-text", optional: true, placeholder: "root", description: "FUT root such as CL, ES, ZN or VX. Defaults to ES." },
+  shape: "bundle", argument: { kind: "free-text", optional: true, placeholder: "root", description: "FUT root such as CL, ES, ZN or VX, or a CME crypto root (BTC, ETH, SOL, XRP). Defaults to ES." },
   // Only the pane reads the tab; the report always carries both.
   options: [{ key: "tab", description: "Curve or the full contract table.", type: "enum",
     values: [{ value: "curve" }, { value: "contracts", aliases: ["contract", "table"] }], defaultValue: "curve",
     pluginState: { pluginId: "market-overview", key: "tab" } },
   { key: "date", type: "string", settingKey: "asOfDate", description: "Past date (YYYY-MM-DD): the curve as the daily settlement archive held it, with the curves a week and a month before." }],
-  describe: (args) => `Futures curve ${args.argument || "ES"}`,
+  describe: (args) => `Futures curve ${args.argument || DEFAULT_ROOT}`,
   async load(args, ctx) {
-    const input = args.argument || "ES";
+    const input = args.argument || DEFAULT_ROOT;
     const root = normalizeCurveRoot(input);
-    if (!root) throw new Error(`Unsupported futures root: ${input}`);
+    if (!root) throw new Error(unsupportedCurveRootMessage(input));
     const date = curveAsOfDate(args.options.date);
-    const data = date ? await loadFuturesCurveAsOf(root, date, ctx.apiClient) : await fetchFuturesCurve(root, ctx.apiClient);
+    // The archive keeps no spot history, so a past curve has no basis.
+    const spotSymbol = date ? null : basisSpotSymbol(root);
+    const now = Date.now();
+    const [data, spot] = await Promise.all([
+      date ? loadFuturesCurveAsOf(root, date, ctx.apiClient) : fetchFuturesCurve(root, ctx.apiClient),
+      spotSymbol ? loadCurveSpot(spotSymbol, ctx.marketData, now) : null,
+    ]);
+    const bases = spot ? data.contracts.map((row) => contractBasis(row, spot)) : [];
+    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.
+    const quoted = data.contracts.map((row) => row.asOf);
+    const freshness: HeadlessPaneFreshness = date
+      ? { status: "not-a-feed", basis: "settlement archive", asOf: date }
+      : { ...(data.source === "cboe" ? { source: "Cboe", status: "not-a-feed", basis: "daily settlement", cadence: "daily" } as const : {}),
+        asOf: newestReportTime(quoted), oldest: oldestReportTime(quoted) };
     return {
+      freshness,
       sections: [
-        { title: "Contracts", rows: data.contracts.map((row) => ({ ...row, percentile: rank(row.percentile) })) },
+        { 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)),
           percentile: rank(data.slope.percentile), rollPercentile: rank(data.slope.rollPercentile) }] },
         ...data.ghosts.map((ghost) => ({ title: `${ghost.label} same-contract history`, rows: ghost.points.map((point) => ({ ...point })) })),
       ],
       errors: data.gaps,
-      metadata: { ...data, complete: data.status === "available", percentileBasis: "Same-contract observations within one year; actual sample start/end retained" },
+      metadata: { ...data, ...(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

@@ -1,7 +1,7 @@
 import type { PluginModule } from "../plugin-module";
 import { futuresCurveCache } from "./client";
 import { futuresCurveHeadless } from "./headless";
-import { CURVE_HORIZONS, CURVE_ROOTS, DEFAULT_CURVE_HORIZON, normalizeCurveRoot } from "./model";
+import { CURVE_HORIZONS, CURVE_ROOTS, curveRootForTicker, DEFAULT_CURVE_HORIZON, normalizeCurveRoot } from "./model";
 import { FuturesCurvePane } from "./pane";
 
 export const futuresCurveModule: PluginModule = {
@@ -17,14 +17,14 @@ 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 futures.",
+    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"],
     shortcut: { prefix: "CTM", aliases: ["CT"], argKind: "text", argPlaceholder: "root", argOptional: true,
       argOptions: () => CURVE_ROOTS },
     headless: futuresCurveHeadless,
     createInstance: (context, options) => {
       const input = options?.arg?.trim();
-      const root = input ? normalizeCurveRoot(input) : normalizeCurveRoot(context.activeTicker) ?? "ES";
+      const root = input ? normalizeCurveRoot(input) : curveRootForTicker(context.activeTicker) ?? "ES";
       return { title: `CTM ${root ?? input}`, params: { root: root ?? input ?? "ES" }, placement: "floating" };
     },
   }],

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

@@ -5,13 +5,28 @@ import { compositeAxisTicks } from "../../../components/chart/composite/format";
 import type { CompositeAxisDomain } from "../../../components/chart/composite/types";
 import { FUTURES_CONTRACTS, tickDecimals } from "../futures/contracts";
 import { formatPercentileRank } from "../../../utils/format";
+import { cryptoPairCoin, isFuturesSymbol } from "../shared/crypto-pair";
+import { parseReportTime } from "../../../utils/utc-time";
 import { compareSortValues, type SortDirection } from "../../../utils/sort-values";
 
+/**
+ * CME crypto futures have a curve but no FUT board row, so their name and tick
+ * live here rather than in the catalogue the board lists. Outright ticks:
+ * BTC $5, ETH $0.50, SOL $0.05, XRP $0.0005 (each $25 a contract).
+ */
+const CRYPTO_CURVE_ROOTS: readonly { code: string; name: string; tick: number }[] = [
+  { code: "BTC", name: "Bitcoin", tick: 5 }, { code: "ETH", name: "Ether", tick: 0.5 },
+  { code: "SOL", name: "Solana", tick: 0.05 }, { code: "XRP", name: "XRP", tick: 0.0005 },
+];
+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: `${row.code} ${row.name}` })),
+  ...FUTURES_CONTRACTS.filter((row) => row.curve !== false).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) })),
 ];
 
+/** A root typed as an argument, a stored pane setting or a request: every listed root, crypto included. */
 export function normalizeCurveRoot(value: unknown): string | null {
   if (typeof value !== "string") return null;
   const raw = value.trim().toUpperCase().replace(/=F$/, "");
@@ -19,6 +34,26 @@ 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. */
+export function unsupportedCurveRootMessage(value: unknown): string {
+  const examples = ["ES", "CL", "GC", "ZN"].filter((root) => CURVE_ROOTS.some((row) => row.value === root));
+  return `Unsupported futures root: ${String(value)}. Try ${examples.join(", ")}.`;
+}
+
+/**
+ * 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.
+ */
+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;
+}
+
 /**
  * Treasury futures trade in fractions of a 32nd (ZT to 1/256, ZF 1/128, ZN
  * 1/64, ZB and UB 1/32), so the catalogue leaves their tick unset. A root
@@ -32,7 +67,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;
+  const tick = FUTURES_CONTRACTS.find((row) => row.code === root)?.tick ?? CRYPTO_CURVE_ROOTS.find((row) => row.code === root)?.tick;
   return tick == null ? 5 : Math.max(2, tickDecimals(tick));
 }
 
@@ -155,17 +190,166 @@ const CHANGE_COLUMNS: Readonly<Record<string, CurveLookback>> = { change1w: "1W"
 
 type CurveSortKey = "symbol" | "expiration" | "price" | "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): FuturesContract[] {
+  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 key = keys[id] ?? "expiration";
   const lookback = CHANGE_COLUMNS[id];
-  const value = (row: FuturesContract) => lookback ? changes?.get(row.symbol)?.[lookback] ?? null : row[key] ?? null;
+  const basisKey = BASIS_COLUMNS[id];
+  const value = (row: FuturesContract) => lookback ? changes?.get(row.symbol)?.[lookback] ?? null
+    : basisKey ? basis?.get(row.symbol)?.[basisKey] ?? null : row[key] ?? null;
   return [...rows].sort((a, b) => compareSortValues(value(a), value(b), direction));
 }
 
 const DAY_MS = 86_400_000;
 
+/**
+ * The quote each crypto root's basis is measured against: the terminal's USD
+ * pair, the same quote every other pane shows, not the CME reference rate, so
+ * a small gap to settlement is expected. A root missing here has no basis
+ * columns; add its spot symbol to give it some.
+ */
+const BASIS_SPOT_SYMBOLS: ReadonlyMap<string, string> = new Map([
+  ["BTC", "BTC-USD"], ["ETH", "ETH-USD"], ["SOL", "SOL-USD"], ["XRP", "XRP-USD"],
+]);
+
+export function basisSpotSymbol(root: string): string | null {
+  return BASIS_SPOT_SYMBOLS.get(root) ?? null;
+}
+
+/** Crypto trades around the clock, so a spot quote older than this no longer prices a live future. */
+const SPOT_STALE_MS = 10 * 60_000;
+/** A free account's quote is held back on purpose; that delay is not staleness, so it is allowed on top. */
+const DELAYED_SPOT_MS = 15 * 60_000;
+
+/** The spot a curve's basis uses, or why there is none. `asOf` is the quote's own time, never the fetch's. */
+export interface CurveSpot {
+  symbol: string;
+  price: number | null;
+  /** UTC ISO instant of the quote. */
+  asOf: string | null;
+  status: "ok" | "stale" | "missing";
+  reason: string | null;
+}
+
+export interface SpotQuote {
+  price: number;
+  lastUpdated: number;
+  stale?: boolean;
+  dataSource?: string;
+}
+
+const positive = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value) && value > 0;
+
+function quoteAge(ms: number): string {
+  const minutes = Math.floor(ms / 60_000);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  return hours < 48 ? `${hours}h` : `${Math.floor(hours / 24)}d`;
+}
+
+/** Judges one spot quote at `now`: usable, older than the rule allows, or absent. */
+export function curveSpot(symbol: string, quote: SpotQuote | null | undefined, now: number): CurveSpot {
+  if (!quote || !positive(quote.price)) return { symbol, price: null, asOf: null, status: "missing", reason: `no ${symbol} quote` };
+  const time = quote.lastUpdated;
+  if (!Number.isFinite(time) || time <= 0) {
+    return { symbol, price: quote.price, asOf: null, status: "stale", reason: `${symbol} quote has no time` };
+  }
+  const asOf = new Date(time).toISOString().replace(".000Z", "Z");
+  const age = now - time;
+  const limit = SPOT_STALE_MS + (quote.dataSource === "delayed" ? DELAYED_SPOT_MS : 0);
+  if (age > limit) return { symbol, price: quote.price, asOf, status: "stale", reason: `${symbol} quote is ${quoteAge(age)} old` };
+  if (quote.stale === true) return { symbol, price: quote.price, asOf, status: "stale", reason: `${symbol} quote is stale` };
+  return { symbol, price: quote.price, asOf, status: "ok", reason: null };
+}
+
+/** How far the contract trades over (positive) or under spot, in percent. */
+export function vsSpotPct(futures: number | null | undefined, spot: number | null | undefined): number | null {
+  return positive(futures) && positive(spot) ? (futures / spot - 1) * 100 : null;
+}
+
+/** Calendar days from the UTC date of the spot's timestamp to the contract's expiration date. */
+export function daysToExpiry(spotTime: number, expiration: string): number | null {
+  const expiry = Date.parse(`${expiration}T00:00:00Z`);
+  if (!Number.isFinite(spotTime) || !Number.isFinite(expiry)) return null;
+  const spotDay = Date.parse(`${new Date(spotTime).toISOString().slice(0, 10)}T00:00:00Z`);
+  return Math.round((expiry - spotDay) / DAY_MS);
+}
+
+/** The premium over spot as a yearly rate, on a 365-day year. Blank on or past expiry, where it has no meaning. */
+export function annualisedBasisPct(futures: number | null | undefined, spot: number | null | undefined, days: number | null): number | null {
+  if (!positive(futures) || !positive(spot) || days == null || !Number.isFinite(days) || days <= 0) return null;
+  return (futures / spot - 1) * 365 / days * 100;
+}
+
+/** A contract that printed longer than this before the spot quote is too old to read against it. */
+const CONTRACT_PRINT_MAX_AGE_MS = 60 * 60_000;
+
+export interface ContractBasis {
+  vsSpotPct: number | null;
+  annualisedBasisPct: number | null;
+  /** Priced and not flagged stale, but its last print is over an hour before spot: a thin month. */
+  thin: boolean;
+}
+
+const NO_BASIS: ContractBasis = { vsSpotPct: null, annualisedBasisPct: null, thin: false };
+
+/**
+ * One contract's basis. Blank without a usable spot, and for a contract whose
+ * own price is missing or stale: an old future against a live spot misleads.
+ * So does a print more than an hour older than the spot (`thin`): the server's
+ * stale flag allows two sessions, which a quote that moves all day outruns. A
+ * date-only `asOf` is UTC midnight of that date, one that cannot be read
+ * counts as old, and a print newer than the spot is never old (the spot of a
+ * delayed feed trails the futures).
+ */
+export function contractBasis(row: Pick<FuturesContract, "price" | "stale" | "expiration" | "asOf">, spot: CurveSpot): ContractBasis {
+  if (spot.status !== "ok" || spot.asOf == null || row.stale) return NO_BASIS;
+  const vs = vsSpotPct(row.price, spot.price);
+  if (vs == null) return NO_BASIS;
+  const spotTime = Date.parse(spot.asOf);
+  const printed = parseReportTime(row.asOf)?.time ?? null;
+  if (printed == null || spotTime - printed > CONTRACT_PRINT_MAX_AGE_MS) return { ...NO_BASIS, thin: true };
+  return { vsSpotPct: vs, annualisedBasisPct: annualisedBasisPct(row.price, spot.price, daysToExpiry(spotTime, row.expiration)), thin: false };
+}
+
+/** A basis in percent, signed; one that rounds to zero stays unsigned. */
+export function curveBasisPercent(value: number | null, decimals: number): string {
+  if (value == null) return "--";
+  const text = Math.abs(value).toFixed(decimals);
+  return /[1-9]/.test(text) ? `${value > 0 ? "+" : "-"}${text}%` : `${text}%`;
+}
+
+/** The footer's spot: `spot BTC-USD 67,250.10 · 07:25 UTC`, with the date when the quote is not from today. */
+export function curveSpotLabel(spot: CurveSpot, root: string, now: number): string {
+  const decimals = curvePriceDecimals(root);
+  const price = spot.price == null ? "--" : spot.price.toLocaleString("en-US", { minimumFractionDigits: decimals, maximumFractionDigits: decimals });
+  const stamp = curveTimestamp(spot.asOf);
+  const today = new Date(now).toISOString().slice(0, 10);
+  return `spot ${spot.symbol} ${price} · ${spot.asOf?.startsWith(today) ? stamp.slice(11) : stamp} UTC`;
+}
+
+/** The basis columns' sort values, which live beside the contract rather than on it. */
+export type CurveBasisRows = ReadonlyMap<string, ContractBasis>;
+
+export function curveBasisRows(rows: readonly FuturesContract[], spot: CurveSpot | null): CurveBasisRows {
+  return new Map(rows.map((row) => [row.symbol, spot ? contractBasis(row, spot) : NO_BASIS]));
+}
+
+/** The contracts a good spot left blank for their old print. */
+export function thinContractCount(basis: Iterable<ContractBasis>): number {
+  let count = 0;
+  for (const row of basis) if (row.thin) count += 1;
+  return count;
+}
+
+/** The footer warning that thin contracts have no basis: the pane's `!` notice, which keeps the footer row for the quote times. */
+export function thinContractsNotice(count: number): string {
+  return `Basis blank on ${count} thin contract${count === 1 ? "" : "s"} (last print over 1h before spot)`;
+}
+
 /** A past date for the as-of view: empty (or "latest") for the live curve, else YYYY-MM-DD no later than today. */
 export function curveAsOfDate(value: unknown, now = new Date()): string {
   const date = typeof value === "string" ? value.trim() : "";

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

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { chartTableChromeRows, ChartTableHeader, CurveSurface, curveGhostColors, DataTableView, Notice, PaneStatusBody, QueryBar, useChartTableSelection, usePaneNoticeFooter, usePaneStatusFooter, usePaneTabs, type DataTableColumn, type StatItem } from "../../../components";
+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";
@@ -13,8 +14,9 @@ import { nextHeaderSort, type SortDirection } from "../../../utils/sort-values";
 import { useAutoRefresh } from "../../../react/auto-refresh";
 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 { curveAsOfDate, curveAxisPrice, curveChangeText, curveContractChanges, curvePrice, curveRank, curveTimestamp, DEFAULT_CURVE_HORIZON, futuresCurveSeries, newestQuote, normalizeCurveRoot, sortCurveContracts, type CurveContractChanges } from "./model";
+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";
 
 const TABS = [{ value: "curve", label: "Curve" }, { value: "contracts", label: "Contracts" }];
 const COLUMNS: DataTableColumn[] = [
@@ -38,6 +40,19 @@ const CURVE_COLUMNS: DataTableColumn[] = [
   { id: "change1m", label: "VS 1M", width: 10, align: "right" },
   ...COLUMNS.slice(4, -1),
 ];
+// 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 },
+  { id: "vsSpot", label: "VS SPOT", width: 9, align: "right" },
+  { id: "annBasis", label: "ANN BASIS", width: 11, align: "right" },
+  ...CURVE_COLUMNS.slice(3),
+];
+const BASIS_DROP_ORDER = ["percentile", "volume", "change1m", "oi"];
+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;
 const signedPercent = (value: number | null) => value == null ? "--" : formatPercentRaw(value);
 const integer = (value: number | null) => value == null ? "--" : value.toLocaleString("en-US");
 const contractKey = (row: FuturesContract) => row.symbol;
@@ -50,7 +65,7 @@ export function FuturesCurvePane(props: PaneProps) {
   const requested = pane?.settings?.root ?? pane?.params?.root ?? "ES";
   const root = normalizeCurveRoot(requested);
   return root ? <FuturesCurveView key={root} {...props} root={root} />
-    : <PaneStatusBody error={`Unsupported futures root: ${String(requested)}`} subject="futures curve" />;
+    : <PaneStatusBody error={unsupportedCurveRootMessage(requested)} subject="futures curve" />;
 }
 
 function FuturesCurveView({ width, height, focused, root }: PaneProps & { root: string }) {
@@ -79,6 +94,23 @@ function FuturesCurveView({ width, height, focused, root }: PaneProps & { root:
   // A pending date change must never relabel the previous curve as the new one.
   const data = resource.data?.date === requestedDate ? resource.data.payload : null;
   usePaneTitle(`CTM ${root}`);
+  const curveTab = tab === "curve";
+  // The Curve tab of a crypto root reads against spot; a past date has no spot history.
+  const spotSymbol = basisSpotSymbol(root);
+  const basisActive = curveTab && !requestedDate && spotSymbol != null;
+  const spotSymbols = useMemo(() => basisActive ? [spotSymbol] : NO_SYMBOLS, [basisActive, spotSymbol]);
+  const { quotes: spotQuotes } = useQuoteBoard(spotSymbols);
+  const [clock, setClock] = useState(() => Date.now());
+  useEffect(() => {
+    if (!basisActive) return;
+    setClock(Date.now());
+    const timer = setInterval(() => setClock(Date.now()), SPOT_CLOCK_MS);
+    return () => clearInterval(timer);
+  }, [basisActive]);
+  const spotState = spotSymbol ? spotQuotes.get(spotSymbol) : undefined;
+  // Until the first answer there is nothing to say: no reason, only blank cells.
+  const spot = useMemo(() => !basisActive || !spotSymbol || !spotState || spotState.loading && !spotState.quote ? null
+    : curveSpot(spotSymbol, spotState.quote, clock), [basisActive, clock, spotState, spotSymbol]);
   const staleCount = data?.contracts.filter((row) => row.stale).length ?? 0;
   const newest = data ? newestQuote(data.contracts) : null;
   // A past curve is named by the session it holds: a weekend or holiday date shows the session before it.
@@ -86,8 +118,9 @@ function FuturesCurveView({ width, height, focused, root }: PaneProps & { root:
     requestedDate ? Date.parse(`${requestedDate}T00:00:00Z`) : Date.now(), requestedDate ? data.asOf ?? requestedDate : undefined) : [],
   [data, colors, horizon, requestedDate]);
   const changes = useMemo<CurveContractChanges>(() => data ? curveContractChanges(data) : new Map(), [data]);
-  const rows = useMemo(() => sortCurveContracts(data?.contracts ?? [], sort.columnId, sort.direction, changes), [data, sort, changes]);
-  const curveTab = tab === "curve";
+  const basis = useMemo(() => curveBasisRows(basisActive ? data?.contracts ?? [] : [], spot), [basisActive, data, spot]);
+  const thinCount = useMemo(() => thinContractCount(basis.values()), [basis]);
+  const rows = useMemo(() => sortCurveContracts(data?.contracts ?? [], sort.columnId, sort.direction, changes, basis), [data, sort, changes, basis]);
   // The curve tab lists the contracts the chart plots; Contracts keeps every one.
   const curveRows = useMemo(() => {
     const charted = new Set(curves[0]?.points.map((point) => point.id));
@@ -108,7 +141,8 @@ function FuturesCurveView({ width, height, focused, root }: PaneProps & { root:
   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 = curveTab ? CURVE_COLUMNS : COLUMNS;
+  const columns = useMemo(() => !curveTab ? COLUMNS : basisActive ? fitChartTableColumns(BASIS_CURVE_COLUMNS, width, BASIS_DROP_ORDER) : CURVE_COLUMNS,
+    [basisActive, curveTab, 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`;
@@ -142,7 +176,9 @@ 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;
-  usePaneNoticeFooter({ registrationId: "futures-curve:notices", focused, notices: emptyPast ? [] : data?.gaps ?? [] });
+  // Thin contracts join the data warnings: the info row has no room for them beside the quote times.
+  usePaneNoticeFooter({ registrationId: "futures-curve:notices", focused,
+    notices: emptyPast ? [] : [...data?.gaps ?? [], ...thinCount ? [thinContractsNotice(thinCount)] : []] });
   const delay = Math.max(0, ...(data?.contracts.map((row) => row.delayMinutes ?? 0) ?? []));
   usePaneStatusFooter({ registrationId: "futures-curve", loading: resource.loading, error: resource.error,
     hints: [
@@ -152,6 +188,8 @@ function FuturesCurveView({ width, height, focused, root }: PaneProps & { root:
     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" }] },
       ...(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 }] }] : []),
     ] : [],
   });
   const tableChromeRows = chartTableChromeRows(columns, width);
@@ -166,8 +204,8 @@ function FuturesCurveView({ width, height, focused, root }: PaneProps & { root:
   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.
-    if (column.id === "price") return { text: curvePrice(row.price, root), color: curveTab && row.stale ? colors.warning : undefined };
+    // 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 };
     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 };
@@ -176,11 +214,15 @@ function FuturesCurveView({ width, height, focused, root }: PaneProps & { root:
       const change = changes.get(row.symbol)?.[column.id === "change1w" ? "1W" : "1M"] ?? null;
       return { text: curveChangeText(change, root), color: colors.textMuted };
     }
+    if (column.id === "vsSpot" || column.id === "annBasis") {
+      const cell = basis.get(row.symbol);
+      return { text: column.id === "vsSpot" ? curveBasisPercent(cell?.vsSpotPct ?? null, 2) : curveBasisPercent(cell?.annualisedBasisPct ?? null, 1), color: colors.textMuted };
+    }
     if (column.id === "percentile") return { text: row.samples < 2 || row.percentile == null ? "--" : row.percentile.toFixed(0) };
     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 };
-  }, [changes, colors, curveTab, root]);
+  }, [basis, changes, colors, curveTab, root]);
   return <Box width={width} height={height} flexDirection="column">
     {tabStrip}
     <QueryBar width={width} filters={[{

package/src/plugins/builtin/gpu/headless.ts

@@ -2,6 +2,7 @@ import type { GpuObservation } from "../../../api-client/gpu";
 import type { HeadlessPaneDefinition } from "../../../types/plugin";
 import { fetchGpuBoard, fetchGpuEvents, fetchGpuHistory, loadGpuEquityHistory } from "./client";
 import { GPU_TABS, gpuArgument, gpuBasisLabel, gpuChange, gpuEquityRows, gpuEventDate, gpuProvenanceLabel, gpuLabel, gpuRows, gpuSource, gpuTab } from "./model";
+import { quoteFreshnessFields } from "../shared/report-freshness";
 
 const observationRow = (row: GpuObservation) => ({ gpu: gpuLabel(row), source: gpuSource(row), basis: gpuBasisLabel(row.basis),
   price: row.pricePerGpuHr, availability: row.availability, observedAt: row.observedAt, effectiveAt: row.effectiveAt, provenance: row.provenance ?? "live", provenanceLabel: gpuProvenanceLabel(row, true),
@@ -26,9 +27,11 @@ export const gpuHeadless: HeadlessPaneDefinition<"bundle"> = {
     const tab = gpuTab(args.options.tab);
     const board = await fetchGpuBoard(ctx.apiClient);
     const metadata = { asOf: board.asOf, stale: board.stale, complete: board.status === "available" && !board.access?.locked, unit: "USD/GPU-hour", access: board.access };
+    // Prices observed on providers' pages, not a feed; each board row says whether its source has gone quiet.
+    const freshness = { source: "GPU cloud providers", status: "not-a-feed" as const, basis: "observed prices" };
     if (tab === "history") {
       const history = await fetchGpuHistory({ ...(model ? { gpuModel: model } : {}), limit: 10_000 }, ctx.apiClient);
-      return { sections: [{ title: "Dated observations", columns: [...columns.filter((column) => !column.key.startsWith("change")), { key: "provenanceLabel", header: "Record" }], rows: history.points.map(observationRow) }], complete: !history.access?.locked, metadata: { ...metadata, access: history.access ?? board.access }, errors: board.gaps };
+      return { sections: [{ title: "Dated observations", columns: [...columns.filter((column) => !column.key.startsWith("change")), { key: "provenanceLabel", header: "Record" }], rows: history.points.map(observationRow) }], freshness: { ...freshness, oldest: null }, complete: !history.access?.locked, metadata: { ...metadata, access: history.access ?? board.access }, errors: board.gaps };
     }
     if (tab === "changes") {
       const payload = await fetchGpuEvents(model || undefined, ctx.apiClient);
@@ -41,7 +44,7 @@ export const gpuHeadless: HeadlessPaneDefinition<"bundle"> = {
         oldPrice: event.oldPrice, newPrice: event.newPrice, changePct: event.changePct, kind: event.kind,
         oldMembers: event.oldMembers, newMembers: event.newMembers, provenance: event.provenance ?? "live",
         provenanceLabel: gpuProvenanceLabel(event, true), evidenceUrl: event.evidenceUrl ?? null, sourceUrl: event.sourceUrl ?? null,
-        oldAvailability: event.oldAvailability ?? null, newAvailability: event.newAvailability ?? null })) }], complete: !payload.access?.locked, metadata: { ...metadata, access: payload.access ?? board.access }, errors: board.gaps };
+        oldAvailability: event.oldAvailability ?? null, newAvailability: event.newAvailability ?? null })) }], freshness: { ...freshness, oldest: null }, complete: !payload.access?.locked, metadata: { ...metadata, access: payload.access ?? board.access }, errors: board.gaps };
     }
     if (tab === "equities") {
       const related = gpuEquityRows(board.rows, model || "H100");
@@ -51,6 +54,7 @@ export const gpuHeadless: HeadlessPaneDefinition<"bundle"> = {
         const history = histories.find((entry) => entry.symbol === row.symbol);
         return { symbol: row.symbol, role: row.role, price: quote?.price ?? null, change1d: quote?.changePercent ?? null,
           change5d: history?.value ?? null, fiveDayAsOf: history?.asOf ?? null, quoteAsOf: quote?.lastUpdated ? new Date(quote.lastUpdated).toISOString() : null,
+          ...quoteFreshnessFields(quote),
           gpu: row.reference ? gpuLabel(row.reference) : row.gpuModel, gpuSource: row.reference ? gpuSource(row.reference) : null, gpuChange7d: row.reference?.change7d ?? null };
       }));
       return { sections: [{ title: "Related equities", columns: [
@@ -62,6 +66,6 @@ export const gpuHeadless: HeadlessPaneDefinition<"bundle"> = {
     }
     const rows = gpuRows(board.rows, model).map((row) => ({ ...observationRow(row), change1d: row.change1d, change7d: row.change7d,
       change30d: row.change30d, stale: row.stale, sample: row.stats ?? null }));
-    return { sections: [{ title: "GPU rental prices", columns, rows }], complete: !board.access?.locked, metadata, errors: board.gaps };
+    return { sections: [{ title: "GPU rental prices", columns, rows }], freshness, complete: !board.access?.locked, metadata, errors: board.gaps };
   },
 };