gloomberb 0.16.4 → 0.16.5

package/src/plugins/builtin/iv-history/model.ts

@@ -1,6 +1,6 @@
 import type { PricePoint } from "../../../types/financials";
 import { rollingRealizedVolatility } from "../shared/volatility";
-import type { IvHistoryPayload, IvMethod, IvPoint, IvScreenRow, IvStats } from "./client";
+import type { IvCoverageStatus, IvHistoryPayload, IvMethod, IvPoint, IvScreenRow, IvStats } from "./client";
 
 export const HV_WINDOWS = [20, 30] as const;
 export type HvWindow = (typeof HV_WINDOWS)[number];
@@ -26,6 +26,44 @@ export interface IvStatRow {
 }
 /** Rank and percentile need this many prior sessions, matching the server. */
 const MIN_RANK_SAMPLES = 120;
+/**
+ * Minutes a symbol's first backfill usually takes from the request that
+ * queued it: nine in ten have history by then (docs/research-data.md).
+ */
+const FIRST_BACKFILL_MINUTES = 10;
+const FIRST_BACKFILL_TEXT = `a first backfill usually takes under ${FIRST_BACKFILL_MINUTES} minutes`;
+
+/** "06:41 UTC" today, with the date on another day: "2026-10-09 06:41 UTC". */
+function utcClock(time: number, now: number): string {
+  const iso = new Date(time).toISOString();
+  return iso.slice(0, 10) === new Date(now).toISOString().slice(0, 10)
+    ? `${iso.slice(11, 16)} UTC` : `${iso.slice(0, 16).replace("T", " ")} UTC`;
+}
+
+/** When a symbol was queued, or null when the answer does not say (older servers) or says a time still to come. */
+function queuedTime(queuedAt: string | null | undefined, now: number): number | null {
+  const time = queuedAt ? Date.parse(queuedAt) : Number.NaN;
+  return Number.isFinite(time) && time <= now ? time : null;
+}
+
+/**
+ * When to look again for history queued at `from`: "a first backfill usually
+ * takes under 10 minutes, try again after 06:41 UTC". One queued for longer
+ * than that is running late, and says so rather than give a time it cannot
+ * know. A view that checks again by itself (`retry: false`) needs no time to
+ * come back at.
+ */
+function firstBackfillText(from: number, now: number, retry: boolean): string {
+  const retryAt = from + FIRST_BACKFILL_MINUTES * 60_000;
+  if (retryAt <= now) return `longer than the usual ${FIRST_BACKFILL_MINUTES} minutes${retry ? ", try again shortly" : ""}`;
+  return retry ? `${FIRST_BACKFILL_TEXT}, try again after ${utcClock(retryAt, now)}` : FIRST_BACKFILL_TEXT;
+}
+
+/** "queued for backfill since 06:31 UTC; a first backfill usually takes under 10 minutes, try again after 06:41 UTC" */
+function queuedText(queuedAt: string | null | undefined, now: number): string {
+  const queued = queuedTime(queuedAt, now);
+  return `queued for backfill${queued == null ? "" : ` since ${utcClock(queued, now)}`}; ${firstBackfillText(queued ?? now, now, true)}`;
+}
 export interface IvHistoryModel {
   symbol: string;
   status: IvHistoryPayload["status"];
@@ -93,7 +131,7 @@ function byMethod(series: readonly IvPoint[], method: IvMethod, field: "iv30" |
  */
 export function projectIvHistory(
   payload: IvHistoryPayload, prices: readonly PricePoint[],
-  options: { lookback?: IvLookback; hvWindow?: HvWindow } = {},
+  options: { lookback?: IvLookback; hvWindow?: HvWindow; now?: number } = {},
 ): IvHistoryModel {
   const lookback = options.lookback ?? "1Y";
   const window = options.hvWindow ?? 20;
@@ -139,9 +177,12 @@ export function projectIvHistory(
     seriesStat("spread", `IV 30d - HV ${window}`, "points", spreadAll, "trade-close"),
     seriesStat("term", "IV 30d / 90d", "ratio", termAll, "trade-close"));
 
-  if (payload.status === "queued") warnings.push(`${payload.symbol} implied volatility history is queued; the first backfill takes a few minutes.`);
-  else if (payload.status === "backfilling") warnings.push(`${payload.symbol} history is still backfilling (through ${payload.coverage?.backfilledThrough ?? "--"}).`);
-  else if (payload.status === "unavailable" && !payload.warnings.length) warnings.push(`No listed options history found for ${payload.symbol}.`);
+  // Worded as VCA words each symbol (screenCoverage).
+  if (payload.status === "queued") warnings.push(`${payload.symbol} ${queuedText(payload.coverage?.addedAt, options.now ?? Date.now())}.`);
+  else if (payload.status === "backfilling") {
+    const through = payload.coverage?.backfilledThrough;
+    warnings.push(`${payload.symbol} backfilling${through ? ` through ${through}` : ""}.`);
+  } else if (payload.status === "unavailable" && !payload.warnings.length) warnings.push(`No options history for ${payload.symbol}.`);
   if (!prices.length) warnings.push("Realized volatility unavailable: daily price history is missing.");
 
   const tradeIv365 = byMethod(payload.series, "trade-close", "iv365");
@@ -163,7 +204,14 @@ export function projectIvHistory(
 export type RichCheap = "rich" | "cheap" | "fair" | null;
 export interface RichCheapRow {
   symbol: string;
-  status: IvScreenRow["status"];
+  /** Where the symbol's history stands, as HIVG reads it; an older server says only ready or queued. */
+  status: IvCoverageStatus;
+  /** When the symbol was queued for backfill, when the server says. */
+  queuedAt: string | null;
+  /** The last session its backfill has reached. */
+  backfilledThrough: string | null;
+  /** Why an unavailable symbol is not covered yet (demand coverage is full): not final, unlike one with no options history. */
+  warning: string | null;
   iv30: number | null;
   date: string | null;
   method: IvMethod | null;
@@ -228,7 +276,9 @@ export function projectRichCheap(rows: readonly IvScreenRow[], hv: ReadonlyMap<s
     const realized = hv.get(row.symbol) ?? null;
     const percentile = row.iv30?.percentile ?? null;
     return {
-      symbol: row.symbol, status: row.status, iv30, date: latest?.date ?? null, method: latest?.method ?? null,
+      symbol: row.symbol, status: row.coverageStatus ?? row.status, queuedAt: row.coverage?.addedAt ?? null,
+      backfilledThrough: row.coverage?.backfilledThrough ?? null, warning: row.warnings?.[0] ?? null,
+      iv30, date: latest?.date ?? null, method: latest?.method ?? null,
       rank: row.iv30?.rank ?? null, percentile, rankDate: row.iv30?.date ?? null,
       termSlope: iv30 != null && latest?.iv90 != null ? iv30 - latest.iv90 : null,
       iv1y: latest?.iv365 ?? null,
@@ -240,6 +290,60 @@ export function projectRichCheap(rows: readonly IvScreenRow[], hv: ReadonlyMap<s
   });
 }
 
+interface ScreenCoverage {
+  /** One line per state, each symbol dated: queued since when, backfilled through which session. */
+  notes: string[];
+  /** Symbols whose history is still to come or not covered yet: the screen is incomplete while there are any. */
+  pending: string[];
+  /** Those of them with no reading to show yet. */
+  missing: string[];
+}
+
+/**
+ * What VCA says about symbols without a full history, in the report's notes
+ * and the pane's notices. A queued symbol says since when and, with `retry`,
+ * when to look again: ten minutes after the newest of them was queued. One
+ * backfilling says how far it has got. One that finished with no options
+ * history is final and leaves the screen complete; one demand coverage could
+ * not take is not final. An older server says only ready or queued, without
+ * dates, so its queued symbols are counted from now as before.
+ */
+export function screenCoverage(rows: readonly RichCheapRow[], options: { now?: number; retry?: boolean } = {}): ScreenCoverage {
+  const now = options.now ?? Date.now();
+  const queued = rows.filter((row) => row.status === "queued");
+  const backfilling = rows.filter((row) => row.status === "backfilling");
+  const final = rows.filter((row) => row.status === "unavailable" && !row.warning);
+  const uncovered = rows.filter((row) => row.status === "unavailable" && row.warning);
+  const notes: string[] = [];
+  if (queued.length) {
+    const times = queued.map((row) => queuedTime(row.queuedAt, now));
+    const listed = queued.map((row, index) => times[index] == null ? row.symbol : `${row.symbol} since ${utcClock(times[index]!, now)}`);
+    const newest = Math.max(...times.map((time) => time ?? now));
+    notes.push(`Queued for backfill: ${listed.join(", ")}; ${firstBackfillText(newest, now, options.retry ?? true)}.`);
+  }
+  if (backfilling.length) {
+    notes.push(`Backfilling: ${backfilling.map((row) => row.backfilledThrough ? `${row.symbol} through ${row.backfilledThrough}` : row.symbol).join(", ")}.`);
+  }
+  if (final.length) notes.push(`No options history: ${final.map((row) => row.symbol).join(", ")}.`);
+  const reasons = new Map<string, string[]>();
+  for (const row of uncovered) reasons.set(row.warning!, [...(reasons.get(row.warning!) ?? []), row.symbol]);
+  for (const [reason, symbols] of reasons) notes.push(`Not queued: ${symbols.join(", ")}. ${reason}`);
+  const pending = [...queued, ...backfilling, ...uncovered];
+  return { notes, pending: pending.map((row) => row.symbol),
+    missing: pending.filter((row) => row.iv30 == null && row.date == null).map((row) => row.symbol) };
+}
+
+/**
+ * The VCA pane's notices: the report's wording without a time to come back
+ * at, since the pane checks again by itself, and a count of ready symbols with
+ * no IV30, which is how an older server reports one that found no options.
+ */
+export function screenPaneNotices(rows: readonly RichCheapRow[], now = Date.now()): string[] {
+  const empty = rows.filter((row) => row.status === "ready" && row.iv30 == null).length;
+  return [...screenCoverage(rows, { now, retry: false }).notes,
+    ...(empty ? [`${empty} symbol${empty === 1 ? " has" : "s have"} no stored implied volatility yet.`] : [])];
+}
+
 export const VCA_PRESETS = {
   etfs: ["SPY", "QQQ", "IWM", "DIA", "EEM", "EFA", "FXI", "EWZ", "GLD", "SLV", "GDX", "USO", "TLT", "HYG",
     "XLE", "XLF", "XLK", "XLV", "XLY", "XLP", "XLI", "XLU", "SMH", "XBI", "KRE"],

package/src/plugins/builtin/iv-history/screen-pane.tsx

@@ -10,7 +10,7 @@ import { useAutoRefresh } from "../../../react/auto-refresh";
 import { compareSortValues, nextHeaderSort, type SortDirection } from "../../../utils/sort-values";
 import { loadIvScreen, loadRealizedVolatilities } from "./client";
 import { formatPoints, formatRank, formatVol, readingLabel, sharedDates, shortDate, VCA_DEFINITIONS, verdictLabel } from "./format";
-import { projectRichCheap, type RichCheapRow, richCheapDates, type VcaPreset } from "./model";
+import { projectRichCheap, type RichCheapRow, richCheapDates, screenPaneNotices, type VcaPreset } from "./model";
 import { vcaUniverse } from "./universe";
 
 type SortId = keyof RichCheapRow;
@@ -78,12 +78,8 @@ export function IvScreenPane({ width, height, focused }: PaneProps) {
     }
   }), [rows, dates]);
   const [selected, setSelected] = useState<string | null>(null);
-  const queued = rows.filter((row) => row.status === "queued").length;
-  const uncovered = rows.filter((row) => row.status !== "queued" && row.iv30 == null).length;
-  const notices = [universe.error, resource.error,
-    ...(queued ? [`${queued} symbol${queued === 1 ? "" : "s"} queued for implied volatility history; they fill in after backfill.`] : []),
-    ...(uncovered ? [`${uncovered} symbol${uncovered === 1 ? " has" : "s have"} no stored implied volatility yet.`] : [])]
-    .filter((value): value is string => !!value);
+  const coverageNotices = useMemo(() => screenPaneNotices(rows), [rows]);
+  const notices = [universe.error, resource.error, ...coverageNotices].filter((value): value is string => !!value);
   usePaneNoticeFooter({ registrationId: "iv-screen-notices", notices, focused });
   const openHistory = (row: RichCheapRow) => createPaneFromTemplate("iv-history-pane", { symbol: row.symbol });
   // The full wording gives way to the short form in a pane too narrow to show the rank date.
@@ -102,8 +98,8 @@ export function IvScreenPane({ width, height, focused }: PaneProps) {
     switch (id) {
       case "symbol": return { text: row.symbol, color: colors.textBright };
       case "iv30": return { text: formatVol(row.iv30), color: colors.warning };
-      case "date": return { text: row.date ? readingLabel(row.date, row.method, true) : row.status === "queued" ? "queued" : "--",
-        color: colors.textDim };
+      case "date": return { text: row.date ? readingLabel(row.date, row.method, true)
+        : row.status === "queued" || row.status === "backfilling" ? row.status : "--", color: colors.textDim };
       case "rankDate": return { text: row.rankDate ? `${shortDate(row.rankDate)} close` : "--", color: colors.textDim };
       case "rank": return { text: formatRank(row.rank) };
       case "percentile": return { text: formatRank(row.percentile) };

package/src/plugins/builtin/iv-history/series.ts

@@ -0,0 +1,29 @@
+import type { SeriesDefinition } from "../../../series/types";
+import { loadIvHistory, type IvPoint } from "./client";
+
+const TENORS: ReadonlyArray<readonly [key: "iv30" | "iv90" | "iv365", label: string]> = [
+  ["iv30", "30-day"],
+  ["iv90", "90-day"],
+  ["iv365", "1-year"],
+];
+
+/** A ticker's at-the-money implied volatility by tenor, one close per session. */
+export const IV_SERIES: readonly SeriesDefinition[] = TENORS.map(([key, label]): SeriesDefinition => ({
+  id: `implied-vol:${key}`,
+  name: `${label} implied volatility`,
+  unit: "%",
+  frequency: "daily",
+  group: "Volatility",
+  tags: ["IV", "implied volatility", "options", key],
+  input: "ticker",
+  load: async ({ ticker, signal }) => {
+    const payload = await loadIvHistory(ticker!, { ...(signal ? { signal } : {}) });
+    return {
+      points: payload.series.map((point: IvPoint) => ({
+        date: point.sessionDate,
+        value: point[key] == null ? null : point[key]! * 100,
+      })),
+      ...(payload.warnings.length ? { warning: payload.warnings.join("; ") } : {}),
+    };
+  },
+}));

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

@@ -1,7 +1,9 @@
 import type {
   HeadlessBundleResult,
+  HeadlessPaneContext,
   HeadlessPaneDefinition,
 } from "../../../types/plugin";
+import { ApiRequestError } from "../../../api-client/errors";
 import { formatCompact, formatNumber } from "../../../utils/format";
 import { fetchJobs, fetchJobsMovers, type JobsCloudClient, type JobsCompanyState } from "./client";
 import {
@@ -13,8 +15,21 @@ import {
   functionLabel,
 } from "./model";
 
-function companyBundle(symbol: string, state: JobsCompanyState, roleLimit: number): HeadlessBundleResult {
-  if (state.kind === "denied") throw new Error(state.message);
+/**
+ * What a refused account needs, and the free preview to try instead: HIRE
+ * reads the same careers systems, and is named only when it answers for this
+ * company.
+ */
+async function jobsDeniedMessage(symbol: string | undefined, status: 401 | 402 | 403, client: Pick<HeadlessPaneContext["apiClient"], "getCloudHiring">): Promise<string> {
+  const need = status === 401 ? "sign-in" : status === 403 ? "a verified email" : "Gloom Pro";
+  const preview = await client.getCloudHiring(symbol, { limit: 1 })
+    .then((payload) => !!payload && (symbol ? "symbol" in payload : "companies" in payload), () => false);
+  return `JOBS needs ${need}${preview ? `; HIRE${symbol ? ` ${symbol}` : ""} is free to preview` : ""}.`;
+}
+
+const DENIED = new Set([401, 402, 403]);
+
+function companyBundle(symbol: string, state: Exclude<JobsCompanyState, { kind: "denied" }>, roleLimit: number): HeadlessBundleResult {
   if (state.kind === "pending") {
     return {
       sections: [{ title: "Hiring", entries: [{ label: "Status", value: "pending", formatted: state.message }] }],
@@ -169,15 +184,25 @@ export const jobsHeadless: HeadlessPaneDefinition<"bundle"> = {
       maximum: 200,
     },
   ],
+  // No aliases: the template's keywords stay the catalog's search terms.
+  discovery: {
+    dataRequirements: ["Gloom Cloud Pro account"],
+    limitations: ["Pro only; HIRE <ticker> previews a company's hiring for free"],
+  },
   describe: (args) => (args.symbols[0] ? `Hiring | ${args.symbols[0]}` : "Hiring | coverage"),
   async load(args, ctx): Promise<HeadlessBundleResult> {
     const limit = Number(args.options.roles);
     const symbol = args.symbols[0];
     if (symbol) {
       const state = await fetchJobs(symbol, { force: true, client: ctx.apiClient as JobsCloudClient });
+      if (state.kind === "denied") throw new Error(await jobsDeniedMessage(symbol, state.status, ctx.apiClient));
       return companyBundle(symbol, state, limit);
     }
-    const payload = await fetchJobsMovers(ctx.apiClient as JobsCloudClient);
+    const payload = await fetchJobsMovers(ctx.apiClient as JobsCloudClient).catch(async (error: unknown) => {
+      const status = error instanceof ApiRequestError ? error.status ?? 0 : 0;
+      if (DENIED.has(status)) throw new Error(await jobsDeniedMessage(undefined, status as 401 | 402 | 403, ctx.apiClient));
+      throw error;
+    });
     const rows = buildMoverRows(payload.movers).slice(0, Math.max(limit, 15)).map((row) => ({
       ticker: row.ticker,
       company: row.company,

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

@@ -1,12 +1,13 @@
 import { publicTickerBindingSymbol } from "../../../tickers/selection";
 import type { PluginModule } from "../plugin-module";
+import { JOBS_SERIES } from "./series";
 import { resetJobsCache } from "./client";
 import { jobsHeadless } from "./headless";
 import { JOBS_PANE_ID, JobsPane, JobsResearchTab } from "./pane";
 
 
 const description =
-  "Hiring read from the company's own careers system: open roles over time, by function and location, new roles, pay ranges. Alone, every covered company ranked.";
+  "Pro hiring read from the company's own careers system: open roles over time, by function and location, new roles, pay ranges. Alone, every covered company ranked.";
 
 function explicitSymbol(options?: { arg?: string; symbol?: string | null }): string | null {
   const symbol = (options?.symbol ?? options?.arg ?? "").trim().toUpperCase();
@@ -14,6 +15,7 @@ function explicitSymbol(options?: { arg?: string; symbol?: string | null }): str
 }
 
 export const jobsModule: PluginModule = {
+  series: JOBS_SERIES,
   setup(ctx) {
     ctx.registerTickerResearchTab({
       id: "jobs",

package/src/plugins/builtin/jobs/series.ts

@@ -0,0 +1,19 @@
+import type { SeriesDefinition } from "../../../series/types";
+import { fetchJobs } from "./client";
+
+/** A company's open job postings each day, as the jobs pane charts them. */
+export const JOBS_SERIES: readonly SeriesDefinition[] = [{
+  id: "jobs:open-roles",
+  name: "Open job postings",
+  unit: "jobs",
+  frequency: "daily",
+  group: "Alternative data",
+  tags: ["hiring", "jobs", "postings", "headcount"],
+  input: "ticker",
+  load: async ({ ticker }) => {
+    const state = await fetchJobs(ticker!);
+    if (state.kind === "pending") throw new Error(state.message || `Postings for ${ticker} are still being collected.`);
+    if (state.kind !== "ready") throw new Error(state.message || `No postings for ${ticker}.`);
+    return state.summary.series.map((point) => ({ date: point.day, value: point.open }));
+  },
+}];

package/src/plugins/builtin/kelly-sizer/pane.tsx

@@ -85,7 +85,8 @@ import {
   buildKellyHistoryItems,
   buildKellyResultItems,
 } from "./sections";
-import { getPortfolioPositionValue, resolveActivePortfolioId, resolveKellyBankroll } from "./portfolio";
+import { resolveActivePortfolioId, resolveKellyBankroll } from "./portfolio";
+import { getPortfolioPositionValue } from "../../../portfolio/position-value";
 import { useKellyCommonAssumptions } from "./state";
 
 export function KellySizerPane({ focused, width, height }: PaneProps) {

package/src/plugins/builtin/kelly-sizer/portfolio.ts

@@ -1,46 +1,7 @@
 import type { AppConfig } from "../../../types/config";
-import type { TickerFinancials } from "../../../types/financials";
 import type { TickerRecord } from "../../../types/ticker";
-import { convertCurrency } from "../../../utils/format";
 import { allocationTotal, type AllocationHolding } from "../portfolio-list/allocation";
 import { getCollectionTypeFromConfig } from "../portfolio-list/pane/data";
-import { getPortfolioPositionMetrics, getPortfolioQuoteDisplay, resolvePortfolioMarketValue } from "../portfolio-list/position-metrics";
-
-export function getPortfolioPositionValue({
-  ticker,
-  financials,
-  portfolioId,
-  baseCurrency,
-  exchangeRates,
-}: {
-  ticker: TickerRecord | null;
-  financials: TickerFinancials | null;
-  portfolioId: string | null;
-  baseCurrency: string;
-  exchangeRates: Map<string, number>;
-}): number {
-  if (!ticker) return 0;
-  const scopedTicker: TickerRecord = portfolioId
-    ? {
-        ...ticker,
-        metadata: {
-          ...ticker.metadata,
-          positions: ticker.metadata.positions.filter((position) => position.portfolio === portfolioId),
-        },
-      }
-    : ticker;
-  const quote = financials?.quote;
-
-  const quoteCurrency = quote?.currency || ticker.metadata.currency || baseCurrency;
-  const metrics = getPortfolioPositionMetrics(scopedTicker, undefined, quoteCurrency, {
-    currency: baseCurrency, convert: (value, currency) => convertCurrency(value, currency, baseCurrency, exchangeRates),
-  }, quote);
-  const activeQuote = getPortfolioQuoteDisplay(metrics, quote);
-
-  return resolvePortfolioMarketValue(metrics, activeQuote
-    ? convertCurrency(activeQuote.price, quoteCurrency, baseCurrency, exchangeRates) : null)?.gross
-    ?? (metrics.positionCount > 0 ? Number.NaN : 0);
-}
 
 /**
  * What the portfolio is worth to bet with: its equity. A broker account's is

package/src/plugins/builtin/macro-day/client.ts

@@ -7,7 +7,9 @@ import type { DataProvider } from "../../../types/data-provider";
 import type { PricePoint } from "../../../types/financials";
 import { abortable, abortError } from "../../../utils/async-deadline";
 import { errorMessage } from "../../../utils/errors";
-import { resolveExchangeTimeZone } from "../../../utils/exchanges";
+import { parsePublicTickerKey, resolveExchangeTimeZone } from "../../../utils/exchanges";
+import { loadEarningsHistory } from "../earnings/client";
+import type { MacroDayEarningsReport } from "./model";
 import { bundledMacroReleases, mergeMacroReleases, type MacroReleaseList } from "./releases";
 
 export const macroReleaseCache = createPluginCache<CloudMacroReleaseDaysPayload>({
@@ -43,11 +45,12 @@ const US_LISTINGS_ONLY = "Macro-day moves are for US listings.";
 
 /**
  * A listing whose venue sits outside New York trades US releases on a different clock.
- * A bare symbol such as 7203.T carries no exchange, so its venue suffix names it.
+ * A bare symbol such as 7203.T carries no exchange, so its venue suffix names it,
+ * and a listing key such as SAP:XETR names it before the ticker record has loaded.
  */
 function isNonUsVenue(instrument: InstrumentRef): boolean {
   if (tickerHasListingSuffix(instrument.symbol)) return true;
-  const zone = resolveExchangeTimeZone(instrument.exchange);
+  const zone = resolveExchangeTimeZone(instrument.exchange || parsePublicTickerKey(instrument.symbol).exchange);
   return !!zone && zone !== "America/New_York";
 }
 
@@ -72,3 +75,41 @@ export async function loadMacroDayHistory(
     return { history: [], stale: false, error: errorMessage(error), fetchedAt: now };
   }
 }
+
+export interface MacroDayEarnings {
+  reports: MacroDayEarningsReport[];
+  stale: boolean;
+  /** Why the reports are missing; the study then runs without the earnings marker. */
+  error: string | null;
+}
+
+/** The earnings history's own depth: the oldest report that can matter is five years back, about twenty quarters. */
+const EARNINGS_REPORT_LIMIT = 24;
+
+/**
+ * The ticker's own earnings reports, from the history `ERN` shows. Never
+ * rejects but on cancel: a listing outside the US or without reports has none,
+ * and a failed read leaves the study as it was, with the reason in `error`.
+ */
+export async function loadMacroDayEarnings(
+  request: { instrument: InstrumentRef; signal?: AbortSignal; forceRefresh?: boolean },
+  load: typeof loadEarningsHistory = loadEarningsHistory,
+): Promise<MacroDayEarnings> {
+  if (request.signal?.aborted) throw abortError(CANCELLED);
+  if (isNonUsVenue(request.instrument)) return { reports: [], stale: false, error: null };
+  try {
+    // Earnings are keyed by the bare US symbol; a listing key ("CRWV:XNAS") drops its exchange.
+    const symbol = parsePublicTickerKey(request.instrument.symbol.trim()).symbol.toUpperCase();
+    const resource = await abortable(load(symbol, request.forceRefresh, EARNINGS_REPORT_LIMIT), request.signal, CANCELLED);
+    return { reports: resource.payload.reports.map((report) => ({ date: report.date, timing: report.timing, reactionSession: report.realized?.afterSession ?? null })),
+      stale: resource.stale, error: null };
+  } catch (error) {
+    if (request.signal?.aborted || (error instanceof Error && error.name === "AbortError")) throw abortError(CANCELLED);
+    return { reports: [], stale: false, error: errorMessage(error) };
+  }
+}
+
+/** What the pane footer and the report notes say when the earnings marker could not be applied. */
+export function macroDayEarningsNotice(earnings: MacroDayEarnings): string | null {
+  return earnings.error ? `Earnings dates unavailable (${earnings.error}); release days on the company's own report are not marked.` : null;
+}

package/src/plugins/builtin/macro-day/headless.ts

@@ -1,7 +1,7 @@
 import type { HeadlessPaneDefinition } from "../../../types/plugin";
 import { resolveHeadlessInstrument } from "../shared/headless-market-data";
-import { loadMacroDayHistory, loadMacroReleases } from "./client";
-import { projectMacroDays, type MacroDayStats } from "./model";
+import { loadMacroDayEarnings, loadMacroDayHistory, loadMacroReleases, macroDayEarningsNotice } from "./client";
+import { macroDayEventLabel, projectMacroDays, type MacroDayStats } from "./model";
 import { MACRO_EVENT_KINDS, MACRO_EVENT_LABELS, MACRO_RELEASE_SOURCES, staleMacroReleasesNotice } from "./releases";
 
 // A mean that rounds to zero reads 0.00%, never -0.00%.
@@ -11,12 +11,14 @@ const share = (value: unknown) => typeof value === "number" ? `${Math.round(valu
 
 export const macroDayHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle", argument: { kind: "ticker", description: "Ticker" },
+  usListingsOnly: "Macro release day data",
   // Dated by the release list (releasesThrough) as much as by the closes, so no session schedule applies.
   freshness: { status: "not-a-feed", basis: "release-day study on daily closes" },
   describe: (args) => `MDAY ${args.symbols[0] ?? ""}`,
   discovery: { screenshotReadiness: "live-dom", limitations: [
     "US listings; close-to-close on the release day.",
     "Published CPI, jobs and FOMC days; sessions after the list's last covered day (releasesThrough) are left out.",
+    "A release day that is also the reaction session of the company's own earnings report is marked earnings and left out of the release averages and the normal day.",
   ] },
   options: [
     { key: "release", type: "enum", values: [{ value: "all" }, ...MACRO_EVENT_KINDS.map((value) => ({ value }))], defaultValue: "all",
@@ -25,11 +27,12 @@ export const macroDayHeadless: HeadlessPaneDefinition<"bundle"> = {
   ],
   async load(args, ctx) {
     const instrument = await resolveHeadlessInstrument(ctx, args.symbols[0]!);
-    const [history, releases] = await Promise.all([loadMacroDayHistory({ instrument, signal: ctx.signal }, ctx.marketData), loadMacroReleases()]);
+    const [history, releases, earnings] = await Promise.all([loadMacroDayHistory({ instrument, signal: ctx.signal }, ctx.marketData), loadMacroReleases(),
+      loadMacroDayEarnings({ instrument, signal: ctx.signal })]);
     ctx.signal.throwIfAborted();
     const model = projectMacroDays(history.history, { symbol: instrument.symbol, lookbackYears: Number(args.options.lookbackYears) || 5,
-      releases: releases.releases, coveredThrough: releases.coveredThrough });
-    const releasesNotice = staleMacroReleasesNotice(releases);
+      releases: releases.releases, coveredThrough: releases.coveredThrough, earnings: earnings.reports });
+    const notes = [staleMacroReleasesNotice(releases), macroDayEarningsNotice(earnings)].filter((note): note is string => !!note);
     const row = (label: string, stats: MacroDayStats) => ({ label, ...stats });
     const release = String(args.options.release ?? "all");
     const events = release === "all" ? model.events : model.events.filter((event) => event.kind === release);
@@ -39,18 +42,18 @@ export const macroDayHeadless: HeadlessPaneDefinition<"bundle"> = {
           { key: "meanAbs", header: "Avg |move|", format: percent }, { key: "multiple", header: "vs normal", format: multiple },
           { key: "mean", header: "Avg move", format: percent }, { key: "hitRate", header: "Up", format: share }],
         rows: [...MACRO_EVENT_KINDS.map((kind) => row(MACRO_EVENT_LABELS[kind], model.byKind[kind])),
-          row("Any release", model.allEvents), row("Normal day", model.normal)] },
+          row("Any release", model.allEvents), ...(model.earnings.count ? [row("Earnings", model.earnings)] : []), row("Normal day", model.normal)] },
         { title: "Release days", columns: [{ key: "date", header: "Date" }, { key: "event", header: "Release" },
           { key: "session", header: "Session" }, { key: "move", header: "Move", format: percent }, { key: "multiple", header: "vs normal", format: multiple }],
-        rows: events.map((event) => ({ ...event, event: MACRO_EVENT_LABELS[event.kind] })) },
+        rows: events.map((event) => ({ ...event, event: macroDayEventLabel(event) })) },
       ],
-      complete: !history.stale && !history.error && !releasesNotice && model.events.length > 0,
+      complete: !history.stale && !earnings.stale && !history.error && !notes.length && model.events.length > 0,
       unavailableSymbols: model.events.length ? [] : [instrument.symbol],
       errors: history.error ? [history.error] : [],
-      ...(releasesNotice ? { notes: [releasesNotice] } : {}),
+      ...(notes.length ? { notes } : {}),
       metadata: { unit: "decimal return, close to close on the release day", start: model.start, asOf: model.asOf,
         releasesThrough: releases.coveredThrough, releaseSources: Object.values(MACRO_RELEASE_SOURCES),
-        stale: history.stale, fetchedAt: history.fetchedAt, methodology: "docs/research-data.md#macro-day-reaction" },
+        stale: history.stale || earnings.stale, fetchedAt: history.fetchedAt, methodology: "docs/research-data.md#macro-day-reaction" },
     };
   },
 };