gloomberb 0.18.3 → 0.18.4

package/src/plugins/builtin/research/corporate-actions-pane.tsx

@@ -6,6 +6,7 @@ import {
   ChartTableHeader,
   DetailScrollBody,
   KeyValueRow,
+  QueryBar,
   Prose,
   SectionHeading,
   usePaneNoticeFooter,
@@ -31,6 +32,8 @@ import { handleRefreshKey } from "../../../components/data-table/table-pane";
 import { SignInWall } from "../cloud/auth-actions";
 import { isCloudSessionRequired, useResearchCloudSession } from "../shared/research-cloud-session";
 import { useBoundTicker as useSymbolBinding, useTickerRequest } from "../shared/ticker-request";
+import { loadEarningsCalendar } from "../earnings/data/cache";
+import { calendarEventOf, newYorkDay, withResolvedEarnings } from "../shared/earnings-calendar";
 import {
   documentContentKey,
   formatCompactDocumentLabel,
@@ -50,7 +53,7 @@ import {
   type EventStatus,
 } from "./event-model";
 
-type EventColumnId = "date" | "status" | "period" | "qEps" | "qRevenue" | "annualEps" | "annualRevenue" | "value" | "detail";
+type EventColumnId = "date" | "status" | "period" | "qEps" | "qRevenue" | "annualEps" | "annualRevenue" | "value" | "detail" | "eps" | "revenue" | "surprise" | "growth";
 type EventColumn = DataTableColumn & { id: EventColumnId };
 
 const SEC_EVENT_FILING_LIMIT = 50;
@@ -138,15 +141,15 @@ export function matchEarningsSecFiling(row: { status: string; date: string; date
   return best?.filing ?? null;
 }
 
-/** The one currency every EPS and revenue cell is in, so the headers carry it once. */
-function sharedMetricCurrency(rows: readonly EventRow[]): string | undefined {
+/** Share the currency label; EE marks any unstated currencies separately. */
+function sharedMetricCurrency(rows: readonly EventRow[], allowUnstated = false): string | undefined {
   const currencies = new Set<string | undefined>();
   for (const row of rows) {
     for (const [value, currency] of [
       [row.qEps, row.epsCurrency], [row.annualEps, row.epsCurrency],
       [row.qRevenue, row.revenueCurrency], [row.annualRevenue, row.revenueCurrency],
     ] as const) {
-      if (value != null && Number.isFinite(value)) currencies.add(currency || undefined);
+      if (value != null && Number.isFinite(value) && (currency || !allowUnstated)) currencies.add(currency || undefined);
     }
   }
   const [only] = currencies;
@@ -154,11 +157,23 @@ function sharedMetricCurrency(rows: readonly EventRow[]): string | undefined {
 }
 
 export function buildEventColumns(width: number, unit?: string, variant: "corporate-actions" | "earnings-estimates" = "corporate-actions"): EventColumn[] {
+  if (variant === "earnings-estimates") {
+    return fitChartTableColumns<EventColumn>([
+      { id: "date", label: "DATE", width: 10, align: "left" },
+      { id: "status", label: "EVENT", width: 8, align: "left" },
+      { id: "period", label: "PERIOD", width: 9, align: "left" },
+      { id: "eps", label: "EPS", width: unit ? 7 : 11, align: "right" },
+      { id: "revenue", label: "REVENUE", width: unit ? 9 : 13, align: "right" },
+      { id: "surprise", label: "EPS SURP", width: 9, align: "right" },
+      { id: "growth", label: "YOY GROWTH", width: 14, align: "right" },
+      { id: "detail", label: "DETAIL", width: 9, align: "left", flexGrow: 1 },
+    ], width, ["detail", "growth", "revenue"]);
+  }
   const withUnit = (label: string) => unit ? `${label} ${unit}` : label;
   const columns: EventColumn[] = [
     { id: "date", label: "DATE", width: 10, align: "left" },
     { id: "status", label: "EVENT", width: 8, align: "left" },
-    { id: "period", label: "PERIOD", width: variant === "corporate-actions" ? 12 : 9, align: "left" },
+    { id: "period", label: "PERIOD", width: 12, align: "left" },
     { id: "qEps", label: withUnit("Q EPS"), width: 12, align: "right" },
     { id: "qRevenue", label: withUnit("Q REV"), width: 12, align: "right" },
     { id: "annualEps", label: withUnit("ANN EPS"), width: 12, align: "right" },
@@ -166,9 +181,7 @@ export function buildEventColumns(width: number, unit?: string, variant: "corpor
     { id: "value", label: "VALUE", width: 11, align: "right" },
     { id: "detail", label: "DETAIL", width: 9, align: "left", flexGrow: 1 },
   ];
-  // EE keeps its scrollable estimate columns; EVT prioritizes the event value.
-  return variant === "earnings-estimates" ? columns
-    : fitChartTableColumns(columns, width, ["annualRevenue", "annualEps", "qRevenue", "qEps", "detail"]);
+  return fitChartTableColumns(columns, width, ["annualRevenue", "annualEps", "qRevenue", "qEps", "detail"]);
 }
 
 function toneColor(tone: EventRow["tone"]): string {
@@ -434,13 +447,16 @@ export function CorporateActionsView({
   const trailingEps = tickerFinancials?.fundamentals?.eps;
   const trailingEpsCurrency = tickerFinancials?.fundamentals?.epsCurrency;
   const fundamentalsCurrency = tickerFinancials?.fundamentals?.financialCurrency;
+  const marketCapCurrency = tickerFinancials?.fundamentals?.marketCapCurrency;
+  const quoteCurrency = tickerFinancials?.quote?.currency;
   const financialsData = useMemo<EventFinancials | null>(
     () => (quarterlyStatements || financialCurrency || trailingEps != null ? {
       quarterlyStatements: quarterlyStatements ?? [],
       financialCurrency,
-      fundamentals: { eps: trailingEps, epsCurrency: trailingEpsCurrency, financialCurrency: fundamentalsCurrency },
+      fundamentals: { eps: trailingEps, epsCurrency: trailingEpsCurrency, financialCurrency: fundamentalsCurrency, marketCapCurrency },
+      quote: quoteCurrency ? { currency: quoteCurrency } : null,
     } : null),
-    [financialCurrency, fundamentalsCurrency, quarterlyStatements, trailingEps, trailingEpsCurrency],
+    [financialCurrency, fundamentalsCurrency, marketCapCurrency, quarterlyStatements, quoteCurrency, trailingEps, trailingEpsCurrency],
   );
   const actionsLoader = useCallback((nextSymbol: string, nextExchange: string, forceRefresh: boolean) => {
     if (!dataProvider?.getCorporateActions) throw new Error("Corporate actions source unavailable");
@@ -450,12 +466,22 @@ export function CorporateActionsView({
     if (!dataProvider?.getAnalystResearch) return null;
     return dataProvider.getAnalystResearch(nextSymbol, nextExchange, forceRefresh ? { cacheMode: "refresh" } : undefined);
   }, [dataProvider, cloudSession.requestKey]);
+  // The earnings calendar's next report, which the rows are resolved against as `earnings` and ERN read it.
+  const calendarLoader = useCallback((nextSymbol: string, _exchange: string, forceRefresh: boolean) => (
+    loadEarningsCalendar(dataProvider, [nextSymbol], { force: forceRefresh }).then((result) => calendarEventOf(result.events, nextSymbol))
+  ), [dataProvider]);
   const {
-    data: actionsData,
+    data: recordedActions,
     loading: actionsLoading,
     error: actionsError,
     reload: reloadActions,
   } = useTickerRequest<CorporateActionsData>(actionsLoader, symbol, exchange);
+  const { data: calendarEvent, reload: reloadCalendar } = useTickerRequest(calendarLoader, symbol, exchange);
+  const today = newYorkDay();
+  const actionsData = useMemo(
+    () => (recordedActions ? withResolvedEarnings(recordedActions, calendarEvent, today) : recordedActions),
+    [calendarEvent, recordedActions, today],
+  );
   const {
     data: analystData,
     loading: analystLoading,
@@ -471,7 +497,11 @@ export function CorporateActionsView({
       ? allRows.filter((row) => EARNINGS_STATUSES.has(row.status))
       : allRows
   ), [allRows, variant]);
-  const unit = useMemo(() => sharedMetricCurrency(rows), [rows]);
+  const unit = useMemo(() => sharedMetricCurrency(rows, variant === "earnings-estimates"), [rows, variant]);
+  const hasUnstatedCurrency = rows.some((row) =>
+    ((row.qEps != null || row.annualEps != null) && !row.epsCurrency)
+    || ((row.qRevenue != null || row.annualRevenue != null) && !row.revenueCurrency));
+  const currencyMeta = [unit, hasUnstatedCurrency ? "? currency unstated" : null].filter(Boolean).join(" · ");
   const columns = useMemo(() => buildEventColumns(width, unit, variant), [width, unit, variant]);
   const sourceNotice = useMemo(() => (
     actionsLoading || analystLoading
@@ -506,7 +536,8 @@ export function CorporateActionsView({
   const reload = useCallback(() => {
     reloadActions();
     reloadAnalyst();
-  }, [reloadActions, reloadAnalyst]);
+    reloadCalendar();
+  }, [reloadActions, reloadAnalyst, reloadCalendar]);
   const openRow = openRowId
     ? rows.find((row) => row.id === openRowId) ?? null
     : null;
@@ -593,6 +624,19 @@ export function CorporateActionsView({
         return { text: row.status, color: colors.textBright, attributes: TextAttributes.BOLD };
       case "period":
         return { text: row.period, color: colors.textDim };
+      case "eps":
+      case "revenue": {
+        const eps = column.id === "eps";
+        const value = eps ? row.qEps ?? row.annualEps : row.qRevenue ?? row.annualRevenue;
+        const currency = eps ? row.epsCurrency : row.revenueCurrency;
+        const text = formatEventMetric(value, unit ? undefined : currency, eps ? "eps" : "revenue");
+        return { text: value != null && !currency ? `${text} ?` : text,
+          value: unit && currency ? value : undefined, color: colors.textDim };
+      }
+      case "surprise":
+        return { text: row.status === "Earnings" ? row.value : "-", value: row.surprisePercent, color: row.status === "Earnings" ? toneColor(row.tone) : colors.textDim };
+      case "growth":
+        return { text: row.estimateGrowthMetric && row.value !== "-" ? `${row.value} ${row.estimateGrowthMetric === "eps" ? "EPS" : "rev"}` : "-", color: row.estimateGrowthMetric ? toneColor(row.tone) : colors.textDim };
       case "qEps":
         return { text: formatEventMetric(row.qEps, unit ? undefined : row.epsCurrency, "eps"), color: colors.textDim };
       case "qRevenue":
@@ -648,7 +692,8 @@ export function CorporateActionsView({
       detailScrollRef={detailScrollRef}
       rootWidth={width}
       rootHeight={height}
-      rootBefore={<ChartTableHeader width={width} height={height} tableRows={rows.length} tableColumns={columns} />}
+      rootBefore={<ChartTableHeader width={width} height={height} tableRows={rows.length} tableColumns={columns}
+        query={variant === "earnings-estimates" && currencyMeta ? <QueryBar width={width} meta={currencyMeta} /> : undefined} />}
       onRootKeyDown={handleKeyDown}
       columns={columns}
       items={rows}
@@ -656,6 +701,10 @@ export function CorporateActionsView({
       sortDirection="desc"
       getItemKey={eventRowKey}
       renderCell={renderCell}
+      getExportMetadata={variant === "earnings-estimates" ? () => [
+        ...(unit ? [["Currency", unit]] : []),
+        ...(hasUnstatedCurrency ? [["?", "Currency unstated"]] : []),
+      ] : undefined}
       selectedTextOverridesCellColor
       getRowBackgroundColor={rowBackground}
       emptyStateTitle={loading

package/src/plugins/builtin/research/event-model.ts

@@ -179,7 +179,9 @@ function estimateValue(pair: EstimatePair): string {
  * with the fundamentals, the figure `ticker` prints as EPS (TTM).
  */
 export type EventFinancials = Pick<TickerFinancials, "quarterlyStatements" | "financialCurrency"> & {
-  fundamentals?: Pick<NonNullable<TickerFinancials["fundamentals"]>, "eps" | "epsCurrency" | "financialCurrency"> | null;
+  fundamentals?: Pick<NonNullable<TickerFinancials["fundamentals"]>, "eps" | "epsCurrency" | "financialCurrency" | "marketCapCurrency"> | null;
+  /** The listing's currency, which says whether an unlabelled EPS can be in the statements' (fundamentalsCurrency). */
+  quote?: Pick<NonNullable<TickerFinancials["quote"]>, "currency"> | null;
 };
 
 /**

package/src/plugins/builtin/research/event-sources.ts

@@ -5,6 +5,8 @@ import type {
   TickerFinancials,
 } from "../../../types/financials";
 import { formatEventMetric } from "./event-model";
+import { loadEarningsCalendar } from "../earnings/data/cache";
+import { calendarEventOf, newYorkDay, withResolvedEarnings } from "../shared/earnings-calendar";
 
 function metricFormat(currencyKey: "epsCurrency" | "revenueCurrency", kind: "eps" | "revenue") {
   return (value: unknown, row: Record<string, unknown>) => {
@@ -42,14 +44,20 @@ function settledError(result: PromiseSettledResult<unknown>): string | null {
   return result.reason instanceof Error ? result.reason.message : String(result.reason);
 }
 
-/** Corporate actions, analyst research and financials together; one failing leaves the others. */
-export async function loadEventSources(provider: DataProvider, symbol: string): Promise<EventSources> {
-  const [actions, estimates, financials] = await Promise.allSettled([
+/**
+ * Corporate actions, analyst research and financials together; one failing
+ * leaves the others. The earnings rows are resolved against the earnings
+ * calendar, so the next report reads as `earnings` and ERN give it.
+ */
+export async function loadEventSources(provider: DataProvider, symbol: string, today = newYorkDay()): Promise<EventSources> {
+  const [actions, estimates, financials, calendar] = await Promise.allSettled([
     provider.getCorporateActions?.(symbol, "") ?? null,
     provider.getAnalystResearch?.(symbol, "") ?? null,
     provider.getTickerFinancials(symbol, ""),
+    loadEarningsCalendar(provider, [symbol]),
   ]);
-  const actionsData = actions.status === "fulfilled" ? actions.value : null;
+  const event = calendar.status === "fulfilled" ? calendarEventOf(calendar.value.events, symbol) : null;
+  const actionsData = actions.status === "fulfilled" && actions.value ? withResolvedEarnings(actions.value, event, today) : null;
   const estimatesData = estimates.status === "fulfilled" ? estimates.value : null;
   const financialsData = financials.status === "fulfilled" ? financials.value : null;
   return {

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

@@ -159,7 +159,8 @@ export const researchModule: PluginModule = {
       paneId: "relative-valuation",
       label: "Relative Valuation",
       description: "Compare valuation and operating metrics across peers.",
-      keywords: ["relative", "valuation", "comps", "peers", "rv"],
+      // The words an analyst asks for a comp table by.
+      keywords: ["relative", "valuation", "comps", "peers", "rv", "comp table", "comparable companies", "peer comparison", "competitors"],
       shortcut: { prefix: "RV", argPlaceholder: "tickers", argKind: "ticker-list" },
       canCreate: (context, options) => !!(options?.symbols?.length || options?.arg || context.activeTicker),
       createInstance: (context, options) => {

package/src/plugins/builtin/research/relative-valuation-basis.ts

@@ -0,0 +1,58 @@
+/**
+ * What RV's figures run through, as its footer says it under the text table,
+ * in the pane and in a capture: the statement period the trailing figures
+ * reach, and the basis of each column that is not trailing twelve months.
+ */
+
+interface DatedPeer {
+  symbol: string;
+  date: string | null | undefined;
+}
+
+/**
+ * `2026-06-30`, or with peers dated apart, the date most of them share and
+ * each other peer's own: `2026-06-30 (LRN 2026-03-31)`. Null when none is dated.
+ */
+export function peerDatesText(peers: readonly DatedPeer[]): string | null {
+  const dated = peers.flatMap(({ symbol, date }) => (date ? [{ symbol, date: date.slice(0, 10) }] : []));
+  if (dated.length === 0) return null;
+  const counts = new Map<string, number>();
+  for (const { date } of dated) counts.set(date, (counts.get(date) ?? 0) + 1);
+  const [common] = [...counts].sort(([leftDate, left], [rightDate, right]) => right - left || rightDate.localeCompare(leftDate))[0]!;
+  const others = dated.filter(({ date }) => date !== common).map(({ symbol, date }) => `${symbol} ${date}`);
+  return others.length > 0 ? `${common} (${others.join(", ")})` : common;
+}
+
+interface BasisRow {
+  symbol: string;
+  fundamentalsThrough?: string | null;
+  revenueGrowth?: number | null;
+  revenueGrowthQuarter?: string | null;
+}
+
+/** `fundamentals through 2026-06-30`, the newest statement period of each peer's trailing figures; null when none is dated. */
+export function fundamentalsThroughText(rows: readonly BasisRow[]): string | null {
+  const through = peerDatesText(rows.map(({ symbol, fundamentalsThrough }) => ({ symbol, date: fundamentalsThrough })));
+  return through ? `fundamentals through ${through}` : null;
+}
+
+/**
+ * `fundamentals through 2026-06-30` and the quarter the revenue growth column
+ * compares with a year earlier, named by the column's header where the table
+ * is read: `, Q REV% for that quarter` when it is the one the fundamentals run
+ * through for every peer, else on its own (`Q REV%: quarter to 2026-03-31`).
+ * P/E, EV/S, FCF yield and the operating margin are trailing twelve months
+ * through that date; the forward P/E says forward in its own header.
+ */
+export function fundamentalsBasisParts(rows: readonly BasisRow[], revenueGrowthHeader: string): string[] {
+  const through = fundamentalsThroughText(rows);
+  const growing = rows.filter((row) => row.revenueGrowth != null);
+  const quarter = peerDatesText(growing.map(({ symbol, revenueGrowthQuarter }) => ({ symbol, date: revenueGrowthQuarter })));
+  if (through && quarter && growing.every((row) => row.revenueGrowthQuarter === row.fundamentalsThrough)) {
+    return [`${through}, ${revenueGrowthHeader} for that quarter`];
+  }
+  return [
+    ...(through ? [through] : []),
+    ...(quarter ? [`${revenueGrowthHeader}: quarter to ${quarter}`] : []),
+  ];
+}

package/src/plugins/builtin/research/relative-valuation-columns.ts

@@ -4,12 +4,14 @@ import type { TickerFinancials } from "../../../types/financials";
 import { isUsListingExchange, parsePublicTickerKey } from "../../../utils/exchanges";
 import { errorMessage } from "../../../utils/errors";
 import { formatNumber } from "../../../utils/format";
+import { formatPriceEarnings, NOT_MEANINGFUL } from "../../../utils/price-earnings";
 import { fetchScreen } from "../equity-screener/client";
 import { refusedLock } from "../shared/cloud-denied";
 import { resolveHeadlessInstrument } from "../shared/headless-market-data";
 import { loadShortInterest } from "../short-interest/client";
 import { buildShortWatchRow } from "../short-interest/watch-model";
 import { analystTargetCurrency, formatAnalystPrice, recommendationTotal } from "./analyst-model";
+import { peerDatesText } from "./relative-valuation-basis";
 
 /** The columns `--columns` adds to RV's report, each read from the path its own function uses. */
 export const EXTRA_COLUMN_IDS = ["shortInterest", "nextEarnings", "target", "grossMargin", "evEbitda"] as const;
@@ -70,6 +72,12 @@ interface ColumnSpec {
   sourceKey: string;
   asOfKey: string;
   label: string;
+  /**
+   * What the column's figures are as of, for the report's footer, from the
+   * dates of its cells (`fiscal year to 2025-12-31`). A column dated only by
+   * when it was read (targets, the earnings calendar) has none.
+   */
+  basis?: (dates: string) => string;
 }
 
 const COLUMN_SPECS: Record<ExtraColumnId, ColumnSpec> = {
@@ -78,6 +86,7 @@ const COLUMN_SPECS: Record<ExtraColumnId, ColumnSpec> = {
     columns: [{ key: "shortInterestPercentFloat", header: "Short % Float", align: "right", format: percent }],
     sourceKey: "shortInterestSource",
     asOfKey: "shortInterestAsOf",
+    basis: (dates) => `settlement ${dates}`,
   },
   nextEarnings: {
     label: "Next Earnings",
@@ -93,7 +102,7 @@ const COLUMN_SPECS: Record<ExtraColumnId, ColumnSpec> = {
   target: {
     label: "Avg Target",
     columns: [
-      { key: "targetMean", header: "Avg Target", align: "right", unitKey: "targetCurrency",
+      { key: "targetMean", header: "Avg Target", align: "right", unitKey: "targetCurrency", unitColumn: true,
         format: (value, row) => (typeof value === "number" ? formatAnalystPrice(value, typeof row.targetCurrency === "string" ? row.targetCurrency : undefined) : "-") },
       { key: "analystCount", header: "Analysts", align: "right", format: (value) => (typeof value === "number" ? String(value) : "-") },
     ],
@@ -105,12 +114,17 @@ const COLUMN_SPECS: Record<ExtraColumnId, ColumnSpec> = {
     columns: [{ key: "grossMarginPercent", header: "Gross Margin", align: "right", format: percent }],
     sourceKey: "grossMarginSource",
     asOfKey: "grossMarginAsOf",
+    // The screener stores the fiscal year's margin (its FY GROSS MGN%), dated by the year's end.
+    basis: (dates) => `fiscal year to ${dates}`,
   },
   evEbitda: {
     label: "EV/EBITDA",
-    columns: [{ key: "evEbitda", header: "EV/EBITDA", align: "right", format: (value) => (typeof value === "number" ? formatNumber(value, 1) : "-") }],
+    // N/M over an EV or EBITDA at or below zero, as EQS shows it.
+    columns: [{ key: "evEbitda", header: "EV/EBITDA", align: "right", format: (value, row) => (typeof value === "number" ? formatNumber(value, 1)
+      : row.evEbitdaNotMeaningful ? formatPriceEarnings(NOT_MEANINGFUL) : "-") }],
     sourceKey: "evEbitdaSource",
     asOfKey: "evEbitdaAsOf",
+    basis: (dates) => `statements to ${dates}`,
   },
 };
 
@@ -130,6 +144,20 @@ export function extraColumns(ids: readonly ExtraColumnId[]): { text: HeadlessPan
   };
 }
 
+/**
+ * The footer's word on each added column dated by its figures: `Gross Margin:
+ * fiscal year to 2025-12-31`, beside the TTM columns' `fundamentals through`.
+ */
+export function extraColumnsBasis(ids: readonly ExtraColumnId[], rows: readonly HeadlessPaneRow[]): string[] {
+  return ids.flatMap((id) => {
+    const spec = COLUMN_SPECS[id];
+    const valueKey = spec.columns[0]!.key;
+    const dates = spec.basis && peerDatesText(rows.filter((row) => row[valueKey] != null)
+      .map((row) => ({ symbol: String(row.symbol), date: typeof row[spec.asOfKey] === "string" ? row[spec.asOfKey] as string : null })));
+    return dates ? [`${spec.label}: ${spec.basis!(dates)}`] : [];
+  });
+}
+
 /** Whether a symbol is a US listing, which FINRA short interest, the earnings calendar and the screener cover. */
 function usListing(symbol: string): string | null {
   const { symbol: bare, exchange } = parsePublicTickerKey(symbol);
@@ -273,6 +301,7 @@ async function loadScreenerFields(ids: readonly ExtraColumnId[], symbols: readon
     if (wanted.includes("evEbitda")) {
       const multiple = metricFields(row.metrics.evToEbitda);
       if (multiple) Object.assign(fields, { evEbitda: multiple.value, evEbitdaSource: multiple.source, evEbitdaAsOf: multiple.asOf });
+      else if (row.metrics.evToEbitda?.notMeaningful) Object.assign(fields, { evEbitda: null, evEbitdaNotMeaningful: row.metrics.evToEbitda.reason ?? true });
     }
   }
 }

package/src/plugins/builtin/research/relative-valuation-currency.ts

@@ -1,4 +1,5 @@
 import type { HeadlessPaneContext } from "../../../types/headless";
+import type { QueryEntry } from "../../../market-data/result-types";
 import { MarketDataCoordinator, resolveEntryValue } from "../../../market-data/coordinator";
 import { fxLegForCurrency } from "../../../market-data/coordinator/fx-legs";
 import { resolveCurrencyUnit } from "../../../utils/currency-units";
@@ -33,6 +34,12 @@ export type ConvertedCapRow<Row extends CapRow> = Row & {
 
 const usable = (rate: number | undefined): rate is number => rate != null && Number.isFinite(rate) && rate > 0;
 
+/** A loaded rate as a `UsdRate`: with its source's observation time and when it was read, from the entry it came in. */
+export function usdRateFromEntry(rate: number, entry: Pick<QueryEntry<number>, "asOf" | "fetchedAt"> | null | undefined): UsdRate {
+  const time = (value: number | null | undefined) => (value != null && Number.isFinite(value) ? new Date(value).toISOString() : null);
+  return { rate, asOf: time(entry?.asOf), retrievedAt: time(entry?.fetchedAt) };
+}
+
 function olderOf(left: string | null, right: string | null): string | null {
   if (!left || !right) return left ?? right;
   return Date.parse(left) <= Date.parse(right) ? left : right;
@@ -105,13 +112,14 @@ function rateTimeText(asOf: string): string {
 
 /**
  * The status line's note naming each rate and its date:
- * `market caps in USD at EUR/USD 1.1612 (2026-10-13 21:00 UTC)`.
+ * `market caps in USD at EUR/USD 1.1612 (2026-10-13 21:00 UTC)`; the pane
+ * names its column instead, `MCAP USD at …`.
  */
-export function conversionNote(target: string, conversions: readonly CapConversion[]): string | null {
+export function conversionNote(target: string, conversions: readonly CapConversion[], subject = `market caps in ${target}`): string | null {
   if (conversions.length === 0) return null;
   const rates = conversions.map((conversion) => `${conversionPairText(conversion)} (${conversion.asOf ? rateTimeText(conversion.asOf)
     : conversion.retrievedAt ? `retrieved ${rateTimeText(conversion.retrievedAt)}` : "time not stated"})`);
-  return `market caps in ${target} at ${rates.join(", ")}`;
+  return `${subject} at ${rates.join(", ")}`;
 }
 
 /**
@@ -134,8 +142,7 @@ export async function loadFxLegs(
         const entry = await coordinator.loadFxRate(currency);
         const rate = resolveEntryValue(entry);
         if (!usable(rate ?? undefined)) throw new Error(entry.error?.message ?? "no usable rate");
-        const time = (value: number | null | undefined) => (value != null && Number.isFinite(value) ? new Date(value).toISOString() : null);
-        legs.set(currency, { rate: rate!, asOf: time(entry.asOf), retrievedAt: time(entry.fetchedAt) });
+        legs.set(currency, usdRateFromEntry(rate!, entry));
       } catch (error) {
         failed.push({ currency, reason: errorMessage(error) });
       }

package/src/plugins/builtin/research/relative-valuation-headless.ts

@@ -4,12 +4,17 @@ import { EXTENDED_SESSION_LABELS, type ExtendedSession } from "../../../market-d
 import { formatCompact, formatCurrency, formatLevelPercent, formatNumber, formatPercent, formatPercentRaw } from "../../../utils/format";
 import { loadHeadlessFinancials, loadHeadlessSymbols } from "../shared/headless-market-data";
 import { quoteFreshnessFields } from "../shared/report-freshness";
-import { RELATIVE_VALUATION_STALE_FUNDAMENTALS_NOTICE, RELATIVE_VALUATION_STALE_QUOTE_NOTICE, relativeValuationValues } from "./relative-valuation-model";
+import {
+  RELATIVE_VALUATION_STALE_FUNDAMENTALS_NOTICE, RELATIVE_VALUATION_STALE_QUOTE_NOTICE, relativeValuationValues, type RelativeValuationGapKey,
+} from "./relative-valuation-model";
 import { paneSchemas } from "./headless-schema";
 import { isRecord } from "../../../utils/guards";
+import { errorMessage } from "../../../utils/errors";
+import { notATickerSymbol } from "../../../sources/provider-errors";
 import { resolveCurrencyUnit } from "../../../utils/currency-units";
 import { pickPeers, peerMethodTitle, type PeerSelection } from "./relative-valuation-peers";
-import { extraColumns, loadExtraColumns, parseExtraColumns } from "./relative-valuation-columns";
+import { extraColumns, extraColumnsBasis, loadExtraColumns, parseExtraColumns } from "./relative-valuation-columns";
+import { fundamentalsBasisParts } from "./relative-valuation-basis";
 import { conversionNote, convertMarketCaps, loadFxLegs } from "./relative-valuation-currency";
 
 const price = (value: unknown, row: Record<string, unknown>) => (
@@ -17,6 +22,12 @@ const price = (value: unknown, row: Record<string, unknown>) => (
 );
 const percent = (value: unknown) => value == null ? "-" : formatPercentRaw(Number(value));
 
+/** The reason a row lacks the figure under `key` ("no TTM FCF"), which exports move to their status column. */
+function gapText(row: Record<string, unknown>, key: RelativeValuationGapKey): string {
+  const gaps = row.gaps as Partial<Record<RelativeValuationGapKey, string>> | undefined;
+  return gaps?.[key] ?? "-";
+}
+
 /**
  * The pre-market, after-hours or overnight print and its move from the regular close in Last, for the peers that have
  * one; "mid" when it is a bid and ask midpoint.
@@ -32,32 +43,60 @@ function extendedColumn(session: ExtendedSession): HeadlessPaneColumn {
   };
 }
 
+/**
+ * An export's extended print: the price alone, in the row's currency, then its move from the close in a
+ * `<session> Chg%` column, blank for a peer whose print is from another session or that has none.
+ */
+function extendedExportColumns(session: ExtendedSession): HeadlessPaneColumn[] {
+  const label = EXTENDED_SESSION_LABELS[session];
+  return [
+    { key: "extendedPrice", header: label, align: "right", unitKey: "currency",
+      format: (value, row) => row.extendedSession === session && typeof value === "number" ? price(value, row) : "-" },
+    { key: "extendedChangePercent", header: `${label} Chg%`, align: "right",
+      format: (value, row) => row.extendedSession === session && typeof value === "number" ? percent(value) : "-" },
+  ];
+}
+
+const EXTENDED_SESSIONS = ["PRE", "POST", "OVERNIGHT"] as const;
+
+/** Every session's columns, whichever peers have a print, so the header is the same before the open and after the close. */
+const EXTENDED_EXPORT_COLUMNS = EXTENDED_SESSIONS.flatMap(extendedExportColumns);
+
+// Last is in each peer's own currency: an export writes the number, and the row's `currency_or_unit` names its currency.
 const QUOTE_COLUMNS: HeadlessPaneColumn[] = [
   { key: "symbol", header: "Ticker" },
-  { key: "price", header: "Last", align: "right", format: price },
-  { key: "changePercent", header: "Chg%", align: "right", format: percent },
+  { key: "price", header: "Last", align: "right", unitKey: "currency",
+    format: (value, row) => value == null ? gapText(row, "price") : price(value, row) },
+  { key: "changePercent", header: "Chg%", align: "right", format: (value, row) => value == null ? gapText(row, "changePercent") : percent(value) },
 ];
 
+/** The latest quarter's revenue against the same quarter a year earlier; the footer names the quarter. */
+const REVENUE_GROWTH_HEADER = "Quarter Revenue YoY";
+
 const VALUATION_COLUMNS: HeadlessPaneColumn[] = [
   // In the currency each peer's cap is in, which exports write in the header or beside the figure.
-  { key: "marketCap", header: "Mkt Cap", align: "right", unitKey: "marketCapCurrency",
-    format: (value, row) => value == null ? "-" : `${formatCompact(Number(value), { fixedDecimals: true })}${row.marketCapCurrency ? ` ${row.marketCapCurrency}` : ""}` },
+  { key: "marketCap", header: "Mkt Cap", align: "right", unitKey: "marketCapCurrency", unitColumn: true,
+    format: (value, row) => value == null ? gapText(row, "marketCap") : `${formatCompact(Number(value), { fixedDecimals: true })}${row.marketCapCurrency ? ` ${row.marketCapCurrency}` : ""}` },
   ...([ ["trailingPE", "P/E"], ["forwardPE", "Fwd P/E"] ] as const).map(([key, header]) => ({
     key, header, align: "right" as const,
-    format: (_value: unknown, row: Record<string, unknown>) => {
+    // The multiple as reported, else the comparable value itself, so an export reads the column as one of figures.
+    format: (value: unknown, row: Record<string, unknown>) => {
       const values = row as Partial<ReturnType<typeof relativeValuationValues>>;
-      return formatPriceEarnings(values.notMeaningful?.[key] ? NOT_MEANINGFUL : values.reportedMultiples?.[key]);
+      const multiple = values.notMeaningful?.[key] ? NOT_MEANINGFUL : values.reportedMultiples?.[key] ?? (typeof value === "number" ? value : null);
+      return multiple == null ? gapText(row, key) : formatPriceEarnings(multiple);
     },
   })),
-  ...[["evSales", "EV/S"]].map(([key, header]) => ({
-    key: key!, header: header!, align: "right" as const,
-    // A withdrawn EV says so rather than leaving a bare dash; the note under the table says why.
+  ...([["evSales", "EV/S"]] as const).map(([key, header]) => ({
+    key, header, align: "right" as const,
+    // A withdrawn EV says so rather than leaving a bare dash, one at or below zero reads N/M; the note under the table says why.
     format: (value: unknown, row: Record<string, unknown>) => value != null ? formatNumber(Number(value), 1)
-      : row.evSalesUnavailable ? "EV unavailable" : "-",
+      : (row as Partial<ReturnType<typeof relativeValuationValues>>).notMeaningful?.evSales ? formatPriceEarnings(NOT_MEANINGFUL)
+        : gapText(row, key),
   })),
-  ...[["fcfYield", "FCF Yield"], ["revenueGrowth", "Quarter Revenue YoY"], ["operatingMargin", "TTM Op Margin"]].map(([key, header]) => ({
-    key: key!, header: header!, align: "right" as const,
-    format: (value: unknown) => value == null ? "-" : key === "revenueGrowth" ? formatPercent(Number(value)) : formatLevelPercent(Number(value)),
+  ...([["fcfYield", "FCF Yield"], ["revenueGrowth", REVENUE_GROWTH_HEADER], ["operatingMargin", "TTM Op Margin"]] as const).map(([key, header]) => ({
+    key, header, align: "right" as const,
+    format: (value: unknown, row: Record<string, unknown>) => value == null ? gapText(row, key)
+      : key === "revenueGrowth" ? formatPercent(Number(value)) : formatLevelPercent(Number(value)),
   })),
 ];
 
@@ -76,7 +115,14 @@ async function choosePeers(symbols: readonly string[], ctx: HeadlessPaneContext)
     throw new Error(`--peers picks the peers of one symbol, such as RV ${symbols[0] ?? "DUOL"} --peers; with several symbols, leave it out.`);
   }
   const subject = symbols[0]!;
-  return pickPeers(subject, await loadHeadlessFinancials(ctx, subject).catch(() => null), ctx);
+  const financials = await loadHeadlessFinancials(ctx, subject).catch((error: unknown) => {
+    ctx.signal.throwIfAborted();
+    // A word that is no ticker is said as `fn RV duolingo lrn` says it, which the CLI follows with the search to run.
+    if (notATickerSymbol(errorMessage(error))) throw error;
+    // Any other failure leaves the peers to what the symbol alone places (a curated core's member).
+    return null;
+  });
+  return pickPeers(subject, financials, ctx);
 }
 
 const PEER_SELECTION_SETTING = "peerSelection";
@@ -93,7 +139,7 @@ export const relativeValuationHeadless: HeadlessPaneDefinition<"rows"> = {
       ? `Relative Valuation | ${selection.subject} and ${peerMethodTitle(selection)}`
       : `Relative Valuation | ${(result?.symbols ?? symbols).join(", ")}`;
   },
-  columns: [...QUOTE_COLUMNS, ...VALUATION_COLUMNS],
+  columns: [...QUOTE_COLUMNS, ...EXTENDED_EXPORT_COLUMNS, ...VALUATION_COLUMNS],
   async expandArgument(args, ctx) {
     if (args.options.peers !== true) return null;
     const selection = await choosePeers(args.symbols, ctx);
@@ -137,23 +183,33 @@ export const relativeValuationHeadless: HeadlessPaneDefinition<"rows"> = {
       const reason = fx?.failed.find((failure) => failure.currency === resolveCurrencyUnit(currency).currency)?.reason;
       return `No ${currency} rate${reason ? ` (${reason})` : ""}: ${left.join(", ")} ${left.length === 1 ? "keeps its" : "keep their"} market cap in ${currency}.`;
     }) ?? [];
-    const conversionText = capCurrency && converted ? conversionNote(capCurrency, converted.conversions) : null;
+    // The footer: the rates the caps were converted at, the statement period the figures run through, and the
+    // basis of each column that is not trailing twelve months.
+    const footnote = [
+      ...capCurrency && converted ? [conversionNote(capCurrency, converted.conversions)] : [],
+      ...fundamentalsBasisParts(rows, REVENUE_GROWTH_HEADER),
+      ...extraColumnsBasis(extraIds, rows),
+    ].filter(Boolean).join(" · ");
     const notes = [
-      ...selection ? [`Peers chosen automatically: ${selection.basis}. To choose your own: gloomberb fn RV ${selection.subject} <tickers>.`] : [],
+      ...selection ? [`Peers chosen automatically: ${selection.basis}. To choose your own: gloom fn RV ${selection.subject} <tickers>.`] : [],
       ...extra.notes,
     ];
     // Last and Chg% are the regular session; an extended print gets a column only when a peer has one.
-    const extendedSessions = (["PRE", "POST", "OVERNIGHT"] as const).filter((session) => rows.some((row) => row.extendedSession === session));
-    const columns = [...QUOTE_COLUMNS, ...extendedSessions.map(extendedColumn), ...VALUATION_COLUMNS];
+    // Exports keep every session's price and move, so their header is the same in every market state.
+    const extendedSessions = EXTENDED_SESSIONS.filter((session) => rows.some((row) => row.extendedSession === session));
+    const textColumns = [...QUOTE_COLUMNS, ...extendedSessions.map(extendedColumn), ...VALUATION_COLUMNS];
     const added = extraIds.length > 0 ? extraColumns(extraIds) : null;
     return {
       rows, unavailableSymbols, errors, complete: unavailableSymbols.length === 0 && errors.length === 0,
       ...(selection ? { symbols } : {}),
-      ...(added ? { columns: [...columns, ...added.export], textColumns: [...columns, ...added.text] }
-        : extendedSessions.length > 0 ? { columns } : {}),
+      columns: [...QUOTE_COLUMNS, ...EXTENDED_EXPORT_COLUMNS, ...VALUATION_COLUMNS, ...added?.export ?? []],
+      textColumns: [...textColumns, ...added?.text ?? []],
+      // Each peer's row names its ticker and the currency its prices are in.
+      rowSymbolKey: "symbol",
+      rowUnitKey: "currency",
       ...(notes.length > 0 ? { notes } : {}),
       ...(warnings.length > 0 ? { warnings } : {}),
-      ...(conversionText ? { freshness: { note: conversionText } } : {}),
+      ...(footnote ? { freshness: { note: footnote } } : {}),
       metadata: {
         staleSymbols,
         staleFundamentalsSymbols,
@@ -165,11 +221,13 @@ export const relativeValuationHeadless: HeadlessPaneDefinition<"rows"> = {
         priceBasis: "price, change and changePercent are the regular session: after the close, its close and that close's move. A pre-market, after-hours or overnight print is in extendedPrice, extendedChange and extendedChangePercent, measured from that close (extendedMark when it is a bid and ask midpoint). marketCap, the P/E multiples, evSales (through the equity part of the enterprise value) and fcfYield are measured at that regular session price.",
         fundamentalsBasis: "Provider multiples and operating metrics retain independent fundamentalsProvenance. Retrieval time does not establish the valuation date.",
         notices: [
-          ...rows.some((row) => Object.keys(row.notMeaningful).length > 0
+          ...rows.some((row) => row.notMeaningful.trailingPE || row.notMeaningful.forwardPE
             || Object.values(row.reportedMultiples).some((value) => value != null && value <= 0)) ? [PRICE_EARNINGS_NOTICE] : [],
           ...rows.flatMap((row) => row.evSalesUnavailable ? [`${row.symbol}: ${row.evSalesUnavailable}`] : []),
+          ...rows.flatMap((row) => row.evSalesNote ? [`${row.symbol}: ${row.evSalesNote}`] : []),
+          ...rows.flatMap((row) => row.marketCapNote ? [`${row.symbol}: ${row.marketCapNote}`] : []),
         ],
-        multipleBasis: "Comparable P/E fields require a positive finite multiple over positive EPS; notMeaningful says why one is null, and reportedMultiples preserves the finite provider values.",
+        multipleBasis: "Comparable P/E fields require a positive finite multiple over positive EPS, and evSales an enterprise value above zero; notMeaningful says why one is null, and reportedMultiples preserves the finite provider P/E values.",
         marketCapBasis: "Market caps retain their own currency and source. Fundamentals retrieval time is not a valuation date; quote timestamps do not date fallback caps.",
       },
     };